stitchkit 0.47.0 → 0.48.1

package/llms-full.txt

@@ -33,7 +33,7 @@ realtime, `@tanstack/react-query` + `react-query-kit` for React). See
 
 ## Entrypoints
 
-stitchkit ships eight entrypoints. Each is import-safe for one environment —
+stitchkit ships nine entrypoints. Each is import-safe for one environment —
 keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
 
 | Import | Use in | Holds |
@@ -45,6 +45,7 @@ keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
 | `stitchkit/tools` | server | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
 | `stitchkit/cli` | server | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
 | `stitchkit/observability` | server | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/testing` | tests on Bun or Node | in-process generated clients over a real Fetch handler, without a TCP port |
 | `stitchkit/react` | browser | `createCursorQuery`, `createCacheBridge` |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
@@ -685,6 +686,30 @@ export const implement = createImplement<AppContext>()
 // every implement() call now has ctx.user typed
 ```
 
+### `implementRegistry` — one backend registry
+
+When contracts already live in one literal registry, bind the backend from that
+same source instead of maintaining a parallel `services` list:
+
+```ts
+import { implementRegistry } from 'stitchkit/server'
+
+export const apiServices = implementRegistry(apiContractRegistry, {
+  users: usersHandlers,
+  posts: postsHandlers,
+})
+```
+
+Every registry key is required, extra keys fail, and each handler map is checked
+against its own contract. The returned service order follows the contract
+registry order. `createImplementRegistry<AppContext>()` fixes the application
+context once, like `createImplement` does for a single contract. Runtime callers
+also fail first on missing/extra keys and duplicate contract prefixes.
+
+The registry is intentionally flat: every key must point to one concrete
+`defineContract()` result. Composed namespace arrays are mounted explicitly with
+`implement()` because they do not have a one-key-to-one-handler-map boundary.
+
 ## `createServer`
 
 `createServer(config)` builds the router and starts `Bun.serve()`. It returns
@@ -991,6 +1016,21 @@ not retain the text. `maxJsonBodyBytes` may also be set once on `createServer` /
 `createHandler`; a route value wins. Both limits are opt-in and abort an
 oversized stream before it is fully buffered. → ADR 0051
 
+### Choosing an HTTP boundary
+
+| Need | Contract declaration | What remains framework-owned |
+|------|----------------------|------------------------------|
+| Typed JSON request/response | ordinary `input` / `output` | routing, auth, schemas, hooks, client, OpenAPI |
+| HMAC-signed JSON | `rawBody: true` + `input` / `output` | the same pipeline plus the exact decoded request text |
+| File upload | typed `multipart` descriptor | file cardinality/limits, text input validation and client form encoding |
+| File, stream or redirect response behind contract auth | `rawResponse: true` | request parsing, route identity, auth and typed URL/client surface |
+| Transport that cannot be expressed as the contract pipeline | `RawRoute` | only raw routing, CORS, request hook and error normalisation |
+
+`rawBody` is for JSON signatures: verify `ctx.rawBody` against the signature
+header, then use the already validated `ctx.input`. A provider-specific binary
+signature protocol, OAuth callback or WebSocket upgrade can be a real raw route,
+but it must own its validation and authorization explicitly.
+
 ## Typed JSON response metadata
 
 A JSON endpoint that must attach dynamic HTTP headers while preserving typed
@@ -1158,6 +1198,13 @@ wildcard — and the two combine: `/app/:slug/*filePath` matches `/app/x/a/b` wi
 deep-link fallback). List more specific routes before the wildcard — the first
 match wins. `staticRoute()` builds a raw route that serves a directory.
 
+At startup Stitchkit rejects exact duplicates, equivalent parameter shapes
+(`/users/:id` vs `/users/:userId`) and any later raw route completely hidden by
+an earlier raw route. Partial overlap stays legal, including the recommended
+specific-before-wildcard order. `GET` and `HEAD` remain independent because that
+is how the actual raw matcher dispatches them. Raw-vs-contract overlap remains a
+startup diagnostic naming the bypassed contract identity and scope.
+
 ### Raw-route helpers
 
 A raw route gives up the contract pipeline, so three things get re-implemented in
@@ -1483,7 +1530,7 @@ without repeating transport configuration.
 | `baseUrl` | — | URL prefix for every request |
 | `timeout` | `30000` | request timeout, ms |
 | `credentials` | `'include'` | fetch credentials mode |
