ts-procedures 5.15.0 → 6.0.0

package/build/implementations/http/route-errors.test.js

@@ -0,0 +1,140 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import { describe, expect, test } from 'vitest';
+import { Type } from 'typebox';
+import { Procedures } from '../../index.js';
+import { HonoAPIAppBuilder } from './hono-api/index.js';
+import { HonoRPCAppBuilder } from './hono-rpc/index.js';
+import { ExpressRPCAppBuilder } from './express-rpc/index.js';
+import { HonoStreamAppBuilder } from './hono-stream/index.js';
+import { DocRegistry } from './doc-registry.js';
+import { defineErrorTaxonomy } from './error-taxonomy.js';
+class UseCaseError extends Error {
+    externalMsg;
+    constructor(externalMsg) {
+        super(externalMsg);
+        this.externalMsg = externalMsg;
+        this.name = 'UseCaseError';
+        Object.setPrototypeOf(this, UseCaseError.prototype);
+    }
+}
+class AuthError extends Error {
+}
+const appErrors = defineErrorTaxonomy({
+    UseCaseError: { class: UseCaseError, statusCode: 422 },
+    AuthError: { class: AuthError, statusCode: 401 },
+});
+describe('per-route errors declaration', () => {
+    test('hono-api copies config.errors onto the route doc', () => {
+        const API = Procedures();
+        API.Create('GetUser', {
+            path: '/users/:id',
+            method: 'get',
+            errors: ['UseCaseError', 'AuthError'],
+            schema: {
+                input: { pathParams: Type.Object({ id: Type.String() }) },
+                returnType: Type.Object({}),
+            },
+        }, async () => ({}));
+        const builder = new HonoAPIAppBuilder().register(API, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['UseCaseError', 'AuthError']);
+    });
+    test('hono-api route doc omits errors when not declared', () => {
+        const API = Procedures();
+        API.Create('Health', { path: '/health', method: 'get', schema: { returnType: Type.Object({}) } }, async () => ({}));
+        const builder = new HonoAPIAppBuilder().register(API, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toBeUndefined();
+    });
+    test('hono-rpc copies config.errors onto the route doc', () => {
+        const RPC = Procedures();
+        RPC.Create('DoThing', {
+            scope: 'things',
+            version: 1,
+            errors: ['UseCaseError'],
+            schema: { params: Type.Object({}) },
+        }, async () => ({}));
+        const builder = new HonoRPCAppBuilder().register(RPC, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['UseCaseError']);
+    });
+    test('express-rpc copies config.errors onto the route doc', () => {
+        const RPC = Procedures();
+        RPC.Create('DoThing', {
+            scope: 'things',
+            version: 1,
+            errors: ['AuthError'],
+            schema: { params: Type.Object({}) },
+        }, async () => ({}));
+        const builder = new ExpressRPCAppBuilder().register(RPC, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['AuthError']);
+    });
+    test('hono-stream copies config.errors onto the route doc', () => {
+        const Stream = Procedures();
+        Stream.CreateStream('Watch', { scope: 'watch', version: 1, errors: ['AuthError'] }, async function* () {
+            yield { ok: true };
+        });
+        const builder = new HonoStreamAppBuilder().register(Stream, () => ({}));
+        builder.build();
+        expect(builder.docs[0].errors).toEqual(['AuthError']);
+    });
+    test('compile-time: errors typed as keyof taxonomy narrows valid keys', () => {
+        const _valid = ['UseCaseError', 'AuthError'];
+        // @ts-expect-error - 'NotRegistered' is not in the taxonomy
+        const _invalid = ['NotRegistered'];
+        expect(_valid).toBeDefined();
+        expect(_invalid).toBeDefined();
+    });
+});
+describe('DocRegistry.fromTaxonomy', () => {
+    test('seeds envelope errors from the taxonomy + framework defaults', () => {
+        const registry = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' });
+        const envelope = registry.toJSON();
+        const names = envelope.errors.map((e) => e.name);
+        expect(names).toContain('UseCaseError');
+        expect(names).toContain('AuthError');
+        expect(names).toContain('ProcedureValidationError');
+        expect(names).toContain('ProcedureRegistrationError');
+        expect(envelope.basePath).toBe('/api');
+    });
+    test('includeDefaults: false omits framework entries', () => {
+        const registry = DocRegistry.fromTaxonomy(appErrors, { includeDefaults: false });
+        const names = registry.toJSON().errors.map((e) => e.name);
+        expect(names).toEqual(['UseCaseError', 'AuthError']);
+    });
+    test('user entry with same key as default takes precedence (deduped)', () => {
+        const overridden = defineErrorTaxonomy({
+            ProcedureError: {
+                class: Error,
+                statusCode: 418,
+                description: 'custom override',
+            },
+        });
+        const envelope = DocRegistry.fromTaxonomy(overridden).toJSON();
+        const proc = envelope.errors.find((e) => e.name === 'ProcedureError');
+        expect(proc?.statusCode).toBe(418);
+        expect(proc?.description).toBe('custom override');
+        // no duplicates
+        const count = envelope.errors.filter((e) => e.name === 'ProcedureError').length;
+        expect(count).toBe(1);
+    });
+    test('registered route errors survive DocRegistry composition', () => {
+        const API = Procedures();
+        API.Create('GetUser', {
+            path: '/users/:id',
+            method: 'get',
+            errors: ['UseCaseError'],
+            schema: {
+                input: { pathParams: Type.Object({ id: Type.String() }) },
+                returnType: Type.Object({}),
+            },
+        }, async () => ({}));
+        const app = new HonoAPIAppBuilder().register(API, () => ({}));
+        app.build();
+        const envelope = DocRegistry.fromTaxonomy(appErrors).from(app).toJSON();
+        const route = envelope.routes.find((r) => r.kind === 'api' && r.name === 'GetUser');
+        expect(route?.errors).toEqual(['UseCaseError']);
+    });
+});
+//# sourceMappingURL=route-errors.test.js.map

package/build/implementations/http/route-errors.test.js.map

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

package/build/implementations/types.d.ts

@@ -1,7 +1,18 @@
 import { Procedures } from '../index.js';
-export interface RPCConfig {
+/**
+ * @typeParam TErrorKey - Union of valid taxonomy keys. Defaults to `string`
+ * (unconstrained). Narrow it by passing `keyof typeof yourTaxonomy & string`
+ * to get compile-time typo protection on `errors`.
+ */
+export interface RPCConfig<TErrorKey extends string = string> {
     scope: string | string[];
     version: number;
+    /**
+     * Taxonomy keys for errors this procedure may emit. Purely informational at
+     * runtime (nothing is rejected), but populates the DocEnvelope per-route
+     * error list so generated clients can narrow their catch types.
+     */
+    errors?: TErrorKey[];
 }
 export type FactoryItem<C> = {
     factory: ReturnType<typeof Procedures<C, RPCConfig>>;
@@ -16,10 +27,17 @@ export interface RPCHttpRouteDoc extends RPCConfig {
         body?: Record<string, unknown>;
         response?: Record<string, unknown>;
     };
+    /** Taxonomy keys for errors this route may emit. */
+    errors?: string[];
 }
 export type StreamMode = 'sse' | 'text';
 export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head';
-export interface APIConfig {
+/**
+ * @typeParam TErrorKey - Union of valid taxonomy keys. Defaults to `string`.
+ * Narrow it by passing `keyof typeof yourTaxonomy & string` for compile-time
+ * typo protection on `errors`.
+ */
+export interface APIConfig<TErrorKey extends string = string> {
     /** HTTP route path (supports Hono path params, e.g., '/users/:id') */
     path: string;
     /** HTTP method for this endpoint */
@@ -28,6 +46,12 @@ export interface APIConfig {
     successStatus?: number;
     /** Optional scope for grouping API routes in generated client files */
     scope?: string;
+    /**
+     * Taxonomy keys for errors this procedure may emit. Purely informational at
+     * runtime (nothing is rejected), but populates the DocEnvelope per-route
+     * error list so generated clients can narrow their catch types.
+     */
+    errors?: TErrorKey[];
 }
 export interface APIHttpRouteDoc extends APIConfig {
     kind: 'api';
@@ -41,6 +65,8 @@ export interface APIHttpRouteDoc extends APIConfig {
         headers?: Record<string, unknown>;
         response?: Record<string, unknown>;
     };
+    /** Taxonomy keys for errors this route may emit. */
+    errors?: string[];
 }
 /**
  * Constrains schema.input channel names to valid HTTP input sources.
@@ -76,6 +102,8 @@ export interface StreamHttpRouteDoc extends RPCConfig {
         yieldType?: Record<string, unknown>;
         returnType?: Record<string, unknown>;
     };
+    /** Taxonomy keys for errors this route may emit (pre-stream only). */
+    errors?: string[];
 }
 /**
  * Extracts the TContext type from a Procedures factory return type.

package/docs/client-and-codegen.md

@@ -20,14 +20,14 @@ npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated
 
 **Step 3 — Use the client:**
 
+The recommended entrypoint is the generated `create${Service}Client` factory. It calls `createClient` under the hood with the generated error registry pre-wired, so non-2xx responses arrive as typed class instances you can catch with `instanceof`.
+
 ```typescript
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import { createApiBindings, Api } from './generated/api'
+import { createApiClient, ApiErrors, createFetchAdapter } from './generated/api'
 
-const client = createClient({
+const api = createApiClient({
   adapter: createFetchAdapter(),
   basePath: 'http://localhost:3000',
-  scopes: createApiBindings,
   hooks: {
     onBeforeRequest(ctx) {
       ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
@@ -36,11 +36,32 @@ const client = createClient({
   },
 })
 
-// Fully typed — params and response inferred from server schemas
-const user = await client.users.GetUser({ pathParams: { id: '123' } })
+try {
+  const user = await api.users.GetUser({ pathParams: { id: '123' } })
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // err.body, err.status, err.procedureName, err.scope all typed
+  } else if (err instanceof ApiErrors.ApiProcedureError) {
+    // Catch-all for any service error (shared base class)
+  }
+}
+
+// Types live under the service namespace: Api.Users.GetUser.Params, Api.Errors.UseCaseError, etc.
+// Pass --service-name <Name> to rename `Api` → `<Name>` throughout.
+```
+
+For advanced control (sharing one `ClientInstance` across services, composing with a custom registry), use `createClient` + `create${Service}Bindings` directly:
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createApiBindings, ApiErrors } from './generated/api'
 
-// Types live under the service namespace: Api.Users.GetUser.Params, Api.Errors.ProcedureError, etc.
-// Pass --service-name <Name> to rename `Api` → `<Name>` (factory becomes create<Name>Bindings).
+const api = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createApiBindings,
+  errorRegistry: ApiErrors.ApiErrorRegistry,  // opt in to typed dispatch — omit to get the plain ClientRequestError transport shape
+})
 ```
 
 ## Generated File Structure
@@ -54,8 +75,8 @@ generated/
   notifications.ts   # Types + callables for stream procedures
   _types.ts          # Client type definitions (self-contained mode)
   _client.ts         # Client runtime bundle (self-contained mode)
-  _errors.ts         # Typed error classes + ${ServiceName}ProcedureErrorUnion (default: ApiProcedureErrorUnion)
-  index.ts           # Service namespace (`export namespace ${ServiceName}`) + create${ServiceName}Bindings factory (default: Api / createApiBindings)
+  _errors.ts         # Runtime error classes extending ${ServiceName}ProcedureError + static fromResponse + ${ServiceName}ErrorRegistry + ${ServiceName}ProcedureErrorUnion (default: ApiProcedureError / ApiErrorRegistry / ApiProcedureErrorUnion)
+  index.ts           # Service namespace + create${ServiceName}Bindings (manual wiring) and create${ServiceName}Client (convenience; registry pre-wired). Default: Api / createApiBindings / createApiClient.
 ```
 
 ## CLI Reference
@@ -106,9 +127,182 @@ const axiosAdapter: ClientAdapter = {
 }
 ```
 
+## Per-Call Options
+
+Every generated callable accepts an optional second argument for per-call configuration. The options bag covers both request-level config (timeout, cancellation, headers, base path) and hooks.
+
+```typescript
+// Timeout — aborts the request if it runs longer than 5 seconds
+const user = await client.users.GetUser({ pathParams: { id: '123' } }, { timeout: 5000 })
+
+// Cancellation — pass your own AbortSignal
+const controller = new AbortController()
+const user = await client.users.GetUser({ pathParams: { id: '123' } }, { signal: controller.signal })
+
+// Per-call headers (correlation IDs, feature flags, etc.)
+const user = await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  { headers: { 'X-Request-Id': crypto.randomUUID() } },
+)
+
+// Override base path for a single call (multi-region fallback, dev/prod switching)
+const user = await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  { basePath: 'https://api-eu.example.com' },
+)
+
+// Combine options with per-call hooks
+await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  {
+    timeout: 5000,
+    headers: { 'X-Trace-Id': traceId },
+    onAfterResponse(ctx) { log(ctx) },
+  },
+)
+```
+
+### Client-Level Defaults
+
+Set defaults via `config.defaults` — they apply to every call and are overridden by per-call options. Headers merge (per-call keys win); `signal` combines with per-call via `AbortSignal.any` (whichever aborts first wins); `timeout` is overridden by per-call `timeout`, and per-call `timeout: 0` disables an inherited default timeout.
+
+```typescript
+const client = createClient({
+  adapter,
+  basePath: 'http://localhost:3000',
+  scopes: createApiBindings,
+  defaults: {
+    timeout: 30_000,
+    headers: { 'X-Client-Version': '1.0.0' },
+  },
+})
+```
+
+### Typed Per-Request Metadata
+
+Every `AdapterRequest` carries an optional `meta` field typed via the `RequestMeta` interface. `RequestMeta` is declared empty by design — augment it in your own project via TypeScript declaration merging and your fields become typed end-to-end: in per-call options, in hook contexts, and inside your adapter.
+
+**Self-contained (code-generated) client:**
+
+```typescript
+declare module './generated/_types' {
+  interface RequestMeta {
+    traceId: string
+    priority?: 'high' | 'low'
+  }
+}
+```
+
+**Direct import of `ts-procedures/client`:**
+
+```typescript
+declare module 'ts-procedures/client' {
+  interface RequestMeta {
+    traceId: string
+    priority?: 'high' | 'low'
+  }
+}
+```
+
+After augmentation, `meta` is typed everywhere:
+
+```typescript
+const client = createClient({
+  adapter: {
+    async request(req) {
+      const trace = req.meta?.traceId     // typed as string | undefined
+      const pri = req.meta?.priority      // typed as 'high' | 'low' | undefined
+      // ...send the request
+    },
+    async stream(req) { /* same */ },
+  },
+  basePath: 'http://localhost:3000',
+  scopes: createApiBindings,
+  defaults: {
+    meta: { traceId: 'default-trace' },   // typed
+  },
+  hooks: {
+    onBeforeRequest(ctx) {
+      const trace = ctx.request.meta?.traceId   // typed
+      return ctx
+    },
+  },
+})
+
+// Per-call meta — traceId required, priority optional
+await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  { meta: { traceId: 'req-abc', priority: 'high' } },
+)
+```
+
+If `RequestMeta` declares required fields, the merged meta (defaults + per-call) must contain them at runtime. TypeScript can't statically verify this across the merge boundary, so supply required fields in `defaults.meta` or per-call `options.meta`.
+
+## Typed Error Handling
+
+Non-2xx responses whose body has a `name` field matching a registry key are dispatched into typed class instances. The generated `_errors.ts` exports:
+
+- A shared base class `${ServiceName}ProcedureError<TBody>` — carries `status`, `procedureName`, `scope`, and `body`. Catch any service error with `instanceof ${ServiceName}Errors.${ServiceName}ProcedureError`.
+- One concrete class per taxonomy entry in the envelope, each with a static `fromResponse(body, meta)` factory.
+- `${ServiceName}ErrorRegistry` — a `{ [name]: ErrorClass }` object consumed by the client's `dispatchTypedError`.
+- `${ServiceName}ProcedureErrorUnion` — a type union of every generated class for annotating catch clauses.
+
+```typescript
+import { createApiClient, ApiErrors } from './generated/api'
+
+const api = createApiClient({ adapter, basePath: '...' })
+
+try {
+  await api.users.GetUser({ pathParams: { id: 'x' } })
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // err.body is typed to UseCaseErrorBody; err.status, err.procedureName, err.scope available
+  } else if (err instanceof ApiErrors.ApiProcedureError) {
+    // Catch-all for any generated service error
+  } else if (err instanceof ClientRequestError) {
+    // Transport-level error (unmatched body.name, or non-JSON response)
+  }
+}
+```
+
+### Per-route error narrowing
+
+When a server route declares `errors: ['UseCaseError', 'AuthError']` on its config, the generated scope file emits an `Errors` type union inside that route's namespace:
+
+```typescript
+// Generated scope file:
+export namespace Users {
+  export namespace GetUser {
+    export type Params = { /* ... */ }
+    export type Response = { /* ... */ }
+    export type Errors = ApiErrors.UseCaseError | ApiErrors.AuthError
+  }
+}
+
+// Consumer:
+try { await api.users.GetUser({ pathParams: { id: 'x' } }) }
+catch (err) {
+  const e = err as Users.GetUser.Errors | ClientRequestError   // TS has no typed-throws; manual annotation
+  if (e instanceof ApiErrors.UseCaseError) { /* ... */ }
+}
+```
+
+Route-errors that reference keys missing from `_errors.ts` are filtered out at codegen time so generated code never references undefined types.
+
+### How dispatch works
+
+`src/client/error-dispatch.ts` exports a pure `dispatchTypedError(registry, body, meta)` helper. The client's `call.ts` invokes it on non-2xx responses:
+
+1. If no registry, or body isn't an object with a string `name`, or no registry key matches → returns `null`.
+2. Otherwise calls `registry[body.name].fromResponse(body, meta)` and returns the typed `Error` instance.
+
+When the helper returns `null`, the call falls back to `ClientRequestError` — the plain transport-error shape, used for unmatched names, non-JSON bodies, and when no registry is configured.
+
+Stream endpoints get the same treatment for **pre-stream** errors (thrown before the first yield — e.g. validation or auth). The fetch adapter's `stream()` eagerly parses a JSON body when status is non-2xx and exposes it via `AdapterStreamResponse.errorBody`, which `executeStream` passes through the registry. **Mid-stream** SSE error events continue to flow through `onMidStreamError` on the server and re-throw on the client without registry dispatch.
+
 ## Hooks
 
-Hooks let you intercept requests and responses globally or per-procedure call. Global hooks apply to every call made through the client instance; per-procedure hooks override or extend them for a single invocation.
+Hooks let you intercept requests and responses globally or per-procedure call. Global hooks apply to every call made through the client instance; per-procedure hooks run after global ones for a single invocation.
 
 ```typescript
 // Global hooks (apply to all calls)
