@foir/sdk 0.10.0 → 0.11.0

package/dist/data/document.d.ts

@@ -237,6 +237,19 @@ export interface FoirNamespaceCall {
  * shape for, and inventing one is what this design exists to stop.
  */
 export declare function planFoirModelCall(source: FoirSelectionSource, call: FoirCall): FoirDocumentPlan;
+/**
+ * A create's arguments with an idempotency key, when the server's create takes
+ * one and the caller sent none.
+ *
+ * The key is made here, before the first attempt, so a retry of the same call
+ * carries the same key and the platform answers it with the record the first
+ * attempt made rather than making a second. A key made on the server would be
+ * new on every attempt, and one derived from the request would merge two
+ * deliberate, identical creates into one. A caller that sends its own key keeps
+ * it, and an update is left alone: an increment's key is the caller's to
+ * choose, since only the caller knows which calls are the same one.
+ */
+export declare function withCreateIdempotencyKey(source: FoirSelectionSource, model: string, op: string, args: Record<string, unknown>): Record<string, unknown>;
 /**
  * Turn a namespace call into a document.
  *

package/dist/data/index.d.ts

@@ -37,6 +37,15 @@
  * const anything = await foir.raw('{ designTokens { name value } }');
  * ```
  *
+ * Inside an operation endpoint the client is built from the dispatch instead of
+ * a key, and calls Foir as the operation, with the module `foir types
+ * --operation <key>` generated for that operation:
+ *
+ * ```ts
+ * const { dispatch } = await requireScopedToken(request, { expectedProjectId });
+ * const foir = createFoirClient({ apiUrl, dispatch, generated });
+ * ```
+ *
  * `FoirSchema` comes from `foir types`. The contract it generates
  * against is written down in `schema.ts` — read that file before changing
  * anything here, because a generator is written against it.
@@ -44,12 +53,13 @@
 export { createFoirClient, createFoirClientFromEnv, graphql } from './client';
 export type { FoirClient, FoirClientCore, FoirModelClient, FoirNamespaceClient, FoirRawOptions, TypedFoirDocument, } from './client';
 export { fetchFoirManifest } from './manifest';
+export type { FoirManifestRequestOptions } from './manifest';
 export type { FoirManifest, FoirManifestComposite, FoirManifestModel, FoirManifestNamespace, FoirManifestOp, FoirManifestOpPayload, FoirManifestRelation, FoirManifestScalar, FoirManifestSelection, FoirManifestSelectionField, FoirManifestSelectionMember, FoirManifestSelectionUnion, FoirManifestStructural, FoirManifestSubscription, FoirManifestSubscriptionArgScope, FoirManifestUnclassifiedField, } from './manifest';
 export { planFoirModelCall, planFoirNamespaceCall } from './document';
 export type { FoirCall, FoirDocumentPlan, FoirNamespaceCall, FoirNamespaceSelections, FoirRecordPath, FoirSelectionModel, FoirSelectionNamespace, FoirSelections, FoirSelectionSource, FoirSelectionUnions, } from './document';
 export { createFoirSubjectRegistry, recordFoirSubjects } from './subjects';
 export type { FoirSubject, FoirSubjectEntry, FoirSubjectOptions, FoirSubjectOrigin, FoirSubjectRegistry, } from './subjects';
-export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirSubmitAnonymousNoteArgs, FoirAnonymousNoteReceipt, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
+export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAccessSource, FoirAccessor, FoirCreateMyNoteArgs, FoirSubmitAnonymousNoteArgs, FoirAnonymousNoteReceipt, FoirCustomerNote, FoirCustomerNoteAttachment, FoirDegraded, FoirDepthBelow, FoirDepthLevel, FoirDeviceType, FoirGranteeKind, FoirJsonValue, FoirMyAccess, FoirMyNotesArgs, FoirMyNotesResult, FoirNoteConfig, FoirNoteSubjectType, FoirPlatformType, FoirRecordOwner, FoirResolveContext, FoirResourceAccess, FoirUnexpandedRecord, FoirUpdateManyPayload, FoirVisibility, GeoPoint, Image, ImageFormat, ImageVariant, ImageVariantSet, MediaValue, Passage, Prose, ProseSpan, RecordAncestor, Reference, Richtext, Video, } from './builtins';
 /**
  * Pre-rename spellings. The `<Name>Block` wrappers and the `<Name>Value`
  * split are the same thing as the types above — an item IS its value — so each
@@ -61,14 +71,14 @@ export type { CollabInfo, FileValue, FoirAccessGrant, FoirAccessLevel, FoirAcces
  */
 export type { FileBlock, GeoPointValue, ImageBlock, ImageValue, ReferenceBlock, ReferenceValue, RichtextBlock, RichtextValue, VideoBlock, VideoValue, } from './builtins';
 export { FoirSchemaDriftError, foirDataEndpoint, foirRoute } from './transport';
-export type { FoirClientConfig, FoirGeneratedModule, FoirLane, FoirLaneReason, FoirRouteDecision, FoirRouteInput, FoirSchemaDrift, } from './transport';
+export type { FoirClientConfig, FoirDispatchClientConfig, FoirDispatchCredential, FoirGeneratedModule, FoirKeyClientConfig, FoirKeyGeneratedModule, FoirLane, FoirLaneReason, FoirOperationCredential, FoirOperationGeneratedModule, FoirRequestConfig, FoirRouteDecision, FoirRouteInput, FoirSchemaDrift, } from './transport';
 export { foirSocketEndpoint, FoirSocketTransport } from './ws-transport';
 export type { FoirReconnectPolicy, FoirSubscribeRequest, FoirSubscription, FoirSubscriptionHandlers, FoirWebSocketFactory, FoirWebSocketLike, } from './ws-transport';
 export { printSubscriptionDocument } from './subscription-document';
 export type { FoirSubscriptionArgument, PrintSubscriptionDocumentInput, } from './subscription-document';
 export type { FoirChangeSubscribeOptions, FoirExecutionSubscribeOptions, FoirJobProgressEvent, FoirModelSubscriptions, FoirNamespaceSubscriptions, FoirNotificationEvent, FoirOperationExecutionEvent, FoirRecordChangedEvent, } from './subscriptions';
 export type { FoirConnection, FoirFieldsShape, FoirModelDefinition, FoirNamespaceDefinition, FoirNamespaceOpDefinition, FoirOpDefinition, FoirRelationDefinition, FoirReturnDefinition, FoirSchemaDefinition, } from './schema';
-export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmittableKey, FoirOpResult, FoirQuery, FoirRecordResult, } from './selection';
+export type { FoirInclude, FoirModelOperation, FoirNamespaceOperation, FoirOmittableKey, FoirOpResult, FoirQuery, FoirRecordResult, FoirWriteResult, } from './selection';
 export { FoirDecimal, decimal } from './decimal';
 export type { FoirDecimalDivOptions, FoirDecimalInput, FoirDecimalRounding, } from './decimal';
 export { FoirRequestError } from '../transport/foir-http';