-| `retry` | 2× GET, network errors only | transport retry policy |
+| `retry` | 2 retries after the initial GET; network errors only | transport retry policy |
 | `headers` | — | extra headers — an object, or a function re-run per request |
 | `suppressUnauthorizedFor` | `[]` | exact contract-derived operation matchers whose expected 401 does not emit `unauthorized` |
 | `parseError` | built-in | map an error body to `{ code, message, details, hint }` |
@@ -1509,7 +1556,10 @@ end-to-end. A `traceparent` you set yourself (via `headers`) always wins.
 Retry is deliberately conservative: only a connection that never landed (a
 network error), only on idempotent `GET`. A server that *responded* with a 5xx
 is the data layer's call (TanStack Query), not the transport's — retrying in
-both places multiplies attempts.
+both places multiplies attempts. `retry.limit` counts retries after the initial
+attempt, so the default `2` permits at most three total attempts. The default
+`statusCodes: []` does not replay HTTP responses; explicit `methods` or
+`statusCodes` expand that policy when a project has a proven idempotent case.
 
 ## `createClient`
 
@@ -1560,14 +1610,15 @@ contract:
 
 ### Per-call cancellation
 
-Every endpoint accepts optional `ClientRequestOptions` containing an
-`AbortSignal`. Endpoints with arguments use `(args, options?)`; endpoints with
-no arguments use `(options?)`:
+Every endpoint callable exposes a `withOptions` method accepting required
+`ClientRequestOptions`. The ordinary callable contains only contract arguments,
+so it can be passed directly to callback APIs such as `react-query-kit` without
+mistaking their callback context for Stitchkit transport options:
 
 ```ts
 const controller = new AbortController()
 
-const pending = api.upload(
+const pending = api.upload.withOptions(
   { file: selectedFile, title: 'Draft' },
   { signal: controller.signal },
 )
@@ -1590,6 +1641,12 @@ Abort and timeout do not emit `network_error` and are not retried. The same
 options work for query, JSON, multipart and raw-response calls. Stitchkit does
 not expose upload progress: Fetch has no portable upload-progress primitive.
 
+For an endpoint without contract arguments, pass only the options object:
+
+```ts
+await api.health.withOptions({ signal: controller.signal })
+```
+
 ### Many contracts at once
 
 ```ts
