@foir/sdk 0.7.0 → 0.9.0

package/dist/data/subscription-document.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Printing a subscription document from a resolved selection tree.
+ *
+ * ---------------------------------------------------------------------------
+ * Why this file is thin
+ * ---------------------------------------------------------------------------
+ *
+ * The body of a subscription document is a selection body like any other, and
+ * `document.ts` already walks one: relations skipped, `truncated` degraded to
+ * `__typename`, unions expanded to `__typename` plus an inline fragment per
+ * member, aliases printed as `alias: key`. Those rules belong to the tree, not
+ * to the operation type, so this file does NOT re-implement them — it calls
+ * `printFoirSelectionBody` and adds only what is genuinely different about a
+ * subscription: the `subscription` keyword, the variable declarations, and the
+ * single root field.
+ *
+ * That split is deliberate. This file previously carried its own copy of the
+ * walk, written before `document.ts` existed; two implementations of one rule
+ * set in one directory is the parallel construction this epic exists to remove,
+ * and the copy would have been correct only until the next rule changed.
+ *
+ * Nothing here inspects a GraphQL type, and nothing here may start to. The
+ * server resolves the tree once per schema version — unions expanded, aliases
+ * assigned, cycles broken, budget counted — so printing is string building. If
+ * this ever needs to know what a field IS, the tree is under-specified and the
+ * fix belongs in the manifest.
+ *
+ * ---------------------------------------------------------------------------
+ * Why it is not APQ
+ * ---------------------------------------------------------------------------
+ *
+ * The HTTP lane hashes its document and sends the hash, because it re-sends the
+ * same document on every request. graphql-ws sends the document ONCE, in the
+ * `subscribe` frame, and the server then pushes events over it for the life of
+ * the subscription. The wire-cost argument does not apply to a stream, so the
+ * document goes whole and the server needs no registry to serve it.
+ */
+import { type FoirSelectionUnions } from './document';
+import type { FoirManifestSelection } from './manifest';
+/**
+ * One argument a subscription root field is called with, bound to a variable.
+ *
+ * Variables rather than inline literals because the values are caller data:
+ * inlining would mean escaping a string into a document, which is the one place
+ * a client can construct an injection. The `subscribe` frame carries a
+ * `variables` object beside the query, so there is no reason to inline.
+ */
+export interface FoirSubscriptionArgument {
+    /** Argument name, e.g. `modelKey`. */
+    name: string;
+    /** GraphQL type for the variable declaration, e.g. `String!`. */
+    type: string;
+}
+export interface PrintSubscriptionDocumentInput {
+    /** The Subscription root field to select. */
+    field: string;
+    /** Operation name, for readability in server logs and dev tools. */
+    operationName: string;
+    /** Arguments the field takes, in the order they should be declared. */
+    args?: readonly FoirSubscriptionArgument[];
+    /** The payload's resolved selection. */
+    selection: FoirManifestSelection;
+    /** Union expansions the selection references by name. */
+    unions?: FoirSelectionUnions;
+}
+/**
+ * Print a complete subscription document.
+ *
+ * Deterministic: the same inputs always produce the same bytes, because the
+ * server sorts union members and emits fields in a stable order. That matters
+ * for readable diffs in tests and for anything that ever wants to recognise a
+ * document, and it costs nothing to preserve — so this must never reorder
+ * anything it is handed.
+ */
+export declare function printSubscriptionDocument(input: PrintSubscriptionDocumentInput): string;

