@foir/sdk 0.4.0 → 0.7.0

package/dist/server/require-scoped-token.d.ts

@@ -0,0 +1,76 @@
+/**
+ * requireScopedToken — the one-line ingress guard for BFF routes the
+ * platform dispatches operations to (EID-498).
+ *
+ * Operation endpoints must be publicly reachable (the platform's dispatcher
+ * refuses private networks), so "the BFF is never public-facing" is achieved
+ * by AUTHENTICATED ingress, not network privacy: every route the platform
+ * calls verifies the platform-minted `X-Foir-Token` before doing anything. A
+ * route that skips verification is an open endpoint anyone can call
+ * directly, bypassing the operation's scopes, quotas, and preconditions.
+ *
+ * ```ts
+ * // Hono / Workers / Hydrogen — any fetch-API request:
+ * const { claims, subject, context } = await requireScopedToken(request, {
+ *   expectedProjectId: env.FOIR_PROJECT_ID,
+ * });
+ * ```
+ *
+ * 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:
+ *
+ * ```ts
+ * catch (err) {
+ *   if (err instanceof ScopedTokenError) {
+ *     return new Response(err.message, { status: err.status });
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+import type { ScopedTokenClaims, ScopedTokenSubject, VerifyScopedTokenOptions } from './verify-scoped-token';
+/**
+ * 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
+ * wrong tenant or project.
+ */
+export declare class ScopedTokenError extends Error {
+    readonly status: 401 | 403;
+    constructor(message: string, status: 401 | 403);
+}
+/** The minimal request shape needed — satisfied by any fetch-API Request. */
+export interface HeaderCarrier {
+    headers: {
+        get(name: string): string | null;
+    };
+}
+export interface RequireScopedTokenOptions extends VerifyScopedTokenOptions {
+    /**
+     * JWKS endpoint to verify against. Defaults to the production platform
+     * (`https://api.foir.dev/.well-known/jwks.json`); point it at your dev
+     * host's `/.well-known/jwks.json` for non-production deployments.
+     */
+    jwksUrl?: string;
+    /**
+     * When set, a verified token whose subject names a different project is
+     * rejected with 403. Set this from your deploy's own config — it pins the
+     * route to its project even if a token minted for another project leaks.
+     */
+    expectedProjectId?: string;
+    /** Tenant analogue of {@link expectedProjectId}. */
+    expectedTenantId?: string;
+}
+export interface ScopedTokenIngress {
+    claims: ScopedTokenClaims;
+    subject: ScopedTokenSubject;
+    /** Parsed `X-Foir-Context` correlation metadata (empty when absent). */
+    context: Record<string, string>;
+}
+/**
+ * Verify the platform-minted scoped token on an inbound dispatch request.
+ * Returns the decoded claims, parsed subject, and dispatch context; throws
+ * {@link ScopedTokenError} otherwise. See the module doc for the catch
+ * pattern.
+ */
+export declare function requireScopedToken(request: HeaderCarrier, options?: RequireScopedTokenOptions): Promise<ScopedTokenIngress>;

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

