@salesforce/graphiti 11.57.3 → 11.58.0

package/AGENT_GUIDE.md

@@ -40,6 +40,18 @@ Notes:
 - Exception: a **401/403 auth failure** during introspection (expired/unauthorized session) errors with an `Auth:` prefix instead of the soft staleness warning — a dead session makes even the cached schema unusable, so re-authenticate (`sf org login web --alias <org>`) rather than retrying.
 - ObjectInfo is keyed by org alias: refreshing alias `A` does not invalidate ObjectInfo cached under a different alias `B` for the same org (its 1-hour TTL heals it).
 
+## Sharing the schema cache from code
+
+Build tooling (codegen, IDE integrations) should not run its own introspection — import graphiti and reuse the shared cache:
+
+```ts
+import { downloadSchemaSdl } from "@salesforce/graphiti";
+
+await downloadSchemaSdl({ org: "<org>", outPath: "schema.graphql", maxAgeMs: 10 * 60_000 });
+```
+
+This primes the same instance-URL-keyed cache `connect` uses, writes canonical SDL to `outPath`, and (via `maxAgeMs`) re-introspects only when the cached schema is older than the gate — otherwise it serves the existing cache ("wait once"). See the README's "Programmatic API" section for the full option/result reference.
+
 ## Session Resolution
 
 All session commands target the **active session** implicitly. Resolution order:

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [11.58.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v11.57.4...v11.58.0) (2026-08-14)
+
+### Features
+
+- **graphiti:** expose downloadSchemaSdl library API for shared schema cache @W-23545346@ ([#856](https://github.com/salesforce-experience-platform-emu/webapps/issues/856)) ([8a29abe](https://github.com/salesforce-experience-platform-emu/webapps/commit/8a29abe0e3925020b816a6bcd2352d5b3d7236d9))
+
+## [11.57.4](https://github.com/salesforce-experience-platform-emu/webapps/compare/v11.57.3...v11.57.4) (2026-08-14)
+
+**Note:** Version bump only for package @salesforce/graphiti
+
 ## [11.57.3](https://github.com/salesforce-experience-platform-emu/webapps/compare/v11.57.2...v11.57.3) (2026-08-14)
 
 **Note:** Version bump only for package @salesforce/graphiti

package/README.md

@@ -207,6 +207,34 @@ graphiti caches three things per org: the on-disk introspection JSON, the in-mem
 
 > **ObjectInfo is keyed by org alias, not instance URL.** Refreshing alias `A` does not invalidate ObjectInfo cached under a different alias `B` that points at the same org; refresh each alias you actively use, or let ObjectInfo's 1-hour TTL heal it.
 
+## Programmatic API (library)
+
+graphiti is primarily a CLI, but it also exposes a small, stable programmatic surface so other tools can **share the same schema cache** instead of running their own introspection. The canonical use is a codegen or IDE pipeline that needs an org's GraphQL SDL on disk:
+
+```ts
+import { downloadSchemaSdl } from "@salesforce/graphiti";
+
+// Prime the shared cache (if needed) and write canonical SDL for codegen.
+await downloadSchemaSdl({
+  org: process.env.SF_TARGET_ORG, // alias or username
+  outPath: "schema.graphql",
+  maxAgeMs: 10 * 60_000, // re-introspect if the cached schema is older than 10 min
+});
+```
+
+`downloadSchemaSdl(options)` primes the org's schema through the same instance-URL-keyed cache the CLI and MCP server use, then serializes it with `printSchema`:
+
+| Option         | Description                                                                                                                      |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `org`          | Org alias or username (the value you'd pass to `--target-org`).                                                                  |
+| `outPath`      | Where to atomically write the SDL (parent dirs are created). Omit to only receive the SDL in the result.                         |
+| `forceRefresh` | Re-download even if cached, clearing all of graphiti's caches coherently (same as `connect --refresh`).                          |
+| `maxAgeMs`     | Age gate: force a refresh when the cached schema is older than this. A fresh cache — or an uncached org — is left to lazy prime. |
+
+Because the **schema cache has no TTL** — a plain `connect` serves any existing schema indefinitely (only the separate ObjectInfo cache expires, on its own 1-hour TTL) — callers that must not run against stale metadata, such as codegen or IDE tooling, should pass a small `maxAgeMs`. Whoever asks first (CLI, MCP, or this call) pays the one-time introspection; everyone else reads the same cache, so you still "wait once."
+
+The result reports what happened — `sdl`, `instanceUrl`, `cacheFilePath`, `outPath`, `downloaded`, `refreshed`, and `refreshedDueToAge`. `downloadSchemaSdl` is the only supported export today; deep `@salesforce/graphiti/dist/...` imports are internal and may change without a major version bump.
+
 ## Development
 
 ```bash

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Public library entry point for `@salesforce/graphiti`.
+ *
+ * graphiti is primarily a CLI. This module exposes just the one function build
+ * tooling needs — {@link downloadSchemaSdl} — so a codegen/IDE pipeline can
+ * obtain an org's GraphQL SDL from graphiti's single instance-URL-keyed schema
+ * cache (`~/.graphiti/schemas/`) instead of running its own introspection.
+ *
+ * Only the names re-exported here are supported; everything else (reachable via
+ * deep `@salesforce/graphiti/dist/...` paths) is internal and may change without
+ * a major version bump. The surface is kept intentionally small — more will be
+ * exported as concrete consumers need it, not before.
+ */
+export { downloadSchemaSdl, type DownloadSchemaSdlOptions, type DownloadSchemaSdlResult, } from "./lib/download-schema.js";

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Public library entry point for `@salesforce/graphiti`.
+ *
+ * graphiti is primarily a CLI. This module exposes just the one function build
+ * tooling needs — {@link downloadSchemaSdl} — so a codegen/IDE pipeline can
+ * obtain an org's GraphQL SDL from graphiti's single instance-URL-keyed schema
+ * cache (`~/.graphiti/schemas/`) instead of running its own introspection.
+ *
+ * Only the names re-exported here are supported; everything else (reachable via
+ * deep `@salesforce/graphiti/dist/...` paths) is internal and may change without
+ * a major version bump. The surface is kept intentionally small — more will be
+ * exported as concrete consumers need it, not before.
+ */
+export { downloadSchemaSdl, } from "./lib/download-schema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EACN,iBAAiB,GAGjB,MAAM,0BAA0B,CAAC"}

package/dist/lib/download-schema.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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>;

package/dist/lib/download-schema.js

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+import path from "node:path";
+import { printSchema } from "graphql";
+import { getOrgAuth } from "./auth.js";
+import { atomicWriteText } from "./fs-utils.js";
+import { getSchemaMetadata } from "./introspect.js";
+import { primeSchemaWithLock } from "./prime-schema.js";
+import { getSchema } from "./walker.js";
+/**
+ * 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 async function downloadSchemaSdl(opts) {
+    const { org, deps } = opts;
+    const maxAgeMs = opts.maxAgeMs;
+    let forceRefresh = !!opts.forceRefresh;
+    let refreshedDueToAge = false;
+    // Age gate: only when a max age is set and we are not already refreshing.
+    // Resolving auth here is the only way to learn the instance URL the cache is
+    // keyed by; auth is memoized per alias, so the subsequent resolution inside
+    // primeSchemaWithLock is free (and in tests the injected stub is trivial).
+    if (!forceRefresh && maxAgeMs !== undefined && maxAgeMs > 0) {
+        const getAuth = deps?.getOrgAuth ?? getOrgAuth;
+        const auth = await getAuth(org);
+        const meta = getSchemaMetadata(auth.instanceUrl);
+        if (meta) {
+            // A NaN age (unparseable timestamp) compares false — we treat an
+            // unreadable cache as "not stale" and let the cache-hit path serve it;
+            // getSchema self-heals from the JSON if the SDL side-file is bad.
+            const ageMs = Date.now() - new Date(meta.downloadedAt).getTime();
+            if (ageMs > maxAgeMs) {
+                forceRefresh = true;
+                refreshedDueToAge = true;
+            }
+        }
+    }
+    const prime = await primeSchemaWithLock(org, deps, { forceRefresh });
+    const { instanceUrl } = prime;
+    // getSchema rebuilds from the on-disk introspection JSON after a refresh
+    // (the refresh evicted the in-memory + SDL caches), so this is always the
+    // schema that was just primed — never a stale copy.
+    const sdl = printSchema(getSchema(instanceUrl));
+    let resolvedOut;
+    if (opts.outPath) {
+        resolvedOut = path.resolve(opts.outPath);
+        atomicWriteText(resolvedOut, sdl);
+    }
+    return {
+        sdl,
+        instanceUrl,
+        cacheFilePath: prime.filePath,
+        outPath: resolvedOut,
+        downloaded: !prime.cached,
+        refreshed: forceRefresh,
+        refreshedDueToAge,
+    };
+}
+//# sourceMappingURL=download-schema.js.map

package/dist/lib/download-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-schema.js","sourceRoot":"","sources":["../../src/lib/download-schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAkB,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAyDxC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,IAA8B;IAE9B,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAE/B,IAAI,YAAY,GAAG,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;IACvC,IAAI,iBAAiB,GAAG,KAAK,CAAC;IAE9B,0EAA0E;IAC1E,6EAA6E;IAC7E,4EAA4E;IAC5E,2EAA2E;IAC3E,IAAI,CAAC,YAAY,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC7D,MAAM,OAAO,GAAG,IAAI,EAAE,UAAU,IAAI,UAAU,CAAC;QAC/C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACjD,IAAI,IAAI,EAAE,CAAC;YACV,iEAAiE;YACjE,uEAAuE;YACvE,kEAAkE;YAClE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC;YACjE,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;gBACtB,YAAY,GAAG,IAAI,CAAC;gBACpB,iBAAiB,GAAG,IAAI,CAAC;YAC1B,CAAC;QACF,CAAC;IACF,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;IACrE,MAAM,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAE9B,yEAAyE;IACzE,0EAA0E;IAC1E,oDAAoD;IACpD,MAAM,GAAG,GAAG,WAAW,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAEhD,IAAI,WAA+B,CAAC;IACpC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzC,eAAe,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACnC,CAAC;IAED,OAAO;QACN,GAAG;QACH,WAAW;QACX,aAAa,EAAE,KAAK,CAAC,QAAQ;QAC7B,OAAO,EAAE,WAAW;QACpB,UAAU,EAAE,CAAC,KAAK,CAAC,MAAM;QACzB,SAAS,EAAE,YAAY;QACvB,iBAAiB;KACjB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@salesforce/graphiti",
-  "version": "11.57.3",
+  "version": "11.58.0",
   "description": "Progressive GraphQL query builder CLI for Salesforce orgs",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
   "bin": {
     "graphiti": "./dist/cli.js",
     "graphiti-mcp": "./dist/mcp/stdio.js"

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Public library entry point for `@salesforce/graphiti`.
+ *
+ * graphiti is primarily a CLI. This module exposes just the one function build
+ * tooling needs — {@link downloadSchemaSdl} — so a codegen/IDE pipeline can
+ * obtain an org's GraphQL SDL from graphiti's single instance-URL-keyed schema
+ * cache (`~/.graphiti/schemas/`) instead of running its own introspection.
+ *
+ * Only the names re-exported here are supported; everything else (reachable via
+ * deep `@salesforce/graphiti/dist/...` paths) is internal and may change without
+ * a major version bump. The surface is kept intentionally small — more will be
+ * exported as concrete consumers need it, not before.
+ */
+
+export {
+	downloadSchemaSdl,
+	type DownloadSchemaSdlOptions,
+	type DownloadSchemaSdlResult,
+} from "./lib/download-schema.js";

package/src/lib/__tests__/download-schema.spec.ts

@@ -0,0 +1,167 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { buildSchema } from "graphql";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { makeNoopPrimeDeps } from "../../__tests__/helpers/prime-deps.js";
+import { downloadSchemaSdl } from "../download-schema.js";
+import { schemaCacheKeyForInstanceUrl, schemaDir } from "../introspect.js";
+import { type PrimeDeps } from "../prime-schema.js";
+import { clearSchemaCache } from "../walker.js";
+
+const ORG = "download-sdl-org";
+const ORG_URL = "https://download-sdl-org.my.salesforce.com";
+// A schema with a recognizable field so we can assert the emitted SDL is the
+// one we primed, not an empty stub.
+const SCHEMA = buildSchema(`type Query { hello: String }`);
+
+describe("lib/download-schema", () => {
+	let tmpRoot: string;
+
+	beforeEach(() => {
+		tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-download-sdl-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+	});
+
+	afterEach(() => {
+		delete process.env.GRAPHITI_HOME;
+		// getSchema populates a module-level parsed-schema cache keyed by instance
+		// URL; clear it so a shared ORG_URL can't leak a schema between tests.
+		clearSchemaCache();
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	function cacheFile(): string {
+		return path.join(schemaDir(), `${schemaCacheKeyForInstanceUrl(ORG_URL)}.json`);
+	}
+
+	/** Wrap real deps with a download counter, mirroring connect.spec.ts. */
+	function counting(base: PrimeDeps): { deps: PrimeDeps; calls: () => number } {
+		let calls = 0;
+		return {
+			deps: {
+				getOrgAuth: base.getOrgAuth,
+				downloadSchema: async (a) => {
+					calls++;
+					return base.downloadSchema(a);
+				},
+			},
+			calls: () => calls,
+		};
+	}
+
+	it("primes a fresh (uncached) org, writes SDL to outPath, and reports downloaded", async () => {
+		const { deps, calls } = counting(makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA));
+		const outPath = path.join(tmpRoot, "schema.graphql");
+
+		const result = await downloadSchemaSdl({ org: ORG, outPath, deps });
+
+		expect(calls()).toBe(1); // fresh org → one introspection
+		expect(result.downloaded).toBe(true);
+		expect(result.refreshed).toBe(false);
+		expect(result.refreshedDueToAge).toBe(false);
+		expect(result.instanceUrl).toBe(ORG_URL);
+		expect(fs.existsSync(cacheFile())).toBe(true); // shared cache populated
+		expect(result.outPath).toBe(path.resolve(outPath));
+		expect(fs.readFileSync(outPath, "utf-8")).toBe(result.sdl);
+		expect(result.sdl).toMatch(/type Query/);
+		expect(result.sdl).toMatch(/hello: String/);
+	});
+
+	it("second call is a cache hit: no re-download, still returns and writes the SDL (wait once)", async () => {
+		const base = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		await downloadSchemaSdl({ org: ORG, deps: base }); // prime once
+
+		const { deps, calls } = counting(base);
+		const outPath = path.join(tmpRoot, "schema.graphql");
+		const result = await downloadSchemaSdl({ org: ORG, outPath, deps });
+
+		expect(calls()).toBe(0); // cache hit — no second introspection
+		expect(result.downloaded).toBe(false);
+		expect(result.refreshed).toBe(false);
+		expect(fs.readFileSync(outPath, "utf-8")).toBe(result.sdl);
+		expect(result.sdl).toMatch(/type Query/);
+	});
+
+	it("omitting outPath returns the SDL without writing an export file", async () => {
+		const base = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		const exportPath = path.join(tmpRoot, "schema.graphql");
+		const result = await downloadSchemaSdl({ org: ORG, deps: base });
+
+		expect(result.outPath).toBeUndefined();
+		expect(result.sdl).toMatch(/type Query/);
+		// With no outPath, downloadSchemaSdl writes no export. (getSchema still
+		// maintains its own `<cacheKey>.graphql` cache side-file under schemaDir,
+		// but never the caller-named export path.)
+		expect(fs.existsSync(exportPath)).toBe(false);
+	});
+
+	it("maxAgeMs forces a refresh when the cached schema is older than the gate", async () => {
+		const base = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		await downloadSchemaSdl({ org: ORG, deps: base }); // prime once (fresh)
+
+		// Backdate the shared cache so it reads as ~20 min old. getSchemaMetadata
+		// derives `downloadedAt` from the file mtime, so this is what the gate sees.
+		const past = new Date(Date.now() - 20 * 60_000);
+		fs.utimesSync(cacheFile(), past, past);
+
+		const { deps, calls } = counting(base);
+		const outPath = path.join(tmpRoot, "schema.graphql");
+		const result = await downloadSchemaSdl({
+			org: ORG,
+			outPath,
+			maxAgeMs: 10 * 60_000,
+			deps,
+		});
+
+		expect(calls()).toBe(1); // stale → forced re-download
+		expect(result.downloaded).toBe(true);
+		expect(result.refreshed).toBe(true);
+		expect(result.refreshedDueToAge).toBe(true);
+		expect(fs.readFileSync(outPath, "utf-8")).toBe(result.sdl);
+	});
+
+	it("maxAgeMs leaves a fresh cache untouched — wait once is preserved", async () => {
+		const base = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		await downloadSchemaSdl({ org: ORG, deps: base }); // prime once (just now)
+
+		const { deps, calls } = counting(base);
+		const result = await downloadSchemaSdl({ org: ORG, maxAgeMs: 10 * 60_000, deps });
+
+		expect(calls()).toBe(0); // young cache → no refresh
+		expect(result.downloaded).toBe(false);
+		expect(result.refreshed).toBe(false);
+		expect(result.refreshedDueToAge).toBe(false);
+	});
+
+	it("maxAgeMs on an uncached org lazily primes (no false 'stale') ", async () => {
+		const { deps, calls } = counting(makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA));
+		// No prior cache: the gate finds no metadata and must not force a refresh;
+		// the normal lazy prime downloads exactly once.
+		const result = await downloadSchemaSdl({ org: ORG, maxAgeMs: 10 * 60_000, deps });
+
+		expect(calls()).toBe(1);
+		expect(result.downloaded).toBe(true);
+		expect(result.refreshed).toBe(false);
+		expect(result.refreshedDueToAge).toBe(false);
+	});
+
+	it("forceRefresh re-downloads even a fresh cache; refreshedDueToAge stays false", async () => {
+		const base = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+		await downloadSchemaSdl({ org: ORG, deps: base }); // prime once
+
+		const { deps, calls } = counting(base);
+		const result = await downloadSchemaSdl({ org: ORG, forceRefresh: true, deps });
+
+		expect(calls()).toBe(1); // explicit refresh re-introspects
+		expect(result.downloaded).toBe(true);
+		expect(result.refreshed).toBe(true);
+		expect(result.refreshedDueToAge).toBe(false); // it was explicit, not the gate
+	});
+});

package/src/lib/download-schema.ts

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import path from "node:path";
+import { printSchema } from "graphql";
+import { getOrgAuth } from "./auth.js";
+import { atomicWriteText } from "./fs-utils.js";
+import { getSchemaMetadata } from "./introspect.js";
+import { type PrimeDeps, primeSchemaWithLock } from "./prime-schema.js";
+import { getSchema } from "./walker.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 async function downloadSchemaSdl(
+	opts: DownloadSchemaSdlOptions,
+): Promise<DownloadSchemaSdlResult> {
+	const { org, deps } = opts;
+	const maxAgeMs = opts.maxAgeMs;
+
+	let forceRefresh = !!opts.forceRefresh;
+	let refreshedDueToAge = false;
+
+	// Age gate: only when a max age is set and we are not already refreshing.
+	// Resolving auth here is the only way to learn the instance URL the cache is
+	// keyed by; auth is memoized per alias, so the subsequent resolution inside
+	// primeSchemaWithLock is free (and in tests the injected stub is trivial).
+	if (!forceRefresh && maxAgeMs !== undefined && maxAgeMs > 0) {
+		const getAuth = deps?.getOrgAuth ?? getOrgAuth;
+		const auth = await getAuth(org);
+		const meta = getSchemaMetadata(auth.instanceUrl);
+		if (meta) {
+			// A NaN age (unparseable timestamp) compares false — we treat an
+			// unreadable cache as "not stale" and let the cache-hit path serve it;
+			// getSchema self-heals from the JSON if the SDL side-file is bad.
+			const ageMs = Date.now() - new Date(meta.downloadedAt).getTime();
+			if (ageMs > maxAgeMs) {
+				forceRefresh = true;
+				refreshedDueToAge = true;
+			}
+		}
+	}
+
+	const prime = await primeSchemaWithLock(org, deps, { forceRefresh });
+	const { instanceUrl } = prime;
+
+	// getSchema rebuilds from the on-disk introspection JSON after a refresh
+	// (the refresh evicted the in-memory + SDL caches), so this is always the
+	// schema that was just primed — never a stale copy.
+	const sdl = printSchema(getSchema(instanceUrl));
+
+	let resolvedOut: string | undefined;
+	if (opts.outPath) {
+		resolvedOut = path.resolve(opts.outPath);
+		atomicWriteText(resolvedOut, sdl);
+	}
+
+	return {
+		sdl,
+		instanceUrl,
+		cacheFilePath: prime.filePath,
+		outPath: resolvedOut,
+		downloaded: !prime.cached,
+		refreshed: forceRefresh,
+		refreshedDueToAge,
+	};
+}