ts-procedures 8.5.0 → 9.0.0

package/src/codegen/__goldens__/ts-flat--users/_client.ts

@@ -0,0 +1,1319 @@
+// Auto-generated by ts-procedures-codegen (v8.6.0) — do not edit
+// Source hash: 7b621d913616819f78563ff671bffa03
+
+import type {
+  ClientAdapter,
+  AdapterRequest,
+  AdapterResponse,
+  AdapterStreamResponse,
+  ClientHooks,
+  BeforeRequestContext,
+  AfterResponseContext,
+  ErrorContext,
+  CallDescriptor,
+  StreamDescriptor,
+  TypedStream,
+  ClientInstance,
+  ProcedureCallDefaults,
+  ProcedureCallOptions,
+  ClientHeadersInit,
+  CreateClientConfig,
+  RequestMeta,
+  ErrorRegistry,
+  ErrorFactory,
+  ErrorResponseMeta,
+  ErrorClassifier,
+  ClassifyErrorContext,
+  ClassifiedError,
+  Result,
+  ResultNoTyped,
+  ClientErrorMap,
+  FrameworkFailure,
+} from './_types'
+
+export class ClientHttpError extends Error {
+  readonly name = 'ClientHttpError'
+  readonly status: number
+  readonly headers: Record<string, string>
+  readonly body: unknown
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: {
+    status: number
+    headers: Record<string, string>
+    body: unknown
+    procedureName: string
+    scope: string
+    cause?: unknown
+  }) {
+    super(
+      `${opts.procedureName} (${opts.scope}) failed with status ${opts.status}`,
+      { cause: opts.cause }
+    )
+    this.status = opts.status
+    this.headers = opts.headers
+    this.body = opts.body
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+
+/** @deprecated Renamed to `ClientHttpError`. The alias is retained for one minor release after the 7.0.0 major bump and will be removed in a subsequent minor (e.g. 7.1.0). Migrate to `ClientHttpError` now. */
+ 
+export const ClientRequestError = ClientHttpError
+/** @deprecated Renamed to `ClientHttpError`. The alias is retained for one minor release after the 7.0.0 major bump and will be removed in a subsequent minor (e.g. 7.1.0). Migrate to `ClientHttpError` now. */
+// eslint-disable-next-line no-redeclare
+export type ClientRequestError = ClientHttpError
+
+export class ClientPathParamError extends Error {
+  readonly name = 'ClientPathParamError'
+
+  constructor(param: string, path: string, procedureName: string, cause?: unknown) {
+    super(`Missing path parameter "${param}" in "${path}" for procedure ${procedureName}`, { cause })
+  }
+}
+
+export class ClientStreamError extends Error {
+  readonly name = 'ClientStreamError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(message: string, procedureName: string, scope: string, cause?: unknown) {
+    super(message, { cause })
+    this.procedureName = procedureName
+    this.scope = scope
+  }
+}
+
+export class ClientNetworkError extends Error {
+  readonly name = 'ClientNetworkError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: { procedureName: string; scope: string; cause?: unknown; message?: string }) {
+    super(opts.message ?? `${opts.procedureName} (${opts.scope}) failed: network error`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+
+export class ClientTimeoutError extends Error {
+  readonly name = 'ClientTimeoutError'
+  readonly procedureName: string
+  readonly scope: string
+  readonly timeoutMs: number
+
+  constructor(opts: { procedureName: string; scope: string; timeoutMs: number; cause?: unknown }) {
+    super(`${opts.procedureName} (${opts.scope}) timed out after ${opts.timeoutMs}ms`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+    this.timeoutMs = opts.timeoutMs
+  }
+}
+
+export class ClientAbortError extends Error {
+  readonly name = 'ClientAbortError'
+  readonly procedureName: string
+  readonly scope: string
+  readonly reason: unknown
+
+  constructor(opts: { procedureName: string; scope: string; reason?: unknown; cause?: unknown }) {
+    super(`${opts.procedureName} (${opts.scope}) aborted`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+    this.reason = opts.reason
+  }
+}
+
+export class ClientParseError extends Error {
+  readonly name = 'ClientParseError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: { procedureName: string; scope: string; cause?: unknown; message?: string }) {
+    super(opts.message ?? `${opts.procedureName} (${opts.scope}) response could not be parsed`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+/**
+ * Default classifier — recognizes:
+ *   - `TypeError` from fetch → `ClientNetworkError`
+ *   - `DOMException` with `name: 'AbortError'` + timeout-signal-aborted → `ClientTimeoutError`
+ *   - `DOMException` with `name: 'AbortError'` + user-signal-aborted → `ClientAbortError`
+ *
+ * Returns `null` for anything else. Timeout precedence: when both signals
+ * fired, classifies as `timeout`.
+ */
+export const defaultClassifyError: ErrorClassifier = (raw, ctx) => {
+  const meta = { procedureName: ctx.procedureName, scope: ctx.scope }
+
+  if (raw instanceof TypeError) {
+    return {
+      kind: 'network',
+      error: new ClientNetworkError({ ...meta, cause: raw, message: raw.message }),
+    }
+  }
+
+  if (
+    raw instanceof DOMException &&
+    raw.name === 'AbortError'
+  ) {
+    if (ctx.timeoutSignal?.aborted) {
+      return {
+        kind: 'timeout',
+        error: new ClientTimeoutError({
+          ...meta,
+          timeoutMs: ctx.timeoutMs ?? 0,
+          cause: raw,
+        }),
+      }
+    }
+    if (ctx.userSignal?.aborted) {
+      return {
+        kind: 'aborted',
+        error: new ClientAbortError({
+          ...meta,
+          reason: ctx.userSignal.reason,
+          cause: raw,
+        }),
+      }
+    }
+    // AbortError without a tracked source — treat as user abort with no reason.
+    return {
+      kind: 'aborted',
+      error: new ClientAbortError({ ...meta, cause: raw }),
+    }
+  }
+
+  return null
+}
+/**
+ * Attempts to construct a typed error from the response body using the
+ * registry. Returns `null` when:
+ *   - no registry is configured,
+ *   - the body is not a plain object with a `name` string,
+ *   - no registry key matches the body's `name`, or
+ *   - `fromResponse` returns a non-Error value (defensive — registry entries
+ *     are expected to return `Error` subclasses).
+ *
+ * Callers fall back to `ClientHttpError` when this returns `null`.
+ */
+export function dispatchTypedError(
+  registry: ErrorRegistry | undefined,
+  body: unknown,
+  meta: ErrorResponseMeta
+): Error | null {
+  if (!registry) return null
+  if (!body || typeof body !== 'object') return null
+  const name = (body as { name?: unknown }).name
+  if (typeof name !== 'string') return null
+  const factory = registry[name]
+  if (!factory?.fromResponse) return null
+  const result = factory.fromResponse(body, meta)
+  return result instanceof Error ? result : null
+}
+/**
+ * Replaces `:paramName` segments in `path` with URI-encoded values from `params`.
+ * Throws `ClientPathParamError` if a required segment is missing from `params`.
+ */
+export function interpolatePath(
+  path: string,
+  params: Record<string, unknown>,
+  procedureName: string
+): string {
+  return path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_match, key: string) => {
+    const value = params[key]
+    if (value === undefined || value === null) {
+      throw new ClientPathParamError(key, path, procedureName)
+    }
+    return encodeURIComponent(String(value))
+  })
+}
+
+/**
+ * Builds an `AdapterRequest` from a `CallDescriptor` and a base URL.
+ *
+ * - `kind === 'rpc'` or `kind === 'stream'`: params are flat — sent as the JSON body.
+ * - `kind === 'api'` or `kind === 'http-stream'`: params are structured channels — `pathParams`, `query`, `body`, `headers`.
+ */
+export function buildAdapterRequest(descriptor: CallDescriptor, basePath: string): AdapterRequest {
+  const { name, path, method, kind, params } = descriptor
+
+  if (kind === 'rpc' || kind === 'stream') {
+    return {
+      url: `${basePath}${path}`,
+      method,
+      body: params,
+    }
+  }
+
+  // kind === 'api' | 'http-stream' — params are structured channels
+  const structured = (params ?? {}) as {
+    pathParams?: Record<string, unknown>
+    query?: Record<string, unknown>
+    body?: unknown
+    headers?: Record<string, string>
+  }
+
+  // Interpolate path params
+  const interpolatedPath = structured.pathParams
+    ? interpolatePath(path, structured.pathParams, name)
+    : path
+
+  // Build query string
+  let url = `${basePath}${interpolatedPath}`
+  if (structured.query && Object.keys(structured.query).length > 0) {
+    const searchParams = new URLSearchParams(
+      Object.entries(structured.query).map(([k, v]) => [k, String(v)])
+    )
+    url = `${url}?${searchParams.toString()}`
+  }
+
+  // Build headers
+  const headers =
+    structured.headers && Object.keys(structured.headers).length > 0
+      ? structured.headers
+      : undefined
+
+  return {
+    url,
+    method,
+    headers,
+    body: structured.body,
+  }
+}
+/**
+ * Resolves the effective base path:
+ *   per-call `basePath` > default `basePath` > config `basePath` (fallback).
+ */
+export function resolveBasePath(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+  fallback: string,
+): string {
+  return options?.basePath ?? defaults?.basePath ?? fallback
+}
+
+/**
+ * Resolves signal sources individually so callers can distinguish which
+ * underlying signal fired (e.g. timeout vs user abort in the error classifier).
+ *
+ * - `userSignal`: the per-call signal (if any); separate from the default signal
+ * - `timeoutSignal`: created via `AbortSignal.timeout(timeoutMs)` when timeout > 0
+ * - `timeoutMs`: the resolved timeout value (may be 0 if per-call explicitly disables)
+ * - `combined`: `AbortSignal.any([...])` of all active signals, or undefined if none
+ *
+ * Per-call `timeout: 0` disables an inherited default timeout (same as `resolveSignal`).
+ * Both `defaults.signal` and `options.signal` are included in `combined` when present.
+ */
+export interface SignalSources {
+  combined?: AbortSignal
+  timeoutSignal?: AbortSignal
+  /** The per-call signal, if provided. Separate from the default signal. */
+  userSignal?: AbortSignal
+  timeoutMs?: number
+}
+
+export function resolveSignalSources(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): SignalSources {
+  const userSignal = options?.signal
+  // Use explicit undefined check so timeout: 0 overrides defaults (not just nullish)
+  const timeoutMs = options?.timeout !== undefined ? options.timeout : defaults?.timeout
+  const timeoutSignal =
+    timeoutMs != null && timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined
+
+  const signals: AbortSignal[] = []
+  if (defaults?.signal) signals.push(defaults.signal)
+  if (userSignal) signals.push(userSignal)
+  if (timeoutSignal) signals.push(timeoutSignal)
+
+  let combined: AbortSignal | undefined
+  if (signals.length === 1) combined = signals[0]
+  else if (signals.length > 1) combined = AbortSignal.any(signals)
+
+  return { combined, timeoutSignal, userSignal, timeoutMs }
+}
+
+/**
+ * Resolves the effective AbortSignal by combining (via `AbortSignal.any`):
+ *   - default signal (if any)
+ *   - per-call signal (if any)
+ *   - timeout signal (if resolved timeout > 0)
+ *
+ * Returns undefined when none apply. Per-call `timeout: 0` disables an
+ * inherited default timeout.
+ *
+ * @deprecated Prefer `resolveSignalSources` when you need access to individual
+ * signal references (e.g. for abort-cause classification).
+ */
+export function resolveSignal(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): AbortSignal | undefined {
+  return resolveSignalSources(defaults, options).combined
+}
+
+/**
+ * Resolves a `ClientHeadersInit` value: a static record passes through, a
+ * function is invoked and (if async) awaited — re-evaluated on every call so
+ * values like a rotating bearer token never go stale.
+ */
+async function resolveHeadersValue(
+  h: ClientHeadersInit | undefined,
+): Promise<Record<string, string> | undefined> {
+  if (h == null) return undefined
+  return typeof h === 'function' ? await h() : h
+}
+
+/**
+ * Merges headers with precedence: default < per-call. Function-valued headers
+ * are evaluated (and awaited) per call. Returns undefined if no headers would
+ * be set.
+ */
+export async function resolveHeaders(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): Promise<Record<string, string> | undefined> {
+  const defaultHeaders = await resolveHeadersValue(defaults?.headers)
+  const callHeaders = await resolveHeadersValue(options?.headers)
+
+  if (!defaultHeaders && !callHeaders) return undefined
+
+  return { ...defaultHeaders, ...callHeaders }
+}
+
+/**
+ * Merges meta with precedence: default < per-call. Returns undefined if
+ * no meta fields would be set.
+ *
+ * The cast is load-bearing: when a developer augments `RequestMeta` with
+ * required fields, spread of two `RequestMeta | undefined` values widens to
+ * a partial shape, which TypeScript can't prove satisfies `RequestMeta`.
+ * At runtime, the merged object carries whichever keys the caller supplied —
+ * the contract is "if you declare required fields in RequestMeta, supply them
+ * somewhere (defaults or per-call)."
+ */
+export function resolveMeta(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): RequestMeta | undefined {
+  const defaultMeta = defaults?.meta
+  const callMeta = options?.meta
+
+  if (!defaultMeta && !callMeta) return undefined
+
+  return { ...defaultMeta, ...callMeta } as RequestMeta
+}
+
+export interface ApplyRequestOptionsResult {
+  request: AdapterRequest
+  signalSources: SignalSources
+}
+
+/**
+ * Applies resolved default + per-call options to an AdapterRequest.
+ *
+ * Runs before hooks, so `onBeforeRequest` observes the merged request and can
+ * still override any field.
+ *
+ * Headers produced by the request builder (e.g., `schema.input.headers` for
+ * API routes) are preserved; resolved headers merge underneath them so the
+ * route-declared headers win, matching the adapter.config → defaults → call
+ * → route-declared → hooks precedence chain documented in the types.
+ *
+ * Returns both the merged request and the raw `signalSources` so callers (e.g.
+ * the error classifier in Task 6) can distinguish timeout from user abort without
+ * losing provenance after `AbortSignal.any` collapses the originals.
+ */
+export async function applyRequestOptions(
+  request: AdapterRequest,
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): Promise<ApplyRequestOptionsResult> {
+  const signalSources = resolveSignalSources(defaults, options)
+  const resolvedHeaders = await resolveHeaders(defaults, options)
+  const meta = resolveMeta(defaults, options)
+
+  const headers =
+    resolvedHeaders || request.headers
+      ? { ...resolvedHeaders, ...request.headers }
+      : undefined
+
+  return {
+    request: { ...request, headers, signal: signalSources.combined, meta },
+    signalSources,
+  }
+}
+/**
+ * Runs `onBeforeRequest` hooks: global first, then per-procedure.
+ * Each hook receives the (possibly mutated) context from the previous hook.
+ * Returns the final context.
+ */
+export async function runBeforeRequest(
+  ctx: BeforeRequestContext,
+  globalHooks: ClientHooks,
+  localHooks: ClientHooks | undefined
+): Promise<BeforeRequestContext> {
+  let current = ctx
+
+  if (globalHooks.onBeforeRequest) {
+    current = await globalHooks.onBeforeRequest(current)
+  }
+
+  if (localHooks?.onBeforeRequest) {
+    current = await localHooks.onBeforeRequest(current)
+  }
+
+  return current
+}
+
+/**
+ * Runs `onAfterResponse` hooks: global first, then per-procedure.
+ * Returns void.
+ */
+export async function runAfterResponse(
+  ctx: AfterResponseContext,
+  globalHooks: ClientHooks,
+  localHooks: ClientHooks | undefined
+): Promise<void> {
+  if (globalHooks.onAfterResponse) {
+    await globalHooks.onAfterResponse(ctx)
+  }
+
+  if (localHooks?.onAfterResponse) {
+    await localHooks.onAfterResponse(ctx)
+  }
+}
+
+/**
+ * Runs `onError` hooks: global first, then per-procedure.
+ * Returns void.
+ */
+export async function runOnError(
+  ctx: ErrorContext,
+  globalHooks: ClientHooks,
+  localHooks: ClientHooks | undefined
+): Promise<void> {
+  if (globalHooks.onError) {
+    await globalHooks.onError(ctx)
+  }
+
+  if (localHooks?.onError) {
+    await localHooks.onError(ctx)
+  }
+}
+export interface ExecuteCallConfig {
+  descriptor: CallDescriptor
+  basePath: string
+  adapter: ClientAdapter
+  hooks: ClientHooks
+  defaults?: ProcedureCallDefaults
+  options?: ProcedureCallOptions
+  errorRegistry?: ErrorRegistry
+}
+
+/**
+ * Executes a single procedure call through the adapter.
+ *
+ * Flow:
+ * 1. Resolve base path (per-call > defaults > config) and build AdapterRequest
+ * 2. Apply request options (headers, signal, timeout, meta) from defaults + per-call
+ * 3. Run onBeforeRequest hooks (global then local) — may further mutate request
+ * 4. Call adapter.request()
+ * 5. On adapter error: run onError hooks, re-throw
+ * 6. Run onAfterResponse hooks (may mutate response.status to swallow errors)
+ * 7. If response status is non-2xx: throw ClientHttpError
+ * 8. Return response.body as TResponse
+ */
+export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise<TResponse> {
+  const { descriptor, basePath, adapter, hooks, defaults, options, errorRegistry } = config
+
+  // 1. Build the initial request (path/query/body from descriptor)
+  const resolvedBasePath = resolveBasePath(defaults, options, basePath)
+  let request = buildAdapterRequest(descriptor, resolvedBasePath)
+
+  // 2. Apply request-level options (headers, signal, timeout, meta)
+  const applied = await applyRequestOptions(request, defaults, options)
+  request = applied.request
+  const signalSources = applied.signalSources
+
+  // 3. Run before-request hooks — they may further mutate the request
+  const beforeCtx = await runBeforeRequest(
+    { procedureName: descriptor.name, scope: descriptor.scope, request },
+    hooks,
+    options,
+  )
+  request = beforeCtx.request
+
+  // 4. Call the adapter
+  let response
+  try {
+    response = await adapter.request(request)
+  } catch (rawErr) {
+    // 5. On adapter error: classify (adapter > default > fallthrough), then run
+    //    onError hooks with the normalized error, then throw.
+    const classifyCtx: ClassifyErrorContext = {
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+      timeoutSignal: signalSources.timeoutSignal,
+      userSignal: signalSources.userSignal,
+      timeoutMs: signalSources.timeoutMs,
+    }
+    const classified =
+      adapter.classifyError?.(rawErr, classifyCtx) ??
+      defaultClassifyError(rawErr, classifyCtx)
+    // Tag the classified error so executeSafeCall can identify its kind without
+    // re-classifying. Default kinds are recognized via instanceof in
+    // classifyThrownError; only custom adapter kinds need an explicit tag.
+    if (classified) {
+      const defaultKinds = new Set(['network', 'timeout', 'aborted', 'parse'])
+      if (!defaultKinds.has(classified.kind)) {
+        ;(classified.error as unknown as { __tsProceduresKind?: string }).__tsProceduresKind = classified.kind
+      }
+    }
+    const finalError = classified?.error ?? rawErr
+
+    await runOnError(
+      { procedureName: descriptor.name, scope: descriptor.scope, request, error: finalError },
+      hooks,
+      options,
+    )
+    throw finalError
+  }
+
+  // 6. Run after-response hooks — they may mutate response.status to swallow errors
+  await runAfterResponse(
+    { procedureName: descriptor.name, scope: descriptor.scope, request, response },
+    hooks,
+    options,
+  )
+
+  // 7. Check status AFTER hooks (hooks may have swallowed the error by mutating status)
+  if (response.status < 200 || response.status >= 300) {
+    const typed = dispatchTypedError(errorRegistry, response.body, {
+      status: response.status,
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+    })
+    if (typed) {
+      // Tag so executeSafeCall can distinguish typed registry errors from plain
+      // ClientHttpError without re-inspecting the registry.
+      ;(typed as unknown as { __tsProceduresTyped?: boolean }).__tsProceduresTyped = true
+      throw typed
+    }
+    throw new ClientHttpError({
+      status: response.status,
+      headers: response.headers,
+      body: response.body,
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+    })
+  }
+
+  // 8. Return the body (or { body, headers } when the route declares res.headers)
+  if (descriptor.responseHeadersDeclared) {
+    return { body: response.body, headers: response.headers } as TResponse
+  }
+  return response.body as TResponse
+}
+
+/**
+ * Wraps `executeCall` and returns a discriminated `Result` instead of throwing.
+ *
+ * Three failure-source paths map to distinct kinds:
+ *   1. Pre-adapter throw (e.g. `ClientPathParamError`) → `kind: 'usage'`
+ *   2. Adapter throw, classified → `kind: 'network' | 'timeout' | 'aborted' | <custom> | 'unknown'`
+ *   3. Adapter returns non-2xx → `kind: 'typed'` (registry match) or `kind: 'http'`
+ *
+ * `onError` hook fires on path 2 and 3 (cross-cutting telemetry); NOT on
+ * path 1 (usage errors bypass the classifier and onError entirely).
+ */
+export async function executeSafeCall<TResponse, ETyped = never>(
+  config: ExecuteCallConfig,
+): Promise<Result<TResponse, ETyped>> {
+  try {
+    const value = await executeCall<TResponse>(config)
+    return { ok: true, value }
+  } catch (err) {
+    return classifyThrownError<ETyped>(err)
+  }
+}
+
+function classifyThrownError<ETyped>(err: unknown): Result<never, ETyped> {
+  // Path 1: pre-adapter usage error — bypasses classifier and onError
+  if (err instanceof ClientPathParamError) {
+    return { ok: false, kind: 'usage', error: err }
+  }
+  // Path 3: post-status-check typed registry match — tagged by executeCall
+  if (err instanceof Error && (err as unknown as { __tsProceduresTyped?: boolean }).__tsProceduresTyped) {
+    return { ok: false, kind: 'typed', error: err as ETyped }
+  }
+  // Path 3: non-2xx fallback (no registry match)
+  if (err instanceof ClientHttpError) {
+    return { ok: false, kind: 'http', error: err }
+  }
+  // Path 2: classifier output (already normalized by executeCall)
+  if (err instanceof ClientNetworkError) {
+    return { ok: false, kind: 'network', error: err }
+  }
+  if (err instanceof ClientTimeoutError) {
+    return { ok: false, kind: 'timeout', error: err }
+  }
+  if (err instanceof ClientAbortError) {
+    return { ok: false, kind: 'aborted', error: err }
+  }
+  if (err instanceof ClientParseError) {
+    return { ok: false, kind: 'parse', error: err }
+  }
+  // Custom adapter-classified error — tagged with its kind by executeCall.
+  // The cast is intentional: the framework knows only the default ClientErrorMap
+  // keys, but consumer-augmented kinds are valid at the consumer's site (where
+  // the augmented map is in scope). The runtime kind string is whatever the
+  // adapter classifier returned; we trust it to match a registered entry.
+  if (err instanceof Error && typeof (err as unknown as { __tsProceduresKind?: string }).__tsProceduresKind === 'string') {
+    const kind = (err as unknown as { __tsProceduresKind: string }).__tsProceduresKind
+    return { ok: false, kind: kind as keyof ClientErrorMap, error: err } as FrameworkFailure
+  }
+  // Fallthrough — unrecognized throw type (non-Error or unclassified)
+  return { ok: false, kind: 'unknown', error: err }
+}
+// ── SSE item shape ────────────────────────────────────────
+
+interface SSEItem {
+  data: unknown
+  event?: string
+  id?: string
+}
+
+// ── createTypedStream ─────────────────────────────────────
+
+/**
+ * Optional context for SSE-mode typed-error dispatch. When supplied,
+ * `event: 'error'` items are decoded through the registry instead of being
+ * yielded as data — giving streams the same typed-error contract as RPC/API
+ * calls. See `dispatchTypedError`.
+ */
+export interface CreateTypedStreamOptions {
+  errorRegistry?: ErrorRegistry
+  /** Status to attach to typed-error meta when an `event: 'error'` is decoded. Defaults to 200 (the response was OK; the error was inline). */
+  errorStatus?: number
+  procedureName?: string
+  scope?: string
+}
+
+/**
+ * Wraps an AsyncIterable into a TypedStream.
+ *
+ * SSE mode: each item is `{ data, event?, id? }`.
+ *   - If `event === 'return'`, the data resolves `.result` and is NOT yielded.
+ *   - If `event === 'error'`, the data is dispatched through the optional
+ *     `errorRegistry` (when supplied) — the resulting typed error rejects
+ *     `.result` and is thrown from the iterator. Falls back to
+ *     `ClientStreamError` when no registry entry matches.
+ *   - Otherwise, `data` is yielded.
+ *
+ * Text mode: each item is yielded as-is.
+ *   - `.result` resolves to `void` on completion.
+ *
+ * On error: `.result` rejects and the error is re-thrown from the async iterator.
+ *
+ * The internal `.result` promise gets a no-op rejection handler attached so
+ * that consumers who only iterate (and never `await stream.result`) don't
+ * trigger an unhandled-rejection warning under Node's strict runners
+ * (e.g. node:test). Consumers that DO await `.result` still observe the
+ * rejection — `.catch(() => undefined)` returns a new promise without
+ * suppressing the original.
+ */
+export function createTypedStream<TYield, TReturn = void>(
+  source: AsyncIterable<unknown>,
+  streamMode: 'sse' | 'text',
+  options?: CreateTypedStreamOptions
+): TypedStream<TYield, TReturn> {
+  let resolveResult: (value: TReturn) => void
+  let rejectResult: (reason: unknown) => void
+
+  const resultPromise = new Promise<TReturn>((resolve, reject) => {
+    resolveResult = resolve
+    rejectResult = reject
+  })
+
+  // Attach a no-op rejection sink so unhandled-rejection trackers don't fire
+  // when the iterator throws but the consumer never `await`s `.result`. This
+  // is independent of the public promise — consumers awaiting `.result` still
+  // see the rejection.
+  resultPromise.catch(() => undefined)
+
+  async function* generate(): AsyncGenerator<TYield> {
+    try {
+      if (streamMode === 'sse') {
+        let returnValue: TReturn | undefined
+        let hasReturn = false
+
+        for await (const item of source) {
+          const sseItem = item as SSEItem
+          if (sseItem.event === 'return') {
+            returnValue = sseItem.data as TReturn
+            hasReturn = true
+          } else if (sseItem.event === 'error') {
+            // Mid-stream typed error. Mirror the call.ts dispatch contract:
+            // body shape is `{ name, ... }` and the registry maps `name` →
+            // typed class. When no registry / no match, surface a
+            // ClientStreamError carrying the raw body.
+            const typed = dispatchTypedError(options?.errorRegistry, sseItem.data, {
+              status: options?.errorStatus ?? 200,
+              procedureName: options?.procedureName ?? '',
+              scope: options?.scope ?? '',
+            })
+            if (typed) throw typed
+            const message = (() => {
+              const data = sseItem.data
+              if (data && typeof data === 'object' && 'message' in data && typeof (data as { message: unknown }).message === 'string') {
+                return (data as { message: string }).message
+              }
+              return `Stream error event for ${options?.procedureName ?? 'procedure'}`
+            })()
+            throw new ClientStreamError(
+              message,
+              options?.procedureName ?? '',
+              options?.scope ?? '',
+              sseItem.data,
+            )
+          } else {
+            yield sseItem.data as TYield
+          }
+        }
+
+        // Resolve result after iteration completes
+        if (hasReturn) {
+          resolveResult(returnValue as TReturn)
+        } else {
+          resolveResult(undefined as TReturn)
+        }
+      } else {
+        // text mode: yield each item as-is
+        for await (const item of source) {
+          yield item as TYield
+        }
+        resolveResult(undefined as TReturn)
+      }
+    } catch (err) {
+      rejectResult(err)
+      throw err
+    }
+  }
+
+  const iterator = generate()
+
+  return {
+    [Symbol.asyncIterator]() {
+      return iterator
+    },
+    result: resultPromise,
+  }
+}
+
+// ── executeStream ─────────────────────────────────────────
+
+export interface ExecuteStreamConfig {
+  descriptor: StreamDescriptor
+  basePath: string
+  adapter: ClientAdapter
+  hooks: ClientHooks
+  defaults?: ProcedureCallDefaults
+  options?: ProcedureCallOptions
+  errorRegistry?: ErrorRegistry
+}
+
+/**
+ * Executes a streaming procedure call through the adapter.
+ *
+ * Flow:
+ * 1. Resolve base path and build AdapterRequest
+ * 2. Apply request options (headers, signal, timeout, meta) from defaults + per-call
+ * 3. Run onBeforeRequest hooks
+ * 4. Call adapter.stream()
+ * 5. On adapter error: run onError hooks, re-throw
+ * 6. Run onAfterResponse immediately (before iteration), body is null
+ * 7. If non-2xx: throw ClientHttpError
+ * 8. Return createTypedStream(streamResponse.body, descriptor.streamMode)
+ */
+export async function executeStream<TYield, TReturn = void>(
+  config: ExecuteStreamConfig,
+): Promise<TypedStream<TYield, TReturn>> {
+  const { descriptor, basePath, adapter, hooks, defaults, options, errorRegistry } = config
+
+  // 1. Build the initial request
+  const resolvedBasePath = resolveBasePath(defaults, options, basePath)
+  let request = buildAdapterRequest(descriptor, resolvedBasePath)
+
+  // 2. Apply request-level options (headers, signal, timeout, meta)
+  const applied = await applyRequestOptions(request, defaults, options)
+  request = applied.request
+  const signalSources = applied.signalSources
+
+  // 3. Run before-request hooks
+  const beforeCtx = await runBeforeRequest(
+    { procedureName: descriptor.name, scope: descriptor.scope, request },
+    hooks,
+    options,
+  )
+  request = beforeCtx.request
+
+  // 4. Call the adapter
+  let streamResponse
+  try {
+    streamResponse = await adapter.stream(request)
+  } catch (rawErr) {
+    // 5. On adapter error: classify (adapter > default > fallthrough), then run
+    //    onError hooks with the normalized error, then throw.
+    const classifyCtx: ClassifyErrorContext = {
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+      timeoutSignal: signalSources.timeoutSignal,
+      userSignal: signalSources.userSignal,
+      timeoutMs: signalSources.timeoutMs,
+    }
+    const classified =
+      adapter.classifyError?.(rawErr, classifyCtx) ??
+      defaultClassifyError(rawErr, classifyCtx)
+    const finalError = classified?.error ?? rawErr
+
+    await runOnError(
+      { procedureName: descriptor.name, scope: descriptor.scope, request, error: finalError },
+      hooks,
+      options,
+    )
+    throw finalError
+  }
+
+  // Convert the platform Headers object to a plain record for the hooks/error
+  // context (AdapterResponse.headers is Record<string, string>). The raw
+  // platform Headers object is kept separately for TypedStream.headers.
+  const headersRecord: Record<string, string> = {}
+  streamResponse.headers.forEach((value, key) => { headersRecord[key] = value })
+
+  // Build an AdapterResponse shape for the hooks. For success the body is null
+  // (the actual data flows through the async iterable); for non-2xx the adapter
+  // eagerly parses the JSON response body and surfaces it via `errorBody`.
+  const responseForHooks: AdapterResponse = {
+    status: streamResponse.status,
+    headers: headersRecord,
+    body: streamResponse.errorBody ?? null,
+  }
+
+  // 6. Run after-response hooks immediately (before iteration)
+  await runAfterResponse(
+    { procedureName: descriptor.name, scope: descriptor.scope, request, response: responseForHooks },
+    hooks,
+    options,
+  )
+
+  // 7. Check status after hooks (hooks may mutate responseForHooks.status)
+  if (responseForHooks.status < 200 || responseForHooks.status >= 300) {
+    const typed = dispatchTypedError(errorRegistry, responseForHooks.body, {
+      status: responseForHooks.status,
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+    })
+    if (typed) throw typed
+    throw new ClientHttpError({
+      status: responseForHooks.status,
+      headers: responseForHooks.headers,
+      body: responseForHooks.body,
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+    })
+  }
+
+  // 8. Return the typed stream — pass the registry/descriptor through so
+  // mid-stream `event: 'error'` items dispatch through the same registry as
+  // RPC/API calls.
+  const typedStream = createTypedStream<TYield, TReturn>(streamResponse.body, descriptor.streamMode, {
+    errorRegistry,
+    errorStatus: responseForHooks.status,
+    procedureName: descriptor.name,
+    scope: descriptor.scope,
+  })
+
+  // Wire the initial response headers onto the stream when the route declares
+  // res.headers. The platform Headers object is passed directly from the adapter.
+  if (descriptor.responseHeadersDeclared) {
+    typedStream.headers = streamResponse.headers
+  }
+
+  return typedStream
+}
+// ── Config ────────────────────────────────────────────────
+
+export interface FetchAdapterConfig {
+  headers?: Record<string, string>
+  classifyError?: ErrorClassifier
+}
+
+// ── SSE parser ────────────────────────────────────────────
+
+interface SSEEvent {
+  data: unknown
+  event?: string
+  id?: string
+}
+
+/**
+ * Parses an SSE message block (the text between double-newlines).
+ * Returns null if there is no data field (e.g., comment-only blocks).
+ */
+function parseSSEBlock(block: string): SSEEvent | null {
+  const lines = block.split('\n')
+  let event: string | undefined
+  let id: string | undefined
+  const dataParts: string[] = []
+
+  for (const line of lines) {
+    if (line.startsWith('event:')) {
+      event = line.slice('event:'.length).trim()
+    } else if (line.startsWith('data:')) {
+      dataParts.push(line.slice('data:'.length).trimStart())
+    } else if (line.startsWith('id:')) {
+      id = line.slice('id:'.length).trim()
+    }
+    // Lines starting with ':' are comments — skip them
+  }
+
+  if (dataParts.length === 0) {
+    return null
+  }
+
+  const dataStr = dataParts.join('\n')
+  let data: unknown
+  try {
+    data = JSON.parse(dataStr)
+  } catch {
+    data = dataStr
+  }
+
+  return { data, event, id }
+}
+
+/**
+ * Async generator that reads a ReadableStream<Uint8Array>, buffers text,
+ * splits on double-newline SSE boundaries, and yields parsed SSE events.
+ */
+async function* parseSseStream(
+  readableStream: ReadableStream<Uint8Array>
+): AsyncGenerator<SSEEvent> {
+  const reader = readableStream.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+
+      if (value) {
+        buffer += decoder.decode(value, { stream: !done })
+      }
+
+      // Process all complete SSE message blocks (split on \n\n)
+      let boundary: number
+      while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+        const block = buffer.slice(0, boundary).trim()
+        buffer = buffer.slice(boundary + 2)
+
+        if (block.length > 0) {
+          const event = parseSSEBlock(block)
+          if (event !== null) {
+            yield event
+          }
+        }
+      }
+
+      if (done) break
+    }
+
+    // Handle any remaining buffer content (no trailing \n\n)
+    const remaining = buffer.trim()
+    if (remaining.length > 0) {
+      const event = parseSSEBlock(remaining)
+      if (event !== null) {
+        yield event
+      }
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+// ── Adapter ───────────────────────────────────────────────
+
+/**
+ * Extracts response headers as a plain Record<string, string>.
+ */
+function extractHeaders(response: Response): Record<string, string> {
+  const headers: Record<string, string> = {}
+  response.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+  return headers
+}
+
+/**
+ * Attempts to parse the response body as JSON, then as text, then returns null.
+ */
+async function parseResponseBody(response: Response): Promise<unknown> {
+  // Clone so we can attempt multiple reads
+  const clone = response.clone()
+  try {
+    return await clone.json()
+  } catch {
+    try {
+      const text = await response.text()
+      return text || null
+    } catch {
+      return null
+    }
+  }
+}
+
+/**
+ * Creates a fetch-based ClientAdapter.
+ *
+ * - `config.headers` are default headers applied to every request.
+ * - Per-request headers override config headers (spread order).
+ * - Works in Node.js 18+ and browsers (uses standard fetch + ReadableStream).
+ */
+export function createFetchAdapter(config?: FetchAdapterConfig): ClientAdapter {
+  const configHeaders = config?.headers ?? {}
+
+  return {
+    async request(req: AdapterRequest): Promise<AdapterResponse> {
+      const mergedHeaders: Record<string, string> = {
+        ...configHeaders,
+        ...(req.headers ?? {}),
+      }
+
+      const response = await fetch(req.url, {
+        method: req.method,
+        headers: mergedHeaders,
+        body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
+        signal: req.signal,
+      })
+
+      const headers = extractHeaders(response)
+      const body = await parseResponseBody(response)
+
+      return { status: response.status, headers, body }
+    },
+
+    async stream(req: AdapterRequest): Promise<AdapterStreamResponse> {
+      const mergedHeaders: Record<string, string> = {
+        ...configHeaders,
+        ...(req.headers ?? {}),
+      }
+
+      const response = await fetch(req.url, {
+        method: req.method,
+        headers: mergedHeaders,
+        body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
+        signal: req.signal,
+      })
+
+      // Expose the platform Headers object directly — callers that declared
+      // res.headers receive it on TypedStream.headers without any conversion.
+      const { headers } = response
+      const emptyBody: AsyncIterable<unknown> = {
+        [Symbol.asyncIterator]: async function* () {},
+      }
+
+      // Non-2xx responses on a stream endpoint are JSON, not SSE. Parse the
+      // body eagerly and surface it via errorBody so the client can dispatch
+      // a typed error (or fall back to ClientHttpError with a real body).
+      if (response.status < 200 || response.status >= 300) {
+        const errorBody = await parseResponseBody(response)
+        return { status: response.status, headers, body: emptyBody, errorBody }
+      }
+
+      if (!response.body) {
+        return { status: response.status, headers, body: emptyBody }
+      }
+
+      const body = parseSseStream(response.body as ReadableStream<Uint8Array>)
+      return { status: response.status, headers, body }
+    },
+
+    classifyError: config?.classifyError,
+  }
+}
+// ── createClient ──────────────────────────────────────────
+
+/**
+ * Folds `config.auth` into the resolved default headers as a single async
+ * function-valued `ClientHeadersInit`. Resolves the user's existing default
+ * headers (record OR function) to a record first, then appends
+ * `Authorization: Bearer <token>` when `auth()` yields a non-null token.
+ * Re-evaluated per request, so a rotating token never goes stale.
+ */
+function composeAuthHeaders(
+  base: ClientHeadersInit | undefined,
+  auth: NonNullable<CreateClientConfig<unknown>['auth']>,
+): ClientHeadersInit {
+  return async () => {
+    const resolvedBase = base == null ? {} : typeof base === 'function' ? await base() : base
+    const token = await auth()
+    return token ? { ...resolvedBase, Authorization: `Bearer ${token}` } : resolvedBase
+  }
+}
+
+/**
+ * Creates a typed client from a config object.
+ *
+ * The `scopes` callback receives a `ClientInstance` and returns the typed
+ * scope bindings (e.g., `{ users: { getUser, createUser }, posts: { ... } }`).
+ * The return value of `createClient` is the scopes object.
+ *
+ * `client.stream()` must return `TypedStream` synchronously even though
+ * `executeStream` is async. We achieve this by creating a deferred TypedStream:
+ * - A deferred async generator awaits `executeStream` internally, then forwards
+ *   yields from the inner stream.
+ * - The outer `.result` is wired up to the inner stream's `.result`.
+ */
+export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TScopes {
+  const {
+    adapter,
+    basePath,
+    hooks: globalHooks = {},
+    defaults: configDefaults = {},
+    errorRegistry,
+    auth,
+    scopes,
+  } = config
+
+  // `auth` is sugar over a function-valued `defaults.headers`: fold it into the
+  // resolved default headers as an async function so it shares the single
+  // per-request header-resolution path (no new resolution branch). The user's
+  // existing `defaults.headers` (record or function) is resolved first, then the
+  // bearer token is appended — a null/undefined token omits the header.
+  const globalDefaults: ProcedureCallDefaults = auth
+    ? { ...configDefaults, headers: composeAuthHeaders(configDefaults.headers, auth) }
+    : configDefaults
+
+  const instance: ClientInstance = {
+    basePath,
+    adapter,
+    hooks: globalHooks,
+    defaults: globalDefaults,
+    errorRegistry,
+
+    call<TResponse>(
+      descriptor: CallDescriptor,
+      options?: ProcedureCallOptions,
+    ): Promise<TResponse> {
+      return executeCall<TResponse>({
+        descriptor,
+        basePath,
+        adapter,
+        hooks: globalHooks,
+        defaults: globalDefaults,
+        options,
+        errorRegistry,
+      })
+    },
+
+    safeCall<TResponse, ETyped = never>(
+      descriptor: CallDescriptor,
+      options?: ProcedureCallOptions,
+    ): Promise<Result<TResponse, ETyped>> {
+      return executeSafeCall<TResponse, ETyped>({
+        descriptor,
+        basePath,
+        adapter,
+        hooks: globalHooks,
+        defaults: globalDefaults,
+        options,
+        errorRegistry,
+      })
+    },
+
+    bindCallable<TParams, TResponse>(descriptor: Omit<CallDescriptor, 'params'>) {
+      const call = (params: TParams, options?: ProcedureCallOptions) =>
+        instance.call<TResponse>({ ...descriptor, params }, options)
+      Object.defineProperty(call, 'name', { value: descriptor.name, configurable: true })
+      return Object.assign(call, {
+        safe: (params: TParams, options?: ProcedureCallOptions) =>
+          instance.safeCall<TResponse>({ ...descriptor, params }, options) as Promise<ResultNoTyped<TResponse>>,
+      })
+    },
+
+    bindCallableTyped<TParams, TResponse, ETyped>(descriptor: Omit<CallDescriptor, 'params'>) {
+      const call = (params: TParams, options?: ProcedureCallOptions) =>
+        instance.call<TResponse>({ ...descriptor, params }, options)
+      Object.defineProperty(call, 'name', { value: descriptor.name, configurable: true })
+      return Object.assign(call, {
+        safe: (params: TParams, options?: ProcedureCallOptions) =>
+          instance.safeCall<TResponse, ETyped>({ ...descriptor, params }, options),
+      })
+    },
+
+    stream<TYield, TReturn>(
+      descriptor: StreamDescriptor,
+      options?: ProcedureCallOptions,
+    ): TypedStream<TYield, TReturn> {
+      // executeStream is async but stream() must be synchronous.
+      // Create a deferred TypedStream that wraps the async executeStream call.
+
+      let resolveResult: (value: TReturn) => void
+      let rejectResult: (reason: unknown) => void
+
+      const resultPromise = new Promise<TReturn>((resolve, reject) => {
+        resolveResult = resolve
+        rejectResult = reject
+      })
+
+      // Attach a no-op rejection sink so unhandled-rejection trackers (e.g.
+      // node:test) don't fire when the iterator throws but the consumer never
+      // awaits `.result`. Returns a new promise — consumers awaiting
+      // `resultPromise` still observe the rejection.
+      resultPromise.catch(() => undefined)
+
+      // The deferred async generator: awaits executeStream, then forwards
+      async function* deferredGenerator(): AsyncGenerator<TYield> {
+        let innerStream: TypedStream<TYield, TReturn>
+        try {
+          innerStream = await executeStream<TYield, TReturn>({
+            descriptor,
+            basePath,
+            adapter,
+            hooks: globalHooks,
+            defaults: globalDefaults,
+            options,
+            errorRegistry,
+          })
+        } catch (err) {
+          rejectResult(err)
+          throw err
+        }
+
+        // Wire up .result from the inner stream
+        innerStream.result.then(resolveResult, rejectResult)
+
+        for await (const item of innerStream) {
+          yield item
+        }
+      }
+
+      const iterator = deferredGenerator()
+
+      return {
+        [Symbol.asyncIterator]() {
+          return iterator
+        },
+        result: resultPromise,
+      }
+    },
+  }
+
+  return scopes(instance)
+}