ts-procedures 7.2.0 → 8.0.0

package/agent_config/claude-code/skills/ts-procedures/patterns.md

@@ -105,11 +105,11 @@ const { TransferFunds } = Create(
 
 ## Error Taxonomy (declarative error-to-response mapping)
 
-`defineErrorTaxonomy` replaces `instanceof` ladders inside `onError`. Register error classes once with their status code and serializer, pass to any HTTP builder. Works across `hono-api`, `hono-rpc`, `express-rpc`, and `hono-stream` pre-stream (mid-stream still uses `onMidStreamError`).
+`defineErrorTaxonomy` replaces `instanceof` ladders inside `onError`. Register error classes once with their status code and serializer, pass to `HonoAppBuilder` for `rpc`, `http`, and pre-stream paths. Mid-stream errors (generator throws after the first yield) still go through `stream.onMidStreamError`.
 
 ```typescript
 import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
-import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import { HonoAppBuilder } from 'ts-procedures/hono'
 
 class UseCaseError extends Error {
   constructor(readonly externalMsg: string, readonly internalMsg: string) {
@@ -135,7 +135,7 @@ const appErrors = defineErrorTaxonomy({
   },
 })
 
-new HonoAPIAppBuilder({
+new HonoAppBuilder({
   errors: appErrors,
   unknownError: {
     toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
@@ -159,25 +159,23 @@ Key rules:
 - `defineErrorTaxonomy` topologically sorts `class:` entries so a subclass always resolves before its base — declaration order inside the helper no longer matters for inheritance chains. `match:` entries keep declared order.
 - The core wraps any non-`ProcedureError` thrown from a handler into a `ProcedureError` with `.cause` set. The resolver unwraps this automatically so your taxonomy sees the real class.
 - Two peer modes: declarative (`errors` + `unknownError`) or imperative (`onError`). Both are first-class. When neither is configured, the builder falls through to a hard default (`{ error: message }`, 500).
-- `onCatch`'s `raw` is the framework request object (Hono `Context` / `{ req, res }` for Express) typed as `unknown` — cast at the use site.
+- `onCatch`'s `raw` is the framework request object (Hono `Context`) typed as `unknown` — cast at the use site.
 
 ### Per-route error declaration (typed)
 
-Narrow `APIConfig` / `RPCConfig` to your taxonomy's keys for compile-time typo protection, and declare which errors each procedure may emit. These populate the DocEnvelope per-route so generated clients can type `catch` blocks precisely.
+Declare which errors each procedure may emit via the `errors` field on `CreateHttp` / `Create` config. These populate the DocEnvelope per-route so generated clients can type `catch` blocks precisely. For compile-time typo protection, pass the taxonomy key type as the `TErrorKey` generic on `CreateHttp`.
 
 ```typescript
-import { APIConfig } from 'ts-procedures/http'
 import { appErrors } from './errors/taxonomy'
 
-type MyAPIConfig = APIConfig<keyof typeof appErrors & string>
+const API = Procedures<Ctx>()
 
-const API = Procedures<Ctx, MyAPIConfig>()
-
-API.Create('GetUser', {
+// CreateHttp accepts TErrorKey as a generic for compile-time protection
+API.CreateHttp<keyof typeof appErrors & string>('GetUser', {
   path: '/users/:id',
   method: 'get',
   errors: ['UseCaseError', 'AuthError'],  // typed against taxonomy keys; typos are TS errors
-  schema: { /* ... */ },
+  schema: { req: { /* ... */ } },
 }, async (ctx, params) => { /* ... */ })
 ```
 
@@ -476,60 +474,11 @@ for (const proc of getProcedures()) {
 
 ---
 
-## Express RPC Integration
-
-```typescript
-import { Procedures } from 'ts-procedures'
-import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
-import { Type } from 'typebox'
-import type { RPCConfig } from 'ts-procedures/http'
-
-// 1. Define context and procedures
-type AppContext = { userId: string; requestId: string }
-const { Create } = Procedures<AppContext, RPCConfig>()
-
-const { GetUser } = Create(
-  'GetUser',
-  { scope: 'users', version: 1, schema: { params: Type.Object({ id: Type.String() }) } },
-  async (ctx, params) => fetchUser(params.id)
-)
-
-const { UpdateUser } = Create(
-  'UpdateUser',
-  { scope: 'users', version: 1 },
-  async (ctx, params) => updateUser(params)
-)
-
-// 2. Build Express app — the taxonomy handles framework errors (ProcedureValidationError
-// maps to 400 by default) and anything the app throws; unknownError is the last resort.
-const app = new ExpressRPCAppBuilder({
-  pathPrefix: '/api',
-  errors: appErrors,   // from defineErrorTaxonomy({ ... })
-  unknownError: {
-    toResponse: (err) => ({ error: (err as Error).message }),
-  },
-})
-  .register(
-    { getProcedures: () => [GetUser.info, UpdateUser.info] },  // Or use the factory directly
-    async (req) => ({
-      userId: await getUserIdFromToken(req.headers.authorization),
-      requestId: req.headers['x-request-id'] || crypto.randomUUID(),
-    })
-  )
-  .build()
-
-// Routes created:
-// POST /api/users/get-user/1
-// POST /api/users/update-user/1
-```
-
----
-
 ## Hono RPC Integration
 
 ```typescript
 import { Procedures } from 'ts-procedures'
-import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+import { HonoAppBuilder } from 'ts-procedures/hono'
 import type { RPCConfig } from 'ts-procedures/http'
 
 type AppContext = { userId: string }
@@ -539,7 +488,7 @@ RPC.Create('GetUser', { scope: 'users', version: 1 }, async (ctx, params) => {
   return fetchUser(params.id)
 })
 
-const app = new HonoRPCAppBuilder({ pathPrefix: '/api' })
+const app = new HonoAppBuilder({ pathPrefix: '/api' })
   .register(RPC, (c) => ({
     userId: c.req.header('x-user-id') || 'anonymous',
   }))
@@ -552,7 +501,7 @@ const app = new HonoRPCAppBuilder({ pathPrefix: '/api' })
 
 ```typescript
 import { Procedures } from 'ts-procedures'
-import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+import { HonoAppBuilder, sse } from 'ts-procedures/hono'
 import { Type } from 'typebox'
 import type { RPCConfig } from 'ts-procedures/http'
 
@@ -578,13 +527,15 @@ const { StreamEvents } = StreamRPC.CreateStream(
   }
 )
 
-const app = new HonoStreamAppBuilder({
+const app = new HonoAppBuilder({
   pathPrefix: '/api',
-  defaultStreamMode: 'sse',
-  onMidStreamError: (procedure, c, error) => ({
-    data: { error: error.message },
-    closeStream: true,
-  }),
+  stream: {
+    defaultStreamMode: 'sse',
+    onMidStreamError: (procedure, c, error) => ({
+      data: { error: error.message },
+      closeStream: true,
+    }),
+  },
 })
   .register(StreamRPC, (c) => ({
     userId: c.req.header('x-user-id') || 'anonymous',
@@ -599,8 +550,10 @@ const app = new HonoStreamAppBuilder({
 ## Text Streaming Mode
 
 ```typescript
-const app = new HonoStreamAppBuilder({
-  defaultStreamMode: 'text',  // Newline-delimited JSON
+const app = new HonoAppBuilder({
+  stream: {
+    defaultStreamMode: 'text',  // Newline-delimited JSON
+  },
 })
   .register(StreamRPC, contextFactory)
   .build()
@@ -610,35 +563,38 @@ const app = new HonoStreamAppBuilder({
 
 ---
 
-## Hono API Integration (REST-style)
+## Hono API Integration (REST-style) — v8 `CreateHttp`
+
+In v8, HTTP routes use `CreateHttp` (and `CreateHttpStream` for streaming). The factory no longer needs an `APIConfig` type parameter; HTTP fields (`path`, `method`, `scope`, `errors`) live on the `CreateHttp` config directly.
 
 ```typescript
 import { Procedures } from 'ts-procedures'
-import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
-import type { APIConfig } from 'ts-procedures/http'
+import { HonoAppBuilder } from 'ts-procedures/hono'
 import { Type } from 'typebox'
 
 type AppContext = { userId: string }
-const API = Procedures<AppContext, APIConfig>()
+const API = Procedures<AppContext>()
 
-API.Create('GetUser', {
+API.CreateHttp('GetUser', {
   path: '/users/:id',
   method: 'get',
   schema: {
-    input: {
+    req: {
       pathParams: Type.Object({ id: Type.String() }),
     },
-    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    res: {
+      body: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
   },
 }, async (ctx, { pathParams }) => {
   return await fetchUser(pathParams.id)
 })
 
-API.Create('CreateUser', {
+API.CreateHttp('CreateUser', {
   path: '/users',
   method: 'post',
   schema: {
-    input: {
+    req: {
       body: Type.Object({ name: Type.String(), email: Type.String() }),
     },
   },
@@ -646,11 +602,11 @@ API.Create('CreateUser', {
   return await createUser(body)
 })
 
-API.Create('DeleteUser', {
+API.CreateHttp('DeleteUser', {
   path: '/users/:id',
   method: 'delete',
   schema: {
-    input: {
+    req: {
       pathParams: Type.Object({ id: Type.String() }),
     },
   },
@@ -658,7 +614,7 @@ API.Create('DeleteUser', {
   await deleteUser(pathParams.id)
 })
 
-const app = new HonoAPIAppBuilder({
+const app = new HonoAppBuilder({
   pathPrefix: '/api',
   errors: appErrors,   // taxonomy maps error classes to statuses/bodies; ProcedureValidationError → 400 by default
   unknownError: {
@@ -678,59 +634,29 @@ const app = new HonoAPIAppBuilder({
 
 ---
 
-## Extended Config with APIConfig
-
-```typescript
-import { Procedures } from 'ts-procedures'
-import type { APIConfig } from 'ts-procedures/http'
-
-type AppContext = { userId: string }
-
-const { Create } = Procedures<AppContext, APIConfig>()
-
-// Every procedure now MUST include path and method
-const { GetUser } = Create(
-  'GetUser',
-  {
-    path: '/users/:id',
-    method: 'get',
-    schema: {
-      input: {
-        pathParams: Type.Object({ id: Type.String() }),
-        query: Type.Object({ include: Type.Optional(Type.String()) }),
-      },
-    },
-  },
-  async (ctx, { pathParams, query }) => {
-    return await fetchUser(pathParams.id, { include: query.include })
-  }
-)
-```
-
----
-
-## schema.input — Multi-Channel Structured Input
+## schema.req — Multi-Channel Structured Input (v8)
 
-Use `schema.input` instead of `schema.params` for structured per-channel validation:
+Use `schema.req` for structured per-channel validation. Channels: `pathParams`, `query`, `body`, `headers`.
 
 ```typescript
-const { Create } = Procedures<AppContext, APIConfig>()
+const API = Procedures<AppContext>()
 
-Create('UpdateUserField', {
+API.CreateHttp('UpdateUserField', {
   path: '/users/:id',
   method: 'put',
   schema: {
-    input: {
+    req: {
       pathParams: Type.Object({ id: Type.String() }),
       query: Type.Object({ notify: Type.Optional(Type.Boolean()) }),
       body: Type.Object({ field: Type.String(), value: Type.String() }),
       headers: Type.Object({ 'x-idempotency-key': Type.String() }),
     },
-    returnType: Type.Object({ ok: Type.Boolean() }),
+    res: {
+      body: Type.Object({ ok: Type.Boolean() }),
+    },
   },
 }, async (ctx, { pathParams, query, body, headers }) => {
   // Each channel independently typed and validated
-  // Validation errors include channel name: "Validation error for UpdateUserField in input.body"
   await updateField(pathParams.id, body.field, body.value, {
     idempotencyKey: headers['x-idempotency-key'],
   })
@@ -741,23 +667,27 @@ Create('UpdateUserField', {
 
 ---
 
-## APIInput Channel Constraint
+## Response Headers (v8 `CreateHttp`)
 
-Use `satisfies APIInput` to catch channel name typos at compile time:
+When `schema.res.headers` is declared, the handler must return `{ body, headers }` instead of the body bare. The client surfaces initial response headers on `TypedStream.headers` for streaming routes.
 
 ```typescript
-import type { APIInput } from 'ts-procedures/hono-api'
-
-Create('Search', {
-  path: '/search',
+API.CreateHttp('DownloadReport', {
+  path: '/reports/:id/download',
   method: 'get',
   schema: {
-    input: {
-      query: Type.Object({ q: Type.String() }),
-    } satisfies APIInput,
+    req: { pathParams: Type.Object({ id: Type.String() }) },
+    res: {
+      body: Type.Object({ url: Type.String() }),
+      headers: Type.Object({ 'x-report-format': Type.String() }),
+    },
   },
-}, async (ctx, { query }) => {
-  return await search(query.q)
+}, async (ctx, { pathParams }) => {
+  const report = await generateReport(pathParams.id)
+  return {
+    body: { url: report.url },
+    headers: { 'x-report-format': report.format },
+  }
 })
 ```
 
@@ -816,11 +746,11 @@ PublicRPC.Create('HealthCheck', { scope: 'health', version: 1 }, async () => ({
 AuthRPC.Create('GetProfile', { scope: 'users', version: 1 }, async (ctx) => fetchProfile(ctx.userId))
 
 // Register with different context resolvers
-const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
-  .register(PublicRPC, (req) => ({ requestId: req.headers['x-request-id'] }))
-  .register(AuthRPC, async (req) => ({
-    userId: await authenticate(req),
-    requestId: req.headers['x-request-id'],
+const app = new HonoAppBuilder({ pathPrefix: '/api' })
+  .register(PublicRPC, (c) => ({ requestId: c.req.header('x-request-id') }))
+  .register(AuthRPC, async (c) => ({
+    userId: await authenticate(c),
+    requestId: c.req.header('x-request-id'),
   }))
   .build()
 ```
@@ -830,7 +760,7 @@ const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
 ## Documentation Generation with extendProcedureDoc
 
 ```typescript
-const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
+const app = new HonoAppBuilder({ pathPrefix: '/api' })
   .register(RPC, contextFactory, ({ base, procedure }) => ({
     summary: procedure.config.description,
     tags: [base.scope],
@@ -944,20 +874,19 @@ describe('StreamNotifications', () => {
 ## Testing HTTP Builders
 
 ```typescript
-import supertest from 'supertest'
-
-describe('Express RPC', () => {
-  const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
-    .register(RPC, { userId: 'test-user', requestId: 'test' })
+describe('Hono RPC', () => {
+  const app = new HonoAppBuilder({ pathPrefix: '/api' })
+    .register(RPC, () => ({ userId: 'test-user', requestId: 'test' }))
     .build()
 
   test('POST /api/users/get-user/1', async () => {
-    const res = await supertest(app)
-      .post('/api/users/get-user/1')
-      .send({ id: 'user-123' })
-      .expect(200)
+    const res = await app.request('/api/users/get-user/1', {
+      method: 'POST',
+      body: JSON.stringify({ id: 'user-123' }),
+    })
 
-    expect(res.body).toEqual({ id: 'user-123', name: 'John' })
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ id: 'user-123', name: 'John' })
   })
 })
 ```
@@ -966,13 +895,13 @@ describe('Express RPC', () => {
 
 ## Lifecycle Hook Execution Order
 
-### Standard RPC (Express/Hono)
+### Standard RPC (HonoAppBuilder)
 ```
 onRequestStart → factoryContext() → handler() → onSuccess → onRequestEnd
                                   → onError  →              onRequestEnd
 ```
 
-### Streaming (HonoStreamAppBuilder)
+### Streaming (HonoAppBuilder)
 ```
 onRequestStart → factoryContext() → params validation
                                   → onError (if invalid) → onRequestEnd
@@ -1202,10 +1131,8 @@ const axiosAdapter: ClientAdapter = {
 
 When a downstream developer is building inside an Astro app, recommend the catch-all pattern:
 
-1. Build the Hono app ONCE in `src/server/api.ts` using `HonoAPIAppBuilder` / `HonoRPCAppBuilder` / `HonoStreamAppBuilder` exactly as you would for any other deployment.
+1. Build the Hono app ONCE in `src/server/api.ts` using `HonoAppBuilder` exactly as you would for any other deployment.
 2. Inside the factory-context closure, call `getAstroContext(c)` to read `locals`, `cookies`, `params`, etc.
 3. Mount the built app(s) in a single catch-all file: `src/pages/api/[...rest].ts`. Use `pathPrefix: '/api'` so your Hono routes don't need to repeat the prefix.
 
 Anti-pattern: don't create one Astro file per procedure — that loses the centralized factory wiring and forces the developer to repeat the context closure.
-
-Anti-pattern: don't try to use `express-rpc` with the Astro adapter. The adapter only accepts Web-Fetch apps (Hono).

package/agent_config/claude-code/skills/ts-procedures-review/SKILL.md

@@ -14,7 +14,7 @@ Parse `$ARGUMENTS` as a file or directory path. If a directory, review all `.ts`
 ## Instructions
 
 1. Read the target file(s).
-2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/express-rpc`, `ts-procedures/hono-rpc`, `ts-procedures/hono-stream`, `ts-procedures/hono-api`, `ts-procedures/http`, `ts-procedures/http-docs`, `ts-procedures/http-errors`, `ts-procedures/client`, `ts-procedures/codegen`) to determine file types.
+2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/hono`, `ts-procedures/http`, `ts-procedures/http-docs`, `ts-procedures/http-errors`, `ts-procedures/client`, `ts-procedures/codegen`) to determine file types.
 3. Check each file against the categorized checklist in [checklist.md](checklist.md).
 4. For detailed code examples of each violation pattern, reference [anti-patterns.md](../ts-procedures/anti-patterns.md) — it shows 20 common mistakes with before/after code fixes and severity ratings.
 5. Output findings grouped by severity.

package/agent_config/claude-code/skills/ts-procedures-review/checklist.md

@@ -57,11 +57,10 @@
 
 ---
 
-## HTTP Builder Checks (Express/Hono)
+## HTTP Builder Checks (HonoAppBuilder)
 
 ### CRITICAL
-- [ ] Standard `Create` procedures registered with `ExpressRPCAppBuilder` or `HonoRPCAppBuilder`, NOT `HonoStreamAppBuilder`
-- [ ] Stream `CreateStream` procedures registered with `HonoStreamAppBuilder`, NOT the RPC builders
+- [ ] `Create` (RPC), `CreateHttp` (REST), `CreateStream` (RPC stream), and `CreateHttpStream` (REST stream) all registered on the same `HonoAppBuilder` — kind dispatch is automatic
 - [ ] Custom error classes are registered via `defineErrorTaxonomy` + builder's `errors` config — NOT hand-written `onError` instanceof ladders (anti-pattern #20)
 - [ ] If a handler throws a non-`ProcedureError`, its class is either in the taxonomy or intentionally caught by `unknownError`
 
@@ -80,7 +79,7 @@
 
 ---
 
-## Streaming Checks (HonoStreamAppBuilder)
+## Streaming Checks (HonoAppBuilder)
 
 ### CRITICAL
 - [ ] Pre-stream errors handled via either peer mode — `errors` + `unknownError` taxonomy OR `onError` callback (the hono-stream `onPreStreamError` was renamed to `onError` in v6)
@@ -98,7 +97,7 @@
 
 ---
 
-## API Builder Checks (HonoAPIAppBuilder)
+## API Builder Checks (HonoAppBuilder)
 
 ### CRITICAL
 - [ ] `build()` is called synchronously — it returns `Hono`, NOT `Promise<Hono>`. Do not `await` it.

package/agent_config/claude-code/skills/ts-procedures-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ts-procedures-scaffold
-description: "Generate ts-procedures implementations with correct patterns — procedures, streams, Express RPC, Hono RPC, Hono streaming, REST APIs, and client setup."
+description: "Generate ts-procedures implementations with correct patterns — procedures, streams, Hono apps (RPC, streams, REST in one builder), and client setup."
 argument-hint: "<type> <Name>"
 allowed-tools: Read Write
 ---
@@ -18,9 +18,9 @@ If either argument is missing, ask the user for `<type>` and `<Name>`.
 3. Derive placeholder variants from the provided PascalCase Name:
    - `{{Name}}` — PascalCase as given (e.g., `UserProfile`)
    - `{{name}}` — camelCase (e.g., `userProfile`)
-   - For URL scopes and file paths, use kebab-case (e.g., `user-profile`)
+   - `{{kebab}}` — kebab-case (e.g., `user-profile`)
 4. Read the template file from `templates/$0.md` (relative to this skill directory).
-5. Replace all `{{Name}}` and `{{name}}` placeholders with the appropriate variants.
+5. Replace all `{{Name}}`, `{{name}}`, and `{{kebab}}` placeholders with the appropriate variants.
 6. Generate the implementation file(s) following the template exactly.
 7. Also generate a colocated test file following ts-procedures test conventions.
 
@@ -30,10 +30,7 @@ If either argument is missing, ask the user for `<type>` and `<Name>`.
 |------|----------|----------------|
 | `procedure` | `templates/procedure.md` | `{{Name}}.procedure.ts`, `{{Name}}.procedure.test.ts` |
 | `stream-procedure` | `templates/stream-procedure.md` | `{{Name}}.stream.ts`, `{{Name}}.stream.test.ts` |
-| `express-rpc` | `templates/express-rpc.md` | `{{Name}}.rpc.ts`, `{{Name}}.rpc.test.ts` |
-| `hono-rpc` | `templates/hono-rpc.md` | `{{Name}}.rpc.ts`, `{{Name}}.rpc.test.ts` |
-| `hono-stream` | `templates/hono-stream.md` | `{{Name}}.stream-rpc.ts`, `{{Name}}.stream-rpc.test.ts` |
-| `hono-api` | `templates/hono-api.md` | `{{Name}}.api.ts`, `{{Name}}.api.test.ts` |
+| `hono` | `templates/hono.md` | `{{Name}}.hono.ts`, `{{Name}}.hono.test.ts` |
 | `client` | `templates/client.md` | `{{Name}}.client.ts`, `{{Name}}.client.test.ts` |
 | `astro-catchall` | `templates/astro-catchall.md` | `src/pages/api/[...rest].ts` |