@@ -0,0 +1,34 @@
+/**
+ * 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).
+ */
+import type { ServerClient, ServerClientOptions } from './types';
+/** Error thrown when a platform API request fails. */
+export 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 } } }');
+ * ```
+ */
+export declare function createServerClient(options: ServerClientOptions): ServerClient;

package/dist/server/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Server-side types for Foir Editor SDK.
+ *
+ * Used by Hono API backends that communicate with the platform.
+ */
+/** Options for creating a ServerClient. */
+export 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.
+ */
+export 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. */
+export 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. */
+export 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>>;
+}

package/dist/server/verify-scoped-token.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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).
+ */
+export 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>;
+}
+export 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);
+ * ```
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function recordsWriteModels(claims: ScopedTokenClaims): Array<string>;
+export 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.
+ */
+export 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`.
+ */
+export declare function parseContextHeader(raw: string | null): Record<string, string>;

package/dist/server/webhook-helpers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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...
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;

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

@@ -0,0 +1,217 @@
+/**
+ * Foir HTTP transport core — the `graphql`-free half of `graphql/foir-request.ts`.
+ *
+ * Everything here is shared by BOTH public data surfaces:
+ *
+ *   - `@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.
+ *
+ * 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
+ * optional customer bearer, and the `FoirRequestError` shape — are identical on
+ * both, and duplicating them is exactly how the two surfaces would drift. So
+ * they live here once and `foir-request.ts` re-exports them unchanged; the only
+ * thing that stayed behind is the part that needs `print`.
+ *
+ * `fetch` only, no Node built-ins, and no module-level cache — the reasoning at
+ * the top of `graphql/foir-request.ts` applies verbatim: a shared cache on a
+ * stateless multi-tenant edge worker is a cross-tenant hazard.
+ */
+export interface FoirEnv {
+    PLATFORM_API_URL?: string;
+    PLATFORM_API_KEY?: string;
+    PLATFORM_PREVIEW_API_KEY?: string;
+    FOIR_PREVIEW?: string;
+}
+/**
+ * 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.
+ * 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
+ * otherwise. Returns `undefined` when neither is configured, so the caller can
+ * raise the "add them to .env" error with its own wording.
+ */
+export declare function resolveFoirApiKey(env: FoirEnv): string | undefined;
+/**
+ * The machine-readable codes Foir puts in `extensions.code`. Stable contract —
+ * the platform's own note on them says never rename — so branching on these is
+ * the supported way to tell one failure from another.
+ *
+ * Note what is NOT here: there is no code for a missing record. A read that
+ * finds nothing resolves the field to `null` with no `errors` entry at all,
+ * because an absent record is an answer rather than a failure. `NOT_FOUND` only
+ * appears when a mutation names something that does not exist.
+ */
+export type FoirErrorCode = 'INVALID_ARGUMENT' | 'NOT_FOUND' | 'ALREADY_EXISTS' | 'FAILED_PRECONDITION' | 'PERMISSION_DENIED' | 'UNAUTHENTICATED' | 'RATE_LIMITED' | 'TIMEOUT' | 'UNAVAILABLE' | 'CANCELED' | 'INTERNAL';
+export interface FoirErrorExtensions {
+    /** Stable machine-readable code. Branch on this, never on `message`. */
+    code?: FoirErrorCode | string;
+    /** Correlation id. Quote it in a support request. */
+    requestId?: string;
+    /** On `RATE_LIMITED`: whole seconds to wait. Never less than 1. */
+    retryAfter?: number;
+    [key: string]: unknown;
+}
+export interface FoirGraphQLErrorItem {
+    message: string;
+    path?: Array<string | number>;
+    extensions?: FoirErrorExtensions;
+}
+/** What the `X-RateLimit-*` headers said on the response that carried them. */
+export interface FoirRateLimitSnapshot {
+    /** Requests allowed per window for this credential. */
+    limit: number;
+    /** Requests left in the current window. */
+    remaining: number;
+    /** Unix seconds at which the window resets. */
+    resetAt: number;
+}
+export declare class FoirRequestError extends Error {
+    /** HTTP status code, when the request failed at the HTTP layer. */
+    readonly status?: number;
+    /** GraphQL errors, when the request failed with a no-data error envelope. */
+    readonly graphQLErrors?: ReadonlyArray<FoirGraphQLErrorItem>;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        status?: number;
+        graphQLErrors?: ReadonlyArray<FoirGraphQLErrorItem>;
+    });
+    /**
+     * 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(): FoirErrorCode | string | undefined;
+    /** The correlation id, if the response carried one. */
+    get requestId(): string | undefined;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): number | undefined;
+}
+/** True when the failure is Foir refusing on rate. */
+export declare function isFoirRateLimited(err: unknown): err is FoirRequestError;
+/**
+ * True when the credential was rejected. Distinguished from
+ * {@link isFoirRateLimited} because the two want opposite responses: a bad key
+ * is never going to start working, and retrying it just spends allowance.
+ */
+export declare function isFoirUnauthenticated(err: unknown): err is FoirRequestError;
+/** True when the credential is valid but not permitted to do this. */
+export declare function isFoirForbidden(err: unknown): err is FoirRequestError;
+/**
+ * True when a MUTATION named something that does not exist.
+ *
+ * Reads do not produce this. A read for a record that is not there resolves the
+ * field to `null` and returns no error at all, so `data.page === null` is the
+ * check for a missing page — not a catch.
+ */
+export declare function isFoirNotFound(err: unknown): err is FoirRequestError;
+/**
+ * Read the `X-RateLimit-*` headers off a response, when it carried them.
+ *
+ * The presence check is not defensive padding. `Number(null)` is 0, not NaN, so
+ * reading a missing header through `Number` alone yields a perfectly plausible
+ * snapshot saying zero requests remain — on every response from anything that
+ * does not set these headers, including a cache or a proxy in front of Foir. An
+ * app wired to warn on a low remaining count would then warn constantly, which
+ * is how a rate-limit alarm becomes noise people mute.
+ */
+export declare function readFoirRateLimit(headers: Headers): FoirRateLimitSnapshot | undefined;
+/**
+ * Seconds the server asked the caller to wait, from a 429's `Retry-After`
+ * header. Undefined when absent or unparseable.
+ *
+ * Read alongside `extensions.retryAfter`, which carries the same number in the
+ * body; the header is the one available when the body is unreadable.
+ */
+export declare function readFoirRetryAfterMs(headers: Headers): number | undefined;
+export interface FoirRequestOptions {
+    /**
+     * Customer bearer token. api-public still needs the `x-api-key` to resolve
+     * the project; the bearer adds the customer identity for self-scoped reads
+     * (e.g. `myProfile`). Used by `@foir/sdk/auth`'s post-login profile fetch.
+     */
+    bearerToken?: string;
+    /**
+     * Called with the `X-RateLimit-*` headers of every response, successful or
+     * not, and with `undefined` when a response carried none.
+     *
+     * Exists because those headers have always been on the wire and nothing has
+     * ever read them. A key can be at 200 of 10,000 remaining for twenty minutes
+     * before it starts refusing, and the only place that number appears is a
+     * header the SDK was throwing away. Log it, and you find out before your site
+     * does.
+     */
+    onRateLimit?: (snapshot: FoirRateLimitSnapshot | undefined) => void;
+}
+/**
+ * Supplies the current customer bearer. Sync or async so consumers can read a
+ * cookie session (Hydrogen/Remix), a KV store, an in-memory value, etc. Returns
+ * the token when signed in, or `null`/`undefined` when signed out.
+ *
+ * Lives here rather than beside `createFoirContentClient` because both data
+ * surfaces bind a session the same way, and a second copy of this alias is how
+ * they would end up accepting subtly different things.
+ */
+export type FoirTokenProvider = () => string | null | undefined | Promise<string | null | undefined>;
+export interface FoirHeaderInput {
+    apiKey: string;
+    /**
+     * Opt into the draft *schema* channel (`X-Foir-Schema-Channel: draft`) so
+     * freshly pushed model changes (new fields, new models) are visible at
+     * runtime — otherwise selections on draft-only fields are silently stripped
+     * and surface as confusing "fragment never used" errors. The header has no
+     * effect under public keys (the server ignores it), so it is safe to send
+     * whenever the caller is in preview.
+     */
+    draftChannel?: boolean;
+    bearerToken?: string;
+    /** Caller-supplied extras, applied last so a caller can override. */
+    extra?: Readonly<Record<string, string>>;
+}
+/**
+ * The exact header set every Foir data-plane request carries. Single
+ * definition on purpose: `/graphql` and `/v1/query` 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>;
+export interface FoirResponseEnvelope<T> {
+    data?: T;
+    errors?: Array<FoirGraphQLErrorItem>;
+}
+/**
+ * Unwrap a Foir `{ data, errors }` envelope.
+ *
+ * GraphQL can return partial data alongside errors; when data is present the
+ * errors are logged and the data returned (callers handle nulls), and we only
+ * throw when there is no data at all. `/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.
+ */
+export declare function readFoirEnvelope<T>(json: FoirResponseEnvelope<T>): T;

