@wow-two-beta/ui-vue 0.0.5 → 0.0.6

package/dist/foundation/http/index.d.ts

@@ -1,9 +1,10 @@
-export * from './ApiResponse';
-export * from './Page';
-export * from './ProblemDetails';
+export * from './models/ApiResponse';
+export * from './models/Page';
+export * from './models/ProblemDetails';
 export * from './ApiError';
+export type { ApiJsonCodec } from './ApiJsonCodec';
+export * from './ApiFailure';
 export * from './Envelope';
-export * from './DateBrands';
-export * from './temporalReviver';
+export * from './models/DateBrands';
 export * from './CreateApiClient';
 export * from './FieldErrors';

package/dist/foundation/http/index.js

@@ -1,58 +1,18 @@
-import { A as ApiError } from "../../chunks/ApiError-l0YdcqqV.js";
-import { Temporal } from "temporal-polyfill";
-import { g as getErrorMessage } from "../../chunks/ErrorMessage-Cqt7WaFn.js";
-import { i as isAbortError } from "../../chunks/ErrorRecognizers-oTklha6D.js";
+import { a as ApiFailureFactory, A as ApiError } from "../../chunks/ApiError-_AOua_XE.js";
+import { b } from "../../chunks/ApiError-_AOua_XE.js";
+import { R as ResultExtensions } from "../../chunks/ResultExtensions-B7dWH0FZ.js";
+import { a as isTimeoutError, i as isAbortError } from "../../chunks/ErrorRecognizers-DO2SHD6N.js";
 import { shouldRetry, computeRetryDelay } from "../resilience/index.js";
-import { a, f } from "../../chunks/FieldErrors-2zjhia4U.js";
+import { f, a } from "../../chunks/FieldErrors-DIHjOm5W.js";
 const isJsonObject = (parsed) => parsed !== null && typeof parsed === "object" && !Array.isArray(parsed);
 const wowTwoEnvelope = {
-  unwrap: (parsed) => isJsonObject(parsed) && "data" in parsed ? parsed["data"] : parsed,
-  toError: (parsed, response) => new ApiError(response.status, isJsonObject(parsed) ? parsed : null)
+  unwrap: (parsed, response) => isJsonObject(parsed) && Object.hasOwn(parsed, "data") ? ResultExtensions.ok(parsed["data"]) : ResultExtensions.fail(ApiFailureFactory.create("protocol", response)),
+  toFailure: (parsed, response) => ApiFailureFactory.create("http", response, isJsonObject(parsed) ? parsed : null)
 };
 const rawEnvelope = {
-  unwrap: (parsed) => parsed,
-  toError: (_parsed, response) => new ApiError(response.status, null, response.statusText || void 0)
+  unwrap: (parsed) => ResultExtensions.ok(parsed),
+  toFailure: (_parsed, response) => ApiFailureFactory.create("http", response)
 };
