ts-procedures 5.9.0 → 5.10.0

package/agent_config/claude-code/skills/scaffold/templates/client.md

@@ -0,0 +1,115 @@
+# Client Template: {{Name}}
+
+## Implementation — `{{Name}}.client.ts`
+
+```typescript
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import { createScopeBindings } from './generated/api'
+// With --service-name: import { create{{Name}}Bindings } from './generated/api'
+
+// Create the typed client
+export const {{name}}Client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000', // TODO: configure base URL
+  scopes: createScopeBindings,
+  // With --service-name: scopes: create{{Name}}Bindings,
+  hooks: {
+    onBeforeRequest(ctx) {
+      // TODO: add auth headers, request IDs, etc.
+      ctx.request.headers = {
+        ...ctx.request.headers,
+        // Authorization: `Bearer ${getToken()}`,
+      }
+      return ctx
+    },
+    onAfterResponse(ctx) {
+      // TODO: handle global response concerns (401 redirect, rate limiting, etc.)
+      // if (ctx.response.status === 401) { redirect('/login') }
+    },
+  },
+})
+
+// --- RPC call example ---
+// const user = await {{name}}Client.users.GetUser({ userId: '123' })
+
+// --- API call example (with schema.input channels) ---
+// const user = await {{name}}Client.users.GetUser({ pathParams: { id: '123' } })
+
+// --- Streaming call example ---
+// const stream = {{name}}Client.events.WatchNotifications({ filter: 'all' })
+// for await (const event of stream) {
+//   console.log(event) // Typed from server yieldType schema
+// }
+// const result = await stream.result // Typed from server returnType schema
+
+// --- Per-procedure hook override ---
+// const user = await {{name}}Client.users.GetUser({ id: '123' }, {
+//   onAfterResponse(ctx) {
+//     console.log('Rate limit:', ctx.response.headers['x-rate-limit-remaining'])
+//   },
+// })
+```
+
+## Test — `{{Name}}.client.test.ts`
+
+```typescript
+import { describe, test, expect, beforeAll, afterAll } from 'vitest'
+import { {{name}}Client } from './{{Name}}.client'
+
+// TODO: start your server before tests, or mock the adapter
+// import { createServer } from './server'
+// let server: ReturnType<typeof createServer>
+
+describe('{{Name}} Client', () => {
+  // beforeAll(async () => {
+  //   server = createServer()
+  //   await server.listen(3000)
+  // })
+  //
+  // afterAll(async () => {
+  //   await server.close()
+  // })
+
+  test('makes RPC calls with typed params and response', async () => {
+    // TODO: replace with an actual procedure call
+    // const result = await {{name}}Client.users.GetUser({ userId: 'test-id' })
+    // expect(result).toBeDefined()
+    // expect(result.id).toBe('test-id')
+  })
+
+  test('handles validation errors from the server', async () => {
+    // TODO: call with invalid params and verify error handling
+    // await expect(
+    //   {{name}}Client.users.GetUser({} as any)
+    // ).rejects.toThrow()
+  })
+
+  test('streams data with typed yields', async () => {
+    // TODO: replace with an actual stream procedure call
+    // const stream = {{name}}Client.events.WatchNotifications({ filter: 'all' })
+    // const values = []
+    // for await (const event of stream) {
+    //   values.push(event)
+    //   if (values.length >= 3) break
+    // }
+    // expect(values).toHaveLength(3)
+    // const result = await stream.result
+    // expect(result).toBeDefined()
+  })
+})
+```
+
+## Code Generation Setup
+
+Generate the typed client bindings from your running server:
+
+```bash
+# Default (self-contained, namespaced types, JSDoc)
+npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api
+
+# With service name for multi-service apps
+npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api --service-name {{Name}}
+
+# Watch mode for development
+npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api --watch
+```

package/agent_config/lib/install-claude.mjs

