ts-procedures 5.15.0 → 6.0.0

package/agent_config/claude-code/skills/ts-procedures-scaffold/templates/hono-rpc.md

@@ -3,8 +3,8 @@
 ## Implementation — `{{Name}}.rpc.ts`
 
 ```typescript
-import { Procedures, ProcedureError, ProcedureValidationError } from 'ts-procedures'
-import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+import { Procedures } from 'ts-procedures'
+import { HonoRPCAppBuilder, defineErrorTaxonomy } from 'ts-procedures/hono-rpc'
 import type { RPCConfig } from 'ts-procedures/http'
 import { Type } from 'typebox'
 
@@ -60,25 +60,28 @@ export const { ListItems } = RPC.Create(
   }
 )
 
+// ─── Error Taxonomy ───────────────────────────────────────
+// Declare the error classes this service throws. Framework errors
+// (ProcedureValidationError → 400, ctx.error() → 500) are caught by the
+// default taxonomy automatically. Add your own classes here — handlers just
+// `throw` them and the builder serializes via this map. See
+// docs/http-integrations.md#error-handling for the full contract.
+
+const {{name}}Errors = defineErrorTaxonomy({
+  // Example — replace with your app's error classes:
+  // NotFoundError: { class: NotFoundError, statusCode: 404 },
+  // AuthError:     { class: AuthError,     statusCode: 401 },
+})
+
 // ─── Hono App Builder ─────────────────────────────────────
 
 export const {{name}}App = new HonoRPCAppBuilder({
   pathPrefix: '/api',
-  onError: (procedure, c, error) => {
-    if (error instanceof ProcedureValidationError) {
-      return c.json({
-        error: error.message,
-        details: error.errors,
-        procedure: error.procedureName,
-      }, 400)
-    } else if (error instanceof ProcedureError) {
-      return c.json({
-        error: error.message,
-        meta: error.meta,
-        procedure: error.procedureName,
-      }, 422)
-    }
-    return c.json({ error: 'Internal server error' }, 500)
+  errors: {{name}}Errors,
+  unknownError: {
+    statusCode: 500,
+    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
+    onCatch: (err, { procedure }) => console.error(`[${procedure.name}]`, err),
   },
 })
   .register(RPC, (c) => ({

package/agent_config/claude-code/skills/ts-procedures-scaffold/templates/hono-stream.md

@@ -4,7 +4,7 @@
 
 ```typescript
 import { Procedures } from 'ts-procedures'
-import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+import { HonoStreamAppBuilder, sse, defineErrorTaxonomy } from 'ts-procedures/hono-stream'
 import type { RPCConfig } from 'ts-procedures/http'
 import { Type } from 'typebox'
 
@@ -60,13 +60,26 @@ async function pollForEvents(channel: string, opts?: { signal?: AbortSignal }) {
   return { type: 'update', data: { value: Math.random() } }
 }
 
