@foir/sdk 0.4.0 → 0.7.0

package/dist/react.js

@@ -12,10 +12,18 @@ import {
 } from "react";
 
 // src/graphql/foir-request.ts
+import { print as print2 } from "graphql";
+
+// src/graphql/cdn-route.ts
 import { print } from "graphql";
+
+// src/transport/foir-http.ts
 function isFoirPreview(env) {
   return env.FOIR_PREVIEW === "true";
 }
+function resolveFoirApiKey(env) {
+  return isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
+}
 var FoirRequestError = class extends Error {
   /** HTTP status code, when the request failed at the HTTP layer. */
   status;
@@ -29,41 +37,83 @@ var FoirRequestError = class extends Error {
     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;
+  }
 };
-async function foirRequest(env, document, variables, options) {
-  const endpoint = env.PLATFORM_API_URL;
-  const apiKey = isFoirPreview(env) ? env.PLATFORM_PREVIEW_API_KEY ?? env.PLATFORM_API_KEY : env.PLATFORM_API_KEY;
-  if (!endpoint || !apiKey) {
-    throw new FoirRequestError(
-      "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
-    );
+function readFoirRateLimit(headers) {
+  const raw = {
+    limit: headers.get("X-RateLimit-Limit"),
+    remaining: headers.get("X-RateLimit-Remaining"),
+    resetAt: headers.get("X-RateLimit-Reset")
+  };
+  if (raw.limit === null || raw.remaining === null || raw.resetAt === null) {
+    return void 0;
   }
+  const limit = Number(raw.limit);
+  const remaining = Number(raw.remaining);
+  const resetAt = Number(raw.resetAt);
+  if (!Number.isFinite(limit) || !Number.isFinite(remaining) || !Number.isFinite(resetAt)) {
+    return void 0;
+  }
+  return { limit, remaining, resetAt };
+}
+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": apiKey
+    "x-api-key": input.apiKey
   };
-  if (isFoirPreview(env)) {
+  if (input.draftChannel) {
     headers["X-Foir-Schema-Channel"] = "draft";
   }
-  if (options?.bearerToken) {
-    headers["Authorization"] = `Bearer ${options.bearerToken}`;
-  }
-  let res;
-  try {
-    res = await fetch(endpoint, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ query: print(document), variables })
-    });
-  } catch (err) {
-    throw new FoirRequestError("[foir] network error", { cause: err });
+  if (input.bearerToken) {
+    headers["Authorization"] = `Bearer ${input.bearerToken}`;
   }
-  if (!res.ok) {
-    throw new FoirRequestError(`[foir] HTTP ${res.status} ${res.statusText}`, {
-      status: res.status
-    });
+  if (input.extra) {
+    for (const [key, value] of Object.entries(input.extra)) {
+      headers[key] = value;
+    }
   }
-  const json = await res.json();
+  return headers;
+}
+function readFoirEnvelope(json) {
   if (json.errors?.length) {
     const msg = json.errors.map((e) => e.message).join("; ");
     if (json.data) {
@@ -80,6 +130,150 @@ async function foirRequest(env, document, variables, options) {
   return json.data;
 }
 
+// src/graphql/cdn-route.ts
+var CDN_PATH = "/cdn/graphql";
+function isCdnEligible(env, documentText, bearerToken) {
+  if (bearerToken) return false;
+  if (isFoirPreview(env)) return false;
+  const apiKey = resolveFoirApiKey(env);
+  if (!apiKey?.startsWith("pk_")) return false;
+  return !/\bmutation\b/.test(documentText);
+}
+function buildCdnUrl(endpoint, apiKey, hash, variables) {
+  const url = new URL(endpoint);
+  url.pathname = url.pathname.replace(/\/graphql\/?$/, "") + CDN_PATH;
+  url.searchParams.set("key", apiKey);
+  url.searchParams.set("extensions", JSON.stringify(persistedQueryExtension(hash)));
+  if (variables && Object.keys(variables).length > 0) {
+    url.searchParams.set("variables", JSON.stringify(variables));
+  }
+  return url.toString();
+}
+function persistedQueryExtension(hash) {
+  return { persistedQuery: { version: 1, sha256Hash: hash } };
+}
+async function documentHash(documentText) {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(documentText)
+  );
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var PERSISTED_QUERY_NOT_FOUND = "PERSISTED_QUERY_NOT_FOUND";
+var NOT_SHAREABLE = "NOT_SHAREABLE";
+
+// src/graphql/foir-request.ts
+async function foirRequest(env, document, variables, options) {
+  const endpoint = env.PLATFORM_API_URL;
+  const apiKey = resolveFoirApiKey(env);
+  if (!endpoint || !apiKey) {
+    throw new FoirRequestError(
+      "[foir] PLATFORM_API_URL or PLATFORM_API_KEY is not set \u2014 add them to .env"
+    );
+  }
+  const headers = buildFoirHeaders({
+    apiKey,
+    draftChannel: isFoirPreview(env),
+    bearerToken: options?.bearerToken
+  });
+  const documentText = print2(document);
+  let res;
+  try {
+    if (isCdnEligible(env, documentText, options?.bearerToken)) {
+      const hash = await documentHash(documentText);
+      let shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
+        method: "GET",
+        headers
+      });
+      if (await isPersistedQueryMiss(shared)) {
+        shared = await fetch(buildCdnUrl(endpoint, apiKey, hash, variables), {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            query: documentText,
+            variables,
+            extensions: persistedQueryExtension(hash)
+          })
+        });
+      }
+      if (await isSharedRefusal(shared)) {
+        res = await fetch(endpoint, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ query: documentText, variables })
+        });
+      } else {
+        res = shared;
+      }
+    } else {
+      res = await fetch(endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query: documentText, variables })
+      });
+    }
+  } catch (err) {
+    throw new FoirRequestError("[foir] network error", { cause: err });
+  }
+  options?.onRateLimit?.(readFoirRateLimit(res.headers));
+  if (!res.ok) {
+    const errors = await readErrorEnvelope(res);
+    const first = errors?.[0]?.message;
+    throw new FoirRequestError(
+      first ? `[foir] HTTP ${res.status} ${res.statusText}: ${first}` : `[foir] HTTP ${res.status} ${res.statusText}`,
+      { status: res.status, graphQLErrors: errors }
+    );
+  }
+  const json = await res.json();
+  return readFoirEnvelope(json);
+}
+async function readErrorEnvelope(res) {
+  let errors;
+  try {
+    const body = await res.json();
+    errors = body.errors;
+  } catch {
+    errors = void 0;
+  }
+  const headerRetryMs = readFoirRetryAfterMs(res.headers);
+  if (headerRetryMs === void 0) return errors;
+  const seconds = Math.round(headerRetryMs / 1e3);
+  if (!errors?.length) {
+    return [
+      {
+        message: res.statusText || `HTTP ${res.status}`,
+        extensions: { code: "RATE_LIMITED", retryAfter: seconds }
+      }
+    ];
+  }
+  if (errors[0].extensions?.retryAfter === void 0) {
+    errors[0] = {
+      ...errors[0],
+      extensions: { ...errors[0].extensions, retryAfter: seconds }
+    };
+  }
+  return errors;
+}
+async function isSharedRefusal(res) {
+  if (res.ok) return false;
+  try {
+    const body = await res.clone().json();
+    return body.errors?.some((e) => e.extensions?.code === NOT_SHAREABLE) ?? false;
+  } catch {
+    return false;
+  }
+}
+async function isPersistedQueryMiss(res) {
+  try {
+    const body = await res.clone().json();
+    return body.errors?.some(
+      (e) => e.extensions?.code === PERSISTED_QUERY_NOT_FOUND
+    ) ?? false;
+  } catch {
+    return false;
+  }
+}
+
 // src/auth/operations.ts
 import { parse } from "graphql";
 var AUTH_RESULT_FIELDS = "token refreshToken customerId email";
