@stapel/core 0.2.0

package/src/client.ts

@@ -0,0 +1,206 @@
+import { parseErrorEnvelope } from "./errors.js";
+import {
+  extractVerificationChallenge,
+  VERIFICATION_TOKEN_HEADER,
+  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;
+}
+
+function isBodyInit(body: unknown): body is BodyInit {
+  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: string,
+  path: string,
+  query?: StapelRequestOptions["query"]
+): string {
+  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: Response): Promise<unknown> {
+  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) as unknown;
+    } catch {
+      return text;
+    }
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } 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: StapelClientOptions): StapelClient {
+  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+
+  async function request<T>(
+    path: string,
+    requestOptions: StapelRequestOptions = {}
+  ): Promise<T> {
+    const method = requestOptions.method ?? "GET";
+    const url = buildUrl(options.baseUrl, path, requestOptions.query);
+
+    let overrideToken: string | undefined;
+    let verificationToken: string | undefined;
+    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: BodyInit | undefined;
+      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: 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)) as T;
+      }
+
+      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" }),
+  };
+}

package/src/config.tsx

@@ -0,0 +1,62 @@
+import { createContext, useContext } from "react";
+import type { ReactElement, ReactNode } from "react";
+import type { StapelClient } from "./client.js";
+import { AnalyticsContext } from "./analytics/context.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>>;
+}
+
+const StapelConfigContext = createContext<StapelConfig | null>(null);
+
+export 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 {
+  return (
+    <StapelConfigContext.Provider value={props.config}>
+      <AnalyticsContext.Provider value={props.analytics ?? null}>
+        {props.children}
+      </AnalyticsContext.Provider>
+    </StapelConfigContext.Provider>
+  );
+}
+
+export function useStapelConfig(): StapelConfig {
+  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?: string): StapelClient {
+  const config = useStapelConfig();
+  if (module !== undefined) {
+    const override = config.clients?.[module];
+    if (override) return override;
+  }
+  return config.client;
+}

package/src/errors.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 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;
+  }) {
+    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: unknown): value is Record<string, unknown> {
+  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: number,
+  body: unknown
+): StapelApiError {
+  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 });
+}

package/src/i18n.tsx

@@ -0,0 +1,147 @@
+import { createContext, useContext, useSyncExternalStore } from "react";
+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 function interpolate(
+  template: string,
+  params?: Record<string, unknown>
+): string {
+  if (!params) return template;
+  return template.replace(/\{([\w.]+)\}/g, (match, name: string) =>
+    Object.prototype.hasOwnProperty.call(params, name)
+      ? String(params[name])
+      : match
+  );
+}
+
+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 function createI18n(options: CreateI18nOptions): I18nEngine {
+  const dictionaries = new Map<string, I18nDictionary>();
+  const loadedLocales = new Set<string>();
+  const listeners = new Set<() => void>();
+  let locale = options.locale;
+  let version = 0;
+
+  if (options.bundles) {
+    for (const [bundleLocale, bundle] of Object.entries(options.bundles)) {
+      dictionaries.set(bundleLocale, { ...bundle });
+    }
+  }
+
+  function notify(): void {
+    version += 1;
+    for (const listener of listeners) listener();
+  }
+
+  async function ensureLoaded(nextLocale: string): Promise<void> {
+    if (!options.loadLocale || loadedLocales.has(nextLocale)) return;
+    loadedLocales.add(nextLocale);
+    const bundle = await options.loadLocale(nextLocale);
+    const existing = dictionaries.get(nextLocale) ?? {};
+    dictionaries.set(nextLocale, { ...existing, ...bundle });
+  }
+
+  const engine: I18nEngine = {
+    get locale(): string {
+      return locale;
+    },
+    t: (key, params) => {
+      const template = dictionaries.get(locale)?.[key];
+      if (template === undefined) return key;
+      return interpolate(template, params);
+    },
+    setLocale: async (nextLocale) => {
+      await ensureLoaded(nextLocale);
+      locale = nextLocale;
+      notify();
+    },
+    registerBundle: (bundleLocale, bundle) => {
+      const existing = dictionaries.get(bundleLocale) ?? {};
+      dictionaries.set(bundleLocale, { ...existing, ...bundle });
+      notify();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getVersion: () => version,
+  };
+
+  return engine;
+}
+
+const I18nContext = createContext<I18nEngine | null>(null);
+
+export function I18nProvider(props: {
+  i18n: I18nEngine;
+  children: ReactNode;
+}): ReactElement {
+  return (
+    <I18nContext.Provider value={props.i18n}>
+      {props.children}
+    </I18nContext.Provider>
+  );
+}
+
+export function useI18n(): I18nEngine {
+  const engine = useContext(I18nContext);
+  if (engine === null) {
+    throw new Error("useI18n must be used within an <I18nProvider>");
+  }
+  return engine;
+}
+
+/**
+ * Reactive translate function: re-renders on locale switches and bundle
+ * registration.
+ */
+export function useT(): TranslateFn {
+  const engine = useI18n();
+  useSyncExternalStore(engine.subscribe, engine.getVersion, engine.getVersion);
+  return engine.t;
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+// fetch + error envelope
+export { createStapelClient } from "./client.js";
+export type {
+  StapelClient,
+  StapelClientOptions,
+  StapelRequestOptions,
+  HttpMethod,
+} from "./client.js";
+export { StapelApiError, parseErrorEnvelope } from "./errors.js";
+export type { StapelErrorEnvelope } from "./errors.js";
+
+// verification-403 interception seam
+export {
+  extractVerificationChallenge,
+  VERIFICATION_TOKEN_HEADER,
+} from "./verification.js";
+export type {
+  VerificationChallenge,
+  VerificationOutcome,
+  VerificationChallengeHandler,
+} from "./verification.js";
+
+// config provider + client injection
+export {
+  StapelConfigProvider,
+  useStapelConfig,
+  useStapelClient,
+} from "./config.js";
+export type { StapelConfig } from "./config.js";
+
+// query layer + persistence
+export { createStapelQueryClient } from "./query.js";
+export type {
+  StapelQueryRuntime,
+  StapelQueryClientOptions,
+  PersistStorage,
+} from "./query.js";
+
+// i18n engine
+export { createI18n, interpolate, I18nProvider, useI18n, useT } from "./i18n.js";
+export type {
+  I18nEngine,
+  I18nDictionary,
+  LocaleLoader,
+  TranslateFn,
+  CreateI18nOptions,
+} from "./i18n.js";
+
+// analytics facade (analytics-standard §2)
+export { createAnalytics } from "./analytics/createAnalytics.js";
+export {
+  consoleProvider,
+  stapelCollectorProvider,
+} from "./analytics/providers.js";
+export type { StapelCollectorOptions } from "./analytics/providers.js";
+export { trackFlowStep } from "./analytics/flow.js";
+export type { FlowStepPhase } from "./analytics/flow.js";
+export { AnalyticsContext, useAnalytics } from "./analytics/context.js";
+export type {
+  Analytics,
+  AnalyticsEvent,
+  AnalyticsEventKind,
+  AnalyticsProvider,
+  AnalyticsOptions,
+  AnalyticsBatchOptions,
+  ConsentState,
+  PiiGuardMode,
+} from "./analytics/types.js";
+
+// breakpoints
+export { useBreakpoint } from "./useBreakpoint.js";
+export type { Breakpoint } from "@stapel/tokens";