@@ -1823,6 +1880,10 @@ export const useUsers      = createQuery({ queryKey: ['users'], fetcher: () => a
 export const useCreateUser = createMutation({ mutationFn: api.create })
 ```
 
+Generated methods intentionally keep their ordinary call signature limited to
+contract variables. Use `api.create.withOptions(variables, { signal })` only for
+an imperative call that needs per-request cancellation.
+
 ### Cursor pagination
 
 For a cursor-paginated list, `createCursorQuery` is the canonical helper:
@@ -2240,15 +2301,18 @@ validateMcpSchemas({
   extend,
   flattenUnionInput: true,
   requireTypedProperties: true,
-  allowUntyped: ['docs_create.payload'],   // deliberately free-form
   requirePortableFormats: true,
   allowFormats: [],
 })
 ```
 
-Off by default, because a contract may legitimately declare `z.unknown()`.
-`allowUntyped` takes dotted `tool.property` paths — an entry there is a decision,
-anything else is a finding. On `createMcpHandler`, put the policy under
+For an arbitrary **JSON value**, declare `z.json()`: its recursive JSON Schema
+describes strings, numbers, booleans, null, arrays and objects, so strict schema
+validation needs no exception. `z.unknown()` means an unknown runtime value —
+including values JSON cannot represent — and therefore gives a model no usable
+shape. The guard is off by default for existing contracts. `allowUntyped` takes
+dotted `tool.property` paths and is reserved for a presentation value that is
+genuinely impossible to represent as JSON Schema. On `createMcpHandler`, put the policy under
 `schemaValidation`; the handler supplies its real `extend` and
 `flattenUnionInput`, so the check cannot vet a different document from the one
 advertised.
@@ -3970,8 +4034,8 @@ export const observability = createObservability({
   },
 })
 
-await observability.flush()
-await observability.close()
+const status = observability.getStatus()
+const drained = await observability.close()
 ```
 
 `maxPending` defaults to `1000` per sink and must be a positive safe integer.
@@ -3982,9 +4046,15 @@ cancelled. Sink, filter and diagnostic-callback failures remain isolated from
 the observed request or tool call and are reported through `onSinkError` when
 configured; `onSinkError`/`onDrop` cannot create unhandled rejections.
 
+`getStatus()` returns immutable per-surface and aggregate counters: capacity,
+received, accepted, filtered, completed, dropped, failed, preparation failures,
+preparing/pending work and the closed flag. Read it from readiness or metrics
+without parsing callback logs.
+
 `flush()` snapshots the current generation and waits only for events admitted
 up to that call. `close()` atomically stops admission, drains every accepted
-generation and is idempotent. Graceful shutdown order is therefore:
+generation and returns the final counters plus `durationMs`; repeated calls
+return the same report. Graceful shutdown order is therefore:
 
 1. stop HTTP/MCP admission;
 2. wait for active requests and tool calls;
@@ -4420,7 +4490,33 @@ never block or break the request. Swallow the sink's own errors.
 stitchkit's own test suite runs on `bun:test`. The contract makes most of an
 API testable without a live socket.
 
-### Test handlers in process
+### Test generated clients in process
+
+`createHandlerTestClient` runs the real generated client against the real Fetch
+handler without opening a TCP port. It keeps URL construction, headers/cookies,
+multipart encoding, cancellation, output validation, `ApiError` and
+`x-request-id` correlation in the test path:
+
+```ts
+import { createHandlerTestClient } from 'stitchkit/testing'
+
+const api = createHandlerTestClient({
+  contract: notes,
+  handler,
+  pathPrefix: 'api',
+  client: { headers: { cookie: 'session=test' } },
+})
+
+expect(await api.create({ text: 'hi' })).toEqual({ id: '1', text: 'hi' })
+```
+
+`contractConfig` accepts the same scoped `pathPrefix` / `stripPrefixKeys` as
+`createClient`. `createHandlerTestClients` is the batch form for a literal
+contract registry. Both helpers are Fetch-only: they construct ordinary
+absolute `Request` objects and call `createHandler` directly, so Bun and Node
+exercise the same framework pipeline.
+
+### Test handlers with raw Requests
 
 `createHandler` is the router as a plain `(req) => Promise<Response>` function —
 no `Bun.serve`, no port. Drive it with a `Request`:
@@ -4450,8 +4546,8 @@ test('create returns the note', async () => {
 })
 ```
 
-This exercises the full pipeline — routing, schema parsing, hooks, the error
-envelope — with no network.
+This lower-level form exercises the same pipeline while letting a test inspect
+the raw `Response` itself.
 
 ### Test handlers directly
 
@@ -4817,7 +4913,40 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
-## Upcoming migration: `[Unreleased]`
+## Released migration: 0.48.0
+
+### Typed-client request options move to `.withOptions`
+
+Generated endpoint methods reserve their ordinary call signature for contract
+variables. This keeps them directly assignable to callback APIs whose runtime
+supplies its own second context argument, including `react-query-kit` and
+TanStack Query. Move imperative cancellation to the callable's explicit method:
+
+```ts
+// before — endpoint with arguments
+await api.create({ name: 'Max' }, { signal })
+
+// after
+await api.create.withOptions({ name: 'Max' }, { signal })
+
+// before — endpoint without arguments
+await api.health({ signal })
+
+// after
+await api.health.withOptions({ signal })
+```
+
+Direct query and mutation composition remains unchanged:
+
+```ts
+createMutation({ mutationFn: api.create })
+createQuery({ queryKey: ['search'], fetcher: api.search })
+```
+
+There is no positional-options alias. Ordinary generated methods ignore extra
+runtime callback arguments; only `.withOptions` reads `ClientRequestOptions`.
+
+## Released migration: 0.47.0
 
 ### HTTP auth moves to the pre-body `authorize` phase
 
@@ -5584,7 +5713,8 @@ The browser-and-server entrypoint. Re-exports everything from
 | `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
 | `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
 | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
-| `ClientRequestOptions` | _type_ | per-call `{ signal?: AbortSignal }`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
+| `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework testing adapters |
+| `ClientRequestOptions` | _type_ | per-call `{ signal?: AbortSignal }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
@@ -5592,7 +5722,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` and optional readonly `traceId` from `x-request-id` |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
 | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
-| `HttpClientConfig` | _type_ | config for `createHttpClient` |
+| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default — [details](../guide/client.md#createhttpclient) |
 | `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
 | `RequestOptions` | _type_ | per-call options — params, timeout, response type |
 | `HeaderProvider` | _type_ | static or per-request headers |
@@ -5745,6 +5875,11 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `createHandler` | function | the router as a bare `(req) => Response` — [guide](../guide/server.md#createserver) |
 | `implement` | function | bind a contract to typed handlers — [guide](../guide/server.md#implement) |
 | `createImplement` | function | fix the handler context type once |
+| `implementRegistry` | function | bind one exact contract registry to one exact backend handler registry |
+| `createImplementRegistry` | function | context-typed factory for `implementRegistry` |
+| `ImplementationRegistry` | _type_ | flat literal registry of concrete contracts accepted by `implementRegistry` |
+| `RegistryHandlers` | _type_ | exact backend handler registry inferred from a contract registry |
+| `ExactRegistryHandlers` | _type_ | fail-first handler shape that rejects extra registry and endpoint keys |
 | `staticRoute` | function | a raw route that serves a directory |
 | `serveFile` | function | serve a file with `Range` / `304` / `HEAD` — [guide](../guide/server.md#serving-files--range-requests) |
 | `parseByteRange` | function | parse a single `Range` header → range / `unsatisfiable` / `null` |
@@ -5894,7 +6029,11 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `createObservability` | function | configure framework-owned request completion and canonical tool event sinks — [guide](../guide/observability.md#createobservability) |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink |
 | `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
-| `Observability` | _type_ | `{ request?, toolCall, flush(), close() }` with bounded sink lifecycle |
+| `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(), close() }` with bounded sink lifecycle |
+| `ObservabilitySinkStatus` | _type_ | immutable counters for one bounded request/tool sink |
+| `ObservabilityStatus` | _type_ | per-surface plus aggregate operational snapshot |
+| `ObservabilityDrainReport` | _type_ | final closed/drained snapshot plus duration |
+| `ObservabilitySinkStatusSchema` / `ObservabilityStatusSchema` / `ObservabilityDrainReportSchema` | schema | runtime schemas for status/report integration boundaries |
 | `RequestEventSinkConfig` | _type_ | `write`, filter/sanitisation, `maxPending`, `onSinkError` and `onDrop` |
 | `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture |
 | `SinkDropReason` | _type_ | `'capacity' \| 'closed'` |
@@ -5961,7 +6100,7 @@ payload.
 | `createMcpHandler` | function | a stateless dual-era Streamable-HTTP MCP handler — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
 | `createMcpHttpRoute` | function | framework-owned `RawRoute` adapter for an MCP HTTP handler |
 | `createStdioMcpServer` | function | a complete stdio MCP server — [guide](../guide/mcp-and-agents.md#mcp-over-stdio--createstdiomcpserver) |
-| `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces — the transport-neutral core |
+| `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces; no-auth configs omit the second argument |
 | `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
 | `implementRemote` | function | bind a contract to a remote HTTP API — [guide](../guide/mcp-and-agents.md#proxying-a-remote-api--implementremote) |
 | `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
@@ -6123,6 +6262,22 @@ Advanced building blocks — the shared machinery the mounts are built on.
 
 ---
 
+## `stitchkit/testing`
+
+Fetch-only integration helpers that preserve the real generated-client and
+handler pipeline without opening a TCP port.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createHandlerTestClient` | function | one contract client backed by an in-process `FetchHandler` |
+| `createHandlerTestClients` | function | exact contract-registry batch form |
+| `HandlerTestClientDefaults` | _type_ | ordinary bare-client defaults with handler-owned `baseUrl` and `fetch` removed |
+| `HandlerTestClientConfig` | _type_ | handler, contract, path prefix, scoped config and client request defaults |
+| `HandlerTestClientsConfig` | _type_ | batch helper configuration |
+| `HandlerTestTransportConfig` | _type_ | shared in-process handler, origin, prefix, client defaults and optional server handle |
+
+---
+
 ## `stitchkit/node`
 
 Server-only, for Node ≥ 22 (Bun uses `stitchkit/server`). The runtime-agnostic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.47.0",
+  "version": "0.48.1",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -72,6 +72,10 @@
       "types": "./dist/observability/index.d.ts",
       "import": "./dist/observability/index.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
@@ -83,7 +87,7 @@
   "scripts": {
     "check": "bun x tsc --noEmit",
     "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/observability/index.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/testing.ts src/observability/index.ts --outdir dist --target node --packages external --splitting --root src",
     "build:js": "bun run build:browser && bun run build:server",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly",
     "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs",
@@ -161,7 +165,7 @@
     "@types/json-schema": "^7.0.15",
     "@types/react": "^19.2.18",
     "@typescript/typescript6": "^6.0.2",
-    "ai": "^7.0.58",
+    "ai": "^7.0.65",
     "react": "^19.2.8",
     "react-query-kit": "^3.3.4",
     "socket.io": "^4.8.3",