@foir/sdk 0.9.0 → 0.11.0

package/dist/server/events-client.d.ts

@@ -1,6 +1,6 @@
 /**
  * `@foir/sdk/server`'s event-log client — cursor-resumable consumption of a
- * project's durable event history (TTS-983, epic TTS-912).
+ * project's durable event history.
  *
  * ```ts
  * import { createEventsClient } from '@foir/sdk/server';
@@ -21,7 +21,7 @@
  * OPERATOR SURFACE. This is not a customer-facing capability.
  * ---------------------------------------------------------------------------
  *
- * DECIDED 2026-08-04 (TTS-981). The event log is reachable by an `sk_` api key
+ * DECIDED 2026-08-04. The event log is reachable by an `sk_` api key
  * and by an admin session. It is NOT reachable by a customer token, there is no
  * customer lane for it on api-public, and a `pk_` key can never be minted
  * holding `events:list.project` at all.
@@ -73,6 +73,7 @@
  * needs. It also keeps this module `graphql`-free, like `@foir/sdk/data`.
  */
 import { FoirRequestError } from '../transport/foir-http';
+import { type FoirReconnectPolicy, type FoirSubscription, type FoirSubscriptionHandlers, type FoirWebSocketFactory } from '../data/ws-transport';
 /** The path `GET /v1/events` is mounted on, inside api-public's api-key group. */
 export declare const FOIR_EVENTS_PATH = "/v1/events";
 /**
@@ -109,7 +110,10 @@ export interface FoirEvent {
      * comparing, never for counting.
      */
     seq: number;
-    /** The registry name, e.g. `"record.created"`. */
+    /**
+     * The registry name, e.g. `"RECORD_CREATED"`. SCREAMING_SNAKE, never the
+     * dotted form.
+     */
     event: string;
     /**
      * The event's own flat keys, plus `state` and `stateSchema`.
@@ -171,7 +175,9 @@ export interface FoirEventsListParams {
     /** Page size. The server defaults to 100 and caps at 1000. */
     limit?: number;
     /**
-     * Filter by event name, e.g. `['record.created', 'record.updated']`. Omit for
+     * Filter by event name, e.g. `['RECORD_CREATED', 'RECORD_UPDATED']`.
+     * SCREAMING_SNAKE: a name in any other casing matches nothing and comes back
+     * as an empty page rather than an error, so a wrong spelling is silent. Omit for
      * every event.
      */
     events?: readonly string[];
