ts-procedures 5.16.0 → 6.0.1

package/src/codegen/emit-index.test.ts

@@ -34,9 +34,12 @@ describe('emitIndexFile', () => {
     expect(output).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
   })
 
-  it('imports ClientInstance from ts-procedures/client', () => {
+  it('imports createClient as a value and client types for the factory', () => {
     const output = emitIndexFile([usersGroup])
-    expect(output).toContain("import type { ClientInstance } from 'ts-procedures/client'")
+    expect(output).toContain("import { createClient } from 'ts-procedures/client'")
+    expect(output).toContain(
+      "import type { ClientInstance, CreateClientConfig } from 'ts-procedures/client'"
+    )
   })
 
   it('imports each scope as a namespace using an underscore-prefixed alias', () => {
@@ -55,27 +58,35 @@ describe('emitIndexFile', () => {
     expect(output).toContain("import * as _adminUsers from './admin-users'")
   })
 
-  it('generates the factory using the default service name (Api)', () => {
+  it('generates the bindings factory using the default service name (Api)', () => {
     const output = emitIndexFile([usersGroup, billingGroup])
     expect(output).toContain('export function createApiBindings(client: ClientInstance)')
     expect(output).toContain('users: _users.bindUsersScope(client)')
     expect(output).toContain('billing: _billing.bindBillingScope(client)')
   })
 
+  it('always emits a createApiClient convenience factory', () => {
+    const output = emitIndexFile([usersGroup])
+    expect(output).toContain('export function createApiClient(')
+    expect(output).toContain('return createClient({')
+    expect(output).toContain('scopes: (client) => createApiBindings(client)')
+  })
+
+  it('createApiClient wires the error registry when hasErrors is true', () => {
+    const output = emitIndexFile([usersGroup], { hasErrors: true })
+    expect(output).toContain('errorRegistry: _errorsModule.ApiErrorRegistry')
+  })
+
+  it('createApiClient omits the registry wiring when hasErrors is false', () => {
+    const output = emitIndexFile([usersGroup], { hasErrors: false })
+    expect(output).not.toContain('errorRegistry:')
+  })
+
   it('uses camelCase as the binding property key (not the underscored alias)', () => {
     const output = emitIndexFile([adminUsersGroup])
     expect(output).toContain('adminUsers: _adminUsers.bindAdminUsersScope(client)')
   })
 
-  it('places imports before the namespace block before the factory', () => {
-    const output = emitIndexFile([usersGroup, billingGroup], { namespaceTypes: true })
-    const importIdx = output.indexOf("import * as _users")
-    const namespaceIdx = output.indexOf('export namespace Api')
-    const factoryIdx = output.indexOf('export function createApiBindings')
-    expect(importIdx).toBeLessThan(namespaceIdx)
-    expect(namespaceIdx).toBeLessThan(factoryIdx)
-  })
-
   describe('service namespace (namespaceTypes: true)', () => {
     it('emits a service namespace named after the default Api', () => {
       const output = emitIndexFile([usersGroup, billingGroup], { namespaceTypes: true })
@@ -85,10 +96,14 @@ describe('emitIndexFile', () => {
     })
 
     it('emits a service namespace named after a provided serviceName', () => {
-      const output = emitIndexFile([usersGroup], { namespaceTypes: true, serviceName: 'UsersApi' })
+      const output = emitIndexFile([usersGroup], {
+        namespaceTypes: true,
+        serviceName: 'UsersApi',
+      })
       expect(output).toContain('export namespace UsersApi {')
       expect(output).toContain('export import Users = _users.Users')
       expect(output).toContain('export function createUsersApiBindings(client: ClientInstance)')
+      expect(output).toContain('export function createUsersApiClient(')
     })
 
     it('PascalCases each scope when re-exporting', () => {
@@ -96,10 +111,19 @@ describe('emitIndexFile', () => {
       expect(output).toContain('export import AdminUsers = _adminUsers.AdminUsers')
     })
 
-    it('PascalCases a kebab-case serviceName for both namespace and factory', () => {
-      const output = emitIndexFile([usersGroup], { namespaceTypes: true, serviceName: 'auth-service' })
+    it('PascalCases a kebab-case serviceName for both namespace and factories', () => {
+      const output = emitIndexFile([usersGroup], {
+        namespaceTypes: true,
+        serviceName: 'auth-service',
+        hasErrors: true,
+      })
       expect(output).toContain('export namespace AuthService {')
       expect(output).toContain('export function createAuthServiceBindings(client: ClientInstance)')
+      expect(output).toContain('export function createAuthServiceClient(')
+      // In namespace mode the registry lives inside the errors namespace.
+      expect(output).toContain(
+        'errorRegistry: _errorsModule.AuthServiceErrors.AuthServiceErrorRegistry'
+      )
     })
 
     it('folds errors into the service namespace as `Errors` when hasErrors is true', () => {
@@ -112,10 +136,9 @@ describe('emitIndexFile', () => {
       expect(output).toContain('export import Errors = _errorsModule.UsersApiErrors')
     })
 
-    it('omits the errors import and re-export when hasErrors is false', () => {
+    it('omits the errors re-export from the namespace when hasErrors is false', () => {
       const output = emitIndexFile([usersGroup], { namespaceTypes: true, hasErrors: false })
-      expect(output).not.toContain("from './_errors'")
-      expect(output).not.toContain('Errors')
+      expect(output).not.toContain("import * as _errorsModule from './_errors'")
     })
   })
 
@@ -126,29 +149,50 @@ describe('emitIndexFile', () => {
       expect(output).not.toContain('export import')
     })
 
-    it('still imports scopes and emits the factory', () => {
+    it('still imports scopes and emits both factories', () => {
       const output = emitIndexFile([usersGroup, billingGroup])
       expect(output).toContain("import * as _users from './users'")
       expect(output).toContain('export function createApiBindings(client: ClientInstance)')
-      expect(output).toContain('users: _users.bindUsersScope(client)')
+      expect(output).toContain('export function createApiClient(')
     })
 
-    it('does not import errors even when hasErrors is true', () => {
+    it('imports _errors as a value when hasErrors, regardless of namespaceTypes', () => {
       const output = emitIndexFile([usersGroup], { hasErrors: true })
+      // Registry is a runtime value, so the import is NOT `import type`.
+      expect(output).toContain("import * as _errorsModule from './_errors'")
+      // In flat mode the registry is a top-level export of the module.
+      expect(output).toContain('errorRegistry: _errorsModule.ApiErrorRegistry')
+    })
+
+    it('qualifies the registry path through the errors namespace in namespace mode', () => {
+      const output = emitIndexFile([usersGroup], {
+        hasErrors: true,
+        namespaceTypes: true,
+      })
+      expect(output).toContain(
+        'errorRegistry: _errorsModule.ApiErrors.ApiErrorRegistry'
+      )
+    })
+
+    it('omits the _errors import when hasErrors is false', () => {
+      const output = emitIndexFile([usersGroup], { hasErrors: false })
       expect(output).not.toContain("from './_errors'")
     })
   })
 
   describe('clientImportPath', () => {
-    it('uses custom clientImportPath in import statement', () => {
+    it('uses custom clientImportPath in both import statements', () => {
       const output = emitIndexFile([usersGroup], { clientImportPath: '@my-app/client' })
-      expect(output).toContain("import type { ClientInstance } from '@my-app/client'")
+      expect(output).toContain("import { createClient } from '@my-app/client'")
+      expect(output).toContain(
+        "import type { ClientInstance, CreateClientConfig } from '@my-app/client'"
+      )
       expect(output).not.toContain("from 'ts-procedures/client'")
     })
 
     it('defaults to ts-procedures/client when not specified', () => {
       const output = emitIndexFile([usersGroup])
-      expect(output).toContain("import type { ClientInstance } from 'ts-procedures/client'")
+      expect(output).toContain("import { createClient } from 'ts-procedures/client'")
     })
   })
 })

package/src/codegen/emit-index.ts

@@ -9,7 +9,14 @@ const ERRORS_MODULE_ALIAS = '_errorsModule'
 // ---------------------------------------------------------------------------
 
 export interface EmitIndexOptions {
+  /** Import specifier for types (`ClientInstance`, `CreateClientConfig`). */
   clientImportPath?: string
+  /**
+   * Import specifier for runtime values (`createClient`). Defaults to
+   * `clientImportPath`. In self-contained mode the pipeline sets this to
+   * `./_client` while `clientImportPath` points at `./_types`.
+   */
+  clientRuntimeImportPath?: string
   hasErrors?: boolean
   namespaceTypes?: boolean
   serviceName?: string
@@ -30,10 +37,13 @@ export function emitIndexFile(groups: ScopeGroup[], options?: EmitIndexOptions):
     namespaceTypes = false,
     serviceName = 'Api',
   } = options ?? {}
+  const clientRuntimeImportPath = options?.clientRuntimeImportPath ?? clientImportPath
 
   const servicePascal = toPascalCase(serviceName)
   const factoryName = `create${servicePascal}Bindings`
+  const clientFactoryName = `create${servicePascal}Client`
   const errorsExportedName = `${servicePascal}Errors`
+  const registryName = `${servicePascal}ErrorRegistry`
 
   // Underscore-prefix the local module alias so scope names that collide with
   // TypeScript reserved words (e.g. `public`, `default`, `class`) compile.
@@ -43,7 +53,9 @@ export function emitIndexFile(groups: ScopeGroup[], options?: EmitIndexOptions):
     .map((g) => `import * as ${localAlias(g.camelCase)} from './${g.scopeKey}'`)
     .join('\n')
 
-  const errorsImport = namespaceTypes && hasErrors
+  // `_errors` is imported as a value (not `import type`) when errors exist, so
+  // the runtime registry is reachable for `createApiClient`.
+  const errorsImport = hasErrors
     ? `import * as ${ERRORS_MODULE_ALIAS} from './_errors'`
     : ''
 
@@ -69,9 +81,10 @@ export function emitIndexFile(groups: ScopeGroup[], options?: EmitIndexOptions):
     .map((g) => `    ${g.camelCase}: ${localAlias(g.camelCase)}.bind${toPascalCase(g.camelCase)}Scope(client),`)
     .join('\n')
 
-  return [
+  const pieces: string[] = [
     CODEGEN_HEADER,
-    `import type { ClientInstance } from '${clientImportPath}'`,
+    `import { createClient } from '${clientRuntimeImportPath}'`,
+    `import type { ClientInstance, CreateClientConfig } from '${clientImportPath}'`,
     importsBlock,
     '',
     namespaceBlock,
@@ -81,5 +94,54 @@ export function emitIndexFile(groups: ScopeGroup[], options?: EmitIndexOptions):
     '  }',
     '}',
     '',
-  ].join('\n')
+  ]
+
+  // `createApiClient` is a convenience wrapper that wires `createClient` with
+  // the generated error registry baked in, then invokes the bindings factory.
+  // Consumers that want manual control over `createClient` still use the
+  // factory above.
+  if (hasErrors) {
+    // In namespace mode, classes + registry live inside `${Service}Errors`;
+    // in flat mode they're at the module's top level.
+    const registryPath = namespaceTypes
+      ? `${ERRORS_MODULE_ALIAS}.${errorsExportedName}.${registryName}`
+      : `${ERRORS_MODULE_ALIAS}.${registryName}`
+
+    pieces.push(
+      `/**`,
+      ` * Creates a typed client for this service with the generated error`,
+      ` * registry pre-configured. Non-2xx responses whose body \`name\` matches`,
+      ` * a registered error are thrown as typed class instances instead of`,
+      ` * generic \`ClientRequestError\`s.`,
+      ` */`,
+      `export function ${clientFactoryName}(`,
+      `  config: Omit<CreateClientConfig<ReturnType<typeof ${factoryName}>>, 'scopes' | 'errorRegistry'>`,
+      `) {`,
+      `  return createClient({`,
+      `    ...config,`,
+      `    errorRegistry: ${registryPath},`,
+      `    scopes: (client) => ${factoryName}(client),`,
+      `  })`,
+      `}`,
+      '',
+    )
+  } else {
+    pieces.push(
+      `/**`,
+      ` * Creates a typed client for this service. No error registry is`,
+      ` * attached because the DocEnvelope contained no typed errors.`,
+      ` */`,
+      `export function ${clientFactoryName}(`,
+      `  config: Omit<CreateClientConfig<ReturnType<typeof ${factoryName}>>, 'scopes'>`,
+      `) {`,
+      `  return createClient({`,
+      `    ...config,`,
+      `    scopes: (client) => ${factoryName}(client),`,
+      `  })`,
+      `}`,
+      '',
+    )
+  }
+
+  return pieces.join('\n')
 }

package/src/codegen/emit-scope.ts

@@ -22,18 +22,30 @@ export interface EmitScopeOptions {
   ajsc?: AjscOptions
   clientImportPath?: string
   namespaceTypes?: boolean
+  /** Service identifier used to namespace generated error types (defaults to 'Api'). */
+  serviceName?: string
+  /**
+   * Error keys present in the generated `_errors.ts`. Routes may list keys
+   * that aren't emitted (e.g. no schema); those are filtered out at emit time
+   * so generated code never references undefined types.
+   */
+  errorKeys?: Set<string>
 }
 
 interface RouteChunks {
   typeDeclarations: string[]
   callable: string
   hasStream: boolean
+  /** True when this route emitted an `Errors` type (drives the `_errors` import at the top of the scope file). */
+  hasErrors: boolean
 }
 
 interface EmitRouteContext {
   ajsc?: AjscOptions
   namespaceTypes: boolean
   scopePascal: string
+  serviceName: string
+  errorKeys?: Set<string>
 }
 
 // ---------------------------------------------------------------------------
@@ -162,6 +174,62 @@ async function formatTypes(
   return { declarations, refs }
 }
 
+// ---------------------------------------------------------------------------
+// Route-level Errors union injection
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the body of an `Errors` type union from the route's declared error
+ * keys. Filters to keys actually emitted in `_errors.ts` so generated code
+ * never references undefined types.
+ *
+ * In namespace mode the union uses qualified names (`ApiErrors.UseCaseError`);
+ * in flat mode it uses the bundled wildcard import alias (`_errors.UseCaseError`).
+ * Returns `null` when no keys remain.
+ */
+function buildErrorUnion(
+  routeErrors: string[] | undefined,
+  ctx: EmitRouteContext
+): string | null {
+  if (!routeErrors || routeErrors.length === 0) return null
+  const available = ctx.errorKeys
+  const filtered = available ? routeErrors.filter((k) => available.has(k)) : routeErrors
+  if (filtered.length === 0) return null
+  const qualify = ctx.namespaceTypes
+    ? (k: string) => `${toPascalCase(ctx.serviceName)}Errors.${k}`
+    : (k: string) => `_errors.${k}`
+  return filtered.map(qualify).join(' | ')
+}
+
+/**
+ * Injects `export type Errors = ...` into an existing route namespace block
+ * (namespace mode) or appends a flat `export type ${pascal}Errors = ...` in
+ * flat mode. Mutates the `declarations` array in place and returns whether an
+ * injection happened.
+ */
+function injectRouteErrors(
+  declarations: string[],
+  routePascal: string,
+  errorUnion: string | null,
+  namespaceTypes: boolean
+): boolean {
+  if (!errorUnion) return false
+  if (namespaceTypes) {
+    const lastIdx = declarations.length - 1
+    if (lastIdx < 0) return false
+    const lastDecl = declarations[lastIdx]!
+    const closingIdx = lastDecl.lastIndexOf('  }')
+    if (closingIdx === -1) return false
+    declarations[lastIdx] =
+      lastDecl.slice(0, closingIdx) +
+      `    export type Errors = ${errorUnion}\n` +
+      lastDecl.slice(closingIdx)
+    return true
+  }
+  declarations.push(`export type ${routePascal}Errors = ${errorUnion}`)
+  return true
+}
+
 // ---------------------------------------------------------------------------
 // Route emitters
 // ---------------------------------------------------------------------------
@@ -192,7 +260,14 @@ async function emitRpcRoute(route: RPCHttpRouteDoc, ctx: EmitRouteContext): Prom
     `    },`,
   ].join('\n')
 
-  return { typeDeclarations: declarations, callable, hasStream: false }
+  const hasErrors = injectRouteErrors(
+    declarations,
+    pascal,
+    buildErrorUnion(route.errors, ctx),
+    ctx.namespaceTypes
+  )
+
+  return { typeDeclarations: declarations, callable, hasStream: false, hasErrors }
 }
 
 async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
@@ -262,7 +337,14 @@ async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Prom
     `    },`,
   ].join('\n')
 
-  return { typeDeclarations: declarations, callable, hasStream: false }
+  const hasErrors = injectRouteErrors(
+    declarations,
+    pascal,
+    buildErrorUnion(route.errors, ctx),
+    ctx.namespaceTypes
+  )
+
+  return { typeDeclarations: declarations, callable, hasStream: false, hasErrors }
 }
 
 async function emitStreamRoute(route: StreamHttpRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
@@ -300,7 +382,14 @@ async function emitStreamRoute(route: StreamHttpRouteDoc, ctx: EmitRouteContext)
     `    },`,
   ].join('\n')
 
-  return { typeDeclarations: declarations, callable, hasStream: true }
+  const hasErrors = injectRouteErrors(
+    declarations,
+    pascal,
+    buildErrorUnion(route.errors, ctx),
+    ctx.namespaceTypes
+  )
+
+  return { typeDeclarations: declarations, callable, hasStream: true, hasErrors }
 }
 
 // ---------------------------------------------------------------------------
@@ -318,14 +407,27 @@ export async function emitScopeFile(
   group: ScopeGroup,
   options?: EmitScopeOptions,
 ): Promise<string> {
-  const { ajsc: ajscOpts, clientImportPath = 'ts-procedures/client', namespaceTypes = false } = options ?? {}
+  const {
+    ajsc: ajscOpts,
+    clientImportPath = 'ts-procedures/client',
+    namespaceTypes = false,
+    serviceName = 'Api',
+    errorKeys,
+  } = options ?? {}
 
   const pascal = toPascalCase(group.camelCase)
-  const ctx: EmitRouteContext = { ajsc: ajscOpts, namespaceTypes, scopePascal: pascal }
+  const ctx: EmitRouteContext = {
+    ajsc: ajscOpts,
+    namespaceTypes,
+    scopePascal: pascal,
+    serviceName,
+    errorKeys,
+  }
 
   const allTypeDeclarations: string[] = []
   const callables: string[] = []
   let hasStream = false
+  let scopeHasErrors = false
 
   for (const route of group.routes) {
     let chunks: RouteChunks
@@ -351,13 +453,28 @@ export async function emitScopeFile(
     allTypeDeclarations.push(...chunks.typeDeclarations)
     callables.push(chunks.callable)
     if (chunks.hasStream) hasStream = true
+    if (chunks.hasErrors) scopeHasErrors = true
   }
 
-  // Build import line
+  // Build client import line
   const clientImports = hasStream
     ? `import type { ClientInstance, ProcedureCallOptions, TypedStream } from '${clientImportPath}'`
     : `import type { ClientInstance, ProcedureCallOptions } from '${clientImportPath}'`
 
+  // Build _errors import line when at least one route emits an Errors union.
+  // Namespace mode uses the qualified `${Service}Errors` namespace; flat mode
+  // pulls classes in via a wildcard alias (`_errors.UseCaseError`).
+  let errorsImport = ''
+  if (scopeHasErrors) {
+    if (namespaceTypes) {
+      errorsImport = `import type { ${toPascalCase(serviceName)}Errors } from './_errors'`
+    } else {
+      errorsImport = `import type * as _errors from './_errors'`
+    }
+  }
+
+  const importsBlock = [clientImports, errorsImport].filter(Boolean).join('\n')
+
   let typesBlock: string
   if (namespaceTypes && allTypeDeclarations.length > 0) {
     typesBlock = `export namespace ${pascal} {\n${allTypeDeclarations.join('\n\n')}\n}\n`
@@ -372,7 +489,7 @@ export async function emitScopeFile(
 
   return [
     CODEGEN_HEADER,
-    clientImports,
+    importsBlock,
     '',
     '// ── Types ────────────────────────────────────────',
     '',

package/src/codegen/pipeline.ts

@@ -43,6 +43,13 @@ export async function runPipeline(options: PipelineOptions): Promise<GeneratedFi
   const groups = groupRoutesByScope(envelope.routes)
   const groupArray = Array.from(groups.values())
 
+  // Error keys that will be emitted in `_errors.ts` — only those with a schema.
+  // Scope emit uses this to filter `route.errors` so generated code never
+  // references an undefined error type.
+  const errorKeys = new Set(
+    envelope.errors.filter((e) => e.schema != null).map((e) => e.name)
+  )
+
   if (selfContained) {
     for (const group of groupArray) {
       if (group.scopeKey === '_types' || group.scopeKey === '_client') {
@@ -56,7 +63,13 @@ export async function runPipeline(options: PipelineOptions): Promise<GeneratedFi
   const files: GeneratedFile[] = []
 
   for (const group of groupArray) {
-    const rawCode = await emitScopeFile(group, { ajsc: ajscOpts, clientImportPath, namespaceTypes })
+    const rawCode = await emitScopeFile(group, {
+      ajsc: ajscOpts,
+      clientImportPath,
+      namespaceTypes,
+      serviceName,
+      errorKeys: errorKeys.size > 0 ? errorKeys : undefined,
+    })
     const lines = rawCode.split('\n')
     lines.splice(1, 0, hashComment)
     const code = lines.join('\n')
@@ -72,7 +85,17 @@ export async function runPipeline(options: PipelineOptions): Promise<GeneratedFi
     files.push({ path: join(outDir, '_errors.ts'), code: errorsWithHash })
   }
 
-  const rawIndexCode = emitIndexFile(groupArray, { clientImportPath, hasErrors, namespaceTypes, serviceName })
+  // In self-contained mode types come from `./_types` but the runtime
+  // (`createClient`) lives in `./_client`. In regular mode both share the
+  // single `clientImportPath` (e.g. `ts-procedures/client`).
+  const clientRuntimeImportPath = selfContained ? './_client' : clientImportPath
+  const rawIndexCode = emitIndexFile(groupArray, {
+    clientImportPath,
+    clientRuntimeImportPath,
+    hasErrors,
+    namespaceTypes,
+    serviceName,
+  })
   const indexLines = rawIndexCode.split('\n')
   indexLines.splice(1, 0, hashComment)
   const indexCode = indexLines.join('\n')

package/src/implementations/http/README.md

@@ -118,6 +118,12 @@ All HTTP implementations automatically inject an `AbortSignal` into the handler
 
 For streaming procedures, `signal.reason` is `'stream-completed'` on normal completion, allowing handlers to distinguish from client disconnection.
 
+### Error Handling
+
+All four builders support two peer error-handling modes — **declarative** (`errors` taxonomy + `unknownError`) and **imperative** (`onError` callback) — plus a cross-cutting `onRequestError` observer for logging, tracing, and metrics.
+
+Full spec (taxonomy shape, `toResponse`/`onCatch`/`match`, per-route narrowing, mid-stream caveats): **[docs/http-integrations.md § Error Handling](../../../docs/http-integrations.md#error-handling)**.
+
 ### Lifecycle Hooks
 
 **RPC Implementations:**
@@ -152,7 +158,8 @@ onRequestStart → onStreamStart → [yields...] → onStreamEnd → onRequestEn
 | `onError` | RPC, API | On handler error |
 | `onStreamStart` | Stream | Before first yield |
 | `onStreamEnd` | Stream | After stream completes |
-| `onPreStreamError` | Stream | On pre-stream error (validation, auth) |
+| `onError` (HonoStream) | Stream | Imperative pre-stream error callback — peer of `errors` taxonomy |
+| `onRequestError` | All | Cross-cutting observer — fires for every caught error before dispatch |
 | `onMidStreamError` | Stream | On mid-stream error (generator throws) |
 
 ### Route Documentation
@@ -225,7 +232,7 @@ const app = builder.build()
 const docs = builder.docs
 ```
 
-**Note:** `HonoAPIAppBuilder.build()` is async (resolves query parser on first call).
+All four builders' `build()` methods are synchronous — they return the framework app instance directly. Don't `await` the call.
 
 **Key methods:**
 
@@ -250,8 +257,7 @@ import { DocRegistry } from 'ts-procedures/http-docs'
 
 const docs = new DocRegistry({
   basePath: '/api',
-  headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
-  errors: DocRegistry.defaultErrors(),
+  errors: appErrors,  // your ErrorTaxonomy — framework defaults auto-merged and deduped
 })
   .from(rpcBuilder)
   .from(apiBuilder)
@@ -262,7 +268,7 @@ app.get('/docs', (c) => c.json(docs.toJSON()))
 
 - `from()` stores a reference — routes are read lazily at `toJSON()` time
 - `toJSON()` supports optional `filter` and `transform` options
-- `defaultErrors()` returns error schemas for all 4 procedure error types
+- `errors` accepts an `ErrorTaxonomy` or raw `ErrorDoc[]`; framework defaults are auto-merged (opt out via `includeDefaults: false`)
 - All builders satisfy the `DocSource` interface (`{ readonly docs: AnyHttpRouteDoc[] }`)
 
 ### Client Code Generation
@@ -314,8 +320,16 @@ apiBuilder.register(factory, (c) => ctx, {
 ## TypeScript Types
 
 ```typescript
-import { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode } from 'ts-procedures/implementations/types'
-import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/http'
+import type {
+  RPCConfig,
+  RPCHttpRouteDoc,
+  StreamHttpRouteDoc,
+  StreamMode,
+  APIConfig,
+  APIHttpRouteDoc,
+  APIInput,
+  HttpMethod,
+} from 'ts-procedures/http'
 
 // Client Runtime
 import { createClient, createFetchAdapter } from 'ts-procedures/client'