@foir/sdk 0.8.0 → 0.10.0

package/dist/data/schema.d.ts

@@ -2,7 +2,7 @@
  * THE `FoirSchema` CONTRACT.
  *
  * `createFoirClient<FoirSchema>()` is parameterised by a type that `foir types`
- * (TTS-875) emits from `GET /v1/manifest`. This file is that contract: the
+ * emits from `GET /v1/manifest`. This file is that contract: the
  * shape the generator writes and the shape the client reads. It is the only
  * coupling between the two, so it is written down here rather than living in
  * the generator's head.
@@ -161,7 +161,7 @@
  * 8. **`raw` and `ns` are reserved top-level names.** They are the escape hatch
  *    and the namespace accessor on the client object. A model whose key is
  *    `raw` or `ns` would collide; the server should reject those model keys at
- *    create time (noted in TTS-868's "Known limits").
+ *    create time (a known limit).
  *
  * 9. **`models` and `namespaces` must be object type LITERALS, not named
  *    `interface`s.** TypeScript gives an implicit index signature to object

package/dist/data/subscriptions.d.ts

@@ -38,13 +38,17 @@
  * 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.
+ * A client built with `foirSubscriptions` makes no request at all: `client.ts`
+ * hands this an already-resolved descriptor instead of the fetcher, and the
+ * printer cannot tell the difference — it is the same shape either way, which is
+ * why nothing in this file changed when that landed.
+ *
+ * Without them it fetches once, which is what every client did before `foir
+ * types` emitted subscription trees and what a module generated before that
+ * still does. 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';
@@ -88,8 +92,12 @@ export interface FoirJobProgressEvent {
 /** `operationExecution` / `operation{Op}Execution` — one execution's progress. */
 export interface FoirOperationExecutionEvent {
     id: string;
-    /** `pending`, `dispatched`, `running`, `completed`, `failed`, `cancelled` or `timed_out`. */
-    status: string;
+    /**
+     * The same spelling `operationExecution` and `operationExecutions` return for
+     * the run, so one comparison serves a read and an event. The socket carries
+     * the platform's lowercase value; this client hands it over as the enum name.
+     */
+    status: 'PENDING' | 'DISPATCHED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMED_OUT';
     /** 0-100; null on terminal events. */
     progressPct?: number | null;
     progressMessage?: string | null;
@@ -117,6 +125,24 @@ export type FoirExecutionSubscribeOptions = FoirSubscriptionHandlers<FoirOperati
      */
     operation?: string;
 };
+/**
+ * What `onChange` takes: the handlers, plus the optional resume cursor.
+ *
+ * `after` is the highest `seq` this consumer has already applied. Passing it
+ * makes the stream cursor-resumable — the server replays what came after it
+ * from the durable log before continuing live, so a message lost anywhere
+ * upstream is repaired by the next connect rather than left as a permanently
+ * stale cache entry. Omitting it is the stream as it has always been: live from
+ * the moment you connect.
+ *
+ * The two refusals it can produce — a cursor older than the retention window,
+ * or one further behind than the surface will page — arrive on `onError` with a
+ * machine-readable code, and both mean the cache must be thrown away rather
+ * than partially repaired. `@foir/sdk/live` classifies them.
+ */
+export type FoirChangeSubscribeOptions = FoirSubscriptionHandlers<FoirRecordChangedEvent> & {
+    after?: number;
+};
 /** The subscriptions a model accessor carries. */
 export interface FoirModelSubscriptions {
     /**
@@ -125,7 +151,7 @@ export interface FoirModelSubscriptions {
      * 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;
+    onChange(options: FoirChangeSubscribeOptions): FoirSubscription;
 }
 /**
  * The subscriptions one namespace carries, by name.

package/dist/data/transport.d.ts

@@ -55,10 +55,11 @@
  * with more force here — this client is per-credential, so anything cached
  * across instances is cached across tenants.
  */
-import { type FoirTokenProvider } from '../transport/foir-http';
+import { FoirRequestError, type FoirTokenProvider } from '../transport/foir-http';
 import type { FoirDocumentPlan, FoirNamespaceSelections, FoirSelections, FoirSelectionUnions } from './document';
 import type { FoirSchemaDefinition } from './schema';
 import type { FoirSubjectRegistry } from './subjects';
+import type { FoirManifestSubscription } from './manifest';
 import type { FoirReconnectPolicy, FoirWebSocketFactory } from './ws-transport';
 /**
  * `foir.generated.ts`, whole — the shape a namespace import of it has.
@@ -91,6 +92,19 @@ export interface FoirGeneratedModule<S extends FoirSchemaDefinition = FoirSchema
     readonly foirNamespaceSelections: FoirNamespaceSelections;
     /** `foirSelectionUnions` — each union expanded once; a tree references one by name. */
     readonly foirSelectionUnions: FoirSelectionUnions;
+    /**
+     * `foirSubscriptions` — the Subscription root fields this credential reaches,
+     * with their resolved payload selections. Lets a subscribing client print its
+     * document from the module instead of fetching `GET /v1/manifest`.
+     *
+     * OPTIONAL, and deliberately not in `GENERATED_EXPORTS`. That list is checked
+     * strictly — a module missing any of it is refused as stale or hand-assembled
+     * — so requiring this one would break every client built against a module
+     * generated before it existed, at construction, for a round trip they were
+     * already happily paying. Absent means "fetch the manifest", which is exactly
+     * what those clients do today.
+     */
+    readonly foirSubscriptions?: readonly FoirManifestSubscription[];
     /** Type carrier for `FoirSchema`. Never read: its runtime value is `undefined`. */
     readonly foirSchemaType: S;
 }
@@ -117,6 +131,41 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * per-request; a bare string is used as-is.
      */
     bearerToken?: string | FoirTokenProvider;
+    /**
+     * The organization every request from this client acts in, sent as
+     * `X-Org-Id`.
+     *
+     * For the PROJECT credential of a product built on organizations: the
+     * back-office, or the multi-tenant app that has just resolved
+     * `<sub>.theapp.com` to an organization and now acts inside it. The server
+     * resolves the id against the credential's OWN project — an unknown,
+     * suspended or another project's organization all answer `NOT_FOUND`, so
+     * nothing enumerates — and binds the request to it: reads are confined to
+     * that organization plus the project-shared tier, writes are stamped into
+     * it, and an organization-owned record created without an explicit owner
+     * belongs to it.
+     *
+     * ⚠️ IT NAMES A SUBTREE, NOT A NODE. Organizations nest, and reach runs
+     * downward: name a reseller and the reads include every client beneath it as
+     * well as the reseller's own rows. Name the client and you get the client
+     * and nothing above or beside it. So the id to send is the NARROWEST one
+     * that covers what this request is about — sending the group when you meant
+     * one branch is not an error anywhere, it is a wider answer that looks
+     * right.
+     *
+     * A credential already confined to an organization may only name its own
+     * (`PERMISSION_DENIED` otherwise), so this cannot steer an organization key
+     * elsewhere. And a request that also carries a customer bearer is refused
+     * unless that customer stands in the named organization. The storefront
+     * pattern is still the confined credential, one per organization; this is
+     * for the side of the product that holds the project key and has to choose.
+     *
+     * Routing: a request naming an organization always goes to the origin
+     * endpoint, never the shared one. The answer is one organization's, and a
+     * cache in front of the caller keys by URL, where this header does not
+     * appear.
+     */
+    orgId?: string;
     /**
      * The generated module, whole — **the documented way to wire a client**.
      *
@@ -206,10 +255,53 @@ export interface FoirClientConfig<S extends FoirSchemaDefinition = FoirSchemaDef
      * Carried by `generated`; set it here only to override that.
      */
     schemaVersion?: number;
+    /**
+     * Subscription descriptors, from the generated module's `foirSubscriptions`.
+     *
+     * Carried by `generated`; set it here only to override that. When present a
+     * subscribing client prints from these and never fetches `GET /v1/manifest`;
+     * when absent it fetches once, as it always has.
+     */
+    subscriptions?: readonly FoirManifestSubscription[];
     /** 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;
+    /**
+     * Refuse typed calls once drift is detected, instead of serving the stale
+     * shape. **On by default**; pass `false` to opt out.
+     *
+     * The asymmetry this closes: an unknown ARGUMENT is refused client-side
+     * before the server sees it, while a field the server has and the generated
+     * selection does not is simply not requested. The second is the common case
+     * when a schema evolves, and it surfaces as absent data rather than as a
+     * tooling problem — so it is the one that needs to be loud.
+     *
+     * It is the default rather than an opt-in because the thing it prevents is
+     * SILENT. An opt-in guard against a silent failure only protects the people
+     * who already suspected the failure existed, and the warning it replaces is
+     * one more line to scroll past.
+     *
+     * Two things it deliberately does not do.
+     *
+     * It does not fail the FIRST call. Drift is only known once the manifest
+     * comes back, and that request is made off the response path after a call has
+     * already been served. A client that refused retroactively would have to
+     * block every first call on a second round trip, which is the cost the
+     * warning was designed to avoid.
+     *
+     * It does not touch `raw`. A hand-written document asks for exactly the
+     * fields it names, so it cannot silently omit one — raw is immune to this
+     * 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:
+     *
+     * ```ts
+     * createFoirClient({ strictSchemaDrift: false })  // serve stale, warn only
+     * ```
+     */
+    strictSchemaDrift?: boolean;
     /**
      * 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
@@ -267,6 +359,18 @@ export interface FoirSchemaDrift {
     server: number;
     channel: string;
 }
+/**
+ * Thrown by a typed call under `strictSchemaDrift` once drift is detected.
+ *
+ * A subclass rather than a plain `FoirRequestError` so an app can tell "your
+ * generated module is stale" from "this request failed", which want different
+ * handling: the first is fixed by a command on the developer's machine and
+ * will fail identically until they run it, the second is worth a retry.
+ */
+export declare class FoirSchemaDriftError extends FoirRequestError {
+    readonly drift: FoirSchemaDrift;
+    constructor(message: string, drift: FoirSchemaDrift);
+}
 /**
  * Build a `/v1/...` URL from whatever the caller put in `apiUrl`.
  *
@@ -284,7 +388,7 @@ 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 type FoirLaneReason = 'key' | 'bearer' | 'org' | 'operation' | 'channel' | 'floor';
 export interface FoirRouteDecision {
     lane: FoirLane;
     /** Set only on the origin lane: the first condition that ruled the shared one out. */
@@ -294,8 +398,19 @@ export interface FoirRouteInput {
     apiKey: string;
     /** The RESOLVED bearer, not the provider — a provider that yields null is not a bearer. */
     bearerToken?: string;
+    /** The organization the call acts in (`X-Org-Id`), when it names one. */
+    orgId?: string;
     mutation: boolean;
     channel?: 'published' | 'draft';
+    /**
+     * A write token from an earlier mutation, making this read a FLOORED one:
+     * serve a cached entry only if it resolved at or above the write's position.
+     *
+     * The token itself is opaque here — resolving it to a seq is the server's job
+     * and needs the event log. All this needs to know is that one is present,
+     * because that alone decides the lane.
+     */
+    writeToken?: string;
 }
 /**
  * Where this call goes.
@@ -322,4 +437,6 @@ export declare function executeFoirDocument<T>(config: FoirClientConfig, plan: F
  * what it gives up is the single-root-field unwrapping, because a document
  * written by hand may legitimately have several.
  */
-export declare function executeFoirRawDocument<T>(config: FoirClientConfig, document: string, mutation: boolean, variables?: Record<string, unknown>): Promise<T>;
+export declare function executeFoirRawDocument<T>(config: FoirClientConfig, document: string, mutation: boolean, variables?: Record<string, unknown>, options?: {
+    strict?: boolean;
+}): Promise<T>;