stitchkit 0.100.3 → 0.101.1

package/llms-full.txt

@@ -70,12 +70,12 @@ own, recorded as an ADR.
 | `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 45 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 46 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/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 45 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 46 minors since 0.56.2, most recently 0.97.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 |
@@ -85,7 +85,7 @@ own, recorded as an ADR.
 | `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 10 of the 45 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 46 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `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 |
@@ -2768,8 +2768,8 @@ non-flat field in a `GET` input, and a missing or invalid multipart file. → AD
 0148.
 
 Abort and timeout do not emit `network_error` and are not retried. The same
-options work for query, JSON, multipart and raw-response calls. Stitchkit does
-not expose upload progress: Fetch has no portable upload-progress primitive.
+options work for query, JSON, multipart and raw-response calls. A body call
+also takes `onUploadProgress` — see [Upload progress](#upload-progress).
 
 An injected transport failure is normalized to `UNKNOWN_ERROR` while its exact
 object remains available as `ApiError.cause`. This is how a bounded adapter can
@@ -2784,6 +2784,51 @@ For an endpoint without contract arguments, pass only the options object:
 await api.health.withOptions({ signal: controller.signal })
 ```
 
+### Upload progress
+
+A call with a body can report it leaving:
+
+```ts
+await api.recordings.upload.withOptions(
+  { file, title: 'Take 3' },
+  {
+    signal,
+    onUploadProgress: ({ sentBytes, totalBytes, attempt }) => {
+      bar.value = sentBytes / totalBytes
+    },
+  },
+)
+```
+
+- `sentBytes` counts bytes of the encoded body handed to the network — not
+  bytes the server accepted. `totalBytes` is the encoded length, multipart
+  boundaries included. The first report is `0`, values only grow, and the last
+  one of an attempt equals `totalBytes`.
+- A transport retry (`HttpClientConfig.retry`) counts again from `0` under the
+  next `attempt`.
+- Without the option nothing changes: the request takes the path it always did.
+- A `GET`, `HEAD`, `DELETE` or streaming endpoint refuses the option with a
+  `TypeError` at the call — it has no body to count, or a live response the
+  browser route would buffer. A listener that throws does not fail the upload.
+
+Fetch has no upload event, so the count comes from one of two routes, chosen
+per call:
+
+| Where the client runs | Route | What counts |
+|---|---|---|
+| Bun, Node, SSR, an injected `fetch`, a unix socket | the body is encoded once and sent as a stream of 64 KiB pieces with an exact `content-length` | a piece counts when the transport pulls it |
+| a browser on its own fetch | `XMLHttpRequest`, with the same headers, credentials, errors, cancellation and timeout | `xhr.upload` progress events |
+
+The browser route exists because a streaming request body is not portable:
+Chromium sends one only over HTTP/2 and Safari not at all. Two consequences of
+XHR: `credentials: 'omit'` is refused (XHR cannot drop same-origin cookies),
+and the response is read whole before the call resolves. An injected `fetch`
+always takes the stream route — it owns the I/O, and a transport that buffers
+the stream before sending reports the whole body at once.
+
+A counted body is encoded in memory once. A file larger than one request
+belongs in [chunked uploads](#chunked-uploads), whose parts are sized for it.
+
 ### Injected delivery adapters
 
 `ClientFetch` is the narrow composition seam for application-owned delivery.
@@ -2881,6 +2926,116 @@ Every method now requires `tenantId`, and the callback sees it as a `string`.
 The batch form delegates to the same single-contract client runtime, including
 HTTP exposure filtering, multipart, raw responses and output validation.
 
+## Chunked uploads
+
+A file larger than one request goes as three calls of the application's own
+contract — open, parts, finish — driven by `uploadInChunks` on the client and
+held by `createChunkSpool` (`stitchkit/files`) on the server. The contract stays
+the application's: its fields, its limits, what happens to the finished file.
+
+```ts
+// shared: one part size for both halves
+export const CHUNK_BYTES = 4 * 1024 * 1024
+
+// contract
+init: {
+  method: 'POST', path: '/uploads', desc: 'Open an upload',
+  input: z.object({ uploadId: z.string(), totalBytes: z.number(), chunkCount: z.number(), name: z.string() }),
+  output: z.object({ finished: Accepted.optional() }),
+},
+chunk: {
+  method: 'PUT', path: '/uploads/:uploadId/chunks/:index', desc: 'Send one part',
+  params: z.object({ uploadId: z.string(), index: z.coerce.number() }),
+  multipart: { files: { bytes: {} } },
+  output: z.object({ state: z.enum(['stored', 'repeated']) }),
+},
+finalize: {
+  method: 'POST', path: '/uploads/:uploadId/finalize', desc: 'Assemble the file',
+  params: z.object({ uploadId: z.string() }),
+  output: Accepted,
+},
+```
+
+```ts
+// server
+import { createChunkSpool } from 'stitchkit/files'
+
+const spool = createChunkSpool({
+  directory: env.UPLOAD_SPOOL_DIR,
+  chunkBytes: CHUNK_BYTES,
+  maxFileBytes: 1024 * 1024 * 1024,
+  meta: z.object({ name: z.string() }),
+})
+
+implement(contract, {
+  init: async ({ input, ctx }) => {
+    const done = await findFinished(input.uploadId) // the app's own record
+    if (done) return { finished: done }
+    await spool.open({ owner: ctx.user.id, ...input, meta: { name: input.name } })
+    return {}
+  },
+  chunk: async ({ params, files, ctx }) => ({
+    state: await spool.put({ owner: ctx.user.id, ...params, bytes: files.bytes }),
+  }),
+  finalize: async ({ params, ctx }) => {
+    const key = { owner: ctx.user.id, uploadId: params.uploadId }
+    const file = await spool.assemble(key) // file.stream(), file.chunkPaths, file.meta
+    const accepted = await store(file)
+    await spool.discard(key)
+    return accepted
+  },
+})
+```
+
+```ts
+// client — Bun, Node or a browser
+import { uploadInChunks } from 'stitchkit'
+
+const accepted = await uploadInChunks({
+  file,
+  chunkBytes: CHUNK_BYTES,
+  signal,
+  onProgress: ({ sentBytes, totalBytes }) => draw(sentBytes / totalBytes),
+  init: async (start, options) => {
+    const opened = await api.uploads.init.withOptions({ ...start, name: file.name }, options)
+    return opened.finished ? { finished: opened.finished } : undefined
+  },
+  chunk: (part, options) => api.uploads.chunk.withOptions(part, options),
+  finalize: (upload, options) => api.uploads.finalize.withOptions(upload, options),
+})
+```
+
+The rules the two halves share:
+
+- **The client mints the upload id** (default `crypto.randomUUID()`), so a
+  repeated `init` is the same upload. The spool keys it by `owner` too — the
+  same id from another owner is another upload.
+- **A part is idempotent.** The spool keeps a size+sha256 receipt per index:
+  the same bytes again answer `'repeated'`, other bytes `UPLOAD_CONFLICT`
+  (409). So the driver repeats `init` and a part on a failure that may pass — no
+  answer (network, timeout), `429`, `5xx` — up to `retries` times (default 3)
+  with a doubling pause from `retryDelayMs` (default 1 s). A refusal is final.
+- **`finalize` is never repeated.** After it the application owns the file and
+  the parts are gone; a lost answer is recovered by `init` returning
+  `{ finished }`, which the driver hands back without sending a byte.
+- **Cancellation is checked between parts**, so a cancelled upload never
+  reaches `finalize`.
+- **Every part but the last is exactly `chunkBytes`** and `chunkCount` must add
+  up; the spool refuses anything else with a 4xx `AppError`
+  (`ChunkSpoolErrorCode`), which a handler can let through as the client's
+  typed error.
+- **Progress counts file bytes**, inside a part too — the driver passes
+  `onUploadProgress` into the part call, so the [upload
+  progress](#upload-progress) route of the client applies. A repeated part
+  counts again from its start.
+- The first writer of a part wins across processes: its data file is named by
+  its hash and its receipt is published by an exclusive link. `sweep()` removes
+  uploads untouched for `staleAfterMs` (default 24 h); run it on a schedule.
+
+Part size is a latency decision: every part costs a round trip, so on a
+200 ms link a smaller part buys smoother progress at the price of a slower
+upload.
+
 ## Contract URL builders
 
 Browser-native consumers such as `<img src>`, downloads and navigation need a
@@ -10799,6 +10954,11 @@ Three things it does that a hand-written check usually does not:
 - `raw` keeps every signed pair, so a field Telegram adds after this release
   does not need a release to reach.
 
+The user arrives `camelCase` — `firstName`, `languageCode` — as `TelegramUser`.
+A bot meets the same person as grammY's `ctx.from`, in Telegram's `snake_case`;
+`parseTelegramUser(ctx.from)` gives the same `TelegramUser`, so one
+`ensureAccount(user)` serves the Mini App and the chat.
+
 `maxAgeSeconds` is optional and there is no default: only the application knows
 how long its own session is worth. Omitting it means the string never expires,
 which is a decision rather than an oversight.
@@ -10828,6 +10988,17 @@ and our payload is wrong, which is the case a list of substrings quietly counts
 against the user. An unrecognised refusal leaves the recipient reachable: losing
 a working subscriber forever costs more than one wasted send.
 
+`TELEGRAM_SEND_FAILURE_REASONS` lists every reason. A table keyed by
+`TelegramSendFailureReason` — error codes, the text a person reads — fails to
+compile when a release adds one, instead of falling through to a default:
+
+```ts
+const codes: Record<TelegramSendFailureReason, string> = {
+  'blocked-by-user': 'E_BLOCKED',
+  /* … every reason … */
+}
+```
+
 The rest of what a bot is assembled from — its resources, journal, operator
 channel, broadcasts and local Bot API files — is in [Telegram bots](telegram.md).
 
@@ -11894,6 +12065,18 @@ A payload goes into an audit row only after `sanitizePayload`:
   `tokenizer`) survive. This applies wherever a key exists — an object field and
   a `Map` entry alike, at any depth. A `Set` member has no key, so nothing there
   is masked by name;
+- **secrets are masked by their shape** in every string, whatever key holds
+  it — the secret half of a Telegram bot token (`123456:[redacted]`: the bot's
+  id stays, it tells two bots apart), the password in
+  `postgresql://user:password@host` (user, host and path stay), and the value
+  of a query parameter named as a secret (`?access_token=`, `?api-key=`,
+  `?key=`, `?sig=`). A URL in an error message or a request log line is the
+  usual way a token reaches a journal;
+- **an error keeps what it says about itself** — its own fields (`error_code`,
+  `parameters`, a provider's `status`) are written beside `name`, `message`,
+  `stack` and `cause`, masked by the same rules; a field holding a class
+  instance other than an error (grammY's `BotError.ctx`) is named, not written,
+  so one error cannot push its line past the bound and lose the stack;
 - **binary blobs** (`Uint8Array`, `Blob`, `FormData`) collapse to metadata —
   never the bytes;
 - the result is **capped** — anything over the byte limit becomes a preview.
@@ -13277,16 +13460,21 @@ output, in pino's shape — numeric `level` (`debug` 20, `info` 30, `warn` 40,
 `error` 50), `time` in epoch milliseconds, `msg` — so `pino-pretty` reads it on
 a terminal and a supervisor matching `"level":50` sees errors. Unlike pino, an
 `Error` under *any* key is written with its name, message, stack and cause; an
-error logged as `{ error }` does not become `"error":{}`.
+error logged as `{ error }` does not become `"error":{}`, and its own fields —
+a `TelegramBotApiError`'s `error_code` and `parameters.retry_after` — are on the
+line beside them.
+
+A bot token is masked wherever it appears — a request URL in an error message,
+a local Bot API file path — with no configuration: `123456:[redacted]` keeps the
+bot's id, which is public and is what tells two bots apart in one journal. So is
+the password in an address and a query parameter named as a secret (`?token=`).
 
 ```ts
 import { createJsonLogger } from 'stitchkit/observability'
-import { TELEGRAM_BOT_TOKEN_PATTERN } from 'stitchkit/telegram'
 
 export const logger = createJsonLogger({
   level: env.LOG_LEVEL,
   fields: { service: 'my-bot' },
-  sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN],
 })
 
 logger.error('Application startup failed', { error })
@@ -13302,11 +13490,13 @@ query values inside any URL variable (`DATABASE_URL`), and each URL-encoded:
 import { createJsonLogger, secretValuesFromEnv } from 'stitchkit/observability'
 
 export const logger = createJsonLogger({
-  sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN],
   sensitiveValues: secretValuesFromEnv(process.env),
 })
 ```
 
+A string of your own — a message for a person, a report — masks bot tokens with
+`redactTelegramBotToken(text)` from `stitchkit/telegram`.
+
 A key added to the environment is masked from its first line; a URL's user name
 is left alone, since it names a role that appears in ordinary text.
 
@@ -13363,7 +13553,21 @@ const operators = createTelegramOperatorChannel<'errors'>({
 })
 ```
 
-Held-back messages reach `onDropped` as `repeated` or `over-budget`. What to post stays the bot's. On the way down, drain it within the grace period
+Held-back messages reach `onDropped` as `repeated` or `over-budget`.
+
+A bot that already sends its alerts itself — its own bot instance, its own retry
+— takes the window alone instead of switching the channel off with parameters:
+
+```ts
+import { createTelegramOperatorDedupe } from 'stitchkit/telegram'
+
+const admit = createTelegramOperatorDedupe<'errors'>({ windowMs: 10 * 60_000 })
+
+const verdict = admit(text, 'errors')
+if (verdict.send) await sendAlert(verdict.text) // the text carries the held-back counts
+```
+
+What to post stays the bot's. On the way down, drain it within the grace period
 and close it: `drain: (context) => operators.drain(context.signal)`,
 `close: () => operators.close()` in a resource.
 
@@ -13484,6 +13688,14 @@ itself be a secret — and says what to pass: set the takeover for one start and
 remove it. `checkTelegramWebhook` on a timer notices a webhook that moved
 elsewhere, which this process cannot see any other way.
 
+**Moving to it from a claim of your own.** A bot that tagged its webhook itself
+holds an address this one does not recognise, so the first claim is refused —
+`other-secret` when the address is the same, `owned-elsewhere` otherwise — and
+names its own host. Start once with `takeoverFrom` set to that host, then remove
+it. The tag is derived from the secret with a fixed context, so it is the same
+across stitchkit releases: that takeover is needed once per bot, not per
+upgrade. A secret rotation is a new owner, and takes a takeover too.
+
 **The update is recorded before Telegram is answered.** A handler that runs
 longer than Telegram waits — a large file from a local Bot API server — gets the
 same update again while it still works, and a process that answers and then
@@ -13498,10 +13710,55 @@ fix (a refused message, a blocked user) is abandoned; `maxAttempts` (5) ends
 the rest. Delivery is at least once: a handler that finished but could not be
 recorded as finished runs again.
 
+With grammY the handler is `bot.handleUpdate`, which wraps a middleware's error
+in a `BotError`; the intake unwraps it, so `retry`, `onFailure` and the error
+stored with the update are what the middleware threw — a `retry` that returns
+`false` for the bot's own terminal error sees that error.
+
 The store is an interface of six atomic steps (`TelegramUpdateStore`), so the
-bot's own database can hold it; `sqliteTelegramUpdateStore` takes a
-`bun:sqlite` or `node:sqlite` handle as it is, and `memoryTelegramUpdateStore`
-is for tests.
+bot's own database holds it:
+
+| Store | Takes |
+|---|---|
+| `sqliteTelegramUpdateStore` | a `bun:sqlite` `Database` or `node:sqlite` `DatabaseSync` as it is |
+| `postgresTelegramUpdateStore` | one `query(text, parameters)` over the client the bot already holds |
+| `memoryTelegramUpdateStore` | nothing — tests, or a bot that accepts losing unhandled updates to a restart |
+
+```ts
+import { postgresTelegramUpdateStore } from 'stitchkit/telegram'
+
+// Bun
+postgresTelegramUpdateStore({ query: (text, parameters) => sql.unsafe(text, [...parameters]) })
+// Prisma
+postgresTelegramUpdateStore({
+  query: (text, parameters) => prisma.$queryRawUnsafe(text, ...parameters),
+  createTable: false, // the migration below owns the table
+})
+// pg
+postgresTelegramUpdateStore({
+  query: (text, parameters) => pool.query(text, [...parameters]).then((result) => result.rows),
+})
+```
+
+Each rule is one conditional statement, so a claim is atomic across every
+process sharing the table. By default the table is created on first use; where
+migrations own the schema, `postgresTelegramUpdateStoreSchema(table)` is the
+statement to put in one.
+
+A store of your own — over an ORM, another database — is put through the same
+rules the shipped ones are, concurrent claims included:
+
+```ts
+import { checkTelegramUpdateStore } from 'stitchkit/telegram'
+
+test('our update store keeps the rules', async () => {
+  expect(await checkTelegramUpdateStore(() => ourStore(freshTable()))).toEqual([])
+})
+```
+
+A store that reads and then writes in two statements passes every test with one
+process and runs one update twice in production; the check races eight claims
+against each other to catch it.
 
 ## Files from a local Bot API server
 
@@ -13950,6 +14207,42 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.101.0
+
+### `TelegramInitDataUser` is `TelegramUser`
+
+**Who must act:** code that names the type `TelegramInitDataUser` from
+`stitchkit/telegram`. The record is the same; its name now says it is any
+Telegram user, since `parseTelegramUser(ctx.from)` returns it for a Bot API user
+too.
+
+```ts
+// Before
+import type { TelegramInitDataUser } from 'stitchkit/telegram'
+function ensureAccount(user: TelegramInitDataUser) {}
+// After
+import type { TelegramUser } from 'stitchkit/telegram'
+function ensureAccount(user: TelegramUser) {}
+```
+
+### `TELEGRAM_BOT_TOKEN_PATTERN` matches the secret half only
+
+**Who must act:** code that uses `TELEGRAM_BOT_TOKEN_PATTERN` to find or cut a
+whole token. It now matches what follows `<bot id>:`, so a masking replace keeps
+the bot's id — `123456:[redacted]`. Masking needs nothing any more: `redact` and
+every logger on it mask bot tokens by shape; remove the pattern from
+`sensitiveUrlPatterns`, and use `redactTelegramBotToken(text)` for a string of
+your own.
+
+```ts
+// Before
+createJsonLogger({ sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN] })
+text.replace(new RegExp(TELEGRAM_BOT_TOKEN_PATTERN.source, 'g'), '[redacted]')
+// After
+createJsonLogger({})
+redactTelegramBotToken(text)
+```
+
 ## Released migration: 0.100.0
 
 ### watch capacity and session/live/delivery adoption
@@ -17886,7 +18179,10 @@ The browser-and-server entrypoint. Re-exports everything from
 | `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) |
