@foir/sdk 0.9.0 → 0.10.0

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