okengine 0.20.0 → 0.21.1

package/src/client/explain.ts

@@ -0,0 +1,272 @@
+/**
+ * Collapse unknown flow / transport errors into a small UX kind.
+ *
+ * Import from `okengine/client/explain` (kept off the 5 kB `okengine/client`
+ * edge graph). Prefer {@link match} on the envelope. Name a code when this
+ * screen has special recovery (`FlightFull` → waitlist). Kind arms handle
+ * chrome (`auth` → sign-in). {@link matchError} / {@link match} require `_`
+ * so that dump bucket is never optional.
+ */
+
+/** UX family for toasts, sign-in, forms — not an HTTP status. */
+export type ErrorKind =
+  | "auth"
+  | "permission"
+  | "missing"
+  | "conflict"
+  | "invalid"
+  | "limited"
+  | "unavailable"
+  | "failed";
+
+const ERROR_KINDS: readonly ErrorKind[] = [
+  "auth",
+  "permission",
+  "missing",
+  "conflict",
+  "invalid",
+  "limited",
+  "unavailable",
+  "failed",
+];
+
+const KIND_SET: ReadonlySet<string> = new Set(ERROR_KINDS);
+
+/** Display-ready failure from {@link explain}. */
+export interface ExplainedError {
+  readonly kind: ErrorKind;
+  readonly code: string;
+  /** Envelope message, transport message, or `code` — never empty. */
+  readonly message: string;
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number;
+  /** `ValidationError` path → message (`.`-joined; empty path is `_`). */
+  readonly fields?: Record<string, string>;
+}
+
+/** Input accepted by {@link explain} (flow error or transport). */
+export type ExplainableError = {
+  readonly code: string;
+  readonly data?: unknown;
+  readonly message?: string;
+};
+
+/**
+ * Envelope `{ data, error }` accepted by {@link match}.
+ *
+ * @typeParam O - Success data
+ * @typeParam Err - Failure (flow error or transport)
+ */
+export type MatchableResult<O, Err extends ExplainableError = ExplainableError> =
+  | { readonly data: O; readonly error: null }
+  | { readonly data: null; readonly error: Err };
+
+/**
+ * Cases for {@link matchError}: named codes, optional UX kinds, required `_`.
+ *
+ * Code arms receive typed `data`. Kind arms and `_` receive {@link ExplainedError}.
+ * Dispatch order: named code → kind → `_`. Kind names (`auth`, `failed`, …) are
+ * reserved — they are never treated as domain codes.
+ *
+ * @typeParam Err - Envelope error
+ * @typeParam R - Handler return
+ */
+export type MatchErrorCases<Err extends ExplainableError, R> = {
+  [K in Exclude<Err["code"], ErrorKind | "_">]?: (
+    data: Extract<Err, { readonly code: K }> extends { readonly data: infer D } ? D : unknown,
+  ) => R;
+} & {
+  [K in ErrorKind]?: (explained: ExplainedError & { readonly kind: K }) => R;
+} & {
+  /** Required dump bucket — unknown / unhandled codes and kinds. */
+  readonly _: (explained: ExplainedError) => R;
+};
+
+/**
+ * Cases for {@link match}: required `ok` plus {@link MatchErrorCases}.
+ *
+ * @typeParam O - Success data
+ * @typeParam Err - Envelope error
+ * @typeParam R - Handler return
+ */
+export type MatchResultCases<O, Err extends ExplainableError, R> = {
+  readonly ok: (data: O) => R;
+} & MatchErrorCases<Err, R>;
+
+const KIND: Record<string, ErrorKind> = {
+  Unauthorized: "auth",
+  AuthFailed: "auth",
+  Forbidden: "permission",
+  NotFound: "missing",
+  Conflict: "conflict",
+  ForeignKey: "conflict",
+  ValidationError: "invalid",
+  InvalidQuery: "invalid",
+  UnsupportedMediaType: "invalid",
+  RateLimited: "limited",
+  AuthRateLimited: "limited",
+  ServiceUnavailable: "unavailable",
+  InternalError: "failed",
+};
+
+const INVALID_DB = new Set(["not_null", "check", "invalid", "too_long", "out_of_range"]);
+
+/**
+ * Collapse a flow or transport error into chrome (`kind`, `message`, `fields`).
+ *
+ * Domain codes (`OutOfStock`, `FlightFull`) are `failed` — product UX stays
+ * on `error.code`. Does not throw.
+ *
+ * @param error - Envelope `error` from a {@link MatchableResult}
+ */
+export function explain(error: ExplainableError): ExplainedError {
+  const kind = kindOf(error);
+  const retryable = kind === "unavailable" || kind === "limited";
+  const retryAfterMs = retryable ? retryDelay(error.data) : undefined;
+  const fields = error.code === "ValidationError" ? fieldsOf(error.data) : undefined;
+  return {
+    kind,
+    code: error.code,
+    message: messageOf(error),
+    retryable,
+    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    ...(fields !== undefined ? { fields } : {}),
+  };
+}
+
+/**
+ * Run a named code handler, a UX {@link ErrorKind} arm, or `_`.
+ *
+ * `_` is required so store auto-map, transport, and domain codes always have
+ * a path. Named arms narrow `data` (e.g. `FlightFull` → `seatsLeft`). Kind
+ * arms receive {@link ExplainedError} (`auth` → sign-in, `invalid` → fields).
+ *
+ * @param error - Envelope error
+ * @param cases - Optional per-code / per-kind handlers plus required `_`
+ */
+export function matchError<Err extends ExplainableError, R>(
+  error: Err,
+  cases: MatchErrorCases<Err, R>,
+): R {
+  const code = error.code;
+  const codeFn = lookupCode<R>(cases, code);
+  if (codeFn !== undefined) return codeFn(error.data);
+  const explained = explain(error);
+  const kindFn = lookupKind<R>(cases, explained.kind);
+  if (kindFn !== undefined) return kindFn(explained);
+  return cases._(explained);
+}
+
+/**
+ * Run `ok` on success, otherwise the same arms as {@link matchError}.
+ *
+ * One import, one call — no `isOk` then `matchError` split.
+ *
+ * @param result - Envelope `{ data, error }`
+ * @param cases - Required `ok`, optional per-code / per-kind, required `_`
+ */
+export function match<T extends MatchableResult<unknown, ExplainableError>, R>(
+  result: T,
+  cases: MatchResultCases<MatchData<T>, MatchErr<T>, R>,
+): R {
+  if (result.error === null) return cases.ok(result.data as MatchData<T>);
+  return matchError(result.error as MatchErr<T>, cases);
+}
+
+/** Success `data` from a {@link MatchableResult} union (null-error branch only). */
+type MatchData<T> = T extends { readonly error: null; readonly data: infer O } ? O : never;
+
+/** Failure from a {@link MatchableResult} union (`error` excluding `null`). */
+type MatchErr<T> = T extends { readonly error: infer E }
+  ? E extends null
+    ? never
+    : E extends ExplainableError
+      ? E
+      : never
+  : never;
+
+function lookupCode<R>(cases: object, code: string): ((data: unknown) => R) | undefined {
+  if (code === "_" || code === "ok" || KIND_SET.has(code)) return undefined;
+  const handler = (cases as Record<string, unknown>)[code];
+  return typeof handler === "function" ? (handler as (data: unknown) => R) : undefined;
+}
+
+function lookupKind<R>(
+  cases: object,
+  kind: ErrorKind,
+): ((explained: ExplainedError) => R) | undefined {
+  const handler = (cases as Record<string, unknown>)[kind];
+  return typeof handler === "function" ? (handler as (explained: ExplainedError) => R) : undefined;
+}
+
+function kindOf(error: ExplainableError): ErrorKind {
+  if (error.code === "TransportError") {
+    return transportStatus(error.data) === 404 ? "missing" : "unavailable";
+  }
+  if (error.code === "DatabaseError") {
+    const reason = dataReason(error.data);
+    if (reason === "retryable") return "unavailable";
+    if (reason !== undefined && INVALID_DB.has(reason)) return "invalid";
+    return "failed";
+  }
+  return KIND[error.code] ?? "failed";
+}
+
+function messageOf(error: ExplainableError): string {
+  if (typeof error.message === "string" && error.message.length > 0) return error.message;
+  const data = error.data;
+  if (
+    error.code === "TransportError" &&
+    data !== null &&
+    typeof data === "object" &&
+    "message" in data &&
+    typeof (data as { message: unknown }).message === "string" &&
+    (data as { message: string }).message.length > 0
+  ) {
+    return (data as { message: string }).message;
+  }
+  return error.code;
+}
+
+function retryDelay(data: unknown): number | undefined {
+  if (data === null || typeof data !== "object") return undefined;
+  const rec = data as { retryAfterMs?: unknown; retryAfter?: unknown };
+  if (typeof rec.retryAfterMs === "number") return rec.retryAfterMs;
+  if (typeof rec.retryAfter === "number") return rec.retryAfter * 1000;
+  return undefined;
+}
+
+function fieldsOf(data: unknown): Record<string, string> | undefined {
+  if (data === null || typeof data !== "object" || !("issues" in data)) return undefined;
+  const issues = (data as { issues: unknown }).issues;
+  if (!Array.isArray(issues) || issues.length === 0) return undefined;
+  const fields: Record<string, string> = {};
+  for (const issue of issues) {
+    if (issue === null || typeof issue !== "object") continue;
+    const rec = issue as { message?: unknown; path?: unknown };
+    if (typeof rec.message !== "string") continue;
+    fields[pathKey(rec.path)] = rec.message;
+  }
+  return Object.keys(fields).length > 0 ? fields : undefined;
+}
+
+function pathKey(path: unknown): string {
+  if (!Array.isArray(path) || path.length === 0) return "_";
+  const parts: string[] = [];
+  for (const p of path) {
+    if (typeof p === "string" || typeof p === "number") parts.push(String(p));
+  }
+  return parts.length > 0 ? parts.join(".") : "_";
+}
+
+function transportStatus(data: unknown): number | undefined {
+  if (data === null || typeof data !== "object" || !("status" in data)) return undefined;
+  const status = (data as { status: unknown }).status;
+  return typeof status === "number" ? status : undefined;
+}
+
+function dataReason(data: unknown): string | undefined {
+  if (data === null || typeof data !== "object" || !("reason" in data)) return undefined;
+  const reason = (data as { reason: unknown }).reason;
+  return typeof reason === "string" ? reason : undefined;
+}

