stitchkit 0.100.3 → 0.101.0

package/CHANGELOG.md

@@ -15,6 +15,73 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.101.0] — 2026-09-29
+
+### ⚠️ Breaking changes
+
+- **`stitchkit/telegram`** — `TelegramInitDataUser` is `TelegramUser`. The same
+  camelCase record now also comes out of `parseTelegramUser(ctx.from)`, so its
+  name says any Telegram user. `import type { TelegramInitDataUser }` →
+  `import type { TelegramUser }`.
+- **`stitchkit/telegram`** — `TELEGRAM_BOT_TOKEN_PATTERN` matches the secret
+  half of a token only, after `<bot id>:`, so masking with it keeps the bot's id
+  (`123456:[redacted]`) — the only thing in a masked line that says which bot
+  failed. Masking no longer needs it at all: `redact` masks bot tokens by shape.
+  `sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN]` → nothing;
+  `text.replace(new RegExp(TELEGRAM_BOT_TOKEN_PATTERN.source, 'g'), …)` →
+  `redactTelegramBotToken(text)`. See ADR 0214 and the 0.101.0 migration in
+  `docs/guide/upgrading.md`.
+
+**Who must act:** code that names the type `TelegramInitDataUser` (rename the
+import), and code that uses `TELEGRAM_BOT_TOKEN_PATTERN` to find or cut a whole
+token. Code that only passes the pattern to a logger keeps working — and can
+drop it, since tokens are masked by shape.
+
+### Added
+
+- `stitchkit/telegram` — `postgresTelegramUpdateStore`: the webhook update store
+  in Postgres over one `query(text, parameters)` the application already has —
+  Bun `sql.unsafe`, Prisma `$queryRawUnsafe`, `pg` `pool.query` — each rule one
+  conditional statement with explicit casts, so a claim is atomic across
+  processes and a driver returning `bigint` as a string or a `bigint` reads the
+  same. `postgresTelegramUpdateStoreSchema(table)` is the table for a migration;
+  `createTable: false` leaves the schema to it.
+- `stitchkit/telegram` — `checkTelegramUpdateStore(make)`: every rule of
+  `TelegramUpdateStore` on a fresh store, eight claims raced against each other,
+  resolving with the violations. A store of one's own over an ORM is checked by
+  the rules the shipped memory, SQLite and Postgres stores pass.
+- `stitchkit/telegram` — `createTelegramOperatorDedupe`: the operator channel's
+  dedupe window alone, for a bot that sends alerts itself — `(text, topic?)` is
+  `{ send: true, text }` with the held-back counts, or `{ send: false, reason }`.
+- `stitchkit/telegram` — `parseTelegramUser`: grammY's `ctx.from`, a Bot API
+  `User` or a Mini App `user` as the one `TelegramUser` initData returns.
+- `stitchkit/telegram` — `TELEGRAM_SEND_FAILURE_REASONS`, every reason as a
+  list; the reasons' traits are one table, so a new reason without its traits
+  does not compile.
+- `stitchkit/telegram` — `redactTelegramBotToken(text)`.
+
+### Changed
+
+- `stitchkit/observability` — `redact`, and so every logger and audit sink,
+  masks secrets by shape in every string: the secret half of a bot token, the
+  password in `scheme://user:password@host`, and the value of a query parameter
+  named as a secret (`token`, `access_token`, `api-key`, `key`, `sig`, …). A URL
+  in an error message is the usual way a token reaches a journal, and no key
+  name marks it.
+- `stitchkit/observability` — an error keeps its own fields: a
+  `TelegramBotApiError`'s `error_code` and `parameters`, a provider's `status`,
+  written beside `name`, `message`, `stack` and `cause` and masked by the same
+  rules. A field holding a class instance other than an error — grammY's
+  `BotError.ctx` — is written as its class name, so one error cannot push its
+  line past the bound and lose the stack.
+
+### Fixed
+
+- `stitchkit/telegram` — the update intake unwraps grammY's `BotError`: a
+  `retry`, an `onFailure` and the error stored with the update saw the wrapper
+  ("Error in middleware: …") instead of what the middleware threw, so a retry
+  policy could not recognise the bot's own terminal error and retried it.
+
 ## [0.100.3] — 2026-09-29
 
 ### Added

package/dist/entrypoints/application.js

@@ -73,9 +73,10 @@ import {
   ApplicationAdmissionError2,
   createApplication2
 } from "../index-w575evhq.js";
