@stapel/core 0.2.0

package/dist/analytics/providers.js

@@ -0,0 +1,82 @@
+/** Dev provider: logs every event via console.debug. Never throws. */
+export function consoleProvider() {
+    const log = (...args) => {
+        try {
+            console.debug("[stapel analytics]", ...args);
+        }
+        catch {
+            // Never throws — a broken console must not fail a batch.
+        }
+    };
+    return {
+        track: (event) => {
+            log(event.kind, event.name, event.props);
+        },
+        identify: (userHash, traits) => {
+            log("identify", userHash, traits ?? {});
+        },
+        page: (name, props) => {
+            log("page", name, props ?? {});
+        },
+    };
+}
+const COLLECTOR_PATH = "/analytics/api/events";
+/**
+ * Built-in provider for the stapel-analytics ingest endpoint: buffers
+ * events handed over by the facade and POSTs `{events: [...]}` to
+ * `{base}/analytics/api/events` on flush (one request per facade batch).
+ * During page teardown (document hidden) it prefers `navigator.sendBeacon`
+ * so the final batch survives navigation; otherwise fetch with keepalive.
+ * On a failed send the buffer is surrendered back to the facade's retry
+ * (the facade re-delivers the batch, repopulating the buffer).
+ */
+export function stapelCollectorProvider(options) {
+    const baseUrl = options.baseUrl ?? options.client?.baseUrl;
+    if (baseUrl === undefined) {
+        throw new Error("stapelCollectorProvider requires a baseUrl or a client");
+    }
+    const endpoint = `${baseUrl.replace(/\/+$/, "")}${COLLECTOR_PATH}`;
+    let buffer = [];
+    async function send(events) {
+        const body = { events };
+        if (options.writeKey !== undefined)
+            body["write_key"] = options.writeKey;
+        const teardown = typeof document !== "undefined" &&
+            document.visibilityState === "hidden" &&
+            typeof navigator !== "undefined" &&
+            typeof navigator.sendBeacon === "function";
+        if (teardown) {
+            const accepted = navigator.sendBeacon(endpoint, new Blob([JSON.stringify(body)], { type: "application/json" }));
+            if (accepted)
+                return;
+            // Beacon rejected (payload too large / unsupported) — fall through.
+        }
+        if (options.client) {
+            await options.client.post(COLLECTOR_PATH, body);
+            return;
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        const response = await fetchImpl(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            keepalive: true,
+        });
+        if (!response.ok) {
+            throw new Error(`[stapel analytics] collector responded ${String(response.status)}`);
+        }
+    }
+    return {
+        track: (event) => {
+            buffer.push(event);
+        },
+        flush: async () => {
+            if (buffer.length === 0)
+                return;
+            const events = buffer;
+            buffer = [];
+            await send(events);
+        },
+    };
+}
+//# sourceMappingURL=providers.js.map

package/dist/analytics/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/analytics/providers.ts"],"names":[],"mappings":"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"}