+| `ClientRequestOptions` | _type_ | per-call `{ signal?, onUploadProgress? }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
+| `UploadProgress` | _type_ | `{ sentBytes, totalBytes, attempt }` heard by `onUploadProgress`: bytes of the encoded body handed to the network, first `0`, last `totalBytes`, counted again on each transport retry — [guide](../guide/client.md#upload-progress) |
+| `uploadInChunks` | function | send a file larger than one request as `init` → parts → `finalize` through three calls the app owns; client-minted id, repeats of a part on a failure that may pass, `finalize` never repeated, cancel checked between parts, progress in file bytes — [guide](../guide/client.md#chunked-uploads) |
+| `ChunkedUploadConfig` / `ChunkedUploadStart` / `ChunkedUploadPart` / `ChunkedUploadProgress` | _type_ | the driver's file, part size, retries and three calls; what `init` declares; one part; progress `{ sentBytes, totalBytes, index, chunkCount, attempt }` |
 | `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 |
@@ -17899,7 +18195,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `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 |
+| `RequestOptions` | _type_ | per-call options — params, timeout, response type, `onUploadProgress` |
 | `HeaderProvider` | _type_ | static or per-request headers |
 | `ApiEvent` | _type_ | a client event — `unauthorized` / `network_error` / `logout` |
 | `ApiEventListener` | _type_ | an `ApiEvent` handler |
@@ -19328,7 +19624,7 @@ audit event. See the [Observability guide](../guide/observability.md).
 | Export | Kind | Summary |
 |--------|------|---------|
 | `sanitizePayload` | function | redact secrets and cap size — [guide](../guide/observability.md#sanitisation) |
-| `redact` | function | mask secret-named keys, drop binary blobs |
+| `redact` | function | mask secret-named keys and secrets recognised by shape in every string — the secret half of a bot token, a password in an address, a query parameter named as a secret; drop binary blobs; an error keeps its own fields (`error_code`, `parameters`), a class instance on one is named, not written |
 | `truncatePreview` | function | cap a value by serialised size |
 | `measureSize` | function | item count + byte size of a result |
 | `JsonValue` | _type_ | a JSON-serialisable value |
@@ -19743,6 +20039,9 @@ available from `stitchkit/contract`.
 | `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
 | `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
+| `createChunkSpool` | function | the server half of a chunked upload: parts on disk under `owner` + client-minted `uploadId`, each with a size+sha256 receipt; idempotent `open` and `put`, the first writer of a part wins across processes, `assemble` in order once every part is in, `sweep` of untouched uploads — [guide](../guide/client.md#chunked-uploads) |
+| `ChunkSpool` / `ChunkSpoolConfig` / `ChunkSpoolKey` / `ChunkSpoolOpen` / `ChunkSpoolPart` / `ChunkSpoolAssembly` | _type_ | the spool, its directory, part size, file limit, meta schema and age; an upload's key; its declaration; one part; the assembled parts with a concatenating `stream()` |
+| `ChunkSpoolErrorCode` | _type_ | the `AppError` codes a spool refuses with, each with its 4xx status: `UPLOAD_INVALID`, `UPLOAD_TOO_LARGE`, `UPLOAD_NOT_FOUND`, `UPLOAD_CONFLICT`, `UPLOAD_CHUNK_OUT_OF_RANGE`, `UPLOAD_CHUNK_SIZE`, `UPLOAD_INCOMPLETE` |
 
 ---
 
@@ -19758,23 +20057,24 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `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 |
+| `TelegramInitData` | _type_ | verified `user`/`receiver` as `TelegramUser`, `authDate`, `ageSeconds`, `queryId`, `startParam`, `chatType`, `chatInstance` and every signed pair in `raw` |
+| `parseTelegramUser` / `TelegramUser` | function / _type_ | Telegram's `snake_case` user — grammY's `ctx.from`, a Bot API `User`, a Mini App `user` — as the one camelCase record initData returns too; `undefined` when it is not a user |
 | `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` |
