stitchkit 0.17.0 → 0.19.0

package/llms-full.txt

@@ -33,19 +33,23 @@ realtime, `@tanstack/react-query` + `react-query-kit` for React). See
 
 ## Entrypoints
 
-stitchkit ships five entrypoints. Each is import-safe for one environment —
+stitchkit ships eight 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 |
 |--------|--------|-------|
 | `stitchkit` | browser **and** server | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
 | `stitchkit/contract` | browser **and** server | the contract layer alone — `defineContract`, errors, pagination |
-| `stitchkit/server` | server | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
-| `stitchkit/tools` | server | `createMcpHandler`, `mountMcp`, `mountAgent` |
+| `stitchkit/server` | server (Bun) | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
+| `stitchkit/node` | server (Node ≥ 22) | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
+| `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 | the audit layer — `createAuditHook`, trace context, sanitisation |
 | `stitchkit/react` | browser | `createCursorQuery`, `createCacheBridge` |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
-code adds `stitchkit/server` and `stitchkit/tools`.
+code adds `stitchkit/server` (or `stitchkit/node` on Node) and `stitchkit/tools`.
+The full export list of each is in the [API reference](../api/reference.md).
 
 ## Project layout
 
@@ -268,6 +272,26 @@ For the client, an endpoint's argument type is the schema's **input** type
 present (required) in the handler's parsed `ctx.input`. The contract handles the
 two type views; you do not.
 
+### Query input (`GET` / `DELETE`)
+
+`GET` and `DELETE` carry their input as the **query string**, and a query
+string can only encode flat values. An input field on these verbs must be a
+`string`, `number`, `boolean`, or an array of `string` / `number` (repeated
+query keys). A **nested object has no canonical query encoding** — the typed
+client throws on one instead of sending a silently incomplete request:
+
+```ts
+// input: z.object({ q: z.string(), filter: z.object({ … }) })  on a GET
+await api.search({ q: 'x', filter: { status: 'active' } })
+// ✗ throws: GET /: input field "filter" is a nested object — it cannot travel
+//   as a query parameter
+```
+
+Flatten the field (`status: 'active'`) or move the operation to a body verb
+(`POST`). Remember the server parses query values from **strings** — use
+`z.coerce.number()` / `z.coerce.boolean()` in a query-input schema for
+non-string fields.
+
 ## Transports
 
 By default an endpoint is exposed on **every** surface — HTTP, MCP and agent
@@ -293,9 +317,9 @@ file upload is not a tool call.
 
 ## `toolName`
 
-When an endpoint is exposed as a tool, its name defaults to `prefix_key`
-(`users` + `create` ⇒ `users_create`). Set `toolName` for an explicit, stable
-name:
+When an endpoint is exposed as a tool, its name defaults to a verb-aware
+derivation from the method key + prefix (`users` + `create` ⇒ `create_user`,
+`users` + `list` ⇒ `list_users`). Set `toolName` for an explicit, stable name:
 
 ```ts
 { method: 'POST', path: '/', desc: 'Create a user', toolName: 'create_user', /* … */ }
@@ -407,6 +431,21 @@ for every endpoint that declares none. Scopes are free strings — the framework
 attaches no meaning, your auth hook does. See
 [Auth & errors](./auth-and-errors.md).
 
+A plain `defineContract` defaults a missing `scope` to `'public'` — forget it and
+the endpoint is public (fail-open). If every contract in your app must be scoped,
+`createContractFactory` binds your scope vocabulary once and makes `scope`
+**required and typed** — a missing or mistyped scope is a compile error:
+
+```ts
+// app: one line, once
+export const { defineContract } = createContractFactory<'public' | 'user' | 'admin'>()
+
+// scope is now mandatory and checked against the union
+export const users = defineContract({ prefix: 'users', scope: 'user' }, { … })
+```
+
+The vocabulary is yours; the returned contracts are ordinary `ContractDef`s.
+
 ## One source of truth
 
 A contract is plain data — no classes, no decorators, no codegen. It is imported
