@foir/sdk 0.9.0 → 0.11.0

package/dist/transport/foir-http.d.ts

@@ -30,16 +30,17 @@ export interface FoirEnv {
  * Returns true when `FOIR_PREVIEW=true` is set in the environment.
  *
  * Preview is selected at the environment level, not per-request: load a
- * preview env file that sets `FOIR_PREVIEW=true` + a `sk_…`
- * `PLATFORM_PREVIEW_API_KEY` with `drafts:read` instead of the default env.
+ * preview env file that sets `FOIR_PREVIEW=true` + the preview environment's
+ * own `pk_…` key holding `drafts:read` as `PLATFORM_PREVIEW_API_KEY`, instead
+ * of the default env.
  * The site-wide mode keeps draft semantics consistent — every loader sees
  * the same preview/published view of the world. Intended for non-production
  * surfaces only.
  */
 export declare function isFoirPreview(env: FoirEnv): boolean;
 /**
- * The api key a request should carry for this env: the `sk_` preview key when
- * `FOIR_PREVIEW=true` (it is the one with `drafts:read`), the `pk_` key
+ * The api key a request should carry for this env: the preview key when
+ * `FOIR_PREVIEW=true` (it is the one with `drafts:read`), the production key
  * otherwise. Returns `undefined` when neither is configured, so the caller can
  * raise the "add them to .env" error with its own wording.
  */
@@ -69,6 +70,42 @@ export interface FoirGraphQLErrorItem {
     path?: Array<string | number>;
     extensions?: FoirErrorExtensions;
 }
+/**
+ * One selection the server stripped from the document before executing it.
+ *
+ * The data plane PRUNES rather than refuses: a selection that does not match
+ * the project's current schema is removed and the rest of the query runs, so an
+ * editor-driven model change cannot fail a deployed client's query mid-flight.
+ * The report arrives in `extensions.pruned` and deliberately NOT in `errors`,
+ * because clients treat any `errors` entry as a failed response.
+ *
+ * Which is why this type exists here. Pruning is the ONLY signal for the
+ * commonest way to get a quietly incomplete object — asking for a field the
+ * type does not have — and it produces no error for `strict` to catch.
+ */
+export interface FoirPrunedSelection {
+    /** Dotted path to the stripped selection, e.g. `pageBySlug.logo.id`. */
+    path: string;
+    /** Why it was stripped. See `MALFORMED_PRUNE_REASONS`. */
+    reason: string;
+    /** The parent type the selection was made on, when the server named one. */
+    type?: string;
+}
+/**
+ * The prune reasons that mean THE DOCUMENT IS WRONG, as opposed to the schema
+ * having moved underneath a document that was right when it shipped.
+ *
+ * A field the type does not have, a subselection on a scalar, or a composite
+ * asked for without one: each is a query that could never have been served as
+ * written. They are the shape that silently returns a plausible object with a
+ * key missing, which is how an empty file id became a `setNull` and would have
+ * deleted a logo on the next save.
+ *
+ * The rest — dead type conditions, dead fragment spreads, unreferenced
+ * fragments, unused variables — are what the pruner exists to absorb, and they
+ * stay a warning.
+ */
+export declare const MALFORMED_PRUNE_REASONS: ReadonlySet<string>;
 /** What the `X-RateLimit-*` headers said on the response that carried them. */
 export interface FoirRateLimitSnapshot {
     /** Requests allowed per window for this credential. */
@@ -83,11 +120,27 @@ export declare class FoirRequestError extends Error {
     readonly status?: number;
     /** GraphQL errors, when the request failed with a no-data error envelope. */
     readonly graphQLErrors?: ReadonlyArray<FoirGraphQLErrorItem>;
+    /**
+     * 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.
+     */
+    readonly partialData?: unknown;
+    /**
+     * 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.
+     */
+    readonly prunedSelections?: ReadonlyArray<FoirPrunedSelection>;
     readonly cause?: unknown;
     constructor(message: string, options?: {
         cause?: unknown;
         status?: number;
         graphQLErrors?: ReadonlyArray<FoirGraphQLErrorItem>;
+        partialData?: unknown;
+        prunedSelections?: ReadonlyArray<FoirPrunedSelection>;
     });
     /**
      * The code of the first error, if the response carried one.
@@ -158,6 +211,32 @@ export interface FoirRequestOptions {
      * (e.g. `myProfile`). Used by `@foir/sdk/auth`'s post-login profile fetch.
      */
     bearerToken?: string;
+    /**
+     * The organization this request acts in, sent as `X-Org-Id`. For a
+     * project-scoped key: the server resolves it to an active organization of
+     * the key's own project (else `NOT_FOUND`) and binds the request to it — a
+     * key already confined to an organization may only name that one (else
+     * `PERMISSION_DENIED`). See `FoirClientConfig.orgId` for the full contract.
+     *
+     * PER CALL, which is the narrower and riskier of the two spellings. The
+     * client-level option is the one to reach for: set it once where the
+     * organization is resolved and every request from that client carries it,
+     * so there is no call left to forget. This one is for the odd request that
+     * has to act somewhere else — and a request that omits it is not refused,
+     * it reads the project-shared tier, which is a smaller answer rather than an
+     * error.
+     *
+     * ⚠️ It names a SUBTREE. Organizations nest and reach runs downward, so a
+     * reseller's id covers every client beneath it. Send the narrowest id that
+     * covers what the request is about.
+     */
+    orgId?: string;
+    /**
+     * The organization this request acts in, named by the address of the page it
+     * is for, sent as `X-Org-Url`. See `FoirClientConfig.orgUrl` for the full
+     * contract. With `orgId` as well, the two must name the same organization.
+     */
+    orgUrl?: string;
     /**
      * Called with the `X-RateLimit-*` headers of every response, successful or
      * not, and with `undefined` when a response carried none.
@@ -180,7 +259,8 @@ export interface FoirRequestOptions {
  * they would end up accepting subtly different things.
  */
 export type FoirTokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
-export interface FoirHeaderInput {
+/** A request made with an api key, optionally for a signed-in customer. */
+export interface FoirKeyHeaderInput {
     apiKey: string;
     /**
      * Opt into the draft *schema* channel (`X-Foir-Schema-Channel: draft`) so
@@ -192,14 +272,62 @@ export interface FoirHeaderInput {
      */
     draftChannel?: boolean;
     bearerToken?: string;
+    /**
+     * The organization the request acts in (`X-Org-Id`). Set from
+     * `FoirClientConfig.orgId` / `FoirRequestOptions.orgId`; a caller who
+     * spells the header in `extra` still wins, because `extra` is applied last.
+     */
+    orgId?: string;
+    /**
+     * The organization the request acts in, named by a page URL (`X-Org-Url`).
+     * Set from `FoirClientConfig.orgUrl` / `FoirRequestOptions.orgUrl`.
+     */
+    orgUrl?: string;
+    dispatchToken?: never;
+    dispatchContext?: never;
     /** Caller-supplied extras, applied last so a caller can override. */
     extra?: Readonly<Record<string, string>>;
 }
+/**
+ * A request made AS an operation, with the dispatch token its endpoint was
+ * handed.
+ *
+ * The token is the whole credential. api-public takes the scoped path when
+ * `X-Foir-Token` is present and never reads `x-api-key` on it, and the
+ * organization, the customer and the schema channel all come from the token's
+ * own claims, so none of the key-side inputs has anything to say here.
+ */
+export interface FoirDispatchHeaderInput {
+    /** Sent as `X-Foir-Token`. */
+    dispatchToken: string;
+    /** The dispatch's `X-Foir-Context`, forwarded as it arrived. */
+    dispatchContext?: string;
+    apiKey?: never;
+    draftChannel?: never;
+    bearerToken?: never;
+    orgId?: never;
+    orgUrl?: never;
+    /**
+     * Caller-supplied extras, applied last. They may not name a credential
+     * header: see {@link refuseCredentialHeaders}.
+     */
+    extra?: Readonly<Record<string, string>>;
+}
+export type FoirHeaderInput = FoirKeyHeaderInput | FoirDispatchHeaderInput;
+/**
+ * Refuse extra headers that would add a second credential to a request made as
+ * an operation. Throws naming the header; returns nothing when there is none.
+ */
+export declare function refuseCredentialHeaders(extra: Readonly<Record<string, string>> | undefined): void;
 /**
  * The exact header set every Foir data-plane request carries. Single
  * definition on purpose: `/graphql` and `/cdn/graphql` authenticate identically,
  * and a header that exists on one surface but not the other is a per-surface
  * authorization difference nobody would notice until it mattered.
+ *
+ * Two credentials, and a request carries exactly one: an api key (with its
+ * optional customer bearer, organization and channel), or an operation's
+ * dispatch token. A dispatch request never writes `x-api-key`.
  */
 export declare function buildFoirHeaders(input: FoirHeaderInput): Record<string, string>;
 /**
@@ -218,17 +346,42 @@ export declare function buildFoirHeaders(input: FoirHeaderInput): Record<string,
  * accepted. `data/transport.ts` re-exports it under its published name.
  */
 export declare function foirApiEndpoint(apiUrl: string, path: `/${string}`): string;
+/**
+ * Foir DISCARDED a credential you sent, and served the request without it.
+ *
+ * A customer JWT is optional: if it fails to verify, the read is served as an
+ * ordinary anonymous one rather than refused, because plenty of reads
+ * legitimately have nobody signed in. That is the right behaviour and it has a
+ * sharp edge — a lapsed token and a genuinely anonymous request produce the
+ * same 200, so the failure surfaces as WRONG CONTENT rather than as an error.
+ * This block is how you find out.
+ *
+ * Present only when a token was actually sent and rejected. Its presence is
+ * always a signal.
+ */
+export interface FoirAuthDowngrade {
+    /** Always `"rejected"`. */
+    customerToken: string;
+    /**
+     * `expired` — re-exchange and retry. `invalid` — not a customer token for
+     * this environment. `wrong_project` — the token and the api-key name
+     * different projects.
+     */
+    reason: 'expired' | 'invalid' | 'wrong_project';
+    /** The authority the request actually ran under. */
+    servedAs: string;
+}
 export interface FoirResponseEnvelope<T> {
     data?: T;
     errors?: Array<FoirGraphQLErrorItem>;
+    extensions?: {
+        auth?: FoirAuthDowngrade;
+        pruned?: {
+            selections?: Array<FoirPrunedSelection>;
+        };
+        [key: string]: unknown;
+    };
 }
-/**
- * Unwrap a Foir `{ data, errors }` envelope.
- *
- * GraphQL can return partial data alongside errors; when data is present the
- * errors are logged and the data returned (callers handle nulls), and we only
- * throw when there is no data at all. Both Foir data-plane routes — `/graphql`
- * and `/cdn/graphql` — hand their document to the same executor, so the two
- * return this envelope and get the same treatment.
- */
-export declare function readFoirEnvelope<T>(json: FoirResponseEnvelope<T>): T;
+export declare function readFoirEnvelope<T>(json: FoirResponseEnvelope<T>, options?: {
+    strict?: boolean;
+}): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {
@@ -25,6 +25,14 @@
       "types": "./dist/data/index.d.ts",
       "import": "./dist/data.js"
     },
+    "./live": {
+      "types": "./dist/live/index.d.ts",
+      "import": "./dist/live.js"
+    },
+    "./live/react": {
+      "types": "./dist/live/react/index.d.ts",
+      "import": "./dist/live-react.js"
+    },
     "./media": {
       "types": "./dist/media/index.d.ts",
       "import": "./dist/media.js"
@@ -157,7 +165,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json && node scripts/assert-export-types.mjs && node scripts/assert-public-exports.mjs",
+    "build": "node scripts/clean-dist.mjs && tsup && tsc -p tsconfig.build.json && node scripts/assert-export-types.mjs && node scripts/assert-public-exports.mjs",
     "snapshot:exports": "node scripts/assert-public-exports.mjs --update",
     "dev": "node scripts/dev-watch.mjs",
     "check-types": "tsc --noEmit",