stitchkit 0.93.0 → 0.94.0

package/llms/stitchkit.3.txt

@@ -0,0 +1,147 @@
+# stitchkit — stitchkit docs slice, part 3 of 3
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Parts of this slice:
+- `llms/stitchkit.txt`: Guide: Getting started  (docs/guide/getting-started.md)
+- `llms/stitchkit.2.txt`: Guide: Typed client  (docs/guide/client.md)
+- `llms/stitchkit.3.txt`: API reference: `stitchkit`  (docs/api/reference.md)
+
+Also read:
+- see `llms/contract.txt` for the Contracts guide
+- see `llms/server.txt` for the Realtime guide
+- see `llms/server.txt` for the Auth & errors guide
+
+==============================================================================
+# API reference: `stitchkit`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit`
+
+The browser-and-server entrypoint. Re-exports everything from
+[`stitchkit/contract`](#stitchkitcontract), plus the client and browser realtime.
+
+### Client
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createClient` | function | build a typed client from a contract — [guide](../guide/client.md#createclient) |
+| `createClients` | function | build one exact typed client per contract from a registry; accepts the same scoped config and transports as `createClient` |
+| `createScopedClients` | function | build one registry routed by contract scope; arrays compose contracts into one namespace |
+| `createScopedUrlBuilders` | function | build one URL registry routed by contract scope; arrays compose contracts into one namespace |
+| `ScopeClientConfigs` | _type_ | per-scope routing configuration consumed by scoped clients and URL builders |
+| `ScopedClientRegistry` | _type_ | exact composed registry returned by `createScopedClients` |
+| `ScopedUrlBuilderRegistry` | _type_ | exact composed registry returned by `createScopedUrlBuilders` |
+| `ClientRegistryValue` | _type_ | one contract or a contract array composing one client namespace |
+| `ClientContract` | _type_ | HTTP-client-compatible contract value used by scoped registries |
+| `RegistryScope` | _type_ | contract-scope union inferred from a scoped client registry value |
+| `createUrlBuilder` | function | build synchronous browser-native URLs for all HTTP endpoints; body methods accept URL-bound args only — [guide](../guide/client.md#contract-url-builders) |
+| `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`) |
+| `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework and application-owned 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 |
+| `createHttpClient` | function | the Ky-based HTTP transport; on Next.js SSR its first attempt stays request-memoizable while every retry is a distinct transport attempt — [guide](../guide/client.md#createhttpclient) |
+| `ApiError` | class | a non-2xx or client failure, with `code` / `status` / `details` / `hint`, optional readonly `traceId` from `x-request-id`, and standard `cause` preserving an injected transport failure |
+| `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the exact projection a `VALIDATION_ERROR` carries in `ApiError.details.issues`, so a caller renders one shape. Also on `stitchkit/server`; same name, one definition |
+| `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) — the element type of `details.issues`. Also on `stitchkit/server` |
+| `formatZodError` | function | a `ZodError` → a readable, field-summarised string. Also on `stitchkit/server` |
+| `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`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `fetch` installs an explicit transport and is mutually exclusive with the legacy Bun-only `unix` option — [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 |
+| `ApiEvent` | _type_ | a client event — `unauthorized` / `network_error` / `logout` |
+| `ApiEventListener` | _type_ | an `ApiEvent` handler |
+
+### Realtime (client) & streaming
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createSocketIOClient` | function | low-level typed Socket.IO transport primitive — [guide](../guide/realtime.md#low-level-transport) |
+| `defineRealtimeContract` | function | Zod-first shared Socket.IO event contract — [guide](../guide/realtime.md#zod-first-event-contract) |
+| `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
+| `bindRealtimeClient` | function | bind contract validation and typed acknowledgements to an existing Stitchkit client transport without owning its lifecycle |
+| `createLiveStateController` | function | keep typed application state current across one source-owned snapshot/event generation with finite pre-snapshot buffering, generation fencing and explicit resync — [guide](../guide/realtime.md#snapshot--event-state-synchronization) |
+| `LiveStateController` | _type_ | renderer-neutral `start` / `resync` / `getSnapshot` / `subscribe` / `close` handle |
+| `LiveStateControllerConfig` | _type_ | typed source, reducer, explicit event/byte bounds, event sizing and isolated error hooks |
+| `LiveStateControllerSnapshot` / `LiveStateControllerStatus` | _types_ | current value plus phase, generation, buffer and application/duplicate/gap/refusal counters |
+| `LiveStateControllerStatusSchema` | schema | strict runtime validation for controller status metadata |
+| `LiveStatePhaseSchema` / `LiveStatePhase` | schema / _type_ | `idle`, `opening`, `live`, `resync-required`, `unavailable` or `closed` |
+| `LiveStateStopReasonSchema` / `LiveStateStopReason` | schema / _type_ | explicit gap, overflow, source loss, controller failure and bounded `controller-capacity` reasons |
+| `LiveStateEventDecision` | _type_ | provider-owned reducer result: applied state, duplicate or gap |
+| `LiveStateSource` / `LiveStateSourceOpenInput` / `LiveStateSourceOpenResult` | _types_ | host binding for one continuous snapshot/event boundary; transport retry and cursor semantics remain host-owned |
+| `LiveStateControllerError` / `LiveStateSubscriberError` | _types_ | isolated observer failure payloads that do not change source or subscriber truth |
+| `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
+| `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
+| `parseNDJSON` | function | parse bounded fatal-UTF-8 NDJSON; blank keep-alives are skipped and `finalLine: 'require-newline'` can make the delimiter mandatory — [guide](../guide/client.md#ndjson) |
+| `resumableIterator` | function | re-open a long-lived stream from the last delivered cursor, with jittered backoff, a caller-owned terminal item and prompt abort — [guide](../guide/client.md#resumable-streams) |
+| `createBackoff` | function | exponential backoff with subtractive jitter as a value: `next()` / `reset()` |
+| `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | default on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
+| `ContractStreamFraming` / `ContractStreamCompletion` | _types_ | opt-in item-vs-envelope framing and terminal-vs-stream-end completion policies |
+| `StreamFinalLinePolicy` | _type_ | permissive or newline-required final NDJSON line policy |
+| `DEFAULT_CONTRACT_STREAM_FRAME_BYTES` | const | default maximum encoded contract-stream frame: 256 KiB |
+| `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
+| `SocketIOClientPeerLoaders` | _type_ | inject `socket.io-client` so a bundler can put it in a self-contained artifact |
+| `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
+| `SocketEventMap` | _type_ | the shape of an event map |
+| `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
+| `RealtimeClientOptions` | _type_ | transport options plus rejected-event and metadata-only acknowledged-request phase hooks for `createRealtimeClient` |
+| `BoundRealtimeClient` | _type_ | validated non-owning `on`/`emit`/`request` client with no `connect`/`disconnect` |
+| `RealtimeClientTransport` | _type_ | minimal existing transport capability accepted by `bindRealtimeClient` |
+| `BindRealtimeClientOptions` | _type_ | rejection/logger options for a bound existing transport |
+| `RealtimeAcknowledgedEvent` | _type_ | event-name union restricted to definitions with an `ack` schema |
+| `RealtimeAcknowledgement` | _type_ | validated acknowledgement output inferred from an event definition |
+| `RealtimeRequestArguments` | _type_ | request arguments inferred from an acknowledged event tuple |
+| `RealtimeRequestOptions` | _type_ | finite positive native acknowledgement `timeoutMs` plus an optional invocation-scoped `onPhase` observer |
+| `RealtimeRequestPhaseSchema` / `RealtimeRequestPhase` | schema / _type_ | closed `engine-handoff` / `engine-ack-received` / `settled` / `timeout` / `disconnected` lifecycle |
+| `RealtimeRequestPhaseEventSchema` / `RealtimeRequestPhaseEvent` | schema / _type_ | strict metadata-only `{ requestId, event, phase, elapsedMs }` observation |
+| `RealtimeRequestPhaseHook` | _type_ | isolated sync/async observer accepted globally by `RealtimeClientOptions.onRequestPhase` or per invocation by `RealtimeRequestOptions.onPhase` |
+| `RealtimeRequestTimeoutError` | class | stable `REALTIME_REQUEST_TIMEOUT` rejection |
+| `RealtimeRequestDisconnectedError` | class | stable `REALTIME_REQUEST_DISCONNECTED` rejection, including an immediate disconnected call |
+| `RealtimeRequestInvalidAcknowledgementError` | class | invalid ack was reported through `onRejected` and the request rejected |
+| `RealtimeRequestRejectedError` | class | the peer refused the frame against its own contract and said so — `reason`, `issues` — instead of leaving the sender to time out ([ADR 0106](../decisions/0106-a-refused-frame-answers-its-sender.md)) |
+| `REALTIME_REJECTION_KEY` | const | the reserved acknowledgement key a refusal travels under |
+| `RealtimeRejectionEnvelope` | _type_ | the wire shape of a refusal |
+| `RealtimeRejectionReport` | _type_ | what the sender is told: event, reason, message, issues |
+| `RealtimeRejectionIssue` | _type_ | one refused field, already flattened (`path: '0.v'`) |
+| `asRealtimeRejection` | function | recognise a refusal in an acknowledgement value, validating it |
+| `RealtimeContract` | _type_ | shared server-to-client and client-to-server event registries |
+| `RealtimeEventRegistry` | _type_ | string-keyed registry of event definitions |
+| `RealtimeEventDefinition` | _type_ | one tuple-shaped event and optional acknowledgement schema |
+| `RealtimeEventArguments` | _type_ | tuple inferred from an event definition |
+| `RealtimeEmitArguments` | _type_ | emit arguments including an inferred acknowledgement callback |
+| `RealtimeEventHandler` | _type_ | handler inferred from an event definition |
+| `InferRealtimeEventMap` | _type_ | inferred Socket.IO-compatible event map |
+| `RealtimeRejectDirection` / `RealtimeRejectPhase` / `RealtimeRejectReason` / `RealtimeRejectFault` | _types_ | canonical inferred rejection direction, validation phase, reason and fault classification |
+| `RealtimeRejectedEvent` | _type_ | structured rejected event with event, direction, phase, reason and fault |
+| `RealtimeRejectedEventHook` | _type_ | sync/async observer for structured realtime rejections |
+| `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries; `emit` returns "accepted by the transport" (`false` only for a client-side disconnected drop) |
+| `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
+| `ParseSSEOptions` | _type_ | options for `parseSSE` |
+| `ParseNDJSONOptions` | _type_ | options for `parseNDJSON` |
+| `BackoffPolicySchema` / `BackoffPolicy` | schema / _type_ | `minDelayMs`, `maxDelayMs` and a `0`–`1` jitter fraction; a ceiling below the floor is refused |
+| `Backoff` | _type_ | the backoff handle returned by `createBackoff` |
+| `ResumableIteratorConfig` | _type_ | caller-owned `open` / `advance` / `isTerminal`, retry policy, abort signal and `onAttempt` observer |
+| `ResumableAttempt` | _type_ | attempt number, the delay about to be waited and the error that caused it |
+
+### 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?, tracestate?, baggage? }` |
+
+---

package/llms/stitchkit.txt

@@ -0,0 +1,260 @@
+# stitchkit — stitchkit docs slice, part 1 of 3
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+> Continues in `llms/stitchkit.2.txt`.
+
+Parts of this slice:
+- `llms/stitchkit.txt`: Guide: Getting started  (docs/guide/getting-started.md)
+- `llms/stitchkit.2.txt`: Guide: Typed client  (docs/guide/client.md)
+- `llms/stitchkit.3.txt`: API reference: `stitchkit`  (docs/api/reference.md)
+
+Also read:
+- see `llms/contract.txt` for the Contracts guide
+- see `llms/server.txt` for the Realtime guide
+- see `llms/server.txt` for the Auth & errors guide
+
+==============================================================================
+# Guide: Getting started  (docs/guide/getting-started.md)
+==============================================================================
+
+# Getting started
+
+stitchkit turns one contract into an HTTP API, MCP tools, AI-agent tools and a
+typed client. This page gets a working app running; the rest of the guide goes
+deep on each piece.
+
+## Requirements
+
+- [Bun](https://bun.sh) `>= 1.2` (recommended) or [Node.js](https://nodejs.org)
+  `>= 22`. Bun is first-class; Node is supported via `stitchkit/node`.
+
+## Install
+
+```bash
+bun add stitchkit zod
+```
+
+`zod` is a required peer — schemas are the source of truth everywhere. Other
+peers are optional and pulled in only when you use the matching feature
+(`@modelcontextprotocol/server` for MCP servers, `ai` for agents, `socket.io*` for
+realtime, `@tanstack/react-query` + `react-query-kit` for React). See
+[deps](#dependencies) below.
+
+## Entrypoints
+
+Every entrypoint is import-safe for one environment — keeping server-only code
+(`Bun.serve`, the MCP SDK) out of browser bundles.
+
+Each also declares how settled it is. **Stable** means the shape changes rarely
+and only with a reason worth a migration. **Evolving** means the shape is still
+being found and may be redefined in any minor — always with a
+`### ⚠️ Breaking changes` entry and a migration section, never silently. Both
+are legitimate choices; the difference is how often you should expect to read
+the changelog. Moving an entrypoint from evolving to stable is a decision on its
+own, recorded as an ADR.
+
+| Import | Use in | Maturity | Holds |
+|--------|--------|----------|-------|
+| `stitchkit` | browser **and** server | stable | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
+| `stitchkit/contract` | browser **and** server | stable | the contract layer alone — `defineContract`, errors, pagination |
+| `stitchkit/live` | browser **and** server | evolving | `defineEvents` — topic declarations beside the operation contract — and watched reads: `createWatchClient`, the value/difference frame and its reassembly |
+| `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports |
+| `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
+| `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
+| `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
+| `stitchkit/tools/contract` | browser + server | evolving | the shapes a tool surface speaks — async-operation contract, snapshot and cancel schemas, view-file input/output — without the runtime that serves them |
+| `stitchkit/tools/invoker` | server | stable | peer-free `createToolInvoker` over the canonical contract tool runner |
+| `stitchkit/tools/connections` | server (Bun or Node) | evolving | consume external MCP servers and a bounded OpenAPI subset — typed reauthorization, a per-request host fence and per-call credentials |
+| `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
+| `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
+| `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
+| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification and Bot API send-failure classification |
+| `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
+| `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
+| `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
+| `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
+| `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
+| `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 39 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
+| `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
+| `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 21 of the 39 minors since 0.56.2, most recently 0.94.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
+| `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
+| `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
+| `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
+| `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
+| `stitchkit/agent-runtime/browser` | browser + server | evolving | canonical agent records, events and reconnect cursor without execution or sinks |
+| `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
+| `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
+| `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 39 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
+| `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
+| `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
+| `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |
+
+Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
+code adds `stitchkit/server` (or `stitchkit/node` on Node) and opts into
+`stitchkit/tools`, `stitchkit/remote` or `stitchkit/files` by capability.
+The full export list of each is in the [API reference](../api/reference.md).
+
+## Project layout
+
+A contract is shared by both sides, so it lives in its own folder:
+
+```
+src/
+├── shared/contracts.ts   the contract — imported by server and client
+├── server/index.ts       implement() + createServer()
+└── client/api.ts         createClient()
+```
+
+## A first app
+
+### 1. Define the contract
+
+```ts
+// src/shared/contracts.ts
+import { defineContract } from 'stitchkit'
+import { z } from 'zod'
+
+const Note = z.object({ id: z.string(), text: z.string() })
+
+export const notes = defineContract({ prefix: 'notes' }, {
+  list:   { method: 'GET',  path: '/',    desc: 'List notes',  output: z.array(Note) },
+  create: { method: 'POST', path: '/',    desc: 'Create note', input: z.object({ text: z.string() }), output: Note },
+  get:    { method: 'GET',  path: '/:id', desc: 'Get a note',  params: z.object({ id: z.string() }), output: Note },
+})
+```
+
+### 2. Implement and serve
+
+```ts
+// src/server/index.ts
+import { implement, createServer } from 'stitchkit/server'
+import { notes } from '../shared/contracts'
+
+const service = implement(notes, {
+  list:   ()    => db.list(),
+  create: (ctx) => db.create(ctx.input.text),   // ctx.input is typed
+  get:    (ctx) => db.get(ctx.params.id),       // ctx.params is typed
+})
+
+createServer({ services: [service], port: 3000 })
+```
+
+### 3. Call it, typed
+
+```ts
+// src/client/api.ts
+import { createClient, createHttpClient } from 'stitchkit'
+import { notes } from '../shared/contracts'
+
+export const api = createClient(notes, createHttpClient({ baseUrl: '/api' }))
+
+await api.list()                   // GET  /notes      → Note[]
+await api.create({ text: 'hi' })   // POST /notes      → Note
+await api.get({ id: '1' })         // GET  /notes/1    → Note
+```
+
+Run the server with `bun run src/server/index.ts`. The contract is the single
+source of truth — change it and both the handler and the client are re-typed at
+once.
+
+#### On Node
+
+`createServer` is Bun's `Bun.serve`. On **Node ≥ 22**, swap it for `serveNode`
+(from `stitchkit/node`, built on `srvx`) — the contract, `implement` and the
+client are identical:
+
+```ts
+import { serveNode } from 'stitchkit/node'
+
+serveNode({ services: [service], port: 3000 })
+```
+
+Add `@types/bun` as a dev dependency on Node (an optional peer — it types the
+shared `stitchkit/server` surface). See [deployment](./testing-and-deployment.md#deploy-on-node).
+
+## Dependencies
+
+`ky` is the **only** bundled runtime dependency. Everything else is an *optional
+peer* — your app installs only what the features it uses need, and owns the
+version (one shared instance, no dual-version skew). This matrix is the install
+map — feature → packages:
+
+| Feature you use | Install |
+|-----------------|---------|
+| anything (validation) | `zod` |
+| `createServer` (Bun) | — (uses `Bun.serve`) |
+| `serveNode` (Node ≥ 22) | `srvx` (+ `@types/bun` dev) |
+| In-process contract tools (`stitchkit/tools/invoker`) | — |
+| MCP / agent adapters (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
+| Agent application runtime (`stitchkit/agent-runtime`) | `ai` |
+| Headless Agent harness (`stitchkit/agent-runtime/harness`) | `ai` |
+| Agent coding tools (`stitchkit/agent-runtime/coding-tools`) | — |
+| OpenRouter runtime adapter (`stitchkit/agent-runtime/openrouter`) | `ai` `@openrouter/ai-sdk-provider` |
+| SQLite agent store (`stitchkit/agent-runtime/sqlite/bun` or `/node`) | — (runtime built-in) |
+| MCP host/client tests | `@modelcontextprotocol/client` |
+| MCP Apps UI widgets | `@modelcontextprotocol/ext-apps` |
+| React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
+| MaxMind GeoIP (`stitchkit/geo`) | `maxmind` |
+| Browser OAuth client (`stitchkit/oauth`) | — |
+| Google OIDC verifier (`stitchkit/google`) | `google-auth-library` |
+| **Socket.IO server on Bun** | `socket.io` `@socket.io/bun-engine` |
+| **Socket.IO server on Node** | `socket.io` |
+| Socket.IO client | `socket.io-client` (runtime peer; unrelated root declarations remain peer-free) |
+| grammY lifecycle adapters (`stitchkit/application/grammy`) | `grammy` |
+| Telegram platform primitives (`stitchkit/telegram`) | — (peer-free) |
+| OpenTelemetry gauges (`stitchkit/application/opentelemetry`) | `@opentelemetry/api` |
+
+```bash
+bun add socket.io @socket.io/bun-engine    # e.g. the Socket.IO server on Bun
+```
+
+Dynamic optional-peer adapters fail with an actionable error naming the package
+and install command. Static entrypoints such as `stitchkit/tools` fail during
+ESM resolution by naming the exact missing package; the feature-to-peer matrix
+below is the canonical install command.
+
+The combined tools entry owns MCP and AI-agent adapters, so install both runtime
+peers before importing `stitchkit/tools`:
+
+```bash
+bun add @modelcontextprotocol/server@^2 ai@^7
+```
+
+Browser, HTTP-client and React entrypoints remain usable without either MCP
+package. MCP hosts and client E2E additionally install
+`@modelcontextprotocol/client@^2`; Apps additionally install
+`@modelcontextprotocol/ext-apps`.
+
+## Next
+
+- [Contracts](./contracts.md) — every endpoint field, in depth.
+- [HTTP server](./server.md) — `createServer`, hooks, raw routes, primitives.
+- [Typed client](./client.md) — the client, React data layer, SSE.
+- [MCP & agents](./mcp-and-agents.md) — contracts as AI tools.
+- [Realtime](./realtime.md) — Socket.IO and the cache bridge.
+- [Auth & errors](./auth-and-errors.md) — scopes, auth hooks, the error model.
+- [Browser OAuth and Google OIDC](./oauth.md) — PKCE transaction and verified provider identity.
+- [Testing & deployment](./testing-and-deployment.md).
+- [API reference](../api/reference.md) — every export, by entrypoint.
+
+For a complete production-shaped app, run `bun create stitchkit my-app`. The
+canonical generated topology is maintained in
+[`packages/create-stitchkit/template`](../../packages/create-stitchkit/template).
+
+For a terminal Agent host instead, run
+`bun create stitchkit my-agent --template agent`, copy `.env.example` to `.env`,
+set `OPENROUTER_API_KEY`, then run `bun run dev` and choose a live tool-capable
+model with `/model`. The provider catalog owns the exact model id and context window and presents
+weekly popularity separately from sourced benchmark observations; `OPENROUTER_MODEL` is only an
+optional preferred row. That profile is a thin `stitchkit.agent.ts` composition over the official
+`stitchkit-tui` package and canonical headless harness:
+durable SQLite history, lazy skills, direct coding tools, approval continuations
+and recovery stay framework-owned primitives, while model choice, permissions,
+executables and OS isolation remain application policy.

package/llms/telegram.txt

@@ -0,0 +1,30 @@
+# stitchkit/telegram — 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: API reference: `stitchkit/telegram`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit/telegram`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/telegram`
+
+Peer-free server-only Telegram platform primitives. Importing this resolves no
+bot library; `stitchkit/application/grammy` remains the lifecycle adapter for an
+injected grammY bot. → ADR 0143
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `verifyTelegramInitData` | function | verify a Mini App `initData` signature against the bot token in constant time, before reading anything out of it |
+| `VerifyTelegramInitDataOptions` | _type_ | raw `initData`, bot token, optional `maxAgeSeconds` bound and injected clock |
+| `TelegramInitDataVerification` | _type_ | `{ valid: true, data }` or a refusal carrying its reason |
+| `TelegramInitData` | _type_ | verified `user`/`receiver`, `authDate`, `ageSeconds`, `queryId`, `startParam`, `chatType`, `chatInstance` and every signed pair in `raw` |
+| `TelegramInitDataUser` | _type_ | camelCase user record inferred from Telegram's signed `user` payload |
+| `TelegramInitDataRefusal` | _type_ | `missing-hash` / `signature-mismatch` / `malformed` / `expired` — an expired string is not a forged one |
+| `classifyTelegramSendFailure` | function | name a refused Bot API send and separate "retry this send" from "stop addressing this recipient" |
+| `TelegramSendFailure` | _type_ | reason, `status`, Telegram-stated `retryAfterSeconds`, `retryable`, `recipientUnreachable` and which evidence produced the answer |
+| `TelegramSendFailureReason` | _type_ | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown` |
+
+---