+| `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
 | `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience written once, an append-only journal, pacing at `ratePerSecond` (25), 429 waits `retry_after`, unreachable recipients never addressed again, a `message-invalid` or unreachable Telegram halts without charging the recipient, a send in flight at a crash is `uncertain` and not repeated, `dryRun`, one runner per name |
 | `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
 | `telegramBroadcastSender` / `TelegramBroadcastSenderConfig` / `TelegramBroadcastMessage` | function / _type_ | the standard `send`: `sendMessage` with a text or `copyMessage` of a prepared message, through the Bot API |
 | `createTelegramOperatorChannel` | function | the operator chat, apart from the journal: `post(text, topic?)` returns at once and never throws; paced sends into forum topics, 429 honoured, oldest dropped on overflow, `drain(signal)` and `close()` for the way down |
 | `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`, `sensitivePatterns` and `sensitiveValues` (a bot token is always masked), `dedupe`; a drop is `overflow` / `refused` / `attempts` / `closed` / `repeated` / `over-budget` with its classification |
+| `createTelegramOperatorDedupe` / `TelegramOperatorDedupeVerdict` | function / _type_ | the channel's dedupe window alone, for a sender with its own bot and retry: `(text, topic?)` → `{ send: true, text }` with the held-back counts, or `{ send: false, reason: 'repeated' \| 'over-budget' }` |
 | `TelegramOperatorDedupe` | _type_ | `windowMs` (10 min): one message per `fingerprint` per window, the next one sent carries `repeatedLine(count)`; `maxPerWindow` (20) across fingerprints, the overflow counted onto the next one sent with `overBudgetLine(count)`; `now` |
 | `telegramOperatorSender` / `TelegramOperatorSenderConfig` | function / _type_ | the standard `send`: `sendMessage` into the chat and topic, plain text unless `parseMode`; with `'HTML'` the markup is cleaned and cut by what it shows, so the channel's cut never leaves a tag open |
 | `createTelegramLocalFiles` | function | files the local Bot API server wrote under `<root>/<token>/`: `resolve(file_path)` and `remove(file_path)` only inside the bot's directory, judged on real paths so a link is judged by where it leads; `check()` for readiness. Recommended root variable: `BOT_API_FILES_ROOT` |
 | `TelegramLocalFilesConfig` / `TelegramLocalFiles` / `TelegramLocalFilesCheck` / `TelegramLocalFileError` / `TelegramLocalFileRefusal` | _type_ / class | `root`, `token`; refusals `root-not-absolute` / `bot-directory-unavailable` / `outside-bot-directory` / `missing` / `not-a-file`, never carrying the path or the token |
 | `callTelegramBotApi` / `TelegramBotApiCall` / `TelegramBotApiError` | function / _type_ / class | one Bot API method over `fetch`; a refusal keeps `error_code`, `description` and `parameters` for the classifier, and no error names the URL |
-| `TELEGRAM_BOT_TOKEN_PATTERN` | constant | the shape of a bot token, for a logger's `sensitiveUrlPatterns` |
+| `TELEGRAM_BOT_TOKEN_PATTERN` / `redactTelegramBotToken` | constant / function | the secret half of a bot token — the bot's id before the colon is not matched; `redact` and every logger on it mask it already, `redactTelegramBotToken(text)` masks every token in a string to `123456:[redacted]` |
 | `claimTelegramWebhook` | function | set the webhook only where it already points here, or by naming the host it is taken from; confirm Telegram holds it; pending updates kept unless `dropPendingUpdates` |
 | `ClaimTelegramWebhookConfig` / `TelegramWebhookConfig` / `TelegramWebhookClaim` | _type_ | `token`, `url`, `secret`, `apiRoot`, `fetch`, `signal`; `takeoverFrom` (a host, or `'none'`), `allowedUpdates`, `maxConnections`, `dropPendingUpdates`; the claim's tagged `url`, `takenFrom`, `pendingUpdates` |
 | `TelegramWebhookClaimError` / `TelegramWebhookRefusal` / `TELEGRAM_WEBHOOK_NONE` | class / _type_ / constant | `owned-elsewhere` / `other-secret` / `not-confirmed` with `ownerHost` — a host, never a path; `'none'` names no webhook |
@@ -19782,10 +20082,13 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `checkTelegramWebhook` / `TelegramWebhookState` | function / _type_ | whether the webhook still points here: `owned`, `ownerHost`, `pendingUpdates`, Telegram's `lastError` |
 | `receiveTelegramWebhook` / `ReceiveTelegramWebhookOptions` / `TelegramUpdateAcceptance` | function / _type_ | one webhook `Request`: 403 without the secret (compared in constant time), 405 for another method, 400 for no update, 200 once `accept` recorded it |
 | `createTelegramUpdateIntake` | function | webhook updates recorded before Telegram is answered and handled after: chat order kept, other chats alongside up to `maxConcurrent`, a renewed lease per attempt, a sweep that takes over what a restart or a dead process left, retries, `maxAttempts`, finished updates remembered `retainMs` to refuse repeats; at least once |
-| `TelegramUpdateIntakeConfig` / `TelegramUpdateIntake` / `TelegramUpdateEnvelope` / `TelegramUpdateFailure` / `TelegramUpdateStoreStep` | _type_ | `store`, `handle`, `retry`, `maxAttempts` (5), `leaseMs` (120 000), `pendingGraceMs` (60 000), `sweepEveryMs` (30 000), `retainMs` (24 h), `maxConcurrent` (32), `onFailure`, `onStoreError`, `now`; `accept(body)`, `start()`, `sweep()`, `idle()`, `close()` |
+| `TelegramUpdateIntakeConfig` / `TelegramUpdateIntake` / `TelegramUpdateEnvelope` / `TelegramUpdateFailure` / `TelegramUpdateStoreStep` | _type_ | `store`, `handle` (a grammY `BotError` is unwrapped: `retry`, `onFailure` and the stored error see what the middleware threw), `retry`, `maxAttempts` (5), `leaseMs` (120 000), `pendingGraceMs` (60 000), `sweepEveryMs` (30 000), `retainMs` (24 h), `maxConcurrent` (32), `onFailure`, `onStoreError`, `now`; `accept(body)`, `start()`, `sweep()`, `idle()`, `close()` |
 | `TelegramUpdateStore` / `StoredTelegramUpdate` / `TelegramUpdateState` / `TelegramUpdateSettlement` / `TelegramUpdateClaimOptions` / `TelegramUpdateDueQuery` | _type_ | the store an intake runs on: `add`, `claim`, `renew`, `settle`, `due`, `prune`, each atomic on one record — a claim takes `pending`, a due `failed` or a lapsed `processing`; renew and settle only by the attempt holding it |
 | `memoryTelegramUpdateStore` | function | the store in this process's memory — tests, or a bot that accepts losing unhandled updates to a restart |
 | `sqliteTelegramUpdateStore` / `SqliteTelegramUpdateStoreConfig` / `TelegramSqliteDatabase` | function / _type_ | the store in SQLite over the handle the application opened — `bun:sqlite` `Database` or `node:sqlite` `DatabaseSync`; `table` (default `telegram_updates`) created when missing |
+| `postgresTelegramUpdateStore` / `PostgresTelegramUpdateStoreConfig` / `TelegramPostgresQuery` | function / _type_ | the store in Postgres over the client the application holds, as one `query(text, parameters)` returning rows — Bun `sql.unsafe`, Prisma `$queryRawUnsafe`, `pg` `pool.query`; each rule one conditional statement; `table`, `createTable` (default `true`) |
+| `postgresTelegramUpdateStoreSchema` | function | the table and its index as a statement for a migration, safe to run twice |
+| `checkTelegramUpdateStore` | function | put any store through every rule, each on a fresh store from `make`, concurrent claims included; resolves with the violations, empty when it keeps them |
 
 ---
 

package/llms.txt

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 16.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 37.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 16.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 16.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 43.6 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 16.9 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.6 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 9.0 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.4 KB
@@ -21,8 +21,8 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 9.3 KB
-- **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 37.5 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
-- **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 43.7 KB
+- **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.1 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
+- **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 44.8 KB
 - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 36.8 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 34.3 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.2 KB
 - **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 4.1 KB
@@ -39,8 +39,8 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/application/schemas**: [llms/application-schemas.txt](llms/application-schemas.txt) 1.8 KB
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.8 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.1 KB
-- **stitchkit/files**: [llms/files.txt](llms/files.txt) 2.9 KB
-- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 22.2 KB
+- **stitchkit/files**: [llms/files.txt](llms/files.txt) 3.8 KB
+- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 26.9 KB
 - **stitchkit/telegram/html**: [llms/telegram-html.txt](llms/telegram-html.txt) 2.7 KB
 - **stitchkit/telegram/screens**: [llms/telegram-screens.txt](llms/telegram-screens.txt) 21.2 KB
 - **stitchkit/tracking**: [llms/tracking.txt](llms/tracking.txt) 16.8 KB
@@ -55,7 +55,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
-- **Upgrading 0.74.0 → 0.100.0**: [llms/upgrading-0.74.0-0.100.0.txt](llms/upgrading-0.74.0-0.100.0.txt) 45.1 KB
+- **Upgrading 0.74.0 → 0.101.0**: [llms/upgrading-0.74.0-0.101.0.txt](llms/upgrading-0.74.0-0.101.0.txt) 46.3 KB
 - **Upgrading 0.61.0 → 0.73.0**: [llms/upgrading-0.61.0-0.73.0.txt](llms/upgrading-0.61.0-0.73.0.txt) 41.2 KB
 - **Upgrading 0.44.0 → 0.60.0**: [llms/upgrading-0.44.0-0.60.0.txt](llms/upgrading-0.44.0-0.60.0.txt) 43.9 KB
 - **Upgrading 0.37.0 → 0.37.0**: [llms/upgrading-0.37.0.txt](llms/upgrading-0.37.0.txt) 6.2 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.100.3",
+  "version": "0.101.1",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",