@foir/sdk 0.7.0 → 0.8.0

package/dist/realtime.js

@@ -91,7 +91,7 @@ function createCollabSession(options) {
       if (clientId === awareness.clientID) return;
       const user = state["user"];
       if (user && typeof user.id === "string") {
-        next.push({ clientId, id: user.id, name: user.name, color: user.color });
+        next.push({ ...user, clientId, id: user.id, name: user.name, color: user.color });
       }
     });
     peers = next;

package/dist/server/events-client.d.ts

@@ -0,0 +1,279 @@
+/**
+ * `@foir/sdk/server`'s event-log client — cursor-resumable consumption of a
+ * project's durable event history (TTS-983, epic TTS-912).
+ *
+ * ```ts
+ * import { createEventsClient } from '@foir/sdk/server';
+ *
+ * const events = createEventsClient({
+ *   apiUrl: process.env.PLATFORM_API_URL!,
+ *   apiKey: process.env.FOIR_SECRET_KEY!, // sk_…, holding events:list.project
+ * });
+ *
+ * const page = await events.list({ after: lastSeq, limit: 500 });
+ * for (const event of page.events) {
+ *   await handle(event);
+ *   lastSeq = event.seq; // durable position; store it
+ * }
+ * ```
+ *
+ * ---------------------------------------------------------------------------
+ * 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
+ * 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.
+ *
+ * The reason is a predicate asymmetry rather than a policy preference.
+ * `events.view` is plain tenant+project containment; `record.view` carries
+ * owner, admin_owner, access_mode, grantee, comp_parent, read_borrow and
+ * slice_parent terms on top of it. A containment-only read over the log
+ * therefore describes rows whose underlying records the same caller could not
+ * read — and every row carries `actor`, naming which OTHER customer acted. In a
+ * project with owner confinement that is a per-record activity feed of other
+ * people's actions.
+ *
+ * Three consequences for the shape of this file, all deliberate:
+ *
+ *   1. **It lives on `@foir/sdk/server` and nowhere else.** Not `./data`, not
+ *      `./client`, not `./react`. Those subpaths are the ones a storefront
+ *      bundles, and `./data` in particular is routinely constructed with a `pk_`
+ *      key in browser-reachable code. `src/server/__tests__/events-client.test.ts`
+ *      walks the import graph of every published subpath and fails if this
+ *      module becomes reachable from one that ships to a browser — because
+ *      "we only documented it on the server" is not a property anything checks.
+ *
+ *   2. **A `pk_` key is refused at construction**, before a request is made. The
+ *      server would refuse it anyway (403), but a 403 at 3am in a deploy log is
+ *      a worse teacher than a thrown error naming the key type at the line that
+ *      built the client.
+ *
+ *   3. **There is no `bearerToken` option, and an `Authorization` header is
+ *      refused.** On api-public a request presenting `sk_` plus a customer
+ *      bearer resolves the CUSTOMER as the authority, and `events` is stripped
+ *      from every customer authority upstream — so attaching a signed-in
+ *      shopper's token to an operator read turns a working call into a 403 that
+ *      reads like a scope problem. Refusing it here says what actually happened.
+ *
+ * Widening this later is easy. Teaching customers a capability they do not have
+ * is a support burden that cannot be retracted.
+ *
+ * ---------------------------------------------------------------------------
+ * Why `GET /v1/events` and not the GraphQL `events` field
+ * ---------------------------------------------------------------------------
+ *
+ * Both exist and both call the same platform RPC with the same credential and
+ * the same scope requirement, so this is not an authorization difference. It is
+ * a caching one: the GraphQL lane sits behind api-public's response cache, and
+ * a cursor-paged log served from a cached body can hand a consumer a page it has
+ * already processed while `hasMore` says there is nothing left. The REST twin is
+ * deliberately not response-cached, which is the property a durable consumer
+ * needs. It also keeps this module `graphql`-free, like `@foir/sdk/data`.
+ */
+import { FoirRequestError } from '../transport/foir-http';
+/** The path `GET /v1/events` is mounted on, inside api-public's api-key group. */
+export declare const FOIR_EVENTS_PATH = "/v1/events";
+/**
+ * The scope an `sk_` key must hold. Never mintable on a `pk_` — `events` is
+ * absent from the platform's `publicSafeScopeResources` — and never present in a
+ * customer's resolved authority.
+ */
+export declare const FOIR_EVENTS_SCOPE = "events:list.project";
+/**
+ * The flat retention window, in days. Reported on every page as
+ * {@link FoirEventRetention.windowDays} too; this constant is the one to compare
+ * a hard-coded expectation against, and the two are pinned to each other by
+ * `oldestRetainedAt` in the tests.
+ */
+export declare const FOIR_EVENTS_RETENTION_DAYS = 90;
+/** Who caused an event. `null` when the emit site attributed nobody. */
+export interface FoirEventActor {
+    /** e.g. `"customer"`, `"admin"`, `"api_key"`, `"system"`. */
+    kind?: string;
+    /** e.g. `"customer:cus_123"`. */
+    ref?: string;
+    [key: string]: unknown;
+}
+/** One row of the durable event log. */
+export interface FoirEvent {
+    id: string;
+    /**
+     * This event's position in the project's stream, assigned by the relay in
+     * COMMIT order — not at insert, and not by `created_at`.
+     *
+     * Store the highest one you have finished processing and pass it back as
+     * `after`. Gaps are normal: the stream carries events your filter did not
+     * match, and history ages out of the retention window. `seq` is for
+     * comparing, never for counting.
+     */
+    seq: number;
+    /** The registry name, e.g. `"record.created"`. */
+    event: string;
+    /**
+     * The event's own flat keys, plus `state` and `stateSchema`.
+     *
+     * `state` is the resource AS OF the event — self-contained, not a pointer to
+     * current state — for the customer, session, operation and workspace-plane
+     * families. It is null for `record.*` events, deliberately and permanently:
+     * `events.view` is plain tenant/project containment while `record.view`
+     * carries owner, grant, borrow and per-field terms, so a copy of record data
+     * in the log would escape every one of them for the whole retention window.
+     *
+     * A record event therefore carries the `recordId` / `modelKey` pointer and no
+     * field content — read the record back under your own credentials.
+     *
+     * `stateSchema` versions the snapshot's shape.
+     */
+    payload: Record<string, unknown>;
+    actor: FoirEventActor | null;
+    /** The operation-key history that led here. */
+    causationChain: string[];
+    /** RFC 3339, as sent. */
+    createdAt: string;
+}
+/**
+ * The retention window, reported on EVERY page rather than only when something
+ * has gone wrong — so a consumer can see how close its cursor is to the edge
+ * before it falls off, which is the difference between an alert and an incident.
+ */
+export interface FoirEventRetention {
+    /** The flat window in days. 90, no tiering. */
+    windowDays: number;
+    /** The oldest `createdAt` the API will serve. RFC 3339. */
+    oldestRetainedAt: string;
+    /**
+     * The lowest `seq` still inside the window for this project, or 0 when nothing
+     * is retained. Compare your stored cursor against it to see the runway left.
+     */
+    oldestAvailableSeq: number;
+}
+export interface FoirEventPage {
+    /** The page, ordered by `seq` ascending. */
+    events: FoirEvent[];
+    /**
+     * The cursor to persist and resume from: the `seq` of the last event on this
+     * page, or the request's `after` when the page is empty. Never moves
+     * backwards, so persisting it unconditionally is safe.
+     */
+    nextCursor: number;
+    /** True when more events are already available past `nextCursor`. */
+    hasMore: boolean;
+    retention: FoirEventRetention;
+}
+export interface FoirEventsListParams {
+    /**
+     * Exclusive cursor: return events with `seq > after`. Omit or pass 0 to start
+     * at the oldest event still inside the retention window.
+     */
+    after?: number;
+    /** 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
+     * every event.
+     */
+    events?: readonly string[];
+    /** Aborts the underlying request. */
+    signal?: AbortSignal;
+}
+export interface FoirEventsStreamParams extends FoirEventsListParams {
+    /**
+     * Called after each page is fetched and before its events are yielded, with
+     * the cursor that page ended on. Use it to checkpoint at page granularity
+     * instead of per event.
+     */
+    onPage?: (page: FoirEventPage) => void | Promise<void>;
+}
+export interface FoirEventsClientConfig {
+    /**
+     * Foir public API origin, e.g. `https://api.foir.dev`. A full
+     * `https://api.foir.dev/graphql` is accepted too, since that is what
+     * `PLATFORM_API_URL` conventionally holds.
+     */
+    apiUrl: string;
+    /**
+     * An `sk_` secret key holding `events:list.project`.
+     *
+     * A `pk_` key is refused here rather than at the server — see the operator
+     * note at the top of this file.
+     */
+    apiKey: string;
+    /**
+     * Extra headers. An `Authorization` header is refused: a customer bearer
+     * flips api-public's resolved authority to the customer, and no customer
+     * authority can contain `events:list.project`.
+     */
+    headers?: Readonly<Record<string, string>>;
+    /** `fetch` implementation. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Merged into every `fetch` call. Applied after method/headers, so those
+     * cannot be clobbered by accident.
+     */
+    requestInit?: Omit<RequestInit, 'method' | 'headers' | 'body'>;
+}
+export interface FoirEventsClient {
+    /** One page of the project's event history. */
+    list(params?: FoirEventsListParams): Promise<FoirEventPage>;
+    /**
+     * Every event from `after` to the current end of the stream, paging as it
+     * goes. Finishes when the server reports no more — it does NOT poll, so a
+     * long-running consumer wraps it in its own interval.
+     *
+     * Each yielded event carries its own `seq`, which is the cursor: a consumer
+     * that stores `event.seq` after processing resumes exactly where it stopped,
+     * including mid-page after a crash.
+     */
+    stream(params?: FoirEventsStreamParams): AsyncGenerator<FoirEvent, void, void>;
+}
+/**
+ * The cursor named a position older than the retention window, so events the
+ * consumer had not read have expired. HTTP 410 Gone.
+ *
+ * The server REFUSES rather than serving a shortened page, deliberately: a flag
+ * on a successful response makes silent data loss the default for every consumer
+ * that does not read the flag. Acknowledging a gap should be one deliberate line
+ * of code, not an accident.
+ *
+ * ```ts
+ * try {
+ *   page = await events.list({ after: cursor });
+ * } catch (err) {
+ *   if (err instanceof FoirEventCursorExpiredError) {
+ *     await recordGap(cursor, err.resumeFrom);
+ *     page = await events.list({ after: err.resumeFrom ?? 0 });
+ *   } else throw err;
+ * }
+ * ```
+ */
+export declare class FoirEventCursorExpiredError extends FoirRequestError {
+    /**
+     * The cursor to resume from, accepting the gap — parsed out of the server's
+     * message, which names it.
+     *
+     * `undefined` only if the message ever stops naming one, in which case
+     * restarting from 0 and de-duplicating on `id` is the safe fallback. It is
+     * optional for that reason and not because the server omits it today; both
+     * refusal messages carry it, and both are pinned as fixtures in the tests.
+     */
+    readonly resumeFrom?: number;
+    /** The cursor that was rejected — whatever was passed as `after`. */
+    readonly requestedCursor?: number;
+    constructor(message: string, options: {
+        status: number;
+        resumeFrom?: number;
+        requestedCursor?: number;
+    });
+}
+/**
+ * True when the failure is a cursor that fell outside the retention window.
+ *
+ * Provided alongside the class because `instanceof` across two copies of the
+ * package — a monorepo with a hoisted and a nested `@foir/sdk` — is false even
+ * for the right error, and the SDK's other taxonomy helpers
+ * (`isFoirRateLimited`, `isFoirForbidden`) already set this precedent.
+ */
+export declare function isFoirEventCursorExpired(err: unknown): err is FoirEventCursorExpiredError;
+export declare function createEventsClient(config: FoirEventsClientConfig): FoirEventsClient;