package/dist/data/subscriptions.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Subscription addressing — the five Subscription root fields, reached through
+ * the client shape that already exists.
+ *
+ * ```ts
+ * const live = foir.page.onChange({ onData: (e) => revalidate(e.recordId) });
+ * const inbox = foir.ns.notifications.onNotification({ onData: show });
+ * const run = foir.ns.operations.onExecution({ id, onData: render });
+ * live.unsubscribe();
+ * ```
+ *
+ * ---------------------------------------------------------------------------
+ * Why the addressing is what it is
+ * ---------------------------------------------------------------------------
+ *
+ * `recordChanged` takes the model as an ARGUMENT, and the argument is exactly
+ * what the client's model accessor already carries — `foir.page` IS
+ * `modelKey: "page"`. So it hangs off the model, and the one argument the
+ * server gates on is supplied by the address rather than by the caller. That is
+ * also why a model the credential may not watch is a compile-time absence
+ * rather than a runtime refusal: it is not in `FoirSchema`.
+ *
+ * The other four are project-independent platform surfaces, so they hang off
+ * the namespace that owns them: `notification` under `notifications`,
+ * `jobProgress` and both execution streams under `operations`.
+ *
+ * Every subscription method is named `on…`, so a call site that opens a stream
+ * is distinguishable at a glance from one that awaits a value — and no
+ * generated op name can collide, because the server never emits a root field
+ * called `on…`.
+ *
+ * ---------------------------------------------------------------------------
+ * Where the document comes from
+ * ---------------------------------------------------------------------------
+ *
+ * From `GET /v1/manifest`, through the CLIENT's memoised loader — the same one
+ * the query path falls back to and the drift check reads. Each subscription
+ * carries a resolved selection tree, which `subscription-document.ts` prints
+ * with the same walk the query path prints models with.
+ *
+ * A subscribing client therefore fetches the descriptor once even when
+ * `config.selections` was supplied, because `selections` carries MODEL trees and
+ * nothing generates subscription ones yet. That is a real cost and it is stated
+ * rather than hidden — but it is ONE fetch, memoised across every subscription
+ * and shared with the query path, sitting behind a long-lived socket. `client.ts`
+ * rejects a round trip in front of every query for good reason; in front of a
+ * socket that will live for minutes it is noise.
+ */
+import type { FoirManifest } from './manifest';
+import type { FoirClientConfig } from './transport';
+import { type FoirSubscription, type FoirSubscriptionHandlers } from './ws-transport';
+/** `recordChanged` — a record in one model was created, updated or removed. */
+export interface FoirRecordChangedEvent {
+    recordId: string;
+    modelKey: string;
+    /** `created`, `updated`, `published`, `unpublished` or `deleted`. */
+    action: string;
+    /** Actor, when a user made the change. Absent for system and service callers. */
+    userId?: string | null;
+    /** The durable event this projects — the same id a webhook delivery carries. */
+    eventId?: string | null;
+    /** Event family name, e.g. `RECORD_UPDATED`. The name a hook subscribes to. */
+    event?: string | null;
+    /**
+     * Platform sequence, assigned in commit order and monotonic per project.
+     * Apply last-write-wins: keep the highest seq applied per record and discard
+     * anything at or below it.
+     */
+    seq?: number | null;
+}
+/** `notification` — one notification for the subscribing user. */
+export interface FoirNotificationEvent {
+    userId: string;
+    /** `notification`, `announcement` or `mention`. */
+    type: string;
+    title?: string | null;
+}
+/** `jobProgress` — a background job's lifecycle. */
+export interface FoirJobProgressEvent {
+    jobId: string;
+    queue?: string | null;
+    /** `started`, `progress`, `completed` or `failed`. */
+    status: string;
+    /** 0-100 when reported. */
+    progress?: number | null;
+    error?: string | null;
+}
+/** `operationExecution` / `operation{Op}Execution` — one execution's progress. */
+export interface FoirOperationExecutionEvent {
+    id: string;
+    /** `pending`, `dispatched`, `running`, `completed`, `failed`, `cancelled` or `timed_out`. */
+    status: string;
+    /** 0-100; null on terminal events. */
+    progressPct?: number | null;
+    progressMessage?: string | null;
+    progressMetadata?: unknown;
+    progressUpdatedAt?: string | null;
+    /** Present on `status: completed`. Typed per operation only on the typed field. */
+    resultJson?: unknown;
+    /** Present on `status: failed` or `timed_out`. */
+    errorJson?: unknown;
+}
+/** Options for `foir.ns.operations.onExecution`. */
+export type FoirExecutionSubscribeOptions = FoirSubscriptionHandlers<FoirOperationExecutionEvent> & {
+    /** Execution id, as returned by `execute<Op>`. */
+    id: string;
+    /**
+     * Operation key, to subscribe to that operation's TYPED stream
+     * (`operation{Op}Execution`) instead of the generic one.
+     *
+     * The key is matched against the field names the manifest publishes rather
+     * than converted into one: the server owns the PascalCase rule, and
+     * re-deriving it here is the naming drift the SDK contract forbids. An
+     * operation with no typed subscription fails with the list of fields that do
+     * exist, rather than silently opening the generic stream under a name the
+     * caller did not ask for.
+     */
+    operation?: string;
+};
+/** The subscriptions a model accessor carries. */
+export interface FoirModelSubscriptions {
+    /**
+     * Stream changes to this model's records.
+     *
+     * The socket refuses a model this credential may not read, but the model is
+     * not in `FoirSchema` in that case, so the refusal is a type error first.
+     */
+    onChange(handlers: FoirSubscriptionHandlers<FoirRecordChangedEvent>): FoirSubscription;
+}
+/**
+ * The subscriptions one namespace carries, by name.
+ *
+ * Keyed on the namespace NAME rather than added to every namespace, because
+ * `foir.ns.search.onNotification` should not type-check. The empty branch is
+ * what every other namespace gets.
+ */
+export type FoirNamespaceSubscriptions<NK> = NK extends 'notifications' ? {
+    /** Stream this caller's own notifications. Scoped server-side; no arguments. */
+    onNotification(handlers: FoirSubscriptionHandlers<FoirNotificationEvent>): FoirSubscription;
+} : NK extends 'operations' ? {
+    /** Stream background-job lifecycle events for this project. */
+    onJobProgress(handlers: FoirSubscriptionHandlers<FoirJobProgressEvent>): FoirSubscription;
+    /** Stream one operation execution's progress until it reaches a terminal state. */
+    onExecution(options: FoirExecutionSubscribeOptions): FoirSubscription;
+} : {};
+/** Does this (address, property) pair name a subscription rather than an op? */
+export declare function isModelSubscriptionMethod(name: string): boolean;
+export declare function isNamespaceSubscriptionMethod(namespace: string, name: string): boolean;
+/**
+ * The runtime half: resolves a call site to a route, prints its document from
+ * the manifest, and hands it to the socket.
+ *
+ * One instance per client, created lazily — a client that never subscribes
+ * neither fetches a manifest nor opens a socket.
+ */
+export declare class FoirSubscriptionRouter {
+    private readonly transport;
+    private readonly loadManifest;
+    /**
+     * `loadManifest` is the client's own memoised descriptor loader, passed in
+     * rather than rebuilt. One client is one credential and one descriptor; a
+     * fetcher of our own would race the query path's for the same bytes and could
+     * end up holding a different schema version than the documents the query path
+     * is printing from.
+     */
+    constructor(config: FoirClientConfig, loadManifest: () => Promise<FoirManifest>);
+    dispose(): void;
+    /** `foir.<model>.onChange(...)`. */
+    model(modelKey: string, method: string, input: Record<string, unknown>): FoirSubscription;
+    /** `foir.ns.<namespace>.on…(...)`. */
+    namespace(namespace: string, method: string, input: Record<string, unknown>): FoirSubscription;
+    /**
+     * Resolve the route's document and subscribe.
+     *
+     * The handle is returned synchronously and the manifest fetch runs behind it,
+     * so a caller can hold and cancel a subscription before the descriptor has
+     * arrived. Cancelling in that window is honoured: `cancelled` is checked
+     * after the await, and the inner handle is never created.
+     */
+    private open;
+}

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>;