+import"../index-sznqf8fx.js";
 import {
   measureSize2
-} from "../index-kzz6rq0w.js";
+} from "../index-e6c2spsd.js";
 import"../index-rfkh44ss.js";
 import {
   diff,

package/dist/entrypoints/observability.js

@@ -19,12 +19,13 @@ import {
   childSpan2,
   resolvePropagationContext2
 } from "../index-hby4qhax.js";
+import"../index-sznqf8fx.js";
 import {
   redact2,
   truncatePreview2,
   sanitizePayload2,
   measureSize2
-} from "../index-kzz6rq0w.js";
+} from "../index-e6c2spsd.js";
 import {
   runWithRequestContext2,
   getRequestContext2,

package/dist/entrypoints/telegram/screens.js

@@ -9,7 +9,7 @@ import {
 } from "../../index-m38ej7e5.js";
 import {
   classifyTelegramEditRefusal
-} from "../../index-6k1svmjh.js";
+} from "../../index-e05cjgtf.js";
 import {
   checkTelegramHtml2
 } from "../../index-rz3z13e9.js";

package/dist/entrypoints/telegram.d.ts

@@ -1,11 +1,15 @@
-export { callTelegramBotApi, TELEGRAM_BOT_TOKEN_PATTERN, type TelegramBotApiCall, TelegramBotApiError, } from '../telegram/bot-api.js';
+export { callTelegramBotApi, redactTelegramBotToken, TELEGRAM_BOT_TOKEN_PATTERN, type TelegramBotApiCall, TelegramBotApiError, } from '../telegram/bot-api.js';
 export { runTelegramBroadcast, type TelegramBroadcastConfig, type TelegramBroadcastMessage, type TelegramBroadcastOutcome, type TelegramBroadcastRecipient, type TelegramBroadcastReport, type TelegramBroadcastRunOutcome, type TelegramBroadcastSend, type TelegramBroadcastSenderConfig, telegramBroadcastSender, } from '../telegram/broadcast.js';
-export { type TelegramInitData, type TelegramInitDataRefusal, type TelegramInitDataUser, type TelegramInitDataVerification, type VerifyTelegramInitDataOptions, verifyTelegramInitData, } from '../telegram/init-data.js';
+export { type TelegramInitData, type TelegramInitDataRefusal, type TelegramInitDataVerification, type VerifyTelegramInitDataOptions, verifyTelegramInitData, } from '../telegram/init-data.js';
 export { createTelegramLocalFiles, TelegramLocalFileError, type TelegramLocalFileRefusal, type TelegramLocalFiles, type TelegramLocalFilesCheck, type TelegramLocalFilesConfig, } from '../telegram/local-files.js';
-export { createTelegramOperatorChannel, type TelegramChatId, type TelegramOperatorChannel, type TelegramOperatorChannelConfig, type TelegramOperatorDedupe, type TelegramOperatorDrop, type TelegramOperatorMessage, type TelegramOperatorSenderConfig, telegramOperatorSender, } from '../telegram/operator-channel.js';
-export { classifyTelegramSendFailure, type TelegramSendFailure, type TelegramSendFailureReason, } from '../telegram/send-failure.js';
+export { createTelegramOperatorChannel, type TelegramChatId, type TelegramOperatorChannel, type TelegramOperatorChannelConfig, type TelegramOperatorDrop, type TelegramOperatorMessage, type TelegramOperatorSenderConfig, telegramOperatorSender, } from '../telegram/operator-channel.js';
+export { createTelegramOperatorDedupe, type TelegramOperatorDedupe, type TelegramOperatorDedupeVerdict, } from '../telegram/operator-dedupe.js';
+export { classifyTelegramSendFailure, TELEGRAM_SEND_FAILURE_REASONS, type TelegramSendFailure, type TelegramSendFailureReason, } from '../telegram/send-failure.js';
 export { createTelegramUpdateIntake, type TelegramUpdateEnvelope, type TelegramUpdateFailure, type TelegramUpdateIntake, type TelegramUpdateIntakeConfig, type TelegramUpdateStoreStep, } from '../telegram/update-intake.js';
 export { memoryTelegramUpdateStore, type StoredTelegramUpdate, type TelegramUpdateClaimOptions, type TelegramUpdateDueQuery, type TelegramUpdateSettlement, type TelegramUpdateState, type TelegramUpdateStore, } from '../telegram/update-store.js';
