@foir/sdk 0.7.0 → 0.8.0

package/dist/data/transport.d.ts

@@ -1,11 +1,53 @@
 /**
- * `POST /v1/query` transport.
+ * The data client's transport: two GraphQL lanes, and no other.
  *
- * Everything Foir-specific about the request — which key, the preview schema
- * channel, the customer bearer, the error shape — comes from
- * `../transport/foir-http`, the same module `@foir/sdk/client`'s `foirRequest`
- * uses. This file adds only what is specific to the JSON op endpoint: the URL,
- * the body, and reading the single root field back out.
+ * ---------------------------------------------------------------------------
+ * Where a call goes
+ * ---------------------------------------------------------------------------
+ *
+ *   read + `pk_` key + no customer bearer + published channel
+ *     → `GET /cdn/graphql?key=pk_…&extensions={"persistedQuery":{"sha256Hash":…}}`
+ *       A shared cache in front of the caller stores the response, because the
+ *       request is a GET and the credential is in the URL.
+ *
+ *   anything else — `sk_`, a customer bearer, a mutation, the draft channel
+ *     → `POST /graphql` with the `x-api-key` header and the APQ body.
+ *
+ * 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
+ * mutation, and the channel is its own configuration. No schema, no extra round
+ * trip. `foirRoute` is that decision, isolated so each condition can be tested on
+ * its own rather than inferred from an end-to-end call that happened to take one
+ * path.
+ *
+ * The server remains the authority. It REFUSES an ineligible request rather than
+ * serving it uncached (`NOT_SHAREABLE`, with the condition named), and a refusal
+ * is retried on `/graphql` — but eligibility is never discovered by trial.
+ *
+ * ---------------------------------------------------------------------------
+ * Persisted queries
+ * ---------------------------------------------------------------------------
+ *
+ * Complete-by-default produces maximal documents: `page.findMany` prints ~34kB.
+ * So the hash goes first and the document follows only on a miss, on both lanes.
+ * A miss answers `PERSISTED_QUERY_NOT_FOUND` with **HTTP 200**, and the retry
+ * that carries the document is always a POST — never a longer GET, which is the
+ * limit the hash exists to stay under.
+ *
+ * ---------------------------------------------------------------------------
+ * One wire format, and no second one
+ * ---------------------------------------------------------------------------
+ *
+ * Every op prints. The manifest publishes a `payload` for each op a credential
+ * can reach — every namespace op included, and the model ops whose result is not
+ * the model — so no call has to be described some other way. An op this client
+ * cannot print is an error that names the op.
+ *
+ * That is a constraint the module holds to, not an accident of what exists: a
+ * second format kept alive beside this one could only ever be reached as a
+ * silent fallback, and an op that quietly stopped being printed would land there
+ * unnoticed.
  *
  * Edge-safe: `fetch` only, no Node built-ins, and no module-level state of any
  * kind. A shared cache on a stateless multi-tenant edge worker is a
@@ -14,29 +56,51 @@
  * across instances is cached across tenants.
  */
 import { type FoirTokenProvider } from '../transport/foir-http';
