stitchkit 0.116.0 → 0.117.0

package/llms/tracking.txt

@@ -33,7 +33,7 @@ Both entrypoints are **evolving**.
 ## Contract
 
 ```ts
-import { createTrackingContract } from 'stitchkit/tracking'
+import { createTrackingContract } from 'stitchkit/tracking/contract'
 
 export const tracking = createTrackingContract({
   scope: 'public',
@@ -232,6 +232,76 @@ has an identity. A bot gets a lease that no store holds, so its events are
 `createPresenceRegistry` is who is here now, in this process: touch it from
 `track`, read it for a live feed. It is honestly empty after a restart.
 
+## Real-visitor speed
+
+`stitchkit/tracking/performance` collects Web Vitals from the people who use the site. Install the
+optional peer `web-vitals` and call it once on the page:
+
+```ts
+import { createPerformanceCollector } from 'stitchkit/tracking/performance'
+
+createPerformanceCollector({
+  buildId: BUILD_ID,
+  url: '/api/tracking/performance',
+  visitId: () => client.visitId(),
+})
+```
+
+The library is fetched as its own chunk after `load`, when the browser is idle, so the measurement costs
+the page nothing it is measuring. Each load posts an `early` sample five seconds later and a `final` one
+as the page goes, both with `sendBeacon` and the same `id`: keep the later one. The body is a string, so
+the endpoint declares `safelistedBody: true`. A sample that could not leave waits in session storage for the
+next page, up to 20 of them, and of one load only the newest.
+
+A browser under automation sends nothing, and neither does an agent that admits to being Lighthouse,
+headless Chrome, GTmetrix or a crawler. Lighthouse with its default settings imitates an ordinary browser, so a
+local run with `webdriver` off cannot be told from a visitor.
+
+One load is one document: a client-side navigation stays under the route the page opened on, and whatever
+`web-vitals` reports after a back-forward restore is left out, because it would replace the load's numbers
+with a restore's. A second call on a page returns the running collector.
+
+A sample carries the route, the build, `mobile` or `desktop`, and the five metrics. **A metric that did not
+arrive is `null`, never zero**: most visits have no INP at all, and a zero would pull every average down.
+
+Parse a sample on your own endpoint and store it in your own table:
+
+```ts
+import { redactTrackingText } from 'stitchkit/tracking'
+import { PerformanceSampleSchema, summarizePerformanceMetric } from 'stitchkit/tracking/contract'
+
+const sample = PerformanceSampleSchema.parse(await request.json())
+await samples.upsert({ ...sample, route: redactTrackingText(sample.route) })
+
+const lcp = summarizePerformanceMetric(rows.map((row) => row.vitals.lcpMs))
+// { samples: 42, p75: 1840, p95: null } — a p95 needs 100 samples
+```
+
+The report is yours: which routes matter and what is slow are the application's words.
+
+## Privacy
+
+`redactTrackingText` masks passwords, sign-in credentials, API keys, bearer tokens and signed Telegram launch
+data in a URL or free text, and leaves paths and campaign parameters byte for byte. Text past 16 KiB is cut
+first, because the endpoint is open to anyone. `code` and `hash` count only beside the
+`state` or `auth_date` that makes them credentials, so a promo code stays. `redactTrackingValue` applies the
+same rule through a value of any shape. The client applies it to the landing path, the referrer and the
+campaign tags before sending or storing them. Apply it again on your ingest: anyone can post to that endpoint without running the client.
+
+## Is tracking losing events?
+
+`trackingTelemetryHealth(reports, baselines)` reads the outbox figures of a visit's bootstrap
+(`browserStreamId` as `stream`, `outboxState`, `outboxQueued`, `outboxDropped`) and answers `ok`, `degraded` or
+`unknown`. An application running without an outbox reports `unavailable` and reads as `degraded`. A browser repeats its lifetime `dropped` with
+every visit, so pass what each stream reported before the window as `baselines`, and only the growth counts.
+
+## Bundle weight
+
+`stitchkit/tracking` has no `zod` in its graph: `createTrackingClient` with `indexedDbOutboxStorage` is under
+8 KB gzip, a test holds that, and the build refuses a published file that reaches `zod`. The schemas live in
+`stitchkit/tracking/contract` for the server and a shared contract. Importing that in code a browser loads
+brings `zod` back, so keep a shared contract out of the storefront's client bundle.
+
 ## Not here
 
 GeoIP, event labels, funnels, reports, the analytics page, Socket.IO push into
@@ -246,8 +316,9 @@ looks different even though their mechanics are now one.
 
 Browser-safe visitor-tracking mechanics, with no event vocabulary of their own
 and no React. The React wrapper (a provider and a hook, ~40 lines) is the
-application's — it owns the router and the session. The server half is
-`stitchkit/tracking/server`. → ADR 0166 — [guide](../guide/tracking.md)
+application's — it owns the router and the session. It imports no `zod`: the wire
+shapes are `stitchkit/tracking/contract`, the server half is
+`stitchkit/tracking/server`. → ADR 0166, ADR 0280 — [guide](../guide/tracking.md)
 
 | Export | Kind | Summary |
 |--------|------|---------|
@@ -256,15 +327,6 @@ application's — it owns the router and the session. The server half is
 | `TrackFn` / `EventsWithMetadata` / `EventsWithoutMetadata` | _type_ | `track(type)` / `track(type, metadata)` typed by the application's metadata map, and the two halves of that map |
 | `BuiltinTrackingEventTypes` / `CONVENTIONAL_TRACKING_EVENT_TYPES` | _type_ / const | the application's names for the events the client emits itself; the conventional `PAGE_VIEW` … `INTERACTION` set |
 | `browserTrackingHost` / `TrackingHost` / `TrackingPageContext` | function / _type_ | everything the client takes from a browser tab behind one interface — page context, visibility, scroll depth, events, intervals, clocks, storage — so a test or a non-tab host can supply its own |
-| `createTrackingContract` / `TrackingContractConfig` / `TrackingContractEndpoints` | function / _type_ | `bootstrap` (`POST /visit`) and `track` (`POST /events`, `safelistedBody`) from the application's event types, scope and optional extras |
-| `createTrackingSchemas` / `TrackingSchemas` / `TrackingSchemasConfig` | function / _type_ | every schema of one surface — `event`, `request`, `response`, `disposition`, `entry`, `bootstrap` — from `eventTypes`, optional `eventExtras`, `buildIdPattern`, `maxEventsPerBatch` |
-| `TrackingEventEnvelope` / `TrackingEventShape` | _type_ | `eventId`, `visitId`, `browserStreamId`, `browserSequence`, `type`, `page`, `metadata`, `clientTimestamp` |
-| `TrackEventsRequest` / `TrackEventsResponse` / `TrackEventsResponseSchema` | _type_ / schema | a batch (`buildId`, `events`, `utm`) and its answer (`accepted`, `dispositions`) |
-| `TrackingDisposition` / `TrackingDispositionSchema` / `TrackingDispositionStatus` / `TrackingDispositionStatusSchema` | _type_ / schema | `accepted` / `duplicate` / `identity-invalid` / `excluded-bot` — every one terminal |
-| `VisitEntryContext` / `VisitEntryContextShape` / `VisitBootstrapResponse` / `VisitBootstrapResponseSchema` | _type_ / schema | what a browser reports to open a visit (lineage, landing, referrer, UTM, display, screen, `buildId`, outbox health) and the lease it gets back |
-| `TrackingOutboxState` / `TrackingOutboxStateSchema` | _type_ / schema | `available` / `unavailable` |
-| `UtmData` / `UtmDataSchema` / `AttributionData` / `AttributionDataSchema` | _type_ / schema | campaign tags and a touch (UTM, referrer, landing page) |
-| `DEFAULT_BUILD_ID_PATTERN` | const | `dev` or a git SHA |
 | `createTrackingOutbox` / `TrackingOutbox` / `TrackingOutboxOptions` / `TrackingOutboxHealth` | function / _type_ | the tab-shared outbox: `streamId`, `reserveSequences`, `enqueue`, `acquireLease` / `releaseLease` (short, released on leave), `readBatch`, `acknowledge`, `health`; bounded by count and age |
 | `TrackingOutboxStorage` / `TrackingOutboxMeta` / `TrackingOutboxEvents` / `TrackingOutboxRecord` / `TrackingQueuedEvent` | _type_ | one atomic, all-or-nothing `transact` over a key/value store and an event store (`readonly` for pure reads) — the contract an adapter implements |
 | `indexedDbOutboxStorage` / `memoryOutboxStorage` | function | the IndexedDB adapter (one `readwrite` transaction per `transact`) and the in-memory one for tests and degraded mode |
@@ -276,6 +338,7 @@ application's — it owns the router and the session. The server half is
 | `createOncePerPage` / `OncePerPage` | function / _type_ | one fact per key per page within a window — the guard a twice-mounted component cannot keep itself |
 | `resolveAttribution` / `ResolveAttributionInput` / `ResolvedAttribution` / `AttributionStorage` / `ReferrerRule` | function / _type_ | first-touch once, current-touch on every new UTM; the referrer → source/medium map is the application's, there is no built-in list |
 | `parseUtmFromSearch` / `parseReferrer` | function | the two parsers `resolveAttribution` is built from |
+| `redactTrackingText` / `redactTrackingValue` | functions | mask passwords, sign-in credentials and signed launch data in text or a value of any shape; the key stays, and navigation and campaign parameters are untouched |
 | `resolveTrackedClick` / `ResolveTrackedClickOptions` / `TrackedClick` / `TrackedClickAttributes` / `ClickTarget` | function / _type_ | `data-track` → click, `data-track-action` → interaction, a link to another origin → outbound; attribute names configurable; `hrefPolicy: 'full'` retains query/fragment (default `path-only` omits them), URL credentials excluded; `leavesPage` says which path to send on |
 
 ---

package/llms/{upgrading-0.105.0-0.116.0.txt → upgrading-0.105.0-0.117.0.txt}

@@ -1,14 +1,61 @@
-# Upgrading 0.105.0 → 0.116.0 — stitchkit docs slice
+# Upgrading 0.105.0 → 0.117.0 — 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: Upgrading, 0.105.0 → 0.116.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.105.0 → 0.117.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.105.0 → 0.116.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.105.0 → 0.117.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.117.0
+
+### telegram-chat-pause
+
+**Who must act:** code that relied on a 429 to one chat to stop the token's other chats. A bot that
+only sends needs no change: its other chats stop waiting.
+
+`run` pauses the `chat_id` of a refused send; the token pauses when `tokenPauseChats` chats are refused
+inside `tokenPauseWindowMs`, or when the call has no chat
+([ADR 0278](../decisions/0278-a-telegram-429-holds-the-chat-that-got-it.md)). A second budget kept under a
+derived key to isolate one group is no longer needed: remove it. Where one refusal must still stop everything,
+say so:
+
+```ts
+// before
+await api.sendMessage(chatId, text)
+// after
+await api.sendMessage(chatId, text).catch((error) => {
+  budget.pauseAfter(error)
+  throw error
+})
+```
+
+The catch belongs at the `Api` call, where grammY has turned a returned refusal into a thrown one. A raw
+`budget.run` around a client transformer's `send` gets that refusal as a value.
+
+Search pattern: `budget.run`, and budgets created under a key derived from the token.
+
+### tracking-contract-entry
+
+**Who must act:** code that imports `createTrackingContract` or a tracking schema or wire type from
+`stitchkit/tracking`. Code that only uses the browser client needs no change.
+
+The wire shapes moved to `stitchkit/tracking/contract`, so a page that sends events no longer carries `zod`
+([ADR 0280](../decisions/0280-real-visitor-speed-is-collected-after-the-page.md)):
+
+```ts
+// before
+import { createTrackingContract, createTrackingSchemas } from 'stitchkit/tracking'
+// after
+import { createTrackingContract, createTrackingSchemas } from 'stitchkit/tracking/contract'
+```
+
+Search pattern: imports from `stitchkit/tracking` naming `createTrackingContract`, `createTrackingSchemas`,
+`UtmData`, `AttributionData`, `TrackingEventEnvelope`, `TrackingDisposition`, `TrackEvents*`, `VisitEntryContext`,
+`VisitBootstrapResponse`, `TrackingOutboxState` or `DEFAULT_BUILD_ID_PATTERN`.
+
 ## Released migration: 0.116.0
 
 ### send-only-telegram-pause

package/llms/upgrading.txt

@@ -11,7 +11,7 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.105.0 → 0.116.0: `llms/upgrading-0.105.0-0.116.0.txt`
+- 0.105.0 → 0.117.0: `llms/upgrading-0.105.0-0.117.0.txt`
 - 0.84.0 → 0.104.0: `llms/upgrading-0.84.0-0.104.0.txt`
 - 0.63.0 → 0.83.0: `llms/upgrading-0.63.0-0.83.0.txt`
 - 0.44.0 → 0.62.0: `llms/upgrading-0.44.0-0.62.0.txt`

package/llms/xlsx.txt

@@ -0,0 +1,107 @@
+# stitchkit/xlsx — 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: XLSX  (docs/guide/xlsx.md) · API reference: `stitchkit/xlsx`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: XLSX  (docs/guide/xlsx.md)
+==============================================================================
+
+# XLSX
+
+`stitchkit/xlsx` turns rows into a workbook. It is evolving, it needs nothing beyond the `zod` the package
+already requires, and it runs wherever
+`CompressionStream` does: Bun, Node and a browser.
+
+```ts
+import { defineMoney } from 'stitchkit/primitives'
+import { renderXlsx, XLSX_MEDIA_TYPE } from 'stitchkit/xlsx'
+
+const rub = defineMoney('RUB')
+
+const bytes = await renderXlsx({
+  sheets: [
+    {
+      name: 'Orders',
+      columns: [
+        { key: 'title', header: 'Title', type: 'text' },
+        { key: 'count', header: 'Count', type: 'number', format: '0.00' },
+        { key: 'day', header: 'Day', type: 'date' },
+        { key: 'at', header: 'Created', type: 'datetime', timeZone: 'Asia/Bangkok' },
+        { key: 'total', header: 'Total', type: 'money', currency: 'RUB', scale: 2 },
+        { key: 'paid', header: 'Paid', type: 'boolean' },
+      ],
+      rows: [
+        {
+          title: 'First order',
+          count: '2.5',
+          day: '2026-11-03',
+          at: new Date(),
+          total: rub.create('504182'),
+          paid: true,
+        },
+      ],
+    },
+  ],
+})
+
+return new Response(bytes, {
+  headers: {
+    'content-type': XLSX_MEDIA_TYPE,
+    'content-disposition': `attachment; filename*=UTF-8''${encodeURIComponent('Übersicht.xlsx')}`,
+  },
+})
+```
+
+A missing or `null` value leaves the cell empty. The first row holds the headers, stays frozen and carries a
+filter. The same input produces the same bytes on one runtime; Bun and Node compress differently.
+
+## Column types
+
+| `type` | Cell value | In the file |
+|---|---|---|
+| `text` | string | text, whatever it looks like: `007` keeps its zeros |
+| `number` | number, bigint or decimal string | a number, with an optional Excel `format` |
+| `date` | `YYYY-MM-DD` | a date serial; a calendar date has no time zone to get wrong |
+| `datetime` | `Date` or ISO instant with an offset | the wall clock of the column's `timeZone` to the second, since a cell stores no zone |
+| `money` | `Money` in the column's `currency` | a number with `scale` places and the currency in its format |
+| `boolean` | boolean | a boolean |
+
+## What it refuses
+
+A value of the wrong type throws `XlsxCellError` naming the cell, such as `sheet "Orders" B2: expected a
+number or a decimal string`, instead of landing as a wrong cell.
+
+Excel keeps numbers as doubles, so 15 significant digits are what survives. A decimal string or `Money` with
+more refuses rather than turning into a different amount. Keep such a value in a `text` column if it must
+stay exact and needs no arithmetic. Dates before 1900-03-01 refuse too: Excel counts a leap day that never
+happened, so its serials before it are off by one.
+
+A wall clock cannot tell the two hours of a daylight-saving change apart: 05:30Z and 06:30Z on a New York
+autumn night are the same cell. Use `UTC` for a column whose order must survive that hour.
+
+## Text is never a formula
+
+Cells are written as inline strings, so `=HYPERLINK("x")` from a user's input is text a reader shows,
+and the file has no formula element at all. A cell that starts with `=`, `+`, `-` or `@` also carries Excel's
+quote prefix, so it stays text when a person edits that cell.
+
+## Limits
+
+Everything is built in memory, up to Excel's own 1 048 576 rows per sheet. There is no reading, no
+charts, no merged cells and no streaming: an application that needs them takes a library.
+
+==============================================================================
+# API reference: `stitchkit/xlsx`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/xlsx`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `renderXlsx` | function | a workbook from rows and typed columns as XLSX bytes; deterministic, no formula in the file |
+| `XLSX_MEDIA_TYPE` | constant | the media type for `defineExportOperation` and a download response |
+| `XlsxCellError` | class | a value of the wrong type, or one Excel cannot hold exactly, with the cell's address |
+| `XlsxWorkbookSchema` / `XlsxWorkbook` / `XlsxSheetSchema` / `XlsxColumnSchema` / `XlsxColumn` | schemas / _types_ | the workbook, its sheets and the six column types |