@foir/sdk 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -104,8 +104,230 @@ on `dev` would publish unreviewed work to npm.
 
 Changes on `dev` that have not been published to npm.
 
+## [0.11.0] — 2026-09-26
+
+Breaking changes under the pre-1.0 note, so this release is a MINOR:
+`OperationPayload` now describes the body the platform actually sends,
+`FoirClientConfig` is a union of two credentials, a record write resolves to
+`FoirWriteResult`, an option field's union is its declared values, and the
+generated module, the drift check and `FoirSchemaDrift` are keyed on the
+surface version instead of the schema counter.
+
+### Added
+
+- The data client takes an operation's dispatch token as its credential, so an
+  operation endpoint calls Foir AS the operation and holds no key.
+
+  ```ts
+  import { createFoirClient } from '@foir/sdk/data';
+  import { readDispatch, requireScopedToken } from '@foir/sdk/server';
+  // foir types --operation checkout --out src/checkout.generated.ts
+  import * as generated from './checkout.generated';
+
+  export async function POST(request: Request) {
+    const { dispatch } = await requireScopedToken(request, {
+      expectedProjectId: process.env.FOIR_PROJECT_ID,
+    });
+    const { input } = await readDispatch<{ email: string }>(request);
+    const foir = createFoirClient({ apiUrl: process.env.PLATFORM_API_URL!, dispatch, generated });
+    // ...
+  }
+  ```
+
+  A dispatch client requires `generated`, and only a module generated for an
+  operation: `foir types --operation <key>` types the surface that operation's
+  token is served (`GET /v1/manifest?operation=<key>`) and exports
+  `foirCredential` naming it. A key client refuses such a module, a dispatch
+  client refuses a key's module, and a dispatch whose `X-Foir-Context` names
+  another operation than the module is refused, each at the type and at
+  construction. New on `@foir/sdk/data`: `FoirOperationCredential`,
+  `FoirKeyGeneratedModule` and `FoirOperationGeneratedModule`.
+
+  A client built with `dispatch` sends the token as `X-Foir-Token`, with the
+  dispatch's `X-Foir-Context`, and never sends `x-api-key`. api-public accepts
+  the token as a caller in its own right and builds the schema from the
+  capabilities the operation declared, so the generated client works unchanged
+  over it: queries, mutations and `execute<Op>`. `dispatch.token` is a provider
+  read before every request, not a string captured once. There is no key
+  fallback: a provider that yields nothing fails the request.
+
+  New on `@foir/sdk/data`: `FoirDispatchCredential`, `FoirKeyClientConfig` and
+  `FoirDispatchClientConfig`. New on `@foir/sdk/server`: `dispatch` on the
+  result of `requireScopedToken`, which is the token it verified as a ready
+  credential.
+
+  Two things a dispatch client does not do. It does not subscribe: the
+  subscription socket authenticates a key, an admin token or a customer bearer
+  and has no path for a dispatch token, so `onChange` and friends throw, naming
+  why. And it takes no key-side option (`apiKey`, `bearerToken`, `orgId`,
+  `channel`, the socket options), because the token carries its own customer,
+  organization and channel; each is a compile error and a runtime refusal.
+
+- `readDispatch(request)` and `OperationPayloadError` on `@foir/sdk/server`.
+
+  An operation endpoint had no typed reader for its own dispatch, and the body
+  is the run, not the input: reading it as the input finds nothing and refuses
+  every call on a missing field. `readDispatch` parses the body into
+  `OperationPayload`, checks the fields that identify a dispatch, and refuses
+  anything else with `OperationPayloadError` (`status` 400), naming what is
+  wrong. It keeps every key the platform sent, typed or not. `input` is always
+  an object: a run started with no input, which the platform sends as `null`,
+  reads as `{}`.
+
+- `FoirWriteResult<R>` on `@foir/sdk/data`: `{ record, replayed }`, what a
+  record write answers with.
+
+- `fetchFoirManifest(config, { operation })` asks for the surface an
+  operation's dispatch token is served instead of the credential's own, which
+  is described to a key that can author the operation (`operations:write`).
+  `fetchFoirManifest` takes `FoirRequestConfig`, the credential and transport
+  half of a client config, so a manifest is fetched without a generated module;
+  `FoirManifestRequestOptions` and `FoirRequestConfig` are new on
+  `@foir/sdk/data`.
+
+- `FoirRecordOwner` on `@foir/sdk/data`: `{ id, ownerId, ownerKind }`, what
+  `setOwner` answers with. An operation that declares `records:attribute:<model>`
+  hands a record to another customer with `foir.<model>.setOwner({ id, ownerId })`,
+  and names the owner of a record it creates with `create({ input, ownerId })`.
+  The answer carries the owner and not the record, because an operation acting
+  for the previous holder may no longer read it.
+
+- `orgUrl` names the organization a client acts in by the address of the page
+  it is for, sent as `X-Org-Url`, beside `orgId`. An app serving many
+  organizations from its own addresses (a path each, a subdomain each, or a
+  domain an organization brought) passes the page URL with the publishable key
+  it already ships, and the server finds the organization whose registered
+  address is the longest prefix of that URL. Also on `FoirRequestOptions` and
+  the auth ops' options. A URL no organization's address covers answers
+  `NOT_FOUND` as an unknown `orgId` does, and a request naming one takes the
+  origin lane.
+
+  ```ts
+  const foir = createFoirClient({ apiUrl, apiKey, generated, orgUrl: window.location.href });
+  ```
+
+  The same answer is available up front as the `resolveOrganizationAddress(url)`
+  query.
+
+### Changed
+
+- `requestOperation` (the editor SDK) no longer gives up after 60 seconds. A
+  blocking operation is now a direct call the platform ends at the operation's
+  own timeout, and the host answers every request with that outcome, so the
+  editor's own clock could only report as failed an operation that went on to
+  complete. The promise settles when the host answers.
+
+- **Breaking (types).** `OperationPayload` matches the platform's
+  `buildOperationPayload` field for field. Code that read a field the platform
+  never sent now fails to compile, which is the point:
+
+  - `credentials` and `config` are removed. The platform stopped sending them
+    when scoped-token dispatch replaced credentials in the body; an app reads
+    its secrets through the dispatch token.
+  - `executionId` is required. It is always sent.
+  - `content`, `record`, `triggerContext` and `callback` are optional and are
+    absent, never `null`, when not sent. `content` is an object.
+  - `OperationRecordContext` is `Record<string, unknown>`. The platform forwards
+    the block as the caller wrote it and shapes none of it; the previous `data`
+    and `metadata` members were never guaranteed.
+  - `OperationTrigger` is `{ type: 'ui' | 'api' | 'lifecycle' | 'schedule' }`,
+    the platform's own four values. `fieldKey`, `fieldType` and the `field`
+    trigger were never sent; caller context arrives in `triggerContext`.
+  - `OperationContext.userId` is a string that is always present (empty for a
+    hook's run), and `locale` is removed.
+  - `OperationPayload` takes a type parameter for `input`.
+  - `callback` is documented as ASYNC only. A blocking (SYNC) dispatch carries
+    no callback: the endpoint's response body is the result. `callback` gains
+    `causationChain`.
+
+- **Breaking (types).** `FoirClientConfig` is `FoirKeyClientConfig |
+  FoirDispatchClientConfig`. A config literal with an `apiKey` is unchanged.
+  Code that `extends FoirClientConfig` in an interface should extend
+  `FoirKeyClientConfig`, and code that reads `config.apiKey` off a
+  `FoirClientConfig` sees `string | undefined`.
+
+- A client with `dispatch` refuses a credential header in `headers`
+  (`x-api-key`, `Authorization`, `X-Foir-Token`, `X-Foir-Context`), whatever its
+  case. A key client's `headers` are unchanged.
+
+- `fetchFoirManifest` resolves the credential before the request rather than
+  inside it, so a `bearerToken` provider that throws surfaces its own error
+  instead of `[foir] network error`, as it already did on `/graphql`.
+
+- **`create`, `update` and `rename` resolve to `FoirWriteResult`, not the
+  record.** The data API's `create<Model>`, `update<Model>` and
+  `rename<Model>` now return `<Model>WritePayload`, the record beside
+  `replayed`, and a typed call returns that payload as it came. `replayed` is
+  true when the call's `idempotencyKey` was already used by an earlier attempt
+  of the same write: nothing was written this time, and `record` is as the
+  first attempt left it. Read the record from `.record`:
+
+  ```ts
+  const { record, replayed } = await foir.order.update({ where, data, idempotencyKey });
+  if (replayed) {
+    // The first attempt's answer. Nothing was applied by this call.
+  }
+  ```
+
+  A generated schema types these ops as `{ kind: 'write' }`; re-run
+  `foir types`.
+
+- `FoirUpdateManyPayload` carries `replayed`, with the same meaning.
+
+- **An option field's generated union is the declared values.** The data API
+  serves an option value exactly as the config declares it (`orderSlip`, not
+  `ORDERSLIP`), so the union `foir types` prints from the manifest is the
+  config's own strings. Re-run `foir types`; a comparison against the
+  upper-cased names no longer type-checks, and never matched a stored value.
+
+- **Schema drift compares the surface version, not the schema counter.**
+
+  `GET /v1/manifest` now serves `surfaceVersion`: a hash over exactly the
+  sections `foir types` reads, so it moves if and only if regenerating the types
+  would write a different file. Beside it, `surfaceHashes` carries the
+  components that version is folded from, one per model, namespace, union
+  expansion and the subscriptions. `schemaVersion` stays on the manifest and
+  keeps meaning what it always did server-side: the invalidation counter that
+  keys the ETag and the response cache.
+
+  The client used to pin generated types to that counter. Every write that
+  could change a response bumps it, so pushing an operation, a role or a key
+  reported drift, and under the strict default the next typed call threw,
+  though nothing the client prints had moved. A false alarm and a real one had
+  the same remedy, so nobody learned which they had. Now a drift is reported
+  only when the surface moved, and it names what moved: "Changed since: model
+  `page`." Every drift is real, so the message says `foir types` and no longer
+  suggests `strictSchemaDrift: false`, which is never the remedy.
+
+  What changes for a caller:
+
+  - The generated module exports `foirSurfaceVersion` and `foirSurfaceHashes`
+    in place of `foirSchemaVersion`, and `FoirGeneratedModule` requires them. A
+    module generated before this is refused at construction by name. **Re-run
+    `foir types`** with a current `@foir/cli` as part of the upgrade.
+  - `createFoirClient`'s `schemaVersion` option is now `surfaceVersion`, with
+    `surfaceHashes` beside it. Only a client wired field by field sets them;
+    one passing `generated` gets both from the module.
+  - `FoirSchemaDefinition.schemaVersion` is now `surfaceVersion: string`.
+  - `FoirSchemaDrift.generated` and `.server` are the two surface versions, as
+    strings, and `.changed` lists the components that moved (`models.page`).
+    An `onSchemaDrift` handler logging the numbers logs the hashes instead.
+  - `foirDriftIsActionable` (`@foir/sdk/live`) treats any difference as
+    actionable: a hash has no ahead or behind, and a rollback is another
+    surface like any other.
+  - `FoirManifest` gains `surfaceVersion` and `surfaceHashes`.
+
 ---
 
+### Fixed
+
+- A response in which no root field answered now throws `FoirRequestError`
+  with the server's errors. It used to count as partial data. Every
+  `execute<Op>` payload is nullable, so a failed operation run came back as
+  `{ r: null }` beside its error, and the typed call resolved to `null` with the
+  refusal only logged. The partial-errors default is unchanged wherever at least
+  one root field answered, and a null root with no error is still an answer.
+
 ## [0.10.0] — 2026-09-22
 
 Two breaking changes under the pre-1.0 note, so a MINOR: `fetchHostedSession`

package/README.md

@@ -79,9 +79,17 @@ and an artifact added to the generator later costs your call site nothing. A
 module missing one of those exports is a compile error naming it, not a quiet
 degrade: pass it whole, or do not pass it.
 
-The four fields it replaces (`schemaVersion`, `selections`,
+The fields it replaces (`surfaceVersion`, `surfaceHashes`, `selections`,
 `namespaceSelections`, `selectionUnions`) still work and still win where both
-are given, so an existing client keeps compiling and behaving exactly as it did.
+are given.
+
+**Drift is keyed on the surface.** The module records the `surfaceVersion` it
+was generated from: a hash over exactly what `foir types` reads, which moves only
+when regenerating would write a different file. Pushing an operation, a role or
+a key moves the server's invalidation counter and not the surface, so it is not
+drift. Publishing a field on a model the types include is, and the client
+refuses the next typed call with a message naming the model. The remedy is
+`foir types`; `strictSchemaDrift: false` never is.
 
 **Scalars are always complete**, so `post.title` is typed present and *is*
 present — there is no partial-`select` footgun. `include` adds a relation key,

package/dist/auth/ops.d.ts

@@ -81,6 +81,14 @@ export interface AuthOpOptions {
      * already confined to an organization may only name its own.
      */
     orgId?: string;
+    /**
+     * The organization the call acts in, named by the address of the page it is
+     * for, sent as `X-Org-Url`: same contract as `FoirClientConfig.orgUrl`. A
+     * storefront on a path per organization signs its customers in on those
+     * pages, and names the organization the way every other request from them
+     * does.
+     */
+    orgUrl?: string;
     /**
      * `fetch` implementation. Defaults to `globalThis.fetch`. Injectable for
      * tests and for runtimes that hand you a bound `fetch` (Hydrogen/Oxygen).

package/dist/auth.js

@@ -103,19 +103,46 @@ function readFoirRetryAfterMs(headers) {
   const seconds = Number(headers.get("Retry-After"));
   return Number.isFinite(seconds) && 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)) {
@@ -159,12 +186,15 @@ function refusePrunedDocument(json, options) {
     `[foir] selections stripped from this query: ${selections.map(describe).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}`, {
@@ -232,12 +262,13 @@ async function foirRequest(env, document, variables, options) {
     apiKey,
     draftChannel: isFoirPreview(env),
     bearerToken: options?.bearerToken,
-    orgId: options?.orgId
+    orgId: options?.orgId,
+    orgUrl: options?.orgUrl
   });
   const documentText = print2(document);
   let res;
   try {
-    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId)) {
+    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId ?? options?.orgUrl)) {
       const hash = await documentHash(documentText);
       let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
         method: "GET",
@@ -793,10 +824,42 @@ 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 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" };
@@ -814,22 +877,16 @@ async function executeFoirDocument(config, plan) {
 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,
@@ -839,8 +896,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
@@ -878,20 +935,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) {
@@ -963,6 +1016,7 @@ function authClientConfig(env, options) {
     channel: isFoirPreview(env) ? "draft" : "published",
     bearerToken: options?.bearerToken,
     orgId: options?.orgId,
+    orgUrl: options?.orgUrl,
     headers: options?.headers,
     fetch: options?.fetch
   };

package/dist/client.js

@@ -115,19 +115,46 @@ function readFoirRetryAfterMs(headers) {
   const seconds = Number(headers.get("Retry-After"));
   return Number.isFinite(seconds) && 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)) {
@@ -164,12 +191,15 @@ function refusePrunedDocument(json, options) {
     `[foir] selections stripped from this query: ${selections.map(describe).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}`, {
@@ -271,12 +301,13 @@ async function foirRequest(env, document, variables, options) {
     apiKey,
     draftChannel: isFoirPreview(env),
     bearerToken: options?.bearerToken,
-    orgId: options?.orgId
+    orgId: options?.orgId,
+    orgUrl: options?.orgUrl
   });
   const documentText = print2(document);
   let res;
   try {
-    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId)) {
+    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId ?? options?.orgUrl)) {
       const hash = await documentHash(documentText);
       let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
         method: "GET",

package/dist/codegen/preset.d.ts

@@ -21,9 +21,10 @@ export interface FoirCodegenOptions {
      */
     apiKey?: string;
     /**
-     * Preview (`sk_`) key with `drafts:read`. Reads the DRAFT schema channel so
+     * Preview key holding `drafts:read`. Reads the DRAFT schema channel so
      * freshly pushed (un-promoted) model changes are visible to codegen.
-     * Strongly preferred — a `pk_` key only sees the published schema.
+     * Strongly preferred: a key without `drafts:read` only sees the published
+     * schema.
      */
     previewKey?: string;
     /** Output directory for the generated client types. Default `./app/gql/foir/`. */

package/dist/data/builtins.d.ts

@@ -423,10 +423,26 @@ export interface FoirResourceAccess {
     public: boolean;
     visibility: FoirVisibility;
 }
-/** `updateMany` — how many rows moved, and which. */
+/**
+ * `updateMany`: how many rows moved, and which. `replayed` is true when the
+ * call's `idempotencyKey` was already used by an earlier attempt of the same
+ * update: nothing moved this time, and `count` and `ids` are that attempt's.
+ */
 export interface FoirUpdateManyPayload {
     count: number;
     ids: string[];
+    replayed: boolean;
+}
+/**
+ * `setOwner`: who the record belongs to after an operation handed it to
+ * another customer. It carries the owner and not the record, because the
+ * operation may have been acting for the previous holder, who can no longer
+ * read it. `ownerKind` is always `'customer'` from this op.
+ */
+export interface FoirRecordOwner {
+    id: string;
+    ownerId: string;
+    ownerKind: string;
 }
 /**
  * What a customer's note can be ABOUT: the customer-plane subset of the closed

package/dist/data/client.d.ts

@@ -23,8 +23,9 @@
  * than named one at a time at every call site — see `resolveGeneratedConfig`
  * below for why that indirection is worth having.
  *
- * The individual fields (`schemaVersion`, `selections`, `namespaceSelections`,
- * `selectionUnions`) still work, and still win where both are given.
+ * The individual fields (`surfaceVersion`, `surfaceHashes`, `selections`,
+ * `namespaceSelections`, `selectionUnions`) still work, and still win where
+ * both are given.
  *
  * The call is the same call it always was. What changed underneath is what goes
  * on the wire: the client loads that op's selection tree, applies
@@ -47,7 +48,7 @@
  * ---------------------------------------------------------------------------
  *
  * The trees ARE runtime data — that is the one thing the generated module has to
- * carry across the type/value boundary, alongside `foirSchemaVersion`. Passing
+ * carry across the type/value boundary, alongside `foirSurfaceVersion`. Passing
  * them in costs nothing and is the intended path.
  *
  * When they are absent the client fetches `GET /v1/manifest` once, at first use,
@@ -75,7 +76,7 @@
 import type { FoirModelDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirSchemaDefinition } from './schema';
 import type { FoirModelOperation, FoirNamespaceOperation } from './selection';
 import { type FoirEnv } from '../transport/foir-http';
-import { type FoirClientConfig, type FoirGeneratedModule } from './transport';
+import { type FoirClientConfig, type FoirKeyGeneratedModule, type FoirKeyClientConfig } from './transport';
 import { type FoirModelSubscriptions, type FoirNamespaceSubscriptions } from './subscriptions';
 /**
  * The ops available on one model for this credential, plus its subscriptions.
@@ -230,8 +231,9 @@ export declare function createFoirClient<S extends FoirSchemaDefinition = FoirSc
  * `createFoirClient` from the `PLATFORM_API_URL` / `PLATFORM_API_KEY` /
  * `FOIR_PREVIEW` convention `@foir/sdk/client` already uses, so a storefront
  * that has an env wired for GraphQL can add the data client without a second
- * set of variables. Preview picks the `sk_` `PLATFORM_PREVIEW_API_KEY` and the
- * draft schema channel, exactly as `foirRequest` does.
+ * set of variables. Preview picks `PLATFORM_PREVIEW_API_KEY`, the preview
+ * environment's own key holding `drafts:read`, and the draft schema channel,
+ * exactly as `foirRequest` does.
  *
  * ```ts
  * import * as generated from './foir.generated';
@@ -241,7 +243,7 @@ export declare function createFoirClient<S extends FoirSchemaDefinition = FoirSc
  * `generated` is spelled out in the overrides type rather than left inside the
  * `Omit<…>` so `S` is inferred from it here exactly as it is on `createFoirClient`.
  */
-export declare function createFoirClientFromEnv<S extends FoirSchemaDefinition = FoirSchemaDefinition>(env: FoirEnv, overrides?: Omit<FoirClientConfig, 'apiUrl' | 'apiKey' | 'channel' | 'generated'> & {
-    generated?: FoirGeneratedModule<S>;
+export declare function createFoirClientFromEnv<S extends FoirSchemaDefinition = FoirSchemaDefinition>(env: FoirEnv, overrides?: Omit<FoirKeyClientConfig, 'apiUrl' | 'apiKey' | 'channel' | 'generated'> & {
+    generated?: FoirKeyGeneratedModule<S>;
 }): FoirClient<S>;
 export {};