package/dist/transport/retry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Retry for the Foir data plane.
+ *
+ * It lives in the SDK rather than in a docs snippet because the snippet was
+ * getting written wrong. The rule everyone reaches for — retry 5xx, never retry
+ * 4xx — is right about every 4xx except the one that matters: a 429 means the
+ * key has spent its hourly allowance, the request is fine, and it will succeed
+ * once the window moves. A storefront implemented that rule faithfully, covering
+ * 502/503/504 only, and when its key saturated every read failed on the first
+ * attempt for a full hour. The reads it failed were rendering pages, and the
+ * pages came out empty.
+ *
+ * So the policy is: retry on no-response, on 5xx, and on 429 — and when the
+ * server said how long to wait, wait that long instead of guessing.
+ */
+import { FoirRequestError } from './foir-http';
+export interface FoirRetryPolicy {
+    /**
+     * Total attempts including the first. 1 disables retrying without needing a
+     * separate flag, which is what makes "off" expressible in the same shape.
+     */
+    attempts?: number;
+    /** Base delay for exponential backoff, in ms. Default 200. */
+    baseDelayMs?: number;
+    /**
+     * Ceiling on any single wait, in ms. Default 20_000.
+     *
+     * A rate-limit window is an hour, so a `Retry-After` on a saturated key can
+     * be most of one — far longer than a page render can wait. Capping it means a
+     * retry is attempted rather than the caller blocking for 40 minutes, and if
+     * that attempt fails too the error surfaces, which is the honest outcome. A
+     * caller that genuinely can wait sets a larger cap.
+     */
+    maxDelayMs?: number;
+    /** Called before each wait. For logging; must not throw. */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: FoirRequestError;
+    }) => void;
+    /** Injectable sleep, so tests do not spend real seconds. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * How long to wait before attempt N+1, or null when this error should not be
+ * retried at all.
+ *
+ * Exported so a caller running its own loop gets the same answer as the built-in
+ * one; two implementations of "is this worth retrying" is how the 429 gets left
+ * out of one of them.
+ */
+export declare function foirRetryDelayMs(error: unknown, attempt: number, policy?: FoirRetryPolicy): number | null;
+/**
+ * Run `fn`, retrying transient Foir failures.
+ *
+ * Deliberately takes a thunk rather than wrapping a specific request shape, so
+ * the same policy covers `/graphql` and `/v1/query` and anything either grows
+ * later. Non-Foir errors propagate untouched on the first throw — this is not a
+ * general-purpose retry helper and should not become one.
+ */
+export declare function withFoirRetry<T>(fn: () => Promise<T>, policy?: FoirRetryPolicy): Promise<T>;