@@ -123,7 +317,7 @@ const client = createClient({
   },
 })
 
-// Per-procedure hook override
+// Per-procedure hook — hooks and request options share the same options bag
 await client.users.GetUser({ pathParams: { id: '123' } }, {
   onAfterResponse(ctx) {
     const rateLimit = ctx.response.headers['x-rate-limit-remaining']
@@ -131,6 +325,16 @@ await client.users.GetUser({ pathParams: { id: '123' } }, {
 })
 ```
 
+### Precedence
+
+Headers and signals combine across layers. From lowest to highest precedence (within a given field):
+
+1. Adapter config (e.g., `createFetchAdapter({ headers })`)
+2. Client `defaults.headers` / `defaults.signal` / `defaults.timeout`
+3. Per-call `options.headers` / `options.signal` / `options.timeout`
+4. Route-declared headers from `schema.input.headers` (part of the typed contract)
+5. `onBeforeRequest` hook mutations — final say
+
 ## Streaming
 
 Stream procedures return a `TypedStream` — an async iterable for yield values, with a `.result` promise for the final return value:
@@ -186,12 +390,22 @@ import { createClient, createFetchAdapter } from './generated/_client'
 import { createClient, createFetchAdapter } from 'ts-procedures/client'
 ```
 
+- **`_client.ts`** also bundles `error-dispatch.ts`, so registry-based typed error dispatch works without importing `ts-procedures/client` at runtime.
+
 ## Type Exports
 
 ```typescript
 // Client Runtime
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import type { ClientAdapter, ClientHooks, TypedStream, ClientInstance } from 'ts-procedures/client'
+import { createClient, createFetchAdapter, dispatchTypedError } from 'ts-procedures/client'
+import type {
+  ClientAdapter,
+  ClientHooks,
+  TypedStream,
+  ClientInstance,
+  ErrorRegistry,
+  ErrorFactory,
+  ErrorResponseMeta,
+} from 'ts-procedures/client'
 
 // Code Generation
 import { generateClient } from 'ts-procedures/codegen'

package/docs/core.md

@@ -31,7 +31,7 @@ Create(name, config, handler)
 **Returns:**
 - `{ [name]: handler }` - Named export for the handler
 - `procedure` - Generic reference to the handler
-- `info` - Procedure meta (name, description, schema, `TExtendedConfig` properties, etc.)
+- `info` - Procedure metadata (name, description, schema, `TExtendedConfig` properties, etc.)
 
 ## Structured Input with schema.input
 
@@ -234,7 +234,8 @@ Create(
   async (ctx, params) => {
     const resource = await db.find(params.id)
     if (!resource) {
-      throw ctx.error(404, 'Resource not found', { id: params.id })
+      // Signature: ctx.error(message: string, meta?: object) => ProcedureError
+      throw ctx.error('Resource not found', { code: 'NOT_FOUND', id: params.id })
     }
     return resource
   },
@@ -249,6 +250,7 @@ Create(
 | ProcedureValidationError | Schema validation failure (params) |
 | ProcedureYieldValidationError | Yield validation failure (streaming with `validateYields: true`) |
 | ProcedureRegistrationError | Invalid schema at registration |
+| `${Service}ProcedureError` (client-side) | Base class for every generated error class on the client — see [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling) |
 
 ### Error Properties
 
@@ -264,6 +266,12 @@ try {
 }
 ```
 
+### Error Taxonomy (HTTP builders)
+
+For structured HTTP error responses, declare an error taxonomy once with `defineErrorTaxonomy` and pass it to any HTTP builder via the `errors` option — handlers `throw` their classes and the builder serializes to the configured status + body. `ctx.error()` continues to work as the ad-hoc ProcedureError path.
+
+The taxonomy also drives typed `catch` blocks on generated clients and per-route error documentation. See [HTTP Integrations → Error Handling](./http-integrations.md#error-handling) for the full contract, and [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling) for the client-side surface.
+
 ## Abort Signal
 
 For regular procedures, `ctx.signal` is available when the server implementation provides it. The built-in HTTP integrations (Hono RPC, Express RPC) inject the request's abort signal automatically:
@@ -394,10 +402,11 @@ describe('GetUser', () => {
   })
 
   test('has correct schema', () => {
+    // `info.schema.params` is the JSON Schema derived from the TypeBox
+    // definition above: `Type.Object({ hideName: Type.Optional(Type.Boolean()) })`.
     expect(info.schema.params).toEqual({
       type: 'object',
-      properties: { id: { type: 'string' } },
-      required: ['id'],
+      properties: { hideName: { type: 'boolean' } },
     })
   })
 })
@@ -431,7 +440,7 @@ Defines a procedure.
 **Returns:**
 - `{ [name]: handler }` - Named handler export
 - `procedure` - Generic handler reference
-- `info` - Procedure metareturnType
+- `info` - Procedure metadata (name, description, schema, extended-config properties)
 
 ### Type Exports