stitchkit 0.100.3 → 0.101.1

package/dist/telegram/init-data.d.ts

@@ -22,52 +22,12 @@
  * Not a domain model (→ ADR 0002): "Telegram signed this string" is a fact
  * about a transport, the same kind of fact as a bearer token being well-formed.
  */
-import { z } from 'zod';
-/**
- * The Telegram user record, as our surface names things.
- *
- * Telegram's wire fields are `snake_case`; every other name this package
- * publishes is `camelCase`, and a surface that switches convention because of
- * where a value came from makes the caller remember which is which. The
- * untouched wire pairs stay available in `raw`.
- */
-declare const TelegramInitDataUserSchema: z.ZodPipe<z.ZodObject<{
-    id: z.ZodInt;
-    is_bot: z.ZodOptional<z.ZodBoolean>;
-    first_name: z.ZodString;
-    last_name: z.ZodOptional<z.ZodString>;
-    username: z.ZodOptional<z.ZodString>;
-    language_code: z.ZodOptional<z.ZodString>;
-    is_premium: z.ZodOptional<z.ZodBoolean>;
-    allows_write_to_pm: z.ZodOptional<z.ZodBoolean>;
-    photo_url: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodTransform<{
-    id: number;
-    firstName: string;
-    isBot?: boolean | undefined;
-    lastName?: string | undefined;
-    username?: string | undefined;
-    languageCode?: string | undefined;
-    isPremium?: boolean | undefined;
-    allowsWriteToPm?: boolean | undefined;
-    photoUrl?: string | undefined;
-}, {
-    id: number;
-    is_bot?: boolean | undefined;
-    first_name: string;
-    last_name?: string | undefined;
-    username?: string | undefined;
-    language_code?: string | undefined;
-    is_premium?: boolean | undefined;
-    allows_write_to_pm?: boolean | undefined;
-    photo_url?: string | undefined;
-}>>;
-export type TelegramInitDataUser = z.infer<typeof TelegramInitDataUserSchema>;
+import { type TelegramUser } from './user.js';
 export interface TelegramInitData {
     /** Absent when the Mini App was opened somewhere Telegram sends no user. */
-    user?: TelegramInitDataUser;
+    user?: TelegramUser;
     /** Whose chat the Mini App was opened from, when Telegram named one. */
-    receiver?: TelegramInitDataUser;
+    receiver?: TelegramUser;
     /** When Telegram signed this string. */
     authDate: Date;
     /** How old the signature was at verification time. */
@@ -130,5 +90,4 @@ export interface VerifyTelegramInitDataOptions {
  * being configured wrong, and it throws.
  */
 export declare function verifyTelegramInitData(options: VerifyTelegramInitDataOptions): Promise<TelegramInitDataVerification>;
-export {};
 //# sourceMappingURL=init-data.d.ts.map

package/dist/telegram/init-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-data.d.ts","sourceRoot":"","sources":["../../src/telegram/init-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;GAOG;AACH,QAAA,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsB3B,CAAC;AAEN,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,wCAAwC;IACxC,QAAQ,EAAE,IAAI,CAAC;IACf,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAC/B,cAAc,GACd,oBAAoB,GACpB,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,MAAM,4BAA4B,GACpC;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACzD;IACE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEN,MAAM,WAAW,6BAA6B;IAC5C,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAWD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,4BAA4B,CAAC,CAuEvC"}
+{"version":3,"file":"init-data.d.ts","sourceRoot":"","sources":["../../src/telegram/init-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAI9D,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,wCAAwC;IACxC,QAAQ,EAAE,IAAI,CAAC;IACf,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAC/B,cAAc,GACd,oBAAoB,GACpB,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,MAAM,4BAA4B,GACpC;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACzD;IACE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEN,MAAM,WAAW,6BAA6B;IAC5C,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAUD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,4BAA4B,CAAC,CAuEvC"}

package/dist/telegram/operator-channel.d.ts

@@ -13,6 +13,7 @@
  * What to post stays the application's. This owns the queue, the pacing, the
  * topics, 429s and the bounded way down.
  */
+import { type TelegramOperatorDedupe } from './operator-dedupe.js';
 import { type TelegramSendFailure } from './send-failure.js';
 export type TelegramChatId = number | string;
 export interface TelegramOperatorMessage {
@@ -66,24 +67,6 @@ export interface TelegramOperatorChannelConfig<TTopic extends string> {
      */
     readonly dedupe?: TelegramOperatorDedupe<TTopic>;
 }
-export interface TelegramOperatorDedupe<TTopic extends string> {
-    /** Default 600 000 — ten minutes. */
-    readonly windowMs?: number;
-    /** Messages sent per window, whatever their fingerprint. Default 20. */
-    readonly maxPerWindow?: number;
-    /**
-     * What makes two messages the same. Default: the topic and the text with
-     * numbers, UUIDs and long identifiers blanked — they differ between two
-     * occurrences of one failure without making it another.
-     */
-    readonly fingerprint?: (text: string, topic: TTopic | undefined) => string;
-    /** The line added to a message after `count` of its repeats were held back. */
-    readonly repeatedLine?: (count: number) => string;
-    /** The line added to the first message after `count` were held back by the budget. */
-    readonly overBudgetLine?: (count: number) => string;
-    /** Default `Date.now`. */
-    readonly now?: () => number;
-}
 export interface TelegramOperatorChannel<TTopic extends string> {
     /** Queue one message. Returns at once and never throws. */
     post(text: string, topic?: TTopic): void;

package/dist/telegram/operator-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator-channel.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-channel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"operator-channel.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-channel.ts"],"names":[],"mappings":"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"}

package/dist/telegram/operator-dedupe.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Repeats and storms held back before they reach a person.
+ *
+ * One failure in a loop is a hundred identical alerts, and a hundred alerts
+ * is a muted chat — after which the one that mattered is not read either. So
+ * the same message, by fingerprint, goes once per window and the next one
+ * that goes says how many were held back; past a budget per window the rest
+ * are counted and the count rides on the first message after. The operator
+ * channel uses it through its `dedupe` option; it is exported for senders of
+ * their own.
+ */
+export interface TelegramOperatorDedupe<TTopic extends string> {
+    /** Default 600 000 — ten minutes. */
+    readonly windowMs?: number;
+    /** Messages sent per window, whatever their fingerprint. Default 20. */
+    readonly maxPerWindow?: number;
+    /**
+     * What makes two messages the same. Default: the topic and the text with
+     * numbers, UUIDs and long identifiers blanked — they differ between two
+     * occurrences of one failure without making it another.
+     */
+    readonly fingerprint?: (text: string, topic: TTopic | undefined) => string;
+    /** The line added to a message after `count` of its repeats were held back. */
+    readonly repeatedLine?: (count: number) => string;
+    /** The line added to the first message after `count` were held back by the budget. */
+    readonly overBudgetLine?: (count: number) => string;
+    /** Default `Date.now`. */
+    readonly now?: () => number;
+}
+/** Send `text` — the message with its held-back counts — or hold it back, with why. */
+export type TelegramOperatorDedupeVerdict = {
+    readonly send: true;
+    readonly text: string;
+} | {
+    readonly send: false;
+    readonly reason: 'repeated' | 'over-budget';
+};
+/**
+ * The dedupe window on its own, for an application that sends alerts itself —
+ * its own bot, its own retry — and wants only the decision: whether this
+ * message goes, and the text it goes with.
+ */
+export declare function createTelegramOperatorDedupe<TTopic extends string = never>(options?: TelegramOperatorDedupe<TTopic>): (text: string, topic?: TTopic) => TelegramOperatorDedupeVerdict;
+//# sourceMappingURL=operator-dedupe.d.ts.map

package/dist/telegram/operator-dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-dedupe.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-dedupe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,sBAAsB,CAAC,MAAM,SAAS,MAAM;IAC3D,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,CAAC;IAC3E,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,sFAAsF;IACtF,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACpD,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAUD,uFAAuF;AACvF,MAAM,MAAM,6BAA6B,GACrC;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAAA;CAAE,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,SAAS,MAAM,GAAG,KAAK,EACxE,OAAO,GAAE,sBAAsB,CAAC,MAAM,CAAM,GAC3C,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,6BAA6B,CAwCjE"}

package/dist/telegram/send-failure.d.ts

@@ -63,6 +63,12 @@ export interface TelegramSendFailure {
      */
     evidence: 'parameters' | 'status' | 'description' | 'none';
 }
+/**
+ * Every reason, for a consumer that maps each one to its own code or text. A
+ * `Record<TelegramSendFailureReason, …>` beside it fails to compile when a
+ * release adds a reason, instead of falling through to a default at run time.
+ */
+export declare const TELEGRAM_SEND_FAILURE_REASONS: readonly TelegramSendFailureReason[];
 /**
  * Classify one refused send.
  *

package/dist/telegram/send-failure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;CAC5D;AAuED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA0D/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}
+{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;CAC5D;AA6CD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAC7B,CAAC;AAyClD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAyD/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}

package/dist/telegram/update-intake.d.ts

@@ -34,7 +34,11 @@ export interface TelegramUpdateFailure {
 export type TelegramUpdateStoreStep = 'claim' | 'renew' | 'settle' | 'sweep';
 export interface TelegramUpdateIntakeConfig<TUpdate extends TelegramUpdateEnvelope> {
     readonly store: TelegramUpdateStore;
-    /** Handle one update — with grammY, `(update) => bot.handleUpdate(update)`. */
+    /**
+     * Handle one update — with grammY, `(update) => bot.handleUpdate(update)`.
+     * A grammY `BotError` is unwrapped: `retry`, `onFailure` and the stored
+     * error see what the middleware threw.
+     */
     readonly handle: (update: TUpdate) => unknown;
     /**
      * After a failed attempt: milliseconds until the next, or `false` to

package/dist/telegram/update-intake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update-intake.d.ts","sourceRoot":"","sources":["../../src/telegram/update-intake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAE1D,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7E,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,sBAAsB;IAChF,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,KAAK,CAAC;IACrE,iBAAiB;IACjB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,sBAAsB;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC9D,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAChF,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACxD,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,0CAA0C;IAC1C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,2DAA2D;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAsDD,wBAAgB,0BAA0B,CAAC,OAAO,SAAS,sBAAsB,EAC/E,MAAM,EAAE,0BAA0B,CAAC,OAAO,CAAC,GAC1C,oBAAoB,CAgJtB"}
+{"version":3,"file":"update-intake.d.ts","sourceRoot":"","sources":["../../src/telegram/update-intake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAE1D,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7E,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,sBAAsB;IAChF,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,KAAK,CAAC;IACrE,iBAAiB;IACjB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,sBAAsB;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC9D,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAChF,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACxD,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,0CAA0C;IAC1C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,2DAA2D;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAsED,wBAAgB,0BAA0B,CAAC,OAAO,SAAS,sBAAsB,EAC/E,MAAM,EAAE,0BAA0B,CAAC,OAAO,CAAC,GAC1C,oBAAoB,CAiJtB"}

package/dist/telegram/update-store-check.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The rules of `TelegramUpdateStore`, as a check any store can be put
+ * through — the ones shipped here and an application's own over its ORM.
+ *
+ * A store is five conditional statements, and each is easy to write almost
+ * right: a claim that does not check the lease, a settle that does not check
+ * the attempt, a claim read and then written in two statements so that two
+ * processes both take one update. Nothing fails in a test with one process;
+ * the update simply runs twice in production. So the check runs every rule on
+ * a fresh store, and races claims against each other.
+ *
+ * It does not depend on a test framework: it returns what was violated, and
+ * an empty list is a store that keeps the rules.
+ */
+import type { TelegramUpdateStore } from './update-store.js';
+/**
+ * Put a store through every rule, each on a fresh store from `make`. Resolves
+ * with the violations — `"<rule>: <what happened>"` — empty when the store
+ * keeps them all. A store that throws violates the rule it threw in.
+ */
+export declare function checkTelegramUpdateStore(make: () => TelegramUpdateStore | Promise<TelegramUpdateStore>): Promise<string[]>;
+//# sourceMappingURL=update-store-check.d.ts.map

package/dist/telegram/update-store-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-store-check.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAqG1D;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAC7D,OAAO,CAAC,MAAM,EAAE,CAAC,CAYnB"}

package/dist/telegram/update-store-postgres.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The update store in Postgres, through whatever client the application
+ * already holds — one function that runs a statement with `$n` parameters and
+ * returns its rows:
+ *
+ * - Bun: `(text, parameters) => sql.unsafe(text, [...parameters])`
+ * - Prisma: `(text, parameters) => prisma.$queryRawUnsafe(text, ...parameters)`
+ * - `pg`: `(text, parameters) => pool.query(text, [...parameters]).then((result) => result.rows)`
+ *
+ * Each rule of `TelegramUpdateStore` is one conditional statement, so a claim
+ * is atomic across every process sharing the table; every statement returns
+ * rows, so a client that has only a "query" call needs nothing else.
+ * Parameters carry explicit casts: a driver that sends a JS number as a
+ * double still lands in a `bigint` column.
+ */
+import type { TelegramUpdateStore } from './update-store.js';
+/** Run one statement with `$1…$n` parameters; resolve with the rows it returned. */
+export type TelegramPostgresQuery = (text: string, parameters: readonly (string | number | null)[]) => Promise<readonly unknown[]>;
+export interface PostgresTelegramUpdateStoreConfig {
+    readonly query: TelegramPostgresQuery;
+    /** Default `telegram_updates`. */
+    readonly table?: string;
+    /**
+     * Create the table on first use when it is missing. Default `true`; set
+     * `false` when migrations own the schema — `postgresTelegramUpdateStoreSchema`
+     * is the statement to put in one.
+     */
+    readonly createTable?: boolean;
+}
+/** The table and its index, for a migration. Safe to run twice. */
+export declare function postgresTelegramUpdateStoreSchema(table?: string): string;
+export declare function postgresTelegramUpdateStore(config: PostgresTelegramUpdateStoreConfig): TelegramUpdateStore;
+//# sourceMappingURL=update-store-postgres.d.ts.map

package/dist/telegram/update-store-postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-store-postgres.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAA4B,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEpF,oFAAoF;AACpF,MAAM,MAAM,qBAAqB,GAAG,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,KAC5C,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;AAEjC,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAaD,mEAAmE;AACnE,wBAAgB,iCAAiC,CAAC,KAAK,SAAqB,GAAG,MAAM,CAapF;AAqBD,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,iCAAiC,GACxC,mBAAmB,CAyGrB"}

package/dist/telegram/user.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A Telegram user in one shape, wherever it came from.
+ *
+ * Telegram sends a user in `snake_case` twice over — the Bot API's `from` on
+ * every update, the Mini App's signed `user` — and every other name this
+ * package publishes is `camelCase`. An application with one `ensureAccount`
+ * receives both, and a surface that switched convention by source would make
+ * it write the same translation twice. So both pass through this schema and
+ * arrive as the same `TelegramUser`.
+ */
+import { z } from 'zod';
+declare const TelegramUserSchema: z.ZodPipe<z.ZodObject<{
+    id: z.ZodInt;
+    is_bot: z.ZodOptional<z.ZodBoolean>;
+    first_name: z.ZodString;
+    last_name: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    language_code: z.ZodOptional<z.ZodString>;
+    is_premium: z.ZodOptional<z.ZodBoolean>;
+    allows_write_to_pm: z.ZodOptional<z.ZodBoolean>;
+    photo_url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    id: number;
+    firstName: string;
+    isBot?: boolean | undefined;
+    lastName?: string | undefined;
+    username?: string | undefined;
+    languageCode?: string | undefined;
+    isPremium?: boolean | undefined;
+    allowsWriteToPm?: boolean | undefined;
+    photoUrl?: string | undefined;
+}, {
+    id: number;
+    is_bot?: boolean | undefined;
+    first_name: string;
+    last_name?: string | undefined;
+    username?: string | undefined;
+    language_code?: string | undefined;
+    is_premium?: boolean | undefined;
+    allows_write_to_pm?: boolean | undefined;
+    photo_url?: string | undefined;
+}>>;
+/** A Telegram user as this package names it; fields Telegram did not send are absent. */
+export type TelegramUser = z.infer<typeof TelegramUserSchema>;
+/**
+ * Telegram's user record — grammY's `ctx.from`, a Bot API `User`, a Mini App's
+ * `user` — as a `TelegramUser`; `undefined` when it is not one.
+ */
+export declare function parseTelegramUser(value: unknown): TelegramUser | undefined;
+export {};
+//# sourceMappingURL=user.d.ts.map

package/dist/telegram/user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/telegram/user.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwBnB,CAAC;AAEN,yFAAyF;AACzF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAG1E"}

package/llms/files.txt

@@ -29,5 +29,8 @@ 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` |
 
 ---

package/llms/observability.txt

@@ -577,6 +577,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.
@@ -889,7 +901,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 |

package/llms/server.4.txt

@@ -357,6 +357,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.
@@ -386,6 +391,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).
 

package/llms/stitchkit.2.txt

@@ -352,8 +352,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
@@ -368,6 +368,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.
@@ -465,6 +510,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

package/llms/stitchkit.3.txt

@@ -41,7 +41,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 |
@@ -54,7 +57,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 |