ts-procedures 10.1.2 → 10.2.1

package/src/server/doc-registry.test.ts

@@ -5,9 +5,7 @@ import type {
   THttpStreamProcedureRegistration,
   TProcedureRegistration,
 } from '../core/types.js'
-import pkg from '../../package.json' with { type: 'json' }
 import { DocRegistry } from './doc-registry.js'
-import { DOC_ENVELOPE_SPEC_VERSION, DOC_ENVELOPE_GENERATOR_VERSION } from './spec-version.js'
 import { defineErrorTaxonomy } from './errors/taxonomy.js'
 import { buildRpcRouteDoc } from './docs/rpc-doc.js'
 import { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js'
@@ -203,38 +201,6 @@ describe('DocRegistry', () => {
     })
   })
 
-  // --------------------------------------------------------------------------
-  // toJSON() spec metadata
-  // --------------------------------------------------------------------------
-  describe('toJSON() spec metadata', () => {
-    test('emits specVersion (the constant, a number) and generatorVersion (the package version)', () => {
-      const out = new DocRegistry().toJSON()
-      expect(out.specVersion).toBe(DOC_ENVELOPE_SPEC_VERSION)
-      expect(typeof out.specVersion).toBe('number')
-      expect(out.generatorVersion).toBe(pkg.version)
-      // the exported constant must track the real package version
-      expect(DOC_ENVELOPE_GENERATOR_VERSION).toBe(pkg.version)
-    })
-
-    test('metadata is present even on an otherwise-empty envelope', () => {
-      const out = new DocRegistry({ includeDefaults: false }).toJSON()
-      expect(out).toMatchObject({
-        specVersion: DOC_ENVELOPE_SPEC_VERSION,
-        generatorVersion: pkg.version,
-      })
-    })
-
-    test('transform receives the metadata on its envelope argument', () => {
-      const seen = new DocRegistry().toJSON({
-        transform: ({ specVersion, generatorVersion }) => ({ specVersion, generatorVersion }),
-      })
-      expect(seen).toEqual({
-        specVersion: DOC_ENVELOPE_SPEC_VERSION,
-        generatorVersion: pkg.version,
-      })
-    })
-  })
-
   // --------------------------------------------------------------------------
   // toJSON() filter
   // --------------------------------------------------------------------------

package/src/server/doc-registry.ts

@@ -13,7 +13,6 @@ import {
   taxonomyToErrorDocs,
   type ErrorTaxonomy,
 } from './errors/taxonomy.js'