@@ -128,6 +322,16 @@ var AuthProvidersDocument = parse(
     authProviders { key name type isDefault }
   }`
 );
+var CustomerJoinWaitlistDocument = parse(
+  `mutation CustomerJoinWaitlist($email: String!) {
+    customerJoinWaitlist(email: $email) { id email status }
+  }`
+);
+var CustomerSignupContextDocument = parse(
+  `query CustomerSignupContext {
+    customerSignupContext { signupMode }
+  }`
+);
 
 // src/auth/auth.ts
 var TOKEN_KEY = "foir:token";

package/dist/{realtime.d.ts → realtime/index.d.ts}

@@ -1,6 +1,3 @@
-import * as Y from 'yjs';
-import { WebsocketProvider } from 'y-websocket';
-
 /**
  * @foir/sdk/realtime — optional thin web helper over y-websocket (EID-103).
  *
@@ -22,22 +19,45 @@ import { WebsocketProvider } from 'y-websocket';
  *
  * Wire-protocol contract: `docs/realtime-collab-contract.md` (EID-117).
  */
-
+import type * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
 type Awareness = WebsocketProvider['awareness'];
-interface RoomAddress {
+export interface RoomAddress {
     /** Room-type selector — e.g. `record`, `ephemeral`, `tilly_note`. */
     namespace: string;
-    /** Namespace-specific id. For `record`: `{modelKey}:{recordId}:{variantId}`. */
+    /**
+     * Namespace-specific id. For `record`: the triple
+     * `{modelKey}:{recordId}:{variantKey}` (contract §2).
+     *
+     * The third segment is the selected variant's HUMAN KEY — `vip`, `default`,
+     * or the reserved `live` — **never a variant row's id**. `default` is the key
+     * for a record on no variant, and the segment is positional, so it cannot be
+     * omitted (`page:rec_1:` is a different room and an empty part is rejected
+     * 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):
+     * 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).
+     *
+     * The address to send is the one the API advertises — the `collab` field on
+     * every public record type returns `{ enabled, wsUrl, roomName }`, where
+     * `roomName` is exactly this triple.
+     */
     id: string;
 }
-interface CollabPresence {
+export interface CollabPresence {
     id: string;
     name: string;
     /** Stable per-user colour; derived deterministically from `id` when omitted. */
     color?: string;
     [key: string]: unknown;
 }
-interface CollabPeer {
+export interface CollabPeer {
     /** The remote peer's y-awareness client id. */
     clientId: number;
     id: string;
@@ -45,7 +65,7 @@ interface CollabPeer {
     color?: string;
     [key: string]: unknown;
 }
-interface CreateCollabSessionOptions {
+export interface CreateCollabSessionOptions {
     /** Explicit realtime origin, e.g. `wss://realtime.foir.io`. Never derived from the API host. */
     url: string;
     /** Room address; built into the canonical bare `{namespace}/{id}` path. A raw string path is also accepted. */