@@ -213,6 +219,21 @@ export interface FoirEventsClientConfig {
      * cannot be clobbered by accident.
      */
     requestInit?: Omit<RequestInit, 'method' | 'headers' | 'body'>;
+    /**
+     * Override the WebSocket endpoint `subscribe()` connects to. Normally derived
+     * from `apiUrl`; set it when the socket is not on the API origin.
+     */
+    wsUrl?: string;
+    /**
+     * WebSocket constructor, called as `(url, protocols)`. Defaults to
+     * `globalThis.WebSocket`. Node 18/20 have no global one, so a server process
+     * on those versions passes the `ws` package's.
+     *
+     * Only `subscribe()` uses it; `list()` and `stream()` are plain fetch.
+     */
+    webSocketImpl?: FoirWebSocketFactory;
+    /** How the `subscribe()` socket behaves when it drops. */
+    reconnect?: FoirReconnectPolicy;
 }
 export interface FoirEventsClient {
     /** One page of the project's event history. */
@@ -227,6 +248,35 @@ export interface FoirEventsClient {
      * including mid-page after a crash.
      */
     stream(params?: FoirEventsStreamParams): AsyncGenerator<FoirEvent, void, void>;
+    /**
+     * The same cursor, pushed instead of pulled.
+     *
+     * The server backfills from `after` and then continues live on ONE stream, so
+     * there is no gap between catching up and keeping up and no second code path
+     * to write. `stream()` remains the right choice for a batch job that wants to
+     * drain and exit; this is for a process that stays open.
+     *
+     * The cursor advances as events arrive, so a dropped socket resumes from the
+     * last event delivered rather than replaying from where the subscription
+     * originally started.
+     *
+     * A cursor older than the retention window ends the subscription with a
+     * {@link FoirEventCursorExpiredError} carrying `resumeFrom`, exactly as the
+     * HTTP lane answers 410 — a gap is always something a consumer is told about,
+     * never something it has to notice.
+     */
+    subscribe(params: FoirEventsSubscribeParams): FoirSubscription;
+}
+export interface FoirEventsSubscribeParams extends FoirSubscriptionHandlers<FoirEvent> {
+    /**
+     * Exclusive cursor: begin with events having `seq > after`. Omit to start
+     * from the live edge rather than the oldest retained event — a long-running
+     * consumer that has no checkpoint usually wants what happens next, not the
+     * whole window.
+     */
+    after?: number;
+    /** Filter by event name. Omit for every event. */
+    events?: readonly string[];
 }
 /**
  * The cursor named a position older than the retention window, so events the

package/dist/server/index.d.ts

@@ -2,11 +2,13 @@ export { createServerClient, ServerClientError } from './server-client';
 export { verifyWebhookSignature } from './webhook-helpers';
 export { verifyScopedToken, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, type ScopedTokenClaims, type ScopedTokenSubject, type VerifyScopedTokenOptions, } from './verify-scoped-token';
 export { requireScopedToken, ScopedTokenError, type RequireScopedTokenOptions, type ScopedTokenIngress, } from './require-scoped-token';
+export { readDispatch, OperationPayloadError, type BodyCarrier, } from './read-dispatch';
 export type { ServerClient, ServerClientOptions, GraphQLResponse, EditorPlacement, } from './types';
 export type { OperationPayload, OperationTrigger, OperationRecordContext, OperationContext, OperationResult, OperationCallback, } from './operation-types';
 export { createCallbackClient } from './callback-client';
 export type { CallbackClient, CallbackResult } from './callback-client';
 export { createEventsClient, FoirEventCursorExpiredError, isFoirEventCursorExpired, FOIR_EVENTS_PATH, FOIR_EVENTS_SCOPE, FOIR_EVENTS_RETENTION_DAYS, } from './events-client';
-export type { FoirEvent, FoirEventActor, FoirEventPage, FoirEventRetention, FoirEventsClient, FoirEventsClientConfig, FoirEventsListParams, FoirEventsStreamParams, } from './events-client';
+export type { FoirEvent, FoirEventActor, FoirEventPage, FoirEventRetention, FoirEventsClient, FoirEventsClientConfig, FoirEventsListParams, FoirEventsStreamParams, FoirEventsSubscribeParams, } from './events-client';
+export type { FoirSubscription, FoirSubscriptionHandlers } from '../data/ws-transport';
 export { FoirRequestError, isFoirForbidden, isFoirNotFound, isFoirRateLimited, isFoirUnauthenticated, } from '../transport/foir-http';
-export type { FoirErrorCode, FoirErrorExtensions, FoirGraphQLErrorItem } from '../transport/foir-http';
+export type { FoirErrorCode, FoirErrorExtensions, FoirGraphQLErrorItem, FoirAuthDowngrade, } from '../transport/foir-http';

package/dist/server/operation-types.d.ts

@@ -1,41 +1,70 @@
 /**
  * Type definitions for platform operations.
  *
- * These types match the platform's operation execution payload structure.
+ * `OperationPayload` is the body the platform POSTs to an operation endpoint,
+ * field for field. It is written against the worker that builds it
+ * (`buildOperationPayload` in the platform's operation processor), not against
+ * what an endpoint might like to receive: every field here is one the platform
+ * sends, present exactly when the platform sends it. A field the platform does
+ * not send is not here, because a type that promises one is how an endpoint
+ * comes to read `undefined` and refuse every call.
+ *
+ * Read it with `readDispatch(request)`, which parses and checks the body into
+ * this type.
  */
 /**
- * Operation payload sent by the platform to extension endpoints.
+ * The body the platform sends an operation endpoint.
+ *
+ * The same shape however the run was started (a person in the console, an
+ * `execute<Op>` call, a lifecycle hook, a schedule) and whichever way it is
+ * delivered (to the registered endpoint, or down `foir operations dev` to one
+ * on your machine).
  *
- * All operations receive this standardized payload structure regardless
- * of how they're triggered (UI, API, lifecycle hook, schedule).
+ * `TInput` types `input`. It is an assertion, not a check: the platform
+ * validates `input` against the operation's input schema before dispatching,
+ * and this parameter lets the endpoint say what that schema is.
  */
-export interface OperationPayload {
-    /** Execution id — present so the extension can include it in callbacks. */
-    executionId?: string;
-    /** Unique key identifying this operation (e.g., 'tilly-process-note') */
+export interface OperationPayload<TInput extends object = Record<string, unknown>> {
+    /** The run. Always present; quote it in a callback and in your own logs. */
+    executionId: string;
+    /** The key of the operation being run, e.g. `send_quote`. */
     operationKey: string;
-    /** How this operation was triggered */
+    /** How the run was started. */
     trigger: OperationTrigger;
-    /** Input data provided by the caller */
-    input: Record<string, unknown>;
-    /** Content/field value (for field-triggered operations) */
-    content: unknown;
-    /** Record context (if operation was triggered by a record event) */
-    record: OperationRecordContext | null;
-    /** Platform context (tenant, project, user, locale) */
+    /**
+     * What the caller passed as the operation's input. Always an object:
+     * `readDispatch` reads a run started with no input (a schedule that declares
+     * none, which the platform serialises as `null`) as `{}`.
+     */
+    input: TInput;
+    /** The tenant, project and principal the run belongs to. */
     context: OperationContext;
-    /** Extension credentials (auto-injected by platform) */
-    credentials?: Record<string, unknown>;
-    /** Extension config (auto-injected by platform) */
-    config?: Record<string, unknown>;
     /**
-     * Async-callback dispatch metadata. Present iff the operation was
-     * dispatched in `async-callback` mode. Contains the scoped token, the
-     * api-public GraphQL endpoint, and the per-op typed mutation names the
-     * extension should call back to.
+     * The content block the caller attached when it started the run, forwarded
+     * as the caller wrote it. Absent when there was none, which is every run
+     * started by a hook, a schedule or `execute<Op>`.
+     */
+    content?: Record<string, unknown>;
+    /**
+     * The record block the caller attached when it started the run, forwarded
+     * as the caller wrote it. Absent when there was none. For a record event,
+     * the record's id arrives in `input` (for example `input.recordId`), not
+     * here: read the record back as the operation when you need its content.
+     */
+    record?: OperationRecordContext;
+    /**
+     * Caller-supplied context about where the run was started from, forwarded as
+     * written. Absent when there was none.
+     */
+    triggerContext?: Record<string, unknown>;
+    /**
+     * Where and how to report back. Present only when the run was dispatched in
+     * ASYNC mode: the endpoint answers `202 Accepted` and reports the outcome
+     * later through this block (see `createCallbackClient`).
      *
-     * Absent for SYNC operations — the extension returns its result in the
-     * HTTP response body and there's nothing to call back to.
+     * Absent in the blocking (SYNC) mode. A blocking run has no callback path:
+     * the endpoint's response body is the result. Branch on this field being
+     * present to tell the two modes apart.
      */
     callback?: OperationCallback;
 }
@@ -61,53 +90,52 @@ export interface OperationCallback {
         progress: string;
         cancel: string;
     };
+    /**
+     * The operation keys that led to this run, its own last. Present when the
+     * run was caused by another operation's work.
+     */
+    causationChain?: string[];
 }
 /**
- * Trigger information describing how the operation was invoked.
+ * How a run was started. The four values are the platform's own; a caller that
+ * names none is recorded as `api`.
+ *
+ * - `ui`: a console surface that names itself as the trigger, such as an app's
+ *   configure page.
+ * - `api`: an `execute<Op>` call, or any caller that named no trigger.
+ * - `lifecycle`: a hook on a platform event (a record published, an operation
+ *   completed).
+ * - `schedule`: a cron schedule firing.
  */
 export interface OperationTrigger {
-    /** Trigger type */
-    type: 'ui' | 'api' | 'lifecycle' | 'field';
-    /** Field key (for field-triggered operations) */
-    fieldKey?: string;
-    /** Field type (for field-triggered operations) */
-    fieldType?: string;
+    type: 'ui' | 'api' | 'lifecycle' | 'schedule';
 }
 /**
- * Record context provided when operation is triggered by a record event.
+ * The record block a caller attached to a run, forwarded as the caller wrote
+ * it. The platform does not shape it, so neither does this type.
  */
-export interface OperationRecordContext {
-    /** Record ID */
-    id: string;
-    /** Model key (e.g., 'tilly_note') */
-    modelKey: string;
-    /** Version ID (if versioned record) */
-    versionId?: string;
-    /** Record content/data */
-    data: Record<string, unknown>;
-    /** Record metadata */
-    metadata: {
-        /** Natural key (slug, handle, etc.) */
-        naturalKey?: string;
-        /** Additional metadata fields */
-        [key: string]: unknown;
-    };
-}
+export type OperationRecordContext = Record<string, unknown>;
 /**
- * Platform context provided to all operations.
+ * The tenant, project and principal a run belongs to.
  */
 export interface OperationContext {
     /** Tenant ID */
     tenantId: string;
     /** Project ID */
     projectId: string;
-    /** User ID (if user-triggered) */
-    userId?: string;
-    /** Customer ID (if customer-scoped operation) */
+    /**
+     * The principal that started the run. Always present, and the empty string
+     * when the run has none, as a hook's run does.
+     */
+    userId: string;
+    /**
+     * The customer the run acts for, when it acts for one: the signed-in
+     * customer who ran it, or the owner of the record whose event fired the
+     * hook. The dispatch token carries the same customer, so a client built from
+     * it acts for them too.
+     */
     customerId?: string;
-    /** Locale code (if locale-specific) */
-    locale?: string;
-    /** Timestamp when operation was triggered */
+    /** When the platform built this body, RFC 3339 in UTC to the second. */
     timestamp: string;
 }
 /**

package/dist/server/read-dispatch.d.ts

@@ -0,0 +1,53 @@
+/**
+ * readDispatch: the body of an operation dispatch, parsed and checked.
+ *
+ * An operation endpoint is handed two things. The headers carry the dispatch
+ * token, which `requireScopedToken` verifies. The body carries the run: its id,
+ * the operation's key, how it was started, the context it runs in, and the
+ * caller's input under `input`. Reading the body as though it WERE the input is
+ * the mistake this exists to prevent, because it fails quietly: every field the
+ * endpoint looks for is absent, and the endpoint refuses every call on a
+ * missing field it was in fact sent.
+ *
+ * ```ts
+ * const { dispatch } = await requireScopedToken(request, { expectedProjectId });
+ * const { input, context } = await readDispatch<{ email: string }>(request);
+ * const foir = createFoirClient({ apiUrl, dispatch, generated });
+ * ```
+ *
+ * The shape is the platform's `buildOperationPayload`, field for field; see
+ * `OperationPayload`. A body that is not that shape is refused with
+ * {@link OperationPayloadError}, naming what is wrong, rather than handed on
+ * half-read.
+ *
+ * What it does not do is drop fields. A key the platform adds later is kept on
+ * the returned object, untyped, because a reader that re-built the body from
+ * the fields it knows would delete whatever it did not, which is the exact way
+ * blocks of this payload have gone missing on their way to an endpoint before.
+ */
+import type { OperationPayload } from './operation-types';
+/**
+ * The dispatch body was not an operation payload. `status` is the HTTP status
+ * the route should answer with: 400, since the request is malformed rather than
+ * unauthorised (the token has already been verified by the time the body is
+ * read).
+ */
+export declare class OperationPayloadError extends Error {
+    readonly status: 400;
+    constructor(message: string);
+}
+/** The minimal request shape needed: satisfied by any fetch-API Request. */
+export interface BodyCarrier {
+    text(): Promise<string>;
+}
+/**
+ * Read the dispatch body off an operation request.
+ *
+ * `TInput` types `input`, as an assertion: the platform has already checked the
+ * input against the operation's input schema, and this is where the endpoint
+ * says what that schema is.
+ *
+ * Reads the body, so call it once per request and after nothing else has
+ * consumed it.
+ */
+export declare function readDispatch<TInput extends object = Record<string, unknown>>(request: BodyCarrier): Promise<OperationPayload<TInput>>;

package/dist/server/require-scoped-token.d.ts

@@ -1,6 +1,6 @@
 /**
  * requireScopedToken — the one-line ingress guard for BFF routes the
- * platform dispatches operations to (EID-498).
+ * platform dispatches operations to.
  *
  * Operation endpoints must be publicly reachable (the platform's dispatcher
  * refuses private networks), so "the BFF is never public-facing" is achieved
@@ -16,6 +16,17 @@
  * });
  * ```
  *
+ * The verified token is also the endpoint's credential for calling Foir back.
+ * `dispatch` on the result is the token as a data-client credential, so the
+ * endpoint acts as the operation, with the capabilities the operation
+ * declared, and holds no key of its own. `generated` is the module
+ * `foir types --operation <key>` wrote for the operation:
+ *
+ * ```ts
+ * const { dispatch } = await requireScopedToken(request, { expectedProjectId });
+ * const foir = createFoirClient({ apiUrl: env.PLATFORM_API_URL, dispatch, generated });
+ * ```
+ *
  * Throws {@link ScopedTokenError} with `status` 401 (missing/invalid token)
  * or 403 (valid token for the wrong tenant/project) — map it to a response
  * in one place:
@@ -30,6 +41,7 @@
  * ```
  */
 import type { ScopedTokenClaims, ScopedTokenSubject, VerifyScopedTokenOptions } from './verify-scoped-token';
+import type { FoirDispatchCredential } from '../data/transport';
 /**
  * Verification failure with the HTTP status the route should answer with:
  * 401 for a missing or invalid token, 403 for a valid token bound to the
@@ -66,6 +78,13 @@ export interface ScopedTokenIngress {
     subject: ScopedTokenSubject;
     /** Parsed `X-Foir-Context` correlation metadata (empty when absent). */
     context: Record<string, string>;
+    /**
+     * The token this call verified, as the credential for a data client that
+     * calls Foir AS the operation:
+     * `createFoirClient({ apiUrl, dispatch, generated })`. It sends the token as
+     * `X-Foir-Token` with the dispatch's `X-Foir-Context`, and never an api key.
+     */
+    dispatch: FoirDispatchCredential;
 }
 /**
  * Verify the platform-minted scoped token on an inbound dispatch request.