@foir/sdk 0.8.0 → 0.10.0

package/dist/push.js

@@ -11,11 +11,30 @@ function isFoirPreview(env) {
 function resolveFoirApiKey(env) {
   return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
 }
+var MALFORMED_PRUNE_REASONS = /* @__PURE__ */ new Set([
+  "unknown_field",
+  "subselections_on_scalar",
+  "missing_subselections"
+]);
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
   status;
   /** GraphQL errors, when the request failed with a no-data error envelope. */
   graphQLErrors;
+  /**
+   * The `data` the server did return, when a STRICT read refused a partial
+   * response. Present only on that path: without it, opting into strictness
+   * would trade a silent wrong answer for a thrown one that discards the answer,
+   * and a caller that wants to log what it nearly rendered could not.
+   */
+  partialData;
+  /**
+   * The selections the server stripped, when the refusal was a pruned document
+   * rather than a partial error. Same purpose as `partialData`: a caller that
+   * wants to log what it nearly rendered, or name the offending path in a
+   * developer-facing message, has it without re-parsing anything.
+   */
+  prunedSelections;
   cause;
   constructor(message, options) {
     super(message);
@@ -23,6 +42,8 @@ var FoirRequestError = class extends Error {
     this.cause = options?.cause;
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
+    this.partialData = options?.partialData;
+    this.prunedSelections = options?.prunedSelections;
   }
   /**
    * The code of the first error, if the response carried one.
@@ -93,6 +114,9 @@ function buildFoirHeaders(input) {
   if (input.bearerToken) {
     headers["Authorization"] = `Bearer ${input.bearerToken}`;
   }
+  if (input.orgId) {
+    headers["X-Org-Id"] = input.orgId;
+  }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
       headers[key] = value;
@@ -107,14 +131,45 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
-function readFoirEnvelope(json) {
+var warnedDowngrade = null;
+function reportAuthDowngrade(envelope) {
+  const downgrade = envelope.extensions?.auth;
+  if (!downgrade) {
+    warnedDowngrade = null;
+    return;
+  }
+  if (warnedDowngrade === downgrade.reason) return;
+  warnedDowngrade = downgrade.reason;
+  console.warn(
+    `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}) \u2014 this request was served as ${downgrade.servedAs}, so auth-targeted content resolved to its anonymous variant. ` + (downgrade.reason === "expired" ? "Re-exchange the token and retry." : "Check which credential you are sending.")
+  );
+}
+function refusePrunedDocument(json, options) {
+  const selections = json.extensions?.pruned?.selections;
+  if (!selections?.length) return;
+  const describe = (s) => `${s.path}${s.type ? ` on ${s.type}` : ""} (${s.reason})`;
+  const malformed = selections.filter((s) => MALFORMED_PRUNE_REASONS.has(s.reason));
+  if (malformed.length && options?.strict !== false) {
+    throw new FoirRequestError(
+      `[foir] the server could not serve part of this query and returned the rest without it: ${malformed.map(describe).join(", ")}. Those selections do not exist on the schema this project is serving. Pass strict: false to get the partial answer instead of this error.`,
+      { prunedSelections: selections }
+    );
+  }
+  console.warn(
+    `[foir] selections stripped from this query: ${selections.map(describe).join(", ")}`
+  );
+}
+function readFoirEnvelope(json, options) {
+  reportAuthDowngrade(json);
+  refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data) {
+    if (json.data && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
-        graphQLErrors: json.errors
+        graphQLErrors: json.errors,
+        partialData: json.data ?? void 0
       });
     }
   }
@@ -155,8 +210,9 @@ async function hasFoirErrorCode(res, ...codes) {
 }
 
 // src/graphql/cdn-route.ts
-function isCdnEligible(env, documentText, bearerToken) {
+function isCdnEligible(env, documentText, bearerToken, orgId) {
   if (bearerToken) return false;
+  if (orgId) return false;
   if (isFoirPreview(env)) return false;
   const apiKey = resolveFoirApiKey(env);
   if (!apiKey?.startsWith("pk_")) return false;
@@ -175,12 +231,13 @@ async function foirRequest(env, document, variables, options) {
   const headers = buildFoirHeaders({
     apiKey,
     draftChannel: isFoirPreview(env),
-    bearerToken: options?.bearerToken
+    bearerToken: options?.bearerToken,
+    orgId: options?.orgId
   });
   const documentText = print2(document);
   let res;
   try {
-    if (isCdnEligible(env, documentText, options?.bearerToken)) {
+    if (isCdnEligible(env, documentText, options?.bearerToken, options?.orgId)) {
       const hash = await documentHash(documentText);
       let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
         method: "GET",
@@ -739,7 +796,9 @@ async function resolveBearerToken(config) {
 function foirRoute(input) {
   if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
+  if (input.orgId) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
+  if (input.writeToken) return { lane: "origin", reason: "floor" };
   if (input.channel === "draft") return { lane: "origin", reason: "channel" };
   return { lane: "shared" };
 }
@@ -752,7 +811,7 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
-async function runFoirDocument(config, document, mutation, variables) {
+async function runFoirDocument(config, document, mutation, variables, options) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
   const bearerToken = await resolveBearerToken(config);
@@ -760,12 +819,14 @@ async function runFoirDocument(config, document, mutation, variables) {
     apiKey: config.apiKey,
     draftChannel: config.channel === "draft",
     bearerToken,
+    orgId: config.orgId,
     extra: config.headers
   });
   const hash = await documentHash(document);
   const route = foirRoute({
     apiKey: config.apiKey,
     bearerToken,
+    orgId: config.orgId,
     mutation,
     channel: config.channel
   });
@@ -805,7 +866,7 @@ async function runFoirDocument(config, document, mutation, variables) {
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json);
+  return readFoirEnvelope(json, options);
 }
 async function readErrorBody(res) {
   try {
@@ -828,6 +889,7 @@ async function fetchFoirManifest(config) {
         apiKey: config.apiKey,
         draftChannel: config.channel === "draft",
         bearerToken: await resolveBearerToken(config),
+        orgId: config.orgId,
         extra: config.headers
       }),
       ...config.requestInit
@@ -869,6 +931,16 @@ var AUTH_OPS = {
   customerUpdatePassword: "customerUpdatePassword",
   customerVerifyEmail: "customerVerifyEmail",
   deleteMyAccount: "deleteMyAccount",
+  // The operator's organization context. TWO ops and no third: one to read
+  // which organizations the caller may stand in, one to say which. There is
+  // deliberately no per-call org argument anywhere in this SDK — the claim the
+  // row layer reads is resolved from the caller's own membership row on every
+  // request, so an application that never names an org cannot name the wrong
+  // one.
+  myOrganizations: "myOrganizations",
+  selectMyOrganization: "selectMyOrganization",
+  // Founding one. Present in a manifest only when the project opted in.
+  registerOperatorOrganization: "registerOperatorOrganization",
   // External identity providers.
   customerLoginWithProvider: "customerLoginWithProvider",
   customerProviderCallback: "customerProviderCallback",
@@ -890,6 +962,7 @@ function authClientConfig(env, options) {
     apiKey,
     channel: isFoirPreview(env) ? "draft" : "published",
     bearerToken: options?.bearerToken,
+    orgId: options?.orgId,
     headers: options?.headers,
     fetch: options?.fetch
   };

package/dist/react.js

@@ -24,11 +24,30 @@ function isFoirPreview(env) {
 function resolveFoirApiKey(env) {
   return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
 }
+var MALFORMED_PRUNE_REASONS = /* @__PURE__ */ new Set([
+  "unknown_field",
+  "subselections_on_scalar",
+  "missing_subselections"
+]);
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
   status;
   /** GraphQL errors, when the request failed with a no-data error envelope. */
   graphQLErrors;
+  /**
+   * The `data` the server did return, when a STRICT read refused a partial
+   * response. Present only on that path: without it, opting into strictness
+   * would trade a silent wrong answer for a thrown one that discards the answer,
+   * and a caller that wants to log what it nearly rendered could not.
+   */
+  partialData;
+  /**
+   * The selections the server stripped, when the refusal was a pruned document
+   * rather than a partial error. Same purpose as `partialData`: a caller that
+   * wants to log what it nearly rendered, or name the offending path in a
+   * developer-facing message, has it without re-parsing anything.
+   */
+  prunedSelections;
   cause;
   constructor(message, options) {
     super(message);
@@ -36,6 +55,8 @@ var FoirRequestError = class extends Error {
     this.cause = options?.cause;
     this.status = options?.status;
     this.graphQLErrors = options?.graphQLErrors;
+    this.partialData = options?.partialData;
+    this.prunedSelections = options?.prunedSelections;
   }
   /**
    * The code of the first error, if the response carried one.
@@ -85,6 +106,9 @@ function buildFoirHeaders(input) {
   if (input.bearerToken) {
     headers["Authorization"] = `Bearer ${input.bearerToken}`;
   }
+  if (input.orgId) {
+    headers["X-Org-Id"] = input.orgId;
+  }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
       headers[key] = value;
@@ -99,14 +123,45 @@ function foirApiEndpoint(apiUrl, path) {
   }
   return base + path;
 }
-function readFoirEnvelope(json) {
+var warnedDowngrade = null;
+function reportAuthDowngrade(envelope) {
+  const downgrade = envelope.extensions?.auth;
+  if (!downgrade) {
+    warnedDowngrade = null;
+    return;
+  }
+  if (warnedDowngrade === downgrade.reason) return;
+  warnedDowngrade = downgrade.reason;
+  console.warn(
+    `[foir] your customer token was ${downgrade.customerToken} (${downgrade.reason}) \u2014 this request was served as ${downgrade.servedAs}, so auth-targeted content resolved to its anonymous variant. ` + (downgrade.reason === "expired" ? "Re-exchange the token and retry." : "Check which credential you are sending.")
+  );
+}
+function refusePrunedDocument(json, options) {
+  const selections = json.extensions?.pruned?.selections;
+  if (!selections?.length) return;
+  const describe = (s) => `${s.path}${s.type ? ` on ${s.type}` : ""} (${s.reason})`;
+  const malformed = selections.filter((s) => MALFORMED_PRUNE_REASONS.has(s.reason));
+  if (malformed.length && options?.strict !== false) {
+    throw new FoirRequestError(
+      `[foir] the server could not serve part of this query and returned the rest without it: ${malformed.map(describe).join(", ")}. Those selections do not exist on the schema this project is serving. Pass strict: false to get the partial answer instead of this error.`,
+      { prunedSelections: selections }
+    );
+  }
+  console.warn(
+    `[foir] selections stripped from this query: ${selections.map(describe).join(", ")}`
+  );
+}
+function readFoirEnvelope(json, options) {
+  reportAuthDowngrade(json);
+  refusePrunedDocument(json, options);
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
-    if (json.data) {
+    if (json.data && !options?.strict) {
       console.warn(`[foir] GraphQL partial errors (data returned): ${msg}`);
     } else {
       throw new FoirRequestError(`[foir] GraphQL errors: ${msg}`, {
-        graphQLErrors: json.errors
+        graphQLErrors: json.errors,
+        partialData: json.data ?? void 0
       });
     }
   }
@@ -623,7 +678,9 @@ async function resolveBearerToken(config) {
 function foirRoute(input) {
   if (!input.apiKey.startsWith("pk_")) return { lane: "origin", reason: "key" };
   if (input.bearerToken) return { lane: "origin", reason: "bearer" };
+  if (input.orgId) return { lane: "origin", reason: "org" };
   if (input.mutation) return { lane: "origin", reason: "operation" };
+  if (input.writeToken) return { lane: "origin", reason: "floor" };
   if (input.channel === "draft") return { lane: "origin", reason: "channel" };
   return { lane: "shared" };
 }
@@ -636,7 +693,7 @@ async function executeFoirDocument(config, plan) {
   }
   return data[plan.rootField];
 }
-async function runFoirDocument(config, document2, mutation, variables) {
+async function runFoirDocument(config, document2, mutation, variables, options) {
   const doFetch = config.fetch ?? globalThis.fetch;
   const endpoint = foirDataEndpoint(config.apiUrl, "/graphql");
   const bearerToken = await resolveBearerToken(config);
@@ -644,12 +701,14 @@ async function runFoirDocument(config, document2, mutation, variables) {
     apiKey: config.apiKey,
     draftChannel: config.channel === "draft",
     bearerToken,
+    orgId: config.orgId,
     extra: config.headers
   });
   const hash = await documentHash(document2);
   const route = foirRoute({
     apiKey: config.apiKey,
     bearerToken,
+    orgId: config.orgId,
     mutation,
     channel: config.channel
   });
@@ -689,7 +748,7 @@ async function runFoirDocument(config, document2, mutation, variables) {
     });
   }
   const json = await res.json();
-  return readFoirEnvelope(json);
+  return readFoirEnvelope(json, options);
 }
 async function readErrorBody(res) {
   try {
@@ -712,6 +771,7 @@ async function fetchFoirManifest(config) {
         apiKey: config.apiKey,
         draftChannel: config.channel === "draft",
         bearerToken: await resolveBearerToken(config),
+        orgId: config.orgId,
         extra: config.headers
       }),
       ...config.requestInit
@@ -753,6 +813,16 @@ var AUTH_OPS = {
   customerUpdatePassword: "customerUpdatePassword",
   customerVerifyEmail: "customerVerifyEmail",
   deleteMyAccount: "deleteMyAccount",
+  // The operator's organization context. TWO ops and no third: one to read
+  // which organizations the caller may stand in, one to say which. There is
+  // deliberately no per-call org argument anywhere in this SDK — the claim the
+  // row layer reads is resolved from the caller's own membership row on every
+  // request, so an application that never names an org cannot name the wrong
+  // one.
+  myOrganizations: "myOrganizations",
+  selectMyOrganization: "selectMyOrganization",
+  // Founding one. Present in a manifest only when the project opted in.
+  registerOperatorOrganization: "registerOperatorOrganization",
   // External identity providers.
   customerLoginWithProvider: "customerLoginWithProvider",
   customerProviderCallback: "customerProviderCallback",
@@ -774,6 +844,7 @@ function authClientConfig(env, options) {
     apiKey,
     channel: isFoirPreview(env) ? "draft" : "published",
     bearerToken: options?.bearerToken,
+    orgId: options?.orgId,
     headers: options?.headers,
     fetch: options?.fetch
   };

package/dist/realtime/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @foir/sdk/realtime — optional thin web helper over y-websocket (EID-103).
+ * @foir/sdk/realtime — optional thin web helper over y-websocket.
  *
  * The apollo-link analogue for Foir realtime collaboration: sugar over the
  * off-the-shelf `y-websocket` provider that adds exactly the wire-protocol
@@ -17,7 +17,7 @@
  * `yjs` + `y-websocket` are OPTIONAL peer deps gated to this subpath, so a
  * consumer importing only other `@foir/sdk/*` exports pulls no Yjs.
  *
- * Wire-protocol contract: `docs/realtime-collab-contract.md` (EID-117).
+ * Wire-protocol contract: `docs/realtime-collab-contract.md`.
  */
 import type * as Y from 'yjs';
 import { WebsocketProvider } from 'y-websocket';
@@ -36,13 +36,12 @@ export interface RoomAddress {
      * with a 400).
      *
      * That segment is a KEY space because the platform compares it against the
-     * reserved token `live` to select an EPHEMERAL persistence policy (EID-385):
+     * reserved token `live` to select an EPHEMERAL persistence policy:
      * live co-edit only — no `editing_state`, no autosave, doc destroyed on last
      * leave. A cuid2 row id can never equal `live`, so sending an id puts that
      * policy out of reach by construction. Worse, variants are themselves rows in
      * `records`, so a variant id still passes the join gate: the connection
-     * succeeds and edits a DIFFERENT record, with nothing reported on either side
-     * (TTS-953).
+     * succeeds and edits a DIFFERENT record, with nothing reported on either side.
      *
      * The address to send is the one the API advertises — the `collab` field on
      * every public record type returns `{ enabled, wsUrl, roomName }`, where

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

@@ -7,6 +7,7 @@ export type { OperationPayload, OperationTrigger, OperationRecordContext, Operat
 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/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