ts-procedures 5.15.0 → 6.0.0

package/docs/http-integrations.md

@@ -13,7 +13,7 @@ For a full cross-framework comparison (config interfaces, path generation, conte
 | Express RPC | `ts-procedures/express-rpc` | RPC (POST routes) | [README](../src/implementations/http/express-rpc/README.md) |
 | Hono RPC | `ts-procedures/hono-rpc` | RPC (POST routes) | [README](../src/implementations/http/hono-rpc/README.md) |
 | Hono Stream | `ts-procedures/hono-stream` | SSE/text streaming | [README](../src/implementations/http/hono-stream/README.md) |
-| Hono API | `ts-procedures/hono-api` | REST (method-based) | [Below](#hono-api-integration) |
+| Hono API | `ts-procedures/hono-api` | REST (method-based) | [README](../src/implementations/http/hono-api/README.md) |
 
 ## Express RPC
 
@@ -27,7 +27,7 @@ const RPC = Procedures<AppContext, RPCConfig>()
 RPC.Create(
   'GetUser',
   {
-    name: ['users', 'get'],
+    scope: ['users', 'get'],
     version: 1,
     schema: {
       params: Type.Object({ id: Type.String() }),
@@ -44,7 +44,7 @@ const app = new ExpressRPCAppBuilder()
   .build()
 
 app.listen(3000)
-// Route created: POST /rpc/users/get/1
+// Route created: POST /users/get/get-user/1
 ```
 
 See the [Express RPC Integration Guide](../src/implementations/http/express-rpc/README.md) for complete setup including lifecycle hooks, error handling, and route documentation.
@@ -139,7 +139,7 @@ API.Create('CreateUser', {
   return await createUser(body)
 })
 
-const app = await new HonoAPIAppBuilder({ pathPrefix: '/api' })
+const app = new HonoAPIAppBuilder({ pathPrefix: '/api' })
   .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
   .build()
 
@@ -148,6 +148,129 @@ const app = await new HonoAPIAppBuilder({ pathPrefix: '/api' })
 // POST /api/users      -> 201
 ```
 
+See the [Hono API Integration Guide](../src/implementations/http/hono-api/README.md) for the full surface: `schema.input` channels, query parsing, success-status defaults, and error handling.
+
+## Error Handling
+
+Every HTTP builder supports **two peer error-handling modes** — neither is "primary" or "fallback". Pick whichever fits your app, or combine them.
+
+| Mode | When to pick | What you configure |
+|---|---|---|
+| **Declarative — the taxonomy** | Structured errors, typed client dispatch, DocEnvelope integration | `errors` (taxonomy) + optional `unknownError` |
+| **Imperative — the `onError` callback** | Simple apps, gradual migration, full response control, no typed client contract | `onError` only |
+
+Both modes also expose `onRequestError` — a cross-cutting observer for logging, tracing, and metrics that fires for every error regardless of dispatch outcome.
+
+### Declarative — the taxonomy
+
+```typescript
+import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+
+class UseCaseError extends Error {
+  constructor(readonly externalMsg: string, readonly internalMsg: string) {
+    super(externalMsg); this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
+  }
+}
+
+const appErrors = defineErrorTaxonomy({
+  UseCaseError: {
+    class: UseCaseError,
+    statusCode: 422,
+    toResponse: (err) => ({ message: err.externalMsg }),        // `name: 'UseCaseError'` auto-injected
+    onCatch: (err) => logger.error(err.internalMsg),
+  },
+  // 3rd-party errors without a subclassable type use `match:` instead of `class:`.
+  MongoDuplicateKey: {
+    match: (err): err is Error =>
+      err instanceof Error && err.name === 'MongoServerError' && (err as any).code === 11000,
+    statusCode: 409,
+    toResponse: () => ({ message: 'Resource already exists' }),
+  },
+})
+
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  unknownError: {
+    statusCode: 500,
+    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
+    onCatch: (err, { procedure }) => logger.error({ procedure: procedure.name, err }),
+  },
+}).register(API, /* ... */).build()
+```
+
+The identical `errors` + `unknownError` shape plugs into `HonoRPCAppBuilder`, `ExpressRPCAppBuilder`, and `HonoStreamAppBuilder` (pre-stream only — mid-stream uses `onMidStreamError`).
+
+### Imperative — the `onError` callback
+
+For apps that don't need typed client dispatch or declarative docs, configure `onError` directly and handle every error in one place:
+
+```typescript
+new HonoAPIAppBuilder({
+  onError: (procedure, c, error) => {
+    logger.error(`[${procedure.name}]`, error)
+    return c.json({ error: error.message ?? 'unknown error' }, 500)
+  },
+}).register(API, /* ... */).build()
+```
+
+(Need to route different error classes to different status codes? Use the taxonomy — that's exactly what it's designed for. Hand-writing `instanceof` ladders inside `onError` is [anti-pattern #20](../agent_config/claude-code/skills/ts-procedures/anti-patterns.md).)
+
+Signatures (differ by framework):
+
+| Builder | `onError` signature |
+|---|---|
+| `HonoAPIAppBuilder`, `HonoRPCAppBuilder` | `(procedure, c: Context, error) => Response \| Promise<Response>` |
+| `ExpressRPCAppBuilder` | `(procedure, req, res, error) => void` (write to `res`) |
+| `HonoStreamAppBuilder` | `(procedure, c: Context, error) => Response \| Promise<Response>` — pre-stream only |
+
+Picking between modes isn't irreversible: you can start with `onError`, migrate chunks to the taxonomy as your error model stabilizes, and leave the rest in `onError`. Both modes coexist in the dispatch order below.
+
+### Per-route error narrowing (taxonomy mode)
+
+`APIConfig` and `RPCConfig` are generic over a `TErrorKey extends string` parameter so you can declare which errors a specific route may emit:
+
+```typescript
+import type { APIConfig } from 'ts-procedures/http'
+
+type MyAPIConfig = APIConfig<keyof typeof appErrors & string>
+const API = Procedures<Ctx, MyAPIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  errors: ['UseCaseError'],   // typo-checked against the taxonomy keys
+  schema: { /* ... */ },
+}, /* handler */)
+```
+
+These per-route declarations flow into the DocEnvelope and drive typed `catch` blocks on generated clients — see [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling).
+
+### Cross-cutting observability — `onRequestError`
+
+`onRequestError` fires for every caught error, **before** dispatch. It's an observer — it can't mutate the response. Use it for APM, distributed tracing, custom logging, or metrics where you want one hook that sees every error regardless of which mode dispatched it.
+
+```typescript
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  onRequestError: async ({ err, procedure, raw }) => {
+    sentry.captureException(err, { procedure: procedure.name })
+  },
+})
+```
+
+The observer is awaited before the response is sent, and any error it throws is swallowed (logged to the console) so a broken instrumentation hook can't corrupt the primary flow.
+
+### Dispatch order inside each builder's catch block
+
+1. **`onRequestError`** (observer) — awaited, can't alter dispatch or response
+2. **`errors` taxonomy** — user entries checked, then framework defaults, then `unknownError`
+3. **`onError` callback** — imperative handler receives anything the taxonomy didn't match
+4. **Hard default** — `{ error: message }` at status 500 (produced only when nothing above handled the error)
+
+Configuring only the taxonomy, only `onError`, both, or neither are all valid. When neither is configured the builder goes straight from step 1 to step 4.
+
 ## DocRegistry — Composing Docs from Multiple Builders
 
 Use `DocRegistry` to compose route documentation from any combination of HTTP builders into a typed envelope:
@@ -169,6 +292,14 @@ app.get('/docs', (c) => c.json(docs.toJSON()))
 
 `from()` stores a reference — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`. Supports optional `filter` and `transform` options for customizing output.
 
+`DocRegistry.fromTaxonomy(taxonomy, config?)` is a convenience constructor that seeds `envelope.errors` from your taxonomy plus framework defaults in one call (deduped — your entries win when keys overlap):
+
+```typescript
+const docs = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
+  .from(rpcBuilder)
+  .from(apiBuilder)
+```
+
 The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md).
 
 ## Type Exports

package/docs/streaming.md

@@ -168,7 +168,9 @@ For the built-in Hono streaming integration, see the [Hono Stream README](../src
 
 ## Stream Errors
 
-Streaming procedures support the same error handling as regular procedures (see [Error Handling](./core.md#error-handling)):
+Streaming procedures support the same error handling as regular procedures (see [Error Handling](./core.md#error-handling)).
+
+For HTTP stream endpoints, pre-stream errors (validation, context resolution, anything thrown before the first yield) go through the same two peer error-handling modes as every other HTTP builder — either the declarative `errors` / `unknownError` taxonomy (from `defineErrorTaxonomy`) or the imperative `onError` callback on `HonoStreamAppBuilder`. Cross-cutting `onRequestError` observer fires for every pre-stream error. See [HTTP Integrations → Error Handling](./http-integrations.md#error-handling) for the full contract. Mid-stream errors (thrown after the first yield) still flow through `onMidStreamError` and are surfaced to the client as SSE error events — the HTTP status is already committed once streaming begins, so mid-stream is outside the peer error modes.
 
 ```typescript
 const { StreamWithErrors } = CreateStream(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "5.15.0",
+  "version": "6.0.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",
@@ -12,7 +12,8 @@
   "scripts": {
     "build": "tsc",
     "lint": "npx eslint src/ --quiet",
-    "prepublishOnly": "npm run lint && npm run build",
+    "check-docs": "bash scripts/check-docs-consistency.sh",
+    "prepublishOnly": "npm run lint && npm run build && npm run check-docs",
     "postinstall": "node ./agent_config/bin/postinstall.mjs",
     "test": "vitest run"
   },
@@ -45,6 +46,10 @@
       "types": "./build/implementations/http/doc-registry.d.ts",
       "import": "./build/implementations/http/doc-registry.js"
     },
+    "./http-errors": {
+      "types": "./build/implementations/http/error-taxonomy.d.ts",
+      "import": "./build/implementations/http/error-taxonomy.js"
+    },
     "./client": {
       "types": "./build/client/index.d.ts",
       "import": "./build/client/index.js"

package/src/client/call.test.ts

@@ -7,6 +7,8 @@ import type {
   AdapterResponse,
   ClientHooks,
   CallDescriptor,
+  ProcedureCallDefaults,
+  ProcedureCallOptions,
 } from './types.js'
 
 // ── helpers ───────────────────────────────────────────────
@@ -37,43 +39,55 @@ function makeAdapter(response?: Partial<AdapterResponse>): ClientAdapter {
   }
 }
 
+interface RunConfig {
+  adapter: ClientAdapter
+  hooks?: ClientHooks
+  defaults?: ProcedureCallDefaults
+  options?: ProcedureCallOptions
+  descriptor?: CallDescriptor
+  basePath?: string
+}
+
+function run<T>({
+  adapter,
+  hooks = {},
+  defaults,
+  options,
+  descriptor = makeDescriptor(),
+  basePath = 'https://api.example.com',
+}: RunConfig): Promise<T> {
+  return executeCall<T>({ descriptor, basePath, adapter, hooks, defaults, options })
+}
+
 // ── executeCall ───────────────────────────────────────────
 
 describe('executeCall', () => {
   it('calls adapter.request and returns body', async () => {
     const adapter = makeAdapter({ body: { id: '1', name: 'Bob' } })
-    const result = await executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
+    const result = await run({ adapter })
     expect(adapter.request).toHaveBeenCalledOnce()
     expect(result).toEqual({ id: '1', name: 'Bob' })
   })
 
   it('throws ClientRequestError on 4xx response', async () => {
     const adapter = makeAdapter({ status: 404, body: { message: 'Not Found' } })
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
-    ).rejects.toThrow(ClientRequestError)
+    await expect(run({ adapter })).rejects.toThrow(ClientRequestError)
   })
 
   it('throws ClientRequestError on 5xx response', async () => {
     const adapter = makeAdapter({ status: 500, body: { message: 'Server Error' } })
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
-    ).rejects.toThrow(ClientRequestError)
+    await expect(run({ adapter })).rejects.toThrow(ClientRequestError)
   })
 
   it('throws ClientRequestError on 199 response (below 200)', async () => {
     const adapter = makeAdapter({ status: 199, body: null })
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
-    ).rejects.toThrow(ClientRequestError)
+    await expect(run({ adapter })).rejects.toThrow(ClientRequestError)
   })
 
   it('does not throw on 2xx boundary responses (200, 201, 299)', async () => {
     for (const status of [200, 201, 204, 299]) {
       const adapter = makeAdapter({ status, body: null })
-      await expect(
-        executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, undefined)
-      ).resolves.not.toThrow()
+      await expect(run({ adapter })).resolves.not.toThrow()
     }
   })
 
@@ -87,7 +101,7 @@ describe('executeCall', () => {
       stream: vi.fn(async () => { throw new Error('not expected') }),
     }
 
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onBeforeRequest: (ctx) => ({
         ...ctx,
         request: {
@@ -97,7 +111,7 @@ describe('executeCall', () => {
       }),
     }
 
-    await executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
+    await run({ adapter, hooks })
     expect(capturedHeaders[0]?.['x-auth']).toBe('token-123')
   })
 
@@ -110,26 +124,23 @@ describe('executeCall', () => {
       }),
       stream: vi.fn(async () => { throw new Error('not expected') }),
     }
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onAfterResponse: () => { order.push('afterResponse') },
     }
 
-    await executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
+    await run({ adapter, hooks })
     expect(order).toEqual(['adapter', 'afterResponse'])
   })
 
   it('does not throw when onAfterResponse swallows non-2xx by mutating status', async () => {
     const adapter = makeAdapter({ status: 401, body: { message: 'Unauthorized' } })
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onAfterResponse: (ctx) => {
-        // Swallow the error by setting status to 200
         ctx.response.status = 200
       },
     }
 
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
-    ).resolves.not.toThrow()
+    await expect(run({ adapter, hooks })).resolves.not.toThrow()
   })
 
   it('runs onError on adapter failure and re-throws', async () => {
@@ -139,24 +150,186 @@ describe('executeCall', () => {
       stream: vi.fn(async () => { throw new Error('not expected') }),
     }
     const receivedErrors: unknown[] = []
-    const globalHooks: ClientHooks = {
+    const hooks: ClientHooks = {
       onError: (ctx) => { receivedErrors.push(ctx.error) },
     }
 
-    await expect(
-      executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
-    ).rejects.toThrow('Network failure')
+    await expect(run({ adapter, hooks })).rejects.toThrow('Network failure')
     expect(receivedErrors[0]).toBe(adapterError)
   })
 
-  it('passes per-procedure hooks as local hooks', async () => {
+  it('passes per-procedure hooks as local options', async () => {
     const adapter = makeAdapter()
     const localOrder: string[] = []
-    const localHooks: ClientHooks = {
+    const options: ProcedureCallOptions = {
       onBeforeRequest: (ctx) => { localOrder.push('local-before'); return ctx },
     }
 
-    await executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, localHooks)
+    await run({ adapter, options })
     expect(localOrder).toContain('local-before')
   })
+
+  // ── Per-call options: signal / timeout / headers / basePath / meta ──
+
+  it('per-call timeout attaches a signal via AbortSignal.timeout', async () => {
+    const spy = vi.spyOn(AbortSignal, 'timeout')
+    try {
+      let observedSignal: AbortSignal | undefined
+      const adapter: ClientAdapter = {
+        request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+          observedSignal = req.signal
+          return { status: 200, headers: {}, body: {} }
+        }),
+        stream: vi.fn(async () => { throw new Error('not expected') }),
+      }
+
+      await run({ adapter, options: { timeout: 5000 } })
+      expect(spy).toHaveBeenCalledWith(5000)
+      expect(observedSignal).toBeDefined()
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('adapter receives a signal that reflects abort when the caller cancels', async () => {
+    const controller = new AbortController()
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        return new Promise((_resolve, reject) => {
+          const abort = () => reject(new Error('aborted'))
+          if (req.signal?.aborted) abort()
+          else req.signal?.addEventListener('abort', abort, { once: true })
+        })
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    const promise = run({ adapter, options: { signal: controller.signal } })
+    // Let executeCall reach the adapter before aborting
+    await Promise.resolve()
+    controller.abort()
+    await expect(promise).rejects.toThrow('aborted')
+  })
+
+  it('per-call signal is forwarded to the adapter', async () => {
+    const controller = new AbortController()
+    let observedSignal: AbortSignal | undefined
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        observedSignal = req.signal
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    await run({ adapter, options: { signal: controller.signal } })
+    expect(observedSignal).toBe(controller.signal)
+  })
+
+  it('per-call headers are merged into the request before hooks', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const seenByHook: Record<string, string>[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    const hooks: ClientHooks = {
+      onBeforeRequest: (ctx) => {
+        seenByHook.push({ ...ctx.request.headers })
+        return ctx
+      },
+    }
+
+    await run({ adapter, hooks, options: { headers: { 'x-request-id': 'req-123' } } })
+    expect(seenByHook[0]?.['x-request-id']).toBe('req-123')
+    expect(capturedHeaders[0]?.['x-request-id']).toBe('req-123')
+  })
+
+  it('per-call basePath overrides the client base path', async () => {
+    const capturedUrls: string[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedUrls.push(req.url)
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    await run({
+      adapter,
+      descriptor: makeDescriptor({ path: '/users' }),
+      basePath: 'https://default.example.com',
+      options: { basePath: 'https://override.example.com' },
+    })
+    expect(capturedUrls[0]).toBe('https://override.example.com/users')
+  })
+
+  it('global defaults apply when no per-call options', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const capturedUrls: string[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        capturedUrls.push(req.url)
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    await run({
+      adapter,
+      descriptor: makeDescriptor({ path: '/users' }),
+      basePath: 'https://default.example.com',
+      defaults: {
+        headers: { 'x-client-version': '1.0' },
+        basePath: 'https://region-us.example.com',
+      },
+    })
+    expect(capturedHeaders[0]?.['x-client-version']).toBe('1.0')
+    expect(capturedUrls[0]).toBe('https://region-us.example.com/users')
+  })
+
+  it('onBeforeRequest can still override resolved signal/headers', async () => {
+    let observedSignal: AbortSignal | undefined
+    const hookController = new AbortController()
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        observedSignal = req.signal
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    const hooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({
+        ...ctx,
+        request: { ...ctx.request, signal: hookController.signal },
+      }),
+    }
+
+    await run({ adapter, hooks, options: { timeout: 10_000 } })
+    expect(observedSignal).toBe(hookController.signal)
+  })
+
+  it('merges default + per-call meta; per-call keys win', async () => {
+    let observedMeta: unknown
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        observedMeta = req.meta
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+
+    await run({
+      adapter,
+      defaults: { meta: { traceId: 'default-trace', attempt: 1 } as never },
+      options: { meta: { traceId: 'override' } as never },
+    })
+    expect(observedMeta).toEqual({ traceId: 'override', attempt: 1 })
+  })
 })

package/src/client/call.ts

@@ -1,65 +1,87 @@
 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'
 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 async function executeCall<TResponse>(
-  descriptor: CallDescriptor,
-  basePath: string,
-  adapter: ClientAdapter,
-  globalHooks: ClientHooks,
-  localHooks: ClientHooks | undefined
-): Promise<TResponse> {
-  // 1. Build the initial request
-  let request = buildAdapterRequest(descriptor, basePath)
+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)
+  request = applyRequestOptions(request, defaults, options)
 
-  // 2. Run before-request hooks — they may mutate the request
+  // 3. Run before-request hooks — they may further mutate the request
   const beforeCtx = await runBeforeRequest(
     { procedureName: descriptor.name, scope: descriptor.scope, request },
-    globalHooks,
-    localHooks
+    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
+    // 5. On adapter error: run error hooks, re-throw
     await runOnError(
       { procedureName: descriptor.name, scope: descriptor.scope, request, error: err },
-      globalHooks,
-      localHooks
+      hooks,
+      options,
     )
     throw err
   }
 
-  // 5. Run after-response hooks — they may mutate response.status to swallow errors
+  // 6. Run after-response hooks — they may mutate response.status to swallow errors
   await runAfterResponse(
     { procedureName: descriptor.name, scope: descriptor.scope, request, response },
-    globalHooks,
-    localHooks
+    hooks,
+    options,
   )
 
-  // 6. Check status AFTER hooks (hooks may have swallowed the error by mutating status)
+  // 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,
@@ -69,6 +91,6 @@ export async function executeCall<TResponse>(
     })
   }
 
-  // 7. Return the body
+  // 8. Return the body
   return response.body as TResponse
 }