+// ─── Error Taxonomy (pre-stream) ──────────────────────────
+// Pre-stream errors (validation, context resolution) flow through the
+// taxonomy — framework errors are caught by the default taxonomy automatically.
+// Mid-stream errors (thrown after the first yield) still go through
+// onMidStreamError since the HTTP status is already committed.
+
+const {{name}}Errors = defineErrorTaxonomy({
+  // Example — replace with your app's error classes:
+  // AuthError: { class: AuthError, statusCode: 401 },
+})
+
 // ─── Hono Stream App Builder ──────────────────────────────
 
 export const {{name}}StreamApp = new HonoStreamAppBuilder({
   pathPrefix: '/api',
   defaultStreamMode: 'sse',  // or 'text' for newline-delimited JSON
-  onPreStreamError: (procedure, c, error) => {
-    return c.json({ error: error.message }, 400)
+  errors: {{name}}Errors,
+  unknownError: {
+    statusCode: 500,
+    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
   },
   onMidStreamError: (procedure, c, error) => ({
     data: { type: 'error', payload: { message: error.message }, timestamp: Date.now() },

package/agent_config/copilot/copilot-instructions.md

@@ -196,24 +196,89 @@ const app = new HonoAPIAppBuilder({ pathPrefix: '/api' })
 
 | Error Class | Trigger | HTTP Status |
 |-------------|---------|-------------|
-| `ProcedureValidationError` | Schema params validation failure | 400 |
-| `ProcedureError` | `ctx.error()` or unhandled handler exception | 422/500 |
+| `ProcedureValidationError` | Schema params validation failure | 400 (auto — default taxonomy) |
+| `ProcedureError` | `ctx.error()` or unhandled handler exception | 500 (auto — default taxonomy) |
 | `ProcedureYieldValidationError` | Yield validation failure (validateYields: true) | N/A (mid-stream) |
 | `ProcedureRegistrationError` | Invalid schema or duplicate name at registration | N/A (startup) |
 
+### Error Taxonomy (required for custom errors)
+
+`defineErrorTaxonomy` maps error classes to HTTP responses declaratively. Works with every HTTP builder (`hono-api`, `hono-rpc`, `express-rpc`, `hono-stream` pre-stream).
+
+Do NOT write `onError` `instanceof` ladders — that's anti-pattern #20. Use the taxonomy instead:
+
 ```typescript
-// In HTTP builder
-onError: (procedure, req, res, error) => {
-  if (error instanceof ProcedureValidationError) {
-    res.status(400).json({ error: error.message, details: error.errors })
-  } else if (error instanceof ProcedureError) {
-    res.status(422).json({ error: error.message, meta: error.meta })
-  } else {
-    res.status(500).json({ error: 'Internal server error' })
+import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
+
+class UseCaseError extends Error {
+  constructor(readonly externalMsg: string, readonly internalMsg: string) {
+    super(externalMsg); this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
   }
 }
+
+const appErrors = defineErrorTaxonomy({
+  // First-match wins — declare subclasses before base classes
+  UseCaseError: {
+    class: UseCaseError,
+    statusCode: 422,
+    toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+    onCatch: (err) => logger.error(err.internalMsg), // internal logs only
+  },
+  MongoDuplicateKey: {
+    match: (err): err is Error => err instanceof Error && (err as any).code === 11000,
+    statusCode: 409,
+    toResponse: () => ({ name: 'Conflict', message: 'Resource already exists' }),
+  },
+})
+
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  unknownError: { statusCode: 500, toResponse: () => ({ name: 'InternalServerError' }) },
+})
 ```
 
+Handlers throw the error classes directly — the builder auto-serializes. `onError` is the first-class imperative peer when you want to handle errors in one callback instead (both modes coexist). In v6 `HonoStreamAppBuilder.onPreStreamError` was renamed to `onError`. Cross-cutting `onRequestError` observer fires for every caught error.
+
+### Per-route errors (typed)
+
+`APIConfig` and `RPCConfig` are generic over `TErrorKey extends string = string`. Narrow to your taxonomy for compile-time typo protection and route-level error doc entries:
+
+```typescript
+import { APIConfig } from 'ts-procedures/http'
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+type MyAPIConfig = APIConfig<keyof typeof appErrors & string>
+const API = Procedures<Ctx, MyAPIConfig>()
+
+API.Create('GetUser', { path: '/users/:id', method: 'get', errors: ['UseCaseError'], /* ... */ }, ...)
+
+// Seed envelope errors from the taxonomy + framework defaults in one call
+const envelope = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' }).from(apiApp).toJSON()
+```
+
+### Client-side typed catch blocks (via codegen)
+
+The generated `_errors.ts` emits real runtime classes extending a shared `${Service}ProcedureError` base. The generated `createApiClient` wires an error registry so non-2xx responses arrive as typed class instances:
+
+```typescript
+import { createApiClient, ApiErrors, createFetchAdapter } from './generated'
+
+const api = createApiClient({ adapter: createFetchAdapter({ /* ... */ }), basePath: '...' })
+
+try {
+  await api.users.getUser({ pathParams: { id: 'x' } })
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // err.body typed; err.status, err.procedureName, err.scope available
+  } else if (err instanceof ApiErrors.ApiProcedureError) {
+    // Catch-all for any service error
+  }
+}
+```
+
+Per-route error unions: routes with `errors: [...]` get an `Errors` type in their namespace (e.g. `Users.GetUser.Errors = ApiErrors.UseCaseError | ApiErrors.AuthError`).
+
 ## Lifecycle Hook Order
 
 ### Standard RPC
@@ -225,7 +290,7 @@ onRequestStart → factoryContext() → handler() → onSuccess → onRequestEnd
 ### Streaming
 ```
 onRequestStart → factoryContext() → validation → onStreamStart → handler yields → onStreamEnd → onRequestEnd
-                                               → onPreStreamError → onRequestEnd
+                                               → onError (or taxonomy) → onRequestEnd
                                                                   → onMidStreamError → onStreamEnd → onRequestEnd
 ```
 
@@ -320,7 +385,7 @@ npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated
 #                  --clean-out-dir   # recursively wipe --out before writing (prunes stale scope files)
 ```
 
-Generates one `.ts` file per scope plus a root `index.ts` that imports each scope as a namespace and exports a `create${ServiceName}Bindings` factory (defaults to `createApiBindings`; pass `--service-name <Name>` to rename). When namespace mode is on (the default), `index.ts` also wraps every scope namespace in an outer `export namespace ${ServiceName} { ... }` block so types are reachable as `Api.Users.GetUser.Params`, `Api.Errors.ProcedureError`, etc. The errors file (`_errors.ts`) emits `${ServiceName}Errors` and `${ServiceName}ProcedureErrorUnion` (defaults: `ApiErrors`, `ApiProcedureErrorUnion`).
+Generates one `.ts` file per scope plus a root `index.ts` that imports each scope as a namespace and exports a `create${ServiceName}Bindings(client)` factory AND a `create${ServiceName}Client(config)` convenience factory that pre-wires the error registry (defaults to `createApiBindings` / `createApiClient`; pass `--service-name <Name>` to rename). When namespace mode is on (the default), `index.ts` also wraps every scope namespace in an outer `export namespace ${ServiceName} { ... }` block so types are reachable as `Api.Users.GetUser.Params`, `Api.Errors.UseCaseError`, etc. The errors file (`_errors.ts`) emits runtime error classes extending a shared `${ServiceName}ProcedureError` base, each with `static fromResponse(body, meta)`, plus `${ServiceName}ErrorRegistry` (runtime dispatch map) and `${ServiceName}ProcedureErrorUnion` (type union). Defaults: `ApiErrors`, `ApiProcedureError`, `ApiErrorRegistry`, `ApiProcedureErrorUnion`.
 By default, types are wrapped in nested TS namespaces (`Scope.Route.Params`), JSDoc comments are emitted, and output is self-contained (no runtime dependency on `ts-procedures`). Use `--no-namespace-types` to revert to flat type names (`RouteParams`); this also disables the outer service namespace in `index.ts` and skips importing `_errors` from there.
 Note: ajsc formatting options (`--enum-style enum`, `--depluralize`, etc.) only take effect in namespace mode (the default). They are ignored with `--no-namespace-types`.
 Supports config file: `ts-procedures-codegen.config.json` (auto-loaded from CWD) or `--config <path>`.
@@ -336,6 +401,7 @@ const client = createClient({
   adapter: createFetchAdapter(),
   basePath: 'http://localhost:3000',
   scopes: createApiBindings,
+  defaults: { timeout: 30_000, headers: { 'X-Client-Version': '1.0.0' } },
   hooks: {
     onBeforeRequest(ctx) {
       ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
@@ -350,20 +416,67 @@ const client = createClient({
 // Fully typed — params and response inferred from server schemas; type aliases live under Api.<Scope>.<Route>.
 const user = await client.users.GetUser({ pathParams: { id: '123' } })
 
-// Per-call hook override
-await client.users.GetUser({ pathParams: { id: '123' } }, {
-  onAfterResponse(ctx) {
-    console.log(ctx.response.headers['x-rate-limit-remaining'])
+// Per-call options — timeout, signal, headers, basePath, and hooks all share one bag
+await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  {
+    timeout: 5000,
+    headers: { 'X-Request-Id': crypto.randomUUID() },
+    onAfterResponse(ctx) {
+      console.log(ctx.response.headers['x-rate-limit-remaining'])
+    },
   },
-})
+)
+```
+
+### Per-Call Options & Defaults
+
+```typescript
+interface ProcedureCallDefaults {
+  signal?: AbortSignal      // cancellation (combined with per-call via AbortSignal.any)
+  timeout?: number          // ms — per-call timeout:0 disables inherited default
+  headers?: Record<string, string>  // merged, per-call keys win
+  basePath?: string         // per-call > default > config.basePath
+  meta?: RequestMeta        // typed per-request metadata (declaration-mergeable)
+}
+
+interface ProcedureCallOptions extends ProcedureCallDefaults, ClientHooks {}
+```
+
+- Defaults are set via `config.defaults`; per-call options are passed as the 2nd argument to any generated callable.
+- Header precedence (low → high): adapter config < `defaults.headers` < per-call `headers` < route-declared `schema.input.headers` < `onBeforeRequest` mutations.
+
+### Typed RequestMeta (Declaration Merging)
+
+Augment `RequestMeta` to type `meta` end-to-end (options, hooks, adapter):
+
+```typescript
+// For code-generated self-contained clients
+declare module './generated/_types' {
+  interface RequestMeta {
+    traceId: string
+    priority?: 'high' | 'low'
+  }
+}
+
+// Or for direct ts-procedures/client usage
+declare module 'ts-procedures/client' {
+  interface RequestMeta { traceId: string }
+}
+
+await client.users.GetUser(
+  { pathParams: { id: '1' } },
+  { meta: { traceId: 'req-abc', priority: 'high' } },  // fully typed
+)
 ```
 
 ### Hook Types
 
 ```typescript
 interface ClientHooks {
-  onBeforeRequest?: (ctx: { request: ClientRequest }) => { request: ClientRequest } | void
-  onAfterResponse?: (ctx: { request: ClientRequest; response: ClientResponse }) => void
+  onBeforeRequest?: (ctx: BeforeRequestContext) => BeforeRequestContext | Promise<BeforeRequestContext>
+  onAfterResponse?: (ctx: AfterResponseContext) => void | Promise<void>
+  onError?: (ctx: ErrorContext) => void | Promise<void>
 }
 ```
 

package/agent_config/cursor/cursorrules

@@ -196,24 +196,89 @@ const app = new HonoAPIAppBuilder({ pathPrefix: '/api' })
 
 | Error Class | Trigger | HTTP Status |
 |-------------|---------|-------------|
-| `ProcedureValidationError` | Schema params validation failure | 400 |
-| `ProcedureError` | `ctx.error()` or unhandled handler exception | 422/500 |
+| `ProcedureValidationError` | Schema params validation failure | 400 (auto — default taxonomy) |
+| `ProcedureError` | `ctx.error()` or unhandled handler exception | 500 (auto — default taxonomy) |
 | `ProcedureYieldValidationError` | Yield validation failure (validateYields: true) | N/A (mid-stream) |
 | `ProcedureRegistrationError` | Invalid schema or duplicate name at registration | N/A (startup) |
 
+### Error Taxonomy (required for custom errors)
+
+`defineErrorTaxonomy` maps error classes to HTTP responses declaratively. Works with every HTTP builder (`hono-api`, `hono-rpc`, `express-rpc`, `hono-stream` pre-stream).
+
+Do NOT write `onError` `instanceof` ladders — that's anti-pattern #20. Use the taxonomy instead:
+
 ```typescript
-// In HTTP builder
-onError: (procedure, req, res, error) => {
-  if (error instanceof ProcedureValidationError) {
-    res.status(400).json({ error: error.message, details: error.errors })
-  } else if (error instanceof ProcedureError) {
-    res.status(422).json({ error: error.message, meta: error.meta })
-  } else {
-    res.status(500).json({ error: 'Internal server error' })
+import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
+
+class UseCaseError extends Error {
+  constructor(readonly externalMsg: string, readonly internalMsg: string) {
+    super(externalMsg); this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
   }
 }
+
+const appErrors = defineErrorTaxonomy({
+  // First-match wins — declare subclasses before base classes
+  UseCaseError: {
+    class: UseCaseError,
+    statusCode: 422,
+    toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+    onCatch: (err) => logger.error(err.internalMsg), // internal logs only
+  },
+  MongoDuplicateKey: {
+    match: (err): err is Error => err instanceof Error && (err as any).code === 11000,
+    statusCode: 409,
+    toResponse: () => ({ name: 'Conflict', message: 'Resource already exists' }),
+  },
+})
+
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  unknownError: { statusCode: 500, toResponse: () => ({ name: 'InternalServerError' }) },
+})
 ```
 
+Handlers throw the error classes directly — the builder auto-serializes. `onError` is the first-class imperative peer when you want to handle errors in one callback instead (both modes coexist). In v6 `HonoStreamAppBuilder.onPreStreamError` was renamed to `onError`. Cross-cutting `onRequestError` observer fires for every caught error.
+
+### Per-route errors (typed)
+
+`APIConfig` and `RPCConfig` are generic over `TErrorKey extends string = string`. Narrow to your taxonomy for compile-time typo protection and route-level error doc entries:
+
+```typescript
+import { APIConfig } from 'ts-procedures/http'
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+type MyAPIConfig = APIConfig<keyof typeof appErrors & string>
+const API = Procedures<Ctx, MyAPIConfig>()
+
+API.Create('GetUser', { path: '/users/:id', method: 'get', errors: ['UseCaseError'], /* ... */ }, ...)
+
+// Seed envelope errors from the taxonomy + framework defaults in one call
+const envelope = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' }).from(apiApp).toJSON()
+```
+
+### Client-side typed catch blocks (via codegen)
+
+The generated `_errors.ts` emits real runtime classes extending a shared `${Service}ProcedureError` base. The generated `createApiClient` wires an error registry so non-2xx responses arrive as typed class instances:
+
+```typescript
+import { createApiClient, ApiErrors, createFetchAdapter } from './generated'
+
+const api = createApiClient({ adapter: createFetchAdapter({ /* ... */ }), basePath: '...' })
+
+try {
+  await api.users.getUser({ pathParams: { id: 'x' } })
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // err.body typed; err.status, err.procedureName, err.scope available
+  } else if (err instanceof ApiErrors.ApiProcedureError) {
+    // Catch-all for any service error
+  }
+}
+```
+
+Per-route error unions: routes with `errors: [...]` get an `Errors` type in their namespace (e.g. `Users.GetUser.Errors = ApiErrors.UseCaseError | ApiErrors.AuthError`).
+
 ## Lifecycle Hook Order
 
 ### Standard RPC
@@ -225,7 +290,7 @@ onRequestStart → factoryContext() → handler() → onSuccess → onRequestEnd
 ### Streaming
 ```
 onRequestStart → factoryContext() → validation → onStreamStart → handler yields → onStreamEnd → onRequestEnd
-                                               → onPreStreamError → onRequestEnd
+                                               → onError (or taxonomy) → onRequestEnd
                                                                   → onMidStreamError → onStreamEnd → onRequestEnd
 ```
 
@@ -320,7 +385,7 @@ npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated
 #                  --clean-out-dir   # recursively wipe --out before writing (prunes stale scope files)
 ```
 
-Generates one `.ts` file per scope plus a root `index.ts` that imports each scope as a namespace and exports a `create${ServiceName}Bindings` factory (defaults to `createApiBindings`; pass `--service-name <Name>` to rename). When namespace mode is on (the default), `index.ts` also wraps every scope namespace in an outer `export namespace ${ServiceName} { ... }` block so types are reachable as `Api.Users.GetUser.Params`, `Api.Errors.ProcedureError`, etc. The errors file (`_errors.ts`) emits `${ServiceName}Errors` and `${ServiceName}ProcedureErrorUnion` (defaults: `ApiErrors`, `ApiProcedureErrorUnion`).
+Generates one `.ts` file per scope plus a root `index.ts` that imports each scope as a namespace and exports a `create${ServiceName}Bindings(client)` factory AND a `create${ServiceName}Client(config)` convenience factory that pre-wires the error registry (defaults to `createApiBindings` / `createApiClient`; pass `--service-name <Name>` to rename). When namespace mode is on (the default), `index.ts` also wraps every scope namespace in an outer `export namespace ${ServiceName} { ... }` block so types are reachable as `Api.Users.GetUser.Params`, `Api.Errors.UseCaseError`, etc. The errors file (`_errors.ts`) emits runtime error classes extending a shared `${ServiceName}ProcedureError` base, each with `static fromResponse(body, meta)`, plus `${ServiceName}ErrorRegistry` (runtime dispatch map) and `${ServiceName}ProcedureErrorUnion` (type union). Defaults: `ApiErrors`, `ApiProcedureError`, `ApiErrorRegistry`, `ApiProcedureErrorUnion`.
 By default, types are wrapped in nested TS namespaces (`Scope.Route.Params`), JSDoc comments are emitted, and output is self-contained (no runtime dependency on `ts-procedures`). Use `--no-namespace-types` to revert to flat type names (`RouteParams`); this also disables the outer service namespace in `index.ts` and skips importing `_errors` from there.
 Note: ajsc formatting options (`--enum-style enum`, `--depluralize`, etc.) only take effect in namespace mode (the default). They are ignored with `--no-namespace-types`.
 Supports config file: `ts-procedures-codegen.config.json` (auto-loaded from CWD) or `--config <path>`.
@@ -336,6 +401,7 @@ const client = createClient({
   adapter: createFetchAdapter(),
   basePath: 'http://localhost:3000',
   scopes: createApiBindings,
+  defaults: { timeout: 30_000, headers: { 'X-Client-Version': '1.0.0' } },
   hooks: {
     onBeforeRequest(ctx) {
       ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
@@ -350,20 +416,67 @@ const client = createClient({
 // Fully typed — params and response inferred from server schemas; type aliases live under Api.<Scope>.<Route>.
 const user = await client.users.GetUser({ pathParams: { id: '123' } })
 
-// Per-call hook override
-await client.users.GetUser({ pathParams: { id: '123' } }, {
-  onAfterResponse(ctx) {
-    console.log(ctx.response.headers['x-rate-limit-remaining'])
+// Per-call options — timeout, signal, headers, basePath, and hooks all share one bag
+await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  {
+    timeout: 5000,
+    headers: { 'X-Request-Id': crypto.randomUUID() },
+    onAfterResponse(ctx) {
+      console.log(ctx.response.headers['x-rate-limit-remaining'])
+    },
   },
-})
+)
+```
+
+### Per-Call Options & Defaults
+
+```typescript
+interface ProcedureCallDefaults {
+  signal?: AbortSignal      // cancellation (combined with per-call via AbortSignal.any)
+  timeout?: number          // ms — per-call timeout:0 disables inherited default
+  headers?: Record<string, string>  // merged, per-call keys win
+  basePath?: string         // per-call > default > config.basePath
+  meta?: RequestMeta        // typed per-request metadata (declaration-mergeable)
+}
+
+interface ProcedureCallOptions extends ProcedureCallDefaults, ClientHooks {}
+```
+
+- Defaults are set via `config.defaults`; per-call options are passed as the 2nd argument to any generated callable.
+- Header precedence (low → high): adapter config < `defaults.headers` < per-call `headers` < route-declared `schema.input.headers` < `onBeforeRequest` mutations.
+
+### Typed RequestMeta (Declaration Merging)
+
+Augment `RequestMeta` to type `meta` end-to-end (options, hooks, adapter):
+
+```typescript
+// For code-generated self-contained clients
+declare module './generated/_types' {
+  interface RequestMeta {
+    traceId: string
+    priority?: 'high' | 'low'
+  }
+}
+
+// Or for direct ts-procedures/client usage
+declare module 'ts-procedures/client' {
+  interface RequestMeta { traceId: string }
+}
+
+await client.users.GetUser(
+  { pathParams: { id: '1' } },
+  { meta: { traceId: 'req-abc', priority: 'high' } },  // fully typed
+)
 ```
 
 ### Hook Types
 
 ```typescript
 interface ClientHooks {
-  onBeforeRequest?: (ctx: { request: ClientRequest }) => { request: ClientRequest } | void
-  onAfterResponse?: (ctx: { request: ClientRequest; response: ClientResponse }) => void
+  onBeforeRequest?: (ctx: BeforeRequestContext) => BeforeRequestContext | Promise<BeforeRequestContext>
+  onAfterResponse?: (ctx: AfterResponseContext) => void | Promise<void>
+  onError?: (ctx: ErrorContext) => void | Promise<void>
 }
 ```
 

package/build/client/call.d.ts

@@ -1,14 +1,24 @@
-import type { ClientAdapter, ClientHooks, CallDescriptor } from './types.js';
+import type { ClientAdapter, ClientHooks, CallDescriptor, ErrorRegistry, ProcedureCallDefaults, ProcedureCallOptions } from './types.js';
+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. Build AdapterRequest from descriptor
- * 2. Run onBeforeRequest hooks (global then local)
- * 3. Call adapter.request()
- * 4. On adapter error: run onError hooks, re-throw
- * 5. Run onAfterResponse hooks (hooks may mutate response.status)
- * 6. If response status is non-2xx: throw ClientRequestError
- * 7. Return response.body as TResponse
+ * 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 ClientRequestError
+ * 8. Return response.body as TResponse
  */
-export declare function executeCall<TResponse>(descriptor: CallDescriptor, basePath: string, adapter: ClientAdapter, globalHooks: ClientHooks, localHooks: ClientHooks | undefined): Promise<TResponse>;
+export declare function executeCall<TResponse>(config: ExecuteCallConfig): Promise<TResponse>;

package/build/client/call.js

@@ -1,38 +1,52 @@
 import { buildAdapterRequest } from './request-builder.js';
 import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js';
+import { applyRequestOptions, resolveBasePath } from './resolve-options.js';
 import { ClientRequestError } from './errors.js';
+import { dispatchTypedError } from './error-dispatch.js';
 /**
  * Executes a single procedure call through the adapter.
  *
  * Flow:
- * 1. Build AdapterRequest from descriptor
- * 2. Run onBeforeRequest hooks (global then local)
- * 3. Call adapter.request()
- * 4. On adapter error: run onError hooks, re-throw
- * 5. Run onAfterResponse hooks (hooks may mutate response.status)
- * 6. If response status is non-2xx: throw ClientRequestError
- * 7. Return response.body as TResponse
+ * 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 ClientRequestError
+ * 8. Return response.body as TResponse
  */
-export async function executeCall(descriptor, basePath, adapter, globalHooks, localHooks) {
-    // 1. Build the initial request
-    let request = buildAdapterRequest(descriptor, basePath);
-    // 2. Run before-request hooks — they may mutate the request
-    const beforeCtx = await runBeforeRequest({ procedureName: descriptor.name, scope: descriptor.scope, request }, globalHooks, localHooks);
+export async function executeCall(config) {
+    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)
+    request = applyRequestOptions(request, defaults, options);
+    // 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;
-    // 3. Call the adapter
+    // 4. Call the adapter
     let response;
     try {
         response = await adapter.request(request);
     }
     catch (err) {
-        // 4. On adapter error: run error hooks, re-throw
-        await runOnError({ procedureName: descriptor.name, scope: descriptor.scope, request, error: err }, globalHooks, localHooks);
+        // 5. On adapter error: run error hooks, re-throw
+        await runOnError({ procedureName: descriptor.name, scope: descriptor.scope, request, error: err }, hooks, options);
         throw err;
     }
-    // 5. Run after-response hooks — they may mutate response.status to swallow errors
-    await runAfterResponse({ procedureName: descriptor.name, scope: descriptor.scope, request, response }, globalHooks, localHooks);
-    // 6. Check status AFTER hooks (hooks may have swallowed the error by mutating status)
+    // 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)
+            throw typed;
         throw new ClientRequestError({
             status: response.status,
             headers: response.headers,
@@ -41,7 +55,7 @@ export async function executeCall(descriptor, basePath, adapter, globalHooks, lo
             scope: descriptor.scope,
         });
     }
-    // 7. Return the body
+    // 8. Return the body
     return response.body;
 }
 //# sourceMappingURL=call.js.map

package/build/client/call.js.map

@@ -1 +1 @@
-{"version":3,"file":"call.js","sourceRoot":"","sources":["../../src/client/call.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAOhD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,UAA0B,EAC1B,QAAgB,EAChB,OAAsB,EACtB,WAAwB,EACxB,UAAmC;IAEnC,+BAA+B;IAC/B,IAAI,OAAO,GAAG,mBAAmB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;IAEvD,4DAA4D;IAC5D,MAAM,SAAS,GAAG,MAAM,gBAAgB,CACtC,EAAE,aAAa,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,EACpE,WAAW,EACX,UAAU,CACX,CAAA;IACD,OAAO,GAAG,SAAS,CAAC,OAAO,CAAA;IAE3B,sBAAsB;IACtB,IAAI,QAAQ,CAAA;IACZ,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,iDAAiD;QACjD,MAAM,UAAU,CACd,EAAE,aAAa,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAChF,WAAW,EACX,UAAU,CACX,CAAA;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IAED,kFAAkF;IAClF,MAAM,gBAAgB,CACpB,EAAE,aAAa,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAC9E,WAAW,EACX,UAAU,CACX,CAAA;IAED,sFAAsF;IACtF,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QACpD,MAAM,IAAI,kBAAkB,CAAC;YAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,aAAa,EAAE,UAAU,CAAC,IAAI;YAC9B,KAAK,EAAE,UAAU,CAAC,KAAK;SACxB,CAAC,CAAA;IACJ,CAAC;IAED,qBAAqB;IACrB,OAAO,QAAQ,CAAC,IAAiB,CAAA;AACnC,CAAC"}
+{"version":3,"file":"call.js","sourceRoot":"","sources":["../../src/client/call.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC3E,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAoBxD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAY,MAAyB;IACpE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAAA;IAEzF,iEAAiE;IACjE,MAAM,gBAAgB,GAAG,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;IACrE,IAAI,OAAO,GAAG,mBAAmB,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAA;IAE/D,kEAAkE;IAClE,OAAO,GAAG,mBAAmB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;IAEzD,oEAAoE;IACpE,MAAM,SAAS,GAAG,MAAM,gBAAgB,CACtC,EAAE,aAAa,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,EACpE,KAAK,EACL,OAAO,CACR,CAAA;IACD,OAAO,GAAG,SAAS,CAAC,OAAO,CAAA;IAE3B,sBAAsB;IACtB,IAAI,QAAQ,CAAA;IACZ,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,iDAAiD;QACjD,MAAM,UAAU,CACd,EAAE,aAAa,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAChF,KAAK,EACL,OAAO,CACR,CAAA;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IAED,kFAAkF;IAClF,MAAM,gBAAgB,CACpB,EAAE,aAAa,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAC9E,KAAK,EACL,OAAO,CACR,CAAA;IAED,sFAAsF;IACtF,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,kBAAkB,CAAC,aAAa,EAAE,QAAQ,CAAC,IAAI,EAAE;YAC7D,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,aAAa,EAAE,UAAU,CAAC,IAAI;YAC9B,KAAK,EAAE,UAAU,CAAC,KAAK;SACxB,CAAC,CAAA;QACF,IAAI,KAAK;YAAE,MAAM,KAAK,CAAA;QACtB,MAAM,IAAI,kBAAkB,CAAC;YAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,aAAa,EAAE,UAAU,CAAC,IAAI;YAC9B,KAAK,EAAE,UAAU,CAAC,KAAK;SACxB,CAAC,CAAA;IACJ,CAAC;IAED,qBAAqB;IACrB,OAAO,QAAQ,CAAC,IAAiB,CAAA;AACnC,CAAC"}