stitchkit 0.18.0 → 0.20.0

package/dist/tools.js

@@ -2,7 +2,10 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-yv93m4yr.js";
+} from "./index-ynnh9x6h.js";
+import {
+  DEFAULT_CORS_ALLOW_HEADERS
+} from "./index-tje0q6gp.js";
 import {
   coerceJsonArgs,
   collectTools,
@@ -15,19 +18,19 @@ import {
   pollUntil,
   readCapped,
   toolResultFromError
-} from "./index-akv8rk4w.js";
+} from "./index-xmncnw8z.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
 import {
   AppError,
   isWithinDir
-} from "./index-ktn76xz0.js";
+} from "./index-ng2v2ts4.js";
 import"./index-khwedj16.js";
 import {
   isRecord,
   typedEntries
-} from "./index-tm7dqzxc.js";
+} from "./index-c7nyw0yt.js";
 
 // src/tools/agent.ts
 import { tool, zodSchema } from "ai";
@@ -319,7 +322,7 @@ function wwwAuthenticateHeader(resource) {
 var PUBLIC_CORS = {
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "GET, OPTIONS",
-  "Access-Control-Allow-Headers": "Authorization, Content-Type"
+  "Access-Control-Allow-Headers": DEFAULT_CORS_ALLOW_HEADERS
 };
 function oauthProtectedResourceRoute(config) {
   const body = JSON.stringify({
@@ -599,7 +602,7 @@ import { randomUUID as randomUUID2 } from "node:crypto";
 var PUBLIC_CORS2 = {
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-  "Access-Control-Allow-Headers": "Authorization, Content-Type"
+  "Access-Control-Allow-Headers": DEFAULT_CORS_ALLOW_HEADERS
 };
 var AS_METADATA_PATH = "/.well-known/oauth-authorization-server";
 var AUTH_CODE_TTL_MS = 60000;
@@ -895,6 +898,12 @@ function withTimeout(options, timeout) {
     return options;
   return { ...options, timeout };
 }
+function withOutput(endpoint, result) {
+  const schema = endpoint.output;
+  if (!schema)
+    return result;
+  return result.then((value) => value === undefined ? undefined : schema.parse(value));
+}
 function isParamArray(value) {
   return Array.isArray(value) && value.every((v) => typeof v === "string" || typeof v === "number");
 }
@@ -958,18 +967,21 @@ function createHttpMethod(endpoint, prefix, client, config) {
       if (!isMultipartFile(file)) {
         throw new Error(`Missing multipart file field: ${endpoint.multipart}`);
       }
+      if (httpMethod === "get" || httpMethod === "delete") {
+        throw new Error(`Multipart endpoint ${endpoint.method} ${endpoint.path} must be POST / PUT / PATCH`);
+      }
       const formData = new FormData;
       appendMultipartFile(formData, endpoint.multipart, file);
       appendFormFields(formData, firstArg, new Set([...prefixKeys, endpoint.multipart]));
-      return client.post(url, formData, withTimeout(undefined, endpoint.timeout));
+      return withOutput(endpoint, client[httpMethod](url, formData, withTimeout(undefined, endpoint.timeout)));
     }
     if (isGet) {
       const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return client.get(url, withTimeout(params ? { params } : undefined, endpoint.timeout));
+      return withOutput(endpoint, client.get(url, withTimeout(params ? { params } : undefined, endpoint.timeout)));
     }
     if (httpMethod === "delete") {
       const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return client.delete(url, withTimeout(params ? { params } : undefined, endpoint.timeout));
+      return withOutput(endpoint, client.delete(url, withTimeout(params ? { params } : undefined, endpoint.timeout)));
     }
     const payload = {};
     for (const [key, value] of Object.entries(firstArg)) {
@@ -977,7 +989,7 @@ function createHttpMethod(endpoint, prefix, client, config) {
         payload[key] = value;
       }
     }
-    return client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint.timeout));
+    return withOutput(endpoint, client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint.timeout)));
   };
 }
 function createFetchMethod(endpoint, prefix, config, contractConfig) {
@@ -994,6 +1006,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       Accept: "application/json",
       ...typeof config.headers === "function" ? config.headers() : config.headers
     };
+    const signal = endpoint.timeout !== undefined ? AbortSignal.timeout(endpoint.timeout) : undefined;
     const isQuery = inputIsQuery(endpoint.method);
     const hasBody = !isQuery && !endpoint.multipart && endpoint.input && args;
     if (isQuery && args) {
@@ -1026,7 +1039,8 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
         method: endpoint.method,
         headers,
         credentials: config.credentials,
-        body: formData
+        body: formData,
+        signal
       });
       if (!res2.ok) {
         await throwForErrorResponse(res2, config, null);
@@ -1040,6 +1054,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       method: endpoint.method,
       headers,
       credentials: config.credentials,
+      signal,
       ...hasBody && {
         body: JSON.stringify(stripParams(hasBody, endpoint.path, prefixKeys))
       }
@@ -1165,6 +1180,26 @@ function implementRemote(contract, http, options) {
     methods
   };
 }
