@storystick/client 0.0.0-stage → 0.2.0-rc.0

package/LICENSE

@@ -0,0 +1,112 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Tanguy Freycon
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This Agreement shall be governed by the laws of France.

package/PUBLIC-API.md

@@ -0,0 +1,22 @@
+# @storystick/client API contract
+
+Install this candidate explicitly with `@storystick/client@0.2.0-rc.0` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
+
+Version 0.2.0-rc.0, cohort `sdk-0.2.0-rc.0`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
+
+This package is a product integration facade. Reserved contracts are required between SDK packages and must be upgraded with the same cohort. Their public export paths do not promise independent stability.
+
+| Entry | Status |
+| --- | --- |
+| `.` | Supported beta entry |
+| `./internal` | Reserved SDK contract |
+| `./normalize-pathname` | Supported beta entry |
+| `./locale-routing` | Supported beta entry |
+| `./adapter` | Reserved SDK contract |
+| `./seo` | Supported beta entry |
+
+The qualified toolchain is Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
+
+Use a generated Query V2 definition. A missing document/singleton returns null, an empty collection returns an empty array, and fetch throws on blocked/degraded execution. Execute exposes the complete result envelope. RSC metadata must remain plain JSON data; request authority must not be stored in shared module state.
+
+The repository is private. Public package availability does not make the monorepo public, and npm provenance from that repository is unavailable. Product and pilot support: [Storystick](https://storystick.app).

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# @storystick/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The generated, typed Query V2 client and universal Content Plane transport.
+
+```bash
+pnpm add @storystick/client@beta
+pnpm add -D @storystick/cli@beta
+pnpm storystick generate
+```
+
+```ts
+import { createClient } from '@storystick/client'
+import { querySchema } from '@/generated/storystick/query'
+
+const client = createClient({
+  schema: querySchema,
+  projectId: process.env.STORYSTICK_PROJECT_ID!,
+  apiKey: process.env.STORYSTICK_API_KEY!,
+})
+
+const posts = await client.query('blogPost')
+  .select({ title: true, slug: true })
+  .page({ first: 20 })
+  .fetch()
+```
+
+`.fetch()` returns exact data and throws `QueryExecutionError` for degraded or
+blocked results. Missing addressed documents return `null`; empty collection
+pages return `[]`. Use `.execute()` when you need the full envelope, pagination
+cursor or diagnostics, and inspect `exactness` before using its data.
+
+## Publication languages in collections
+
+In public queries, `.locale('fr')` includes only documents with an active French
+publication. To allow another published language for this collection, opt in:
+
+```ts
+const result = await client.query('blogPost')
+  .select({ title: true })
+  .locale('fr')
+  .publicationFallback('configured')
+  .page({ first: 20 })
+  .execute()
+```
+
+The server chooses one publication per document: French first, then the project's
+configured fallback languages. It applies content filters and sorting to that
+chosen publication before counting and paginating. It never substitutes a draft.
+`result.pageInfo.totalCount` gives the exact matching count before pagination
+when available; blocked results omit it. `result.meta.locale.requested` keeps the
+requested language and each document's `_locale.code` identifies its actual
+publication language.
+
+Omitting `.publicationFallback(...)` or passing `'none'` keeps the default local
+selection. This choice is separate from field inheritance inside a publication.
+It applies only to public collections; addressed reads and authorized Preview
+continue to use their existing read scopes. Preview does not use publication
+fallback to fill gaps in the working content.
+
+Publication changes or a different collection policy invalidate an existing
+cursor. Restart from the first page after `QUERY_CURSOR_INVALID`; do not merge
+pages from different publication states. This option does not create translated
+routes or change link resolution.
+
+Update the backend and SDK together: the closed Query V2 response now includes
+`totalCount` on computed collection pages, which older SDK validators reject.
+
+The client is framework-neutral and can run in Node, browser loaders or other
+server frameworks. Use a server API key only on the server; use a publishable
+key for public browser reads. Preview request authority is supplied by the
+framework's authorized request adapter, not by a document or URL parameter.
+
+The generated story definition is carried all the way to the result. A
+`selectAll()` document has the exact generated document fields; a narrowed
+`select(...)` result exposes only the selected fields, with the same optionality
+as the Story contract. No result cast is required.
+
+Reference values remain document IDs in ordinary fields. Resolve them against
+the delivery sidecar when a renderer needs a target address:
+
+```ts
+import { resolveReference, resolveReferences } from '@storystick/client'
+
+const author = resolveReference(querySchema, 'author', post.fields.author, {
+  source: post,
+  path: 'author',
+})
+
+if (author.status === 'ok') {
+  console.log(author.document.resolvedPathname)
+}
+
+const related = resolveReferences(
+  querySchema,
+  'blogPost',
+  post.fields.relatedPosts,
+  { source: post, path: 'relatedPosts' },
+)
+```
+
+Both helpers return one discriminated outcome per input (`ok`, `empty`,
+`missing`, `archived`, `unpublished`, `no-sidecar`, `wrong-type`, or
+`ambiguous`, plus `pinnedSnapshotMissing` and `pinnedSnapshotMismatch`). Array
+resolution preserves order. The generated schema fixes the target document
+type, so an `ok` result is typed without an application-owned lookup table.
+
+`PathnameValue` describes the structured editorial pathname field. Use the
+separate `resolvedPathname` delivery-envelope string for routing. `safeHref()`
+is the fail-closed URL boundary for app-owned anchors; it accepts relative URLs
+and `http`, `https`, `mailto`, and `tel`, and rejects unsafe protocols.
+
+`storystick generate` writes `generated/storystick/query.ts` (alongside the
+other generated Storystick files). The `@/generated/storystick/query` import
+above assumes the standard `@/*` project alias; use the equivalent relative
+path if your project does not define it.
+
+The generated schema controls story names, selections, filters, sorting and
+addressing at compile time and is validated again at runtime.
+
+Reusable selections are ordinary generated TypeScript values. They preserve
+their exact result type without introducing another query language:
+
+```ts
+import { defineSelection } from '@/generated/storystick/query'
+
+export const postCard = defineSelection('blogPost', {
+  title: true,
+  slug: true,
+  coverImage: true,
+})
+
+const posts = await client.query('blogPost').select(postCard).fetch()
+```
+
+The generated query definition is self-contained and has no runtime import from
+this package. Framework adapters can therefore own compatible client versions
+without making their internal package graph part of application setup.
+
+Licensed under [FSL-1.1-MIT](./LICENSE).
+
+`resolveReference` resolves address/identity metadata from a sidecar. It does not
+promise the target's fields. Use `query(...).select({ relation: { resolve: ... } })`
+or an explicit target query to read typed content.
+
+The HTTP transport reserves status 200 for exact results. Non-exact Query V2
+results use 503 when retryable or 422 otherwise, with `private, no-store`, so
+native fetch caches do not retain them. `.execute()` still returns their full
+envelope; `.fetch()` throws `QueryExecutionError`. Preview always bypasses the
+persistent fetch cache. A subsequent read can recover without clearing caches.
+
+## Read representation
+
+Query V2 keeps the same selection syntax. Selecting a composition also loads its
+bounded rendering dependencies (bindings, model fields and mapped zones).
+Unselected host fields stay absent from `fields`; they are carried in the
+internal versioned render plan. Scalar-only reads do not expand compositions.
+
+SDK content objects carry JSON-safe `__ssContent` metadata, so they can be moved,
+filtered or sent to a client component without passing their owning document as
+technical context. Richtext reads return a ProseMirror `doc` object. Authored
+storage remains serialized; do not write SDK rendering metadata into content.
+
+An incompatible backend without the render plan fails with
+`storystick/CONTENT_PROTOCOL`. Upgrade backend and SDK together and let the
+Content Plane reconcile its projection; do not republish user documents to
+repair an old projection. This pre-launch contract has no legacy fallback.
+
+## Adapter boundaries
+
+Application code uses the root content API above. Framework infrastructure such
+as HTTP transport construction, project discovery and route resolution lives at
+`@storystick/client/adapter`. Studio-only target resolution remains on the
+existing internal entry. Those boundaries are for Storystick adapters and
+tooling. They are intentionally absent from the root API so ordinary content
+code does not inherit deployment or Studio concepts.
+
+## Candidate distribution contract
+
+See [PUBLIC-API.md](./PUBLIC-API.md) for supported entries, reserved SDK contracts,
+the qualified runtime matrix and the candidate cohort. Upgrade Storystick
+packages together.

package/dist/.source-hash

@@ -0,0 +1 @@
+e9b1f5ad508349c6004d7e10c0272e3d09bbce936e2556b3c8e7d474d778c994

package/dist/_fetchers.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Token fetchers — two origins, one result shape (ADR-045 §4, §11.1).
+ *
+ * - `apiKeyFetcher({ gatewayUrl, apiKey })` — explicit machine delegation.
+ *   Calls `POST /api/tokens/issue` with Bearer <apiKey>. Used by mutation/import
+ *   consumers. Ordinary HTTP reads authenticate directly in `transport.ts`.
+ *
+ * - `userSessionFetcher({ gatewayUrl, getSessionToken, projectId })` —
+ *   Studio flow. Calls `POST /api/tokens/issue-for-user` with the caller's
+ *   Convex Auth session token + the target projectId in the body.
+ *
+ * Both produce `{ token, expiresAt }` consumed by the state machine.
+ * Both attach the §11.5 CSRF headers (`X-Storystick-Client`, credentialed
+ * CORS) so they succeed against the gateway's three-layer defense.
+ *
+ * Errors: if the gateway replies non-2xx, we throw an `SdkError`-shaped
+ * `Error` with `.code` set to the gateway's ConvexError code. The state
+ * machine inspects `.code` to decide DEAD vs refreshable (see §13.3).
+ */
+import type { TokenFetcher } from './_stateMachine.js';
+export interface ApiKeyFetcherOptions {
+    /** Central gateway URL, e.g. `https://<name>.convex.site`. */
+    gatewayUrl: string;
+    /** The caller's long-lived API key (`ss_sk_live_*` or `ss_pk_live_*`). */
+    apiKey: string;
+    /** Client tag for the CSRF stack. Default: `"sdk"`. */
+    client?: 'sdk' | 'hub' | 'studio' | 'ops';
+    /** Exact customer application build to pair with a schema generation. */
+    applicationBuildId?: string;
+    /**
+     * Optional override of `globalThis.fetch`, including for isolated tests.
+     */
+    fetchImpl?: typeof fetch;
+}
+export declare function apiKeyFetcher({ gatewayUrl, apiKey, client, applicationBuildId, fetchImpl, }: ApiKeyFetcherOptions): TokenFetcher;
+export interface UserSessionFetcherOptions {
+    /** Central gateway URL, e.g. `https://<name>.convex.site`. */
+    gatewayUrl: string;
+    /**
+     * Returns the caller's current Convex Auth session token. Called on
+     * every fetch (cheap — usually a ref-read). Return `null` when the user
+     * is not signed in; the fetcher will throw `UNAUTHENTICATED`, which the
+     * state machine will surface.
+     */
+    getSessionToken: () => string | null;
+    /** The project the caller is asking a scope for. */
+    projectId: string;
+    /** Client tag for the CSRF stack. Default: `"studio"`. */
+    client?: 'studio' | 'hub' | 'ops';
+}
+export declare function userSessionFetcher({ gatewayUrl, getSessionToken, projectId, client, }: UserSessionFetcherOptions): TokenFetcher;

package/dist/_fetchers.js

@@ -0,0 +1,144 @@
+/**
+ * Token fetchers — two origins, one result shape (ADR-045 §4, §11.1).
+ *
+ * - `apiKeyFetcher({ gatewayUrl, apiKey })` — explicit machine delegation.
+ *   Calls `POST /api/tokens/issue` with Bearer <apiKey>. Used by mutation/import
+ *   consumers. Ordinary HTTP reads authenticate directly in `transport.ts`.
+ *
+ * - `userSessionFetcher({ gatewayUrl, getSessionToken, projectId })` —
+ *   Studio flow. Calls `POST /api/tokens/issue-for-user` with the caller's
+ *   Convex Auth session token + the target projectId in the body.
+ *
+ * Both produce `{ token, expiresAt }` consumed by the state machine.
+ * Both attach the §11.5 CSRF headers (`X-Storystick-Client`, credentialed
+ * CORS) so they succeed against the gateway's three-layer defense.
+ *
+ * Errors: if the gateway replies non-2xx, we throw an `SdkError`-shaped
+ * `Error` with `.code` set to the gateway's ConvexError code. The state
+ * machine inspects `.code` to decide DEAD vs refreshable (see §13.3).
+ */
+import { contentShapeCapabilityHeaders, } from '@storystick/types';
+function makeSdkError(code, message, opts = {}) {
+    const refLine = opts.ref
+        ? `\n\nReference ID: ${opts.ref}\nShare this with support when reporting this issue.`
+        : '';
+    const err = new Error(`${message}${refLine}`);
+    err.code = code;
+    if (opts.ref !== undefined)
+        err.ref = opts.ref;
+    if (opts.payload !== undefined)
+        err.payload = opts.payload;
+    if (opts.category !== undefined)
+        err.category = opts.category;
+    if (opts.recoverable !== undefined)
+        err.recoverable = opts.recoverable;
+    if (opts.retryable !== undefined)
+        err.retryable = opts.retryable;
+    return err;
+}
+async function readTokenResponse(response) {
+    if (!response.ok) {
+        const body = (await response
+            .json()
+            .catch(() => ({})));
+        const wrapped = body.error;
+        const code = wrapped?.code ?? body.code ?? `HTTP_${response.status}`;
+        const message = wrapped?.message ??
+            body.message ??
+            `Gateway returned HTTP ${response.status} without a body.`;
+        throw makeSdkError(code, message, {
+            ref: wrapped?.ref,
+            payload: wrapped?.payload,
+            category: wrapped?.category,
+            recoverable: wrapped?.recoverable,
+            retryable: wrapped?.retryable,
+        });
+    }
+    const body = (await response.json());
+    if (!body.token || typeof body.token !== 'string') {
+        throw makeSdkError('storystick/INVALID_GATEWAY_RESPONSE', 'Gateway returned 200 without a `token` field.', { category: 'system', recoverable: false, retryable: false });
+    }
+    return {
+        token: body.token,
+        expiresAt: Date.now() + body.expiresIn * 1000,
+        ...(typeof body.contentShapeCapability === 'string' &&
+            body.contentShapeCapability.length > 0
+            ? { contentShapeCapability: body.contentShapeCapability }
+            : {}),
+    };
+}
+export function apiKeyFetcher({ gatewayUrl, apiKey, client = 'sdk', applicationBuildId, fetchImpl, }) {
+    const fetchFn = fetchImpl ?? globalThis.fetch.bind(globalThis);
+    let retainedContentShapeCapability;
+    let initialMint;
+    const surface = 'api';
+    return async () => {
+        if (!retainedContentShapeCapability && initialMint)
+            return initialMint;
+        const mint = (async () => {
+            const response = await fetchFn(`${gatewayUrl}/api/tokens/issue`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                    'X-Storystick-Client': client,
+                    ...contentShapeCapabilityHeaders(surface, retainedContentShapeCapability, applicationBuildId),
+                },
+            });
+            const result = await readTokenResponse(response);
+            retainedContentShapeCapability ??= result.contentShapeCapability;
+            return result;
+        })();
+        if (!retainedContentShapeCapability)
+            initialMint = mint;
+        try {
+            return await mint;
+        }
+        finally {
+            if (initialMint === mint)
+                initialMint = undefined;
+        }
+    };
+}
+export function userSessionFetcher({ gatewayUrl, getSessionToken, projectId, client = 'studio', }) {
+    let retainedContentShapeCapability;
+    let initialMint;
+    const surface = client === 'studio' ? 'studio' : 'api';
+    return async () => {
+        if (!retainedContentShapeCapability && initialMint)
+            return initialMint;
+        const session = getSessionToken();
+        if (!session) {
+            throw makeSdkError('storystick/UNAUTHENTICATED', 'Not signed in.', {
+                category: 'auth',
+                recoverable: true,
+                retryable: false,
+            });
+        }
+        const mint = (async () => {
+            const response = await fetch(`${gatewayUrl}/api/tokens/issue-for-user`, {
+                method: 'POST',
+                credentials: 'include',
+                headers: {
+                    Authorization: `Bearer ${session}`,
+                    'Content-Type': 'application/json',
+                    'X-Storystick-Client': client,
+                    ...contentShapeCapabilityHeaders(surface, retainedContentShapeCapability),
+                },
+                body: JSON.stringify({ projectId }),
+            });
+            const result = await readTokenResponse(response);
+            retainedContentShapeCapability ??= result.contentShapeCapability;
+            return result;
+        })();
+        if (!retainedContentShapeCapability)
+            initialMint = mint;
+        try {
+            return await mint;
+        }
+        finally {
+            if (initialMint === mint)
+                initialMint = undefined;
+        }
+    };
+}

