@foir/sdk 0.10.0 → 0.12.0

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
@@ -55,7 +60,7 @@
  * with more force here — this client is per-credential, so anything cached
  * across instances is cached across tenants.
  */
-import { FoirRequestError, type FoirTokenProvider } from '../transport/foir-http';
+import { FoirRequestError, type FoirTokenProvider, type FoirVisitorSource } from '../transport/foir-http';
 import type { FoirDocumentPlan, FoirNamespaceSelections, FoirSelections, FoirSelectionUnions } from './document';
 import type { FoirSchemaDefinition } from './schema';
 import type { FoirSubjectRegistry } from './subjects';
@@ -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;
 }
-export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDefinition> {
+/** 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;
+}
+/**
+ * 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';
     /**
@@ -131,6 +211,18 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * per-request; a bare string is used as-is.
      */
     bearerToken?: string | FoirTokenProvider;
+    /**
+     * Renew the customer bearer when an answer comes back served without it
+     * because it expired. Resolve the new token, or null when the session is
+     * over. It is called at most once per request, and one call is shared by the
+     * client's requests that find the bearer lapsed at the same time.
+     *
+     * With it, such a request is asked again with the new token, and fails with
+     * `FoirSessionExpiredError` when there is none. Without it, the request fails
+     * with `FoirAuthDowngradedError`. Either way it is never handed the signed-out
+     * answer as though it were the signed-in one.
+     */
+    refreshBearer?: () => Promise<string | null>;
     /**
      * The organization every request from this client acts in, sent as
      * `X-Org-Id`.
@@ -166,6 +258,51 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * appear.
      */
     orgId?: string;
+    /**
+     * The address of the visitor a server rendering pages is calling for, or a
+     * function resolving it for each request, sent as `X-Foir-Visitor-IP`. The
+     * public API's per-visitor limit then applies to that visitor rather than to
+     * your server, which otherwise counts as one visitor for every page it
+     * renders.
+     *
+     * Give it the address your host guarantees: the one its edge sets and a
+     * visitor cannot. A header a visitor can write lets them name a fresh address
+     * per request, which is exactly what the limit exists to stop. The docs list
+     * the value for each common host.
+     *
+     * A secret key only, and one holding `visitors:forward`: the API refuses the
+     * header, naming the permission, from any other. A client built from a public
+     * key is refused `visitor` here, because a browser already calls as its own
+     * visitor and a public key cannot hold the permission.
+     */
+    visitor?: FoirVisitorSource;
+    /**
+     * 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 +311,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 +325,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 +377,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 +395,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 +414,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 +446,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 +508,76 @@ 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' | 'refreshBearer' | 'orgId' | 'orgUrl' | 'visitor' | '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;
+    refreshBearer?: never;
+    orgId?: never;
+    orgUrl?: never;
+    visitor?: 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 +600,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 +651,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 +693,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.
      *