+export { checkTelegramUpdateStore } from '../telegram/update-store-check.js';
+export { type PostgresTelegramUpdateStoreConfig, postgresTelegramUpdateStore, postgresTelegramUpdateStoreSchema, type TelegramPostgresQuery, } from '../telegram/update-store-postgres.js';
 export { type SqliteTelegramUpdateStoreConfig, sqliteTelegramUpdateStore, type TelegramSqliteDatabase, } from '../telegram/update-store-sqlite.js';
+export { parseTelegramUser, type TelegramUser } from '../telegram/user.js';
 export { type ClaimTelegramWebhookConfig, checkTelegramWebhook, claimTelegramWebhook, type ReceiveTelegramWebhookOptions, receiveTelegramWebhook, TELEGRAM_WEBHOOK_NONE, type TelegramUpdateAcceptance, type TelegramWebhookClaim, TelegramWebhookClaimError, type TelegramWebhookConfig, type TelegramWebhookRefusal, type TelegramWebhookState, telegramWebhookUrl, } from '../telegram/webhook.js';
 //# sourceMappingURL=telegram.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/entrypoints/telegram.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,KAAK,kBAAkB,EACvB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,6BAA6B,EAC7B,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,0BAA0B,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,GAC7B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,yBAAyB,EACzB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,+BAA+B,EACpC,yBAAyB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,KAAK,0BAA0B,EAC/B,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,6BAA6B,EAClC,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/entrypoints/telegram.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,0BAA0B,EAC1B,KAAK,kBAAkB,EACvB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,oBAAoB,EACpB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAClC,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,6BAA6B,EAC7B,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,4BAA4B,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,0BAA0B,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,GAC7B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,yBAAyB,EACzB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EACL,KAAK,iCAAiC,EACtC,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,qBAAqB,GAC3B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,KAAK,+BAA+B,EACpC,yBAAyB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EACL,KAAK,0BAA0B,EAC/B,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,6BAA6B,EAClC,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/entrypoints/telegram.js

@@ -1,6 +1,10 @@
 import {
+  BOT_TOKEN_SECRET
+} from "../index-sznqf8fx.js";
+import {
+  TELEGRAM_SEND_FAILURE_REASONS2,
   classifyTelegramSendFailure2
-} from "../index-6k1svmjh.js";
+} from "../index-e05cjgtf.js";
 import {
   TELEGRAM_TEXT_LIMIT2,
   truncateTelegramHtml2
@@ -11,7 +15,10 @@ import {
 } from "../index-9jfdm5tg.js";
 
 // src/telegram/bot-api.ts
-var TELEGRAM_BOT_TOKEN_PATTERN = /\d{5,}:[A-Za-z0-9_-]{30,}/;
+var TELEGRAM_BOT_TOKEN_PATTERN = BOT_TOKEN_SECRET;
+function redactTelegramBotToken(text) {
+  return text.replace(new RegExp(BOT_TOKEN_SECRET.source, "g"), "[redacted]");
+}
 var DEFAULT_API_ROOT = "https://api.telegram.org";
 
 class TelegramBotApiError extends Error {
@@ -336,9 +343,6 @@ function telegramBroadcastSender(config) {
     ...config.fetch && { fetch: config.fetch }
   });
 }