package/dist/data/manifest.d.ts

@@ -14,7 +14,7 @@
  * (`api-public/internal/schema/manifest.go`) field for field; where the two
  * disagree the platform is right and this file is the bug.
  */
-import { type FoirClientConfig } from './transport';
+import { type FoirRequestConfig } from './transport';
 export interface FoirManifestScalar {
     key: string;
     /**
@@ -273,7 +273,25 @@ export interface FoirManifestNamespace {
     ops?: Record<string, FoirManifestOp>;
 }
 export interface FoirManifest {
+    /**
+     * The invalidation counter for this project and channel. Every write that
+     * could change a response moves it, including the many that change nothing
+     * here, so it keys the ETag and the server's caches and nothing on the client
+     * is pinned to it.
+     */
     schemaVersion: number;
+    /**
+     * A hash over exactly the sections `foir types` reads, so it moves if and only
+     * if regenerating the types would write a different file. The generated
+     * module records it, and the drift check compares the two.
+     */
+    surfaceVersion: string;
+    /**
+     * The components `surfaceVersion` is folded from, keyed by where each sits in
+     * this body: `models.<key>`, `namespaces.<name>`, `selectionUnions.<name>`,
+     * `subscriptions`, `composedFor`. A drift names what moved by comparing these.
+     */
+    surfaceHashes: Record<string, string>;
     channel: 'published' | 'draft';
     /**
      * The organisation whose composition this surface is, absent for the
@@ -441,11 +459,21 @@ export interface FoirManifestSelectionMember {
     typeName: string;
     fields: FoirManifestSelectionField[];
 }
+/** What a manifest request asks for beyond the credential's own surface. */
+export interface FoirManifestRequestOptions {
+    /**
+     * Describe the surface this operation's dispatch token is served instead of
+     * the credential's own (`GET /v1/manifest?operation=<key>`). Answered to a
+     * credential that can author the operation (one holding `operations:write`)
+     * and refused to any other. `foir types --operation` sends it.
+     */
+    operation?: string;
+}
 /**
  * Fetch the manifest for the credential in `config`.
  *
  * Exported because two things outside this file need it: `foir types` reads it
  * to generate `FoirSchema`, and the client's drift check reads its
- * `schemaVersion`. Both would otherwise hand-roll the same fetch.
+ * `surfaceVersion`. Both would otherwise hand-roll the same fetch.
  */
-export declare function fetchFoirManifest(config: FoirClientConfig): Promise<FoirManifest>;
+export declare function fetchFoirManifest(config: FoirRequestConfig, options?: FoirManifestRequestOptions): Promise<FoirManifest>;

package/dist/data/schema.d.ts

@@ -19,7 +19,7 @@
  * ```
  *
  * A `.ts` and not a `.d.ts` because the file has a runtime half — the selection
- * trees, `foirSchemaVersion`, and `foirSchemaType`, which is what carries
+ * trees, `foirSurfaceVersion`, and `foirSchemaType`, which is what carries
  * `FoirSchema` across the type/value boundary so the client can infer it (a
  * namespace import carries values; an interface erases). `FoirGeneratedModule`
  * in `transport.ts` is the shape those exports have to satisfy, and it requires
@@ -30,8 +30,9 @@
  * // foir.generated.ts — DO NOT EDIT. Generated by `foir types`.
  * import type { FoirSchemaDefinition } from '@foir/sdk/data';
  *
- * /** `schemaVersion` from the manifest these types were generated from. *\/
- * export const foirSchemaVersion = 317;
+ * /** The surface these types were generated from. *\/
+ * export const foirSurfaceVersion = '6f1c0d2a9b8e4f7c3a5d1e0b2c4f6a8d';
+ * export const foirSurfaceHashes: Record<string, string> = { 'models.tilly_block': '…' };
  * export const foirSchemaChannel = 'published';
  *
  * // `<D>` ONLY on the types between the record and a union stopping point —
@@ -71,7 +72,7 @@
  * }
  *
  * export interface FoirSchema extends FoirSchemaDefinition {
- *   schemaVersion: typeof foirSchemaVersion;
+ *   surfaceVersion: typeof foirSurfaceVersion;
  *   channel: 'published';
  *   models: {
  *     tilly_block: {
@@ -211,10 +212,16 @@ export interface FoirRelationDefinition {
     /** True when the relation itself can resolve null. */
     readonly nullable: boolean;
 }
-/** How an op's result wraps (or does not wrap) the model. */
+/**
+ * How an op's result wraps (or does not wrap) the model. `write` is a record
+ * write's result: the record, and whether the answer is a replay (see
+ * `FoirWriteResult`).
+ */
 export type FoirReturnDefinition = {
     readonly kind: 'record';
     readonly nullable: boolean;
+} | {
+    readonly kind: 'write';
 } | {
     readonly kind: 'connection';
 } | {
@@ -282,12 +289,12 @@ export interface FoirNamespaceDefinition {
  */
 export interface FoirSchemaDefinition {
     /**
-     * `schemaVersion` from the manifest these types were generated from. Kept as
+     * `surfaceVersion` from the manifest these types were generated from. Kept as
      * a literal so a human reading the generated file sees it, and mirrored by a
-     * runtime `foirSchemaVersion` const for drift detection — the type cannot be
-     * read at runtime.
+     * runtime `foirSurfaceVersion` const for drift detection, because the type
+     * cannot be read at runtime.
      */
-    readonly schemaVersion: number;
+    readonly surfaceVersion: string;
     readonly channel: 'published' | 'draft';
     readonly models: Readonly<Record<string, FoirModelDefinition>>;
     readonly namespaces: Readonly<Record<string, FoirNamespaceDefinition>>;

package/dist/data/selection.d.ts

@@ -428,11 +428,26 @@ type WrapRelation<R extends FoirRelationDefinition, T> = R['list'] extends true
 export type FoirRecordResult<S extends FoirSchemaDefinition, M extends FoirModelDefinition, Q, D extends number = IncludeDepth, Depth extends number = DepthOf<Q>> = Q extends {
     include: infer I;
 } ? ApplySelection<M, Q, Depth> & IncludedRelations<S, M, I, D, Depth> : ApplySelection<M, Q, Depth>;
+/**
+ * What a record write (`create`, `update`, `rename`) answers with.
+ *
+ * `replayed` is true when the call carried an `idempotencyKey` an earlier
+ * attempt of the same write already used: the platform wrote nothing this time
+ * and `record` is as that first attempt left it. A caller that acts on the
+ * result (a stock count read back after a take, say) checks it, because a
+ * replayed answer looks exactly like a fresh one.
+ */
+export interface FoirWriteResult<R> {
+    record: R;
+    replayed: boolean;
+}
 /** Apply an op's return wrapper to the shaped record. */
 export type FoirOpResult<S extends FoirSchemaDefinition, M extends FoirModelDefinition, O extends FoirOpDefinition, Q> = O['returns'] extends {
     kind: 'opaque';
     type: infer T;
 } ? T : O['returns'] extends {
+    kind: 'write';
+} ? FoirWriteResult<FoirRecordResult<S, M, Q>> : O['returns'] extends {
     kind: 'connection';
 } ? FoirConnection<FoirRecordResult<S, M, Q>> : O['returns'] extends {
     kind: 'list';

package/dist/data/transport.d.ts

@@ -13,6 +13,11 @@
  *   anything else — `sk_`, a customer bearer, a mutation, the draft channel
  *     → `POST /graphql` with the `x-api-key` header and the APQ body.
  *
+ *   a call made AS an operation, with its dispatch token
+ *     → `POST /graphql` with `X-Foir-Token` and the dispatch's `X-Foir-Context`,
+ *       and no `x-api-key`. Always this lane: the shared one takes its
+ *       credential from the URL, and a dispatch token has no key to put there.
+ *
  * All five conditions the server's shared-lane gate refuses on are evaluated
  * HERE, locally: this code is constructing the URL, it can read the key prefix,
  * it knows whether a bearer resolved, the manifest told it whether the op is a
@@ -84,8 +89,18 @@ import type { FoirReconnectPolicy, FoirWebSocketFactory } from './ws-transport';
  * Its runtime value is `undefined` by design and nothing reads it.
  */
 export interface FoirGeneratedModule<S extends FoirSchemaDefinition = FoirSchemaDefinition> {
-    /** `foirSchemaVersion` — the manifest version these types came from. Drives the drift check. */
-    readonly foirSchemaVersion: number;
+    /**
+     * `foirSurfaceVersion`: the surface these types were generated from, a hash
+     * over exactly the parts of the manifest `foir types` reads. Drives the drift
+     * check, which compares it with the one the server is serving now.
+     */
+    readonly foirSurfaceVersion: string;
+    /**
+     * `foirSurfaceHashes`: the components that version is folded from, keyed as
+     * the manifest keys them (`models.<key>`, `namespaces.<name>`, …). What lets a
+     * drift name the models that moved rather than just say something did.
+     */
+    readonly foirSurfaceHashes: Readonly<Record<string, string>>;
     /** `foirSelections` — one entry per model, in the printer's own input shape. */
     readonly foirSelections: FoirSelections;
     /** `foirNamespaceSelections` — the same, per namespace op. */
@@ -107,8 +122,70 @@ export interface FoirGeneratedModule<S extends FoirSchemaDefinition = FoirSchema
     readonly foirSubscriptions?: readonly FoirManifestSubscription[];
     /** Type carrier for `FoirSchema`. Never read: its runtime value is `undefined`. */
     readonly foirSchemaType: S;
+    /**
+     * `foirCredential`: present when the module was generated for an operation
+     * (`foir types --operation <key>`), naming it. Its types are the surface that
+     * operation's dispatch token is served, so the module is for a client built
+     * from that token and for no other: a dispatch client requires it, and a key
+     * client refuses it. Absent from a module generated for a key.
+     */
+    readonly foirCredential?: FoirOperationCredential;
+}
+/**
+ * What a module `foir types --operation <key>` generated says about itself:
+ * the operation whose dispatch token its types describe.
+ */
+export interface FoirOperationCredential {
+    readonly operation: string;
+}
+/** A module generated for an api key: the kind a key client takes. */
+export type FoirKeyGeneratedModule<S extends FoirSchemaDefinition = FoirSchemaDefinition> = FoirGeneratedModule<S> & {
+    readonly foirCredential?: undefined;
+};
+/** A module generated for an operation: the kind a dispatch client takes. */
+export type FoirOperationGeneratedModule<S extends FoirSchemaDefinition = FoirSchemaDefinition> = FoirGeneratedModule<S> & {
+    readonly foirCredential: FoirOperationCredential;
+};
+/**
+ * The credential of a client built inside an operation endpoint: the dispatch
+ * token the platform handed it.
+ *
+ * ```ts
+ * const { dispatch } = await requireScopedToken(request, { expectedProjectId });
+ * const foir = createFoirClient({ apiUrl, dispatch, generated });
+ * ```
+ *
+ * The endpoint calls Foir AS the operation, with the capabilities the operation
+ * declared, and holds no key of its own. api-public accepts the token as a
+ * caller in its own right: it builds the schema overlay from the token's
+ * capabilities, and it reads the organization and the customer from the
+ * token's claims. So nothing a key client configures beside its key
+ * (`bearerToken`, `orgId`, `channel`) means anything here, and none of it is
+ * accepted.
+ *
+ * `requireScopedToken` returns one of these, built from the token it verified.
+ * Build one by hand only when the token reaches you some other way.
+ */
+export interface FoirDispatchCredential {
+    /**
+     * The dispatch token, sent as `X-Foir-Token`. Resolved before every request,
+     * so a caller holding a refreshed token hands the client the current one
+     * rather than the one it was built with. A provider that yields nothing fails
+     * the request: there is no other credential to fall back to.
+     */
+    token: FoirTokenProvider;
+    /**
+     * The dispatch's `X-Foir-Context` header, forwarded as it arrived so the
+     * requests the operation makes carry the run's correlation metadata. Pass
+     * `request.headers.get('X-Foir-Context')` as it is; absent is fine.
+     */
+    context?: string | null;
 }
-export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDefinition> {
+/**
+ * A client that calls Foir with an api key: a storefront's `pk_`, a server's
+ * `sk_`, optionally for a signed-in customer.
+ */
+export interface FoirKeyClientConfig<S extends FoirSchemaDefinition = FoirSchemaDefinition> {
     /**
      * Foir public API origin, e.g. `https://api.foir.dev`.
      *
@@ -119,10 +196,13 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
     apiUrl: string;
     /** `pk_…` or `sk_…`. The manifest, and therefore the generated types, are shaped by it. */
     apiKey: string;
+    /** A key client has no dispatch token; see {@link FoirDispatchClientConfig}. */
+    dispatch?: never;
     /**
-     * Read the draft schema channel (`X-Foir-Schema-Channel: draft`). Needs a
-     * `sk_` key with `drafts:read`; the header is ignored under public keys.
-     * Defaults to `'published'`.
+     * Read the draft schema channel (`X-Foir-Schema-Channel: draft`). Needs a key
+     * holding `drafts:read`: a preview environment's own `pk_`, or an `sk_`. A
+     * public key without it is served the published copy; a secret key without
+     * it is refused. Defaults to `'published'`.
      */
     channel?: 'published' | 'draft';
     /**
@@ -166,6 +246,33 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * appear.
      */
     orgId?: string;
+    /**
+     * The organization every request from this client acts in, named by the
+     * address of the page it is for, sent as `X-Org-Url`.
+     *
+     * For an app that serves many organizations from its own addresses: a path
+     * per organization (`saasapp.com/soho`), a subdomain each, or a domain an
+     * organization brought. Pass the page URL and the server finds the
+     * organization whose registered address (its app base URL, or a verified
+     * custom domain bound to it) is the longest prefix of that URL at a
+     * path-segment boundary, so `saasapp.com/soho` answers for `/soho/menu` and
+     * never for `/sohonews`. It works with the publishable key the page already
+     * ships.
+     *
+     * ```ts
+     * const foir = createFoirClient({ apiUrl, apiKey, generated, orgUrl: window.location.href });
+     * ```
+     *
+     * It is `orgId` by another spelling and bounded the same way: a URL no
+     * organization's address covers answers `NOT_FOUND` exactly as an unknown id
+     * does, a credential confined to an organization is answered about that
+     * organization alone, and the organization is a selection rather than
+     * authority. Sent with `orgId`, the two must name the same organization.
+     * `resolveOrganizationAddress(url)` answers the same id up front.
+     *
+     * Routing: always the origin endpoint, for the reason `orgId` is.
+     */
+    orgUrl?: string;
     /**
      * The generated module, whole — **the documented way to wire a client**.
      *
@@ -174,8 +281,8 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * const foir = createFoirClient({ apiUrl, apiKey, generated });
      * ```
      *
-     * It supplies `schemaVersion`, `selections`, `namespaceSelections` and
-     * `selectionUnions` in one member, and carries `FoirSchema` with it so the
+     * It supplies `surfaceVersion`, `surfaceHashes`, `selections`,
+     * `namespaceSelections` and `selectionUnions` in one member, and carries `FoirSchema` with it so the
      * type parameter is inferred rather than restated. An artifact added to
      * `foir types` later then costs a call site nothing.
      *
@@ -188,8 +295,12 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * Omitting `generated` AND `selections` asks for the manifest fallback, which
      * is supported, announced (see `announceManifestFallback`) and never reached
      * by accident.
+     *
+     * A module generated for an operation (`foir types --operation`) is refused
+     * here: its types are what that operation's dispatch token is served, not
+     * what this key is.
      */
-    generated?: FoirGeneratedModule<S>;
+    generated?: FoirKeyGeneratedModule<S>;
     /**
      * The runtime half of `foir.generated.ts` — `foirSelections`, the resolved
      * complete-by-default selection per model.
@@ -236,7 +347,11 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * `subjects.add(...)`.
      */
     subjects?: FoirSubjectRegistry;
-    /** Extra headers, applied last so they can override the ones above. */
+    /**
+     * Extra headers, applied last so they can override the ones above. A client
+     * built from a dispatch token refuses a credential header here (`x-api-key`,
+     * `Authorization`, `X-Foir-Token`, `X-Foir-Context`).
+     */
     headers?: Readonly<Record<string, string>>;
     /**
      * `fetch` implementation. Defaults to `globalThis.fetch`. Injectable for
@@ -250,11 +365,17 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      */
     requestInit?: Omit<RequestInit, 'method' | 'headers' | 'body'>;
     /**
-     * `foirSchemaVersion` from the generated module. When set, the client
-     * compares it against the server's manifest once and warns on mismatch.
-     * Carried by `generated`; set it here only to override that.
+     * `foirSurfaceVersion` from the generated module. When set, the client
+     * compares it against the surface the server is serving, once, and reports
+     * drift when they differ. Carried by `generated`; set it here only to
+     * override that.
+     */
+    surfaceVersion?: string;
+    /**
+     * `foirSurfaceHashes` from the generated module, so a drift can name what
+     * moved. Carried by `generated`; set it here only to override that.
      */
-    schemaVersion?: number;
+    surfaceHashes?: Readonly<Record<string, string>>;
     /**
      * Subscription descriptors, from the generated module's `foirSubscriptions`.
      *
@@ -263,7 +384,7 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * when absent it fetches once, as it always has.
      */
     subscriptions?: readonly FoirManifestSubscription[];
-    /** Set `false` to suppress the drift check even when `schemaVersion` is set. */
+    /** Set `false` to suppress the drift check even when `surfaceVersion` is set. */
     checkSchemaDrift?: boolean;
     /** Called instead of `console.warn` when drift is detected. */
     onSchemaDrift?: (drift: FoirSchemaDrift) => void;
@@ -295,7 +416,12 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * class of bug by construction, and refusing it would punish the escape
      * hatch people reach for precisely because it is immune.
      *
-     * Opt out at the call site, where a reader can see it:
+     * Turning it off is never the remedy for a drift. The version it compares
+     * is the SURFACE the types were generated from, which moves only when
+     * regenerating would write a different file, so every drift it reports is a
+     * real one and the fix is `foir types`. The opt-out exists for an app that
+     * knowingly ships a stale module for a while, and it says so at the call
+     * site, where a reader can see it:
      *
      * ```ts
      * createFoirClient({ strictSchemaDrift: false })  // serve stale, warn only
@@ -352,12 +478,74 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      */
     connectionParams?: () => Record<string, string> | Promise<Record<string, string>>;
 }
+/**
+ * The options that belong to a key: the key itself, what it is presented with
+ * (a customer bearer, an organization, a channel), and the subscription socket,
+ * which only a key can open.
+ */
+type FoirKeySideOption = 'apiKey' | 'dispatch' | 'channel' | 'bearerToken' | 'orgId' | 'orgUrl' | 'wsUrl' | 'webSocketImpl' | 'reconnect' | 'connectionParams';
+/**
+ * A client that calls Foir AS an operation, from inside the endpoint the
+ * operation dispatched to. See {@link FoirDispatchCredential}.
+ *
+ * Everything a key client takes except the key-side options, which are typed
+ * `never` rather than left out, so passing one is a compile error that names
+ * it. No `apiKey` above all: the dispatch token is the credential, and an
+ * endpoint that holds a key as well has become the server in the middle the
+ * operation exists to replace.
+ */
+export interface FoirDispatchClientConfig<S extends FoirSchemaDefinition = FoirSchemaDefinition> extends Omit<FoirKeyClientConfig<S>, FoirKeySideOption | 'generated'> {
+    /** The dispatch token this endpoint was handed, and the dispatch's context header. */
+    dispatch: FoirDispatchCredential;
+    /**
+     * The module `foir types --operation <key>` generated for this operation.
+     * Required: its types are the surface this operation's token is served, and
+     * a module generated for a key would type calls the token is refused. A
+     * dispatch whose context names a different operation is refused too.
+     *
+     * ```ts
+     * // foir types --operation checkout --out src/checkout.generated.ts
+     * import * as generated from './checkout.generated';
+     * const foir = createFoirClient({ apiUrl, dispatch, generated });
+     * ```
+     */
+    generated: FoirOperationGeneratedModule<S>;
+    apiKey?: never;
+    channel?: never;
+    bearerToken?: never;
+    orgId?: never;
+    orgUrl?: never;
+    wsUrl?: never;
+    webSocketImpl?: never;
+    reconnect?: never;
+    connectionParams?: never;
+}
+/**
+ * How a data client is configured: with an api key, or with an operation's
+ * dispatch token. Exactly one of the two. They are different actors, and there
+ * is no configuration that accepts either.
+ */
+export type FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDefinition> = FoirKeyClientConfig<S> | FoirDispatchClientConfig<S>;
+/**
+ * The credential and transport half of a client config, which is everything a
+ * request reads. A manifest fetch takes this rather than a whole client config:
+ * what it asks for does not depend on a generated module, and a dispatch token
+ * asks for its own surface before any module exists.
+ */
+export type FoirRequestConfig = Omit<FoirKeyClientConfig, 'generated'> | Omit<FoirDispatchClientConfig, 'generated'>;
 export interface FoirSchemaDrift {
-    /** Manifest version the local types were generated from. */
-    generated: number;
-    /** Manifest version the server is serving now. */
-    server: number;
+    /** The surface version the local types were generated from. */
+    generated: string;
+    /** The surface version the server is serving now. */
+    server: string;
     channel: string;
+    /**
+     * What moved, as the manifest keys its components: `models.<key>`,
+     * `namespaces.<name>`, `selectionUnions.<name>`, `subscriptions`,
+     * `composedFor`. A component added or removed since generation is listed
+     * too. Empty only when the module was wired without `surfaceHashes`.
+     */
+    changed: readonly string[];
 }
 /**
  * Thrown by a typed call under `strictSchemaDrift` once drift is detected.
@@ -380,8 +568,39 @@ export declare class FoirSchemaDriftError extends FoirRequestError {
  * than a re-export so `@foir/sdk/data`'s public surface is unchanged.
  */
 export declare function foirDataEndpoint(apiUrl: string, path: `/${string}`): string;
-/** Resolve `config.bearerToken`, whether it is a string, a function, or absent. */
-export declare function resolveBearerToken(config: Pick<FoirClientConfig, 'bearerToken'>): Promise<string | undefined>;
+/** One request's credential, resolved now. */
+export interface FoirResolvedAuth {
+    /** The headers the request carries, `extra` included. */
+    headers: Record<string, string>;
+    /**
+     * The key and the resolved bearer, when the credential is a key. Absent for a
+     * dispatch token, which has no key to put in a URL and so never takes the
+     * shared lane.
+     */
+    key?: {
+        apiKey: string;
+        bearerToken?: string;
+    };
+}
+/**
+ * The credential a request carries, resolved at the moment it is sent.
+ *
+ * The one place every transport (`/graphql`, `GET /v1/manifest`, the socket's
+ * `connection_init`) asks, so the three cannot drift into authenticating a
+ * client differently. Providers are called here, once per request, and not at
+ * construction.
+ */
+export declare function resolveFoirAuth(config: FoirRequestConfig): Promise<FoirResolvedAuth>;
+/**
+ * Refuse a config that names no credential, or two.
+ *
+ * The types already say this. It is checked again at runtime for a caller in
+ * plain JavaScript, or one who spread two configs together, because the
+ * failure it prevents is quiet: a client handed both a key and a dispatch token
+ * would send one and discard the other, and which actor made each request
+ * would depend on a precedence rule nobody chose.
+ */
+export declare function assertFoirCredential(config: FoirClientConfig): void;
 /** Which GraphQL endpoint a call is sent to. */
 export type FoirLane = 'shared' | 'origin';
 /**
@@ -400,6 +619,8 @@ export interface FoirRouteInput {
     bearerToken?: string;
     /** The organization the call acts in (`X-Org-Id`), when it names one. */
     orgId?: string;
+    /** The page URL the call names its organization by (`X-Org-Url`), when it does. */
+    orgUrl?: string;
     mutation: boolean;
     channel?: 'published' | 'draft';
     /**
@@ -440,3 +661,4 @@ export declare function executeFoirDocument<T>(config: FoirClientConfig, plan: F
 export declare function executeFoirRawDocument<T>(config: FoirClientConfig, document: string, mutation: boolean, variables?: Record<string, unknown>, options?: {
     strict?: boolean;
 }): Promise<T>;
+export {};

package/dist/data/ws-transport.d.ts

@@ -41,9 +41,15 @@
  * `config.connectionParams`, which is a FUNCTION and is called on every
  * connect — so a short-lived credential is re-resolved on reconnect instead of
  * being replayed after it expired.
+ *
+ * An operation's dispatch token is not one of them. The server's
+ * `connection_init` authenticates a key, an admin token or a customer bearer
+ * and has no path for a dispatch token, so a client built from one is refused
+ * here, by name, rather than opening a socket the server will close as "Not
+ * authenticated".
  */
 import { FoirRequestError } from '../transport/foir-http';
-import { type FoirClientConfig } from './transport';
+import { type FoirRequestConfig } from './transport';
 /**
  * The slice of `WebSocket` this transport uses.
  *
@@ -143,7 +149,7 @@ export declare class FoirSocketTransport {
     private disposed;
     private keepAlive;
     private retryTimer;
-    constructor(config: FoirClientConfig);
+    constructor(config: FoirRequestConfig);
     /**
      * Start a subscription.
      *