+// src/tools/tool-logger.ts
+function createToolLogger(config = {}) {
+  const log = config.log ?? ((line) => console.info(line));
+  return {
+    afterToolCall: (toolName, _args, result, durationMs, context, endpoint) => {
+      const record = {
+        tool: toolName,
+        service: endpoint.serviceName,
+        action: endpoint.key,
+        ok: result.ok,
+        code: result.ok ? undefined : result.code,
+        durationMs: Math.round(durationMs),
+        source: String(context.source)
+      };
+      const codePart = result.ok ? "" : ` ${result.code}`;
+      log(`[tool] ${result.ok ? "ok" : "warn"} ${toolName} (${endpoint.serviceName}.${endpoint.key})${codePart} ${record.durationMs}ms`);
+      config.onRecord?.(record);
+    }
+  };
+}
 // src/tools/toolkit.ts
 function createToolkit() {
   return {
@@ -1176,6 +1211,29 @@ function createToolkit() {
     createCli: (config) => createCli(config)
   };
 }
+// src/tools/transports.ts
+var TOOL_TRANSPORTS2 = ["MCP", "AGENT", "CLI"];
+function emptyCounts() {
+  return { HTTP: 0, MCP: 0, AGENT: 0, CLI: 0 };
+}
+function summarizeTransports(services) {
+  const totals = emptyCounts();
+  const perService = services.map((service) => {
+    const counts = emptyCounts();
+    for (const method of Object.values(service.methods)) {
+      if (!method.expose || method.expose.includes("HTTP"))
+        counts.HTTP += 1;
+    }
+    for (const transport of TOOL_TRANSPORTS2) {
+      counts[transport] = collectTools(service, transport).length;
+    }
+    for (const transport of Object.keys(counts)) {
+      totals[transport] += counts[transport];
+    }
+    return { service: service.name, counts };
+  });
+  return { services: services.length, totals, perService };
+}
 // src/tools/view-file.ts
 import { readFile, realpath, stat } from "node:fs/promises";
 import { extname as extname2, resolve } from "node:path";
@@ -1301,6 +1359,7 @@ function mountViewFile(server, options = {}) {
 export {
   wwwAuthenticateHeader,
   validateMcpSchemas,
+  summarizeTransports,
   resolveMedia,
   protectedResourceMetadataUrl,
   oauthProtectedResourceRoute,
@@ -1318,6 +1377,7 @@ export {
   flattenUnionsDeep,
   flattenDiscriminatedUnion,
   createToolkit,
+  createToolLogger,
   createStdioMcpServer,
   createMcpHandler,
   createCli,

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
 
@@ -379,6 +383,25 @@ upload: {
 The client sends a `multipart/form-data` request; the field value must be a
 `Blob`. See [HTTP server → multipart](./server.md#multipart).
 
+### Multipart text fields
+
+Any non-file fields sent alongside the file are validated by the endpoint's
+`input` schema. A multipart text field is **always a string** (per the spec) —
+the schema owns its type, exactly as with [query input](#query-input-get--delete):
+
+```ts
+input: z.object({
+  id: z.string(),               // an id like '33111715' stays a string
+  count: z.coerce.number(),     // '5' → 5
+  active: z.coerce.boolean(),   // 'true' → true
+  meta: z.preprocess((v) => JSON.parse(String(v)), MetaSchema),  // opt a field into JSON
+})
+```
+
+The content is never sniffed to guess a type — a field is a string until the
+schema coerces it. Send a JSON blob as a stringified field and parse it with
+`z.preprocess`; do not rely on the framework to auto-decode it.
+
 ## Pagination
 
 Every list endpoint should return the cursor envelope — one shape, one infinite-
@@ -427,6 +450,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
@@ -1440,6 +1478,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
@@ -1858,6 +1915,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)`)
@@ -2242,6 +2328,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)
@@ -2414,6 +2548,11 @@ 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
@@ -2938,6 +3077,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` |
@@ -2954,6 +3095,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
 
@@ -2968,6 +3111,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? |
@@ -3023,14 +3169,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
 
@@ -3041,6 +3195,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 |
@@ -3073,9 +3228,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
@@ -3115,6 +3272,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 |
@@ -3177,11 +3336,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`
@@ -3216,6 +3462,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.18.0",
+  "version": "0.20.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",