-// src/telegram/init-data.ts
-import { z as z2 } from "zod";
-
 // src/telegram/crypto.ts
 var encoder = new TextEncoder;
 async function hmacSha256(key, message) {
@@ -358,9 +362,9 @@ function digestsEqual(a, b) {
   return difference === 0;
 }
 
-// src/telegram/init-data.ts
-var encoder2 = new TextEncoder;
-var TelegramInitDataUserSchema = z2.object({
+// src/telegram/user.ts
+import { z as z2 } from "zod";
+var TelegramUserSchema = z2.object({
   id: z2.int(),
   is_bot: z2.boolean().optional(),
   first_name: z2.string(),
@@ -381,11 +385,21 @@ var TelegramInitDataUserSchema = z2.object({
   ...user.allows_write_to_pm !== undefined && { allowsWriteToPm: user.allows_write_to_pm },
   ...user.photo_url !== undefined && { photoUrl: user.photo_url }
 }));
+function parseTelegramUser(value) {
+  const parsed = TelegramUserSchema.safeParse(value);
+  return parsed.success ? parsed.data : undefined;
+}
+
+// src/telegram/init-data.ts
+var encoder2 = new TextEncoder;
 function optionalUser(raw, key) {
   const encoded = raw[key];
   if (encoded === undefined)
     return;
-  return TelegramInitDataUserSchema.parse(JSON.parse(encoded));
+  const user = parseTelegramUser(JSON.parse(encoded));
+  if (user === undefined)
+    throw new TypeError(`initData ${key} is not a Telegram user`);
+  return user;
 }
 async function verifyTelegramInitData(options) {
   if (!options.botToken)
@@ -531,42 +545,12 @@ function createTelegramLocalFiles(config) {
     }
   };
 }
-// src/telegram/operator-channel.ts
-var MASK = "[redacted]";
-function masked(text, patterns) {
-  let output = text;
-  for (const pattern of patterns) {
-    output = output.replace(new RegExp(pattern.source, `${pattern.flags.replace(/[gy]/g, "")}g`), MASK);
-  }
-  return output;
-}
-function literal(value) {
-  return new RegExp(value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
-}
-function timer(milliseconds, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal.aborted)
-      return reject(signal.reason);
-    const handle = setTimeout(() => {
-      signal.removeEventListener("abort", stop);
-      resolve();
-    }, milliseconds);
-    const stop = () => {
-      clearTimeout(handle);
-      reject(signal.reason);
-    };
-    signal.addEventListener("abort", stop, { once: true });
-  });
-}
-function fitted(text) {
-  const points = Array.from(text);
-  return points.length <= TELEGRAM_TEXT_LIMIT2 ? text : `${points.slice(0, TELEGRAM_TEXT_LIMIT2 - 1).join("")}…`;
-}
+// src/telegram/operator-dedupe.ts
 function defaultFingerprint(text, topic) {
   const blanked = text.replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "#").replace(/\b[a-z0-9]{20,}\b/gi, "#").replace(/\d+/g, "#");
   return `${topic ?? ""}\x00${blanked.slice(0, 300)}`;
 }