@@ -59,42 +59,42 @@ export function installClaude(projectRoot) {
 
   // 1. Rules file — framework reference (always loaded in context)
   const guideSkill = readFileSync(join(SKILLS_DIR, 'guide', 'SKILL.md'), 'utf-8');
+  const guideBasePath = 'node_modules/ts-procedures/agent_config/claude-code/skills/guide';
   const guideBody = stripFrontmatter(guideSkill)
-    // Remove the "Supporting Files" section — replaced by "Detailed Reference" below
-    .replace(/\n## Supporting Files[\s\S]*$/, '');
-
-  const rulesContent = autoHeader + guideBody + `
-
-## Detailed Reference
-
-For complete API details, patterns, and anti-patterns, read the files in:
-\`node_modules/ts-procedures/agent_config/claude-code/skills/guide/\`
-
-- \`api-reference.md\` — Full API reference for Procedures, Create, CreateStream, errors, schema, HTTP implementations
-- \`patterns.md\` — Prescribed patterns with code examples
-- \`anti-patterns.md\` — Common mistakes to avoid with fixes
-`;
-
-  writeFileSync(join(rulesDir, 'ts-procedures.md'), rulesContent, 'utf-8');
+    // Replace relative markdown links with node_modules paths
+    .replace(/\[patterns\.md\]\(patterns\.md\)/g, `\`${guideBasePath}/patterns.md\``)
+    .replace(/\[anti-patterns\.md\]\(anti-patterns\.md\)/g, `\`${guideBasePath}/anti-patterns.md\``)
+    .replace(/\[api-reference\.md\]\(api-reference\.md\)/g, `\`${guideBasePath}/api-reference.md\``)
+    // Replace the Workflow section — skill cross-references don't apply outside the plugin
+    .replace(/\n## Workflow[\s\S]*$/, '');
+
+  writeFileSync(join(rulesDir, 'ts-procedures.md'), autoHeader + guideBody, 'utf-8');
   files.push('.claude/rules/ts-procedures.md');
 
   // 2. Scaffold command
   const scaffoldSkill = readFileSync(join(SKILLS_DIR, 'scaffold', 'SKILL.md'), 'utf-8');
+  const scaffoldBasePath = 'node_modules/ts-procedures/agent_config/claude-code/skills/scaffold';
   const scaffoldBody = stripFrontmatter(scaffoldSkill)
+    // Replace ${CLAUDE_SKILL_DIR} template path with node_modules path
     .replace(
-      'Read the template file from `templates/<type>.md` in this skill directory.',
-      'Read the template file from `node_modules/ts-procedures/agent_config/claude-code/skills/scaffold/templates/<type>.md`.'
-    );
+      '`${CLAUDE_SKILL_DIR}/templates/$0.md`',
+      `\`${scaffoldBasePath}/templates/$0.md\``
+    )
+    // Replace Workflow section — skill cross-references don't apply outside the plugin
+    .replace(/\n## Workflow[\s\S]*$/, '');
 
   writeFileSync(join(commandsDir, 'ts-procedures-scaffold.md'), autoHeader + scaffoldBody, 'utf-8');
   files.push('.claude/commands/ts-procedures-scaffold.md');
 
   // 3. Review command
   const reviewSkill = readFileSync(join(SKILLS_DIR, 'review', 'SKILL.md'), 'utf-8');
+  const reviewBasePath = 'node_modules/ts-procedures/agent_config/claude-code/skills/review';
   const reviewBody = stripFrontmatter(reviewSkill)
-    .replaceAll(
-      '`checklist.md`',
-      '`node_modules/ts-procedures/agent_config/claude-code/skills/review/checklist.md`'
+    // Replace relative markdown links with node_modules paths
+    .replace(/\[checklist\.md\]\(checklist\.md\)/g, `\`${reviewBasePath}/checklist.md\``)
+    .replace(
+      /\[anti-patterns\.md\]\(\.\.\/guide\/anti-patterns\.md\)/g,
+      `\`${guideBasePath}/anti-patterns.md\``
     );
 
   writeFileSync(join(commandsDir, 'ts-procedures-review.md'), autoHeader + reviewBody, 'utf-8');

package/docs/core.md

@@ -203,18 +203,15 @@ const { CreateUser } = Create(
 
 ## Schema Validation
 
-ts-procedures supports two schema libraries — **TypeBox** (recommended) and **Suretype**. The library is auto-detected from the schema object. Both work identically at runtime; choose whichever you prefer:
+ts-procedures uses **TypeBox** for schema definitions:
 
 ```typescript
-// TypeBox
 import { Type } from 'typebox'
 schema: { params: Type.Object({ title: Type.String() }) }
-
-// Suretype
-import { v } from 'suretype'
-schema: { params: v.object({ title: v.string().required() }) }
 ```
 
+TypeBox schemas are valid JSON Schema and work directly with AJV for runtime validation.
+
 ### Validation Behavior
 
 AJV is configured with:
@@ -426,8 +423,8 @@ Defines a procedure.
 **Parameters:**
 - `name` - Unique procedure name (becomes named export)
 - `config.description` - Optional description
-- `config.schema.params` - Suretype or TypeBox schema for params (validated at runtime)
-- `config.schema.returnType` - Suretype or TypeBox schema for return returnType (documentation only)
+- `config.schema.params` - TypeBox schema for params (validated at runtime)
+- `config.schema.returnType` - TypeBox schema for return type (documentation only)
 - Additional properties from `TExtendedConfig`
 - `handler` - Async function `(ctx, params) => Promise<returnType>`
 
@@ -460,7 +457,6 @@ import {
   extractJsonSchema,
   schemaParser,
   isTypeboxSchema,
-  isSuretypeSchema,
 
   // Schema types
   TJSONSchema,

package/docs/streaming.md

@@ -10,7 +10,7 @@ For the `CreateStream` function signature and config options, see [Core Procedur
 
 ```typescript
 import { Procedures } from 'ts-procedures'
-import { v } from 'suretype'
+import { Type } from 'typebox'
 
 const { CreateStream } = Procedures<{ userId: string }>()
 
@@ -19,11 +19,11 @@ const { StreamUpdates } = CreateStream(
   {
     description: 'Stream real-time updates',
     schema: {
-      params: v.object({ topic: v.string().required() }),
-      yieldType: v.object({
-        id: v.string().required(),
-        message: v.string().required(),
-        timestamp: v.number().required(),
+      params: Type.Object({ topic: Type.String() }),
+      yieldType: Type.Object({
+        id: Type.String(),
+        message: Type.String(),
+        timestamp: Type.Number(),
       }),
     },
   },
@@ -60,7 +60,7 @@ const { ValidatedStream } = CreateStream(
   'ValidatedStream',
   {
     schema: {
-      yieldType: v.object({ count: v.number().required() }),
+      yieldType: Type.Object({ count: Type.Number() }),
     },
     validateYields: true, // Enable runtime validation of each yield
   },
@@ -148,8 +148,8 @@ CreateStream(
   'LiveFeed',
   {
     schema: {
-      params: v.object({ channel: v.string() }),
-      yieldType: v.object({ event: v.string(), data: v.any() }),
+      params: Type.Object({ channel: Type.String() }),
+      yieldType: Type.Object({ event: Type.String(), data: Type.Any() }),
     },
   },
   async function* (ctx, params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "5.9.0",
+  "version": "5.10.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",
@@ -23,7 +23,7 @@
       "import": "./build/exports.js"
     },
     "./http": {
-      "types": "./build/implementations/http/types.d.ts"
+      "types": "./build/implementations/types.d.ts"
     },
     "./express-rpc": {
       "types": "./build/implementations/http/express-rpc/index.d.ts",
@@ -61,18 +61,7 @@
     "build",
     "docs",
     "agent_config",
-    "src/implementations/http/README.md",
-    "src/implementations/http/express-rpc/README.md",
-    "src/implementations/http/hono-rpc/README.md",
-    "src/implementations/http/hono-stream/README.md",
-    "src/client/types.ts",
-    "src/client/errors.ts",
-    "src/client/request-builder.ts",
-    "src/client/hooks.ts",
-    "src/client/call.ts",
-    "src/client/stream.ts",
-    "src/client/fetch-adapter.ts",
-    "src/client/index.ts"
+    "src"
   ],
   "keywords": [
     "typescript",

package/src/client/call.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, vi } from 'vitest'
+import { executeCall } from './call.js'
+import { ClientRequestError } from './errors.js'
+import type {
+  ClientAdapter,
+  AdapterRequest,
+  AdapterResponse,
+  ClientHooks,
+  CallDescriptor,
+} from './types.js'
+
+// ── helpers ───────────────────────────────────────────────
+
+function makeDescriptor(overrides?: Partial<CallDescriptor>): CallDescriptor {
+  return {
+    name: 'GetUser',
+    scope: 'users',
+    path: '/users',
+    method: 'GET',
+    kind: 'rpc',
+    params: { id: '42' },
+    ...overrides,
+  }
+}
+
+function makeAdapter(response?: Partial<AdapterResponse>): ClientAdapter {
+  return {
+    request: vi.fn(async (_req: AdapterRequest): Promise<AdapterResponse> => ({
+      status: 200,
+      headers: {},
+      body: { id: '42', name: 'Alice' },
+      ...response,
+    })),
+    stream: vi.fn(async () => {
+      throw new Error('stream not expected in call tests')
+    }),
+  }
+}
+
+// ── 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)
+    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)
+  })
+
+  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)
+  })
+
+  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)
+  })
+
+  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()
+    }
+  })
+
+  it('runs onBeforeRequest before calling adapter (headers are modified)', async () => {
+    const capturedHeaders: 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 globalHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => ({
+        ...ctx,
+        request: {
+          ...ctx.request,
+          headers: { ...ctx.request.headers, 'x-auth': 'token-123' },
+        },
+      }),
+    }
+
+    await executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
+    expect(capturedHeaders[0]?.['x-auth']).toBe('token-123')
+  })
+
+  it('runs onAfterResponse after adapter returns', async () => {
+    const order: string[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (): Promise<AdapterResponse> => {
+        order.push('adapter')
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+    const globalHooks: ClientHooks = {
+      onAfterResponse: () => { order.push('afterResponse') },
+    }
+
+    await executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
+    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 = {
+      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()
+  })
+
+  it('runs onError on adapter failure and re-throws', async () => {
+    const adapterError = new Error('Network failure')
+    const adapter: ClientAdapter = {
+      request: vi.fn(async () => { throw adapterError }),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+    const receivedErrors: unknown[] = []
+    const globalHooks: ClientHooks = {
+      onError: (ctx) => { receivedErrors.push(ctx.error) },
+    }
+
+    await expect(
+      executeCall(makeDescriptor(), 'https://api.example.com', adapter, globalHooks, undefined)
+    ).rejects.toThrow('Network failure')
+    expect(receivedErrors[0]).toBe(adapterError)
+  })
+
+  it('passes per-procedure hooks as local hooks', async () => {
+    const adapter = makeAdapter()
+    const localOrder: string[] = []
+    const localHooks: ClientHooks = {
+      onBeforeRequest: (ctx) => { localOrder.push('local-before'); return ctx },
+    }
+
+    await executeCall(makeDescriptor(), 'https://api.example.com', adapter, {}, localHooks)
+    expect(localOrder).toContain('local-before')
+  })
+})

package/src/client/errors.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { ClientRequestError, ClientPathParamError, ClientStreamError } from './errors.js'
+
+describe('ClientRequestError', () => {
+  it('includes status, headers, and body', () => {
+    const err = new ClientRequestError({
+      status: 401,
+      headers: { 'x-request-id': 'abc' },
+      body: { message: 'Unauthorized' },
+      procedureName: 'GetUser',
+      scope: 'users',
+    })
+    expect(err).toBeInstanceOf(Error)
+    expect(err.name).toBe('ClientRequestError')
+    expect(err.status).toBe(401)
+    expect(err.headers['x-request-id']).toBe('abc')
+    expect(err.body).toEqual({ message: 'Unauthorized' })
+    expect(err.procedureName).toBe('GetUser')
+    expect(err.scope).toBe('users')
+    expect(err.message).toBe('GetUser (users) failed with status 401')
+  })
+})
+
+describe('ClientPathParamError', () => {
+  it('reports missing param', () => {
+    const err = new ClientPathParamError('id', '/users/:id', 'GetUser')
+    expect(err).toBeInstanceOf(Error)
+    expect(err.name).toBe('ClientPathParamError')
+    expect(err.message).toContain('id')
+    expect(err.message).toContain('/users/:id')
+  })
+})
+
+describe('ClientStreamError', () => {
+  it('includes procedure context', () => {
+    const err = new ClientStreamError('stream interrupted', 'Watch', 'events')
+    expect(err).toBeInstanceOf(Error)
+    expect(err.name).toBe('ClientStreamError')
+    expect(err.procedureName).toBe('Watch')
+    expect(err.scope).toBe('events')
+    expect(err.message).toBe('stream interrupted')
+  })
+})