package/src/client/live.test.ts

@@ -413,6 +413,50 @@ describe("createClient — live", () => {
   });
 });
 
+describe("sseError — envelope message fallback", () => {
+  test("prefers top-level error.message", async () => {
+    const { sseError } = await import("./sse.ts");
+    const err = sseError(
+      401,
+      JSON.stringify({
+        data: null,
+        error: { code: "Unauthorized", message: "Auth required", data: {} },
+      }),
+    );
+    expect(err.message).toBe("Auth required");
+  });
+
+  test("falls back to error.data.message", async () => {
+    const { sseError } = await import("./sse.ts");
+    const err = sseError(
+      401,
+      JSON.stringify({
+        data: null,
+        error: { code: "Unauthorized", data: { message: "Auth required" } },
+      }),
+    );
+    expect(err.message).toBe("Auth required");
+  });
+
+  test("falls back to error.code", async () => {
+    const { sseError } = await import("./sse.ts");
+    const err = sseError(
+      401,
+      JSON.stringify({
+        data: null,
+        error: { code: "Unauthorized" },
+      }),
+    );
+    expect(err.message).toBe("Unauthorized");
+  });
+
+  test("falls back to HTTP status for plain body", async () => {
+    const { sseError } = await import("./sse.ts");
+    const err = sseError(401, "nope");
+    expect(err.message).toBe("nope");
+  });
+});
+
 async function waitFor(pred: () => boolean, ms = 500): Promise<void> {
   const start = Date.now();
   while (!pred()) {

package/src/client/live.ts

@@ -4,7 +4,16 @@
 
 import type { ClientFetch, ClientOptions, ClientRouteMap, FlowContract } from "./types.ts";
 import type { LiveHandlers, LiveUnsubscribe } from "./types.ts";
-import { readSse, sseError } from "./sse.ts";
+import { iterateSseFrames, sseError } from "./sse.ts";
+import {
+  applyAuthHeader,
+  applyHeaderBag,
+  interpolatePath,
+  methodAndPath,
+  resolveHeaders,
+  toQuery,
+  walkContracts,
+} from "./wire.ts";
 
 /** One HTTP exposure of a live signal. */
 export interface LiveExposure {
@@ -31,24 +40,16 @@ export function flattenLiveRoutes($routes: ClientRouteMap | undefined): {
 } {
   const bySignal: Record<string, LiveExposure[]> = {};
   const byFlow: Record<string, LiveExposure> = {};
-  if (!$routes) return { bySignal, byFlow };
-  for (const [unit, flows] of Object.entries($routes)) {
-    if (!flows || typeof flows !== "object") continue;
-    for (const [flow, contract] of Object.entries(flows)) {
-      if (!contract || typeof contract !== "object") continue;
-      const live = liveName(contract);
-      const method = "method" in contract ? contract.method : undefined;
-      const path = "path" in contract ? contract.path : undefined;
-      if (typeof live !== "string" || typeof method !== "string" || typeof path !== "string") {
-        continue;
-      }
-      const matchKey = matchKeyOf(contract);
-      const id = `${unit}.${flow}`;
-      const exposure: LiveExposure = { flow: id, method, path, matchKey };
-      (bySignal[live] ??= []).push(exposure);
-      byFlow[id] = exposure;
-    }
-  }
+  walkContracts($routes, (unit, flow, contract) => {
+    const live = liveName(contract);
+    const route = methodAndPath(contract);
+    if (typeof live !== "string" || !route) return;
+    const matchKey = matchKeyOf(contract);
+    const id = `${unit}.${flow}`;
+    const exposure: LiveExposure = { flow: id, method: route.method, path: route.path, matchKey };
+    (bySignal[live] ??= []).push(exposure);
+    byFlow[id] = exposure;
+  });
   return { bySignal, byFlow };
 }
 
@@ -87,11 +88,7 @@ export function pickLiveExposure(
 ): LiveExposure {
   if (via) {
     const hit = exposures.find((e) => e.flow === via);
-    if (!hit) {
-      throw new Error(
-        `Unknown live via "${via}". Known: ${exposures.map((e) => e.flow).join(", ")}`,
-      );
-    }
+    if (!hit) throw new Error(`Unknown live via "${via}"`);
     return hit;
   }
   const keys =
@@ -100,19 +97,12 @@ export function pickLiveExposure(
       : [];
   const candidates = exposures.filter((e) => e.matchKey.every((k) => keys.includes(k)));
   if (candidates.length === 0) {
-    throw new Error(
-      `No live exposure matches input keys [${keys.join(", ")}]. Flows: ${exposures.map((e) => e.flow).join(", ")}`,
-    );
-  }
-  let max = -1;
-  for (const e of candidates) {
-    if (e.matchKey.length > max) max = e.matchKey.length;
+    throw new Error(`No live exposure matches input keys [${keys.join(", ")}]`);
   }
+  const max = Math.max(...candidates.map((e) => e.matchKey.length));
   const top = candidates.filter((e) => e.matchKey.length === max);
   if (top.length !== 1) {
-    throw new Error(
-      `Multiple live exposures match: ${top.map((e) => e.flow).join(", ")}. Pass via: "unit.flow".`,
-    );
+    throw new Error(`Multiple live exposures match. Pass via: "unit.flow".`);
   }
   return top[0]!;
 }
@@ -173,6 +163,11 @@ async function pump(
   let delayMs = LIVE_RESUBSCRIBE_INITIAL_MS;
   let attempt = 0;
   let lastSeenId: string | undefined;
+  /** Report `err`. Returns whether the loop should resubscribe. */
+  const note = (err: unknown): boolean => {
+    handlers.onError?.(err);
+    return auto;
+  };
   for (;;) {
     if (signal.aborted) return;
     if (attempt > 0 && auto) {
@@ -182,45 +177,26 @@ async function pump(
     }
     attempt += 1;
     try {
-      const res = await openSse(base, exposure, input, opts, signal, lastSeenId);
+      let res = await openSse(base, exposure, input, opts, signal, lastSeenId);
       if (signal.aborted) return;
       if (res.status === 401 && opts.auth?.refresh) {
         await opts.auth.refresh();
-        const retry = await openSse(base, exposure, input, opts, signal, lastSeenId);
-        if (signal.aborted) return;
-        lastSeenId = await consumeSse(retry, handlers, signal, lastSeenId);
+        res = await openSse(base, exposure, input, opts, signal, lastSeenId);
         if (signal.aborted) return;
-        const closed = new Error("live connection closed");
-        if (auto) {
-          handlers.onError?.(closed);
-          continue;
-        }
-        handlers.onError?.(closed);
-        return;
       }
       if (res.status === 410) {
-        const err = await liveResumeGapError(res);
         lastSeenId = undefined;
-        handlers.onError?.(err);
-        if (!auto) return;
-        continue;
+        const text = await res.text().catch(() => "");
+        if (note(sseError(410, text))) continue;
+        return;
       }
       lastSeenId = await consumeSse(res, handlers, signal, lastSeenId);
       if (signal.aborted) return;
-      const closed = new Error("live connection closed");
-      if (auto) {
-        handlers.onError?.(closed);
-        continue;
-      }
-      handlers.onError?.(closed);
+      if (note(new Error("live connection closed"))) continue;
       return;
     } catch (err) {
       if (signal.aborted) return;
-      if (auto) {
-        handlers.onError?.(err);
-        continue;
-      }
-      handlers.onError?.(err);
+      if (note(err)) continue;
       return;
     }
   }
@@ -233,23 +209,13 @@ async function consumeSse(
   lastSeenId: string | undefined,
 ): Promise<string | undefined> {
   let cursor = lastSeenId;
-  await readSse(
-    res,
-    (event, id) => {
-      handlers.onEvent(event);
-      if (id !== undefined && id.length > 0) cursor = id;
-    },
-    signal,
-    handlers.onOpen,
-  );
+  for await (const frame of iterateSseFrames(res, signal, handlers.onOpen)) {
+    handlers.onEvent(frame.event);
+    if (frame.id !== undefined && frame.id.length > 0) cursor = frame.id;
+  }
   return cursor;
 }
 
-async function liveResumeGapError(res: Response): Promise<Error> {
-  const text = await res.text().catch(() => "");
-  return sseError(410, text);
-}
-
 /**
  * Abortable delay. Resolves immediately when `signal` is already aborted.
  *
@@ -280,19 +246,8 @@ async function openSse(
 ): Promise<Response> {
   const { url, method } = restGet(base, exposure.path, input);
   const headers = new Headers({ accept: "text/event-stream" });
-  const extra = typeof opts.headers === "function" ? await opts.headers() : opts.headers;
-  if (Array.isArray(extra)) {
-    for (const [k, v] of extra) headers.set(k, v);
-  } else if (extra) {
-    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
-  }
-  const token =
-    opts.auth && "getToken" in opts.auth && typeof opts.auth.getToken === "function"
-      ? await opts.auth.getToken()
-      : undefined;
-  if (token && !headers.has("authorization")) {
-    headers.set("authorization", `Bearer ${token}`);
-  }
+  applyHeaderBag(headers, await resolveHeaders(opts));
+  await applyAuthHeader(headers, opts);
   if (lastSeenId) headers.set("last-event-id", lastSeenId);
   const fetchFn: ClientFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
   return fetchFn(url, {
@@ -304,18 +259,6 @@ async function openSse(
 }
 
 function restGet(base: string, path: string, input: unknown): { url: string; method: string } {
-  const params =
-    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
-  let pathOut = path;
-  const query: string[] = [];
-  for (const [k, v] of Object.entries(params)) {
-    const token = `:${k}`;
-    if (pathOut.includes(token)) {
-      pathOut = pathOut.replaceAll(token, encodeURIComponent(String(v)));
-    } else if (v !== undefined) {
-      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
-    }
-  }
-  const qs = query.length ? `?${query.join("&")}` : "";
-  return { url: `${base}${pathOut}${qs}`, method: "GET" };
+  const { path: pathOut, rest } = interpolatePath(path, input);
+  return { url: `${base}${pathOut}${toQuery(rest)}`, method: "GET" };
 }

package/src/client/notes-contract.test.ts

@@ -76,6 +76,16 @@ describe("Notes — typeof app carries contracts", () => {
     expect(typeof api.notes.create).toBe("function");
   });
 
+  test("create without errors: bag still types built-in NotFound", () => {
+    const app = oke({ name: "notes" }).adopt({ notes: { create } });
+    const api = createClient<typeof app>("http://localhost:6530");
+    type CreateError = NonNullable<Awaited<ReturnType<typeof api.notes.create>>["error"]>;
+    type NotFoundData = Extract<CreateError, { code: "NotFound" }>["data"];
+    type _Id = Assert<Eq<NotFoundData["id"], string | undefined>>;
+    const ok: [_Id] = [true];
+    expect(ok).toEqual([true]);
+  });
+
   test("Notes client block: createClient<App> narrows data and NotFound", async () => {
     const app = oke({ name: "notes" }).adopt({ notes });
     type App = typeof app;