package/dist/_stateMachine.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Storystick SDK token state machine (ADR-045 §13).
+ *
+ * Pure state, zero Convex dep. Given a pluggable `fetcher` that returns
+ * `{ token, expiresAt }` from any issuance endpoint, the machine:
+ *
+ * 1. **Opportunistic JIT refresh** (§13.1) — on every `ensureToken()` call,
+ *    if the cached token has ≤ `margin` seconds left, refresh BEFORE returning.
+ *    Jitter on the margin per instance so a fleet cold-start doesn't thunder
+ *    the gateway all at once.
+ * 2. **Single-flight coalescing** (§13.2) — N concurrent calls during a
+ *    refresh share the same `pendingRefresh` promise, one HTTP call out.
+ * 3. **DEAD state** (§13.3) — hard-auth errors (INVALID_API_KEY, revoked,
+ *    expired, not-a-member) lock the machine; all subsequent calls throw
+ *    immediately. Exit only via explicit `reset()`.
+ * 4. **Reactive 401 backstop** — exposed as `forceRefresh()` for the wire
+ *    layer to call when a Convex query returns 401 in-flight.
+ *
+ * Not included here on purpose: the transient-error backoff (§13.7) lives
+ * in the wire layer (Convex client's built-in retry), not in this file.
+ */
+export interface TokenFetchResult {
+    /** The compact JWT. */
+    token: string;
+    /** Absolute unix-ms at which the token expires. Used to compute margin. */
+    expiresAt: number;
+    /** Opaque first-epoch capability retained by the fetcher across refreshes. */
+    contentShapeCapability?: string;
+}
+/**
+ * A token fetcher — the only thing the state machine needs from the
+ * outside. Keeps the state machine reusable across API-key and
+ * user-session origins.
+ */
+export type TokenFetcher = () => Promise<TokenFetchResult>;
+/**
+ * Boundary error codes the state machine knows about. Post ADR-079 batch 5
+ * the codes are namespaced (`storystick/<NAME>`) ; the legacy-bare aliases
+ * are tolerated for the gateway-rollout window (matches `_fetchers.ts`'s
+ * dual-shape acceptance).
+ */
+export type StateMachineErrorCode = 'storystick/TOKEN_EXPIRED' | 'storystick/INVALID_TOKEN' | 'storystick/UNAUTHENTICATED' | 'storystick/VERIFY_UNAVAILABLE' | 'storystick/RATE_LIMITED' | 'storystick/INVALID_API_KEY' | 'storystick/API_KEY_REVOKED' | 'storystick/API_KEY_EXPIRED' | 'storystick/NOT_A_MEMBER' | 'storystick/ACCESS_DENIED' | 'storystick/CSRF_ORIGIN_REJECTED' | 'storystick/CSRF_CLIENT_HEADER_MISSING';
+/**
+ * SDK-side error class. Post ADR-079 batch 5 enriched with canonical
+ * envelope metadata (`category`, `recoverable`, `retryable`, `payload`) when
+ * the gateway response carried them — see `_fetchers.ts`. The state
+ * machine's `isHardAuthError` / `isRefreshableError` prefer these
+ * canonical fields over the hardcoded code list (Tension #5 lock B).
+ */
+export interface SdkError extends Error {
+    code?: StateMachineErrorCode | string;
+    /**
+     * Gateway-issued ref ID (SPEC-1 Item #6 — ops-error-reporting). Populated
+     * when the gateway responded with a `{ error: { ref } }` body. Present
+     * on every non-2xx response from up-to-date deployments; absent for
+     * local validation errors that never hit the gateway.
+     */
+    ref?: string;
+    /** Canonical category from the gateway envelope (post ADR-079 batch 4). */
+    category?: 'validation' | 'conflict' | 'auth' | 'system' | 'cancel';
+    /** True if the user can fix the cause and retry. */
+    recoverable?: boolean;
+    /** True if the SDK / CLI can auto-retry without user input. */
+    retryable?: boolean;
+    /** Per-code structured payload from the gateway envelope. */
+    payload?: unknown;
+}
+export interface TokenStateMachine {
+    /** Get a valid token, refreshing opportunistically if near expiry. */
+    ensureToken(): Promise<string>;
+    /** Bypass cache and force a refresh (reactive 401 backstop). */
+    forceRefresh(): Promise<string>;
+    /** Clear DEAD state. The next `ensureToken()` will attempt to refresh. */
+    reset(): void;
+    /** True if the last hard-auth error has locked the machine. */
+    isDead(): boolean;
+}
+export interface CreateStateMachineOptions {
+    fetcher: TokenFetcher;
+    /** Override the jitter base for tests. Default: 60s ± 10s. */
+    marginSecondsOverride?: number;
+}
+/**
+ * Construct a fresh state machine. Per-instance state (cache, pendingRefresh,
+ * DEAD flag, margin) is captured in the closure returned here — one instance
+ * per Convex client. Module-level sharing between clients is intentionally
+ * NOT supported: different clients have different issuance endpoints,
+ * different keys, different tenant scopes.
+ */
+export declare function createTokenStateMachine({ fetcher, marginSecondsOverride, }: CreateStateMachineOptions): TokenStateMachine;
+/**
+ * Refreshable error : the SDK should attempt a token refresh + retry.
+ * Canonical signal : `category: 'auth' && retryable: true` (e.g. TOKEN_EXPIRED,
+ * INVALID_TOKEN, UNAUTHENTICATED have `retryable: true` in the catalogue).
+ */
+export declare function isRefreshableError(err: unknown): boolean;
+/**
+ * Hard auth error : the SDK should NOT retry, mark itself DEAD, surface to
+ * user. Canonical signal : `category: 'auth' && recoverable: false` (e.g.
+ * INVALID_API_KEY, ACCESS_DENIED).
+ */
+export declare function isHardAuthError(err: unknown): boolean;