/**
 * Copyright (c) 2026, Salesforce, Inc.,
 * All rights reserved.
 * For full license text, see the LICENSE.txt file
 */
import { type PrimeDeps } from "./prime-schema.js";
export interface DownloadSchemaSdlOptions {
    /** Org alias or username (the value normally passed to `--target-org`). */
    org: string;
    /**
     * Where to write the canonical GraphQL SDL (e.g. `schema.graphql` for a
     * codegen pipeline). Written atomically; parent directories are created as
     * needed. Omit to skip the write and only receive the SDL in the result.
     */
    outPath?: string;
    /**
     * Re-download even if the org's schema is already cached. Routes through the
     * shared refresh path so all of graphiti's caches (introspection JSON,
     * in-memory parsed schema, ObjectInfo) are cleared coherently.
     */
    forceRefresh?: boolean;
    /**
     * Age gate. When the shared cache's schema is older than this many
     * milliseconds, this call forces a refresh (equivalent to `forceRefresh`).
     * A cache younger than the threshold — or a not-yet-primed org — is left to
     * the normal lazy-prime path, so a fresh cache is still served without a
     * second download ("wait once"). Undefined or `<= 0` disables the gate.
     *
     * graphiti's cache has no TTL of its own — a plain `connect` serves any
     * existing schema indefinitely — so callers that must not run against stale
     * metadata (codegen, IDE tooling) should pass a small `maxAgeMs`.
     */
    maxAgeMs?: number;
    /**
     * Injectable priming dependencies (auth + introspection download). Defaults
     * to the real graphiti implementations; tests pass stubs.
     */
    deps?: PrimeDeps;
}
export interface DownloadSchemaSdlResult {
    /** The org's canonical GraphQL SDL (`printSchema` of the primed schema). */
    sdl: string;
    /** Resolved Salesforce instance URL — the key the shared cache is stored under. */
    instanceUrl: string;
    /** Absolute path of the shared introspection JSON cache. */
    cacheFilePath: string;
    /** Absolute path the SDL was written to, or `undefined` when `outPath` was omitted. */
    outPath?: string;
    /**
     * True when this call performed a network introspection (a fresh prime or a
     * refresh that this process ran). A cache hit — including a refresh that
     * coalesced onto a concurrent peer's download — is `false`.
     */
    downloaded: boolean;
    /** True when a refresh was requested, whether explicitly or by the age gate. */
    refreshed: boolean;
    /** True when the age gate (`maxAgeMs`) is what triggered the refresh. */
    refreshedDueToAge: boolean;
}
/**
 * Prime the org's schema through graphiti's shared, lock-coalesced cache and
 * serialize it to canonical SDL — the programmatic equivalent of
 * `graphiti connect <org>` plus an SDL export.
 *
 * This is the sanctioned way for other tools (codegen, IDE integrations) to
 * obtain an org's schema: it shares graphiti's single instance-URL-keyed cache
 * (`~/.graphiti/schemas/`), so whoever asks first — the CLI, the MCP server, or
 * this function — pays the one-time introspection cost, and everyone else reads
 * the same cache.
 *
 * Priming semantics are inherited from {@link primeSchemaWithLock}: a lazy prime
 * on an uncached org, a no-op on a cached one, and a coherent cache-clearing
 * re-download on `forceRefresh`. The SDL is read back via {@link getSchema},
 * which after a refresh rebuilds from the freshly-downloaded introspection JSON,
 * so the returned SDL always matches what is on disk.
 *
 * @throws the underlying auth/schema error verbatim on a lazy-prime failure, or
 * `SchemaRefreshError` when a forced refresh fails but a usable cache survives
 * (see {@link primeSchemaWithLock}).
 */
export declare function downloadSchemaSdl(opts: DownloadSchemaSdlOptions): Promise<DownloadSchemaSdlResult>;