-const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
-const PLAIN_DATE = /^\d{4}-\d{2}-\d{2}$/;
-const PLAIN_TIME = /^\d{2}:\d{2}(:\d{2})?(\.\d+)?$/;
-const DURATION = /^-?P(?=[\dT])(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(\d+H)?(\d+M)?(\d+(\.\d+)?S)?)?$/;
-function temporalReviver(_key, value) {
-  if (typeof value !== "string") return value;
-  if (INSTANT.test(value)) {
-    try {
-      return Temporal.Instant.from(value);
-    } catch {
-      return value;
-    }
-  }
-  if (PLAIN_DATE.test(value)) {
-    try {
-      return Temporal.PlainDate.from(value);
-    } catch {
-      return value;
-    }
-  }
-  if (PLAIN_TIME.test(value)) {
-    try {
-      return Temporal.PlainTime.from(value);
-    } catch {
-      return value;
-    }
-  }
-  if (DURATION.test(value)) {
-    try {
-      return Temporal.Duration.from(value);
-    } catch {
-      return value;
-    }
-  }
-  return value;
-}
-function parseJson(text) {
-  return JSON.parse(text, temporalReviver);
-}
-const JsonMime = "application/json";
 function buildQueryString(query) {
   const params = new URLSearchParams();
   for (const [key, value] of Object.entries(query)) {
@@ -62,119 +22,158 @@ function buildQueryString(query) {
   }
   return params.toString();
 }
+function interruption(signal, error) {
+  if (isTimeoutError(error) || signal?.aborted && isTimeoutError(signal.reason))
+    return ApiFailureFactory.create("timeout");
+  if (signal?.aborted || isAbortError(error)) return ApiFailureFactory.create("cancelled");
+  return void 0;
+}
 function wait(ms, signal) {
-  return new Promise((resolve, reject) => {
-    const abortReason = () => signal?.reason ?? new DOMException("The operation was aborted.", "AbortError");
+  return new Promise((resolve) => {
     if (signal?.aborted) {
-      reject(abortReason());
+      resolve();
       return;
     }
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
+    const finish = () => {
       clearTimeout(timer);
-      reject(abortReason());
+      signal?.removeEventListener("abort", finish);
+      resolve();
     };
-    signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener("abort", finish, { once: true });
   });
 }
-async function readErrorBody(response) {
-  try {
-    const text = await response.text();
-    return text === "" ? void 0 : JSON.parse(text);
-  } catch {
-    return void 0;
-  }
-}
 function createApiClient(options = {}) {
-  const {
-    baseUrl = "",
-    getAuthToken,
-    credentials,
-    onUnauthorized,
-    defaultHeaders,
-    reviveTemporal = false,
-    envelope = wowTwoEnvelope,
-    retry = false
-  } = options;
-  const buildHeaders = async (init, hasJsonBody) => {
-    const headers = new Headers({ Accept: JsonMime });
-    if (hasJsonBody) headers.set("Content-Type", JsonMime);
+  const { baseUrl = "", getAuthToken, credentials, defaultHeaders, envelope = wowTwoEnvelope, retry = false } = options;
+  const attempt = async (url, init, body, hasJsonBody) => {
+    const cancelled = interruption(init.signal);
+    if (cancelled) return ResultExtensions.fail(cancelled);
+    const headers = new Headers({ Accept: "application/json" });
+    if (hasJsonBody) headers.set("Content-Type", "application/json");
     if (defaultHeaders) new Headers(defaultHeaders).forEach((value, key) => headers.set(key, value));
     const token = getAuthToken ? await getAuthToken() : null;
     if (token != null) headers.set("Authorization", `Bearer ${token}`);
     if (init.headers) new Headers(init.headers).forEach((value, key) => headers.set(key, value));
-    return headers;
-  };
-  const attempt = async (url, init, body, hasJsonBody) => {
-    const headers = await buildHeaders(init, hasJsonBody);
-    const doFetch = options.fetch ?? globalThis.fetch;
     let response;
     try {
-      response = await doFetch(url, {
+      response = await (options.fetch ?? globalThis.fetch)(url, {
         method: init.method ?? "GET",
         headers,
-        // `?? null` lets callers pass an optional signal directly under exactOptionalPropertyTypes.
         signal: init.signal ?? null,
         ...credentials !== void 0 ? { credentials } : {},
         ...body !== void 0 ? { body } : {}
       });
     } catch (error) {
-      if (isAbortError(error)) throw error;
-      throw new ApiError(0, null, getErrorMessage(error, "Network request failed"));
+      return ResultExtensions.fail(interruption(init.signal, error) ?? ApiFailureFactory.create("transport"));
+    }
+    let text;
+    try {
+      text = await response.text();
+    } catch (error) {
+      return ResultExtensions.fail(interruption(init.signal, error) ?? ApiFailureFactory.create("transport", response));
+    }
+    const aborted = interruption(init.signal);
+    if (aborted) return ResultExtensions.fail(aborted);
+    if (!response.ok) {
+      let diagnostics;
+      if (text !== "" && options.json) {
+        const decoded = options.json.parse(text);
+        const interrupted = interruption(init.signal);
+        if (interrupted) return ResultExtensions.fail(interrupted);
+        if (!decoded.ok) return ResultExtensions.fail(ApiFailureFactory.create("protocol", response));
+        diagnostics = decoded.value;
+      } else {
+        try {
+          diagnostics = text === "" ? void 0 : JSON.parse(text);
+        } catch {
+          diagnostics = void 0;
+        }
+      }
+      return ResultExtensions.fail(envelope.toFailure(diagnostics, response));
     }
-    if (!response.ok) throw envelope.toError(await readErrorBody(response), response);
-    const text = await response.text();
-    if (text === "") return void 0;
-    const parsed = reviveTemporal ? parseJson(text) : JSON.parse(text);
-    if (init.unwrap === false) return parsed;
-    return envelope.unwrap(parsed, response);
+    if (init.response === "empty")
+      return text === "" ? ResultExtensions.ok(void 0) : ResultExtensions.fail(ApiFailureFactory.create("protocol", response));
+    if (text === "" || !/^application\/(?:[\w.-]+\+)?json(?:;|$)/i.test(response.headers.get("Content-Type") ?? "")) {
+      return ResultExtensions.fail(ApiFailureFactory.create("protocol", response));
+    }
+    let parsed;
+    if (options.json) {
+      const decoded = options.json.parse(text);
+      const interrupted = interruption(init.signal);
+      if (interrupted) return ResultExtensions.fail(interrupted);
+      if (!decoded.ok) return ResultExtensions.fail(ApiFailureFactory.create("protocol", response));
+      parsed = decoded.value;
+    } else {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        return ResultExtensions.fail(ApiFailureFactory.create("protocol", response));
+      }
+    }
+    const payload = init.unwrap === false ? ResultExtensions.ok(parsed) : envelope.unwrap(parsed, response);
+    if (!payload.ok) return payload;
+    return init.decode ? init.decode(payload.value) : payload;
   };
-  const request = async (path, init = {}) => {
-    const queryString = init.query ? buildQueryString(init.query) : "";
-    const url = `${baseUrl}${path}${queryString ? (path.includes("?") ? "&" : "?") + queryString : ""}`;
+  const execute = async (path, init) => {
+    const cancelled = interruption(init.signal);
+    if (cancelled) return ResultExtensions.fail(cancelled);
+    const query = init.query ? buildQueryString(init.query) : "";
+    const url = `${baseUrl}${path}${query ? (path.includes("?") ? "&" : "?") + query : ""}`;
     const isFormData = typeof FormData !== "undefined" && init.body instanceof FormData;
-    const body = init.body === void 0 ? void 0 : isFormData ? init.body : JSON.stringify(init.body);
+    let body;
+    if (init.body !== void 0 && !isFormData && options.json) {
+      const encoded = options.json.stringify(init.body);
+      const interrupted = interruption(init.signal);
+      if (interrupted) return ResultExtensions.fail(interrupted);
+      if (!encoded.ok) return ResultExtensions.fail(ApiFailureFactory.create("validation"));
+      body = encoded.value;
+    } else {
+      body = init.body === void 0 ? void 0 : isFormData ? init.body : JSON.stringify(init.body);
+    }
     let retries = 0;
     let previousDelayMs = 0;
     for (; ; ) {
-      try {
-        return await attempt(url, init, body, init.body !== void 0 && !isFormData);
-      } catch (error) {
-        if (!(error instanceof ApiError)) throw error;
-        if (retry !== false && shouldRetry(retry, retries, error.status)) {
-          const attemptNumber = retries + 1;
-          const delayMs = computeRetryDelay(retry, attemptNumber, previousDelayMs);
-          retry.onRetry?.({ attempt: attemptNumber, error, status: error.status, delayMs });
-          await wait(delayMs, init.signal);
-          previousDelayMs = delayMs;
-          retries = attemptNumber;
-          continue;
-        }
-        if (error.status === 401) onUnauthorized?.(error);
-        throw error;
+      const result = await attempt(url, init, body, init.body !== void 0 && !isFormData);
+      if (result.ok) return result;
+      const failure = result.failure;
+      const retryable = failure.code === "http" || failure.code === "transport";
+      const idempotent = ["GET", "HEAD", "OPTIONS"].includes((init.method ?? "GET").toUpperCase());
+      if (retry !== false && retryable && idempotent && shouldRetry(retry, retries, failure.status)) {
+        const attemptNumber = retries + 1;
+        const delayMs = computeRetryDelay(retry, attemptNumber, previousDelayMs);
+        retry.onRetry?.({ attempt: attemptNumber, error: new ApiError(failure), status: failure.status, delayMs });
+        await wait(delayMs, init.signal);
+        retries = attemptNumber;
+        previousDelayMs = delayMs;
+        continue;
       }
+      if (failure.status === 401) options.onUnauthorized?.(failure);
+      return result;
+    }
+  };
+  const method = (verb) => {
+    function send(path, init = {}) {
+      return execute(path, verb ? { ...init, method: verb } : init);
     }
+    return send;
   };
   return {
-    request,
-    get: (path, init) => request(path, { ...init, method: "GET" }),
-    post: (path, init) => request(path, { ...init, method: "POST" }),
-    put: (path, init) => request(path, { ...init, method: "PUT" }),
-    patch: (path, init) => request(path, { ...init, method: "PATCH" }),
-    delete: (path, init) => request(path, { ...init, method: "DELETE" })
+    request: method(),
+    get: method("GET"),
+    post: method("POST"),
+    put: method("PUT"),
+    patch: method("PATCH"),
+    delete: method("DELETE")
   };
 }
 export {
   ApiError,
+  b as ApiFailureCode,
+  ApiFailureFactory,
   createApiClient,
-  a as fieldErrors,
-  f as fieldIssues,
-  parseJson,
+  f as fieldErrors,
+  a as fieldIssues,
   rawEnvelope,
-  temporalReviver,
   wowTwoEnvelope
 };
 //# sourceMappingURL=index.js.map

package/dist/foundation/http/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/http/Envelope.ts","../../../src/foundation/http/temporalReviver.ts","../../../src/foundation/http/CreateApiClient.ts"],"sourcesContent":["import { ApiError } from './ApiError';\nimport type { ProblemDetails } from './ProblemDetails';\n\n/** Checks whether a parsed body is a plain JSON object — not `null`, not an array — the only shape that can carry an envelope or a problem. */\nconst isJsonObject = (parsed: unknown): parsed is Record<string, unknown> =>\n  parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);\n\n/**\n * Defines the wire-contract strategy for `createApiClient` — how a parsed 2xx body yields the payload\n * and how a parsed non-2xx body yields the thrown error. The client core stays contract-free: it reads\n * and parses the body (an empty body resolves `undefined` before any strategy runs; a network failure\n * throws a core {@link ApiError} status `0` — there is no response to delegate) and hands the rest here.\n */\nexport interface ResponseEnvelope {\n  /** Extracts the payload from a parsed 2xx body. Skipped when the request passes `unwrap: false` — the request flag wins over the strategy. */\n  readonly unwrap: (parsed: unknown, response: Response) => unknown;\n\n  /**\n   * Builds the error thrown for a non-2xx response from its parsed body (plain JSON, no Temporal\n   * revive; `undefined` when empty or malformed). Return an {@link ApiError} to keep retry and\n   * `onUnauthorized` working — both key off the thrown error's `status` — a foreign `Error` type\n   * simply never triggers them.\n   */\n  readonly toError: (parsed: unknown, response: Response) => Error;\n}\n\n/**\n * Provides the wow-two wire contract (the default): a 2xx object body shaped `{ data }` (`ApiResponse`)\n * unwraps to its `data` member — anything else, including a literal `null` body, passes through\n * unchanged — and a non-2xx JSON-object body is taken as the RFC 7807 {@link ProblemDetails} (non-object\n * bodies → `null` problem), thrown as {@link ApiError} with its message precedence: title → detail →\n * status fallback.\n */\nexport const wowTwoEnvelope: ResponseEnvelope = {\n  unwrap: (parsed) => (isJsonObject(parsed) && 'data' in parsed ? parsed['data'] : parsed),\n  toError: (parsed, response) => new ApiError(response.status, isJsonObject(parsed) ? (parsed as ProblemDetails) : null),\n};\n\n/**\n * Provides the identity contract for un-enveloped APIs: 2xx bodies pass through unchanged, and a\n * non-2xx response throws `ApiError(status, null, statusText)` — deliberately still an {@link ApiError}\n * rather than a plain `Error`, so `status`-keyed retry, `onUnauthorized`, and caller `instanceof`\n * handling stay uniform across envelopes. The error body is ignored (no contract to read a problem\n * from); an empty `statusText` (HTTP/2 sends none) falls back to `Request failed with status N`.\n */\nexport const rawEnvelope: ResponseEnvelope = {\n  unwrap: (parsed) => parsed,\n  toError: (_parsed, response) => new ApiError(response.status, null, response.statusText || undefined),\n};\n","import { Temporal } from 'temporal-polyfill';\n\n// Strict ISO-8601 shapes. Anchored (^…$) so partial / lenient strings never match — only a\n// wire value that is unambiguously one Temporal kind is upgraded; everything else stays a string.\nconst INSTANT = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$/;\nconst PLAIN_DATE = /^\\d{4}-\\d{2}-\\d{2}$/;\nconst PLAIN_TIME = /^\\d{2}:\\d{2}(:\\d{2})?(\\.\\d+)?$/;\n// ISO-8601 duration: sign, `P`, then at least one designator (lookahead rejects a bare `P`).\nconst DURATION = /^-?P(?=[\\dT])(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$/;\n\n/**\n * Upgrades a matching ISO-8601 string to its `Temporal.*` value; returns everything else unchanged.\n * Intended as the reviver argument to `JSON.parse` so inbound date fields arrive as Temporal objects\n * (outbound is automatic via each `Temporal.*.toJSON()`). Each parse is guarded — an ISO-shaped but\n * invalid value (e.g. `2026-13-40`) falls back to the raw string rather than throwing.\n */\nexport function temporalReviver(_key: string, value: unknown): unknown {\n  if (typeof value !== 'string') return value;\n\n  if (INSTANT.test(value)) {\n    try {\n      return Temporal.Instant.from(value);\n    } catch {\n      return value;\n    }\n  }\n  if (PLAIN_DATE.test(value)) {\n    try {\n      return Temporal.PlainDate.from(value);\n    } catch {\n      return value;\n    }\n  }\n  if (PLAIN_TIME.test(value)) {\n    try {\n      return Temporal.PlainTime.from(value);\n    } catch {\n      return value;\n    }\n  }\n  if (DURATION.test(value)) {\n    try {\n      return Temporal.Duration.from(value);\n    } catch {\n      return value;\n    }\n  }\n  return value;\n}\n\n/** Parses a JSON string with {@link temporalReviver} applied, upgrading ISO date fields to `Temporal.*`. */\nexport function parseJson<T>(text: string): T {\n  return JSON.parse(text, temporalReviver) as T;\n}\n","import { getErrorMessage, isAbortError } from '../errors';\nimport { computeRetryDelay, shouldRetry, type RetryPolicy } from '../resilience';\n\nimport { ApiError } from './ApiError';\nimport { wowTwoEnvelope, type ResponseEnvelope } from './Envelope';\nimport { parseJson } from './temporalReviver';\n\nconst JsonMime = 'application/json';\n\n/** Defines query params appended to a request path — arrays repeat the key; `null`/`undefined` entries are skipped; everything else is `String()`-ed. */\nexport type ApiQueryParams = Record<string, unknown>;\n\n/** Defines the per-request init accepted by every {@link ApiClient} method. */\nexport interface ApiRequestInit {\n  /** The query params appended to the path (see {@link ApiQueryParams}); merged onto any query string already in the path. */\n  readonly query?: ApiQueryParams;\n\n  /** The request body — JSON-stringified with `Content-Type: application/json`, except `FormData`, which passes through untouched (the runtime sets the multipart boundary). */\n  readonly body?: unknown;\n\n  /** Aborts the request (and any retry wait) — an abort rethrows the native `AbortError`, never an {@link ApiError}. */\n  readonly signal?: AbortSignal | null;\n\n  /** Extra headers merged last — they win over the computed JSON headers, the client defaults, and the bearer token. */\n  readonly headers?: HeadersInit;\n\n  /** Whether to run the envelope's unwrap on the parsed body. Default `true`; `false` returns the body exactly as parsed — the request flag wins over {@link ApiClientOptions.envelope}. */\n  readonly unwrap?: boolean;\n\n  /** The HTTP method for the `request` escape hatch. Default `GET`. The verb helpers force their own method. */\n  readonly method?: string;\n}\n\n/** Defines the options for {@link createApiClient}. */\nexport interface ApiClientOptions {\n  /** The prefix for every request path. Default `''` (same-origin — the SPA is served by the API host). */\n  readonly baseUrl?: string;\n\n  /** Supplies the bearer token, re-read on every attempt — return `null` to skip the `Authorization` header (signed-out / cookie mode). */\n  readonly getAuthToken?: () => string | null | Promise<string | null>;\n\n  /** The fetch credentials mode — `'include'` for cross-origin cookie auth; omit for the runtime default. */\n  readonly credentials?: RequestCredentials;\n\n  /** Fires on a 401 after the {@link ApiError} is built (which is still thrown) — wire session-expiry handling here. */\n  readonly onUnauthorized?: (error: ApiError) => void;\n\n  /** Headers applied to every request; per-request headers win. */\n  readonly defaultHeaders?: HeadersInit;\n\n  /** Whether to parse response bodies through the Temporal reviver so ISO date fields arrive as `Temporal.*`. Default `false`. */\n  readonly reviveTemporal?: boolean;\n\n  /** The wire-contract strategy — how 2xx bodies unwrap and how non-2xx bodies become thrown errors. Default {@link wowTwoEnvelope} (zero-config for wow-two APIs); use `rawEnvelope` for un-enveloped APIs, or supply your own. */\n  readonly envelope?: ResponseEnvelope;\n\n  /** The transport-level retry policy for transient failures. Default `false` (off) — leave off under `/query`, which owns retries, or requests double-retry. */\n  readonly retry?: RetryPolicy | false;\n\n  /** The fetch implementation, resolved per request. Default the global `fetch` — injectable for tests. */\n  readonly fetch?: typeof globalThis.fetch;\n}\n\n/** Defines the typed HTTP client returned by {@link createApiClient}. */\nexport interface ApiClient {\n  /** Sends a GET request. */\n  get<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;\n\n  /** Sends a POST request. */\n  post<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;\n\n  /** Sends a PUT request. */\n  put<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;\n\n  /** Sends a PATCH request. */\n  patch<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;\n\n  /** Sends a DELETE request. */\n  delete<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;\n\n  /** Sends a request with an arbitrary method (`init.method`, default `GET`) — the escape hatch under the verb helpers. */\n  request<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;\n}\n\n/** Serializes query params — arrays repeat the key, `null`/`undefined` entries are skipped. */\nfunction buildQueryString(query: ApiQueryParams): string {\n  const params = new URLSearchParams();\n  for (const [key, value] of Object.entries(query)) {\n    for (const item of Array.isArray(value) ? value : [value]) {\n      if (item != null) params.append(key, String(item));\n    }\n  }\n  return params.toString();\n}\n\n/** Waits `ms` before a retry attempt, rejecting with the signal's native abort reason if aborted mid-wait. */\nfunction wait(ms: number, signal?: AbortSignal | null): Promise<void> {\n  return new Promise((resolve, reject) => {\n    const abortReason = (): unknown => signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError');\n    if (signal?.aborted) {\n      reject(abortReason());\n      return;\n    }\n    const timer = setTimeout(() => {\n      signal?.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n    const onAbort = (): void => {\n      clearTimeout(timer);\n      reject(abortReason());\n    };\n    signal?.addEventListener('abort', onAbort, { once: true });\n  });\n}\n\n/** Reads a non-2xx body as plain JSON for the envelope's `toError` — empty, unreadable, or malformed bodies yield `undefined`. */\nasync function readErrorBody(response: Response): Promise<unknown> {\n  try {\n    const text = await response.text();\n    return text === '' ? undefined : (JSON.parse(text) as unknown);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Creates the typed fetch client every wow-two frontend talks through — JSON by default, a swappable\n * wire contract ({@link ApiClientOptions.envelope}, default {@link wowTwoEnvelope}: `{ data }` unwrap +\n * ProblemDetails → {@link ApiError}), body-driven empties (an empty body resolves `undefined` and a\n * literal `null` body resolves `null`, whatever the status), bearer/cookie auth, optional Temporal\n * revive, and opt-in transport retry (network failure → {@link ApiError} status `0`, envelope-independent).\n * Aborts rethrow the native `AbortError` so `/query` cancellation semantics stay intact.\n */\nexport function createApiClient(options: ApiClientOptions = {}): ApiClient {\n  const {\n    baseUrl = '',\n    getAuthToken,\n    credentials,\n    onUnauthorized,\n    defaultHeaders,\n    reviveTemporal = false,\n    envelope = wowTwoEnvelope,\n    retry = false,\n  } = options;\n\n  /** Builds the attempt's headers — JSON base → client defaults → bearer token → per-request (last wins). */\n  const buildHeaders = async (init: ApiRequestInit, hasJsonBody: boolean): Promise<Headers> => {\n    const headers = new Headers({ Accept: JsonMime });\n    if (hasJsonBody) headers.set('Content-Type', JsonMime);\n    if (defaultHeaders) new Headers(defaultHeaders).forEach((value, key) => headers.set(key, value));\n    const token = getAuthToken ? await getAuthToken() : null;\n    if (token != null) headers.set('Authorization', `Bearer ${token}`);\n    if (init.headers) new Headers(init.headers).forEach((value, key) => headers.set(key, value));\n    return headers;\n  };\n\n  /** Performs one attempt — throws `ApiError` for transport failures, rethrows aborts natively. */\n  const attempt = async <T>(url: string, init: ApiRequestInit, body: BodyInit | undefined, hasJsonBody: boolean): Promise<T> => {\n    // Outside the try: a token-delegate crash is a programmer error, not a transport failure.\n    const headers = await buildHeaders(init, hasJsonBody);\n    const doFetch = options.fetch ?? globalThis.fetch;\n\n    let response: Response;\n    try {\n      response = await doFetch(url, {\n        method: init.method ?? 'GET',\n        headers,\n        // `?? null` lets callers pass an optional signal directly under exactOptionalPropertyTypes.\n        signal: init.signal ?? null,\n        ...(credentials !== undefined ? { credentials } : {}),\n        ...(body !== undefined ? { body } : {}),\n      });\n    } catch (error) {\n      if (isAbortError(error)) throw error;\n      throw new ApiError(0, null, getErrorMessage(error, 'Network request failed'));\n    }\n\n    if (!response.ok) throw envelope.toError(await readErrorBody(response), response);\n\n    // Body-driven, not status-driven: no 204 / Content-Length sniffing. An empty body (any\n    // status) resolves `undefined`; a literal `null` JSON body parses — and returns — as `null`.\n    const text = await response.text();\n    if (text === '') return undefined as T;\n\n    const parsed: unknown = reviveTemporal ? parseJson<unknown>(text) : (JSON.parse(text) as unknown);\n    if (init.unwrap === false) return parsed as T;\n    return envelope.unwrap(parsed, response) as T;\n  };\n\n  const request = async <T = unknown>(path: string, init: ApiRequestInit = {}): Promise<T> => {\n    const queryString = init.query ? buildQueryString(init.query) : '';\n    const url = `${baseUrl}${path}${queryString ? (path.includes('?') ? '&' : '?') + queryString : ''}`;\n    const isFormData = typeof FormData !== 'undefined' && init.body instanceof FormData;\n    const body: BodyInit | undefined =\n      init.body === undefined ? undefined : isFormData ? (init.body as FormData) : JSON.stringify(init.body);\n\n    let retries = 0;\n    let previousDelayMs = 0;\n    for (;;) {\n      try {\n        return await attempt<T>(url, init, body, init.body !== undefined && !isFormData);\n      } catch (error) {\n        // Only ApiErrors drive retry/401 — aborts, token-delegate crashes, malformed-JSON parse\n        // errors, and foreign error types from a custom envelope's `toError` all pass through\n        // natively (the `/query` layer coerces whatever it catches).\n        if (!(error instanceof ApiError)) throw error;\n        if (retry !== false && shouldRetry(retry, retries, error.status)) {\n          const attemptNumber = retries + 1;\n          const delayMs = computeRetryDelay(retry, attemptNumber, previousDelayMs);\n          retry.onRetry?.({ attempt: attemptNumber, error, status: error.status, delayMs });\n          await wait(delayMs, init.signal);\n          previousDelayMs = delayMs;\n          retries = attemptNumber;\n          continue;\n        }\n        if (error.status === 401) onUnauthorized?.(error);\n        throw error;\n      }\n    }\n  };\n\n  return {\n    request,\n    get: <T = unknown>(path: string, init?: ApiRequestInit): Promise<T> => request<T>(path, { ...init, method: 'GET' }),\n    post: <T = unknown>(path: string, init?: ApiRequestInit): Promise<T> => request<T>(path, { ...init, method: 'POST' }),\n    put: <T = unknown>(path: string, init?: ApiRequestInit): Promise<T> => request<T>(path, { ...init, method: 'PUT' }),\n    patch: <T = unknown>(path: string, init?: ApiRequestInit): Promise<T> => request<T>(path, { ...init, method: 'PATCH' }),\n    delete: <T = unknown>(path: string, init?: ApiRequestInit): Promise<T> => request<T>(path, { ...init, method: 'DELETE' }),\n  };\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/http/Envelope.ts","../../../src/foundation/http/CreateApiClient.ts"],"sourcesContent":["import { ResultExtensions, type Result } from '../results';\nimport { ApiFailureFactory, type ApiFailure } from './ApiFailure';\n\nconst isJsonObject = (parsed: unknown): parsed is Record<string, unknown> =>\n  parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed);\n\n/** Declares success-envelope decoding and non-success transport diagnostics. */\nexport interface ResponseEnvelope {\n  readonly unwrap: (parsed: unknown, response: Response) => Result<unknown, ApiFailure>;\n  readonly toFailure: (parsed: unknown, response: Response) => ApiFailure;\n}\n\n/** Requires a JSON object with its own data member. */\nexport const wowTwoEnvelope: ResponseEnvelope = {\n  unwrap: (parsed, response) =>\n    isJsonObject(parsed) && Object.hasOwn(parsed, 'data')\n      ? ResultExtensions.ok(parsed['data'])\n      : ResultExtensions.fail(ApiFailureFactory.create('protocol', response)),\n  toFailure: (parsed, response) => ApiFailureFactory.create('http', response, isJsonObject(parsed) ? parsed : null),\n};\n\n/** Leaves un-enveloped JSON values unchanged. */\nexport const rawEnvelope: ResponseEnvelope = {\n  unwrap: (parsed) => ResultExtensions.ok(parsed),\n  toFailure: (_parsed, response) => ApiFailureFactory.create('http', response),\n};\n","import { isAbortError, isTimeoutError } from '../errors';\nimport { computeRetryDelay, shouldRetry, type RetryPolicy } from '../resilience';\nimport { ResultExtensions, type Result } from '../results';\nimport { ApiError } from './ApiError';\nimport type { ApiJsonCodec } from './ApiJsonCodec';\nimport { ApiFailureFactory, type ApiFailure } from './ApiFailure';\nimport { wowTwoEnvelope, type ResponseEnvelope } from './Envelope';\n\nexport type ApiQueryParams = Record<string, unknown>;\nexport type ApiDecoder<T> = (value: unknown) => Result<T, ApiFailure>;\nexport interface ApiRequestInit {\n  readonly query?: ApiQueryParams;\n  readonly body?: unknown;\n  readonly signal?: AbortSignal | null;\n  readonly headers?: HeadersInit;\n  readonly unwrap?: boolean;\n  readonly method?: string;\n}\nexport interface ApiEmptyRequestInit extends ApiRequestInit {\n  readonly response: 'empty';\n}\nexport interface ApiJsonRequestInit<T> extends ApiRequestInit {\n  readonly response?: 'json';\n  readonly decode: ApiDecoder<T>;\n}\nexport interface ApiClientOptions {\n  readonly baseUrl?: string;\n  readonly getAuthToken?: () => string | null | Promise<string | null>;\n  readonly credentials?: RequestCredentials;\n  readonly onUnauthorized?: (failure: ApiFailure) => void;\n  readonly defaultHeaders?: HeadersInit;\n  readonly envelope?: ResponseEnvelope;\n  readonly retry?: RetryPolicy | false;\n  readonly fetch?: typeof globalThis.fetch;\n  /** Overrides request/response JSON conversion, including non-success diagnostics. Native JSON is the default. */\n  readonly json?: ApiJsonCodec;\n}\n/** Typed payloads require a decoder; an empty response must be requested explicitly. */\nexport interface ApiMethod {\n  (path: string, init: ApiEmptyRequestInit): Promise<Result<void, ApiFailure>>;\n  <T>(path: string, init: ApiJsonRequestInit<T>): Promise<Result<T, ApiFailure>>;\n  (path: string, init?: ApiRequestInit): Promise<Result<unknown, ApiFailure>>;\n}\nexport interface ApiClient {\n  readonly get: ApiMethod;\n  readonly post: ApiMethod;\n  readonly put: ApiMethod;\n  readonly patch: ApiMethod;\n  readonly delete: ApiMethod;\n  readonly request: ApiMethod;\n}\ninterface RequestOptions extends ApiRequestInit {\n  readonly response?: 'json' | 'empty';\n  readonly decode?: ApiDecoder<unknown>;\n}\nfunction buildQueryString(query: ApiQueryParams): string {\n  const params = new URLSearchParams();\n  for (const [key, value] of Object.entries(query)) {\n    for (const item of Array.isArray(value) ? value : [value]) {\n      if (item != null) params.append(key, String(item));\n    }\n  }\n  return params.toString();\n}\nfunction interruption(signal?: AbortSignal | null, error?: unknown): ApiFailure | undefined {\n  if (isTimeoutError(error) || (signal?.aborted && isTimeoutError(signal.reason)))\n    return ApiFailureFactory.create('timeout');\n  if (signal?.aborted || isAbortError(error)) return ApiFailureFactory.create('cancelled');\n  return undefined;\n}\n/** Wakes immediately on cancellation; the request loop returns its typed outcome. */\nfunction wait(ms: number, signal?: AbortSignal | null): Promise<void> {\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve();\n      return;\n    }\n    const finish = (): void => {\n      clearTimeout(timer);\n      signal?.removeEventListener('abort', finish);\n      resolve();\n    };\n    const timer = setTimeout(finish, ms);\n    signal?.addEventListener('abort', finish, { once: true });\n  });\n}\n/** Returns expected transport/protocol failures; application decoder bugs still throw. */\nexport function createApiClient(options: ApiClientOptions = {}): ApiClient {\n  const { baseUrl = '', getAuthToken, credentials, defaultHeaders, envelope = wowTwoEnvelope, retry = false } = options;\n  const attempt = async (\n    url: string,\n    init: RequestOptions,\n    body: BodyInit | undefined,\n    hasJsonBody: boolean,\n  ): Promise<Result<unknown, ApiFailure>> => {\n    const cancelled = interruption(init.signal);\n    if (cancelled) return ResultExtensions.fail(cancelled);\n    const headers = new Headers({ Accept: 'application/json' });\n    if (hasJsonBody) headers.set('Content-Type', 'application/json');\n    if (defaultHeaders) new Headers(defaultHeaders).forEach((value, key) => headers.set(key, value));\n    const token = getAuthToken ? await getAuthToken() : null;\n    if (token != null) headers.set('Authorization', `Bearer ${token}`);\n    if (init.headers) new Headers(init.headers).forEach((value, key) => headers.set(key, value));\n    let response: Response;\n    try {\n      response = await (options.fetch ?? globalThis.fetch)(url, {\n        method: init.method ?? 'GET',\n        headers,\n        signal: init.signal ?? null,\n        ...(credentials !== undefined ? { credentials } : {}),\n        ...(body !== undefined ? { body } : {}),\n      });\n    } catch (error) {\n      return ResultExtensions.fail(interruption(init.signal, error) ?? ApiFailureFactory.create('transport'));\n    }\n    let text: string;\n    try {\n      text = await response.text();\n    } catch (error) {\n      return ResultExtensions.fail(interruption(init.signal, error) ?? ApiFailureFactory.create('transport', response));\n    }\n    const aborted = interruption(init.signal);\n    if (aborted) return ResultExtensions.fail(aborted);\n    if (!response.ok) {\n      let diagnostics: unknown;\n      if (text !== '' && options.json) {\n        const decoded = options.json.parse(text);\n        const interrupted = interruption(init.signal);\n        if (interrupted) return ResultExtensions.fail(interrupted);\n        if (!decoded.ok) return ResultExtensions.fail(ApiFailureFactory.create('protocol', response));\n        diagnostics = decoded.value;\n      } else {\n        try {\n          diagnostics = text === '' ? undefined : JSON.parse(text);\n        } catch {\n          diagnostics = undefined;\n        }\n      }\n      return ResultExtensions.fail(envelope.toFailure(diagnostics, response));\n    }\n    if (init.response === 'empty')\n      return text === ''\n        ? ResultExtensions.ok(undefined)\n        : ResultExtensions.fail(ApiFailureFactory.create('protocol', response));\n    if (text === '' || !/^application\\/(?:[\\w.-]+\\+)?json(?:;|$)/i.test(response.headers.get('Content-Type') ?? '')) {\n      return ResultExtensions.fail(ApiFailureFactory.create('protocol', response));\n    }\n    let parsed: unknown;\n    if (options.json) {\n      const decoded = options.json.parse(text);\n      const interrupted = interruption(init.signal);\n      if (interrupted) return ResultExtensions.fail(interrupted);\n      if (!decoded.ok) return ResultExtensions.fail(ApiFailureFactory.create('protocol', response));\n      parsed = decoded.value;\n    } else {\n      try {\n        parsed = JSON.parse(text);\n      } catch {\n        return ResultExtensions.fail(ApiFailureFactory.create('protocol', response));\n      }\n    }\n    const payload = init.unwrap === false ? ResultExtensions.ok(parsed) : envelope.unwrap(parsed, response);\n    if (!payload.ok) return payload;\n    return init.decode ? init.decode(payload.value) : payload;\n  };\n  const execute = async (path: string, init: RequestOptions): Promise<Result<unknown, ApiFailure>> => {\n    const cancelled = interruption(init.signal);\n    if (cancelled) return ResultExtensions.fail(cancelled);\n    const query = init.query ? buildQueryString(init.query) : '';\n    const url = `${baseUrl}${path}${query ? (path.includes('?') ? '&' : '?') + query : ''}`;\n    const isFormData = typeof FormData !== 'undefined' && init.body instanceof FormData;\n    let body: BodyInit | undefined;\n    if (init.body !== undefined && !isFormData && options.json) {\n      const encoded = options.json.stringify(init.body);\n      const interrupted = interruption(init.signal);\n      if (interrupted) return ResultExtensions.fail(interrupted);\n      if (!encoded.ok) return ResultExtensions.fail(ApiFailureFactory.create('validation'));\n      body = encoded.value;\n    } else {\n      body = init.body === undefined ? undefined : isFormData ? (init.body as FormData) : JSON.stringify(init.body);\n    }\n    let retries = 0;\n    let previousDelayMs = 0;\n    for (;;) {\n      const result = await attempt(url, init, body, init.body !== undefined && !isFormData);\n      if (result.ok) return result;\n      const failure = result.failure;\n      const retryable = failure.code === 'http' || failure.code === 'transport';\n      const idempotent = ['GET', 'HEAD', 'OPTIONS'].includes((init.method ?? 'GET').toUpperCase());\n      if (retry !== false && retryable && idempotent && shouldRetry(retry, retries, failure.status)) {\n        const attemptNumber = retries + 1;\n        const delayMs = computeRetryDelay(retry, attemptNumber, previousDelayMs);\n        retry.onRetry?.({ attempt: attemptNumber, error: new ApiError(failure), status: failure.status, delayMs });\n        await wait(delayMs, init.signal);\n        retries = attemptNumber;\n        previousDelayMs = delayMs;\n        continue;\n      }\n      if (failure.status === 401) options.onUnauthorized?.(failure);\n      return result;\n    }\n  };\n  const method = (verb?: string): ApiMethod => {\n    function send(path: string, init: ApiEmptyRequestInit): Promise<Result<void, ApiFailure>>;\n    function send<T>(path: string, init: ApiJsonRequestInit<T>): Promise<Result<T, ApiFailure>>;\n    function send(path: string, init?: ApiRequestInit): Promise<Result<unknown, ApiFailure>>;\n    function send(path: string, init: RequestOptions = {}): Promise<Result<unknown, ApiFailure>> {\n      return execute(path, verb ? { ...init, method: verb } : init);\n    }\n    return send;\n  };\n  return {\n    request: method(),\n    get: method('GET'),\n    post: method('POST'),\n    put: method('PUT'),\n    patch: method('PATCH'),\n    delete: method('DELETE'),\n  };\n}\n"],"names":[],"mappings":";;;;;;AAGA,MAAM,eAAe,CAAC,WACpB,WAAW,QAAQ,OAAO,WAAW,YAAY,CAAC,MAAM,QAAQ,MAAM;AASjE,MAAM,iBAAmC;AAAA,EAC9C,QAAQ,CAAC,QAAQ,aACf,aAAa,MAAM,KAAK,OAAO,OAAO,QAAQ,MAAM,IAChD,iBAAiB,GAAG,OAAO,MAAM,CAAC,IAClC,iBAAiB,KAAK,kBAAkB,OAAO,YAAY,QAAQ,CAAC;AAAA,EAC1E,WAAW,CAAC,QAAQ,aAAa,kBAAkB,OAAO,QAAQ,UAAU,aAAa,MAAM,IAAI,SAAS,IAAI;AAClH;AAGO,MAAM,cAAgC;AAAA,EAC3C,QAAQ,CAAC,WAAW,iBAAiB,GAAG,MAAM;AAAA,EAC9C,WAAW,CAAC,SAAS,aAAa,kBAAkB,OAAO,QAAQ,QAAQ;AAC7E;AC8BA,SAAS,iBAAiB,OAA+B;AACvD,QAAM,SAAS,IAAI,gBAAA;AACnB,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,eAAW,QAAQ,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK,GAAG;AACzD,UAAI,QAAQ,KAAM,QAAO,OAAO,KAAK,OAAO,IAAI,CAAC;AAAA,IACnD;AAAA,EACF;AACA,SAAO,OAAO,SAAA;AAChB;AACA,SAAS,aAAa,QAA6B,OAAyC;AAC1F,MAAI,eAAe,KAAK,KAAM,QAAQ,WAAW,eAAe,OAAO,MAAM;AAC3E,WAAO,kBAAkB,OAAO,SAAS;AAC3C,MAAI,QAAQ,WAAW,aAAa,KAAK,EAAG,QAAO,kBAAkB,OAAO,WAAW;AACvF,SAAO;AACT;AAEA,SAAS,KAAK,IAAY,QAA4C;AACpE,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,QAAI,QAAQ,SAAS;AACnB,cAAA;AACA;AAAA,IACF;AACA,UAAM,SAAS,MAAY;AACzB,mBAAa,KAAK;AAClB,cAAQ,oBAAoB,SAAS,MAAM;AAC3C,cAAA;AAAA,IACF;AACA,UAAM,QAAQ,WAAW,QAAQ,EAAE;AACnC,YAAQ,iBAAiB,SAAS,QAAQ,EAAE,MAAM,MAAM;AAAA,EAC1D,CAAC;AACH;AAEO,SAAS,gBAAgB,UAA4B,IAAe;AACzE,QAAM,EAAE,UAAU,IAAI,cAAc,aAAa,gBAAgB,WAAW,gBAAgB,QAAQ,MAAA,IAAU;AAC9G,QAAM,UAAU,OACd,KACA,MACA,MACA,gBACyC;AACzC,UAAM,YAAY,aAAa,KAAK,MAAM;AAC1C,QAAI,UAAW,QAAO,iBAAiB,KAAK,SAAS;AACrD,UAAM,UAAU,IAAI,QAAQ,EAAE,QAAQ,oBAAoB;AAC1D,QAAI,YAAa,SAAQ,IAAI,gBAAgB,kBAAkB;AAC/D,QAAI,eAAgB,KAAI,QAAQ,cAAc,EAAE,QAAQ,CAAC,OAAO,QAAQ,QAAQ,IAAI,KAAK,KAAK,CAAC;AAC/F,UAAM,QAAQ,eAAe,MAAM,aAAA,IAAiB;AACpD,QAAI,SAAS,KAAM,SAAQ,IAAI,iBAAiB,UAAU,KAAK,EAAE;AACjE,QAAI,KAAK,QAAS,KAAI,QAAQ,KAAK,OAAO,EAAE,QAAQ,CAAC,OAAO,QAAQ,QAAQ,IAAI,KAAK,KAAK,CAAC;AAC3F,QAAI;AACJ,QAAI;AACF,iBAAW,OAAO,QAAQ,SAAS,WAAW,OAAO,KAAK;AAAA,QACxD,QAAQ,KAAK,UAAU;AAAA,QACvB;AAAA,QACA,QAAQ,KAAK,UAAU;AAAA,QACvB,GAAI,gBAAgB,SAAY,EAAE,YAAA,IAAgB,CAAA;AAAA,QAClD,GAAI,SAAS,SAAY,EAAE,KAAA,IAAS,CAAA;AAAA,MAAC,CACtC;AAAA,IACH,SAAS,OAAO;AACd,aAAO,iBAAiB,KAAK,aAAa,KAAK,QAAQ,KAAK,KAAK,kBAAkB,OAAO,WAAW,CAAC;AAAA,IACxG;AACA,QAAI;AACJ,QAAI;AACF,aAAO,MAAM,SAAS,KAAA;AAAA,IACxB,SAAS,OAAO;AACd,aAAO,iBAAiB,KAAK,aAAa,KAAK,QAAQ,KAAK,KAAK,kBAAkB,OAAO,aAAa,QAAQ,CAAC;AAAA,IAClH;AACA,UAAM,UAAU,aAAa,KAAK,MAAM;AACxC,QAAI,QAAS,QAAO,iBAAiB,KAAK,OAAO;AACjD,QAAI,CAAC,SAAS,IAAI;AAChB,UAAI;AACJ,UAAI,SAAS,MAAM,QAAQ,MAAM;AAC/B,cAAM,UAAU,QAAQ,KAAK,MAAM,IAAI;AACvC,cAAM,cAAc,aAAa,KAAK,MAAM;AAC5C,YAAI,YAAa,QAAO,iBAAiB,KAAK,WAAW;AACzD,YAAI,CAAC,QAAQ,GAAI,QAAO,iBAAiB,KAAK,kBAAkB,OAAO,YAAY,QAAQ,CAAC;AAC5F,sBAAc,QAAQ;AAAA,MACxB,OAAO;AACL,YAAI;AACF,wBAAc,SAAS,KAAK,SAAY,KAAK,MAAM,IAAI;AAAA,QACzD,QAAQ;AACN,wBAAc;AAAA,QAChB;AAAA,MACF;AACA,aAAO,iBAAiB,KAAK,SAAS,UAAU,aAAa,QAAQ,CAAC;AAAA,IACxE;AACA,QAAI,KAAK,aAAa;AACpB,aAAO,SAAS,KACZ,iBAAiB,GAAG,MAAS,IAC7B,iBAAiB,KAAK,kBAAkB,OAAO,YAAY,QAAQ,CAAC;AAC1E,QAAI,SAAS,MAAM,CAAC,2CAA2C,KAAK,SAAS,QAAQ,IAAI,cAAc,KAAK,EAAE,GAAG;AAC/G,aAAO,iBAAiB,KAAK,kBAAkB,OAAO,YAAY,QAAQ,CAAC;AAAA,IAC7E;AACA,QAAI;AACJ,QAAI,QAAQ,MAAM;AAChB,YAAM,UAAU,QAAQ,KAAK,MAAM,IAAI;AACvC,YAAM,cAAc,aAAa,KAAK,MAAM;AAC5C,UAAI,YAAa,QAAO,iBAAiB,KAAK,WAAW;AACzD,UAAI,CAAC,QAAQ,GAAI,QAAO,iBAAiB,KAAK,kBAAkB,OAAO,YAAY,QAAQ,CAAC;AAC5F,eAAS,QAAQ;AAAA,IACnB,OAAO;AACL,UAAI;AACF,iBAAS,KAAK,MAAM,IAAI;AAAA,MAC1B,QAAQ;AACN,eAAO,iBAAiB,KAAK,kBAAkB,OAAO,YAAY,QAAQ,CAAC;AAAA,MAC7E;AAAA,IACF;AACA,UAAM,UAAU,KAAK,WAAW,QAAQ,iBAAiB,GAAG,MAAM,IAAI,SAAS,OAAO,QAAQ,QAAQ;AACtG,QAAI,CAAC,QAAQ,GAAI,QAAO;AACxB,WAAO,KAAK,SAAS,KAAK,OAAO,QAAQ,KAAK,IAAI;AAAA,EACpD;AACA,QAAM,UAAU,OAAO,MAAc,SAA+D;AAClG,UAAM,YAAY,aAAa,KAAK,MAAM;AAC1C,QAAI,UAAW,QAAO,iBAAiB,KAAK,SAAS;AACrD,UAAM,QAAQ,KAAK,QAAQ,iBAAiB,KAAK,KAAK,IAAI;AAC1D,UAAM,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,KAAK,SAAS,GAAG,IAAI,MAAM,OAAO,QAAQ,EAAE;AACrF,UAAM,aAAa,OAAO,aAAa,eAAe,KAAK,gBAAgB;AAC3E,QAAI;AACJ,QAAI,KAAK,SAAS,UAAa,CAAC,cAAc,QAAQ,MAAM;AAC1D,YAAM,UAAU,QAAQ,KAAK,UAAU,KAAK,IAAI;AAChD,YAAM,cAAc,aAAa,KAAK,MAAM;AAC5C,UAAI,YAAa,QAAO,iBAAiB,KAAK,WAAW;AACzD,UAAI,CAAC,QAAQ,GAAI,QAAO,iBAAiB,KAAK,kBAAkB,OAAO,YAAY,CAAC;AACpF,aAAO,QAAQ;AAAA,IACjB,OAAO;AACL,aAAO,KAAK,SAAS,SAAY,SAAY,aAAc,KAAK,OAAoB,KAAK,UAAU,KAAK,IAAI;AAAA,IAC9G;AACA,QAAI,UAAU;AACd,QAAI,kBAAkB;AACtB,eAAS;AACP,YAAM,SAAS,MAAM,QAAQ,KAAK,MAAM,MAAM,KAAK,SAAS,UAAa,CAAC,UAAU;AACpF,UAAI,OAAO,GAAI,QAAO;AACtB,YAAM,UAAU,OAAO;AACvB,YAAM,YAAY,QAAQ,SAAS,UAAU,QAAQ,SAAS;AAC9D,YAAM,aAAa,CAAC,OAAO,QAAQ,SAAS,EAAE,UAAU,KAAK,UAAU,OAAO,YAAA,CAAa;AAC3F,UAAI,UAAU,SAAS,aAAa,cAAc,YAAY,OAAO,SAAS,QAAQ,MAAM,GAAG;AAC7F,cAAM,gBAAgB,UAAU;AAChC,cAAM,UAAU,kBAAkB,OAAO,eAAe,eAAe;AACvE,cAAM,UAAU,EAAE,SAAS,eAAe,OAAO,IAAI,SAAS,OAAO,GAAG,QAAQ,QAAQ,QAAQ,SAAS;AACzG,cAAM,KAAK,SAAS,KAAK,MAAM;AAC/B,kBAAU;AACV,0BAAkB;AAClB;AAAA,MACF;AACA,UAAI,QAAQ,WAAW,IAAK,SAAQ,iBAAiB,OAAO;AAC5D,aAAO;AAAA,IACT;AAAA,EACF;AACA,QAAM,SAAS,CAAC,SAA6B;AAI3C,aAAS,KAAK,MAAc,OAAuB,IAA0C;AAC3F,aAAO,QAAQ,MAAM,OAAO,EAAE,GAAG,MAAM,QAAQ,KAAA,IAAS,IAAI;AAAA,IAC9D;AACA,WAAO;AAAA,EACT;AACA,SAAO;AAAA,IACL,SAAS,OAAA;AAAA,IACT,KAAK,OAAO,KAAK;AAAA,IACjB,MAAM,OAAO,MAAM;AAAA,IACnB,KAAK,OAAO,KAAK;AAAA,IACjB,OAAO,OAAO,OAAO;AAAA,IACrB,QAAQ,OAAO,QAAQ;AAAA,EAAA;AAE3B;"}

package/dist/foundation/http/models/Page.d.ts

@@ -0,0 +1,47 @@
+/** Defines a page's rows — the universal fragment every page carries. */
+export interface IHasItems<T> {
+    items: ReadonlyArray<T>;
+}
+/** Defines the effective page size a read was served at. */
+export interface IHasPageSize {
+    pageSize: number;
+}
+/** Defines the 1-based page index echo (offset paradigm; matches the `Pagination` component's `page`). */
+export interface IHasPageNumber {
+    pageNumber: number;
+}
+/** Defines the raw skip/limit echo — the alternate offset encoding for skip/take backends. */
+export interface IHasOffset {
+    offset: number;
+}
+/** Defines the total number of matching rows across all pages (offset paradigm). */
+export interface IHasTotalCount {
+    totalCount: number;
+}
+/**
+ * Defines the opaque forward continuation cursor (cursor/token paradigm). Generic over the token type
+ * (`string` by default, but a `number`, id, or any opaque cursor). An **absent** token marks the last page.
+ */
+export interface IHasPageToken<TToken = string> {
+    nextPageToken?: TToken;
+}
+/** Defines the "another page exists" flag — carry only when a backend sends one; otherwise has-more is derived. */
+export interface IHasMore {
+    hasMore: boolean;
+}
+/** Defines the server-side query elapsed time (diagnostics) — carry only where a screen renders it. */
+export interface IHasQueryTiming {
+    queryElapsedMs?: number;
+}
+/** Defines an echo of applied filter/sort/paging (`TQuery` = the product's `{Noun}QueryDto`) — stretch, opt-in. */
+export interface IHasAppliedQuery<TQuery> {
+    appliedQuery?: TQuery;
+}
+/** Defines an offset/page-indexed slice of a list read — the shape `useAppPaginatedQuery` binds `TPage` to. */
+export interface Page<T> extends IHasItems<T>, IHasPageNumber, IHasPageSize, IHasTotalCount {
+}
+/** Defines a cursor/token slice of a list read — the shape `useAppInfiniteQuery` binds `TPage` to. */
+export interface TokenPage<T, TToken = string> extends IHasItems<T>, IHasPageToken<TToken>, IHasPageSize {
+}
+/** Documented alias for {@link TokenPage} — "cursor" and "token" are the same keyset-forward paradigm. */
+export type CursorPage<T, TToken = string> = TokenPage<T, TToken>;

package/dist/foundation/i18n/IntlCache.d.ts

@@ -0,0 +1,4 @@
+/** Reuses recently used Intl instances and evicts only cache entries. */
+export declare function memoIntl<T>(key: string, create: () => T): T;
+/** Equivalent option objects share a cache entry regardless of insertion order. */
+export declare function intlOptionsKey(options: object | undefined): string;

package/dist/foundation/i18n/formattedRelative/FormattedRelative.vue.d.ts

@@ -0,0 +1,9 @@
+/** Props for `FormattedRelative`. */
+export interface FormattedRelativeProps {
+    /** Signed magnitude — negative = past (`-3` → "3 days ago"), positive = future. */
+    readonly value: number;
+    readonly unit: Intl.RelativeTimeFormatUnit;
+    readonly options?: Intl.RelativeTimeFormatOptions;
+}
+declare const _default: import('vue').DefineComponent<FormattedRelativeProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<FormattedRelativeProps> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/foundation/i18n/formattedRelative/index.d.ts

@@ -0,0 +1 @@
+export { default as FormattedRelative, type FormattedRelativeProps } from './FormattedRelative.vue';

package/dist/foundation/i18n/index.d.ts

@@ -1,4 +1,5 @@
-export * from './LocaleContext';
+export * from './providers/LocaleContext';
 export * from './LocaleFormatters';
-export { default as LocaleProvider, type LocaleProviderProps } from './LocaleProvider.vue';
-export { default as FormattedRelative, type FormattedRelativeProps } from './FormattedRelative.vue';
+export { default as LocaleProvider, type LocaleProviderProps } from './providers/LocaleProvider.vue';
+export { FormattedRelative, type FormattedRelativeProps } from './formattedRelative';
+export { createCollator, compareStrings } from './Compare';

package/dist/foundation/i18n/index.js

@@ -1,19 +1,11 @@
-import { u as useLocale, p as provideLocale } from "../../chunks/LocaleContext-B3UXrI6p.js";
-import { L, i, r } from "../../chunks/LocaleContext-B3UXrI6p.js";
-import { computed, defineComponent, renderSlot, toDisplayString } from "vue";
-const intlCache = /* @__PURE__ */ new Map();
-function memo(cacheKey, make) {
-  let instance = intlCache.get(cacheKey);
-  if (instance === void 0) {
-    instance = make();
-    intlCache.set(cacheKey, instance);
-  }
-  return instance;
-}
-const optKey = (options) => options ? JSON.stringify(options) : "";
+import { u as useLocale, p as provideLocale } from "../../chunks/LocaleContext-B7vUZmX-.js";
+import { L, i, r } from "../../chunks/LocaleContext-B7vUZmX-.js";
+import { computed, defineComponent, toRef, renderSlot, toDisplayString } from "vue";
+import { m as memoIntl, i as intlOptionsKey } from "../../chunks/Compare-C5NGppdh.js";
+import { c, a } from "../../chunks/Compare-C5NGppdh.js";
 function createLocaleFormatters(locale) {
-  const nf = (options) => memo(`n|${locale}|${optKey(options)}`, () => new Intl.NumberFormat(locale, options));
-  const dtf = (options) => memo(`d|${locale}|${optKey(options)}`, () => new Intl.DateTimeFormat(locale, options));
+  const nf = (options) => memoIntl(`n|${locale}|${intlOptionsKey(options)}`, () => new Intl.NumberFormat(locale, options));
+  const dtf = (options) => memoIntl(`d|${locale}|${intlOptionsKey(options)}`, () => new Intl.DateTimeFormat(locale, options));
   return {
     locale,
     number: (value, options) => nf(options).format(value),
@@ -21,9 +13,9 @@ function createLocaleFormatters(locale) {
     percent: (value, options) => nf({ ...options, style: "percent" }).format(value),
     date: (value, options) => dtf(options ?? { dateStyle: "medium" }).format(value),
     time: (value, options) => dtf(options ?? { timeStyle: "short" }).format(value),
-    relativeTime: (value, unit, options) => memo(`r|${locale}|${optKey(options)}`, () => new Intl.RelativeTimeFormat(locale, options)).format(value, unit),
-    list: (items, options) => memo(`l|${locale}|${optKey(options)}`, () => new Intl.ListFormat(locale, options)).format(items),
-    plural: (value, options) => memo(`p|${locale}|${optKey(options)}`, () => new Intl.PluralRules(locale, options)).select(value)
+    relativeTime: (value, unit, options) => memoIntl(`r|${locale}|${intlOptionsKey(options)}`, () => new Intl.RelativeTimeFormat(locale, options)).format(value, unit),
+    list: (items, options) => memoIntl(`l|${locale}|${intlOptionsKey(options)}`, () => new Intl.ListFormat(locale, options)).format(items),
+    plural: (value, options) => memoIntl(`p|${locale}|${intlOptionsKey(options)}`, () => new Intl.PluralRules(locale, options)).select(value)
   };
 }
 function useLocaleFormatters() {
@@ -39,10 +31,7 @@ const _sfc_main$1 = /* @__PURE__ */ defineComponent({
   },
   setup(__props) {
     const props = __props;
-    provideLocale(
-      () => props.locale,
-      () => props.messages
-    );
+    provideLocale(() => props.locale, toRef(props, "messages"));
     return (_ctx, _cache) => {
       return renderSlot(_ctx.$slots, "default");
     };
@@ -69,6 +58,8 @@ export {
   _sfc_main as FormattedRelative,
   L as LocaleKey,
   _sfc_main$1 as LocaleProvider,
+  c as compareStrings,
+  a as createCollator,
   createLocaleFormatters,
   i as interpolate,
   provideLocale,

package/dist/foundation/i18n/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/i18n/LocaleFormatters.ts","../../../src/foundation/i18n/LocaleProvider.vue","../../../src/foundation/i18n/FormattedRelative.vue"],"sourcesContent":["import { computed, type ComputedRef } from 'vue';\n\nimport { useLocale } from './LocaleContext';\n\n// `Intl` instances are cached across components by locale + options — constructing them is the expensive part,\n// so a shared module cache keeps `useLocaleFormatters` allocation-free after warm-up.\nconst intlCache = new Map<string, unknown>();\nfunction memo<T>(cacheKey: string, make: () => T): T {\n  let instance = intlCache.get(cacheKey) as T | undefined;\n  if (instance === undefined) {\n    instance = make();\n    intlCache.set(cacheKey, instance);\n  }\n  return instance;\n}\nconst optKey = (options: object | undefined): string => (options ? JSON.stringify(options) : '');\n\n/** Locale-bound `Intl` formatters — the surface every embedded-text component formats through. */\nexport interface LocaleFormatters {\n  /** The BCP-47 locale these formatters are bound to. */\n  locale: string;\n  number(value: number, options?: Intl.NumberFormatOptions): string;\n  currency(value: number, currency: string, options?: Intl.NumberFormatOptions): string;\n  percent(value: number, options?: Intl.NumberFormatOptions): string;\n  date(value: Date | number, options?: Intl.DateTimeFormatOptions): string;\n  time(value: Date | number, options?: Intl.DateTimeFormatOptions): string;\n  relativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;\n  list(items: Iterable<string>, options?: Intl.ListFormatOptions): string;\n  plural(value: number, options?: Intl.PluralRulesOptions): Intl.LDMLPluralRule;\n}\n\n/** Builds locale-bound formatters (pure — the testable core of `useLocaleFormatters`). */\nexport function createLocaleFormatters(locale: string): LocaleFormatters {\n  const nf = (options?: Intl.NumberFormatOptions) =>\n    memo(`n|${locale}|${optKey(options)}`, () => new Intl.NumberFormat(locale, options));\n  const dtf = (options?: Intl.DateTimeFormatOptions) =>\n    memo(`d|${locale}|${optKey(options)}`, () => new Intl.DateTimeFormat(locale, options));\n  return {\n    locale,\n    number: (value, options) => nf(options).format(value),\n    currency: (value, currency, options) => nf({ ...options, style: 'currency', currency }).format(value),\n    percent: (value, options) => nf({ ...options, style: 'percent' }).format(value),\n    date: (value, options) => dtf(options ?? { dateStyle: 'medium' }).format(value),\n    time: (value, options) => dtf(options ?? { timeStyle: 'short' }).format(value),\n    relativeTime: (value, unit, options) =>\n      memo(`r|${locale}|${optKey(options)}`, () => new Intl.RelativeTimeFormat(locale, options)).format(value, unit),\n    list: (items, options) =>\n      memo(`l|${locale}|${optKey(options)}`, () => new Intl.ListFormat(locale, options)).format(items),\n    plural: (value, options) =>\n      memo(`p|${locale}|${optKey(options)}`, () => new Intl.PluralRules(locale, options)).select(value),\n  };\n}\n\n/**\n * Returns locale-bound `Intl` formatters — `number`/`currency`/`percent`/`date`/`time`/`relativeTime`/`list`/\n * `plural` — recomputed only when the active locale changes.\n *\n * A `ComputedRef` rather than a plain object: the locale is reactive, so the formatter set bound to it has to\n * be too. Read it as `formatters.value.number(1234)`.\n */\nexport function useLocaleFormatters(): ComputedRef<LocaleFormatters> {\n  const { locale } = useLocale();\n  return computed(() => createLocaleFormatters(locale.value));\n}\n","<script lang=\"ts\">\nimport type { Messages } from './LocaleContext';\n\n/** Props for `LocaleProvider`. */\nexport interface LocaleProviderProps {\n  /** BCP-47 locale. Defaults to `navigator.language`, then `en-US`. */\n  locale?: string;\n  /** Consumer message overrides — a dictionary or a `(key, vars) => string` callback. */\n  messages?: Messages;\n}\n</script>\n\n<script setup lang=\"ts\">\nimport { provideLocale } from './LocaleContext';\n\n/**\n * Provides the active locale + message overrides to every descendant SDK component.\n *\n * Renders no element of its own — the slot passes straight through.\n */\ndefineOptions({ name: 'LocaleProvider' });\n\nconst props = defineProps<LocaleProviderProps>();\n\nprovideLocale(\n  () => props.locale,\n  () => props.messages,\n);\n</script>\n\n<template>\n  <slot />\n</template>\n","<script lang=\"ts\">\n/** Props for `FormattedRelative`. */\nexport interface FormattedRelativeProps {\n  /** Signed magnitude — negative = past (`-3` → \"3 days ago\"), positive = future. */\n  value: number;\n  unit: Intl.RelativeTimeFormatUnit;\n  options?: Intl.RelativeTimeFormatOptions;\n}\n</script>\n\n<script setup lang=\"ts\">\nimport { computed } from 'vue';\n\nimport { useLocaleFormatters } from './LocaleFormatters';\n\n/** Renders a locale-formatted relative time (e.g. \"3 days ago\") via `Intl.RelativeTimeFormat`. */\ndefineOptions({ name: 'FormattedRelative' });\n\nconst props = defineProps<FormattedRelativeProps>();\n\nconst formatters = useLocaleFormatters();\nconst text = computed(() => formatters.value.relativeTime(props.value, props.unit, props.options));\n</script>\n\n<template>{{ text }}</template>\n"],"names":["_renderSlot"],"mappings":";;;AAMA,MAAM,gCAAgB,IAAA;AACtB,SAAS,KAAQ,UAAkB,MAAkB;AACnD,MAAI,WAAW,UAAU,IAAI,QAAQ;AACrC,MAAI,aAAa,QAAW;AAC1B,eAAW,KAAA;AACX,cAAU,IAAI,UAAU,QAAQ;AAAA,EAClC;AACA,SAAO;AACT;AACA,MAAM,SAAS,CAAC,YAAyC,UAAU,KAAK,UAAU,OAAO,IAAI;AAiBtF,SAAS,uBAAuB,QAAkC;AACvE,QAAM,KAAK,CAAC,YACV,KAAK,KAAK,MAAM,IAAI,OAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,aAAa,QAAQ,OAAO,CAAC;AACrF,QAAM,MAAM,CAAC,YACX,KAAK,KAAK,MAAM,IAAI,OAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,eAAe,QAAQ,OAAO,CAAC;AACvF,SAAO;AAAA,IACL;AAAA,IACA,QAAQ,CAAC,OAAO,YAAY,GAAG,OAAO,EAAE,OAAO,KAAK;AAAA,IACpD,UAAU,CAAC,OAAO,UAAU,YAAY,GAAG,EAAE,GAAG,SAAS,OAAO,YAAY,SAAA,CAAU,EAAE,OAAO,KAAK;AAAA,IACpG,SAAS,CAAC,OAAO,YAAY,GAAG,EAAE,GAAG,SAAS,OAAO,UAAA,CAAW,EAAE,OAAO,KAAK;AAAA,IAC9E,MAAM,CAAC,OAAO,YAAY,IAAI,WAAW,EAAE,WAAW,SAAA,CAAU,EAAE,OAAO,KAAK;AAAA,IAC9E,MAAM,CAAC,OAAO,YAAY,IAAI,WAAW,EAAE,WAAW,QAAA,CAAS,EAAE,OAAO,KAAK;AAAA,IAC7E,cAAc,CAAC,OAAO,MAAM,YAC1B,KAAK,KAAK,MAAM,IAAI,OAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,mBAAmB,QAAQ,OAAO,CAAC,EAAE,OAAO,OAAO,IAAI;AAAA,IAC/G,MAAM,CAAC,OAAO,YACZ,KAAK,KAAK,MAAM,IAAI,OAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,WAAW,QAAQ,OAAO,CAAC,EAAE,OAAO,KAAK;AAAA,IACjG,QAAQ,CAAC,OAAO,YACd,KAAK,KAAK,MAAM,IAAI,OAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,YAAY,QAAQ,OAAO,CAAC,EAAE,OAAO,KAAK;AAAA,EAAA;AAEtG;AASO,SAAS,sBAAqD;AACnE,QAAM,EAAE,OAAA,IAAW,UAAA;AACnB,SAAO,SAAS,MAAM,uBAAuB,OAAO,KAAK,CAAC;AAC5D;;;;;;;;;ACzCA,UAAM,QAAQ;AAEd;AAAA,MACE,MAAM,MAAM;AAAA,MACZ,MAAM,MAAM;AAAA,IAAA;;aAKZA,WAAQ,KAAA,QAAA,SAAA;AAAA;;;;;;;;;;;;ACbV,UAAM,QAAQ;AAEd,UAAM,aAAa,oBAAA;AACnB,UAAM,OAAO,SAAS,MAAM,WAAW,MAAM,aAAa,MAAM,OAAO,MAAM,MAAM,MAAM,OAAO,CAAC;;6BAGpF,KAAA,KAAI;AAAA;;;"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/i18n/LocaleFormatters.ts","../../../src/foundation/i18n/providers/LocaleProvider.vue","../../../src/foundation/i18n/formattedRelative/FormattedRelative.vue"],"sourcesContent":["import { computed, type ComputedRef } from 'vue';\n\nimport { useLocale } from './providers/LocaleContext';\n\nimport { intlOptionsKey as optKey, memoIntl as memo } from './IntlCache';\n\n/** Locale-bound `Intl` formatters — the surface every embedded-text component formats through. */\nexport interface LocaleFormatters {\n  /** The BCP-47 locale these formatters are bound to. */\n  locale: string;\n  number(value: number, options?: Intl.NumberFormatOptions): string;\n  currency(value: number, currency: string, options?: Intl.NumberFormatOptions): string;\n  percent(value: number, options?: Intl.NumberFormatOptions): string;\n  date(value: Date | number, options?: Intl.DateTimeFormatOptions): string;\n  time(value: Date | number, options?: Intl.DateTimeFormatOptions): string;\n  relativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;\n  list(items: Iterable<string>, options?: Intl.ListFormatOptions): string;\n  plural(value: number, options?: Intl.PluralRulesOptions): Intl.LDMLPluralRule;\n}\n\n/** Builds locale-bound formatters (pure — the testable core of `useLocaleFormatters`). */\nexport function createLocaleFormatters(locale: string): LocaleFormatters {\n  const nf = (options?: Intl.NumberFormatOptions) =>\n    memo(`n|${locale}|${optKey(options)}`, () => new Intl.NumberFormat(locale, options));\n  const dtf = (options?: Intl.DateTimeFormatOptions) =>\n    memo(`d|${locale}|${optKey(options)}`, () => new Intl.DateTimeFormat(locale, options));\n  return {\n    locale,\n    number: (value, options) => nf(options).format(value),\n    currency: (value, currency, options) => nf({ ...options, style: 'currency', currency }).format(value),\n    percent: (value, options) => nf({ ...options, style: 'percent' }).format(value),\n    date: (value, options) => dtf(options ?? { dateStyle: 'medium' }).format(value),\n    time: (value, options) => dtf(options ?? { timeStyle: 'short' }).format(value),\n    relativeTime: (value, unit, options) =>\n      memo(`r|${locale}|${optKey(options)}`, () => new Intl.RelativeTimeFormat(locale, options)).format(value, unit),\n    list: (items, options) =>\n      memo(`l|${locale}|${optKey(options)}`, () => new Intl.ListFormat(locale, options)).format(items),\n    plural: (value, options) =>\n      memo(`p|${locale}|${optKey(options)}`, () => new Intl.PluralRules(locale, options)).select(value),\n  };\n}\n\n/**\n * Returns locale-bound `Intl` formatters — `number`/`currency`/`percent`/`date`/`time`/`relativeTime`/`list`/\n * `plural` — recomputed only when the active locale changes.\n *\n * A `ComputedRef` rather than a plain object: the locale is reactive, so the formatter set bound to it has to\n * be too. Read it as `formatters.value.number(1234)`.\n */\nexport function useLocaleFormatters(): ComputedRef<LocaleFormatters> {\n  const { locale } = useLocale();\n  return computed(() => createLocaleFormatters(locale.value));\n}\n","<script lang=\"ts\">\nimport type { Messages } from './LocaleContext';\n\n/** Props for `LocaleProvider`. */\nexport interface LocaleProviderProps {\n  /** BCP-47 locale. Defaults to `en-US` on both server and client. */\n  readonly locale?: string;\n  /** Consumer message overrides — a dictionary or a `(key, vars) => string` callback. */\n  readonly messages?: Messages;\n}\n</script>\n\n<script setup lang=\"ts\">\nimport { toRef } from 'vue';\nimport { provideLocale } from './LocaleContext';\n\n/**\n * Renders no element of its own — the slot passes straight through — while providing the active locale and its\n * message overrides to every descendant SDK component.\n */\ndefineOptions({ name: 'LocaleProvider' });\n\nconst props = defineProps<LocaleProviderProps>();\n\ndefineSlots<{\n  /** The subtree that reads the provided locale and messages. */\n  default(): unknown;\n}>();\n\nprovideLocale(() => props.locale, toRef(props, 'messages'));\n</script>\n\n<template>\n  <slot />\n</template>\n","<script lang=\"ts\">\n/** Props for `FormattedRelative`. */\nexport interface FormattedRelativeProps {\n  /** Signed magnitude — negative = past (`-3` → \"3 days ago\"), positive = future. */\n  readonly value: number;\n  readonly unit: Intl.RelativeTimeFormatUnit;\n  readonly options?: Intl.RelativeTimeFormatOptions;\n}\n</script>\n\n<script setup lang=\"ts\">\nimport { computed } from 'vue';\n\nimport { useLocaleFormatters } from '../LocaleFormatters';\n\n/** Renders a locale-formatted relative time (e.g. \"3 days ago\") via `Intl.RelativeTimeFormat`. */\ndefineOptions({ name: 'FormattedRelative' });\n\nconst props = defineProps<FormattedRelativeProps>();\n\nconst formatters = useLocaleFormatters();\nconst text = computed(() => formatters.value.relativeTime(props.value, props.unit, props.options));\n</script>\n\n<template>{{ text }}</template>\n"],"names":["memo","optKey","_renderSlot"],"mappings":";;;;;AAqBO,SAAS,uBAAuB,QAAkC;AACvE,QAAM,KAAK,CAAC,YACVA,SAAK,KAAK,MAAM,IAAIC,eAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,aAAa,QAAQ,OAAO,CAAC;AACrF,QAAM,MAAM,CAAC,YACXD,SAAK,KAAK,MAAM,IAAIC,eAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,eAAe,QAAQ,OAAO,CAAC;AACvF,SAAO;AAAA,IACL;AAAA,IACA,QAAQ,CAAC,OAAO,YAAY,GAAG,OAAO,EAAE,OAAO,KAAK;AAAA,IACpD,UAAU,CAAC,OAAO,UAAU,YAAY,GAAG,EAAE,GAAG,SAAS,OAAO,YAAY,SAAA,CAAU,EAAE,OAAO,KAAK;AAAA,IACpG,SAAS,CAAC,OAAO,YAAY,GAAG,EAAE,GAAG,SAAS,OAAO,UAAA,CAAW,EAAE,OAAO,KAAK;AAAA,IAC9E,MAAM,CAAC,OAAO,YAAY,IAAI,WAAW,EAAE,WAAW,SAAA,CAAU,EAAE,OAAO,KAAK;AAAA,IAC9E,MAAM,CAAC,OAAO,YAAY,IAAI,WAAW,EAAE,WAAW,QAAA,CAAS,EAAE,OAAO,KAAK;AAAA,IAC7E,cAAc,CAAC,OAAO,MAAM,YAC1BD,SAAK,KAAK,MAAM,IAAIC,eAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,mBAAmB,QAAQ,OAAO,CAAC,EAAE,OAAO,OAAO,IAAI;AAAA,IAC/G,MAAM,CAAC,OAAO,YACZD,SAAK,KAAK,MAAM,IAAIC,eAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,WAAW,QAAQ,OAAO,CAAC,EAAE,OAAO,KAAK;AAAA,IACjG,QAAQ,CAAC,OAAO,YACdD,SAAK,KAAK,MAAM,IAAIC,eAAO,OAAO,CAAC,IAAI,MAAM,IAAI,KAAK,YAAY,QAAQ,OAAO,CAAC,EAAE,OAAO,KAAK;AAAA,EAAA;AAEtG;AASO,SAAS,sBAAqD;AACnE,QAAM,EAAE,OAAA,IAAW,UAAA;AACnB,SAAO,SAAS,MAAM,uBAAuB,OAAO,KAAK,CAAC;AAC5D;;;;;;;;;AC9BA,UAAM,QAAQ;AAOd,kBAAc,MAAM,MAAM,QAAQ,MAAM,OAAO,UAAU,CAAC;;aAIxDC,WAAQ,KAAA,QAAA,SAAA;AAAA;;;;;;;;;;;;ACfV,UAAM,QAAQ;AAEd,UAAM,aAAa,oBAAA;AACnB,UAAM,OAAO,SAAS,MAAM,WAAW,MAAM,aAAa,MAAM,OAAO,MAAM,MAAM,MAAM,OAAO,CAAC;;6BAGpF,KAAA,KAAI;AAAA;;;"}

package/dist/foundation/i18n/providers/LocaleContext.d.ts

@@ -0,0 +1,35 @@
+import { ComputedRef, InjectionKey, MaybeRef, MaybeRefOrGetter } from 'vue';
+/** Interpolation variables for a message template (`Hello {name}` + `{ name: 'Sam' }`). */
+export type MessageVars = Record<string, string | number>;
+/** A message resolver — a `key → template` dictionary, or a `(key, vars) => string` callback (bring-your-own ICU). */
+export type Messages = Record<string, string> | ((key: string, vars?: MessageVars) => string);
+/** Replaces `{token}` placeholders from `vars`; leaves unknown tokens untouched. */
+export declare function interpolate(template: string, vars?: MessageVars): string;
+/** Resolves a message: consumer `messages` override (dict or callback) → SDK-authored `fallback` → the raw key. */
+export declare function resolveMessage(messages: Messages | undefined, key: string, vars?: MessageVars, fallback?: string): string;
+/**
+ * The active locale + message resolver exposed by `useLocale`.
+ *
+ * `locale` is a `ComputedRef` rather than a bare string — Vue's `provide` is not reactive on its own, and a
+ * consumer switching locales must re-evaluate every descendant. `t` stays a plain function: it reads the
+ * provider's messages at CALL time, so invoking it inside a `computed` tracks a message-table swap without
+ * `t` itself ever changing identity.
+ */
+export interface LocaleContextValue {
+    /** The active BCP-47 locale (e.g. `en-US`, `de`). */
+    locale: ComputedRef<string>;
+    /** Resolves a message key — consumer override, else the SDK-authored `fallback`, else the key. */
+    t: (key: string, vars?: MessageVars, fallback?: string) => string;
+}
+/** Identifies the locale owned by the nearest provider. */
+export declare const LocaleKey: InjectionKey<LocaleContextValue>;
+/**
+ * The provider half — used by `LocaleProvider`, and by any component that owns a locale.
+ *
+ * The deterministic fallback matches server and initial client rendering. Applications can pass the same
+ * request locale to both, or explicitly switch to browser preferences after hydration.
+ * Message callbacks are values; wrap a reactive message source in a ref or computed.
+ */
+export declare function provideLocale(locale?: MaybeRefOrGetter<string | undefined>, messages?: MaybeRef<Messages | undefined>): LocaleContextValue;
+/** Reads the active locale + `t`. Works without a provider — defaults to `en-US` + fallback-only messages. */
+export declare function useLocale(): LocaleContextValue;