-/** The wire body `POST /v1/query` accepts. Exactly one of model/namespace. */
-export type FoirRawOp = {
-    op: string;
-    args?: Record<string, unknown>;
-    include?: Record<string, unknown>;
-    /** Remove named paths. Mutually exclusive with `pick` — the server 400s on both. */
-    omit?: readonly string[];
-    /** Keep only named paths. Mutually exclusive with `omit`. `_id` is always returned. */
-    pick?: readonly string[];
-} & ({
-    model: string;
-    namespace?: never;
-} | {
-    namespace: string;
-    model?: never;
-});
-export interface FoirClientConfig {
+import type { FoirDocumentPlan, FoirNamespaceSelections, FoirSelections, FoirSelectionUnions } from './document';
+import type { FoirSchemaDefinition } from './schema';
+import type { FoirSubjectRegistry } from './subjects';
+import type { FoirReconnectPolicy, FoirWebSocketFactory } from './ws-transport';
+/**
+ * `foir.generated.ts`, whole — the shape a namespace import of it has.
+ *
+ * ```ts
+ * import * as generated from './foir.generated';
+ * const foir = createFoirClient({ apiUrl, apiKey, generated });
+ * ```
+ *
+ * Every member is REQUIRED, and that is the point rather than an oversight.
+ * `foir types` emits all of them together and there is no case where a consumer
+ * wants a subset, so a module missing one is stale or hand-assembled — and the
+ * cost of accepting it quietly is the failure this type exists to stop:
+ * `foirSelections` once shipped in a shape the printer could not read, every
+ * call fell through to `GET /v1/manifest`, and nothing said so. A partial bundle
+ * is a compile error here and a refusal at construction, never a fallback.
+ *
+ * `foirSchemaType` is how `S` is inferred. A namespace import carries VALUES,
+ * and `FoirSchema` is an interface — it does not survive to runtime — so without
+ * a value whose TYPE is `FoirSchema` there would be nothing to infer from and
+ * every call site would go back to restating `createFoirClient<FoirSchema>`.
+ * 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;
+    /** `foirSelections` — one entry per model, in the printer's own input shape. */
+    readonly foirSelections: FoirSelections;
+    /** `foirNamespaceSelections` — the same, per namespace op. */
+    readonly foirNamespaceSelections: FoirNamespaceSelections;
+    /** `foirSelectionUnions` — each union expanded once; a tree references one by name. */
+    readonly foirSelectionUnions: FoirSelectionUnions;
+    /** Type carrier for `FoirSchema`. Never read: its runtime value is `undefined`. */
+    readonly foirSchemaType: S;
+}
+export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDefinition> {
     /**
      * Foir public API origin, e.g. `https://api.foir.dev`.
      *
      * A full GraphQL endpoint is accepted too — `PLATFORM_API_URL` is
      * conventionally `https://api.foir.dev/graphql` and people will paste it — so
-     * a trailing `/graphql` is stripped before `/v1/query` is appended.
+     * a trailing `/graphql` is stripped before a path is appended.
      */
     apiUrl: string;
     /** `pk_…` or `sk_…`. The manifest, and therefore the generated types, are shaped by it. */
@@ -53,6 +117,76 @@ export interface FoirClientConfig {
      * per-request; a bare string is used as-is.
      */
     bearerToken?: string | FoirTokenProvider;
+    /**
+     * The generated module, whole — **the documented way to wire a client**.
+     *
+     * ```ts
+     * import * as generated from './foir.generated';
+     * const foir = createFoirClient({ apiUrl, apiKey, generated });
+     * ```
+     *
+     * It supplies `schemaVersion`, `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.
+     *
+     * The four fields below still work and still win where both are given, so a
+     * client written against the older shape is untouched. What they cannot do is
+     * be individually forgotten: `foir types` emits all of them together, four out
+     * of five was always a mistake, and it used to degrade into a silent manifest
+     * fetch. Passing the module makes that a refusal instead.
+     *
+     * Omitting `generated` AND `selections` asks for the manifest fallback, which
+     * is supported, announced (see `announceManifestFallback`) and never reached
+     * by accident.
+     */
+    generated?: FoirGeneratedModule<S>;
+    /**
+     * The runtime half of `foir.generated.ts` — `foirSelections`, the resolved
+     * complete-by-default selection per model.
+     *
+     * Pass it, or pass `generated`, which carries it. Without either the client
+     * fetches `GET /v1/manifest` once at first use to get the same trees, which
+     * works and is the reason a zero-codegen start still functions, but it puts a
+     * round trip in front of the first query on every cold edge invocation to
+     * learn something the generated file already knows.
+     */
+    selections?: FoirSelections;
+    /**
+     * `foirNamespaceSelections` from the same generated module — the namespace
+     * half of the surface, one `payload` per namespace op.
+     *
+     * Read only when `selections` is passed; the manifest fallback carries both.
+     * Omitting it under `selections` makes every `foir.ns.*` call an error naming
+     * the namespace, which is the honest failure for a generated module that
+     * predates namespace payloads.
+     */
+    namespaceSelections?: FoirNamespaceSelections;
+    /** `foirSelectionUnions` from the same generated module. Required whenever a tree names a union. */
+    selectionUnions?: FoirSelectionUnions;
+    /**
+     * A registry that records which records this client fetched, so an annotation
+     * surface can anchor to the RECORD rather than to a URL or a CSS selector.
+     *
+     * ```ts
+     * const subjects = createFoirSubjectRegistry();
+     * const foir = createFoirClient({ apiUrl, apiKey, generated, subjects });
+     * ```
+     *
+     * There is no boolean to set. A registry is a list of what a page fetched,
+     * which is a disclosure surface — so it exists only when the host builds one,
+     * the host holds the only reference, and its lifetime is the host's. Omitting
+     * this field is the off state, and no other input reaches it.
+     *
+     * Build one per client, never at module scope: a shared registry on a
+     * multi-tenant edge worker is shared across tenants, for the same reason
+     * nothing else in this client keeps module-level state.
+     *
+     * `foir.raw()` does not record — a hand-written document has no published
+     * payload, so there are no record positions to read. Seed those with
+     * `subjects.add(...)`.
+     */
+    subjects?: FoirSubjectRegistry;
     /** Extra headers, applied last so they can override the ones above. */
     headers?: Readonly<Record<string, string>>;
     /**
@@ -69,13 +203,62 @@ export interface FoirClientConfig {
     /**
      * `foirSchemaVersion` from the generated module. When set, the client
      * compares it against the server's manifest once and warns on mismatch.
-     * Omitted — e.g. types generated as a bare `.d.ts` — disables the check.
+     * Carried by `generated`; set it here only to override that.
      */
     schemaVersion?: number;
     /** Set `false` to suppress the drift check even when `schemaVersion` is set. */
     checkSchemaDrift?: boolean;
     /** Called instead of `console.warn` when drift is detected. */
     onSchemaDrift?: (drift: FoirSchemaDrift) => void;
+    /**
+     * Set `false` to silence the one-line notice a client prints when it is built
+     * with neither `generated` nor `selections` and will therefore read its
+     * selection trees from `GET /v1/manifest`.
+     *
+     * The notice exists because the fallback is legitimate and expensive at the
+     * same time: it is what makes a zero-codegen start work, and it is also what a
+     * mis-wired generated module used to silently become. Announcing it is the
+     * difference between choosing it and landing in it.
+     */
+    announceManifestFallback?: boolean;
+    /**
+     * WebSocket endpoint. Defaults to `apiUrl` with the scheme swapped to `ws`
+     * and `/graphql/ws` appended, which is where the public API serves
+     * subscriptions. Override only for a proxy or a test server.
+     */
+    wsUrl?: string;
+    /**
+     * WebSocket constructor, called as `(url, protocols)`.
+     *
+     * Defaults to `globalThis.WebSocket`, which browsers, Deno, Bun, Cloudflare
+     * Workers and Node 22+ all provide. On Node 18/20 there is none, so pass one:
+     * `webSocketImpl: (url, p) => new WebSocket(url, p)` from the `ws` package.
+     */
+    webSocketImpl?: FoirWebSocketFactory;
+    /** How the subscription socket behaves when it drops. */
+    reconnect?: FoirReconnectPolicy;
+    /**
+     * Extra `connection_init` parameters, resolved on EVERY connect.
+     *
+     * A WebSocket handshake carries no headers a browser will let you set, so
+     * graphql-ws puts credentials in the `connection_init` payload — and this
+     * client builds that payload from the same `buildFoirHeaders` the HTTP
+     * transport uses, so `apiKey`, `bearerToken` and `headers` all reach the
+     * socket already. What none of them can do is carry a credential that is
+     * neither of the two the header builder knows about, resolved fresh.
+     *
+     * Both halves matter. `headers` is a static object captured when the client
+     * was constructed; a socket outlives a short-lived token, and a reconnect
+     * that replays a captured credential re-presents an expired one and fails to
+     * re-authenticate — on exactly the drop the reconnect logic exists to
+     * recover from. This is a function, called per connect, so the credential
+     * the socket presents is the one that is valid now.
+     *
+     * Merged LAST, so it wins over everything above it. Returning `{}` (or
+     * omitting the field) leaves the payload exactly as the header builder made
+     * it.
+     */
+    connectionParams?: () => Record<string, string> | Promise<Record<string, string>>;
 }
 export interface FoirSchemaDrift {
     /** Manifest version the local types were generated from. */
@@ -87,21 +270,56 @@ export interface FoirSchemaDrift {
 /**
  * Build a `/v1/...` URL from whatever the caller put in `apiUrl`.
  *
- * Tolerates the three things people actually pass: an origin, an origin with a
- * trailing slash, and the conventional `PLATFORM_API_URL` value
- * (`https://api.foir.dev/graphql`).
+ * The published name for `foirApiEndpoint`, which is where the implementation
+ * lives now that `@foir/sdk/server`'s events client needs the same tolerance for
+ * a `PLATFORM_API_URL` ending in `/graphql`. Kept as a named function rather
+ * 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>;
+/** Which GraphQL endpoint a call is sent to. */
+export type FoirLane = 'shared' | 'origin';
+/**
+ * Why a call did not take the shared lane. One name per condition the server's
+ * gate refuses on, so a decision can be asserted rather than inferred.
+ */
+export type FoirLaneReason = 'key' | 'bearer' | 'operation' | 'channel';
+export interface FoirRouteDecision {
+    lane: FoirLane;
+    /** Set only on the origin lane: the first condition that ruled the shared one out. */
+    reason?: FoirLaneReason;
+}
+export interface FoirRouteInput {
+    apiKey: string;
+    /** The RESOLVED bearer, not the provider — a provider that yields null is not a bearer. */
+    bearerToken?: string;
+    mutation: boolean;
+    channel?: 'published' | 'draft';
+}
 /**
- * Execute one op and return the single root field's value.
- *
- * The response is a normal GraphQL envelope keyed by the compiled document's
- * root field (`{"data":{"tillyBlocks":{…}}}`), and the client has no manifest at
- * runtime so it does not know that name. It does not need to: one op compiles
- * to exactly one root field, so "the only key of `data`" is unambiguous. A
- * response with a different number of keys means the server changed shape, and
- * guessing would be worse than saying so.
+ * Where this call goes.
+ *
+ * The first condition — that the credential is in the URL — needs no test here
+ * because this client always puts it there (`buildCdnUrl`); it is asserted on
+ * the built URL instead. The other four are decided below, in the order the
+ * server states them.
+ */
+export declare function foirRoute(input: FoirRouteInput): FoirRouteDecision;
+/**
+ * Execute a printed document and return the single root field's value.
+ *
+ * One op prints exactly one root field, and the plan says which — so unlike the
+ * JSON lane, which had to guess from "the only key of `data`", this reads the
+ * name it asked for. A response missing it means the server answered something
+ * else, and saying so beats returning `undefined`.
+ */
+export declare function executeFoirDocument<T>(config: FoirClientConfig, plan: FoirDocumentPlan): Promise<T>;
+/**
+ * Execute a hand-written document and return the whole `data` object.
+ *
+ * The escape hatch keeps the routing, the APQ handshake and the error shape;
+ * what it gives up is the single-root-field unwrapping, because a document
+ * written by hand may legitimately have several.
  */
-export declare function postFoirOp<T>(config: FoirClientConfig, body: FoirRawOp): Promise<T>;
+export declare function executeFoirRawDocument<T>(config: FoirClientConfig, document: string, mutation: boolean, variables?: Record<string, unknown>): Promise<T>;

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

@@ -0,0 +1,197 @@
+/**
+ * The graphql-ws transport — `@foir/sdk/data`'s second wire, beside the HTTP
+ * one.
+ *
+ * ---------------------------------------------------------------------------
+ * Why the protocol is implemented here rather than imported
+ * ---------------------------------------------------------------------------
+ *
+ * `graphql-ws` (the npm package) would do this, and `packages/shell` uses it.
+ * It is not used here for three reasons that are specific to this subpath:
+ *
+ *  1. `@foir/sdk/data` has exactly one runtime dependency and a build-time
+ *     assertion that nothing in its import graph reaches `graphql` or a Node
+ *     built-in. A second runtime dependency on this subpath is a real cost to
+ *     every storefront that installs it.
+ *  2. The protocol surface actually used is small and closed: `connection_init`
+ *     / `connection_ack`, `subscribe`, `next` / `error` / `complete`, `ping` /
+ *     `pong`. The server (`api-public/internal/ws`) implements exactly that
+ *     set and nothing else, so there is no negotiation to get wrong.
+ *  3. Reconnect-with-resubscribe has to be OURS regardless. A generic client
+ *     reconnects the socket; what a caller needs is their subscriptions still
+ *     running afterwards, which means replaying the subscribe frames — and
+ *     that bookkeeping is the part worth testing, not the framing.
+ *
+ * The wire is the standard `graphql-transport-ws` subprotocol either way, so a
+ * consumer who prefers the package can still talk to the same endpoint.
+ *
+ * ---------------------------------------------------------------------------
+ * Credentials
+ * ---------------------------------------------------------------------------
+ *
+ * A WebSocket handshake carries no request headers a browser will let you set,
+ * so graphql-ws puts credentials in the `connection_init` payload. This client
+ * builds that payload from `buildFoirHeaders` — the same function the HTTP
+ * transport builds its headers from — and drops only `Content-Type`, which
+ * means nothing on a socket. The server reads `x-api-key` and `Authorization`
+ * from those params under exactly those names, so the two surfaces authenticate
+ * with one builder rather than two spellings that can drift.
+ *
+ * A credential the header builder does not know about goes in
+ * `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.
+ */
+import { FoirRequestError } from '../transport/foir-http';
+import { type FoirClientConfig } from './transport';
+/**
+ * The slice of `WebSocket` this transport uses.
+ *
+ * Deliberately the event-handler PROPERTIES rather than `addEventListener`,
+ * because that is the intersection of the browser's `WebSocket`, Node's global
+ * one, and the `ws` package — so a consumer can pass any of the three without
+ * an adapter.
+ */
+export interface FoirWebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+}
+/** Constructs a socket. Matches `new WebSocket(url, protocols)`. */
+export type FoirWebSocketFactory = (url: string, protocols: string | string[]) => FoirWebSocketLike;
+/** How the transport behaves when the socket drops. */
+export interface FoirReconnectPolicy {
+    /**
+     * Attempts before giving up and reporting the failure to every live
+     * subscription. `Infinity` retries forever, which is the right default for a
+     * long-lived stream in a browser tab.
+     */
+    maxAttempts?: number;
+    /** Delay before the first retry. Doubles, capped at `maxDelayMs`. */
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    /**
+     * Random fraction of the delay added on each attempt, so a server restart
+     * does not bring every client back simultaneously. 0 disables it, which is
+     * what tests want and production does not.
+     */
+    jitter?: number;
+}
+/** A live subscription. Idempotent teardown. */
+export interface FoirSubscription {
+    unsubscribe(): void;
+}
+export interface FoirSubscriptionHandlers<T> {
+    /** One event. Called for every `next` frame the server pushes. */
+    onData: (value: T) => void;
+    /**
+     * A terminal error for THIS subscription: the server refused it, or the
+     * transport gave up reconnecting. Not called for a drop the transport
+     * recovers from — that is what `onReconnect` reports.
+     */
+    onError?: (error: FoirRequestError) => void;
+    /** The server ended the stream (an execution reached a terminal state). */
+    onComplete?: () => void;
+    /**
+     * The socket dropped and this subscription was re-established.
+     *
+     * Worth surfacing rather than hiding, because a subscription is not a
+     * durable log: events published while the socket was down were not buffered
+     * anywhere and are gone. A consumer that needs them refetches here. (The
+     * `events` subscription is the exception — it is cursor-resumable — and it is
+     * not one of the fields this client addresses.)
+     */
+    onReconnect?: () => void;
+}
+/** What to send in one `subscribe` frame. */
+export interface FoirSubscribeRequest {
+    query: string;
+    variables?: Record<string, unknown>;
+}
+/**
+ * Derive the WebSocket endpoint from the HTTP one.
+ *
+ * `apiUrl` is conventionally `https://api.foir.dev` or
+ * `https://api.foir.dev/graphql` — people paste whichever their env holds, and
+ * the HTTP transport already strips a trailing `/graphql` for the same reason.
+ * The socket lives at `/graphql/ws`, so this normalises to the origin and
+ * appends it.
+ */
+export declare function foirSocketEndpoint(apiUrl: string): string;
+/**
+ * The socket, its subscriptions, and the reconnect loop.
+ *
+ * One instance per client. It is lazy — nothing connects until the first
+ * `subscribe` — and it closes itself when the last subscription is dropped, so
+ * a client that is constructed and only used for queries never opens a socket.
+ */
+export declare class FoirSocketTransport {
+    private readonly config;
+    private readonly policy;
+    private readonly registrations;
+    private socket;
+    private acknowledged;
+    private connecting;
+    private attempt;
+    private nextId;
+    private disposed;
+    private keepAlive;
+    private retryTimer;
+    constructor(config: FoirClientConfig);
+    /**
+     * Start a subscription.
+     *
+     * Returns synchronously so a caller can hold the handle immediately, while
+     * the connect and the handshake proceed in the background. A subscription
+     * registered before the socket is acknowledged is sent the moment it is —
+     * which is the same path a reconnect takes, so the ordinary case and the
+     * recovery case exercise one piece of code.
+     */
+    subscribe<T>(request: FoirSubscribeRequest, handlers: FoirSubscriptionHandlers<T>): FoirSubscription;
+    /** Close the socket and drop every subscription. */
+    dispose(): void;
+    /** Live subscription count. Exposed for tests and diagnostics. */
+    get size(): number;
+    private ensureConnected;
+    private sendConnectionInit;
+    private handleClose;
+    private scheduleReconnect;
+    private teardownSocket;
+    private receive;
+    /**
+     * Send every registration the current socket has not yet been told about.
+     *
+     * This IS the resubscribe path. A reconnect clears `sent` on every
+     * registration and lands here, so a subscription re-established after a drop
+     * takes the same code as one opened for the first time — there is no second
+     * implementation that can be correct in one case and wrong in the other.
+     */
+    private flush;
+    private cancel;
+    /**
+     * Close the socket once nothing is using it.
+     *
+     * A socket held open with no subscriptions is a connection the server has to
+     * keep, a keepalive timer that keeps a serverless invocation alive, and
+     * nothing in return.
+     */
+    private closeIfIdle;
+    private failAll;
+    /**
+     * Client-side keepalive.
+     *
+     * The server pings on its own timer and this client answers, which is enough
+     * for the server to know the client is alive. This is the other direction:
+     * an idle subscription can sit for hours with no events, and a proxy that
+     * times out idle sockets will drop it. A periodic `ping` keeps it warm, and
+     * the pong that comes back proves the path is still there.
+     */
+    private startKeepAlive;
+    private send;
+}