package/dist/server/index.d.ts

@@ -6,3 +6,7 @@ export type { ServerClient, ServerClientOptions, GraphQLResponse, EditorPlacemen
 export type { OperationPayload, OperationTrigger, OperationRecordContext, OperationContext, OperationResult, OperationCallback, } from './operation-types';
 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 { FoirRequestError, isFoirForbidden, isFoirNotFound, isFoirRateLimited, isFoirUnauthenticated, } from '../transport/foir-http';
+export type { FoirErrorCode, FoirErrorExtensions, FoirGraphQLErrorItem } from '../transport/foir-http';

package/dist/server.js

@@ -344,11 +344,309 @@ async function hmacSha256Hex(secret, body) {
   const sig = await crypto.subtle.sign("HMAC", key, enc.encode(body));
   return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+
+// src/transport/foir-http.ts
+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;
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "FoirRequestError";
+    this.cause = options?.cause;
+    this.status = options?.status;
+    this.graphQLErrors = options?.graphQLErrors;
+  }
+  /**
+   * The code of the first error, if the response carried one.
+   *
+   * A getter rather than a stored field so it stays correct for an error
+   * constructed anywhere, including by a caller in a test.
+   */
+  get code() {
+    return this.graphQLErrors?.[0]?.extensions?.code;
+  }
+  /** The correlation id, if the response carried one. */
+  get requestId() {
+    return this.graphQLErrors?.[0]?.extensions?.requestId;
+  }
+  /**
+   * Whether retrying this request could succeed.
+   *
+   * The 429 is the one that has to be in here and is easy to leave out: it sits
+   * among the 4xx statuses that are otherwise permanent, so a policy written as
+   * "retry 5xx, never retry 4xx" excludes exactly the failure that clears on its
+   * own. A storefront wrote that policy, its key saturated, and every read
+   * failed on the first attempt for an hour.
+   */
+  get retryable() {
+    if (this.status === void 0) return true;
+    if (this.status === 429 || this.code === "RATE_LIMITED") return true;
+    if (this.status >= 500) return true;
+    return this.code === "UNAVAILABLE" || this.code === "TIMEOUT";
+  }
+  /**
+   * How long to wait before retrying, in milliseconds, when the server said.
+   * Undefined when it did not, which means the caller picks its own backoff.
+   */
+  get retryAfterMs() {
+    const seconds = this.graphQLErrors?.[0]?.extensions?.retryAfter;
+    return typeof seconds === "number" && seconds > 0 ? seconds * 1e3 : void 0;
+  }
+};
+function isFoirRateLimited(err) {
+  return err instanceof FoirRequestError && (err.status === 429 || err.code === "RATE_LIMITED");
+}
+function isFoirUnauthenticated(err) {
+  return err instanceof FoirRequestError && (err.status === 401 || err.code === "UNAUTHENTICATED");
+}
+function isFoirForbidden(err) {
+  return err instanceof FoirRequestError && (err.status === 403 || err.code === "PERMISSION_DENIED");
+}
+function isFoirNotFound(err) {
+  return err instanceof FoirRequestError && err.code === "NOT_FOUND";
+}
+function readFoirRetryAfterMs(headers) {
+  const seconds = Number(headers.get("Retry-After"));
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
+}
+function buildFoirHeaders(input) {
+  const headers = {
+    "Content-Type": "application/json",
+    "x-api-key": input.apiKey
+  };
+  if (input.draftChannel) {
+    headers["X-Foir-Schema-Channel"] = "draft";
+  }
+  if (input.bearerToken) {
+    headers["Authorization"] = `Bearer ${input.bearerToken}`;
+  }
+  if (input.extra) {
+    for (const [key, value] of Object.entries(input.extra)) {
+      headers[key] = value;
+    }
+  }
+  return headers;
+}
+function foirApiEndpoint(apiUrl, path) {
+  const base = apiUrl.trim().replace(/\/+$/, "").replace(/\/graphql$/i, "");
+  if (!base) {
+    throw new FoirRequestError("[foir] apiUrl is empty \u2014 pass the Foir API origin");
+  }
+  return base + path;
+}
+
+// src/server/events-client.ts
+var FOIR_EVENTS_PATH = "/v1/events";
+var FOIR_EVENTS_SCOPE = "events:list.project";
+var FOIR_EVENTS_RETENTION_DAYS = 90;
+var FoirEventCursorExpiredError = class extends FoirRequestError {
+  /**
+   * The cursor to resume from, accepting the gap — parsed out of the server's
+   * message, which names it.
+   *
+   * `undefined` only if the message ever stops naming one, in which case
+   * restarting from 0 and de-duplicating on `id` is the safe fallback. It is
+   * optional for that reason and not because the server omits it today; both
+   * refusal messages carry it, and both are pinned as fixtures in the tests.
+   */
+  resumeFrom;
+  /** The cursor that was rejected — whatever was passed as `after`. */
+  requestedCursor;
+  constructor(message, options) {
+    super(message, { status: options.status });
+    this.name = "FoirEventCursorExpiredError";
+    this.resumeFrom = options.resumeFrom;
+    this.requestedCursor = options.requestedCursor;
+  }
+};
+function isFoirEventCursorExpired(err) {
+  return err instanceof FoirRequestError && err.status === 410;
+}
+var RESUME_FROM = /resume from\s+(\d+)/i;
+function parseResumeFrom(message) {
+  const m = RESUME_FROM.exec(message);
+  if (!m) return void 0;
+  const n = Number(m[1]);
+  return Number.isSafeInteger(n) ? n : void 0;
+}
+function assertOperatorKey(apiKey) {
+  const key = apiKey?.trim() ?? "";
+  if (!key) {
+    throw new FoirRequestError(
+      `[foir] createEventsClient: apiKey is empty \u2014 pass an sk_ secret key holding ${FOIR_EVENTS_SCOPE}.`
+    );
+  }
+  if (key.startsWith("pk_")) {
+    throw new FoirRequestError(
+      `[foir] createEventsClient: the event log is an OPERATOR surface and a public (pk_) key can never hold ${FOIR_EVENTS_SCOPE} \u2014 it is not mintable on a public key. Use an sk_ secret key from a server-side runtime; a pk_ key is embeddable in browser bundles, and the log names which customer acted on records the bundle's reader cannot themselves read.`
+    );
+  }
+  if (!key.startsWith("sk_")) {
+    throw new FoirRequestError(
+      `[foir] createEventsClient: apiKey must be an sk_ secret key (sk_ or sk_t_), got a key starting "${key.slice(0, 4)}". The event log is reachable by an sk_ api key or an admin session only.`
+    );
+  }
+  return key;
+}
+function assertNoBearer(headers) {
+  if (!headers) return;
+  for (const name of Object.keys(headers)) {
+    if (name.toLowerCase() === "authorization") {
+      throw new FoirRequestError(
+        `[foir] createEventsClient: an Authorization header is not accepted. A customer bearer makes the customer the resolved authority on api-public, and no customer authority can contain ${FOIR_EVENTS_SCOPE}. The sk_ key alone is the credential for this surface.`
+      );
+    }
+  }
+}
+function readSeq(value, field) {
+  const n = typeof value === "number" ? value : Number(value ?? 0);
+  if (!Number.isSafeInteger(n)) {
+    throw new FoirRequestError(
+      `[foir] events: ${field} is not a safe integer (${String(value)}). A sequence number past 2^53 cannot be represented exactly in JSON, and an inexact cursor skips or repeats events.`
+    );
+  }
+  return n;
+}
+function toEvent(raw) {
+  return {
+    id: raw.id ?? "",
+    seq: readSeq(raw.seq, "event.seq"),
+    event: raw.event ?? "",
+    payload: raw.payload ?? {},
+    // `null` is preserved rather than defaulted to `{}`: "nobody was attributed"
+    // and "attributed to nothing in particular" are different facts, and the
+    // platform goes out of its way to keep them apart.
+    actor: raw.actor ?? null,
+    causationChain: raw.causation_chain ?? [],
+    createdAt: raw.created_at ?? ""
+  };
+}
+function toPage(raw) {
+  const retention = raw.retention ?? {};
+  return {
+    events: (raw.events ?? []).map(toEvent),
+    nextCursor: readSeq(raw.next_cursor, "next_cursor"),
+    hasMore: raw.has_more === true,
+    retention: {
+      windowDays: Number(retention.window_days ?? 0),
+      oldestRetainedAt: retention.oldest_retained_at ?? "",
+      oldestAvailableSeq: readSeq(retention.oldest_available_seq, "retention.oldest_available_seq")
+    }
+  };
+}
+var STATUS_CODES = {
+  400: "INVALID_ARGUMENT",
+  401: "UNAUTHENTICATED",
+  403: "PERMISSION_DENIED",
+  404: "NOT_FOUND",
+  410: "FAILED_PRECONDITION",
+  429: "RATE_LIMITED",
+  503: "UNAVAILABLE",
+  504: "TIMEOUT"
+};
+async function readErrorMessage(res) {
+  try {
+    const json = await res.json();
+    if (typeof json?.error === "string" && json.error) return json.error;
+    const first = json?.errors?.[0]?.message;
+    return typeof first === "string" && first ? first : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function createEventsClient(config) {
+  const apiKey = assertOperatorKey(config.apiKey);
+  assertNoBearer(config.headers);
+  const url = foirApiEndpoint(config.apiUrl, FOIR_EVENTS_PATH);
+  async function list(params = {}) {
+    const doFetch = config.fetch ?? globalThis.fetch;
+    const query = new URLSearchParams();
+    if (params.after !== void 0) query.set("after", String(readSeq(params.after, "after")));
+    if (params.limit !== void 0) query.set("limit", String(params.limit));
+    for (const name of params.events ?? []) {
+      if (name) query.append("event", name);
+    }
+    const qs = query.toString();
+    let res;
+    try {
+      res = await doFetch(qs ? `${url}?${qs}` : url, {
+        method: "GET",
+        headers: buildFoirHeaders({ apiKey, extra: config.headers }),
+        ...params.signal ? { signal: params.signal } : {},
+        ...config.requestInit
+      });
+    } catch (err) {
+      throw new FoirRequestError("[foir] events: network error", { cause: err });
+    }
+    if (!res.ok) {
+      const message = await readErrorMessage(res);
+      const detail = message ? `: ${message}` : "";
+      if (res.status === 410) {
+        throw new FoirEventCursorExpiredError(`[foir] events: cursor expired${detail}`, {
+          status: 410,
+          resumeFrom: message ? parseResumeFrom(message) : void 0,
+          requestedCursor: params.after
+        });
+      }
+      const extensions = {};
+      const code = STATUS_CODES[res.status] ?? (res.status >= 500 ? "INTERNAL" : void 0);
+      if (code) extensions.code = code;
+      const retryAfterMs = readFoirRetryAfterMs(res.headers);
+      if (retryAfterMs !== void 0) extensions.retryAfter = retryAfterMs / 1e3;
+      throw new FoirRequestError(`[foir] events: HTTP ${res.status} ${res.statusText}${detail}`, {
+        status: res.status,
+        graphQLErrors: [{ message: message ?? res.statusText, extensions }]
+      });
+    }
+    let body;
+    try {
+      body = await res.json();
+    } catch (err) {
+      throw new FoirRequestError("[foir] events: response was not JSON", {
+        cause: err,
+        status: res.status
+      });
+    }
+    return toPage(body);
+  }
+  async function* stream(params = {}) {
+    const { onPage, ...rest } = params;
+    let after = params.after ?? 0;
+    for (; ; ) {
+      const page = await list({ ...rest, after });
+      if (onPage) await onPage(page);
+      for (const event of page.events) yield event;
+      if (!page.hasMore) return;
+      if (page.nextCursor <= after) {
+        throw new FoirRequestError(
+          `[foir] events: the server reported has_more with a cursor that did not advance (${after} -> ${page.nextCursor}). Refusing to loop.`,
+          { status: 500 }
+        );
+      }
+      after = page.nextCursor;
+    }
+  }
+  return { list, stream };
+}
 export {
+  FOIR_EVENTS_PATH,
+  FOIR_EVENTS_RETENTION_DAYS,
+  FOIR_EVENTS_SCOPE,
+  FoirEventCursorExpiredError,
+  FoirRequestError,
   ScopedTokenError,
   ServerClientError,
   createCallbackClient,
+  createEventsClient,
   createServerClient,
+  isFoirEventCursorExpired,
+  isFoirForbidden,
+  isFoirNotFound,
+  isFoirRateLimited,
+  isFoirUnauthenticated,
   parseContextHeader,
   parseSubject,
   recordsReadModels,

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

@@ -5,8 +5,9 @@
  *
  *   - `@foir/sdk/client` — `foirRequest`, which prints a `TypedDocumentNode` and
  *     POSTs it to `/graphql`. Needs `graphql` for `print`.
- *   - `@foir/sdk/data`   — `createFoirClient`, which POSTs a JSON op to
- *     `/v1/query` and must not pull `graphql` into a storefront bundle at all.
+ *   - `@foir/sdk/data`   — `createFoirClient`, which prints a document from a
+ *     selection tree and must not pull `graphql` into a storefront bundle at
+ *     all. Printing a pre-resolved tree is string building.
  *
  * The split exists so the second one is possible. The Foir-specific transport
  * concerns — which api key is in play, the preview schema channel header, the
@@ -196,11 +197,27 @@ export interface FoirHeaderInput {
 }
 /**
  * The exact header set every Foir data-plane request carries. Single
- * definition on purpose: `/graphql` and `/v1/query` authenticate identically,
+ * 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.
  */
 export declare function buildFoirHeaders(input: FoirHeaderInput): Record<string, string>;
+/**
+ * Build a `/v1/...` URL from whatever the caller put in `apiUrl`.
+ *
+ * Tolerates the three things people actually pass: an origin, an origin with a
+ * trailing slash, and the conventional `PLATFORM_API_URL` value
+ * (`https://api.foir.dev/graphql`).
+ *
+ * Lives here rather than beside one of its callers because three surfaces now
+ * turn an `apiUrl` into a path on the API origin — `@foir/sdk/data`'s `/graphql`,
+ * `@foir/sdk/server`'s `/v1/events`, and anything that follows — and the
+ * tolerated inputs are a property of the config field, not of the endpoint. A
+ * second copy would accept a slightly different set, and the difference would
+ * only ever show up as one surface rejecting a `PLATFORM_API_URL` the other
+ * accepted. `data/transport.ts` re-exports it under its published name.
+ */
+export declare function foirApiEndpoint(apiUrl: string, path: `/${string}`): string;
 export interface FoirResponseEnvelope<T> {
     data?: T;
     errors?: Array<FoirGraphQLErrorItem>;
@@ -210,8 +227,8 @@ export interface FoirResponseEnvelope<T> {
  *
  * 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. `/v1/query` compiles to a GraphQL
- * document and hands it to the same executor, so it returns the same envelope
- * and gets the same treatment.
+ * 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;