@foir/sdk 0.9.0 → 0.11.0

package/dist/data.js

@@ -5,11 +5,30 @@ function isFoirPreview(env) {
 function resolveFoirApiKey(env) {
   return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
 }
+var MALFORMED_PRUNE_REASONS = /* @__PURE__ */ new Set([
+  "unknown_field",
+  "subselections_on_scalar",
+  "missing_subselections"
+]);
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
   status;
   /** GraphQL errors, when the request failed with a no-data error envelope. */
   graphQLErrors;
+  /**
+   * The `data` the server did return, when a STRICT read refused a partial
+   * response. Present only on that path: without it, opting into strictness
+   * would trade a silent wrong answer for a thrown one that discards the answer,
+   * and a caller that wants to log what it nearly rendered could not.
+   */
+  partialData;
+  /**
+   * The selections the server stripped, when the refusal was a pruned document
+   * rather than a partial error. Same purpose as `partialData`: a caller that
+   * wants to log what it nearly rendered, or name the offending path in a
+   * developer-facing message, has it without re-parsing anything.
+   */
+  prunedSelections;
   cause;
   constructor(message, options) {
     super(message);
@@ -17,6 +36,8 @@ var FoirRequestError = class extends Error {
     this.cause = options?.cause;
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
+    this.partialData = options?.partialData;
+    this.prunedSelections = options?.prunedSelections;
   }
   /**
    * The code of the first error, if the response carried one.
@@ -55,16 +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.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)) {
@@ -80,14 +131,48 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
-function readFoirEnvelope(json) {
+var warnedDowngrade = null;
+function reportAuthDowngrade(envelope) {
+  const downgrade = envelope.extensions?.auth;
+  if (!downgrade) {
+    warnedDowngrade = null;
+    return;
+  }
+  if (warnedDowngrade === downgrade.reason) return;
+  warnedDowngrade = downgrade.reason;
+  console.warn(
+    `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}) \u2014 this request was served as ${downgrade.servedAs}, so auth-targeted content resolved to its anonymous variant. ` + (downgrade.reason === "expired" ? "Re-exchange the token and retry." : "Check which credential you are sending.")
+  );
+}
+function refusePrunedDocument(json, options) {
+  const selections = json.extensions?.pruned?.selections;
+  if (!selections?.length) return;
+  const describe2 = (s) => `${s.path}${s.type ? ` on ${s.type}` : ""} (${s.reason})`;
+  const malformed = selections.filter((s) => MALFORMED_PRUNE_REASONS.has(s.reason));
+  if (malformed.length && options?.strict !== false) {
+    throw new FoirRequestError(
+      `[foir] the server could not serve part of this query and returned the rest without it: ${malformed.map(describe2).join(", ")}. Those selections do not exist on the schema this project is serving. Pass strict: false to get the partial answer instead of this error.`,
+      { prunedSelections: selections }
+    );
+  }
+  console.warn(
+    `[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) {
+    if (answeredAnything(json.data) && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
-        graphQLErrors: json.errors
+        graphQLErrors: json.errors,
+        partialData: json.data ?? void 0
       });
     }
   }
@@ -128,6 +213,14 @@ async function hasFoirErrorCode(res, ...codes) {
 }
 
 // src/data/transport.ts
+var FoirSchemaDriftError = class extends FoirRequestError {
+  drift;
+  constructor(message, drift) {
+    super(message);
+    this.name = "FoirSchemaDriftError";
+    this.drift = drift;
+  }
+};
 function foirDataEndpoint(apiUrl, path) {
   return foirApiEndpoint(apiUrl, path);
 }
@@ -136,10 +229,109 @@ 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 || 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" };
   return { lane: "shared" };
 }
@@ -152,26 +344,22 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
-async function executeFoirRawDocument(config, document, mutation, variables) {
-  return await runFoirDocument(config, document, mutation, variables);
+async function executeFoirRawDocument(config, document, mutation, variables, options) {
+  return await runFoirDocument(config, document, mutation, variables, options);
 }
-async function runFoirDocument(config, document, mutation, variables) {
+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,
-    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,
@@ -181,8 +369,8 @@ async function runFoirDocument(config, document, mutation, variables) {
   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
@@ -208,7 +396,7 @@ async function runFoirDocument(config, document, mutation, variables) {
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json);
+  return readFoirEnvelope(json, options);
 }
 async function readErrorBody(res) {
   try {
@@ -220,19 +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),
-        extra: config.headers
-      }),
+      headers,
       ...config.requestInit
     });
   } catch (err) {
@@ -637,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) {
@@ -794,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 ?? {} };
   }
@@ -865,12 +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),
-        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, {
@@ -977,7 +1169,9 @@ var FoirSocketTransport = class {
         return;
       }
       case GQL.error: {
-        const error = new FoirRequestError(`[foir] subscription refused: ${describe(message.payload)}`);
+        const error = new FoirRequestError(`[foir] subscription refused: ${describe(message.payload)}`, {
+          graphQLErrors: graphQLErrorItems(message.payload)
+        });
         if (!message.id) {
           this.failAll(error);
           this.teardownSocket(true);
@@ -1088,6 +1282,21 @@ function defaultWebSocketFactory() {
   }
   return (url, protocols) => new Impl(url, protocols);
 }
+function graphQLErrorItems(payload) {
+  const list = Array.isArray(payload) ? payload : payload == null ? [] : [payload];
+  const items = [];
+  for (const entry of list) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const { message, path, extensions } = entry;
+    if (extensions === void 0 && path === void 0) continue;
+    items.push({
+      message: typeof message === "string" ? message : describe(entry),
+      ...Array.isArray(path) ? { path } : {},
+      ...typeof extensions === "object" && extensions !== null ? { extensions } : {}
+    });
+  }
+  return items.length > 0 ? items : void 0;
+}
 function describe(payload) {
   if (payload == null) return "no reason given";
   if (typeof payload === "string") return payload;
@@ -1133,12 +1342,19 @@ var FoirSubscriptionRouter = class {
     if (method !== "onChange") {
       throw new FoirRequestError(`[foir] ${modelKey}.${method} is not a subscription`);
     }
+    const after = input.after;
+    const args = [{ name: "modelKey", type: "String!" }];
+    const variables = { modelKey };
+    if (typeof after === "number") {
+      args.push({ name: "after", type: "EventSeq" });
+      variables.after = after;
+    }
     return this.open(
       {
         field: "recordChanged",
         operationName: "FoirRecordChanged",
-        args: [{ name: "modelKey", type: "String!" }],
-        variables: { modelKey }
+        args,
+        variables
       },
       input
     );
@@ -1177,7 +1393,7 @@ var FoirSubscriptionRouter = class {
           args: [{ name: "id", type: "String!" }],
           variables: { id }
         },
-        handlers
+        { ...handlers, onData: (event) => handlers.onData(executionEventWithEnumStatus(event)) }
       );
     }
     throw new FoirRequestError(`[foir] ns.${namespace}.${method} is not a subscription`);
@@ -1222,6 +1438,12 @@ var FoirSubscriptionRouter = class {
     };
   }
 };
+function executionEventWithEnumStatus(event) {
+  if (event === null || typeof event !== "object") return event;
+  const status = event.status;
+  if (typeof status !== "string") return event;
+  return { ...event, status: status.toUpperCase() };
+}
 function findSubscription(manifest, field) {
   const found = manifest.subscriptions?.find((s) => s.field === field);
   if (found) return found;
@@ -1369,6 +1591,9 @@ function recordsAt(value, path) {
 }
 
 // src/data/client.ts
+function graphql(document) {
+  return document;
+}
 var NON_MODEL_PROPS = /* @__PURE__ */ new Set([
   "then",
   "catch",
@@ -1444,7 +1669,8 @@ function splitQuery(query) {
   return { args, include, omit, pick, depth };
 }
 var GENERATED_EXPORTS = [
-  "foirSchemaVersion",
+  "foirSurfaceVersion",
+  "foirSurfaceHashes",
   "foirSelections",
   "foirNamespaceSelections",
   "foirSelectionUnions"
@@ -1464,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"];
@@ -1500,28 +1732,83 @@ function resolveGeneratedConfig(config) {
       `[foir] createFoirClient: \`generated.foirSelectionUnions["${name}"]\` has no \`members\`. A tree that names this union would print an empty selection set. Re-run \`foir types\`.`
     );
   }
+  const subscriptions = generated["foirSubscriptions"];
+  if (subscriptions !== void 0 && !Array.isArray(subscriptions)) {
+    throw new FoirRequestError(
+      "[foir] createFoirClient: `generated.foirSubscriptions` is not an array of subscription descriptors. Re-run `foir types`."
+    );
+  }
   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
+    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;
   console.info(
-    "[foir] no generated module passed, so this client fetches `GET /v1/manifest` once at first use and prints from the trees it publishes. That works \u2014 it is what makes a zero-codegen start possible \u2014 but it puts a round trip in front of the first query on every cold start. Run `foir types`, then `import * as generated from './foir.generated'` and pass `generated`. Silence this with `announceManifestFallback: false`."
+    "[foir] no generated module passed, so this client fetches `GET /v1/manifest` once at first use and prints from the trees it publishes. That works \u2014 it is what makes a zero-codegen start possible \u2014 but it puts a round trip in front of the first query on every cold start. Run `foir types`, then `import * as generated from './foir.generated'` and pass `generated`. Silence this with `announceManifestFallback: false`.\n[foir] A subscribe-only client can now take that advice too: `foir types` emits `foirSubscriptions` alongside the model trees, so a generated client prints its subscribe document from the module and makes no request at all. Weigh the module against one fetch behind a socket that lives for the whole session \u2014 on a phone the fallback may still be the better trade."
   );
 }
 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;
+  let detectedDrift;
   let manifestOnce;
   const manifest = () => {
     if (!manifestOnce) {
@@ -1543,34 +1830,45 @@ function createFoirClient(clientConfig) {
     return manifest();
   };
   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 (!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) {
         config.onSchemaDrift(drift);
         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(() => {
     });
   };
+  const assertNoStaleSelections = (what) => {
+    if (config.strictSchemaDrift === false || !detectedDrift) return;
+    throw new FoirSchemaDriftError(
+      `[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,
@@ -1582,6 +1880,7 @@ function createFoirClient(clientConfig) {
     return result;
   };
   const runNamespace = async (namespace, op, query) => {
+    assertNoStaleSelections(`ns.${namespace}.${op}`);
     const { args, include, omit, pick, depth } = splitQuery(query);
     const plan = planFoirNamespaceCall(await selectionSource(), {
       namespace,
@@ -1597,11 +1896,18 @@ function createFoirClient(clientConfig) {
     maybeCheckDrift();
     return result;
   };
+  const subscriptionManifest = () => {
+    if (!config.subscriptions) return manifest();
+    return Promise.resolve({
+      subscriptions: config.subscriptions,
+      selectionUnions: config.selectionUnions
+    });
+  };
   const subscriptions = /* @__PURE__ */ (() => {
     const held = { router: null };
     return {
       get() {
-        held.router ??= new FoirSubscriptionRouter(config, manifest);
+        held.router ??= new FoirSubscriptionRouter(config, subscriptionManifest);
         return held.router;
       },
       dispose() {
@@ -1629,7 +1935,7 @@ function createFoirClient(clientConfig) {
       return opProxy({ namespace });
     }
   });
-  const raw = async (document, variables) => {
+  const raw = async (document, variables, options) => {
     if (typeof document !== "string" || !document.trim()) {
       throw new FoirRequestError("[foir] raw() takes a GraphQL document string");
     }
@@ -1637,7 +1943,8 @@ function createFoirClient(clientConfig) {
       config,
       document,
       isFoirMutationDocument(document),
-      variables
+      variables,
+      options
     );
     maybeCheckDrift();
     return result;
@@ -1666,16 +1973,236 @@ function createFoirClientFromEnv(env, overrides) {
     channel: isFoirPreview(env) ? "draft" : "published"
   });
 }
+
+// src/data/decimal.ts
+var DECIMAL_PATTERN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+var MAX_SCALE = 1e3;
+function pow10(n) {
+  return 10n ** BigInt(n);
+}
+function divRound(numerator, denominator, rounding) {
+  if (denominator === 0n) throw new RangeError("FoirDecimal: division by zero");
+  const negative = numerator < 0n !== denominator < 0n;
+  const n = numerator < 0n ? -numerator : numerator;
+  const d = denominator < 0n ? -denominator : denominator;
+  let quotient = n / d;
+  const remainder = n % d;
+  if (remainder !== 0n && rounding !== "down") {
+    const doubled = remainder * 2n;
+    if (doubled > d) {
+      quotient += 1n;
+    } else if (doubled === d) {
+      if (rounding === "half-up" || quotient % 2n === 1n) quotient += 1n;
+    }
+  }
+  return negative ? -quotient : quotient;
+}
+function parse(input) {
+  const text = input.trim();
+  if (!DECIMAL_PATTERN.test(text)) {
+    throw new TypeError(
+      `FoirDecimal: ${JSON.stringify(input)} is not a decimal. Expected a numeric string such as "19.99".`
+    );
+  }
+  const [mantissa, exponentText] = text.split(/[eE]/);
+  const exponent = exponentText ? Number(exponentText) : 0;
+  const negative = mantissa.startsWith("-");
+  const unsigned = negative || mantissa.startsWith("+") ? mantissa.slice(1) : mantissa;
+  const [integerPart = "", fractionPart = ""] = unsigned.split(".");
+  let units = BigInt(`${integerPart || "0"}${fractionPart}`);
+  let scale = fractionPart.length - exponent;
+  if (scale < 0) {
+    units *= pow10(-scale);
+    scale = 0;
+  }
+  if (scale > MAX_SCALE) {
+    throw new RangeError(`FoirDecimal: scale ${scale} exceeds the maximum of ${MAX_SCALE}`);
+  }
+  return { units: negative ? -units : units, scale };
+}
+var FoirDecimal = class _FoirDecimal {
+  // Not `readonly` only so `#of` can populate a fresh instance without going
+  // back through the string parser. Never mutated after construction, and
+  // `#`-private so immutability is not part of the public contract to keep.
+  #units;
+  #scale;
+  constructor(value) {
+    if (value instanceof _FoirDecimal) {
+      this.#units = value.#units;
+      this.#scale = value.#scale;
+      return;
+    }
+    if (typeof value === "bigint") {
+      this.#units = value;
+      this.#scale = 0;
+      return;
+    }
+    if (typeof value !== "string") {
+      throw new TypeError(
+        `FoirDecimal: refusing to construct from ${typeof value}. A JavaScript number is a float and may already have lost precision \u2014 pass the string, or use FoirDecimal.fromNumber() to accept that loss explicitly.`
+      );
+    }
+    const { units, scale } = parse(value);
+    this.#units = units;
+    this.#scale = scale;
+  }
+  /**
+   * Build a decimal from a JavaScript number, accepting the precision that
+   * number may already have lost.
+   *
+   * Deliberately not the constructor. It is for interop — a value read from a
+   * third-party JSON API that emitted a float — and naming it at every call
+   * site is the point. `fromNumber(0.1 + 0.2)` gives `0.30000000000000004`,
+   * because that is genuinely the value it was handed.
+   */
+  static fromNumber(value) {
+    if (!Number.isFinite(value)) {
+      throw new RangeError(`FoirDecimal: ${value} is not a finite number`);
+    }
+    return new _FoirDecimal(value.toPrecision(17));
+  }
+  /** `true` if `value` parses as a decimal. Does not throw. */
+  static isDecimalString(value) {
+    return typeof value === "string" && DECIMAL_PATTERN.test(value.trim());
+  }
+  /** Decimal places carried by this value. `19.90` has scale 2. */
+  get scale() {
+    return this.#scale;
+  }
+  /** Re-express at `scale`, rounding away any digits that no longer fit. */
+  rescale(scale, rounding = "half-up") {
+    if (!Number.isInteger(scale) || scale < 0 || scale > MAX_SCALE) {
+      throw new RangeError(`FoirDecimal: scale must be an integer in 0..${MAX_SCALE}, got ${scale}`);
+    }
+    if (scale === this.#scale) return this;
+    const units = scale > this.#scale ? this.#units * pow10(scale - this.#scale) : divRound(this.#units, pow10(this.#scale - scale), rounding);
+    return _FoirDecimal.#of(units, scale);
+  }
+  add(other) {
+    const [a, b, scale] = _FoirDecimal.#align(this, other);
+    return _FoirDecimal.#of(a + b, scale);
+  }
+  sub(other) {
+    const [a, b, scale] = _FoirDecimal.#align(this, other);
+    return _FoirDecimal.#of(a - b, scale);
+  }
+  /** Exact: scales add, so `1.10 × 1.10` is `1.2100` rather than `1.21`. */
+  mul(other) {
+    const rhs = new _FoirDecimal(other);
+    return _FoirDecimal.#of(this.#units * rhs.#units, this.#scale + rhs.#scale);
+  }
+  /** The only inexact operation — see {@link FoirDecimalDivOptions}. */
+  div(other, options = {}) {
+    const { scale = 20, rounding = "half-even" } = options;
+    if (!Number.isInteger(scale) || scale < 0 || scale > MAX_SCALE) {
+      throw new RangeError(`FoirDecimal: scale must be an integer in 0..${MAX_SCALE}, got ${scale}`);
+    }
+    const rhs = new _FoirDecimal(other);
+    const numerator = this.#units * pow10(rhs.#scale + scale);
+    const denominator = rhs.#units * pow10(this.#scale);
+    return _FoirDecimal.#of(divRound(numerator, denominator, rounding), scale);
+  }
+  abs() {
+    return this.#units < 0n ? _FoirDecimal.#of(-this.#units, this.#scale) : this;
+  }
+  neg() {
+    return _FoirDecimal.#of(-this.#units, this.#scale);
+  }
+  isZero() {
+    return this.#units === 0n;
+  }
+  isNegative() {
+    return this.#units < 0n;
+  }
+  /** `-1`, `0` or `1`. Use this rather than `<`, which throws. */
+  cmp(other) {
+    const [a, b] = _FoirDecimal.#align(this, other);
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  /** Numeric equality: `1.0` equals `1.00`. Scale is display, not identity. */
+  equals(other) {
+    return this.cmp(other) === 0;
+  }
+  /**
+   * Fixed-place string, rounding `half-up` by default because this is the
+   * display operation and that is what a person means by "to 2dp".
+   */
+  toFixed(places, rounding = "half-up") {
+    return this.rescale(places, rounding).toString();
+  }
+  /**
+   * The canonical wire form, preserving scale. Never exponent notation, so the
+   * output always parses back to an equal value.
+   */
+  toString() {
+    const negative = this.#units < 0n;
+    const digits = (negative ? -this.#units : this.#units).toString();
+    if (this.#scale === 0) return negative ? `-${digits}` : digits;
+    const padded = digits.padStart(this.#scale + 1, "0");
+    const integerPart = padded.slice(0, padded.length - this.#scale);
+    const fractionPart = padded.slice(padded.length - this.#scale);
+    return `${negative ? "-" : ""}${integerPart}.${fractionPart}`;
+  }
+  /** `JSON.stringify` emits the canonical string, not an object. Pinned by test. */
+  toJSON() {
+    return this.toString();
+  }
+  /**
+   * Explicitly lossy — this is the boundary back into float, and naming it is
+   * the point. Fine for a chart axis; never for money you will add up.
+   */
+  toNumber() {
+    return Number(this.toString());
+  }
+  /**
+   * Answers the `'string'` hint so template literals work, and throws on every
+   * other hint so `+`, `<` and `Number()` fail loudly instead of silently
+   * concatenating or truncating.
+   */
+  [Symbol.toPrimitive](hint) {
+    if (hint === "string") return this.toString();
+    throw new TypeError(
+      hint === "number" ? "FoirDecimal: cannot be coerced to a number implicitly. Use .toNumber() to accept the precision loss, or .cmp() to compare." : "FoirDecimal: cannot be coerced implicitly. Use .add() / .sub() / .mul() / .div() for arithmetic, .cmp() to compare, or .toString() for text."
+    );
+  }
+  get [Symbol.toStringTag]() {
+    return "FoirDecimal";
+  }
+  /** Skip parsing when the units are already known to be well-formed. */
+  static #of(units, scale) {
+    const instance = new _FoirDecimal(0n);
+    instance.#units = units;
+    instance.#scale = scale;
+    return instance;
+  }
+  /** Bring two values to a common scale so their units can be compared. */
+  static #align(left, right) {
+    const rhs = new _FoirDecimal(right);
+    const scale = Math.max(left.#scale, rhs.#scale);
+    return [
+      left.#units * pow10(scale - left.#scale),
+      rhs.#units * pow10(scale - rhs.#scale),
+      scale
+    ];
+  }
+};
+function decimal(value) {
+  return new FoirDecimal(value);
+}
 export {
+  FoirDecimal,
   FoirRequestError,
+  FoirSchemaDriftError,
   FoirSocketTransport,
   createFoirClient,
   createFoirClientFromEnv,
   createFoirSubjectRegistry,
+  decimal,
   fetchFoirManifest,
   foirDataEndpoint,
   foirRoute,
   foirSocketEndpoint,
+  graphql,
   planFoirModelCall,
   planFoirNamespaceCall,
   printSubscriptionDocument,