@foir/sdk 0.10.0 → 0.12.0

package/dist/data.js

@@ -62,7 +62,12 @@ var FoirRequestError = class extends Error {
    * failed on the first attempt for an hour.
    */
   get retryable() {
-    if (this.status === void 0) return true;
+    if (this.status === void 0) {
+      if (this.graphQLErrors?.length || this.prunedSelections?.length) {
+        return this.code === "RATE_LIMITED" || this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+      }
+      return true;
+    }
     if (this.status === 429 || this.code === "RATE_LIMITED") return true;
     if (this.status >= 500) return true;
     return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
@@ -76,19 +81,50 @@ 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.`
+      );
+    }
+  }
+}
+var FOIR_VISITOR_IP_HEADER = "X-Foir-Visitor-IP";
 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.visitorAddress) {
+      headers[FOIR_VISITOR_IP_HEADER] = input.visitorAddress;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -104,6 +140,26 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
+var FoirAuthDowngradedError = class extends FoirRequestError {
+  downgrade;
+  constructor(downgrade) {
+    super(
+      `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}), so the request was served as ${downgrade.servedAs}`,
+      { graphQLErrors: [{ message: "customer token rejected", extensions: { code: "AUTH_DOWNGRADED" } }] }
+    );
+    this.name = "FoirAuthDowngradedError";
+    this.downgrade = downgrade;
+  }
+};
+var FoirSessionExpiredError = class extends FoirRequestError {
+  constructor(options) {
+    super("[foir] the customer session has expired and could not be refreshed: sign in again", {
+      cause: options?.cause,
+      graphQLErrors: [{ message: "session expired", extensions: { code: "SESSION_EXPIRED" } }]
+    });
+    this.name = "FoirSessionExpiredError";
+  }
+};
 var warnedDowngrade = null;
 function reportAuthDowngrade(envelope) {
   const downgrade = envelope.extensions?.auth;
@@ -132,12 +188,18 @@ 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) {
+  if (options?.rejectDowngrade && json.extensions?.auth) {
+    throw new FoirAuthDowngradedError(json.extensions.auth);
+  }
   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}`, {
@@ -194,15 +256,126 @@ var FoirSchemaDriftError = class extends FoirRequestError {
 function foirDataEndpoint(apiUrl, path) {
   return foirApiEndpoint(apiUrl, path);
 }
+async function resolveVisitorAddress(config) {
+  const source = config.visitor;
+  const value = typeof source === "function" ? await source() : source;
+  const address = value?.trim();
+  return address ? address : void 0;
+}
 async function resolveBearerToken(config) {
   const source = config.bearerToken;
   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,
+      visitorAddress: await resolveVisitorAddress(config),
+      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 (loose.visitor !== void 0 && !loose.apiKey.startsWith("sk_")) {
+      throw new FoirRequestError(
+        "[foir] createFoirClient: `visitor` names the visitor a server calls for, and only a secret key holding visitors:forward may send it. A public key already calls as its visitor, and cannot hold the permission. Drop `visitor`, or build this client from your server's secret key."
+      );
+    }
+    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",
+    "refreshBearer",
+    "orgId",
+    "orgUrl",
+    "visitor",
+    "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" };
@@ -220,25 +393,45 @@ async function executeFoirDocument(config, plan) {
 async function executeFoirRawDocument(config, document, mutation, variables, options) {
   return await runFoirDocument(config, document, mutation, variables, options);
 }
+var renewing = /* @__PURE__ */ new WeakMap();
+function renewBearerOnce(refresh) {
+  const running = renewing.get(refresh);
+  if (running) return running;
+  const next = refresh().finally(() => renewing.delete(refresh));
+  renewing.set(refresh, next);
+  return next;
+}
 async function runFoirDocument(config, document, mutation, variables, options) {
+  try {
+    return await sendFoirDocument(config, document, mutation, variables, options);
+  } catch (err) {
+    const refresh = config.refreshBearer;
+    if (!(err instanceof FoirAuthDowngradedError) || !refresh || err.downgrade.reason === "wrong_project") {
+      throw err;
+    }
+    const token = err.downgrade.reason === "expired" ? await renewBearerOnce(refresh) : null;
+    if (!token) throw new FoirSessionExpiredError({ cause: err });
+    try {
+      return await sendFoirDocument({ ...config, bearerToken: token }, document, mutation, variables, options);
+    } catch (again) {
+      if (again instanceof FoirAuthDowngradedError) throw new FoirSessionExpiredError({ cause: again });
+      throw again;
+    }
+  }
+}
+async function sendFoirDocument(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 +441,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
@@ -275,7 +468,7 @@ async function runFoirDocument(config, document, mutation, variables, options) {
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json, options);
+  return readFoirEnvelope(json, { ...options, rejectDowngrade: Boolean(key?.bearerToken) });
 }
 async function readErrorBody(res) {
   try {
@@ -287,20 +480,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 +894,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 +1058,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 +1134,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 +1741,8 @@ function splitQuery(query) {
   return { args, include, omit, pick, depth };
 }
 var GENERATED_EXPORTS = [
-  "foirSchemaVersion",
+  "foirSurfaceVersion",
+  "foirSurfaceHashes",
   "foirSelections",
   "foirNamespaceSelections",
   "foirSelectionUnions"
@@ -1566,10 +1762,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 +1812,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 +1871,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 +1901,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 +1921,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 +1929,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,
@@ -2024,9 +2262,12 @@ function decimal(value) {
   return new FoirDecimal(value);
 }
 export {
+  FOIR_VISITOR_IP_HEADER,
+  FoirAuthDowngradedError,
   FoirDecimal,
   FoirRequestError,
   FoirSchemaDriftError,
+  FoirSessionExpiredError,
   FoirSocketTransport,
   createFoirClient,
   createFoirClientFromEnv,

package/dist/graphql/client.d.ts

@@ -6,7 +6,7 @@
  * Consumers that bring their own GraphQL client (Apollo/urql/react-query) use
  * the generated `TypedDocumentNode`s directly and replicate those two headers.
  */
-export { foirRequest, isFoirPreview, absolutiseFoirMediaUrl, FOIR_CDN_BASE, FoirRequestError, } from './foir-request';
+export { foirRequest, isFoirPreview, absolutiseFoirMediaUrl, FOIR_CDN_BASE, FoirRequestError, FoirAuthDowngradedError, FoirSessionExpiredError, } from './foir-request';
 export type { FoirEnv, FoirRequestOptions } from './foir-request';
 /**
  * Failure classification. Branch on these rather than on `err.message`: the

package/dist/graphql/foir-request.d.ts

@@ -24,7 +24,7 @@
  */
 import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { type FoirEnv, type FoirRequestOptions } from '../transport/foir-http';
-export { FoirRequestError, isFoirPreview, isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, type FoirEnv, type FoirErrorCode, type FoirErrorExtensions, type FoirGraphQLErrorItem, type FoirRateLimitSnapshot, type FoirRequestOptions, type FoirAuthDowngrade, } from '../transport/foir-http';
+export { FoirRequestError, FoirAuthDowngradedError, FoirSessionExpiredError, isFoirPreview, isFoirRateLimited, isFoirUnauthenticated, isFoirForbidden, isFoirNotFound, readFoirRateLimit, type FoirEnv, type FoirErrorCode, type FoirErrorExtensions, type FoirGraphQLErrorItem, type FoirRateLimitSnapshot, type FoirRequestOptions, type FoirAuthDowngrade, } from '../transport/foir-http';
 export { withFoirRetry, foirRetryDelayMs, type FoirRetryPolicy, } from '../transport/retry';
 /** Default Foir CDN origin used to absolutise relative media URLs. */
 export declare const FOIR_CDN_BASE = "https://cdn.foir.dev/";

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) => {