okengine 0.20.0 → 0.21.1

package/src/client/sse.ts

@@ -4,33 +4,30 @@
  * @module
  */
 
-/** Callback for one parsed SSE data frame. */
-export type SseFrameHandler = (event: unknown, id: string | undefined) => void;
+/** One parsed SSE data frame. */
+export interface ParsedSseFrame {
+  readonly event: unknown;
+  readonly id: string | undefined;
+}
 
 /**
- * Read an SSE response body until `[DONE]`, abort, or EOF.
+ * Shared frame pump. `[DONE]` and abort end the iterator without throwing.
  *
- * @param res - Fetch response (`text/event-stream`)
- * @param onEvent - Frame handler
+ * @param res - Fetch response
  * @param signal - Abort signal
  * @param onOpen - Called after content-type validation
  */
-export async function readSse(
+export async function* iterateSseFrames(
   res: Response,
-  onEvent: SseFrameHandler,
   signal: AbortSignal,
   onOpen?: () => void,
-): Promise<void> {
+): AsyncGenerator<ParsedSseFrame> {
   if (signal.aborted) return;
   const ct = res.headers.get("content-type") ?? "";
-  if (!res.ok || !res.body) {
+  if (!res.ok || !res.body || !ct.includes("text/event-stream")) {
     const text = await res.text().catch(() => "");
     throw sseError(res.status, text);
   }
-  if (!ct.includes("text/event-stream")) {
-    const text = await res.text().catch(() => "");
-    throw sseError(res.status, text || `Expected text/event-stream, got ${ct || "none"}`);
-  }
   onOpen?.();
   const reader = res.body.getReader();
   const dec = new TextDecoder();
@@ -39,14 +36,15 @@ export async function readSse(
     for (;;) {
       if (signal.aborted) return;
       const { done, value } = await reader.read();
-      if (done) break;
+      if (done) return;
       buf += dec.decode(value, { stream: true });
       let sep = buf.indexOf("\n\n");
       while (sep >= 0) {
         const raw = buf.slice(0, sep);
         buf = buf.slice(sep + 2);
-        const stop = dispatchFrame(raw, onEvent, signal);
-        if (stop || signal.aborted) return;
+        const frame = parseFrame(raw);
+        if (frame === "done" || signal.aborted) return;
+        if (frame) yield frame;
         sep = buf.indexOf("\n\n");
       }
     }
@@ -56,65 +54,21 @@ export async function readSse(
 }
 
 /**
- * Yield SSE JSON frames as an async iterable until `[DONE]`.
+ * Parse one SSE block. `"done"` stops the pump; `null` skips empty blocks.
  *
- * @param res - Fetch response
- * @param signal - Abort signal
+ * @param raw - Text between blank lines
  */
-export async function* iterateSse(res: Response, signal: AbortSignal): AsyncGenerator<unknown> {
-  const queue: unknown[] = [];
-  let wake: (() => void) | undefined;
-  let done = false;
-  let err: unknown;
-
-  const pump = readSse(
-    res,
-    (event) => {
-      queue.push(event);
-      wake?.();
-    },
-    signal,
-  )
-    .then(() => {
-      done = true;
-      wake?.();
-    })
-    .catch((e) => {
-      err = e;
-      done = true;
-      wake?.();
-    });
-
-  try {
-    for (;;) {
-      while (queue.length > 0) {
-        yield queue.shift();
-      }
-      if (done) break;
-      await new Promise<void>((r) => {
-        wake = r;
-      });
-      wake = undefined;
-    }
-    if (err) throw err;
-  } finally {
-    await pump.catch(() => {});
-  }
-}
-
-function dispatchFrame(raw: string, onEvent: SseFrameHandler, signal: AbortSignal): boolean {
+function parseFrame(raw: string): ParsedSseFrame | "done" | null {
   const dataLines: string[] = [];
   let id: string | undefined;
   for (const line of raw.split("\n")) {
     if (line.startsWith("id:")) id = line.slice(3).replace(/^ /, "");
     if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
   }
-  if (dataLines.length === 0) return false;
+  if (dataLines.length === 0) return null;
   const data = dataLines.join("\n");
-  if (data === "[DONE]") return true;
-  if (signal.aborted) return true;
-  onEvent(JSON.parse(data) as unknown, id);
-  return false;
+  if (data === "[DONE]") return "done";
+  return { event: JSON.parse(data) as unknown, id };
 }
 
 /** Build an Error with optional HTTP status. */
@@ -124,8 +78,12 @@ export function sseError(status: number, body: string): Error {
     try {
       const json: unknown = JSON.parse(body);
       if (json !== null && typeof json === "object" && "error" in json) {
-        const err = (json as { error?: { code?: string; data?: { message?: string } } }).error;
-        message = err?.data?.message ?? err?.code ?? message;
+        const err = (
+          json as {
+            error?: { code?: string; message?: string; data?: { message?: string } };
+          }
+        ).error;
+        message = err?.message ?? err?.data?.message ?? err?.code ?? message;
       }
     } catch {
       message = body.slice(0, 200);

package/src/client/stream.ts

@@ -4,8 +4,17 @@
  * @module
  */
 
-import { iterateSse, sseError } from "./sse.ts";
-import type { ClientFetch, ClientHeaders, ClientOptions, ClientRouteMap } from "./types.ts";
+import { iterateSseFrames, sseError } from "./sse.ts";
+import type { ClientFetch, ClientOptions, ClientRouteMap } from "./types.ts";
+import {
+  applyAuthHeader,
+  applyHeaderBag,
+  interpolatePath,
+  methodAndPath,
+  resolveHeaders,
+  toQuery,
+  walkContracts,
+} from "./wire.ts";
 
 /** Flow id → REST route for stream-only (non-live) SSE. */
 export type StreamByFlow = Readonly<
@@ -19,20 +28,12 @@ export type StreamByFlow = Readonly<
  */
 export function flattenStreamRoutes($routes: ClientRouteMap | undefined): StreamByFlow {
   const out: Record<string, { readonly method: string; readonly path: string }> = {};
-  if (!$routes) return out;
-  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;
-      if (!("stream" in contract) || contract.stream !== true) continue;
-      if ("live" in contract && typeof contract.live === "string") continue;
-      const method = "method" in contract ? contract.method : undefined;
-      const path = "path" in contract ? contract.path : undefined;
-      if (typeof method === "string" && typeof path === "string") {
-        out[`${unit}.${flow}`] = { method, path };
-      }
-    }
-  }
+  walkContracts($routes, (unit, flow, contract) => {
+    if (!("stream" in contract) || contract.stream !== true) return;
+    if ("live" in contract && typeof contract.live === "string") return;
+    const route = methodAndPath(contract);
+    if (route) out[`${unit}.${flow}`] = route;
+  });
   return out;
 }
 
@@ -51,36 +52,21 @@ export async function* openStream(
   opts: ClientOptions,
 ): AsyncGenerator<unknown> {
   const fetchFn: ClientFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  const signal = opts.signal ?? new AbortController().signal;
   let refreshed = false;
   for (;;) {
-    const ctrl = new AbortController();
-    const parent = opts.signal;
-    if (parent) {
-      if (parent.aborted) {
-        ctrl.abort();
-      } else {
-        parent.addEventListener("abort", () => ctrl.abort(), { once: true });
-      }
-    }
     const { url, method, body } = streamRequest(base, route.method, route.path, input);
     const headers = new Headers({ accept: "text/event-stream" });
-    const extra = typeof opts.headers === "function" ? await opts.headers() : opts.headers;
-    applyHeaders(headers, extra);
+    applyHeaderBag(headers, await resolveHeaders(opts));
     if (body !== undefined && !headers.has("content-type")) {
       headers.set("content-type", "application/json");
     }
-    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}`);
-    }
+    await applyAuthHeader(headers, opts);
     const res = await fetchFn(url, {
       method,
       headers,
       body,
-      signal: ctrl.signal,
+      signal,
       ...(opts.credentials !== undefined ? { credentials: opts.credentials } : {}),
     });
     if (
@@ -98,7 +84,7 @@ export async function* openStream(
       const text = await res.text().catch(() => "");
       throw sseError(res.status, text);
     }
-    yield* iterateSse(res, ctrl.signal);
+    for await (const frame of iterateSseFrames(res, signal)) yield frame.event;
     return;
   }
 }
@@ -109,39 +95,11 @@ function streamRequest(
   path: string,
   input: unknown,
 ): { url: string; method: string; body: string | undefined } {
-  const params =
-    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
-  let pathOut = path;
-  const rest: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(params)) {
-    const token = `:${k}`;
-    if (pathOut.includes(token)) {
-      pathOut = pathOut.replaceAll(token, encodeURIComponent(String(v)));
-    } else {
-      rest[k] = v;
-    }
-  }
+  const { path: pathOut, rest } = interpolatePath(path, input);
   const upper = method.toUpperCase();
-  let body: string | undefined;
   if (upper === "GET" || upper === "HEAD") {
-    const query: string[] = [];
-    for (const [k, v] of Object.entries(rest)) {
-      if (v !== undefined) {
-        query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
-      }
-    }
-    const qs = query.length ? `?${query.join("&")}` : "";
-    return { url: `${base}${pathOut}${qs}`, method: upper, body: undefined };
+    return { url: `${base}${pathOut}${toQuery(rest)}`, method: upper, body: undefined };
   }
-  body = JSON.stringify(Object.keys(rest).length > 0 ? rest : (input ?? {}));
+  const body = JSON.stringify(Object.keys(rest).length > 0 ? rest : (input ?? {}));
   return { url: `${base}${pathOut}`, method: upper, body };
 }
-
-function applyHeaders(headers: Headers, extra: ClientHeaders | undefined): void {
-  if (!extra) return;
-  if (Array.isArray(extra)) {
-    for (const [k, v] of extra) headers.set(k, v);
-  } else {
-    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
-  }
-}

package/src/client/transport.test.ts

@@ -46,6 +46,11 @@ describe("transport — retry", () => {
     const { error } = await api.sys.ping();
     expect(error?.code).toBe("TransportError");
     expect(n).toBe(2);
+    if (error?.code === "TransportError") {
+      expect(typeof error.message).toBe("string");
+      expect(error.message.length).toBeGreaterThan(0);
+      expect(error.message).toBe(error.data.message);
+    }
   });
 
   test("structured 5xx envelope is returned (not TransportError)", async () => {
@@ -139,6 +144,68 @@ describe("transport — auth refresh", () => {
     expect(error?.code).toBe("TransportError");
     if (error?.code === "TransportError") {
       expect(error.data.status).toBe(401);
+      expect(error.message).toBe(error.data.message);
+      expect(error.message).toBe("Invalid JSON (401)");
+    }
+  });
+});
+
+describe("transport — TransportError message contract", () => {
+  test("empty error body populates matching message fields", async () => {
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async () => new Response("", { status: 404 }),
+    });
+    const { error } = await api.sys.ping();
+    expect(error?.code).toBe("TransportError");
+    if (error?.code === "TransportError") {
+      expect(error.message).toBe("HTTP 404");
+      expect(error.message).toBe(error.data.message);
+      expect(error.data.status).toBe(404);
+    }
+  });
+
+  test("malformed JSON populates matching message fields", async () => {
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async () =>
+        new Response("not-json", {
+          status: 400,
+          headers: { "content-type": "application/json" },
+        }),
+    });
+    const { error } = await api.sys.ping();
+    expect(error?.code).toBe("TransportError");
+    if (error?.code === "TransportError") {
+      expect(error.message).toBe("Invalid JSON (400)");
+      expect(error.message).toBe(error.data.message);
+      expect(error.data.status).toBe(400);
+    }
+  });
+
+  test("incomplete proxy path populates matching message fields", async () => {
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async () => Response.json({ data: { ok: true }, error: null }),
+    });
+    // path stops at unit — api.sys() is incomplete
+    const result = await (
+      api.sys as unknown as () => Promise<{
+        error: { code: string; message: string; data: { message: string } };
+      }>
+    )();
+    expect(result.error.code).toBe("TransportError");
+    expect(result.error.message).toMatch(/Incomplete path/);
+    expect(result.error.message).toBe(result.error.data.message);
+  });
+
+  test("binary error path populates matching message fields", async () => {
+    const api = createClient<PingApp>("http://app.test", {
+      fetch: async () => new Response("nope", { status: 403 }),
+    });
+    const { error } = await api.sys.ping({ response: "blob" });
+    expect(error?.code).toBe("TransportError");
+    if (error?.code === "TransportError") {
+      expect(error.message).toBe("HTTP 403");
+      expect(error.message).toBe(error.data.message);
+      expect(error.data.status).toBe(403);
     }
   });
 });

package/src/client/transport.ts

@@ -12,6 +12,13 @@ import type {
   ClientHeaders,
   ClientOptions,
 } from "./types.ts";
+import {
+  applyAuthHeader,
+  applyHeaderBag,
+  interpolatePath,
+  resolveHeaders,
+  toQuery,
+} from "./wire.ts";
 
 /** Per-call transport options (binary decode, abort). */
 export interface TransportCallOptions {
@@ -83,15 +90,7 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
         } catch (err) {
           const transient = isTransient(err);
           if (!transient || attempt >= retries) {
-            return {
-              data: null,
-              error: {
-                code: "TransportError",
-                data: {
-                  message: err instanceof Error ? err.message : String(err),
-                },
-              },
-            };
+            return transportEnvelope(err instanceof Error ? err.message : String(err));
           }
           await sleep(delay);
           delay *= backoff;
@@ -102,6 +101,25 @@ export function createTransport(base: string, opts: ClientOptions = {}): Transpo
   };
 }
 
+/**
+ * Build a {@link ClientEnvelope} for a transport / protocol failure.
+ *
+ * Guarantees `error.message === error.data.message`.
+ *
+ * @param message - Human-readable failure text
+ * @param status - Optional HTTP status
+ */
+export function transportEnvelope(message: string, status?: number): ClientEnvelope {
+  return {
+    data: null,
+    error: {
+      code: "TransportError",
+      message,
+      data: status !== undefined ? { message, status } : { message },
+    },
+  };
+}
+
 function normalizeCallOpts(
   headersOrOpts: ClientHeaders | TransportCallOptions | undefined,
 ): TransportCallOptions {
@@ -143,37 +161,16 @@ async function once(
     : rpcRequest(base, key, input);
 
   const headers = new Headers();
-  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);
-  }
-  if (Array.isArray(callHeaders)) {
-    for (const [k, v] of callHeaders) headers.set(k, v);
-  } else if (callHeaders) {
-    for (const [k, v] of Object.entries(callHeaders)) headers.set(k, v);
-  }
+  applyHeaderBag(headers, await resolveHeaders(opts));
+  applyHeaderBag(headers, callHeaders);
   if (body !== undefined && !headers.has("content-type") && typeof body === "string") {
     headers.set("content-type", "application/json");
   }
+  await applyAuthHeader(headers, opts);
 
-  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}`);
-  }
-
-  const signals: AbortSignal[] = [];
-  if (opts.signal) signals.push(opts.signal);
-  if (opts.timeout !== undefined) {
-    const t = AbortSignal.timeout(opts.timeout);
-    signals.push(t);
-  }
+  const timeout = opts.timeout !== undefined ? AbortSignal.timeout(opts.timeout) : undefined;
   const signal =
-    signals.length === 0 ? undefined : signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+    opts.signal && timeout ? AbortSignal.any([opts.signal, timeout]) : (opts.signal ?? timeout);
 
   return await fetchFn(url, {
     method,
@@ -225,47 +222,32 @@ function restRequest(
   if (isRawBody(input)) {
     return { url: `${base}${path}`, method: method.toUpperCase(), body: input };
   }
-  const params =
-    input !== null && typeof input === "object" ? (input as Record<string, unknown>) : {};
-  let pathOut = path;
-  const query: string[] = [];
-  const rest: Record<string, unknown> = {};
-
-  for (const [k, v] of Object.entries(params)) {
-    const token = `:${k}`;
-    if (pathOut.includes(token)) {
-      pathOut = pathOut.replaceAll(token, encodeURIComponent(String(v)));
-    } else {
-      rest[k] = v;
-    }
-  }
+  const interpolated = interpolatePath(path, input);
+  const pathOut = interpolated.path;
+  const rest = interpolated.rest;
 
   const upper = method.toUpperCase();
+  const hasRest = Object.keys(rest).length > 0;
   let body: ClientBodyInit | undefined;
+  let qs = "";
   if (upper === "GET" || upper === "HEAD") {
-    for (const [k, v] of Object.entries(rest)) {
-      if (v !== undefined) {
-        query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
-      }
-    }
+    qs = toQuery(rest);
   } else if (upper === "QUERY") {
     // RFC 10008 QUERY always carries JSON content (empty object when only path params).
-    body = JSON.stringify(Object.keys(rest).length > 0 ? rest : {});
-  } else if (Object.keys(rest).length > 0 || path === pathOut) {
-    body = JSON.stringify(Object.keys(rest).length > 0 ? rest : (input ?? {}));
+    body = JSON.stringify(hasRest ? rest : {});
+  } else if (hasRest || path === pathOut) {
+    body = JSON.stringify(hasRest ? rest : (input ?? {}));
   }
 
-  const qs = query.length ? `?${query.join("&")}` : "";
   return { url: `${base}${pathOut}${qs}`, method: upper, body };
 }
 
 function isRawBody(input: unknown): input is ClientBodyInit {
-  if (input === null || input === undefined) return false;
-  if (typeof Blob !== "undefined" && input instanceof Blob) return true;
-  if (typeof FormData !== "undefined" && input instanceof FormData) return true;
-  if (typeof ArrayBuffer !== "undefined" && input instanceof ArrayBuffer) return true;
-  if (typeof ArrayBuffer !== "undefined" && ArrayBuffer.isView(input)) return true;
-  if (typeof ReadableStream !== "undefined" && input instanceof ReadableStream) return true;
+  if (input instanceof Blob) return true;
+  if (input instanceof FormData) return true;
+  if (input instanceof ArrayBuffer) return true;
+  if (ArrayBuffer.isView(input)) return true;
+  if (input instanceof ReadableStream) return true;
   return false;
 }
 
@@ -277,29 +259,14 @@ async function decode(res: Response): Promise<ClientEnvelope> {
   const text = await res.text();
   if (!text) {
     if (res.ok) return { data: undefined, error: null };
-    return {
-      data: null,
-      error: {
-        code: "TransportError",
-        data: { message: `HTTP ${res.status}`, status: res.status },
-      },
-    };
+    return transportEnvelope(`HTTP ${res.status}`, res.status);
   }
 
   let json: unknown;
   try {
     json = JSON.parse(text);
   } catch {
-    return {
-      data: null,
-      error: {
-        code: "TransportError",
-        data: {
-          message: `Invalid JSON (${res.status})`,
-          status: res.status,
-        },
-      },
-    };
+    return transportEnvelope(`Invalid JSON (${res.status})`, res.status);
   }
 
   if (json !== null && typeof json === "object" && "data" in json && "error" in json) {
@@ -310,47 +277,19 @@ async function decode(res: Response): Promise<ClientEnvelope> {
     return { data: json, error: null };
   }
 
-  return {
-    data: null,
-    error: {
-      code: "TransportError",
-      data: { message: `HTTP ${res.status}`, status: res.status },
-    },
-  };
+  return transportEnvelope(`HTTP ${res.status}`, res.status);
 }
 
 async function decodeBinary(res: Response, mode: "blob" | "arrayBuffer"): Promise<ClientEnvelope> {
   if (!res.ok) {
-    const structured = await decodeIfEnvelopeClone(res);
+    const structured = await decodeIfEnvelope(res);
     if (structured) return structured;
-    return {
-      data: null,
-      error: {
-        code: "TransportError",
-        data: { message: `HTTP ${res.status}`, status: res.status },
-      },
-    };
+    return transportEnvelope(`HTTP ${res.status}`, res.status);
   }
   const data = mode === "blob" ? await res.blob() : await res.arrayBuffer();
   return { data, error: null };
 }
 
-/** Try JSON envelope from an error response without assuming the body is reusable. */
-async function decodeIfEnvelopeClone(res: Response): Promise<ClientEnvelope | null> {
-  const text = await res.text();
-  if (!text) return null;
-  let json: unknown;
-  try {
-    json = JSON.parse(text);
-  } catch {
-    return null;
-  }
-  if (json !== null && typeof json === "object" && "data" in json && "error" in json) {
-    return json as ClientEnvelope;
-  }
-  return null;
-}
-
 function isTransient(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
   if (err.name === "AbortError") return false;

package/src/client/types.ts

@@ -5,6 +5,8 @@
  * Local / separate-repo: augment {@link Register} so `createClient(url)` needs no import.
  */
 
+import type { BuiltinErrorMap } from "../kernel/builtin-errors.ts";
+
 /**
  * One flow's client contract. `in` / `out` / `errors` are phantom (type-only).
  *
@@ -125,7 +127,8 @@ export interface TransportError {
     readonly message: string;
     readonly status?: number;
   };
-  readonly message?: string;
+  /** Same string as {@link TransportError.data.message}. */
+  readonly message: string;
 }
 
 /** Next / previous list request — TanStack `pageParam` / URL bag. */
@@ -431,12 +434,20 @@ type ContractIn<C> = "in" extends keyof C
 /** Pull output from a contract shape. */
 type ContractOut<C> = "out" extends keyof C ? NonNullable<C["out"]> : unknown;
 
-/** Pull error map from a contract shape. */
+/**
+ * Pull error map from a contract shape. Built-in codes are always on; declared
+ * keys win. A missing `errors` bag (phantom `Record<string, unknown>`) is
+ * treated as unspecified — not as an index signature that wipes the builtins.
+ */
 type ContractErrors<C> = "errors" extends keyof C
-  ? NonNullable<C["errors"]> extends Record<string, unknown>
-    ? NonNullable<C["errors"]>
-    : Record<string, never>
-  : Record<string, never>;
+  ? NonNullable<C["errors"]> extends infer E
+    ? E extends Record<string, unknown>
+      ? string extends keyof E
+        ? BuiltinErrorMap
+        : Omit<BuiltinErrorMap, keyof E> & E
+      : BuiltinErrorMap
+    : BuiltinErrorMap
+  : BuiltinErrorMap;
 
 /**
  * Typed client proxy derived from a route map.