@foir/sdk 0.10.0 → 0.11.0

package/dist/data.js

@@ -76,19 +76,46 @@ var FoirRequestError = class extends Error {
     return typeof seconds === "number" && seconds > 0 ? seconds * 1e3 : void 0;
   }
 };
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
 function buildFoirHeaders(input) {
   const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": input.apiKey
+    "Content-Type": "application/json"
   };
-  if (input.draftChannel) {
-    headers["X-Foir-Schema-Channel"] = "draft";
-  }
-  if (input.bearerToken) {
-    headers["Authorization"] = `Bearer ${input.bearerToken}`;
-  }
-  if (input.orgId) {
-    headers["X-Org-Id"] = input.orgId;
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    if (input.orgUrl) {
+      headers["X-Org-Url"] = input.orgUrl;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -132,12 +159,15 @@ function refusePrunedDocument(json, options) {
     `[foir] selections stripped from this query: ${selections.map(describe2).join(", ")}`
   );
 }
+function answeredAnything(data) {
+  return typeof data === "object" && data !== null && Object.values(data).some((value) => value !== null && value !== void 0);
+}
 function readFoirEnvelope(json, options) {
   reportAuthDowngrade(json);
   refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data && !options?.strict) {
+    if (answeredAnything(json.data) && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
@@ -199,10 +229,107 @@ async function resolveBearerToken(config) {
   if (typeof source === "function") return await source() ?? void 0;
   return source ?? void 0;
 }
+async function resolveDispatchToken(dispatch) {
+  const token = (await dispatch.token())?.trim();
+  if (!token) {
+    throw new FoirRequestError(
+      "[foir] the dispatch token provider returned no token. A client built from a dispatch calls Foir as that operation and holds no other credential. Build it from the token the endpoint was handed: `(await requireScopedToken(request)).dispatch`."
+    );
+  }
+  return token;
+}
+async function resolveFoirAuth(config) {
+  if (config.dispatch !== void 0) {
+    return {
+      headers: buildFoirHeaders({
+        dispatchToken: await resolveDispatchToken(config.dispatch),
+        dispatchContext: config.dispatch.context ?? void 0,
+        extra: config.headers
+      })
+    };
+  }
+  const bearerToken = await resolveBearerToken(config);
+  return {
+    headers: buildFoirHeaders({
+      apiKey: config.apiKey,
+      draftChannel: config.channel === "draft",
+      bearerToken,
+      orgId: config.orgId,
+      orgUrl: config.orgUrl,
+      extra: config.headers
+    }),
+    key: { apiKey: config.apiKey, bearerToken }
+  };
+}
+function assertFoirCredential(config) {
+  const loose = config;
+  const operation = generatedOperation(config.generated);
+  if (loose.dispatch === void 0) {
+    if (typeof loose.apiKey !== "string" || loose.apiKey === "") {
+      throw new FoirRequestError(
+        "[foir] createFoirClient needs both apiUrl and apiKey (or, inside an operation endpoint, apiUrl and dispatch)"
+      );
+    }
+    if (operation !== void 0) {
+      throw new FoirRequestError(
+        `[foir] createFoirClient: the module passed as \`generated\` was generated for operation "${operation}" (\`foir types --operation ${operation}\`), so its types are what that operation's dispatch token is served, and this client holds an api key, which is served its own surface. Generate the key's types with \`foir types\`, or build this client from the dispatch token inside the operation's endpoint.`
+      );
+    }
+    return;
+  }
+  const keySide = [
+    "apiKey",
+    "bearerToken",
+    "orgId",
+    "orgUrl",
+    "channel",
+    "wsUrl",
+    "webSocketImpl",
+    "reconnect",
+    "connectionParams"
+  ].filter((name) => loose[name] !== void 0);
+  if (keySide.length > 0) {
+    throw new FoirRequestError(
+      `[foir] createFoirClient was given \`dispatch\` and ${keySide.map((n) => `\`${n}\``).join(", ")}. A dispatch token and an api key are different actors, and the dispatch token carries its own customer, organization and channel. Pass one credential: \`dispatch\` inside an operation endpoint, \`apiKey\` everywhere else.`
+    );
+  }
+  const dispatch = loose.dispatch;
+  if (!dispatch || typeof dispatch.token !== "function") {
+    throw new FoirRequestError(
+      "[foir] `dispatch.token` must be a function that returns the token, e.g. `() => token`, so a refreshed token is read on each request rather than one captured at construction. `requireScopedToken` returns one ready to pass."
+    );
+  }
+  refuseCredentialHeaders(config.headers);
+  if (operation === void 0) {
+    throw new FoirRequestError(
+      "[foir] createFoirClient: a client built from a dispatch token takes the module `foir types --operation <operation key>` generated for that operation, as `generated`. Its types are what the operation's token is served; a module generated for a key types calls the token is refused, and without one nothing says which operation this is."
+    );
+  }
+  const dispatched = contextOperation(dispatch.context);
+  if (dispatched !== void 0 && dispatched !== operation) {
+    throw new FoirRequestError(
+      `[foir] createFoirClient: the module passed as \`generated\` was generated for operation "${operation}", and this endpoint was dispatched for "${dispatched}". Generate this endpoint's types with \`foir types --operation ${dispatched}\`.`
+    );
+  }
+}
+function generatedOperation(generated) {
+  if (typeof generated !== "object" || generated === null) return void 0;
+  const credential = generated.foirCredential;
+  if (typeof credential !== "object" || credential === null) return void 0;
+  const operation = credential.operation;
+  return typeof operation === "string" && operation !== "" ? operation : void 0;
+}
+function contextOperation(context) {
+  for (const part of (context ?? "").split(";")) {
+    const [key, value] = part.split("=", 2);
+    if (key?.trim() === "operation" && value) return value.trim();
+  }
+  return void 0;
+}
 function foirRoute(input) {
   if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
-  if (input.orgId) return { lane: "origin", reason: "org" };
+  if (input.orgId || input.orgUrl) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
   if (input.writeToken) return { lane: "origin", reason: "floor" };
   if (input.channel === "draft") return { lane: "origin", reason: "channel" };
@@ -223,22 +350,16 @@ async function executeFoirRawDocument(config, document, mutation, variables, opt
 async function runFoirDocument(config, document, mutation, variables, options) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
-  const bearerToken = await resolveBearerToken(config);
-  const headers = buildFoirHeaders({
-    apiKey: config.apiKey,
-    draftChannel: config.channel === "draft",
-    bearerToken,
-    orgId: config.orgId,
-    extra: config.headers
-  });
+  const { headers, key } = await resolveFoirAuth(config);
   const hash = await documentHash(document);
-  const route = foirRoute({
-    apiKey: config.apiKey,
-    bearerToken,
+  const sharedKey = key !== void 0 && foirRoute({
+    apiKey: key.apiKey,
+    bearerToken: key.bearerToken,
     orgId: config.orgId,
+    orgUrl: config.orgUrl,
     mutation,
     channel: config.channel
-  });
+  }).lane === "shared" ? key.apiKey : void 0;
   const post = (body) => doFetch(endpoint, {
     method: "POST",
     headers,
@@ -248,8 +369,8 @@ async function runFoirDocument(config, document, mutation, variables, options) {
   const extensions = persistedQueryExtension(hash);
   let res;
   try {
-    if (route.lane === "shared") {
-      res = await doFetch(buildCdnUrl(endpoint, config.apiKey, hash, variables), {
+    if (sharedKey !== void 0) {
+      res = await doFetch(buildCdnUrl(endpoint, sharedKey, hash, variables), {
         method: "GET",
         headers,
         ...config.requestInit
@@ -287,20 +408,16 @@ async function readErrorBody(res) {
 }
 
 // src/data/manifest.ts
-async function fetchFoirManifest(config) {
-  const url = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+async function fetchFoirManifest(config, options = {}) {
+  const base = foirDataEndpoint(config.apiUrl, "/v1/manifest");
+  const url = options.operation === void 0 ? base : `${base}?operation=${encodeURIComponent(options.operation)}`;
   const doFetch = config.fetch ?? globalThis.fetch;
+  const { headers } = await resolveFoirAuth(config);
   let res;
   try {
     res = await doFetch(url, {
       method: "GET",
-      headers: buildFoirHeaders({
-        apiKey: config.apiKey,
-        draftChannel: config.channel === "draft",
-        bearerToken: await resolveBearerToken(config),
-        orgId: config.orgId,
-        extra: config.headers
-      }),
+      headers,
       ...config.requestInit
     });
   } catch (err) {
@@ -705,6 +822,13 @@ function planFoirModelCall(source, call) {
   }
   return planCall(source, opDef, `${call.model}.${call.op}`, operationName(model.typeName, call.op), call);
 }
+var CREATING_OPS = /* @__PURE__ */ new Set(["create", "submit"]);
+function withCreateIdempotencyKey(source, model, op, args) {
+  if (!CREATING_OPS.has(op) || args.idempotencyKey !== void 0) return args;
+  const argTypes = source.models[model]?.ops?.[op]?.argTypes;
+  if (!argTypes || !("idempotencyKey" in argTypes)) return args;
+  return { ...args, idempotencyKey: globalThis.crypto.randomUUID() };
+}
 function planFoirNamespaceCall(source, call) {
   const namespace = source.namespaces?.[call.namespace];
   if (!namespace) {
@@ -862,6 +986,11 @@ var FoirSocketTransport = class {
   keepAlive = null;
   retryTimer = null;
   constructor(config) {
+    if (config.dispatch !== void 0) {
+      throw new FoirRequestError(
+        "[foir] a client built from a dispatch token cannot subscribe. The subscription socket authenticates an api key, an admin token or a customer bearer, and has no path for a dispatch token. Queries and mutations made as the operation go to /graphql and work as they are."
+      );
+    }
     this.config = config;
     this.policy = { ...DEFAULT_RECONNECT, ...config.reconnect ?? {} };
   }
@@ -933,13 +1062,7 @@ var FoirSocketTransport = class {
   async sendConnectionInit(socket) {
     this.connecting = false;
     try {
-      const headers = buildFoirHeaders({
-        apiKey: this.config.apiKey,
-        draftChannel: this.config.channel === "draft",
-        bearerToken: await resolveBearerToken(this.config),
-        orgId: this.config.orgId,
-        extra: this.config.headers
-      });
+      const { headers } = await resolveFoirAuth(this.config);
       const { "Content-Type": _contentType, ...params } = headers;
       const extra = await this.config.connectionParams?.() ?? {};
       this.send(socket, {
@@ -1546,7 +1669,8 @@ function splitQuery(query) {
   return { args, include, omit, pick, depth };
 }
 var GENERATED_EXPORTS = [
-  "foirSchemaVersion",
+  "foirSurfaceVersion",
+  "foirSurfaceHashes",
   "foirSelections",
   "foirNamespaceSelections",
   "foirSelectionUnions"
@@ -1566,10 +1690,16 @@ function resolveGeneratedConfig(config) {
       `[foir] createFoirClient: the module passed as \`generated\` is missing ${missing.join(", ")}. \`foir types\` emits ${GENERATED_EXPORTS.join(", ")} together, so a module missing one is stale or hand-assembled \u2014 re-run \`foir types\`. Reading the rest and fetching \`GET /v1/manifest\` for the remainder would hide that; omit \`generated\` entirely to ask for the manifest deliberately.`
     );
   }
-  const version = generated["foirSchemaVersion"];
-  if (typeof version !== "number" || !Number.isFinite(version)) {
+  const version = generated["foirSurfaceVersion"];
+  if (typeof version !== "string" || version === "") {
+    throw new FoirRequestError(
+      "[foir] createFoirClient: `generated.foirSurfaceVersion` is not a surface version. It is what the drift check compares against the server. Re-run `foir types`."
+    );
+  }
+  const hashes = generated["foirSurfaceHashes"];
+  if (!isRecord(hashes) || Object.values(hashes).some((h) => typeof h !== "string")) {
     throw new FoirRequestError(
-      "[foir] createFoirClient: `generated.foirSchemaVersion` is not a number. It is the manifest version the drift check compares against \u2014 re-run `foir types`."
+      "[foir] createFoirClient: `generated.foirSurfaceHashes` is not an object of component -> hash. It is how a drift names what moved. Re-run `foir types`."
     );
   }
   const selections = generated["foirSelections"];
@@ -1610,13 +1740,57 @@ function resolveGeneratedConfig(config) {
   }
   return {
     ...config,
-    schemaVersion: config.schemaVersion ?? version,
+    surfaceVersion: config.surfaceVersion ?? version,
+    surfaceHashes: config.surfaceHashes ?? hashes,
     selections: config.selections ?? selections,
     namespaceSelections: config.namespaceSelections ?? namespaceSelections,
     selectionUnions: config.selectionUnions ?? selectionUnions,
     subscriptions: config.subscriptions ?? subscriptions
   };
 }
+function changedSurfaceParts(generated, served) {
+  if (!generated || !served) return [];
+  const out = /* @__PURE__ */ new Set();
+  for (const [key, hash] of Object.entries(served)) {
+    if (generated[key] !== hash) out.add(key);
+  }
+  for (const key of Object.keys(generated)) {
+    if (served[key] === void 0) out.add(key);
+  }
+  return [...out].sort();
+}
+var SURFACE_SECTIONS = {
+  models: ["model", "models"],
+  namespaces: ["namespace", "namespaces"],
+  selectionUnions: ["union", "unions"]
+};
+var SURFACE_WHOLES = {
+  subscriptions: "the subscriptions",
+  composedFor: "the organization it is composed for"
+};
+function describeChanged(changed) {
+  const named = /* @__PURE__ */ new Map();
+  const wholes = [];
+  for (const part of changed) {
+    const dot = part.indexOf(".");
+    const section = dot < 0 ? part : part.slice(0, dot);
+    if (dot < 0 || !SURFACE_SECTIONS[section]) {
+      wholes.push(SURFACE_WHOLES[part] ?? part);
+      continue;
+    }
+    named.set(section, [...named.get(section) ?? [], `\`${part.slice(dot + 1)}\``]);
+  }
+  const phrases = [];
+  for (const [section, [one, many]] of Object.entries(SURFACE_SECTIONS)) {
+    const names = named.get(section);
+    if (names?.length) phrases.push(`${names.length === 1 ? one : many} ${names.join(", ")}`);
+  }
+  return [...phrases, ...wholes].join("; ");
+}
+function describeDrift(drift) {
+  const moved = describeChanged(drift.changed);
+  return `the types were generated from surface ${drift.generated}, and the server is serving ${drift.server} (${drift.channel}).` + (moved ? ` Changed since: ${moved}.` : "");
+}
 function announceFallback(config) {
   if (config.generated !== void 0 || config.selections !== void 0) return;
   if (config.announceManifestFallback === false) return;
@@ -1625,9 +1799,12 @@ function announceFallback(config) {
   );
 }
 function createFoirClient(clientConfig) {
-  if (!clientConfig?.apiUrl || !clientConfig?.apiKey) {
-    throw new Error("[foir] createFoirClient needs both apiUrl and apiKey");
+  if (!clientConfig?.apiUrl) {
+    throw new Error(
+      "[foir] createFoirClient needs both apiUrl and apiKey (or, inside an operation endpoint, apiUrl and dispatch)"
+    );
   }
+  assertFoirCredential(clientConfig);
   const config = resolveGeneratedConfig(clientConfig);
   announceFallback(config);
   let driftChecked = false;
@@ -1652,31 +1829,19 @@ function createFoirClient(clientConfig) {
     }
     return manifest();
   };
-  const sameSurface = (a, b) => {
-    const stable = (v) => {
-      if (Array.isArray(v)) return v.map(stable);
-      if (v && typeof v === "object") {
-        return Object.keys(v).sort().map((k) => [k, stable(v[k])]);
-      }
-      return v;
-    };
-    return JSON.stringify(stable(a)) === JSON.stringify(stable(b));
-  };
   const maybeCheckDrift = () => {
-    const generated = config.schemaVersion;
+    const generated = config.surfaceVersion;
     if (driftChecked) return;
     if (generated === void 0) return;
     if (config.checkSchemaDrift === false) return;
     driftChecked = true;
     void manifest().then((served) => {
-      if (served.schemaVersion === generated) return;
-      if (sameSurface(config.selections, served.models) && sameSurface(config.namespaceSelections ?? {}, served.namespaces ?? {}) && sameSurface(config.selectionUnions ?? {}, served.selectionUnions ?? {})) {
-        return;
-      }
+      if (!served.surfaceVersion || served.surfaceVersion === generated) return;
       const drift = {
         generated,
-        server: served.schemaVersion,
-        channel: served.channel
+        server: served.surfaceVersion,
+        channel: served.channel,
+        changed: changedSurfaceParts(config.surfaceHashes, served.surfaceHashes)
       };
       detectedDrift = drift;
       if (config.onSchemaDrift) {
@@ -1684,7 +1849,7 @@ function createFoirClient(clientConfig) {
         return;
       }
       console.warn(
-        `[foir] schema drift: types were generated from schemaVersion ${drift.generated}, the server is serving ${drift.server} (${drift.channel}). Re-run \`foir types\` \u2014 the selection trees this client prints from are the ones that version published, so a new field is not merely untyped, it is not requested.`
+        `[foir] schema drift: ${describeDrift(drift)} Re-run \`foir types\`: the selection trees this client prints from are the ones that surface published, so a new field is not merely untyped, it is not requested.`
       );
     }).catch(() => {
     });
@@ -1692,17 +1857,18 @@ function createFoirClient(clientConfig) {
   const assertNoStaleSelections = (what) => {
     if (config.strictSchemaDrift === false || !detectedDrift) return;
     throw new FoirSchemaDriftError(
-      `[foir] refusing ${what}: types were generated from schemaVersion ${detectedDrift.generated}, the server is serving ${detectedDrift.server} (${detectedDrift.channel}). The selection trees this client prints from are the ones that version published, so a field added since is not requested at all. Re-run \`foir types\`. Set \`strictSchemaDrift: false\` to warn instead.`,
+      `[foir] refusing ${what}: ${describeDrift(detectedDrift)} The selection trees this client prints from are the ones that surface published, so a field added since is not requested at all. Re-run \`foir types\`.`,
       detectedDrift
     );
   };
   const runModel = async (model, op, query) => {
     assertNoStaleSelections(`${model}.${op}`);
     const { args, include, omit, pick, depth } = splitQuery(query);
-    const plan = planFoirModelCall(await selectionSource(), {
+    const source = await selectionSource();
+    const plan = planFoirModelCall(source, {
       model,
       op,
-      args,
+      args: withCreateIdempotencyKey(source, model, op, args),
       include,
       omit,
       pick,

package/dist/index.js

@@ -256,15 +256,6 @@ function EditorProvider({
           type: "request-operation",
           payload: { operationKey, input, requestId, mode: options?.mode ?? "sync" }
         });
-        setTimeout(() => {
-          if (pendingOperationsRef.current.has(requestId)) {
-            pendingOperationsRef.current.delete(requestId);
-            resolve({
-              success: false,
-              error: { code: "TIMEOUT", message: "Operation timed out" }
-            });
-          }
-        }, 6e4);
       });
     },
     [postMessage]

package/dist/live/drift.d.ts

@@ -15,7 +15,7 @@ import type { FoirSchemaDrift } from '../data/transport';
  * longer exists — until the tab is reloaded, which on a long-lived admin
  * session can be days.
  *
- * The SDK already detects this: the data client compares the manifest version
+ * The SDK already detects this: the data client compares the surface version
  * its generated types came from against the one the server is serving, and
  * reports `FoirSchemaDrift`. What was missing is anyone acting on it.
  *
@@ -36,16 +36,15 @@ export interface FoirDriftHandlerOptions {
 /**
  * Whether a reported drift is worth clearing the cache for.
  *
- * A server AHEAD of the generated types is the deploy case, and it is the one
- * that matters: entries resolved against the old shape are still being served
- * to code that was compiled for it.
+ * Any surface other than the one the types were generated from is. The versions
+ * are content hashes, so there is no ahead or behind: a deploy that added a
+ * field and a rollback that removed one are both a different surface, and in
+ * both the cache holds responses resolved against a shape the code no longer
+ * reads, which is the torn state this exists to remove.
  *
- * A server BEHIND is a rollback, or a client that reached an older replica
- * mid-deploy. Clearing there is defensible too, and it is deliberately included:
- * the cache holds responses from BOTH versions in that window, which is the
- * torn state this exists to remove. What is NOT actionable is equality — a
- * client reporting no drift at all, which the detector should not produce but
- * which costs nothing to refuse here rather than to clear the world for.
+ * What is NOT actionable is equality, or a version missing on either side: a
+ * report the detector should not produce, and one that costs nothing to refuse
+ * here rather than to clear the world for.
  */
 export declare function foirDriftIsActionable(drift: FoirSchemaDrift): boolean;
 /**

package/dist/live.js

@@ -800,7 +800,7 @@ function createFoirCoalescer(options) {
 
 // src/live/drift.ts
 function foirDriftIsActionable(drift) {
-  return Number.isFinite(drift.generated) && Number.isFinite(drift.server) && drift.generated !== drift.server;
+  return Boolean(drift.generated) && Boolean(drift.server) && drift.generated !== drift.server;
 }
 function createFoirDriftHandler(options) {
   return (drift) => {