package/dist/analytics/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Analytics facade types (analytics-standard.md §1–2). Packages and hosts
+ * talk to the facade only — never to providers directly
+ * (frontend-standard §4.7).
+ */
+import type { PersistStorage } from "../storage.js";
+export type AnalyticsEventKind = "track" | "page" | "identify";
+export type ConsentState = "granted" | "denied" | "pending";
+export type PiiGuardMode = "strip" | "warn" | "off";
+/** A captured event as providers receive it (PII-guarded, user id hashed). */
+export interface AnalyticsEvent {
+    /** Facade-assigned id, unique per instance lifetime (dedupe aid). */
+    readonly id: string;
+    readonly kind: AnalyticsEventKind;
+    /** track: registry event name; page: page name; identify: `"identify"`. */
+    readonly name: string;
+    /** track/page props or identify traits, after the PII guard. */
+    readonly props: Record<string, unknown>;
+    /** SHA-256 hex of the user id (identify events only). */
+    readonly userHash?: string;
+    /** Epoch ms at capture time. */
+    readonly ts: number;
+}
+/**
+ * A fan-out target. Only `track` is mandatory: events of kind `page` /
+ * `identify` fall back to `track(event)` when the dedicated method is
+ * absent (the event carries its `kind`). `flush` is called after each
+ * delivered batch and on page teardown — batching providers (like the
+ * Stapel collector) send there. A rejected/thrown delivery marks the whole
+ * batch as undelivered for this provider; it will be retried.
+ */
+export interface AnalyticsProvider {
+    track(event: AnalyticsEvent): void | Promise<void>;
+    identify?(userHash: string, traits?: Record<string, unknown>): void | Promise<void>;
+    page?(name: string, props?: Record<string, unknown>): void | Promise<void>;
+    flush?(): void | Promise<void>;
+}
+export interface AnalyticsBatchOptions {
+    /** Queue length that triggers an automatic flush. Default 20. */
+    readonly maxSize?: number;
+    /** Periodic flush interval, ms. Default 10000. */
+    readonly flushIntervalMs?: number;
+    /** Delivery attempts per batch before it is dropped. Default 5. */
+    readonly maxAttempts?: number;
+    /** Base of the exponential retry backoff, ms. Default 500. */
+    readonly backoffBaseMs?: number;
+}
+export interface AnalyticsOptions {
+    /** Initial named providers (more via `register`/`unregister`). */
+    readonly providers?: Record<string, AnalyticsProvider>;
+    /**
+     * Event registry (analytics-standard §1.1): `track` with a name outside
+     * it logs a dev console.warn but still delivers — the hard gate is the
+     * eslint rule against the project's events.json.
+     */
+    readonly registry?: readonly string[];
+    /**
+     * Initial consent when none has been persisted yet. Default `"pending"`.
+     * A state persisted by `setConsent` takes precedence on recreation.
+     */
+    readonly consent?: ConsentState;
+    /** PII guard mode for prop/trait values. Default `"strip"`. */
+    readonly piiGuard?: PiiGuardMode;
+    readonly batch?: AnalyticsBatchOptions;
+    /** Storage key prefix for the offline queue + consent. Default `"stapel-analytics"`. */
+    readonly persistKey?: string;
+    /** Storage override (tests, custom stores). Default: IndexedDB → localStorage → memory. */
+    readonly storage?: PersistStorage;
+}
+export interface Analytics {
+    /** Queue a registry event. No-op while consent is `"denied"`. */
+    track(event: string, props?: Record<string, unknown>): void;
+    /**
+     * Queue an identify. The raw `userId` never leaves the facade: providers
+     * see its SHA-256 hex. Traits pass the PII guard.
+     */
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /** Queue a page view. */
+    page(name: string, props?: Record<string, unknown>): void;
+    /** Deliver everything queued (one delivery attempt per pending batch). */
+    flush(): Promise<void>;
+    /**
+     * Consent gate (analytics-standard §1.4): `"pending"` buffers,
+     * `"granted"` flushes the buffer, `"denied"` drops it (memory +
+     * persisted) and turns subsequent calls into no-ops. Persisted.
+     */
+    setConsent(state: ConsentState): Promise<void>;
+    /** Current consent state (after async restore; see `flush`). */
+    getConsent(): ConsentState;
+    /** Register a provider at runtime (merge semantics). */
+    register(name: string, provider: AnalyticsProvider): void;
+    unregister(name: string): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/analytics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;AAE/D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5D,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEpD,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,QAAQ,CAAC,CACP,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAC;IACvC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAED,MAAM,WAAW,SAAS;IACxB,iEAAiE;IACjE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjE,yBAAyB;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1D,0EAA0E;IAC1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gEAAgE;IAChE,UAAU,IAAI,YAAY,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC"}

package/dist/analytics/types.js

@@ -0,0 +1,7 @@
+/**
+ * Analytics facade types (analytics-standard.md §1–2). Packages and hosts
+ * talk to the facade only — never to providers directly
+ * (frontend-standard §4.7).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/analytics/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import { type VerificationChallengeHandler } from "./verification.js";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface StapelRequestOptions {
+    readonly method?: HttpMethod;
+    /** JSON-serialized unless it is a `BodyInit` (FormData, Blob, string…). */
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+    /** Appended to the URL; `undefined` values are skipped. */
+    readonly query?: Record<string, string | number | boolean | undefined>;
+    readonly signal?: AbortSignal;
+}
+export interface StapelClient {
+    readonly baseUrl: string;
+    request<T>(path: string, options?: StapelRequestOptions): Promise<T>;
+    get<T>(path: string, options?: Omit<StapelRequestOptions, "method" | "body">): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: Omit<StapelRequestOptions, "method" | "body">): Promise<T>;
+    put<T>(path: string, body?: unknown, options?: Omit<StapelRequestOptions, "method" | "body">): Promise<T>;
+    patch<T>(path: string, body?: unknown, options?: Omit<StapelRequestOptions, "method" | "body">): Promise<T>;
+    delete<T>(path: string, options?: Omit<StapelRequestOptions, "method" | "body">): Promise<T>;
+}
+export interface StapelClientOptions {
+    /** e.g. `https://api.example.com` or `/api`. */
+    readonly baseUrl: string;
+    /** Auth seam: current access token (attached as `Authorization: Bearer`). */
+    readonly getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * Refresh seam: called once per request on a 401. Return the new access
+     * token to retry the request with it; return null/undefined to give up
+     * (the 401 is then thrown as `StapelApiError`).
+     */
+    readonly onAuthRefresh?: () => Promise<string | null | undefined>;
+    /**
+     * Step-up verification seam: called when a 403 body carries a
+     * `verification` challenge. On `{retry: true}` the original request is
+     * retried exactly once, with `X-Verification-Token` when a token is given.
+     */
+    readonly onVerificationChallenge?: VerificationChallengeHandler;
+    /** Merged into every request (overridable per request). */
+    readonly defaultHeaders?: Record<string, string>;
+    /** Injectable fetch (tests, SSR, instrumentation). Default: global fetch. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * Typed fetch wrapper around the Stapel API conventions: JSON in/out, bearer
+ * auth with a refresh seam, the `{localizable_error, error, params}` error
+ * envelope, and verification-403 interception (see `StapelClientOptions`).
+ */
+export declare function createStapelClient(options: StapelClientOptions): StapelClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,4BAA4B,EAClC,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1F,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3G,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1G,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5G,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC9F;AAED,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAChB,MAAM,GACN,IAAI,GACJ,SAAS,GACT,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAClE;;;;OAIG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,4BAA4B,CAAC;IAChE,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CAC1C;AAmDD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA+F7E"}

package/dist/client.js

@@ -0,0 +1,135 @@
+import { parseErrorEnvelope } from "./errors.js";
+import { extractVerificationChallenge, VERIFICATION_TOKEN_HEADER, } from "./verification.js";
+function isBodyInit(body) {
+    return (typeof body === "string" ||
+        (typeof Blob !== "undefined" && body instanceof Blob) ||
+        (typeof FormData !== "undefined" && body instanceof FormData) ||
+        (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) ||
+        (typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer) ||
+        (typeof ReadableStream !== "undefined" && body instanceof ReadableStream));
+}
+function buildUrl(baseUrl, path, query) {
+    const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    const suffix = path.startsWith("/") ? path : `/${path}`;
+    let url = `${base}${suffix}`;
+    if (query) {
+        const search = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined)
+                search.set(key, String(value));
+        }
+        const qs = search.toString();
+        if (qs.length > 0)
+            url += `?${qs}`;
+    }
+    return url;
+}
+async function parseBody(response) {
+    if (response.status === 204 || response.status === 205)
+        return undefined;
+    const contentType = response.headers.get("content-type") ?? "";
+    const text = await response.text();
+    if (text.length === 0)
+        return undefined;
+    if (contentType.includes("json")) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Typed fetch wrapper around the Stapel API conventions: JSON in/out, bearer
+ * auth with a refresh seam, the `{localizable_error, error, params}` error
+ * envelope, and verification-403 interception (see `StapelClientOptions`).
+ */
+export function createStapelClient(options) {
+    const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    async function request(path, requestOptions = {}) {
+        const method = requestOptions.method ?? "GET";
+        const url = buildUrl(options.baseUrl, path, requestOptions.query);
+        let overrideToken;
+        let verificationToken;
+        let triedRefresh = false;
+        let triedVerification = false;
+        for (;;) {
+            const headers = new Headers(options.defaultHeaders);
+            if (requestOptions.headers) {
+                for (const [key, value] of Object.entries(requestOptions.headers)) {
+                    headers.set(key, value);
+                }
+            }
+            const token = overrideToken ?? (await options.getToken?.());
+            if (token != null && token.length > 0 && !headers.has("authorization")) {
+                headers.set("Authorization", `Bearer ${token}`);
+            }
+            if (verificationToken !== undefined) {
+                headers.set(VERIFICATION_TOKEN_HEADER, verificationToken);
+            }
+            let body;
+            if (requestOptions.body !== undefined) {
+                if (isBodyInit(requestOptions.body)) {
+                    body = requestOptions.body;
+                }
+                else {
+                    body = JSON.stringify(requestOptions.body);
+                    if (!headers.has("content-type")) {
+                        headers.set("Content-Type", "application/json");
+                    }
+                }
+            }
+            const requestInit = { method, headers };
+            if (body !== undefined)
+                requestInit.body = body;
+            if (requestOptions.signal)
+                requestInit.signal = requestOptions.signal;
+            const response = await fetchImpl(url, requestInit);
+            if (response.ok) {
+                return (await parseBody(response));
+            }
+            const errorBody = await parseBody(response);
+            if (response.status === 401 && options.onAuthRefresh && !triedRefresh) {
+                triedRefresh = true;
+                const refreshed = await options.onAuthRefresh();
+                if (refreshed != null && refreshed.length > 0) {
+                    overrideToken = refreshed;
+                    continue;
+                }
+            }
+            if (response.status === 403 &&
+                options.onVerificationChallenge &&
+                !triedVerification) {
+                const challenge = extractVerificationChallenge(errorBody);
+                if (challenge) {
+                    triedVerification = true;
+                    const outcome = await options.onVerificationChallenge(challenge);
+                    if (outcome.retry) {
+                        if (outcome.token !== undefined) {
+                            verificationToken = outcome.token;
+                        }
+                        continue;
+                    }
+                }
+            }
+            throw parseErrorEnvelope(response.status, errorBody);
+        }
+    }
+    return {
+        baseUrl: options.baseUrl,
+        request,
+        get: (path, opts) => request(path, { ...opts, method: "GET" }),
+        post: (path, body, opts) => request(path, { ...opts, method: "POST", body }),
+        put: (path, body, opts) => request(path, { ...opts, method: "PUT", body }),
+        patch: (path, body, opts) => request(path, { ...opts, method: "PATCH", body }),
+        delete: (path, opts) => request(path, { ...opts, method: "DELETE" }),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+import type { ReactElement, ReactNode } from "react";
+import type { StapelClient } from "./client.js";
+import type { Analytics } from "./analytics/types.js";
+/**
+ * App-level Stapel configuration. `clients` allows per-module client
+ * overrides — the client-injection fork-resolution seam of
+ * frontend-standard §7.2: a divergent backend gets its own generated client
+ * injected into the same package machines.
+ */
+export interface StapelConfig {
+    /** Default API client used by all `@stapel/<module>-react` packages. */
+    readonly client: StapelClient;
+    /** Per-module overrides, keyed by module name (e.g. `"auth"`). */
+    readonly clients?: Readonly<Record<string, StapelClient>>;
+}
+export declare function StapelConfigProvider(props: {
+    config: StapelConfig;
+    /**
+     * Optional analytics facade (analytics-standard §2); when provided,
+     * `useAnalytics()` works anywhere below. Omitting it keeps the previous
+     * behaviour.
+     */
+    analytics?: Analytics;
+    children: ReactNode;
+}): ReactElement;
+export declare function useStapelConfig(): StapelConfig;
+/**
+ * Resolve the API client for a module: the per-module override when
+ * configured, otherwise the default client.
+ */
+export declare function useStapelClient(module?: string): StapelClient;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC3D;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,MAAM,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,YAAY,CAQf;AAED,wBAAgB,eAAe,IAAI,YAAY,CAQ9C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAO7D"}

package/dist/config.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+import { AnalyticsContext } from "./analytics/context.js";
+const StapelConfigContext = createContext(null);
+export function StapelConfigProvider(props) {
+    return (_jsx(StapelConfigContext.Provider, { value: props.config, children: _jsx(AnalyticsContext.Provider, { value: props.analytics ?? null, children: props.children }) }));
+}
+export function useStapelConfig() {
+    const config = useContext(StapelConfigContext);
+    if (config === null) {
+        throw new Error("useStapelConfig must be used within a <StapelConfigProvider>");
+    }
+    return config;
+}
+/**
+ * Resolve the API client for a module: the per-module override when
+ * configured, otherwise the default client.
+ */
+export function useStapelClient(module) {
+    const config = useStapelConfig();
+    if (module !== undefined) {
+        const override = config.clients?.[module];
+        if (override)
+            return override;
+    }
+    return config.client;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAgB1D,MAAM,mBAAmB,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAC;AAErE,MAAM,UAAU,oBAAoB,CAAC,KASpC;IACC,OAAO,CACL,KAAC,mBAAmB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,CAAC,MAAM,YAC/C,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,YACtD,KAAK,CAAC,QAAQ,GACW,GACC,CAChC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,MAAM,MAAM,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAC/C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,8DAA8D,CAC/D,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;IAChC,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The Stapel backend error envelope:
+ * `{ localizable_error: "auth.otp.invalid", error: "Invalid OTP", params: {...} }`
+ * `localizable_error` is an i18n key; `params` feed `{param}` interpolation.
+ */
+export interface StapelErrorEnvelope {
+    readonly localizable_error?: string;
+    readonly error?: string;
+    readonly params?: Record<string, unknown>;
+}
+export declare class StapelApiError extends Error {
+    /** i18n key from `localizable_error` (fallback: `stapel.http.<status>`). */
+    readonly code: string;
+    /** Interpolation params for the i18n key. */
+    readonly params: Readonly<Record<string, unknown>>;
+    /** HTTP status code. */
+    readonly status: number;
+    /** Raw (parsed) response body, for diagnostics and extensions. */
+    readonly body: unknown;
+    constructor(args: {
+        code: string;
+        message: string;
+        params?: Record<string, unknown>;
+        status: number;
+        body?: unknown;
+    });
+}
+/**
+ * Parse a failed response body (already JSON-decoded; may be anything) into
+ * a `StapelApiError`. Tolerant of non-envelope bodies.
+ */
+export declare function parseErrorEnvelope(status: number, body: unknown): StapelApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,IAAI,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB;CAQF;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,GACZ,cAAc,CAqBhB"}

package/dist/errors.js

@@ -0,0 +1,46 @@
+export class StapelApiError extends Error {
+    /** i18n key from `localizable_error` (fallback: `stapel.http.<status>`). */
+    code;
+    /** Interpolation params for the i18n key. */
+    params;
+    /** HTTP status code. */
+    status;
+    /** Raw (parsed) response body, for diagnostics and extensions. */
+    body;
+    constructor(args) {
+        super(args.message);
+        this.name = "StapelApiError";
+        this.code = args.code;
+        this.params = args.params ?? {};
+        this.status = args.status;
+        this.body = args.body;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse a failed response body (already JSON-decoded; may be anything) into
+ * a `StapelApiError`. Tolerant of non-envelope bodies.
+ */
+export function parseErrorEnvelope(status, body) {
+    const fallbackCode = `stapel.http.${String(status)}`;
+    if (!isRecord(body)) {
+        return new StapelApiError({
+            code: fallbackCode,
+            message: `Request failed with status ${String(status)}`,
+            status,
+            body,
+        });
+    }
+    const code = typeof body["localizable_error"] === "string" &&
+        body["localizable_error"].length > 0
+        ? body["localizable_error"]
+        : fallbackCode;
+    const message = typeof body["error"] === "string" && body["error"].length > 0
+        ? body["error"]
+        : code;
+    const params = isRecord(body["params"]) ? body["params"] : {};
+    return new StapelApiError({ code, message, params, status, body });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,4EAA4E;IACnE,IAAI,CAAS;IACtB,6CAA6C;IACpC,MAAM,CAAoC;IACnD,wBAAwB;IACf,MAAM,CAAS;IACxB,kEAAkE;IACzD,IAAI,CAAU;IAEvB,YAAY,IAMX;QACC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,IAAa;IAEb,MAAM,YAAY,GAAG,eAAe,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IACrD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,OAAO,IAAI,cAAc,CAAC;YACxB,IAAI,EAAE,YAAY;YAClB,OAAO,EAAE,8BAA8B,MAAM,CAAC,MAAM,CAAC,EAAE;YACvD,MAAM;YACN,IAAI;SACL,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,GACR,OAAO,IAAI,CAAC,mBAAmB,CAAC,KAAK,QAAQ;QAC7C,IAAI,CAAC,mBAAmB,CAAC,CAAC,MAAM,GAAG,CAAC;QAClC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC;QAC3B,CAAC,CAAC,YAAY,CAAC;IACnB,MAAM,OAAO,GACX,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC;QAC3D,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QACf,CAAC,CAAC,IAAI,CAAC;IACX,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,OAAO,IAAI,cAAc,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACrE,CAAC"}

package/dist/i18n.d.ts

@@ -0,0 +1,51 @@
+import type { ReactElement, ReactNode } from "react";
+/** Flat key → string dictionary, e.g. `{"auth.otp.invalid": "Invalid code"}`. */
+export type I18nDictionary = Record<string, string>;
+/**
+ * Async locale loader seam. Point it at the stapel-translate pair:
+ * `loadLocale: (locale) => translateClient.resolve(locale)` — the engine
+ * calls it once per locale and caches the result as a bundle.
+ */
+export type LocaleLoader = (locale: string) => Promise<I18nDictionary>;
+export type TranslateFn = (key: string, params?: Record<string, unknown>) => string;
+export interface I18nEngine {
+    /** Current locale. */
+    readonly locale: string;
+    /** Translate a key; missing keys fall back to the key itself. */
+    t: TranslateFn;
+    /** Switch locale; loads it via `loadLocale` when not already registered. */
+    setLocale(locale: string): Promise<void>;
+    /** Register a static bundle (packages register their keys this way). */
+    registerBundle(locale: string, bundle: I18nDictionary): void;
+    /** Subscribe to engine changes (locale switches, bundle registration). */
+    subscribe(listener: () => void): () => void;
+    /** Monotonic change counter (for useSyncExternalStore). */
+    getVersion(): number;
+}
+/** `{param}` interpolation. Unknown params are left as-is. */
+export declare function interpolate(template: string, params?: Record<string, unknown>): string;
+export interface CreateI18nOptions {
+    /** Initial locale. */
+    readonly locale: string;
+    /** Static bundles, keyed by locale. */
+    readonly bundles?: Readonly<Record<string, I18nDictionary>>;
+    /** Async loader for locales not covered by static bundles. */
+    readonly loadLocale?: LocaleLoader;
+}
+/**
+ * Minimal i18n engine: dictionaries per locale, `{param}` interpolation,
+ * static bundles + async loader, missing-key fallback to the key itself
+ * (frontend-standard §4.2 — user-facing strings are always keys).
+ */
+export declare function createI18n(options: CreateI18nOptions): I18nEngine;
+export declare function I18nProvider(props: {
+    i18n: I18nEngine;
+    children: ReactNode;
+}): ReactElement;
+export declare function useI18n(): I18nEngine;
+/**
+ * Reactive translate function: re-renders on locale switches and bundle
+ * registration.
+ */
+export declare function useT(): TranslateFn;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAEvE,MAAM,MAAM,WAAW,GAAG,CACxB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC;AAEZ,MAAM,WAAW,UAAU;IACzB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,CAAC,EAAE,WAAW,CAAC;IACf,4EAA4E;IAC5E,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,wEAAwE;IACxE,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7D,0EAA0E;IAC1E,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,2DAA2D;IAC3D,UAAU,IAAI,MAAM,CAAC;CACtB;AAED,8DAA8D;AAC9D,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAOR;AAED,MAAM,WAAW,iBAAiB;IAChC,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAC5D,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAuDjE;AAID,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,YAAY,CAMf;AAED,wBAAgB,OAAO,IAAI,UAAU,CAMpC;AAED;;;GAGG;AACH,wBAAgB,IAAI,IAAI,WAAW,CAIlC"}