-function dedupeWindow(options) {
+function createTelegramOperatorDedupe(options = {}) {
   const windowMs = options.windowMs ?? 600000;
   const maxPerWindow = options.maxPerWindow ?? 20;
   const fingerprint = options.fingerprint ?? defaultFingerprint;
@@ -610,6 +594,38 @@ function dedupeWindow(options) {
 `) };
   };
 }
+
+// src/telegram/operator-channel.ts
+var MASK = "[redacted]";
+function masked(text, patterns) {
+  let output = text;
+  for (const pattern of patterns) {
+    output = output.replace(new RegExp(pattern.source, `${pattern.flags.replace(/[gy]/g, "")}g`), MASK);
+  }
+  return output;
+}
+function literal(value) {
+  return new RegExp(value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+}
+function timer(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted)
+      return reject(signal.reason);
+    const handle = setTimeout(() => {
+      signal.removeEventListener("abort", stop);
+      resolve();
+    }, milliseconds);
+    const stop = () => {
+      clearTimeout(handle);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", stop, { once: true });
+  });
+}
+function fitted(text) {
+  const points = Array.from(text);
+  return points.length <= TELEGRAM_TEXT_LIMIT2 ? text : `${points.slice(0, TELEGRAM_TEXT_LIMIT2 - 1).join("")}…`;
+}
 function createTelegramOperatorChannel(config) {
   const maxQueued = config.maxQueued ?? 200;
   const minIntervalMs = config.minIntervalMs ?? 3000;
@@ -620,7 +636,7 @@ function createTelegramOperatorChannel(config) {
     ...config.sensitivePatterns ?? [],
     ...[...config.sensitiveValues ?? []].filter((value) => value !== "").sort((left, right) => right.length - left.length).map(literal)
   ];
-  const admit = config.dedupe ? dedupeWindow(config.dedupe) : undefined;
+  const admit = config.dedupe ? createTelegramOperatorDedupe(config.dedupe) : undefined;
   const queue = [];
   const idle = new Set;
   let lifetime = new AbortController;
@@ -809,6 +825,9 @@ function parsed(body) {
     return;
   }
 }
+function handlerError(error) {
+  return error instanceof Error && error.name === "BotError" && "ctx" in error && "error" in error ? error.error : error;
+}
 function positive(name, value) {
   if (!Number.isSafeInteger(value) || value < 1) {
     throw new RangeError(`[stitchkit] telegram update intake: ${name} is a positive integer`);
@@ -862,7 +881,8 @@ function createTelegramUpdateIntake(config) {
     try {
       await config.handle(transportResult(update));
       settlement = { state: "completed", at: now() };
-    } catch (error) {
+    } catch (thrown) {
+      const error = handlerError(thrown);
       const delay = number >= maxAttempts ? false : retry(error, number);
       const message = error instanceof Error ? error.message : String(error);
       settlement = delay === false ? { state: "abandoned", at: now(), error: message } : { state: "failed", at: now(), retryAt: now() + delay, error: message };
@@ -1022,9 +1042,210 @@ function memoryTelegramUpdateStore() {
     }
   };
 }
-// src/telegram/update-store-sqlite.ts
+// src/telegram/update-store-check.ts
+function same(actual, expected) {
+  return JSON.stringify(actual) === JSON.stringify(expected);
+}
+var claim = { maxAttempts: 2 };
+var RULES = {
+  "one record per update_id": async (store, violated) => {
+    if (!await store.add({ updateId: 7, body: "b", receivedAt: 0 }))
+      violated("add of a new update returned false");
+    if (await store.add({ updateId: 7, body: "other", receivedAt: 1 }))
+      violated("add of a recorded update_id returned true");
+  },
+  "a live lease is not taken, a lapsed one is": async (store, violated) => {
+    await store.add({ updateId: 7, body: "b", receivedAt: 0 });
+    if (await store.claim(7, { ...claim, now: 10, leaseUntil: 100 }) !== 1)
+      violated("the first claim was not attempt 1");
+    if (await store.claim(7, { ...claim, now: 50, leaseUntil: 150 }) !== undefined)
+      violated("a claim took an update under a live lease");
+    if (!same(await store.due({ now: 50, pendingBefore: 50, limit: 10 }), []))
+      violated("due listed an update under a live lease");
+    if (!same(await store.due({ now: 101, pendingBefore: 0, limit: 10 }), [
+      { updateId: 7, body: "b" }
+    ]))
+      violated("due did not list an update whose lease lapsed, with its body");
+    if (await store.claim(7, { ...claim, now: 101, leaseUntil: 200 }) !== 2)
+      violated("a lapsed lease was not taken as attempt 2");
+  },
+  "only the attempt holding the update renews or settles it": async (store, violated) => {
+    await store.add({ updateId: 1, body: "b", receivedAt: 0 });
+    await store.claim(1, { ...claim, now: 0, leaseUntil: 10 });
+    await store.claim(1, { ...claim, now: 11, leaseUntil: 50 });
+    if (await store.renew(1, 1, 500))
+      violated("an attempt that lost its lease renewed it");
+    if (!await store.renew(1, 2, 60))
+      violated("the holding attempt could not renew");
+    await store.settle(1, 1, { state: "completed", at: 20 });
+    if ((await store.due({ now: 61, pendingBefore: 0, limit: 10 })).length !== 1)
+      violated("an attempt that lost its lease settled the update");
+    await store.settle(1, 2, { state: "completed", at: 30 });
+    if (!same(await store.due({ now: 1000, pendingBefore: 1000, limit: 10 }), []))
+      violated("a completed update is still due");
+  },
+  "a failed update is due at its retry, spent attempts abandon it": async (store, violated) => {
+    await store.add({ updateId: 2, body: "b", receivedAt: 0 });
+    await store.add({ updateId: 1, body: "a", receivedAt: 5 });
+    await store.claim(2, { ...claim, now: 0, leaseUntil: 10 });
+    await store.settle(2, 1, { state: "failed", at: 1, retryAt: 30, error: "x" });
+    if (!same(await store.due({ now: 29, pendingBefore: 0, limit: 10 }), []))
+      violated("a failed update was due before its retry, or a pending one before its grace");
+    const due = await store.due({ now: 30, pendingBefore: 5, limit: 10 });
+    if (!same(due.map((row) => row.updateId), [1, 2]))
+      violated("due did not list a retry and a pending update in update_id order");
+    if ((await store.due({ now: 30, pendingBefore: 5, limit: 1 })).length !== 1)
+      violated("due ignored its limit");
+    await store.claim(2, { ...claim, now: 30, leaseUntil: 40 });
+    await store.settle(2, 2, { state: "failed", at: 31, retryAt: 35, error: "x" });
+    if (await store.claim(2, { ...claim, now: 36, leaseUntil: 50 }) !== undefined)
+      violated("an update past maxAttempts was claimed");
+    if (!same(await store.due({ now: 100, pendingBefore: 0, limit: 10 }), []))
+      violated("an update past maxAttempts was not abandoned");
+  },
+  "settled updates are forgotten after they are pruned": async (store, violated) => {
+    await store.add({ updateId: 3, body: "b", receivedAt: 0 });
+    await store.claim(3, { ...claim, now: 0, leaseUntil: 10 });
+    await store.settle(3, 1, { state: "abandoned", at: 36, error: "x" });
+    await store.add({ updateId: 4, body: "b", receivedAt: 0 });
+    if (await store.prune(36) !== 0)
+      violated("prune forgot an update settled at its bound");
+    if (await store.prune(37) !== 1)
+      violated("prune did not forget exactly the settled update before its bound");
+    if (!await store.add({ updateId: 3, body: "b", receivedAt: 40 }))
+      violated("a pruned update_id could not be recorded again");
+    if (await store.add({ updateId: 4, body: "b", receivedAt: 40 }))
+      violated("prune forgot an update that was never settled");
+  },
+  "of concurrent claims exactly one takes the update": async (store, violated) => {
+    await store.add({ updateId: 9, body: "b", receivedAt: 0 });
+    const taken = await Promise.all(Array.from({ length: 8 }, () => store.claim(9, { maxAttempts: 5, now: 1, leaseUntil: 100 })));
+    if (taken.filter((attempt) => attempt !== undefined).length !== 1)
+      violated(`${taken.filter((attempt) => attempt !== undefined).length} of 8 concurrent claims took one update`);
+  }
+};
+async function checkTelegramUpdateStore(make) {
+  const violations = [];
+  for (const [name, rule] of Object.entries(RULES)) {
+    try {
+      await rule(await make(), (what) => violations.push(`${name}: ${what}`));
+    } catch (error) {
+      violations.push(`${name}: threw ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return violations;
+}
+// src/telegram/update-store-postgres.ts
 var TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
-var CLAIMABLE = `(state = 'pending' OR (state = 'failed' AND due_at <= ?1)
+function checkedTable(table) {
+  if (!TABLE_NAME.test(table)) {
+    throw new TypeError("[stitchkit] telegram update store: a table name is [A-Za-z_][A-Za-z0-9_]*");
+  }
+  return table;
+}
+function postgresTelegramUpdateStoreSchema(table = "telegram_updates") {
+  const name = checkedTable(table);
+  return `CREATE TABLE IF NOT EXISTS ${name} (
+  update_id BIGINT PRIMARY KEY,
+  body TEXT NOT NULL,
+  state TEXT NOT NULL,
+  attempts INTEGER NOT NULL,
+  due_at BIGINT NOT NULL,
+  received_at BIGINT NOT NULL,
+  settled_at BIGINT,
+  error TEXT
+);
+CREATE INDEX IF NOT EXISTS ${name}_due ON ${name} (state, due_at);`;
+}
+var CLAIMABLE = `(state = 'pending' OR (state = 'failed' AND due_at <= $1::bigint)
+  OR (state = 'processing' AND due_at < $1::bigint))`;
+function integer(value) {
+  if (typeof value === "number")
+    return value;
+  if (typeof value === "bigint" || typeof value === "string" && /^-?\d+$/.test(value)) {
+    return Number(value);
+  }
+  return;
+}
+function field(row, name) {
+  return typeof row === "object" && row !== null && name in row ? Reflect.get(row, name) : undefined;
+}
+function postgresTelegramUpdateStore(config) {
+  const table = checkedTable(config.table ?? "telegram_updates");
+  const { query } = config;
+  let ready;
+  const run = async (text, parameters) => {
+    if (config.createTable !== false) {
+      ready ??= postgresTelegramUpdateStoreSchema(table).split(";").map((statement) => statement.trim()).filter((statement) => statement !== "").reduce((previous, statement) => previous.then(() => query(statement, [])), Promise.resolve()).then(() => {
+        return;
+      }, (error) => {
+        ready = undefined;
+        throw error;
+      });
+      await ready;
+    }
+    return query(text, parameters);
+  };
+  return {
+    async add(update) {
+      const rows = await run(`INSERT INTO ${table} (update_id, body, state, attempts, due_at, received_at)
+         VALUES ($1::bigint, $2::text, 'pending', 0, $3::bigint, $3::bigint)
+         ON CONFLICT (update_id) DO NOTHING RETURNING update_id`, [update.updateId, update.body, update.receivedAt]);
+      return rows.length > 0;
+    },
+    async claim(updateId, options) {
+      const [row] = await run(`UPDATE ${table} SET state = 'processing', attempts = attempts + 1,
+           due_at = $2::bigint, error = NULL
+         WHERE update_id = $3::bigint AND attempts < $4::integer AND ${CLAIMABLE}
+         RETURNING attempts`, [options.now, options.leaseUntil, updateId, options.maxAttempts]);
+      const attempts = integer(field(row, "attempts"));
+      if (attempts !== undefined)
+        return attempts;
+      await run(`UPDATE ${table} SET state = 'abandoned', settled_at = $1::bigint, error = 'attempts spent'
+         WHERE update_id = $2::bigint AND attempts >= $3::integer AND ${CLAIMABLE}
+         RETURNING update_id`, [options.now, updateId, options.maxAttempts]);
+      return;
+    },
+    async renew(updateId, attempt, leaseUntil) {
+      const rows = await run(`UPDATE ${table} SET due_at = $1::bigint
+         WHERE update_id = $2::bigint AND attempts = $3::integer AND state = 'processing'
+         RETURNING update_id`, [leaseUntil, updateId, attempt]);
+      return rows.length > 0;
+    },
+    async settle(updateId, attempt, settlement) {
+      await run(`UPDATE ${table} SET state = $1::text, due_at = COALESCE($2::bigint, due_at),
+           settled_at = $3::bigint, error = $4::text
+         WHERE update_id = $5::bigint AND attempts = $6::integer AND state = 'processing'
+         RETURNING update_id`, [
+        settlement.state,
+        settlement.state === "failed" ? settlement.retryAt : null,
+        settlement.state === "failed" ? null : settlement.at,
+        settlement.state === "completed" ? null : settlement.error,
+        updateId,
+        attempt
+      ]);
+    },
+    async due(options) {
+      const rows = await run(`SELECT update_id, body FROM ${table}
+         WHERE (state = 'pending' AND received_at <= $2::bigint)
+           OR (state <> 'pending' AND ${CLAIMABLE})
+         ORDER BY update_id LIMIT $3::integer`, [options.now, options.pendingBefore, options.limit]);
+      return rows.flatMap((row) => {
+        const updateId = integer(field(row, "update_id"));
+        const body = field(row, "body");
+        return updateId !== undefined && typeof body === "string" ? [{ updateId, body }] : [];
+      });
+    },
+    async prune(before) {
+      const rows = await run(`DELETE FROM ${table} WHERE state IN ('completed', 'abandoned') AND settled_at < $1::bigint
+         RETURNING update_id`, [before]);
+      return rows.length;
+    }
+  };
+}
+// src/telegram/update-store-sqlite.ts
+var TABLE_NAME2 = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+var CLAIMABLE2 = `(state = 'pending' OR (state = 'failed' AND due_at <= ?1)
   OR (state = 'processing' AND due_at < ?1))`;
 function rowOf(row) {
   if (typeof row !== "object" || row === null)
@@ -1035,7 +1256,7 @@ function rowOf(row) {
 }
 function sqliteTelegramUpdateStore(config) {
   const table = config.table ?? "telegram_updates";
-  if (!TABLE_NAME.test(table)) {
+  if (!TABLE_NAME2.test(table)) {
     throw new TypeError("[stitchkit] telegram update store: a table name is [A-Za-z_][A-Za-z0-9_]*");
   }
   const database = config.database;
@@ -1053,14 +1274,14 @@ function sqliteTelegramUpdateStore(config) {
   const insert = database.prepare(`INSERT OR IGNORE INTO ${table} (update_id, body, state, attempts, due_at, received_at)
      VALUES (?1, ?2, 'pending', 0, ?3, ?3)`);
   const take = database.prepare(`UPDATE ${table} SET state = 'processing', attempts = attempts + 1, due_at = ?2, error = NULL
-     WHERE update_id = ?3 AND attempts < ?4 AND ${CLAIMABLE} RETURNING attempts`);
+     WHERE update_id = ?3 AND attempts < ?4 AND ${CLAIMABLE2} RETURNING attempts`);
   const spend = database.prepare(`UPDATE ${table} SET state = 'abandoned', settled_at = ?1, error = 'attempts spent'
-     WHERE update_id = ?2 AND attempts >= ?3 AND ${CLAIMABLE}`);
+     WHERE update_id = ?2 AND attempts >= ?3 AND ${CLAIMABLE2}`);
   const renew = database.prepare(`UPDATE ${table} SET due_at = ?1 WHERE update_id = ?2 AND attempts = ?3 AND state = 'processing'`);
   const settle = database.prepare(`UPDATE ${table} SET state = ?1, due_at = COALESCE(?2, due_at), settled_at = ?3, error = ?4
      WHERE update_id = ?5 AND attempts = ?6 AND state = 'processing'`);
   const due = database.prepare(`SELECT update_id, body FROM ${table}
-     WHERE (state = 'pending' AND received_at <= ?2) OR (state <> 'pending' AND ${CLAIMABLE})
+     WHERE (state = 'pending' AND received_at <= ?2) OR (state <> 'pending' AND ${CLAIMABLE2})
      ORDER BY update_id LIMIT ?3`);
   const prune = database.prepare(`DELETE FROM ${table} WHERE state IN ('completed', 'abandoned') AND settled_at < ?1`);
   return {
@@ -1199,19 +1420,26 @@ async function receiveTelegramWebhook(request, options) {
 }
 export {
   TELEGRAM_BOT_TOKEN_PATTERN,
+  TELEGRAM_SEND_FAILURE_REASONS2 as TELEGRAM_SEND_FAILURE_REASONS,
   TELEGRAM_WEBHOOK_NONE,
   TelegramBotApiError,
   TelegramLocalFileError,
   TelegramWebhookClaimError,
   callTelegramBotApi,
+  checkTelegramUpdateStore,
   checkTelegramWebhook,
   claimTelegramWebhook,
   classifyTelegramSendFailure2 as classifyTelegramSendFailure,
   createTelegramLocalFiles,
   createTelegramOperatorChannel,
+  createTelegramOperatorDedupe,
   createTelegramUpdateIntake,
   memoryTelegramUpdateStore,
+  parseTelegramUser,
+  postgresTelegramUpdateStore,
+  postgresTelegramUpdateStoreSchema,
   receiveTelegramWebhook,
+  redactTelegramBotToken,
   runTelegramBroadcast,
   sqliteTelegramUpdateStore,
   telegramBroadcastSender,

package/dist/entrypoints/tools.js

@@ -57,9 +57,10 @@ import {
   defineContract2
 } from "../index-ck71tbcf.js";
 import"../index-1bx1xv1k.js";
+import"../index-sznqf8fx.js";
 import {
   redact2
-} from "../index-kzz6rq0w.js";
+} from "../index-e6c2spsd.js";
 import {
   AsyncOperationCancelResultSchema2,
   createAsyncOperationSnapshotSchema2,

package/dist/{index-6k1svmjh.js → index-e05cjgtf.js}

@@ -14,16 +14,20 @@ var BY_DESCRIPTION = [
     "message-invalid"
   ]
 ];
-var RETRYABLE = new Set([
-  "rate-limited",
-  "server-error"
-]);
-var UNREACHABLE = new Set([
-  "blocked-by-user",
-  "user-deactivated",
-  "chat-not-found",
-  "not-started"
-]);
+var TRAITS = {
+  "blocked-by-user": { retryable: false, recipientUnreachable: true },
+  "user-deactivated": { retryable: false, recipientUnreachable: true },
+  "chat-not-found": { retryable: false, recipientUnreachable: true },
+  "not-started": { retryable: false, recipientUnreachable: true },
+  "rate-limited": { retryable: true, recipientUnreachable: false },
+  "message-invalid": { retryable: false, recipientUnreachable: false },
+  "server-error": { retryable: true, recipientUnreachable: false },
+  unknown: { retryable: false, recipientUnreachable: false }
+};
+function isSendFailureReason(value) {
+  return Object.hasOwn(TRAITS, value);
+}
+var TELEGRAM_SEND_FAILURE_REASONS2 = Object.keys(TRAITS).filter(isSendFailureReason);
 function numberAt(value, keys) {
   if (!isRecord(value))
     return;
@@ -85,8 +89,7 @@ function classifyTelegramSendFailure2(error) {
       return {
         reason,
         ...status !== undefined && { status },
-        retryable: RETRYABLE.has(reason),
-        recipientUnreachable: UNREACHABLE.has(reason),
+        ...TRAITS[reason],
         evidence: "description"
       };
     }
@@ -138,4 +141,4 @@ function classifyTelegramEditRefusal(error) {
   return "other";
 }
 
-export { classifyTelegramSendFailure2, classifyTelegramEditRefusal };
+export { TELEGRAM_SEND_FAILURE_REASONS2, classifyTelegramSendFailure2, classifyTelegramEditRefusal };