@@ -65,7 +85,7 @@ interface CreateCollabSessionOptions {
     /** WebSocket implementation for non-browser runtimes. */
     WebSocketPolyfill?: typeof WebSocket;
 }
-type CollabEventMap = {
+export type CollabEventMap = {
     /** Connection status flipped. */
     status: {
         connected: boolean;
@@ -77,7 +97,7 @@ type CollabEventMap = {
     /** A `getToken()` (or other internal) error surfaced. */
     error: unknown;
 };
-interface CollabSession {
+export interface CollabSession {
     /** The underlying y-websocket provider (escape hatch). */
     readonly provider: WebsocketProvider;
     /** The y-awareness instance (escape hatch). */
@@ -99,13 +119,12 @@ interface CollabSession {
     destroy(): void;
 }
 /** Deterministic per-id presence colour (stable across sessions and clients). */
-declare function colorForId(id: string): string;
+export declare function colorForId(id: string): string;
 /** Build the canonical bare `{namespace}/{id}` room path (contract §2). */
-declare function roomPath(room: RoomAddress | string): string;
+export declare function roomPath(room: RoomAddress | string): string;
 /**
  * Create a collaboration session: a wrapped `y-websocket` provider that conforms
  * to the Foir realtime contract and keeps its auth token fresh for reconnects.
  */
-declare function createCollabSession(options: CreateCollabSessionOptions): CollabSession;
-
-export { type CollabEventMap, type CollabPeer, type CollabPresence, type CollabSession, type CreateCollabSessionOptions, type RoomAddress, colorForId, createCollabSession, roomPath };
+export declare function createCollabSession(options: CreateCollabSessionOptions): CollabSession;
+export {};

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

@@ -0,0 +1,92 @@
+/**
+ * Callback client for extensions running async operations.
+ *
+ * The platform dispatches with `mode='async'` and includes a `callback`
+ * block in the operation payload. The extension acks 202, kicks the work
+ * off in its own durable runtime (CF Queue, BullMQ, etc.), and later
+ * calls back with one of:
+ *
+ *   - `complete(result)` — operation succeeded; result conforms to the
+ *     operation's `output_schema` (per-op typed via codegen).
+ *   - `fail(code, message, opts?)` — operation failed; `retryable=true`
+ *     pushes a DLQ entry.
+ *   - `progress({pct, message, metadata})` — non-terminal update; the
+ *     monotonic guard at the platform DB layer drops out-of-order packets.
+ *   - `cancel()` — extension self-cancels (rare; admins normally drive
+ *     cancel via the admin app's ConnectRPC path).
+ *
+ * Each call carries:
+ *   - `Authorization: Bearer <callback.token>` — Ed25519 scoped token.
+ *   - `X-Foir-Signature: sha256=<hex>` — HMAC of the raw request body
+ *     keyed on the project's `operations.signing_secret`. The secret is
+ *     out-of-band (CLI publishes it to the extension on push); the SDK
+ *     only handles the HMAC computation.
+ *
+ * Both response body shape and content-type follow the GraphQL spec —
+ * extensions importing this client receive typed result data.
+ */
+import type { OperationCallback } from './operation-types.js';
+/** Shape of a successful response from any callback mutation. */
+export interface CallbackResult {
+    /**
+     * Status as seen by the platform AFTER the call. One of:
+     * pending|dispatched|running|completed|failed|cancelled|timed_out|progress_stale.
+     * Always set even on idempotent / cancelled calls.
+     */
+    status: string;
+    /**
+     * True when the admin cancelled the execution while the extension was
+     * processing — the platform refused to overwrite the cancelled state.
+     * Extensions should stop work and (optionally) call `fail('CANCELLED')`.
+     */
+    cancelled: boolean;
+    /**
+     * Progress mutations only: false when the monotonic guard rejected an
+     * out-of-order update. Extensions can use this to detect packet
+     * reordering without erroring; missing on complete/fail/cancel.
+     */
+    applied?: boolean;
+}
+/**
+ * Per-operation callback client. `TResult` is the operation's typed result
+ * shape — supply the type generated by graphql-codegen against the
+ * api-public schema (`Complete{Op}ExecutionMutationVariables['result']`).
+ */
+export interface CallbackClient<TResult = unknown> {
+    complete(result: TResult): Promise<CallbackResult>;
+    fail(code: string, message: string, opts?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    }): Promise<CallbackResult>;
+    /**
+     * Returns `{cancelled: true}` when the admin has cancelled — extension
+     * must stop work. `applied: false` means the monotonic guard dropped
+     * the update because pct was lower than the persisted value.
+     */
+    progress(update: {
+        pct?: number;
+        message?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<CallbackResult>;
+    cancel(): Promise<CallbackResult>;
+}
+/**
+ * Construct a callback client from the dispatch payload's callback block
+ * plus the runtime-provided execution id and signing secret.
+ *
+ * `executionId` comes from the same operation payload that delivered
+ * `callback`; pass them together so the SDK doesn't have to re-parse the
+ * payload structure on every call.
+ *
+ * `signingSecret` lives on the extension (set as `FOIR_SIGNING_SECRET` or
+ * equivalent env var). `foir push` writes it there from the project's
+ * signing secret, so it's available before any callback runs.
+ *
+ * `fetch` is overridable for testability and to support runtimes (CF
+ * Workers, Node) where `fetch` may not be the global.
+ */
+export declare function createCallbackClient<TResult = unknown>(callback: OperationCallback, opts: {
+    executionId: string;
+    signingSecret: string;
+    fetch?: typeof fetch;
+}): CallbackClient<TResult>;

package/dist/server/index.d.ts

@@ -0,0 +1,8 @@
+export { createServerClient, ServerClientError } from './server-client';
+export { verifyWebhookSignature } from './webhook-helpers';
+export { verifyScopedToken, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, type ScopedTokenClaims, type ScopedTokenSubject, type VerifyScopedTokenOptions, } from './verify-scoped-token';
+export { requireScopedToken, ScopedTokenError, type RequireScopedTokenOptions, type ScopedTokenIngress, } from './require-scoped-token';
+export type { ServerClient, ServerClientOptions, GraphQLResponse, EditorPlacement, } from './types';
+export type { OperationPayload, OperationTrigger, OperationRecordContext, OperationContext, OperationResult, OperationCallback, } from './operation-types';
+export { createCallbackClient } from './callback-client';
+export type { CallbackClient, CallbackResult } from './callback-client';

package/dist/server/operation-types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Type definitions for platform operations.
+ *
+ * These types match the platform's operation execution payload structure.
+ */
+/**
+ * Operation payload sent by the platform to extension endpoints.
+ *
+ * All operations receive this standardized payload structure regardless
+ * of how they're triggered (UI, API, lifecycle hook, schedule).
+ */
+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') */
+    operationKey: string;
+    /** How this operation was triggered */
+    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) */
+    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.
+     *
+     * Absent for SYNC operations — the extension returns its result in the
+     * HTTP response body and there's nothing to call back to.
+     */
+    callback?: OperationCallback;
+}
+/**
+ * Callback context the platform hands the extension when it dispatches an
+ * async-callback operation. Everything the extension needs to call back is
+ * here — endpoint, auth token, signing secret reference (the secret itself
+ * lives on the extension, set out of band; the platform only sends the
+ * token), and the per-op mutation names so the extension doesn't need to
+ * derive them from the operation key.
+ */
+export interface OperationCallback {
+    /** api-public GraphQL endpoint, e.g. https://api.foir.dev/graphql */
+    gqlEndpoint: string;
+    /** Bearer token for the Authorization header (Ed25519, single execution scope) */
+    token: string;
+    /** RFC3339 expiry — extensions can short-circuit work past this. */
+    expiresAt: string;
+    /** Per-op typed mutation names the extension should call back with. */
+    mutations: {
+        complete: string;
+        fail: string;
+        progress: string;
+        cancel: string;
+    };
+}
+/**
+ * Trigger information describing how the operation was invoked.
+ */
+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;
+}
+/**
+ * Record context provided when operation is triggered by a record event.
+ */
+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;
+    };
+}
+/**
+ * Platform context provided to all operations.
+ */
+export interface OperationContext {
+    /** Tenant ID */
+    tenantId: string;
+    /** Project ID */
+    projectId: string;
+    /** User ID (if user-triggered) */
+    userId?: string;
+    /** Customer ID (if customer-scoped operation) */
+    customerId?: string;
+    /** Locale code (if locale-specific) */
+    locale?: string;
+    /** Timestamp when operation was triggered */
+    timestamp: string;
+}
+/**
+ * Standard operation result shape.
+ *
+ * All operations should return this structure.
+ */
+export interface OperationResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Operation result data (if successful) */
+    result?: unknown;
+    /** Error information (if failed) */
+    error?: {
+        /** Error code (e.g., 'MISSING_INPUT', 'PROCESSING_FAILED') */
+        code: string;
+        /** Human-readable error message */
+        message: string;
+        /** Additional error details */
+        details?: Record<string, unknown>;
+    };
+    /** Optional metadata (timing, cost, etc.) */
+    metadata?: Record<string, unknown>;
+}