@foir/sdk 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,457 @@
+/**
+ * Server-side types for Foir Editor SDK.
+ *
+ * Used by Hono API backends that communicate with the platform.
+ */
+/** Options for creating a ServerClient. */
+interface ServerClientOptions {
+    /** Base URL for the platform API (e.g., 'https://api.example.com'). */
+    baseUrl: string;
+    /** Project-scoped API key (sk_* format). */
+    apiKey: string;
+    /**
+     * Optional config key. Retained for backwards compatibility with older
+     * extension scaffolds that pass it; the current client does not use it.
+     */
+    configKey?: string;
+}
+/**
+ * Where an editor iframe should appear in the admin record editor.
+ */
+interface EditorPlacement {
+    /** 'main-editor' replaces / augments the content tab; 'sidebar' renders in the sidebar. */
+    type: 'main-editor' | 'sidebar';
+    /** Full URL of the editor iframe. */
+    url: string;
+    /** Allowed postMessage origin (defaults to url origin). */
+    allowedOrigin?: string;
+    /** Iframe height: 'auto' (resize via postMessage), 'fill' (100%), or fixed px. */
+    height?: 'auto' | 'fill' | number;
+    /** Tab label for main-editor placements (defaults to config name). */
+    tabName?: string;
+    /** When true, hides the standard Content tab (main-editor only). */
+    hideContentTab?: boolean;
+    /** Which model keys this placement applies to; omit for all models. */
+    modelKeys?: string[];
+}
+/** GraphQL response shape. */
+interface GraphQLResponse<T = Record<string, unknown>> {
+    data: T | null;
+    errors?: Array<{
+        message: string;
+        locations?: Array<{
+            line: number;
+            column: number;
+        }>;
+        path?: Array<string | number>;
+        extensions?: Record<string, unknown>;
+    }>;
+}
+/** The ServerClient interface — runtime communication with the platform. */
+interface ServerClient {
+    /** Execute a GraphQL query against the platform public API. */
+    query<T = Record<string, unknown>>(query: string, variables?: Record<string, unknown>): Promise<GraphQLResponse<T>>;
+}
+
+/**
+ * Server-side client for runtime communication with the Foir platform.
+ *
+ * Used by config API backends (e.g., Hono servers) to query the platform
+ * GraphQL API at runtime. Provisioning (models, operations, schedules) is
+ * handled by `foir push`. Record writes from upstream sources go through
+ * the scoped-token `upsertRecord` GraphQL mutation served by the
+ * integrations gateway, not through this client.
+ *
+ * Auth: All requests use an API key (x-api-key header).
+ */
+
+/** Error thrown when a platform API request fails. */
+declare class ServerClientError extends Error {
+    status?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, response?: unknown | undefined);
+}
+/**
+ * Create a ServerClient for runtime platform communication.
+ *
+ * @example
+ * ```ts
+ * import { createServerClient } from '@foir/sdk/server';
+ *
+ * const client = createServerClient({
+ *   baseUrl: 'https://api.example.com',
+ *   apiKey: 'sk_project_xxx',
+ * });
+ *
+ * const { data } = await client.query('query { models { items { key } } }');
+ * ```
+ */
+declare function createServerClient(options: ServerClientOptions): ServerClient;
+
+/**
+ * Webhook verification helpers for extension API backends.
+ *
+ * Verifies HMAC-SHA256 signatures on incoming webhook requests
+ * from the EIDE platform.
+ *
+ * The platform sends two security headers:
+ * - `x-foir-signature`: HMAC-SHA256 hex signature of the request body
+ * - `x-foir-token`: Short-lived JWT (5min) containing extension context + API key
+ *
+ * Extensions should verify the signature and extract the API key from the token.
+ */
+/**
+ * Verify a webhook signature from the platform.
+ *
+ * The platform signs webhook payloads with HMAC-SHA256 using the
+ * extension's webhook secret. The signature is sent in the
+ * `x-foir-signature` header as a hex-encoded string.
+ *
+ * @example
+ * ```ts
+ * import { verifyWebhookSignature } from '@foir/sdk/server';
+ *
+ * app.post('/webhooks/entity-published', async (c) => {
+ *   const body = await c.req.text();
+ *   const signature = c.req.header('x-foir-signature') ?? '';
+ *
+ *   const valid = await verifyWebhookSignature(body, signature, WEBHOOK_SECRET);
+ *   if (!valid) return c.text('Invalid signature', 401);
+ *
+ *   const payload = JSON.parse(body);
+ *   // process webhook...
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
+
+/**
+ * Verify a Foir scoped-token JWT (Ed25519, EdDSA) using Web Crypto.
+ *
+ * Operation handlers receive this token in the `X-Foir-Token` header (the
+ * dispatch token authenticating the inbound request) or embedded in the
+ * dispatch envelope's `callback.token` field (the callback token used as
+ * Bearer for mid-execution GraphQL calls back to api-public). Replaces the
+ * legacy HMAC + shared-secret verification for operation dispatches — the
+ * handler no longer needs `FOIR_SIGNING_SECRET` for the inbound path, only
+ * the URL of the platform's JWKS endpoint
+ * (`https://api.foir.dev/.well-known/jwks.json`).
+ *
+ * Lifted verbatim from the inline implementations in
+ * belstaff-translation-portal/src/lib/verify-scoped-token.ts and
+ * hydrogen-storefront/app/lib/foir/verify-scoped-token.ts so consumers can
+ * drop their copies in favor of the shared export. JWKS keys are cached
+ * per-isolate via `globalThis`; TTL matches the endpoint's
+ * Cache-Control max-age (5 minutes).
+ */
+interface ScopedTokenClaims {
+    iss: string;
+    /**
+     * Pipe-delimited `<tenantId>|<projectId>|<appName>` triple. Use
+     * {@link parseSubject} to split into a typed object.
+     */
+    sub: string;
+    cap: Array<string>;
+    jti: string;
+    exp: number;
+    nbf: number;
+    iat: number;
+    ctx?: Record<string, string>;
+    /**
+     * Records-read model allow-list. Present when the operation declared one
+     * or more `records:read:<model>` capabilities. Pair with the
+     * `records:read` marker in {@link ScopedTokenClaims.cap} to authorize a
+     * record read for a specific model.
+     */
+    rrm?: Array<string>;
+    /**
+     * Records-write model allow-list. Present when the operation declared
+     * one or more `records:write:<model>` capabilities. Pair with the
+     * `records:write` marker in {@link ScopedTokenClaims.cap} to authorize
+     * a record write for a specific model.
+     */
+    rwm?: Array<string>;
+}
+interface ScopedTokenSubject {
+    tenantId: string;
+    projectId: string;
+    appName: string;
+}
+/**
+ * Parse the pipe-delimited `sub` claim emitted by the platform's
+ * scoped-token minter into its three components. Throws on a missing or
+ * empty segment — the platform never emits a partially-populated subject,
+ * so a malformed sub indicates a forged or corrupt token.
+ *
+ * @example
+ * ```ts
+ * const { tenantId, projectId, appName } = parseSubject(claims.sub);
+ * ```
+ */
+declare function parseSubject(sub: string): ScopedTokenSubject;
+/**
+ * Extract the `records:read:<model>` allow-list from a verified claim
+ * set. Returns an empty array when the token grants no per-model read
+ * capabilities. Convenience over reading {@link ScopedTokenClaims.rrm}
+ * directly, mirroring the platform's
+ * `scopedtoken.Claims.RecordsReadModels` field.
+ */
+declare function recordsReadModels(claims: ScopedTokenClaims): Array<string>;
+/**
+ * Extract the `records:write:<model>` allow-list from a verified claim
+ * set. Returns an empty array when the token grants no per-model write
+ * capabilities. Mirror of {@link recordsReadModels} for the write side.
+ */
+declare function recordsWriteModels(claims: ScopedTokenClaims): Array<string>;
+interface VerifyScopedTokenOptions {
+    /**
+     * Expected `iss` claim. Defaults to `'foir-platform'`, the issuer the
+     * platform's scoped-token minter uses. Override only when verifying
+     * tokens from a non-default issuer (test harnesses, alternate deploys).
+     */
+    expectedIssuer?: string;
+}
+/**
+ * Verify a scoped-token JWT against the platform's JWKS.
+ *
+ * Throws on malformed header, unknown kid, bad signature, missing/expired
+ * exp, future nbf (with 30s skew tolerance), or mismatched iss. Returns
+ * the decoded claim set on success.
+ */
+declare function verifyScopedToken(token: string, jwksUrl: string, options?: VerifyScopedTokenOptions): Promise<ScopedTokenClaims>;
+/**
+ * Parse the semicolon-delimited `X-Foir-Context` header the platform
+ * attaches to dispatched operation requests. Shape:
+ * `project=P;app=A;operation=O;triggered_by=T;execution_id=E;causation_chain=a,b,c`.
+ */
+declare function parseContextHeader(raw: string | null): Record<string, string>;
+
+/**
+ * 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).
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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>;
+}
+
+/**
+ * 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.
+ */
+
+/** Shape of a successful response from any callback mutation. */
+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']`).
+ */
+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). The CLI publishes it during `foir push` so it's
+ * available before any callback runs — see foir-cli writeConfigCredential.
+ *
+ * `fetch` is overridable for testability and to support runtimes (CF
+ * Workers, Node) where `fetch` may not be the global.
+ */
+declare function createCallbackClient<TResult = unknown>(callback: OperationCallback, opts: {
+    executionId: string;
+    signingSecret: string;
+    fetch?: typeof fetch;
+}): CallbackClient<TResult>;
+
+export { type CallbackClient, type CallbackResult, type EditorPlacement, type GraphQLResponse, type OperationCallback, type OperationContext, type OperationPayload, type OperationRecordContext, type OperationResult, type OperationTrigger, type ScopedTokenClaims, type ScopedTokenSubject, type ServerClient, ServerClientError, type ServerClientOptions, type VerifyScopedTokenOptions, createCallbackClient, createServerClient, parseContextHeader, parseSubject, recordsReadModels, recordsWriteModels, verifyScopedToken, verifyWebhookSignature };