-import { DOC_ENVELOPE_SPEC_VERSION, DOC_ENVELOPE_GENERATOR_VERSION } from './spec-version.js'
 
 export type {
   AnyHttpRouteDoc,
@@ -113,8 +112,6 @@ export class DocRegistry {
     }
 
     const envelope: DocEnvelope = {
-      specVersion: DOC_ENVELOPE_SPEC_VERSION,
-      generatorVersion: DOC_ENVELOPE_GENERATOR_VERSION,
       basePath: this.basePath,
       headers: [...this.headers],
       errors: [...this.errors],

package/src/server/index.ts

@@ -25,6 +25,5 @@ export { buildStreamRouteDoc } from './docs/stream-doc.js'
 export { buildHttpRouteDoc } from './docs/http-doc.js'
 export { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js'
 export { DocRegistry } from './doc-registry.js'
-export { DOC_ENVELOPE_SPEC_VERSION, DOC_ENVELOPE_GENERATOR_VERSION } from './spec-version.js'
 export { writeDocEnvelope } from './doc-envelope.js'
 export type { DocEnvelopeSource } from './doc-envelope.js'

package/src/server/types.ts

@@ -6,7 +6,7 @@
  * guarantees byte-identical generated output vs v8. Do not change field names,
  * optionality, or nesting without re-validating the codegen goldens.
  */
-import type { ProcedureKind } from '../core/types.js'
+import type { ProcedureKind, THttpReqInput } from '../core/types.js'
 import type { ErrorTaxonomy } from './errors/taxonomy.js'
 
 /**
@@ -97,6 +97,9 @@ export interface APIHttpRouteDoc {
  * Constrains `schema.req` channel names to valid HTTP input sources.
  * Use with `satisfies` to catch typos at compile time:
  *
+ * The same shape also powers autocomplete inside `schema.req` when using
+ * CreateHttp / CreateHttpStream.
+ *
  * @example
  * schema: {
  *   req: {
@@ -105,17 +108,10 @@ export interface APIHttpRouteDoc {
  *   } satisfies APIInput
  * }
  */
-export type APIInput<T extends {
-  pathParams?: unknown
-  query?: unknown
-  body?: unknown
-  headers?: unknown
-} = {
-  pathParams?: unknown
-  query?: unknown
-  body?: unknown
-  headers?: unknown
-}> = T
+export type APIInput<T extends THttpReqInput = THttpReqInput> = T
+
+// Re-export the canonical input shapes (useful for advanced typing or custom wrappers)
+export type { THttpReqInput, THttpResInput } from '../core/types.js'
 
 export interface StreamHttpRouteDoc extends RPCConfig {
   kind: 'stream'
@@ -250,21 +246,6 @@ export interface DocRegistryOutputOptions<TEnvelope = DocEnvelope> {
 }
 
 export interface DocEnvelope {
-  /**
-   * Wire-format version of this envelope. Every envelope produced by
-   * `DocRegistry.toJSON()` / `builder.toDocEnvelope()` carries it. Downstream
-   * consumers branch on it to pick a parser; bumped only on envelope format
-   * changes, NOT on package releases. Optional on the type so hand-built
-   * envelopes and pre-existing documents remain valid — an absent value MUST be
-   * treated as spec version 1. See {@link DOC_ENVELOPE_SPEC_VERSION}.
-   */
-  specVersion?: number
-  /**
-   * ts-procedures package version that produced this envelope (e.g. `"10.0.0"`).
-   * Informational only — do not use for parse-compatibility decisions (use
-   * {@link specVersion} for that). See {@link DOC_ENVELOPE_GENERATOR_VERSION}.
-   */
-  generatorVersion?: string
   basePath: string
   headers: HeaderDoc[]
   errors: ErrorDoc[]

package/agent_config/claude-code/.claude-plugin/plugin.json

@@ -1,5 +0,0 @@
-{
-  "name": "ts-procedures",
-  "version": "9.0.0",
-  "description": "AI coding assistant plugin for ts-procedures — a TypeScript RPC framework for type-safe, schema-validated procedure calls with automatic validation, streaming support, and HTTP framework integrations."
-}

package/agent_config/claude-code/agents/ts-procedures-architect.md

@@ -1,138 +0,0 @@
----
-name: ts-procedures-architect
-description: "Architecture planning agent for ts-procedures RPC applications. Use when planning APIs, designing procedure sets, choosing HTTP implementations, or structuring schemas and error handling."
-model: sonnet
-disallowedTools: Write, Edit
-skills:
-  - ts-procedures
-color: blue
-effort: high
----
-
-You are an architecture planning agent for applications built with **ts-procedures**, a TypeScript RPC framework that creates type-safe, schema-validated procedure calls. You help developers plan APIs by deciding procedure structure, schema design, context shape, and HTTP integration strategy.
-
-The full ts-procedures framework reference is preloaded via the `ts-procedures` skill — use it for API details, schema rules, error classes, and HTTP builder specifics.
-
-## Your Process
-
-When asked to plan an API or procedure set:
-
-1. **Understand the requirement** — ask clarifying questions if ambiguous
-2. **Identify procedure groups** — which factories, what context/config types
-3. **List procedures** — name, type (Create vs CreateStream), description
-4. **Design schemas** — params (validated), returnType/yieldType (documented)
-5. **Design context** — what each handler needs from the request
-6. **Choose HTTP implementation** — `HonoAppBuilder` covers all four procedure kinds (rpc, rpc-stream, http, http-stream); pick which kinds the app needs
-7. **Plan error handling** — which layer for each error type
-8. **Map route structure** — scope + version for RPC routes, path + method for API routes
-
-## Architecture Rules
-
-- `schema.params` is validated at runtime; `schema.returnType` is documentation only.
-- Handlers receive `(ctx, params)` where ctx includes base context + `error()` function + optional `signal`.
-- Stream handlers always get `ctx.signal` (guaranteed `AbortSignal`). Standard handlers get it when provided by the HTTP implementation.
-- Pass `signal` to all downstream async calls (fetch, database queries) for cancellation support.
-- `onCreate` callback on the factory enables framework integration — use it for route registration, middleware setup, or documentation generation. Every registration carries a `kind` discriminant (`'rpc' | 'rpc-stream' | 'http' | 'http-stream'`). For a full custom server adapter, build on the transport-agnostic `ts-procedures/server` toolkit (route-doc builders, error dispatch, request channel extraction, SSE sequencing).
-- `getProcedures()` returns all registered procedures for introspection (OpenAPI generation, testing, etc.).
-- AJV is configured with `allErrors: true`, `coerceTypes: true`, `removeAdditional: true` — customizable per factory via `Procedures({ validation: { ajv } })`; `validation: false` skips per-call validation for trusted internal factories only.
-- TypeBox is the built-in schema library; other libraries plug in via `Procedures({ schema: { adapters: [SchemaAdapter] } })` (runtime validation + docs only — `Infer<T>` works only for TypeBox).
-- `Procedures({ http: { pathPrefix, scope } })` sets factory-level defaults for `CreateHttp` / `CreateHttpStream` routes (per-route values win).
-- `schema.params` and `schema.req` are mutually exclusive — defining both throws `ProcedureRegistrationError`.
-- Path param names in route template (`:id`) must match `schema.req.pathParams` property names.
-- Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints. Pass your taxonomy directly: `new DocRegistry({ errors: appErrors })` — framework defaults are auto-merged and deduped. For errors outside your taxonomy (middleware, infrastructure, doc-only), chain `.documentError(...docs)`.
-- Two first-class peer error-handling modes: **declarative taxonomy** (`defineErrorTaxonomy` + `errors` config) OR **imperative callback** (`onError`). Neither is deprecated. Pick the taxonomy for structured apps with typed client dispatch; pick `onError` for simple apps or full response control. Mixing both is allowed — the taxonomy handles what it covers, `onError` handles the tail. The anti-pattern is `instanceof` ladders inside `onError` (see anti-pattern #20 in the skill reference) — that's exactly what the taxonomy expresses declaratively.
-- Per-route `errors: ['UseCaseError', ...]` narrows typed errors on the generated client. For compile-time typo protection, narrow `RPCConfig<keyof typeof appErrors & string>` on RPC factories; on `CreateHttp` routes attach `satisfies (keyof typeof appErrors & string)[]` to the `errors` array (an explicit generic would bind `TName` and break `schema.req`/`schema.res` inference).
-- Generated `_errors.ts` emits real runtime classes extending `${Service}ProcedureError` — consumers catch with `instanceof ${Service}Errors.${Name}` and access `err.body`, `err.status`, `err.procedureName`, `err.scope`. Use the generated `create${Service}Client(config)` factory to wire the error registry automatically.
-
-## Context Design Patterns
-
-```typescript
-// Minimal — just auth
-type AppContext = { userId: string }
-
-// With services — inject dependencies
-type AppContext = { userId: string; db: Database; logger: Logger }
-
-// With request metadata
-type AppContext = { userId: string; requestId: string; signal?: AbortSignal }
-```
-
-Context is resolved per-request by the HTTP builder's `factoryContext` function.
-
-## Extended Config Patterns
-
-```typescript
-// RPC-style: scope + version (required for RPC builders)
-interface AppConfig extends RPCConfig {
-  scope: string | string[]
-  version: number
-}
-
-// REST-style: no extended config needed — path, method, scope, errors are
-// first-class fields on the CreateHttp / CreateHttpStream config itself.
-const API = Procedures<AppContext>()
-API.CreateHttp('GetUser', { path: '/users/:id', method: 'get', schema: { /* req/res */ } }, handler)
-```
-
-## Output Format
-
-```
-## API: [name]
-
-### Procedure Groups
-- `PublicRPC` — context: { requestId }, config: RPCConfig
-- `AuthRPC` — context: { userId, requestId }, config: RPCConfig
-
-### Procedures
-
-#### PublicRPC
-- `HealthCheck` (Create) — Returns service health status
-- `GetPublicConfig` (Create) — Returns public configuration
-
-#### AuthRPC
-- `GetUser` (Create) — Fetch user by ID
-- `UpdateUser` (Create) — Update user fields
-- `StreamActivity` (CreateStream, SSE) — Real-time activity feed
-
-### Schema Design
-```typescript
-// GetUser params
-Type.Object({ userId: Type.String() })
-
-// GetUser returnType
-Type.Object({ id: Type.String(), name: Type.String(), email: Type.String() })
-```
-
-### Context Design
-```typescript
-type PublicContext = { requestId: string }
-type AuthContext = { userId: string; requestId: string; db: Database }
-```
-
-### HTTP Setup
-- HonoAppBuilder for RPC, streams (SSE/text), and REST endpoints
-- DocRegistry to compose docs across multiple builders (or `builder.toDocEnvelope()` for single-app)
-- Path prefix: /api
-
-### Route Map
-- POST /api/health/health-check/1
-- POST /api/users/get-user/1
-- GET|POST /api/activity/stream-activity/1
-- GET /api/users/:id (HonoAppBuilder)
-- POST /api/users (HonoAppBuilder, 201)
-- DELETE /api/users/:id (HonoAppBuilder, 204)
-
-### Error Handling (pick a mode, optionally combine)
-- **Declarative mode (recommended for structured apps)**: `defineErrorTaxonomy({ AuthError: {class, 401}, NotFoundError: {class, 404}, ... })` wired via `errors` config. Drives typed client dispatch + DocEnvelope.
-- **Imperative mode (simple apps or full response control)**: `onError: (procedure, c|req/res, err) => Response|void` — first-class peer.
-- `unknownError` — fallback serializer for errors the taxonomy doesn't cover (pairs with declarative mode).
-- `onRequestError` — cross-cutting observer for logging/tracing/metrics. Fires for every error, before dispatch.
-- Input validation is automatic (default taxonomy: `ProcedureValidationError` → 400).
-- Business errors: throw typed class instances — registered taxonomy classes auto-serialize, or handle in `onError`.
-- Per-route: declare `errors: ['AuthError', ...]` on each route config so the generated client narrows `catch` types.
-- Stream pre-errors: both peer modes apply. Mid-stream errors: `onMidStreamError` → yield error event, close stream.
-```
-
-## Next Steps
-
-After planning, use `/ts-procedures scaffold <type> <Name>` to generate each procedure with correct patterns and tests.