@foir/sdk 0.10.0 → 0.11.0

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

@@ -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.

package/dist/server.js

@@ -238,13 +238,93 @@ async function requireScopedToken(request, options) {
       403
     );
   }
+  const rawContext = request.headers.get(CONTEXT_HEADER);
   return {
     claims,
     subject,
-    context: parseContextHeader(request.headers.get(CONTEXT_HEADER))
+    context: parseContextHeader(rawContext),
+    // The token handed over is the one verified above, not a fresh read of the
+    // header, so the client presents exactly what this guard accepted.
+    dispatch: { token: () => token, context: rawContext }
   };
 }
 
+// src/server/read-dispatch.ts
+var OperationPayloadError = class extends Error {
+  status;
+  constructor(message) {
+    super(message);
+    this.name = "OperationPayloadError";
+    this.status = 400;
+  }
+};
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function refuse(message) {
+  throw new OperationPayloadError(`[foir] not an operation dispatch body: ${message}`);
+}
+function requireString(from, key, where, allowEmpty = false) {
+  const value = from[key];
+  if (typeof value !== "string" || !allowEmpty && value === "") {
+    refuse(`${where}.${key} is ${describe(value)}, expected a${allowEmpty ? "" : " non-empty"} string`);
+  }
+  return value;
+}
+function describe(value) {
+  if (value === void 0) return "missing";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return `a ${typeof value}`;
+}
+async function readDispatch(request) {
+  let text;
+  try {
+    text = await request.text();
+  } catch (err) {
+    throw new OperationPayloadError(
+      `[foir] could not read the dispatch body (has something already consumed it?): ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    refuse("the body is not JSON");
+  }
+  if (!isObject(body)) refuse(`the body is ${describe(body)}, expected a JSON object`);
+  if (typeof body.executionId !== "string" || typeof body.operationKey !== "string") {
+    refuse(
+      "it has no executionId and operationKey. The platform sends the run, not the input: the caller's input is under `input`"
+    );
+  }
+  requireString(body, "executionId", "body");
+  requireString(body, "operationKey", "body");
+  const trigger = body.trigger;
+  if (!isObject(trigger)) refuse(`body.trigger is ${describe(trigger)}, expected an object`);
+  requireString(trigger, "type", "body.trigger");
+  const context = body.context;
+  if (!isObject(context)) refuse(`body.context is ${describe(context)}, expected an object`);
+  requireString(context, "tenantId", "body.context");
+  requireString(context, "projectId", "body.context");
+  requireString(context, "userId", "body.context", true);
+  requireString(context, "timestamp", "body.context");
+  if (context.customerId !== void 0) requireString(context, "customerId", "body.context");
+  const input = body.input;
+  if (input !== null && !isObject(input)) {
+    refuse(`body.input is ${describe(input)}, expected an object`);
+  }
+  const payload = { ...body, input: input ?? {} };
+  for (const block of ["content", "record", "triggerContext", "callback"]) {
+    const value = payload[block];
+    if (value === void 0) continue;
+    if (value === null) {
+      delete payload[block];
+      continue;
+    }
+    if (!isObject(value)) refuse(`body.${block} is ${describe(value)}, expected an object`);
+  }
+  return payload;
+}
+
 // src/server/callback-client.ts
 function createCallbackClient(callback, opts) {
   const { executionId, signingSecret } = opts;
@@ -428,19 +508,46 @@ function readFoirRetryAfterMs(headers) {
   const seconds = Number(headers.get("Retry-After"));
   return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
 }
+var DISPATCH_RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "x-api-key",
+  "authorization",
+  "x-foir-token",
+  "x-foir-context"
+]);
+function refuseCredentialHeaders(extra) {
+  if (!extra) return;
+  for (const name of Object.keys(extra)) {
+    if (DISPATCH_RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw new FoirRequestError(
+        `[foir] a client built from a dispatch token cannot send "${name}" in \`headers\`. The dispatch token is the credential, and an api key or a bearer beside it would make the request two actors at once. Build a separate client for the other credential.`
+      );
+    }
+  }
+}
 function buildFoirHeaders(input) {
   const headers = {
-    "Content-Type": "application/json",
-    "x-api-key": input.apiKey
+    "Content-Type": "application/json"
   };
-  if (input.draftChannel) {
-    headers["X-Foir-Schema-Channel"] = "draft";
-  }
-  if (input.bearerToken) {
-    headers["Authorization"] = `Bearer ${input.bearerToken}`;
-  }
-  if (input.orgId) {
-    headers["X-Org-Id"] = input.orgId;
+  if (input.dispatchToken !== void 0) {
+    refuseCredentialHeaders(input.extra);
+    headers["X-Foir-Token"] = input.dispatchToken;
+    if (input.dispatchContext) {
+      headers["X-Foir-Context"] = input.dispatchContext;
+    }
+  } else {
+    headers["x-api-key"] = input.apiKey;
+    if (input.draftChannel) {
+      headers["X-Foir-Schema-Channel"] = "draft";
+    }
+    if (input.bearerToken) {
+      headers["Authorization"] = `Bearer ${input.bearerToken}`;
+    }
+    if (input.orgId) {
+      headers["X-Org-Id"] = input.orgId;
+    }
+    if (input.orgUrl) {
+      headers["X-Org-Url"] = input.orgUrl;
+    }
   }
   if (input.extra) {
     for (const [key, value] of Object.entries(input.extra)) {
@@ -463,6 +570,38 @@ async function resolveBearerToken(config) {
   if (typeof source === "function") return await source() ?? void 0;
   return source ?? void 0;
 }
+async function resolveDispatchToken(dispatch) {
+  const token = (await dispatch.token())?.trim();
+  if (!token) {
+    throw new FoirRequestError(
+      "[foir] the dispatch token provider returned no token. A client built from a dispatch calls Foir as that operation and holds no other credential. Build it from the token the endpoint was handed: `(await requireScopedToken(request)).dispatch`."
+    );
+  }
+  return token;
+}
+async function resolveFoirAuth(config) {
+  if (config.dispatch !== void 0) {
+    return {
+      headers: buildFoirHeaders({
+        dispatchToken: await resolveDispatchToken(config.dispatch),
+        dispatchContext: config.dispatch.context ?? void 0,
+        extra: config.headers
+      })
+    };
+  }
+  const bearerToken = await resolveBearerToken(config);
+  return {
+    headers: buildFoirHeaders({
+      apiKey: config.apiKey,
+      draftChannel: config.channel === "draft",
+      bearerToken,
+      orgId: config.orgId,
+      orgUrl: config.orgUrl,
+      extra: config.headers
+    }),
+    key: { apiKey: config.apiKey, bearerToken }
+  };
+}
 
 // src/data/ws-transport.ts
 var GQL = {
@@ -500,6 +639,11 @@ var FoirSocketTransport = class {
   keepAlive = null;
   retryTimer = null;
   constructor(config) {
+    if (config.dispatch !== void 0) {
+      throw new FoirRequestError(
+        "[foir] a client built from a dispatch token cannot subscribe. The subscription socket authenticates an api key, an admin token or a customer bearer, and has no path for a dispatch token. Queries and mutations made as the operation go to /graphql and work as they are."
+      );
+    }
     this.config = config;
     this.policy = { ...DEFAULT_RECONNECT, ...config.reconnect ?? {} };
   }
@@ -571,13 +715,7 @@ var FoirSocketTransport = class {
   async sendConnectionInit(socket) {
     this.connecting = false;
     try {
-      const headers = buildFoirHeaders({
-        apiKey: this.config.apiKey,
-        draftChannel: this.config.channel === "draft",
-        bearerToken: await resolveBearerToken(this.config),
-        orgId: this.config.orgId,
-        extra: this.config.headers
-      });
+      const { headers } = await resolveFoirAuth(this.config);
       const { "Content-Type": _contentType, ...params } = headers;
       const extra = await this.config.connectionParams?.() ?? {};
       this.send(socket, {
@@ -684,7 +822,7 @@ var FoirSocketTransport = class {
         return;
       }
       case GQL.error: {
-        const error = new FoirRequestError(`[foir] subscription refused: ${describe(message.payload)}`, {
+        const error = new FoirRequestError(`[foir] subscription refused: ${describe2(message.payload)}`, {
           graphQLErrors: graphQLErrorItems(message.payload)
         });
         if (!message.id) {
@@ -805,17 +943,17 @@ function graphQLErrorItems(payload) {
     const { message, path, extensions } = entry;
     if (extensions === void 0 && path === void 0) continue;
     items.push({
-      message: typeof message === "string" ? message : describe(entry),
+      message: typeof message === "string" ? message : describe2(entry),
       ...Array.isArray(path) ? { path } : {},
       ...typeof extensions === "object" && extensions !== null ? { extensions } : {}
     });
   }
   return items.length > 0 ? items : void 0;
 }
-function describe(payload) {
+function describe2(payload) {
   if (payload == null) return "no reason given";
   if (typeof payload === "string") return payload;
-  if (Array.isArray(payload)) return payload.map(describe).join("; ");
+  if (Array.isArray(payload)) return payload.map(describe2).join("; ");
   if (typeof payload === "object") {
     const message = payload.message;
     if (typeof message === "string") return message;
@@ -1089,6 +1227,7 @@ export {
   FOIR_EVENTS_SCOPE,
   FoirEventCursorExpiredError,
   FoirRequestError,
+  OperationPayloadError,
   ScopedTokenError,
   ServerClientError,
   createCallbackClient,
@@ -1101,6 +1240,7 @@ export {
   isFoirUnauthenticated,
   parseContextHeader,
   parseSubject,
+  readDispatch,
   recordsReadModels,
   recordsWriteModels,
   requireScopedToken,

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.
  */
@@ -230,6 +231,12 @@ export interface FoirRequestOptions {
      * 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.
@@ -252,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
@@ -270,14 +278,56 @@ export interface FoirHeaderInput {
      * 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>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {