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

package/dist/_stateMachine.js

@@ -0,0 +1,168 @@
+/**
+ * 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.
+ */
+// ─── Constants ──────────────────────────────────────────────────
+const MARGIN_BASE_SECONDS = 60;
+const MARGIN_JITTER_SECONDS = 10;
+/**
+ * Hard-auth code list — post-batch-5 includes both namespaced (canonical)
+ * and bare (legacy-rollout-window) variants. The classifier prefers the
+ * canonical `category === 'auth' && !recoverable` signal when present (per
+ * Tension #5 lock B) ; this list is the fallback for SdkErrors that lack
+ * canonical metadata (e.g. legacy gateway versions, local non-wire errors).
+ */
+const HARD_AUTH_ERRORS = [
+    'storystick/INVALID_API_KEY',
+    'storystick/API_KEY_REVOKED',
+    'storystick/API_KEY_EXPIRED',
+    'storystick/NOT_A_MEMBER',
+    'storystick/ACCESS_DENIED',
+    // Legacy bare codes
+    'INVALID_API_KEY',
+    'API_KEY_REVOKED',
+    'API_KEY_EXPIRED',
+    'NOT_A_MEMBER',
+    'ACCESS_DENIED',
+];
+const REFRESHABLE_ERRORS = [
+    'storystick/TOKEN_EXPIRED',
+    'storystick/INVALID_TOKEN',
+    'storystick/UNAUTHENTICATED',
+    // Legacy bare codes
+    'TOKEN_EXPIRED',
+    'INVALID_TOKEN',
+    'UNAUTHENTICATED',
+];
+/**
+ * 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 function createTokenStateMachine({ fetcher, marginSecondsOverride, }) {
+    // Per-instance jitter, set once at construction time (§13.1). Keeps the
+    // machine deterministic within a single instance's lifetime — the margin
+    // does not jitter on each call.
+    const marginSeconds = marginSecondsOverride ??
+        MARGIN_BASE_SECONDS + (Math.random() * 2 - 1) * MARGIN_JITTER_SECONDS;
+    let cache = null;
+    let pendingRefresh = null;
+    let dead = null;
+    async function fetchAndCache() {
+        try {
+            const result = await fetcher();
+            cache = result;
+            return result.token;
+        }
+        catch (err) {
+            if (isHardAuthError(err)) {
+                dead = err;
+            }
+            throw err;
+        }
+    }
+    async function forceRefresh() {
+        if (dead)
+            throw dead;
+        if (pendingRefresh)
+            return pendingRefresh;
+        pendingRefresh = fetchAndCache().finally(() => {
+            pendingRefresh = null;
+        });
+        return pendingRefresh;
+    }
+    async function ensureToken() {
+        if (dead)
+            throw dead;
+        const now = Date.now();
+        if (cache && cache.expiresAt > now + marginSeconds * 1000) {
+            return cache.token;
+        }
+        return forceRefresh();
+    }
+    function reset() {
+        cache = null;
+        pendingRefresh = null;
+        dead = null;
+    }
+    function isDead() {
+        return dead !== null;
+    }
+    return { ensureToken, forceRefresh, reset, isDead };
+}
+// ─── Error classification (exported for wire layer) ─────────────
+//
+// Post ADR-079 batch 5 (Tension #5 lock B — full routing refactor) :
+// classifiers prefer the canonical envelope's `category` + `recoverable` +
+// `retryable` fields when present. They fall back to hardcoded code lists
+// (legacy bare + namespaced variants) when the SdkError lacks canonical
+// metadata — the gateway-rollout window and local non-wire SdkErrors.
+/**
+ * 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 function isRefreshableError(err) {
+    const meta = extractMetadata(err);
+    if (meta.category !== undefined && meta.retryable !== undefined) {
+        // Canonical fast path : auth-retryable means refreshable.
+        return meta.category === 'auth' && meta.retryable === true;
+    }
+    // Fallback : hardcoded refreshable code list.
+    return meta.code !== undefined && REFRESHABLE_ERRORS.includes(meta.code);
+}
+/**
+ * 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 function isHardAuthError(err) {
+    const meta = extractMetadata(err);
+    if (meta.category !== undefined && meta.recoverable !== undefined) {
+        // Canonical fast path : auth + non-recoverable means hard.
+        return meta.category === 'auth' && meta.recoverable === false;
+    }
+    // Fallback : hardcoded hard-auth code list.
+    return meta.code !== undefined && HARD_AUTH_ERRORS.includes(meta.code);
+}
+function extractMetadata(err) {
+    if (err == null || typeof err !== 'object')
+        return {};
+    const obj = err;
+    const meta = {};
+    if (typeof obj.code === 'string')
+        meta.code = obj.code;
+    if (typeof obj.category === 'string')
+        meta.category = obj.category;
+    if (typeof obj.recoverable === 'boolean')
+        meta.recoverable = obj.recoverable;
+    if (typeof obj.retryable === 'boolean')
+        meta.retryable = obj.retryable;
+    if (meta.code === undefined && typeof obj.message === 'string') {
+        // ConvexError surfaces on `message` — parse the ADR error envelope.
+        // Post-batch-5 the namespaced form `storystick/<NAME>` matches too.
+        const match = obj.message.match(/"code"\s*:\s*"([\w/]+)"/);
+        if (match)
+            meta.code = match[1];
+    }
+    return meta;
+}

package/dist/_wireAuth.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Wire the state machine into a Convex client's `setAuth` (ADR-045 §13).
+ *
+ * `ConvexReactClient.setAuth(fetchToken)` and `ConvexHttpClient.setAuth(...)`
+ * both accept an async function receiving `{ forceRefreshToken: boolean }`.
+ * This helper bridges that signature to our `TokenStateMachine`:
+ *
+ * - Regular call → `machine.ensureToken()` (opportunistic JIT).
+ * - `forceRefreshToken: true` signal from Convex (sent after a 401 on an
+ *   in-flight query) → `machine.forceRefresh()` (reactive backstop, §13.6).
+ *
+ * This is the single seam between our SDK logic and Convex's client. Keep
+ * it thin: every new concern (logging, metrics, sentry hooks) lands here,
+ * not inside the state machine.
+ */
+import { type TokenFetcher, type TokenStateMachine } from './_stateMachine.js';
+/** Minimal shape our wire helper expects on a Convex client. */
+export interface ConvexClientWithSetAuth {
+    setAuth(fetchToken: (args: {
+        forceRefreshToken: boolean;
+    }) => Promise<string | null>): void;
+}
+export interface WireAuthOptions {
+    fetcher: TokenFetcher;
+    /** Override the margin for tests. Default: 60s ± 10s jitter. */
+    marginSecondsOverride?: number;
+}
+export interface WireAuthResult {
+    /** The underlying state machine, exposed for `reset()` on sign-out. */
+    machine: TokenStateMachine;
+    /**
+     * Detach the `setAuth` wire by setting a no-op fetcher. Convex does not
+     * expose a first-class unsubscribe, so this is the conventional path:
+     * `setAuth(async () => null)` drops the machine.
+     */
+    detach: () => void;
+}
+/**
+ * Attach state-machine-backed auth to a Convex client.
+ *
+ *   const { machine } = wireConvexAuth(client, { fetcher: apiKeyFetcher(...) })
+ *   // on sign-out:
+ *   machine.reset()
+ *
+ * The machine lives for the lifetime of the client. Build a new one per
+ * client — different clients have different issuance targets.
+ */
+export declare function wireConvexAuth(client: ConvexClientWithSetAuth, { fetcher, marginSecondsOverride }: WireAuthOptions): WireAuthResult;

package/dist/_wireAuth.js

@@ -0,0 +1,52 @@
+/**
+ * Wire the state machine into a Convex client's `setAuth` (ADR-045 §13).
+ *
+ * `ConvexReactClient.setAuth(fetchToken)` and `ConvexHttpClient.setAuth(...)`
+ * both accept an async function receiving `{ forceRefreshToken: boolean }`.
+ * This helper bridges that signature to our `TokenStateMachine`:
+ *
+ * - Regular call → `machine.ensureToken()` (opportunistic JIT).
+ * - `forceRefreshToken: true` signal from Convex (sent after a 401 on an
+ *   in-flight query) → `machine.forceRefresh()` (reactive backstop, §13.6).
+ *
+ * This is the single seam between our SDK logic and Convex's client. Keep
+ * it thin: every new concern (logging, metrics, sentry hooks) lands here,
+ * not inside the state machine.
+ */
+import { createTokenStateMachine, } from './_stateMachine.js';
+/**
+ * Attach state-machine-backed auth to a Convex client.
+ *
+ *   const { machine } = wireConvexAuth(client, { fetcher: apiKeyFetcher(...) })
+ *   // on sign-out:
+ *   machine.reset()
+ *
+ * The machine lives for the lifetime of the client. Build a new one per
+ * client — different clients have different issuance targets.
+ */
+export function wireConvexAuth(client, { fetcher, marginSecondsOverride }) {
+    const machine = createTokenStateMachine({
+        fetcher,
+        marginSecondsOverride,
+    });
+    client.setAuth(async ({ forceRefreshToken }) => {
+        try {
+            return forceRefreshToken
+                ? await machine.forceRefresh()
+                : await machine.ensureToken();
+        }
+        catch {
+            // Convex treats `null` as "no auth available"; any exception thrown
+            // from `fetchToken` is logged by Convex as a warning. Returning null
+            // lets the component-side `requireTenant` surface `UNAUTHENTICATED`
+            // cleanly, which the app layer catches.
+            return null;
+        }
+    });
+    return {
+        machine,
+        detach() {
+            client.setAuth(async () => null);
+        },
+    };
+}

package/dist/adapter.d.ts

@@ -0,0 +1,14 @@
+/** Framework-adapter infrastructure. Application code should use createClient. */
+export { resolveProject } from './resolve.js';
+export type { ProjectConfig } from './resolve.js';
+export { resolveInfra, resolveInfraSync } from './infra-resolver.js';
+export type { ResolveInfraOptions, ResolvedInfra } from './infra-resolver.js';
+export { createHttpTransportV2 } from './transport.js';
+export type { HttpTransportOptions } from './transport.js';
+export { resolveStorystickPage } from './resolve-route.js';
+export { fetchCurrentSchema, isSchemaFormatUnsupportedError, SCHEMA_FORMAT_UNSUPPORTED_CODE, } from './schemas.js';
+export type { RawSchemaRow, SchemaFormatUnsupportedPayload, } from './schemas.js';
+export { publishedLocaleRoutes } from './published-routes.js';
+export { fetchProjectLocaleSettings } from './project-locales.js';
+export { appendSearchParamsToRedirect } from './redirect-search.js';
+export { readSignedWebhook, signWebhookBody } from './signed-webhook.js';

package/dist/adapter.js

@@ -0,0 +1,10 @@
+/** Framework-adapter infrastructure. Application code should use createClient. */
+export { resolveProject } from './resolve.js';
+export { resolveInfra, resolveInfraSync } from './infra-resolver.js';
+export { createHttpTransportV2 } from './transport.js';
+export { resolveStorystickPage } from './resolve-route.js';
+export { fetchCurrentSchema, isSchemaFormatUnsupportedError, SCHEMA_FORMAT_UNSUPPORTED_CODE, } from './schemas.js';
+export { publishedLocaleRoutes } from './published-routes.js';
+export { fetchProjectLocaleSettings } from './project-locales.js';
+export { appendSearchParamsToRedirect } from './redirect-search.js';
+export { readSignedWebhook, signWebhookBody } from './signed-webhook.js';

package/dist/content-values.d.ts

@@ -0,0 +1,11 @@
+export interface ContentSource {
+    document: unknown;
+    path: string;
+}
+export { readContentOrigin, type ContentOrigin } from '@storystick/types/internal/content-origin';
+/** Internal: live projections apply to authored reads before effective hydration. */
+export declare function rawContentValues<T>(value: T): T;
+/** Prepare once per consumer, after the raw read cache and Preview coding. */
+export declare function prepareContentValues<T>(value: T, requirePlan?: boolean, preview?: boolean): T;
+/** Explicit raw-content escape hatch. Never performs I/O or reads app context. */
+export declare function prepareContentSource<T>(value: T, source?: ContentSource): T;