@nifrajs/client 1.12.0 → 2.0.0

package/dist/validate-responses.js

@@ -0,0 +1,82 @@
+/**
+ * Runtime response-contract assertion for the in-process test client
+ * (`testClient(app, { validateResponses: true })`).
+ *
+ * The `response` / `errors` schemas on a route are a compile-time contract on the handler; nothing
+ * re-checks the bytes that actually leave the app. This wrapper closes that gap in tests: every
+ * JSON response is validated against the route's declared schema for its status - `response` for
+ * 2xx, `errors[status]` for declared failures - and a mismatch THROWS (failing the test loudly)
+ * instead of letting a drifted payload pass. Responses with no declared schema for their status,
+ * non-JSON bodies (SSE, streams, HTML), and 204/205/HEAD are passed through untouched.
+ *
+ * Route lookup reuses the framework's own `Router` over `app.routes()`, so pattern matching can
+ * never drift from what the server itself does.
+ */
+import { Router } from "@nifrajs/core/router";
+/**
+ * A response body that broke its route's declared contract. Thrown THROUGH the "never throws"
+ * client on purpose: this is a test assertion about the server's honesty, not a call outcome the
+ * caller should branch on - swallowing it into a `Result` would let the drift pass the test.
+ */
+export class ResponseContractViolation extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ResponseContractViolation";
+    }
+}
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = (issue.path ?? [])
+            .map((seg) => String(typeof seg === "object" && seg !== null ? seg.key : seg))
+            .join(".");
+        return path === "" ? issue.message : `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+/**
+ * Wrap the in-process bridge so every response is checked against its route's declared contract.
+ * Throws at wrap time when the app cannot enumerate routes - a misconfiguration, not a soft skip.
+ */
+export function withResponseValidation(app, bridge) {
+    const routesOf = app.routes;
+    if (typeof routesOf !== "function") {
+        throw new Error("validateResponses needs an app that exposes .routes() (a nifra server); this app does not");
+    }
+    // One router per client, built once: match by the server's own engine, payload = the schema.
+    const router = new Router();
+    for (const route of routesOf.call(app)) {
+        router.add(route.method, route.path, route.schema);
+    }
+    return async (url, init) => {
+        const response = await bridge(url, init);
+        const method = (init?.method ?? "GET").toUpperCase();
+        const status = response.status;
+        if (method === "HEAD" || status === 204 || status === 205)
+            return response;
+        const match = router.find(method, new URL(url).pathname);
+        if (!match.found)
+            return response;
+        const schema = match.payload;
+        const declared = status >= 200 && status < 300 ? schema?.response : schema?.errors?.[status];
+        if (declared === undefined)
+            return response;
+        const contentType = response.headers.get("content-type") ?? "";
+        if (!contentType.includes("application/json"))
+            return response;
+        // Clone so the caller still gets an unconsumed body; unparseable JSON is the transport's problem.
+        let body;
+        try {
+            body = await response.clone().json();
+        }
+        catch {
+            return response;
+        }
+        const result = await declared["~standard"].validate(body);
+        if (result.issues !== undefined) {
+            throw new ResponseContractViolation(`response contract violation: ${method} ${new URL(url).pathname} → ${status}: ${formatIssues(result.issues)}`);
+        }
+        return response;
+    };
+}
+//# sourceMappingURL=validate-responses.js.map

package/dist/validate-responses.js.map

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

package/dist/ws.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The typed client's WebSocket transport - the runtime behind `api.chat.ws()` for routes declared
+ * with `app.ws()`. Uses the platform's global `WebSocket` (browser, Bun, Node 22+, Deno, workerd),
+ * mapping the client's `http(s)` base to `ws(s)`. Frames are JSON on the typed surface: `send`
+ * encodes, `messages()`/`onMessage` parse text frames (binary frames bypass the typed contract -
+ * read them off `raw`). Sends before the socket opens are queued, so the handle never throws.
+ */
+import type { WsCallOptions, WsHandle } from "./treaty.js";
+/** Internal handshake between `inProcessClient` and the proxy: in-process apps have no socket. */
+export declare const NO_SOCKET: unique symbol;
+interface WsRuntimeOptions extends WsCallOptions {
+    headers?: Record<string, string> | undefined;
+}
+export declare function openWebSocket(base: string, path: string, callOptions: WsRuntimeOptions | undefined, noSocket: boolean): WsHandle<unknown, unknown>;
+export {};
+//# sourceMappingURL=ws.d.ts.map

package/dist/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE1D,kGAAkG;AAClG,eAAO,MAAM,SAAS,eAA0C,CAAA;AAEhE,UAAU,gBAAiB,SAAQ,aAAa;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;CAC7C;AAWD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,gBAAgB,GAAG,SAAS,EACzC,QAAQ,EAAE,OAAO,GAChB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CA0H5B"}

package/dist/ws.js

@@ -0,0 +1,133 @@
+/**
+ * The typed client's WebSocket transport - the runtime behind `api.chat.ws()` for routes declared
+ * with `app.ws()`. Uses the platform's global `WebSocket` (browser, Bun, Node 22+, Deno, workerd),
+ * mapping the client's `http(s)` base to `ws(s)`. Frames are JSON on the typed surface: `send`
+ * encodes, `messages()`/`onMessage` parse text frames (binary frames bypass the typed contract -
+ * read them off `raw`). Sends before the socket opens are queued, so the handle never throws.
+ */
+/** Internal handshake between `inProcessClient` and the proxy: in-process apps have no socket. */
+export const NO_SOCKET = Symbol.for("@nifrajs/client/no-socket");
+function toWsUrl(base, path, query) {
+    const url = new URL(base + (path === "" ? "/" : path));
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    for (const [key, value] of Object.entries(query ?? {})) {
+        url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+}
+export function openWebSocket(base, path, callOptions, noSocket) {
+    if (noSocket) {
+        throw new Error("the in-process client cannot open WebSockets (app.fetch has no socket) - listen() the app and connect with client(baseUrl)");
+    }
+    const WebSocketImpl = globalThis.WebSocket;
+    if (WebSocketImpl === undefined) {
+        throw new Error("no global WebSocket in this runtime - .ws() needs one (browser, Bun, Node 22+)");
+    }
+    const url = toWsUrl(base, path, callOptions?.query);
+    const socket = callOptions?.protocols !== undefined
+        ? new WebSocketImpl(url, callOptions.protocols)
+        : new WebSocketImpl(url);
+    const sendQueue = [];
+    const listeners = new Set();
+    const opened = new Promise((resolve, reject) => {
+        socket.addEventListener("open", () => resolve(), { once: true });
+        socket.addEventListener("error", (event) => {
+            callOptions?.onError?.(event);
+            reject(new Error("websocket_connect_failed"));
+        }, { once: true });
+    });
+    // The rejection is surfaced via `opened` (and `onError`) only for those who look - an unconsumed
+    // `opened` on a failed connect must not crash the process with an unhandled rejection.
+    opened.catch(() => { });
+    socket.addEventListener("open", () => {
+        for (const frame of sendQueue)
+            socket.send(frame);
+        sendQueue.length = 0;
+    });
+    socket.addEventListener("message", (event) => {
+        if (typeof event.data !== "string")
+            return; // binary frames live off the typed contract
+        let parsed;
+        try {
+            parsed = JSON.parse(event.data);
+        }
+        catch {
+            return; // a non-JSON text frame is outside the contract too
+        }
+        for (const listener of listeners)
+            listener(parsed);
+    });
+    if (callOptions?.signal !== undefined) {
+        if (callOptions.signal.aborted)
+            socket.close();
+        else
+            callOptions.signal.addEventListener("abort", () => socket.close(), { once: true });
+    }
+    const onMessage = (callback) => {
+        listeners.add(callback);
+        return () => listeners.delete(callback);
+    };
+    return {
+        raw: socket,
+        opened,
+        send(message) {
+            const frame = JSON.stringify(message);
+            if (socket.readyState === WebSocketImpl.OPEN)
+                socket.send(frame);
+            else
+                sendQueue.push(frame);
+        },
+        close(code, reason) {
+            socket.close(code, reason);
+        },
+        onMessage,
+        messages(options) {
+            const buffered = [];
+            let pending;
+            let done = false;
+            const push = (message) => {
+                if (pending !== undefined) {
+                    const resolve = pending;
+                    pending = undefined;
+                    resolve({ value: message, done: false });
+                }
+                else {
+                    buffered.push(message);
+                }
+            };
+            const end = () => {
+                if (done)
+                    return;
+                done = true;
+                unsubscribe();
+                pending?.({ value: undefined, done: true });
+                pending = undefined;
+            };
+            const unsubscribe = onMessage(push);
+            socket.addEventListener("close", end, { once: true });
+            socket.addEventListener("error", end, { once: true });
+            options?.signal?.addEventListener("abort", end, { once: true });
+            const iterator = {
+                [Symbol.asyncIterator]() {
+                    return this;
+                },
+                next() {
+                    if (buffered.length > 0) {
+                        return Promise.resolve({ value: buffered.shift(), done: false });
+                    }
+                    if (done)
+                        return Promise.resolve({ value: undefined, done: true });
+                    return new Promise((resolve) => {
+                        pending = resolve;
+                    });
+                },
+                return() {
+                    end();
+                    return Promise.resolve({ value: undefined, done: true });
+                },
+            };
+            return iterator;
+        },
+    };
+}
+//# sourceMappingURL=ws.js.map

package/dist/ws.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/client",
-  "version": "1.12.0",
+  "version": "2.0.0",
   "description": "Browser-safe, end-to-end-typed client for @nifrajs/core servers (Eden-style proxy).",
   "keywords": [
     "bun",
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^1.12.0"
+    "@nifrajs/core": "^2.0.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*",

package/src/client.ts

@@ -1,4 +1,4 @@
-import type { ContractShape, RegistryFor } from "@nifrajs/core"
+import type { ContractShape, RegistryFor } from "@nifrajs/core/contract"
 import {
   type BackendMount,
   type BackendMountHandler,
@@ -6,6 +6,8 @@ import {
 } from "@nifrajs/core/mount"
 import type { ApiError, Result } from "./result.ts"
 import type { Subscription, Treaty, TreatyFromRegistry } from "./treaty.ts"
+import { ResponseContractViolation, withResponseValidation } from "./validate-responses.ts"
+import { NO_SOCKET, openWebSocket } from "./ws.ts"
 
 const HTTP_VERBS: ReadonlySet<string> = new Set([
   "get",
@@ -24,16 +26,93 @@ const BODY_VERBS: ReadonlySet<string> = new Set(["post", "put", "patch"])
  */
 export type FetchFn = (input: string, init?: RequestInit) => Promise<Response>
 
+type MaybePromise<T> = T | Promise<T>
+
+/** Safe retry policy. Off unless `retry` is set; retries ONLY idempotent methods and transient 5xx —
+ * never a 4xx/429 and never a non-idempotent method, so a retry can't double a side effect. */
+export interface ClientRetryOptions {
+  /** Max RETRIES after the first attempt. Default 2. */
+  readonly attempts?: number
+  /** Response statuses to retry. Default `[502, 503, 504]`. 4xx/429 are never added by default. */
+  readonly on?: readonly number[]
+  /** Methods eligible for retry. Default the idempotent set `GET/HEAD/OPTIONS/PUT/DELETE`. */
+  readonly methods?: readonly string[]
+  /** Delay (ms) before retry `n` (1-based). Default exponential backoff with jitter, capped at 3s. */
+  readonly backoff?: (attempt: number) => number
+}
+
 export interface ClientOptions {
   /** Headers sent on every request (a per-call `headers` option is merged on top). */
   readonly headers?: Record<string, string>
   /** Override the `fetch` implementation (tests, an in-process bridge, a custom agent, etc.). */
   readonly fetch?: FetchFn
+  /**
+   * Runs before each request (including each retry). Return a header map to MERGE onto the outgoing
+   * request — the place to inject a fresh auth token. `await`ed, so async token refresh works.
+   */
+  readonly onRequest?: (request: {
+    readonly url: string
+    readonly method: string
+    readonly headers: Record<string, string>
+    readonly body: unknown
+  }) => MaybePromise<Record<string, string> | undefined>
+  /** Runs after a response arrives (once per call, on the final response). Observe-only. */
+  readonly onResponse?: (response: {
+    readonly url: string
+    readonly method: string
+    readonly response: Response
+  }) => MaybePromise<void>
+  /** Abort a call that takes longer than this many ms. Surfaces as `{ ok: false, status: 0 }` with a
+   * `timeout` error, never a throw. Combined with a per-call `signal`. */
+  readonly timeoutMs?: number
+  /** Enable safe automatic retries. See {@link ClientRetryOptions}. */
+  readonly retry?: ClientRetryOptions
+}
+
+const DEFAULT_RETRY_STATUSES: readonly number[] = [502, 503, 504]
+const IDEMPOTENT_METHODS: readonly string[] = ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]
+
+function defaultBackoff(attempt: number): number {
+  return Math.min(300 * 2 ** (attempt - 1), 3000) + Math.random() * 100
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+/** Combine a per-call signal with a timeout into one signal; also returns the timeout signal so the
+ * caller can tell a timeout abort from a caller abort. */
+function buildSignal(
+  userSignal: AbortSignal | undefined,
+  timeoutMs: number | undefined,
+): { signal?: AbortSignal | undefined; timeout?: AbortSignal | undefined } {
+  const timeout =
+    timeoutMs !== undefined && typeof AbortSignal.timeout === "function"
+      ? AbortSignal.timeout(timeoutMs)
+      : undefined
+  const parts = [userSignal, timeout].filter((s): s is AbortSignal => s !== undefined)
+  if (parts.length === 0) return {}
+  if (parts.length === 1) return { signal: parts[0], timeout }
+  const signal = typeof AbortSignal.any === "function" ? AbortSignal.any(parts) : parts[0]
+  return { signal, timeout }
 }
 
 /** Typed route client plus the explicit platform-aware backend mount capability. */
 export type InProcessClient<App> = Treaty<App> & BackendMount
 
+export interface InProcessClientOptions extends Omit<ClientOptions, "fetch"> {
+  /**
+   * Assert every JSON response against the route's declared contract — `schema.response` for 2xx,
+   * `schema.errors[status]` for declared failures — and THROW on mismatch, so a handler whose real
+   * output drifts from its schema fails the test instead of passing silently. Statuses with no
+   * declared schema, non-JSON bodies, and 204/205/HEAD pass through unchecked. Test-focused: the
+   * check parses a clone of each JSON body, a cost that belongs in tests, not production hot paths.
+   */
+  readonly validateResponses?: boolean
+}
+
 interface CallOptions {
   readonly query?: Record<string, unknown>
   readonly headers?: Record<string, string>
@@ -83,25 +162,30 @@ export function client(
  *
  * The returned proxy also implements the explicit symbol-keyed {@link BackendMount} interface, so
  * `createWebApp({ api: inProcessClient(backend) })` can auto-mount the backend while forwarding the
- * outer runtime's `env` and `waitUntil`. The released `.fetch(url, init)` bridge remains available as
- * a compatibility surface for custom integrations, but the platform-aware mount never relies on it.
+ * outer runtime's `env` and `waitUntil`.
  */
 export function inProcessClient<
   App extends { fetch(request: Request): Response | Promise<Response> },
->(app: App, options?: Omit<ClientOptions, "fetch">): InProcessClient<App> {
+>(app: App, options?: InProcessClientOptions): InProcessClient<App> {
   // The in-process bridge: the client speaks `fetch(url, init)` (the `FetchFn` shape) while the app's
-  // own `fetch` takes a `Request`. Kept as the proxy's per-call transport and the released legacy
-  // `.fetch` mount bridge; the symbol-keyed mount below is the platform-aware path.
-  const bridge: FetchFn = (url, init) => Promise.resolve(app.fetch(new Request(url, init)))
+  // own `fetch` takes a `Request`. It is the proxy's per-call transport; the symbol-keyed mount below
+  // is the platform-aware auto-mount path.
+  const direct: FetchFn = (url, init) => Promise.resolve(app.fetch(new Request(url, init)))
+  const bridge = options?.validateResponses === true ? withResponseValidation(app, direct) : direct
   const mount: BackendMountHandler = (request, platform) =>
     Promise.resolve((app.fetch as BackendMountHandler)(request, platform))
-  const proxy = client<App>("http://nifra.internal", { ...options, fetch: bridge })
-  // An outer Proxy intercepts only the explicit mount symbol and legacy `fetch` key, delegating every
-  // typed route segment unchanged (`api.users({ id }).get()`).
+  // NO_SOCKET marks the options so a typed `.ws()` call fails with a real explanation — an
+  // in-process app has no socket to upgrade — instead of dialing ws://nifra.internal into the void.
+  const proxy = client<App>("http://nifra.internal", {
+    ...options,
+    fetch: bridge,
+    [NO_SOCKET]: true,
+  } as ClientOptions)
+  // An outer Proxy intercepts only the explicit mount symbol, delegating every typed route segment
+  // unchanged (`api.users({ id }).get()`).
   return new Proxy(proxy as object, {
     get(targetProxy, key, receiver) {
       if (key === NIFRA_BACKEND_MOUNT) return mount
-      if (key === "fetch") return bridge
       return Reflect.get(targetProxy, key, receiver)
     },
   }) as InProcessClient<App>
@@ -141,6 +225,16 @@ function createProxy(base: string, path: string, options: ClientOptions): unknow
         return (onEvent: (event: unknown) => void, subscribeOptions?: SubscribeCallOptions) =>
           subscribeSse(base, path, onEvent, subscribeOptions, options)
       }
+      // Typed WebSocket handle for `app.ws()` routes — `ws` is a reserved proxy key like `subscribe`.
+      if (key === "ws") {
+        return (wsOptions?: Parameters<typeof openWebSocket>[2]) =>
+          openWebSocket(
+            base,
+            path,
+            { headers: options.headers, ...wsOptions },
+            NO_SOCKET in options,
+          )
+      }
       // `index` addresses the root path "/" and adds no segment.
       return createProxy(base, key === "index" ? path : `${path}/${key}`, options)
     },
@@ -177,22 +271,57 @@ async function execute(
   const query = callOptions?.query ? buildQuery(callOptions.query) : ""
   if (query !== "") url += `?${query}`
 
+  const method = verb.toUpperCase()
   const headers: Record<string, string> = { ...options.headers, ...callOptions?.headers }
-  const init: RequestInit = { method: verb.toUpperCase(), headers }
+  if (options.onRequest !== undefined) {
+    const extra = await options.onRequest({ url, method, headers, body })
+    if (extra !== undefined) Object.assign(headers, extra)
+  }
+  const init: RequestInit = { method, headers }
   if (body !== undefined) {
     init.body = JSON.stringify(body)
     headers["content-type"] = "application/json"
   }
-  if (callOptions?.signal) init.signal = callOptions.signal
-
+  const { signal, timeout } = buildSignal(callOptions?.signal, options.timeoutMs)
+  if (signal !== undefined) init.signal = signal
+
+  // Safe retry: only when configured, only for idempotent methods + transient statuses, so a retry
+  // can never duplicate a side effect (a POST is never retried unless the app opts its method in).
+  const retry = options.retry
+  const maxRetries = retry === undefined ? 0 : (retry.attempts ?? 2)
+  const retryStatuses = new Set(retry?.on ?? DEFAULT_RETRY_STATUSES)
+  const retryMethods = new Set((retry?.methods ?? IDEMPOTENT_METHODS).map((m) => m.toUpperCase()))
+  const methodRetryable = retryMethods.has(method)
+  const backoff = retry?.backoff ?? defaultBackoff
   const doFetch = options.fetch ?? fetch
+
   let response: Response
-  try {
-    response = await doFetch(url, init)
-  } catch {
-    return { ok: false, status: 0, data: null, error: { error: "network_error" } }
+  let attempt = 0
+  for (;;) {
+    try {
+      response = await doFetch(url, init)
+    } catch (error) {
+      // A contract violation is a test assertion (validateResponses), not a call outcome — let it
+      // fail the test instead of degrading into a `Result` the test would happily branch on.
+      if (error instanceof ResponseContractViolation) throw error
+      if (methodRetryable && attempt < maxRetries) {
+        attempt += 1
+        await delay(backoff(attempt))
+        continue
+      }
+      const code = timeout?.aborted === true ? "timeout" : "network_error"
+      return { ok: false, status: 0, data: null, error: { error: code } }
+    }
+    if (methodRetryable && attempt < maxRetries && retryStatuses.has(response.status)) {
+      attempt += 1
+      await delay(backoff(attempt))
+      continue
+    }
+    break
   }
 
+  if (options.onResponse !== undefined) await options.onResponse({ url, method, response })
+
   const data = await parseBody(response)
   if (response.ok) {
     return { ok: true, status: response.status, data, error: null }
@@ -394,7 +523,12 @@ function subscribeSse(
 function buildQuery(query: Record<string, unknown>): string {
   const params = new URLSearchParams()
   for (const [key, value] of Object.entries(query)) {
-    if (value !== undefined) params.set(key, String(value))
+    if (value === undefined) continue
+    if (Array.isArray(value)) {
+      for (const item of value) params.append(key, String(item))
+    } else {
+      params.set(key, String(value))
+    }
   }
   return params.toString()
 }

package/src/index.ts

@@ -6,9 +6,11 @@
  */
 export {
   type ClientOptions,
+  type ClientRetryOptions,
   client,
   type FetchFn,
   type InProcessClient,
+  type InProcessClientOptions,
   inProcessClient,
   testClient,
 } from "./client.ts"
@@ -21,4 +23,7 @@ export type {
   Subscription,
   Treaty,
   TreatyFromRegistry,
+  WsCallOptions,
+  WsHandle,
 } from "./treaty.ts"
+export { ResponseContractViolation } from "./validate-responses.ts"

package/src/result.ts

@@ -8,18 +8,96 @@ export interface ApiError {
 }
 
 /**
- * The outcome of a client call. The client never throws — inspect `ok` to branch.
- * `data` is the parsed response body, **typed by `ok`**: on success it's the route's
- * response type; on failure it's the parsed error body, typed from the route's
- * `errors` contract (`unknown` when the route declares none, `null` on a transport
- * error with no response body). `error` is always the server's normalized
- * `{ error, issues? }` summary on failure (or a transport error), `null` on success.
+ * The failure statuses a call can carry (the IANA registry's 3xx/4xx/5xx set). Finite on purpose:
+ * the undeclared-status fallback arm of {@link Result} is `Exclude<ErrorStatus, declared>` - with a
+ * bare `number` there instead, `status === 404` could not narrow `data` to the declared 404 body,
+ * because 404 would still inhabit the fallback arm.
  */
-export type Result<Data, ErrData = unknown> =
+export type ErrorStatus =
+  | 300
+  | 301
+  | 302
+  | 303
+  | 304
+  | 305
+  | 306
+  | 307
+  | 308
+  | 400
+  | 401
+  | 402
+  | 403
+  | 404
+  | 405
+  | 406
+  | 407
+  | 408
+  | 409
+  | 410
+  | 411
+  | 412
+  | 413
+  | 414
+  | 415
+  | 416
+  | 417
+  | 418
+  | 421
+  | 422
+  | 423
+  | 424
+  | 425
+  | 426
+  | 428
+  | 429
+  | 431
+  | 451
+  | 500
+  | 501
+  | 502
+  | 503
+  | 504
+  | 505
+  | 506
+  | 507
+  | 508
+  | 510
+  | 511
+
+/** One failure arm per declared error status: `status` is the literal, `data` its declared body. */
+type DeclaredFailures<Errors extends Record<number, unknown>> = {
+  [K in Extract<keyof Errors, number>]: {
+    readonly ok: false
+    readonly status: K
+    readonly data: Errors[K]
+    readonly error: ApiError
+  }
+}[Extract<keyof Errors, number>]
+
+/**
+ * The outcome of a client call. The client never throws - inspect `ok` to branch.
+ *
+ * On success, `data` is the route's response type. On failure the union is DISCRIMINATED BY
+ * `status` when the route declares an `errors` record: `status === 404` narrows `data` to the
+ * declared 404 body; every undeclared status (plus `0` for a transport error with no response)
+ * falls into a fallback arm whose `data` is `unknown`. A route with no `errors` contract keeps a
+ * single failure arm with `data: Errors` (`unknown`). `error` is always the server's normalized
+ * `{ error, issues? }` summary on failure, `null` on success.
+ */
+export type Result<Data, Errors = unknown> =
   | { readonly ok: true; readonly status: number; readonly data: Data; readonly error: null }
-  | {
-      readonly ok: false
-      readonly status: number
-      readonly data: ErrData
-      readonly error: ApiError
-    }
+  | ([Errors] extends [Record<number, unknown>]
+      ?
+          | DeclaredFailures<Errors>
+          | {
+              readonly ok: false
+              readonly status: Exclude<ErrorStatus, Extract<keyof Errors, number>> | 0
+              readonly data: unknown
+              readonly error: ApiError
+            }
+      : {
+          readonly ok: false
+          readonly status: number
+          readonly data: Errors
+          readonly error: ApiError
+        })

package/src/routes.ts

@@ -1,4 +1,4 @@
-import type { ContractShape, RegistryFor } from "@nifrajs/core"
+import type { ContractShape, RegistryFor } from "@nifrajs/core/contract"
 import type { Treaty, TreatyFromRegistry } from "./treaty.ts"
 
 /**