stitchkit 0.93.0 → 0.94.1

package/llms/contract.txt

@@ -0,0 +1,606 @@
+# stitchkit/contract — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: Contracts  (docs/guide/contracts.md) · API reference: `stitchkit/contract`  (docs/api/reference.md)
+
+Also read:
+- see `llms/server.txt` for the Auth & errors guide
+
+==============================================================================
+# Guide: Contracts  (docs/guide/contracts.md)
+==============================================================================
+
+# Contracts
+
+A **contract** describes a set of operations once — method, path, schemas,
+scope, which transports each is exposed on. From it stitchkit derives the HTTP
+route, the MCP tool, the agent tool and the typed client. One declaration; the
+surfaces cannot drift.
+
+## `defineContract`
+
+```ts
+import { defineContract } from 'stitchkit'
+
+const contract = defineContract(meta, endpoints)
+```
+
+- **`meta`** — `{ prefix: string }`, or `{ prefix: string, scope: string }` to
+  give every endpoint a default scope.
+- **`endpoints`** — a map of `key → endpoint definition`. The key becomes the
+  client method name and the handler name.
+
+`defineContract` throws at definition time if two endpoints declare the same
+`tool.name` on the same transport — a tool-name clash is a bug, caught early.
+
+## An endpoint
+
+```ts
+export const users = defineContract({ prefix: 'users' }, {
+  list: {
+    method: 'GET',
+    path: '/',
+    desc: 'List all users',
+    output: z.array(UserSchema),
+  },
+  create: {
+    method: 'POST',
+    path: '/',
+    desc: 'Create a user',
+    input: CreateUserSchema,
+    output: UserSchema,
+  },
+  get: {
+    method: 'GET',
+    path: '/:id',
+    desc: 'Get a user by id',
+    params: z.object({ id: z.string() }),
+    output: UserSchema,
+  },
+})
+```
+
+### Fields
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `method` | yes | `GET` · `HEAD` · `POST` · `PUT` · `PATCH` · `DELETE` |
+| `path` | yes | route path under the contract `prefix`; `:name` marks a path param and a named terminal `/*filePath` captures the remaining path |
+| `desc` | yes | human description — also the MCP / agent tool description |
+| `params` | no | Zod schema for **path params** (`:id`, …) |
+| `input` | no | Zod schema for the **request body** (or query, for GET/DELETE) |
+| `output` | no | Zod schema for the **response body**; its presence declares a JSON result (`null` is data, `undefined` is not) |
+| `scope` | no | access scope for this endpoint — see [Auth & errors](./auth-and-errors.md) |
+| `expose` | no | which transports carry this endpoint — see [below](#transports) |
+| `tool` | no | what the tool surfaces (MCP / agent / CLI) read that HTTP does not — see [below](#tool-options-tool) |
+| `multipart` | no | typed file fields, cardinality, delivery and upload policy — see [below](#file-uploads) |
+| `maxJsonBodyBytes` | no | per-route JSON body ceiling; overrides the server default |
+| `timeout` | no | per-endpoint client timeout in ms, for slow endpoints |
+| `idempotent` | no | safe to call twice with the same input (like `PUT`/`DELETE`); a retrying transport reads it — see [Realtime](./realtime.md#bring-your-own-transport) |
+| `meta` | no | opaque app metadata — read in hooks / on tool mounts, never in OpenAPI ([below](#endpoint-metadata-meta)) |
+| `rawResponse` | no | the handler returns the `Response` itself — a download, a file, an SSE stream. HTTP-only, never a tool, no `output`. See [Raw-response endpoints](./server.md#raw-response-endpoints) |
+| `rawBody` | no | retain original JSON text for a signed HTTP webhook. See [Signed JSON webhooks](./server.md#signed-json-webhooks) |
+| `responseMeta` | no | make a typed-data endpoint HTTP-only, optionally declare its success status and expose `ctx.response.headers` — [Typed JSON response metadata](./server.md#typed-json-response-metadata) |
+| `contentType` | no | documented response media type of a `rawResponse` endpoint (OpenAPI only) |
+
+`HEAD` is an explicit HTTP-only operation, never an automatic alias for `GET`.
+It must declare `rawResponse: true`; request body, `input`, multipart, `rawBody`,
+typed `output` and tool exposure are rejected. The handler owns status and
+headers, while Stitchkit guarantees an empty wire body even if the returned
+`Response` accidentally contains one.
+
+## `params` vs `input` vs `output`
+
+`output` owns response presence across HTTP and tool transports. With a schema,
+the handler must return a value that validates and can be represented as JSON;
+a nullable schema may return `null`, but `undefined` is always a contract
+violation. Without `output`, the handler is empty (`undefined`/`null`) and may
+not return undeclared data. On HTTP this means a default `200` JSON response
+with output and a default bodyless `204` without it.
+
+The three schemas are distinct on purpose:
+
+- **`params`** — values in the URL path. `path: '/:id'` infers
+  `{ id: string }` and materializes the same Zod string schema for HTTP, OpenAPI,
+  MCP, Agent and CLI. Declare `params: z.object({ id: z.uuid() })` only when the
+  path value needs validation or coercion; an explicit schema must cover every
+  name in the path. The client takes params from the call argument and
+  substitutes them into the URL. A terminal wildcard is explicitly named:
+  `path: '/:slug/*filePath'` matches both
+  `/foo/page` and `/foo/a/b`; the handler reads `ctx.params.filePath` as
+  `'page'` or `'a/b'`. Bare `/*`, invalid/duplicate names and a wildcard before
+  the final segment fail at contract definition.
+- **`input`** — the request payload. For `POST` / `PUT` / `PATCH` it is the JSON
+  body; for `GET` / `DELETE` it is the query string. The handler reads it as
+  `ctx.input`.
+- **`output`** — the response shape. When set, the client parses the response
+  through it; the handler's return value is type-checked against it.
+
+The typed client merges `params` and `input` into one argument object — the
+caller passes a single flat object, the client routes each field to the path or
+the body.
+
+```ts
+// path: '/:id' infers params: { id: string }; input: { text }
+await api.update({ id: '1', text: 'new' })   // PUT /users/1  body: { text: 'new' }
+
+// path: '/:slug/*filePath', params: { slug, filePath }
+await api.app({ slug: 'foo', filePath: 'a/b' })   // GET /apps/foo/a/b
+```
+
+### Input vs. output types
+
+For the client, an endpoint's argument type is the schema's **input** type
+(pre-parse). A field with `.default()` is therefore optional for the caller but
+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()` for numbers and `z.stringbool()` for booleans in a
+query-input schema (not `z.coerce.boolean()`, which is `Boolean(str)`, so
+`'false'` would become `true`).
+
+## Transports
+
+By default an endpoint is exposed on **every** surface — HTTP, MCP and agent
+tools. Narrow it with `expose`:
+
+```ts
+{
+  method: 'POST', path: '/', desc: 'Internal sync',
+  expose: ['HTTP'],            // HTTP only — not an MCP or agent tool
+}
+{
+  method: 'GET', path: '/search', desc: 'Search the catalog',
+  expose: ['HTTP', 'MCP', 'AGENT'],   // explicit — all three
+}
+```
+
+- `expose: ['HTTP']` — HTTP only. The endpoint never becomes a tool.
+- `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
+- omit `expose` — all transports.
+
+For a curated or security-sensitive tool surface, opt into explicit tool
+exposure at the scoped factory:
+
+```ts
+const { defineContract } = createContractFactory<AppScope>({
+  toolExposure: 'explicit',
+})
+```
+
+With this policy, omitting `expose` materializes `['HTTP']` on the returned
+endpoint. MCP, Agent and CLI then require an explicit endpoint array. The plain
+factory and `defineContract` keep the default-on behaviour above.
+
+Consequently, `expose: ['HTTP']` is redundant inside a factory configured with
+`toolExposure: 'explicit'`: omit it unless the explicit spelling is useful to a
+local reader. Add `MCP`, `AGENT` or `CLI` only on endpoints that intentionally
+join those surfaces.
+
+Tool transports (`MCP`, `AGENT`) skip four kinds of endpoint automatically:
+`multipart` (a file upload is not a tool call),
+[`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
+a tool result cannot carry — it would serialize to `{}`),
+[`responseMeta`](./server.md#typed-json-response-metadata) (outbound HTTP
+headers have no meaning on a tool call) and `rawBody` (HTTP-only by
+construction).
+
+## Tool options (`tool`)
+
+Everything a tool surface reads that HTTP does not lives in one group, so an
+endpoint that can never be a tool (a raw response, a stream, `responseMeta`,
+`rawBody`, `HEAD`) refuses all of it with one key:
+
+| `tool.` | Purpose |
+|---------|---------|
+| `name` | explicit tool name (default: a verb-aware derivation, below) |
+| `view` | a different call or answer on MCP / agent / CLI — input defaults alone, or with a projected, separately validated output; declared only with `withToolView` — see [MCP & agents](./mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
+| `ui` | MCP Apps widget for the tool's results — see [MCP & agents](./mcp-and-agents.md) |
+| `annotations` | MCP behavioural hints (`readOnlyHint`, `destructiveHint`, `title`, …) |
+| `mcp` | elicitation rounds asked before the handler runs (`inputRequired`) |
+
+`expose` stays outside the group: it chooses transports, HTTP included.
+Setting `tool` on an endpoint with no tool transport — `expose: ['HTTP']`, or an
+omitted `expose` under a factory with `toolExposure: 'explicit'` — throws at
+definition time. The pre-0.94 top-level keys (`toolName`, `toolView`, `ui`,
+`annotations`, `mcp`) are refused by name, with where each one went.
+
+### `tool.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 `tool.name` for an explicit, stable name:
+
+```ts
+{ method: 'POST', path: '/', desc: 'Create a user', tool: { name: 'create_user' }, /* … */ }
+```
+
+**Every tool name — derived or explicit — must match `[a-zA-Z0-9_-]` and be at
+most 64 characters**, the character class every major provider accepts.
+
+Derivation normalises **per half**, and the halves differ (→ ADR 0035). The
+*service* half collapses everything outside `[a-zA-Z0-9_]` to `_`, hyphen
+included: `bot-status` + `get` ⇒ `get_bot_status`, `admin/analytics` + `get` ⇒
+`get_admin_analytics`. The *method* half keeps its hyphen and normalises only
+what no provider accepts (`[^a-zA-Z0-9_-]`), because a hyphenated method key has
+always shipped a legal name that a client config may already pin: `notes` +
+`get-user` ⇒ `get-user_notes`. An explicit `tool.name` is taken verbatim.
+
+A prefix with *no* usable character at all (`'///'`, `'_'`, a fully non-ASCII
+prefix) and any explicit `tool.name` outside the accepted class **throw at
+mount**. An unusable prefix is rescued by setting an explicit `tool.name` — the
+prefix then never enters the name. An over-long name is fixed by a shorter
+explicit `tool.name` (or a shorter prefix / method key). Nothing downstream checks this: the provider rejects the whole
+request, so one bad name takes every tool of that mount down with it.
+→ [ADR 0035](../decisions/0035-tool-name-derivation-and-validation.md).
+
+## Endpoint metadata (`meta`)
+
+A contract can declare a **default** `meta` that every endpoint inherits, and an
+endpoint's own keys are **shallow-merged over** it:
+
+```ts
+defineContract({ prefix: 'admin', meta: { public: true } }, {
+  list: { method: 'GET', path: '/', desc: 'List', /* meta → { public: true } */ },
+  purge: { method: 'POST', path: '/purge', desc: 'Purge', meta: { rateTier: 2 } },
+  //                                          meta → { public: true, rateTier: 2 }
+})
+```
+
+One level deep — no deep merge. To **opt an endpoint out** of an inherited key,
+declare it with an explicit `undefined`:
+
+```ts
+defineContract({ prefix: 'leads', meta: { page: 'LEADS' } }, {
+  // Public website form inside an otherwise admin-gated contract:
+  submit: { method: 'POST', path: '/', desc: 'Submit', meta: { page: undefined } },
+  //                                       meta → { page: undefined } — gate off
+  list: { method: 'GET', path: '/list', desc: 'List' },   // meta → { page: 'LEADS' }
+})
+```
+
+The key stays *present* with value `undefined`, so read `meta` by **value**
+(`method.meta?.page`), never by key membership. `expose` deliberately has **no**
+contract-level equivalent
+(→ [ADR 0036](../decisions/0036-contract-level-meta.md)).
+
+`meta` is an **opaque, app-defined** bag the core attaches no meaning to — the
+same escape-hatch spirit as `scope` being a free string ([ADR 0002](../decisions/0002-generic-core.md) /
+[ADR 0021](../decisions/0021-endpoint-meta-passthrough.md)). Declare app concerns
+the generic core does not model — a feature gate, a rate tier, a cache hint, a
+doc/owner tag — right next to the endpoint:
+
+```ts
+broadcast: {
+  method: 'POST', path: '/broadcast', desc: 'Send a broadcast',
+  input: BroadcastInput, output: Broadcast,
+  meta: { requiredFeature: 'broadcasts' },   // opaque to the core
+}
+```
+
+It rides through to `MethodDef.meta`, readable in lifecycle hooks (the second
+argument is the endpoint) and on tool mounts. The consumer narrows the type when
+reading:
+
+```ts
+beforeHandle: (ctx, endpoint) => {
+  const feature = endpoint.meta?.requiredFeature
+  if (typeof feature === 'string' && !ctx.user?.features?.includes(feature)) {
+    throw forbidden('feature not enabled')
+  }
+}
+```
+
+`meta` is **app-private** — it is never serialized into the OpenAPI document. It
+can still *drive* generation: `generateOpenApiDocument`'s `includeMethod` reads
+it to curate a public spec (e.g. `meta: { public: true }`), without ever emitting
+`meta` itself — see [Curating the spec](./server.md#curating-the-spec--includemethod).
+
+> **Declare a meta type as a `type`, an inline literal, or with `satisfies` — not
+> an `interface`.** A TS `interface` has no implicit index signature (it can be
+> augmented by declaration merging), so it is not assignable to `meta`'s
+> `Record<string, unknown>` — and on the overloaded `defineContract` the error
+> misleadingly surfaces as a `scope` mismatch. Use
+> `type EndpointMeta = { requiredFeature?: PlanFeature }`, or
+> `meta: { requiredFeature: 'x' } satisfies EndpointMeta`. The read side is
+> unchanged — `endpoint.meta?.x` is `unknown`, narrow it in the hook.
+
+## File uploads
+
+`multipart` is the single source of truth for file fields, cardinality and
+transport-level upload policy. Buffered delivery (the default) gives the
+handler a typed `ctx.files` map:
+
+```ts
+uploadAttachments: {
+  method: 'POST',
+  path: '/:answerId/attachments',
+  desc: 'Upload attachments',
+  params: AnswerIdParamsSchema,
+  input: UploadMetadataSchema,
+  output: UploadedAttachmentsSchema,
+  multipart: {
+    maxRequestBytes: 120 * 1024 * 1024,
+    maxFieldBytes: 64 * 1024,
+    files: {
+      cover: {
+        required: false,
+        maxBytes: 10 * 1024 * 1024,
+        contentTypes: ['image/*'],
+      },
+      attachments: {
+        multiple: true,
+        maxFiles: 8,
+        maxBytes: 20 * 1024 * 1024,
+        contentTypes: ['image/*', 'application/pdf'],
+      },
+    },
+  },
+}
+```
+
+```ts
+uploadAttachments: ({ params, input, files }) => {
+  files.cover        // File | undefined
+  files.attachments  // File[] in multipart order
+}
+```
+
+`required` defaults to `true`; `multiple` defaults to `false`. `maxFiles` is
+valid only for a multiple field. `contentTypes` accepts exact media types and
+validated type wildcards such as `image/*`; it checks the declared multipart
+header, not file contents. Content sniffing, antivirus and storage policy stay
+in the application.
+
+The typed client accepts a web `Blob`/`File` or React Native
+`{ uri, name, type }` descriptor for each single value, and arrays for multiple
+fields. It appends repeated multipart field names in stable order. Undeclared
+file fields, duplicate single fields, missing required fields and wrong part
+kinds fail before the handler. Multipart endpoints are HTTP-only.
+
+Set `delivery: 'stream'` when files must go directly to consumer-owned storage
+without becoming `File` objects in framework memory. The contract descriptor
+stays the same; the implementation supplies receivers with Web streams. 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.stringbool(),       // 'true' → true, 'false' → false
+  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-
+query helper:
+
+```ts
+import { paginatedSchema } from 'stitchkit'
+
+feed: {
+  method: 'GET',
+  path: '/',
+  desc: 'Paginated feed',
+  input: z.object({ limit: z.coerce.number().default(20) }),
+  output: paginatedSchema(PostSchema),   // { items: Post[], nextCursor: string | null }
+}
+```
+
+`paginatedSchema(itemSchema)` produces `{ items, nextCursor }`. The page size
+default lives in the contract (`limit`'s `.default()`), never on the client —
+the two cannot diverge. The client side is [`createCursorQuery`](./client.md#cursor-pagination).
+
+The **format** of `nextCursor` is the server's choice — keep it opaque. For the
+usual keyset cursor (resume after the last row's `(sortValue, id)`), encode it
+with **`encodeCursor`** and read it back with **`decodeCursor`** (Zod-validated;
+a missing or garbage cursor decodes to `null`, i.e. "start from the top"):
+
+```ts
+import { encodeCursor, decodeCursor } from 'stitchkit'
+
+const Cursor = z.object({ v: z.string(), id: z.string() })   // your keyset shape
+
+const after = decodeCursor(ctx.input.cursor, Cursor)         // { v, id } | null
+const rows = await db.list({ after, take: limit + 1 })        // your keyset WHERE
+const nextCursor =
+  rows.length > limit ? encodeCursor({ v: last.createdAt, id: last.id }) : null
+```
+
+The codec is base64url over UTF-8 (`btoa`/`atob`, not Node `Buffer`) — server,
+client and browser safe, and a non-ASCII sort value round-trips. The keyset
+WHERE clause is yours (it's ORM-specific); stitchkit only carries the string.
+
+## Scope
+
+An endpoint may carry a `scope` string; the contract `meta.scope` is the default
+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 mandatory, checked against the union and retained as the 'user' literal
+export const users = defineContract({ prefix: 'users', scope: 'user' }, { … })
+```
+
+The vocabulary is yours; each returned `ScopedContractDef` retains its concrete
+scope literal as a required `meta.scope` field, so scope-aware registries select
+the exact config without `NonNullable` or another wrapper. Plain `ContractDef`
+keeps optional scope because ordinary `defineContract` still supports its
+default-public overload.
+
+The union covers **per-endpoint overrides too**, not just the contract's scope —
+that is where typos are densest, and one there used to compile and then fail
+closed at request time (`[stitchkit] auth: no rule for scope "…"`):
+
+```ts
+defineContract({ prefix: 'posts', scope: 'user' }, {
+  drop: { method: 'DELETE', path: '/:id', desc: 'Drop', scope: 'admn', … },
+  //                                              ^ compile error, and TypeScript
+  //                                                suggests 'admin'
+})
+```
+
+Contracts built with plain `defineContract` are unaffected — their endpoint
+`scope` stays a free string.
+
+## One source of truth
+
+A contract is plain data — no classes, no decorators, no codegen. It is imported
+by the server (to `implement`), by the client (to `createClient`) and by the
+tool layer (to `mountMcp` / `mountAgent`). Change an endpoint and every surface
+is re-typed by the compiler at once.
+
+==============================================================================
+# API reference: `stitchkit/contract`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/contract`
+
+The contract layer alone — browser-and-server safe. All of this is also exported
+from the root `stitchkit`.
+
+### Contract
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
+| `createContractFactory` | function | a `defineContract` whose scope — on the contract **and** on any endpoint override — is required and held to your union, retaining each concrete literal — [guide](../guide/contracts.md#scope) |
+| `ContractFactoryConfig` | _type_ | optional scoped-factory policy, including explicit tool exposure |
+| `ContractFactoryToolExposure` | _type_ | `'explicit'` — omitted endpoint exposure materializes as HTTP-only |
+| `ExplicitScopedDefineContract` | _type_ | scoped factory authoring with explicit tool opt-in |
+| `ExplicitToolExposureEndpoints` | _type_ | endpoint map after missing exposure is materialized as `['HTTP']` |
+| `FactoryScopedEndpoint` | _type_ | an endpoint authored through the factory — its own `scope` override is held to the same union |
+| `ScopedContractDef` | _type_ | a factory-defined contract whose `meta.scope` is the required concrete literal |
+| `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns — endpoint `scope` overrides join the union |
+| `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
+| `TOOL_TRANSPORTS` / `ToolTransport` | constant / _type_ | `['MCP', 'AGENT', 'CLI']` — the transports a model or tool client reads; the one name for a tool surface everywhere (runtime-tool `transports`, invoker, collector, connections) |
+| `ContractDef` | _type_ | a defined contract |
+| `PathParams` | _type_ | infer named `:segments` and a terminal `*wildcard` from a path literal as string params |
+| `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
+| `EndpointDef` | _type_ | a single endpoint definition; `output` declares JSON response presence (`null` is data, `undefined` is invalid); `safelistedBody: true` admits the JSON body as `text/plain` from an allow-listed `Origin` — [guide](../guide/server.md#safelisted-request-bodies-beacons) |
+| `withToolView` | function | declare an endpoint's call and answer on the tool surface (MCP, AGENT, CLI): input `defaults`, and optionally a view `output` and a `project`, typed against the endpoint's own schemas; HTTP keeps the full answer — [guide](../guide/mcp-and-agents.md#a-different-answer-for-tools--withtoolview) |
+| `EndpointToolOptions` | _type_ | an endpoint's `tool` group — `name`, `view`, `ui`, `annotations`, `mcp`: what the tool surfaces read that HTTP does not |
+| `EndpointToolView` | _type_ | the stored shape of a tool view (`MethodDef.toolView`) |
+| `DeclaredToolView` | _type_ | a tool view as `withToolView` produces it — the only form `tool.view` accepts |
+| `WithToolView` | _type_ | the endpoint `withToolView` returns: its own tool options plus the declared view in `tool.view` — name it when a helper returns such an endpoint |
+| `DefaultsOnlyToolView` / `ProjectedToolView` / `ReshapedToolView` / `SlicedToolView` | _type_ | the four forms `withToolView` accepts: input `defaults` alone with the full answer, own schema + `project`, `project` inside the full schema, a slice by `output` |
+| `ToolViewCall` | _type_ | what `project` is told besides the full result: the parsed `input` and the `source` |
+| `ToolViewSliceMismatch` | _type_ | the compile-time refusal of a slice whose schema does not accept the full output |
+| `ToolViewNeedsToolTransport` | _type_ | the compile-time refusal of a view on an `expose: ['HTTP']` endpoint |
+| `EndpointStreamDescriptor` | _type_ | HTTP-only schema-derived stream declaration: item schema, envelope/item framing, stream-end/terminal completion, NDJSON/SSE encoding and frame/lifetime/heartbeat/idle bounds — [guide](../guide/server.md#contract-first-streams) |
+| `HeadEndpointDef` | _type_ | explicit HTTP-only, bodyless `HEAD` endpoint definition |
+| `EndpointResponseMeta` | _type_ | static success metadata declared by an HTTP-only typed-data endpoint |
+| `ResponseMetadata` | _type_ | per-request outbound collector exposed as `ctx.response` only for a `responseMeta` endpoint |
+| `HttpSuccessStatus` | _type_ | supported declared 2xx success statuses |
+| `BodyHttpSuccessStatus` | _type_ | supported 2xx statuses excluding bodyless 204/205 |
+| `HttpMethod` | _type_ | `GET \| HEAD \| POST \| PUT \| PATCH \| DELETE` |
+| `Transport` | _type_ | `HTTP \| MCP \| AGENT \| CLI` |
+| `TransportSource` | _type_ | `http \| mcp \| agent \| cli` — the value of `ctx.source` |
+| `RuntimeContext` | _type_ | the loose context seen by transport and hooks, including optional typed `mcp` metadata |
+| `HandlerContext` | _type_ | the typed context seen by a handler, including optional typed `mcp` metadata |
+| `McpCallContext` | _type_ | validated metadata for the active managed MCP call (`era`, method, tool, client and multi-round fields) |
+| `McpClientInfo` | _type_ | self-reported MCP host name/version; attribution only, never application identity |
+| `McpInputRequiredCall` | _type_ | the parsed `params` / `input` an elicitation resolver chooses its questions from |
+| `McpInputRequiredResolver` | _type_ | `mcp.inputRequired` as a function of the parsed arguments — returns the rounds for this call, or none |
+| `McpProgressUpdate` | _type_ | one mid-call progress update — `message`, and `progress`/`total` when the operation knows a scale |
+| `McpReportProgress` | _type_ | `ctx.reportProgress` — sends one update to the host that asked for progress; a no-op when none did, and never throws |
+| `McpRoundOutcome` | _type_ | managed multi-round attempt outcome |
+| `EndpointHandlerContext` | _type_ | one endpoint handler's fully inferred params, input, files and runtime context |
+| `EndpointFn` | _type_ | the call signature of one client method |
+| `TypedClient` | _type_ | the full typed client for a contract |
+| `TypedHttpClient` | _type_ | the typed client, HTTP endpoints only (`= ScopedHttpClient<C, unknown>`) |
+| `ScopedHttpClient` | _type_ | a client whose `stripPrefixKeys` become required args ([guide](../guide/multi-tenant.md)) |
+| `ScopedEndpointFn` | _type_ | one method's signature with the consumed keys folded in |
+| `TypedUrlBuilder` | _type_ | one contract's HTTP endpoints as synchronous, method-aware URL functions |
+| `ScopedUrlBuilder` | _type_ | a URL builder whose scoped-prefix keys are required method arguments |
+| `ScopedUrlFn` | _type_ | one URL method's signature with scoped-prefix keys folded in |
+| `MultipartFile` | _type_ | a `multipart` file field — `Blob \| FileDescriptor` |
+| `FileDescriptor` | _type_ | a React Native / Expo file — `{ uri, name, type }` |
+| `MultipartDescriptor` | _type_ | file fields, cardinality, delivery and request/text limits |
+| `MultipartFilePolicy` | _type_ | required/multiple, per-file bytes/count and declared MIME policy |
+| `MultipartBufferedFiles` | _type_ | `File` map inferred from a multipart descriptor |
+| `EndpointToolAnnotations` | _type_ | MCP behavioural hints on an endpoint (`readOnlyHint` / `destructiveHint` / `title`) |
+| `EndpointUiMeta` | _type_ | MCP Apps widget metadata on an endpoint |
+| `EndpointMcpInputRequired` | _type_ | typed MCP multi-round input request (`key`, message and Zod object schema) |
+| `EndpointMcpPolicy` | _type_ | MCP-only endpoint policy containing `inputRequired` |
+
+### Errors
+
+| `ErrorVocabularyCode` / `ErrorVocabularyMapping` / `VocabularyCodeMap` | _type_ | application-code union, partial/exhaustive framework mapping input and resolved wire map returned by `defineErrors` |
+| Export | Kind | Summary |
+|--------|------|---------|
+| `AppError` | class | the framework error — `code` / `status` / `details` / `hint` |
+| `ErrorEnvelope` | _type_ | the JSON shape of an error response |
+| `notFound` | function | throw `404 NOT_FOUND` — [guide](../guide/auth-and-errors.md#throwing-errors) |
+| `badRequest` | function | throw `400 BAD_REQUEST` |
+| `unauthorized` | function | throw `401 UNAUTHORIZED` |
+| `forbidden` | function | throw `403 FORBIDDEN` |
+| `conflict` | function | throw `409 CONFLICT` |
+| `rateLimited` | function | throw `429 RATE_LIMITED` |
+| `appError` | function | throw an `AppError` for any code |
+| `defineErrors` | function | declare immutable domain error definitions → typed `AppError` constructors, codes and schemas — [guide](../guide/auth-and-errors.md#domain-errors--defineerrors) |
+| `DefinedErrors` | _type_ | the `{ errors, codes, definitions, isCode, codeMap }` handle `defineErrors` returns |
+| `DefinedAppError` | _type_ | literal-code error instance with schema-refined details |
+| `ErrorDefinition` | _type_ | `{ status, message?, details? }` definition for one domain code |
+| `ErrorDefinitions` | _type_ | string-keyed domain error definition registry |
+| `ErrorDetailsSchema` | _type_ | required or optional Zod object accepted for structured details |
+| `ErrorDetailsOutput` | _type_ | parsed details inferred from one definition |
+| `ErrorFactoryArguments` | _type_ | options tuple with forbidden/required/optional details inferred per code |
+| `ErrorFactory` | _type_ | one typed `AppError` constructor |
+| `ErrorFactories` | _type_ | mapped constructor registry derived from all definitions |
+| `FrozenErrorDefinitions` | _type_ | read-only definition registry returned to consumers |
+| `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? |
+| `isRetryableStatus` | function | whether a status class means "the same call could work later" — `408`, `429`, `502`, `503`, `504`, and deliberately not every `5xx` |
+
+### Pagination
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `paginatedSchema` | function | the `{ items, nextCursor }` Zod schema — [guide](../guide/contracts.md#pagination) |
+| `Paginated` | _type_ | the cursor-pagination envelope |
+| `encodeCursor` | function | encode a keyset value into an opaque `nextCursor` string (base64url, UTF-8-safe) |
+| `decodeCursor` | function | decode + Zod-validate a cursor back to its value (`null` if missing/invalid) |
+
+---