@@ -831,10 +870,16 @@ const http = createHttpClient({ baseUrl: '/api' })
 | `headers` | — | extra headers — an object, or a function re-run per request |
 | `authEndpoints` | `['auth/']` | paths that should **not** emit `unauthorized` on 401 |
 | `parseError` | built-in | map an error body to `{ code, message, details, hint }` |
+| `trace` | `false` | emit a W3C `traceparent` header on every request |
 
 `headers` as a function is the hook for runtime tokens — a bearer token or any
 short-lived credential — re-evaluated on every request.
 
+`trace: true` mints a fresh root trace per request. The stitchkit server
+[continues an inbound `traceparent`](./observability.md#trace-context), so the
+browser call, the HTTP handler and every nested tool call share one trace id
+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
@@ -1053,6 +1098,27 @@ to a verb-aware name from the method + prefix (`list` → `list_widgets`, `get`
 `get_widget`); set `toolName` for an explicit one. See
 [Contracts → transports](./contracts.md#transports).
 
+### Pinning tool names — `listToolNames`
+
+Derived tool names are part of your public surface — an MCP client config or an
+agent prompt refers to them by string. `listToolNames(services)` resolves every
+tool name your services expose (the exact resolver the mounts use), with its
+`(service, method)` identity and transports, sorted — a stable shape to
+snapshot:
+
+```ts
+import { listToolNames } from 'stitchkit/tools'
+
+test('tool names have not drifted', () => {
+  expect(listToolNames(services)).toMatchSnapshot()
+})
+```
+
+A stitchkit upgrade (or a contract refactor) that would shift a derived name
+now fails this test instead of silently breaking the clients that call the
+tool. It is also the mechanical diff when migrating a service: run it before
+and after, compare.
+
 ## MCP — `createMcpHandler`
 
 `createMcpHandler` builds a complete Streamable-HTTP MCP server as a single
@@ -1393,6 +1459,25 @@ const handleMcp = createMcpHandler({
 })
 ```
 
+## Logging tool calls — `createToolLogger`
+
+Every tool mount fires an `afterToolCall` hook. `createToolLogger` is a ready
+preset for it — one line logs each call (ok / failed, duration, which endpoint,
+keyed by the endpoint's stable `serviceName` / `key` identity):
+
+```ts
+import { createToolLogger } from 'stitchkit/tools'
+
+mountMcp(server, services, { hooks: createToolLogger() })
+// [tool] ok list_widgets (widgets.list) 12ms
+// [tool] warn get_widget (widgets.get) NOT_FOUND 4ms
+```
+
+Pass `log` to redirect the line, or `onRecord` to feed a metrics sink the
+structured `ToolCallRecord`. For a boot-time picture of what is exposed where,
+`summarizeTransports(services)` returns per-transport operation counts (HTTP /
+MCP / AGENT / CLI) for you to log.
+
 ## One handler, three callers
 
 A contract handler runs the same for an HTTP request, an MCP tool call and an
@@ -1811,6 +1896,35 @@ onSuccess: () => bridge.markFresh(['notes'])
 to the socket and call `queryClient` directly. The bridge just centralises the
 event-to-cache mapping and the echo guard.
 
+### Entity cache handlers
+
+The created / updated / deleted events of one entity almost always patch the
+cache the same way: prepend to the list, replace by id, remove by id — plus the
+detail query. `createEntityCacheHandlers` builds those three handlers from a
+small config, so you wire them onto the bridge instead of hand-rolling the
+updater per entity:
+
+```ts
+import { createEntityCacheHandlers } from 'stitchkit/react'
+
+const widgetCache = createEntityCacheHandlers<Widget>({
+  getId: (w) => w.id,
+  listKey: ['widgets'],
+  detailKey: (id) => ['widgets', id],
+})
+
+createCacheBridge({ socket, queryClient, handlers: {
+  widgetCreated: widgetCache.created,
+  widgetUpdated: widgetCache.updated,
+  widgetDeleted: widgetCache.deleted,
+}})
+```
+
+It patches stitchkit's `Paginated<T>` list envelope (plain or an infinite list
+of pages) and honours the same `isFresh` echo guard. It deliberately does **not**
+flatten pages or add a `useAllX` surface — flattening stays in the component;
+this only keeps the cache correct.
+
 ## Raw binary lane (Bun)
 
 Socket.IO carries binary fine — for most streams a binary event (`pcm(frame)`)
@@ -2195,6 +2309,54 @@ onError: (ctx, err) => {
 }
 ```
 
+## Domain errors — `defineErrors`
+
+Declaring your app's error codes once gives you typed throwers on the server and
+a code table the client matches with autocomplete — instead of reading the raw
+`message` string (which breaks the moment a code expects a string but gets an
+object):
+
+```ts
+export const { errors, codes, isCode } = defineErrors({
+  SESSION_NOT_FOUND: 404,
+  QUOTA_EXCEEDED: 429,
+})
+
+// server — a typed thrower, the right HTTP status baked in
+throw errors.SESSION_NOT_FOUND('no such session')
+
+// client — match the code, never a magic string
+if (err instanceof ApiError && err.code === codes.SESSION_NOT_FOUND) { … }
+```
+
+The `code` rides through unchanged in both the HTTP envelope and the MCP tool
+result, so one vocabulary covers every transport. The codes are yours; the core
+stays domain-free.
+
+## `createErrorHook`
+
+`createErrorHook` is the code-map above, packaged — you supply the exhaustive
+`codeMap` and the envelope shape, it does the normalisation (including the
+never-leak-an-internal-message rule for a raw throw):
+
+```ts
+const onError = createErrorHook({
+  codeMap: {
+    BAD_REQUEST: 'bad_request', VALIDATION_ERROR: 'bad_request',
+    UNAUTHORIZED: 'unauthenticated', FORBIDDEN: 'forbidden',
+    NOT_FOUND: 'not_found', METHOD_NOT_ALLOWED: 'not_found',
+    CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
+    INTERNAL_SERVER_ERROR: 'internal',
+  } satisfies Record<StitchErrorCode, string>,
+  render: (info) => ({ ok: false, error: { code: info.code, message: info.message } }),
+})
+
+createServer({ services, hooks: { onError } })
+```
+
+Codes you threw yourself (not stitchkit's) pass through `codeMap` unchanged; the
+`satisfies Record<StitchErrorCode, …>` keeps the map exhaustive across upgrades.
+
 
 ==============================================================================
 # Guide: Observability  (docs/guide/observability.md)
@@ -2361,6 +2523,17 @@ You rarely call the trace functions directly — `wrapInRequestContext` and
 `parseTraceparent`, `formatTraceparent`, `childSpan`) for when you need to
 propagate a `traceparent` onward to another service.
 
+The browser side starts the trace:
+[`createHttpClient({ trace: true })`](./client.md#httpclientconfig) emits a
+fresh root `traceparent` on every request, which the server then continues. The
+trace helpers themselves are browser-safe and also exported from the root
+`stitchkit` entry — a custom client can format its own header.
+
+The default CORS allow-list already permits `traceparent` / `tracestate`, so a
+cross-origin `trace: true` client works out of the box. If you set a custom
+`cors.headers`, extend `DEFAULT_CORS_ALLOW_HEADERS` rather than replacing it, or
+the preflight will reject the trace header.
+
 > **Span ids live in the request context, not on `ctx`.** The handler `ctx`
 > carries a single `traceId`; the full `{ traceId, spanId, parentSpanId }` is on
 > the observability request context. To stamp `spanId` / `parentSpanId` into an
@@ -2859,6 +3032,20 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
 
+### Trace (client)
+
+Browser-safe W3C trace helpers — the same functions as on
+[`stitchkit/observability`](#stitchkitobservability), re-exported so a client
+can emit / propagate a `traceparent` (see `HttpClientConfig.trace`).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createTraceContext` | function | a fresh root trace |
+| `formatTraceparent` | function | render a `traceparent` header value |
+| `parseTraceparent` | function | parse a `traceparent` header |
+| `childSpan` | function | a child span of a parent trace |
+| `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId? }` |
+
 ---
 
 ## `stitchkit/contract`
@@ -2871,6 +3058,8 @@ from the root `stitchkit`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
+| `createContractFactory` | function | a `defineContract` with a required, typed `scope` — [guide](../guide/contracts.md#scope) |
+| `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns |
 | `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
 | `ContractDef` | _type_ | a defined contract |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` |
@@ -2887,6 +3076,8 @@ from the root `stitchkit`.
 | `ScopedEndpointFn` | _type_ | one method's signature with the consumed keys folded in |
 | `MultipartFile` | _type_ | a `multipart` file field — `Blob \| FileDescriptor` |
 | `FileDescriptor` | _type_ | a React Native / Expo file — `{ uri, name, type }` |
+| `EndpointToolAnnotations` | _type_ | MCP behavioural hints on an endpoint (`readOnlyHint` / `destructiveHint` / `title`) |
+| `EndpointUiMeta` | _type_ | MCP Apps widget metadata on an endpoint |
 
 ### Errors
 
@@ -2901,6 +3092,9 @@ from the root `stitchkit`.
 | `conflict` | function | throw `409 CONFLICT` |
 | `rateLimited` | function | throw `429 RATE_LIMITED` |
 | `appError` | function | throw an `AppError` for any code |
+| `defineErrors` | function | declare domain error codes → typed throwers + a code table — [guide](../guide/auth-and-errors.md#domain-errors--defineerrors) |
+| `DefinedErrors` | _type_ | the `{ errors, codes, isCode }` handle `defineErrors` returns |
+| `ErrorThrower` | _type_ | one `defineErrors` thrower — `(message?, details?, hint?) => never` |
 | `STITCH_ERROR_STATUS` | const | `code → HTTP status` map for stitchkit's own error codes — [guide](../guide/auth-and-errors.md#stitch-codes-vs-your-codes) |
 | `StitchErrorCode` | _type_ | a code stitchkit itself emits (`keyof STITCH_ERROR_STATUS`) |
 | `isStitchErrorCode` | function | type guard — is a code one of stitchkit's own? |
@@ -2956,14 +3150,22 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createAuthHook` | function | a scope-enforcing `beforeHandle` hook — [guide](../guide/auth-and-errors.md#createauthhook) |
+| `createErrorHook` | function | an `onError` hook from a code map + envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
+| `ErrorHookConfig` | _type_ | config for `createErrorHook` |
+| `ResolvedError` | _type_ | the normalised error handed to `createErrorHook`'s `render` |
 | `createBearerResolver` | function | a bearer-token identity resolver |
+| `signJwt` | function | sign an HS256 JWT |
 | `verifyJwt` | function | verify an HS256 JWT |
 | `extractToken` | function | read a bearer token from header or cookie |
+| `deriveCodeChallenge` | function | PKCE — derive the `code_challenge` from a verifier |
+| `verifyPkce` | function | PKCE — verify a verifier against a stored challenge |
 | `AuthHook` | _type_ | the hook `createAuthHook` returns |
 | `AuthHookConfig` | _type_ | config for `createAuthHook` |
 | `AuthRule` | _type_ | `'public' \| 'authenticated' \| predicate` |
 | `BearerResolverConfig` | _type_ | config for `createBearerResolver` |
 | `JwtPayload` | _type_ | a decoded JWT payload |
+| `SignJwtOptions` | _type_ | options for `signJwt` (expiry, claims) |
+| `PkceMethod` | _type_ | the PKCE challenge method — `'S256' \| 'plain'` |
 
 ### Cookies & CORS
 
@@ -2974,6 +3176,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `serializeCookie` | function | build a `Set-Cookie` value |
 | `corsHeaders` | function | compute CORS response headers |
 | `corsPreflightResponse` | function | build a preflight `Response` |
+| `DEFAULT_CORS_ALLOW_HEADERS` | const | the default `Access-Control-Allow-Headers` (incl. `traceparent`) — extend it when overriding `cors.headers` |
 | `CookieDef` | _type_ | the `defineCookie` handle |
 | `CookieOptions` | _type_ | cookie attributes |
 | `CorsConfig` | _type_ | CORS policy |
@@ -3006,9 +3209,11 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `generateTraceId` | function | a fresh trace id |
 | `resolveTraceId` | function | the default per-request trace-id resolver |
 | `extractIp` | function | the caller IP from a request |
+| `resolveSocketIp` | function | the caller IP for a Socket.IO handshake (proxy-aware) |
 | `getClientInfo` | function | caller IP + user-agent |
 | `EventBus` | _type_ | the `createEventBus` handle |
 | `RateLimitConfig` | _type_ | config for `createRateLimiter` |
+| `ClientIpOptions` | _type_ | trusted-proxy config for `extractIp` / `resolveSocketIp` |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
 
 ### OpenAPI
@@ -3048,6 +3253,8 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `getTraceId` | function | the active trace id — pass as `traceId` to `createServer` |
 | `getUserId` | function | the active user id, once auth has resolved it |
 | `setRequestUser` | function | attach the resolved user to the active context |
+| `setRequestEndpoint` | function | attach the resolved endpoint identity to the active context |
+| `setRequestDimensions` | function | attach custom audit dimensions to the active context |
 | `setRequestError` | function | record the error outcome on the active context |
 | `runWithRequestContext` | function | run a function inside a given context |
 | `RequestContext` | _type_ | the per-request record |
@@ -3095,6 +3302,7 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `mountViewFile` | function | a native multimodal "view file" MCP tool |
 | `resolveMedia` | function | resolve a media reference for a tool result |
 | `validateMcpSchemas` | function | assert every tool schema is JSON Schema-compatible — [guide](../guide/mcp-and-agents.md#incompatible-schemas--onincompatibleschema) |
+| `listToolNames` | function | every mounted tool name with its `(service, method)` identity — for name-baseline snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
 | `McpHandlerConfig` | _type_ | config for `createMcpHandler` |
 | `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
 | `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
@@ -3109,10 +3317,98 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `ToolExtend` | _type_ | extra-args extension for `mountMcp` / `mountAgent` |
 | `ToolLifecycle` | _type_ | `beforeHandle` / `afterHandle` gate for tool calls — [guide](../guide/mcp-and-agents.md#guarding-tools--lifecycle) |
 | `ToolCallHooks` | _type_ | `beforeToolCall` / `afterToolCall` observability hooks |
+| `ErrorHintFn` | _type_ | `(toolName, errorCode) => string \| null` — a per-tool recovery hint, shared by every mount |
 | `ToolResult` | _type_ | the result of one tool call |
+| `ToolNameEntry` | _type_ | one `listToolNames` row — `{ name, service, method, transports }` |
 | `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
 | `McpMediaContent` | _type_ | a multimodal MCP content item |
 
+### Native tools
+
+Generic host-supplied tools mounted onto a server — not derived from a contract.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `mountDownload` | function | a "download a URL to disk" tool (SSRF-guarded, size-capped) |
+| `mountUpload` | function | an "upload a local file" tool |
+| `mountWait` | function | a generic `--wait`-style polling tool |
+| `DownloadToolConfig` | _type_ | config for `mountDownload` |
+| `UploadToolConfig` | _type_ | config for `mountUpload` |
+| `WaitToolConfig` | _type_ | config for `mountWait` |
+
+### OAuth 2.1 provider
+
+A native remote-connector auth surface for MCP — [guide](../guide/mcp-and-agents.md#oauth-21--a-native-remote-connector).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `mountOAuthProvider` | function | the OAuth 2.1 provider routes (DCR, PKCE, token) |
+| `oauthProtectedResourceRoute` | function | the RFC 9728 protected-resource-metadata route |
+| `protectedResourceMetadataUrl` | function | build the metadata URL for a resource |
+| `wwwAuthenticateHeader` | function | build the `WWW-Authenticate` challenge header |
+| `PROTECTED_RESOURCE_PATH` | const | the well-known metadata path |
+| `OAuthProviderConfig` | _type_ | config for `mountOAuthProvider` |
+| `ProtectedResourceConfig` | _type_ | config for `oauthProtectedResourceRoute` |
+| `AuthCodeData` | _type_ | a stored authorization-code record |
+| `AuthRequest` | _type_ | a parsed authorization request |
+| `ClientMetadata` | _type_ | dynamic-client-registration metadata |
+| `RefreshData` | _type_ | a stored refresh-token record |
+| `RegisteredClient` | _type_ | a registered OAuth client |
+
+### MCP Apps (widgets)
+
+Interactive MCP resources — [ADR 0019](../decisions/0019-generic-native-tools.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `mountMcpResource` | function | mount an MCP Apps widget resource |
+| `inlineMcpAppBundle` | function | inline a built widget bundle into a resource |
+| `EXT_APPS_BUNDLE_PLACEHOLDER` | const | the placeholder token `inlineMcpAppBundle` replaces |
+| `RESOURCE_MIME_TYPE` | const | the MCP Apps resource MIME type |
+| `McpResourceDef` | _type_ | an MCP Apps resource definition |
+| `McpAppResourceMeta` | _type_ | resource `_meta` for an MCP App |
+| `McpAppCsp` | _type_ | the widget content-security policy |
+
+### Introspection & internals
+
+Advanced building blocks — the shared machinery the mounts are built on.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `collectTools` | function | resolve a service's methods to mountable tools (the shared resolver) |
+| `createToolLogger` | function | a ready `afterToolCall` that logs every tool call — [guide](../guide/mcp-and-agents.md#logging-tool-calls--createtoollogger) |
+| `summarizeTransports` | function | per-transport operation counts for a boot-time summary |
+| `buildToolManifest` | function | a searchable `{ name, description, inputSchema }` manifest for a `tool_search` tool |
+| `ToolLoggerConfig` | _type_ | config for `createToolLogger` |
+| `ToolCallRecord` | _type_ | the structured record `createToolLogger` passes to `onRecord` |
+| `TransportSummary` | _type_ | the result of `summarizeTransports` |
+| `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
+| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
+| `flattenDiscriminatedUnion` | function | flatten one discriminated union into a single object schema |
+| `flattenUnionsDeep` | function | flatten discriminated unions at every depth (advertised schema only) |
+| `MountableTool` | _type_ | one contract method resolved for mounting |
+| `ToolManifestEntry` | _type_ | one `buildToolManifest` row |
+
+---
+
+## `stitchkit/node`
+
+Server-only, for Node ≥ 22 (Bun uses `stitchkit/server`). The runtime-agnostic
+core plus a Node HTTP adapter — [ADR 0013](../decisions/0013-runtime-agnostic-core.md),
+[deployment guide](../guide/testing-and-deployment.md#node). Re-exports the
+runtime-agnostic pieces of `stitchkit/server` and the error helpers.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `serveNode` | function | build the router and start a Node HTTP server (via `srvx`) |
+| `createHandler` | function | the router as a bare `(req) => Response` (same as `/server`) |
+| `createSocketIOServer` | function | the typed Socket.IO server (same as `/server`) |
+| `implement` / `createImplement` | function | bind a contract to typed handlers (same as `/server`) |
+| `NodeServerConfig` | _type_ | config for `serveNode` |
+| `NodeServerHandle` | _type_ | the `serveNode` handle (`{ port, stop }`) |
+| `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` / `SocketIOServerConfig` / `SocketIOServerHandle` | _type_ | re-exported from `/server` |
+| `AppError` + `appError` / `badRequest` / `unauthorized` / `forbidden` / `notFound` / `conflict` / `rateLimited` | — | error helpers (same as `/contract`) |
+
 ---
 
 ## `stitchkit/cli`
@@ -3147,6 +3443,10 @@ and `react-query-kit` peers.
 |--------|------|---------|
 | `createCursorQuery` | function | a cursor-paginated infinite query — [guide](../guide/client.md#cursor-pagination) |
 | `createCacheBridge` | function | sync socket events into the Query cache — [guide](../guide/realtime.md#cache-bridge) |
+| `createEntityCacheHandlers` | function | created/updated/deleted cache handlers for one entity — [guide](../guide/realtime.md#entity-cache-handlers) |
+| `EntityCacheConfig` | _type_ | config for `createEntityCacheHandlers` |
+| `EntityCacheHandlers` | _type_ | the `{ created, updated, deleted }` handlers it returns |
+| `DeletedPayload` | _type_ | a `deleted` event payload — the entity or a bare `{ id }` |
 | `CursorQueryConfig` | _type_ | config for `createCursorQuery` |
 | `CacheBridge` | _type_ | the `createCacheBridge` handle |
 | `CacheBridgeConfig` | _type_ | config for `createCacheBridge` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "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",