stitchkit 0.100.2 → 0.101.0

package/dist/entrypoints/telegram.js

@@ -1,9 +1,24 @@
 import {
-  isRecord
-} from "../index-hffjpmq9.js";
+  BOT_TOKEN_SECRET
+} from "../index-sznqf8fx.js";
+import {
+  TELEGRAM_SEND_FAILURE_REASONS2,
+  classifyTelegramSendFailure2
+} from "../index-e05cjgtf.js";
+import {
+  TELEGRAM_TEXT_LIMIT2,
+  truncateTelegramHtml2
+} from "../index-nmaqxdx7.js";
+import {
+  isRecord,
+  transportResult
+} 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 {
@@ -175,122 +190,6 @@ async function lockBroadcast(directory, files) {
   throw new Error("Telegram broadcast lock could not be taken");
 }
 
-// src/telegram/send-failure.ts
-var BY_DESCRIPTION = [
-  [/bot was blocked by the user|bot was kicked/i, "blocked-by-user"],
-  [/user is deactivated|account is deactivated/i, "user-deactivated"],
-  [/can'?t initiate conversation|need to start a conversation/i, "not-started"],
-  [/chat not found|peer_id_invalid|user not found/i, "chat-not-found"],
-  [/too many requests|retry later|flood/i, "rate-limited"],
-  [
-    /message is too long|can'?t parse entities|message text is empty|wrong file identifier|button_url_invalid/i,
-    "message-invalid"
-  ]
-];
-var RETRYABLE = new Set([
-  "rate-limited",
-  "server-error"
-]);
-var UNREACHABLE = new Set([
-  "blocked-by-user",
-  "user-deactivated",
-  "chat-not-found",
-  "not-started"
-]);
-function numberAt(value, keys) {
-  if (!isRecord(value))
-    return;
-  for (const key of keys) {
-    const candidate = value[key];
-    if (typeof candidate === "number" && Number.isFinite(candidate))
-      return candidate;
-  }
-  return;
-}
-function statusOf(value, depth = 0) {
-  if (!isRecord(value) || depth > 4)
-    return;
-  const direct = numberAt(value, ["error_code", "statusCode", "status"]);
-  if (direct !== undefined && direct >= 400 && direct < 600)
-    return direct;
-  const nested = value.cause ?? value.response ?? value.error;
-  return nested === value ? undefined : statusOf(nested, depth + 1);
-}
-function retryAfterOf(value, depth = 0) {
-  if (!isRecord(value) || depth > 4)
-    return;
-  const direct = numberAt(value.parameters, ["retry_after"]);
-  if (direct !== undefined)
-    return direct;
-  const nested = value.cause ?? value.response ?? value.error;
-  return nested === value ? undefined : retryAfterOf(nested, depth + 1);
-}
-function descriptionOf(value, depth = 0) {
-  if (typeof value === "string")
-    return value;
-  if (value instanceof Error) {
-    const nested2 = isRecord(value) ? descriptionOf(value.cause, depth + 1) : "";
-    return `${value.message} ${nested2}`.trim();
-  }
-  if (!isRecord(value) || depth > 4)
-    return "";
-  const own = typeof value.description === "string" ? value.description : "";
-  const message = typeof value.message === "string" ? value.message : "";
-  const nested = descriptionOf(value.cause ?? value.response ?? value.error, depth + 1);
-  return [own, message, nested].filter(Boolean).join(" ");
-}
-function classifyTelegramSendFailure(error) {
-  const status = statusOf(error);
-  const retryAfterSeconds = retryAfterOf(error);
-  const description = descriptionOf(error);
-  if (retryAfterSeconds !== undefined) {
-    return {
-      reason: "rate-limited",
-      ...status !== undefined && { status },
-      retryAfterSeconds,
-      retryable: true,
-      recipientUnreachable: false,
-      evidence: "parameters"
-    };
-  }
-  for (const [pattern, reason] of BY_DESCRIPTION) {
-    if (pattern.test(description)) {
-      return {
-        reason,
-        ...status !== undefined && { status },
-        retryable: RETRYABLE.has(reason),
-        recipientUnreachable: UNREACHABLE.has(reason),
-        evidence: "description"
-      };
-    }
-  }
-  if (status === 429) {
-    return {
-      reason: "rate-limited",
-      status,
-      retryable: true,
-      recipientUnreachable: false,
-      evidence: "status"
-    };
-  }
-  if (status !== undefined && status >= 500) {
-    return {
-      reason: "server-error",
-      status,
-      retryable: true,
-      recipientUnreachable: false,
-      evidence: "status"
-    };
-  }
-  return {
-    reason: "unknown",
-    ...status !== undefined && { status },
-    retryable: false,
-    recipientUnreachable: false,
-    evidence: "none"
-  };
-}
-
 // src/telegram/broadcast.ts
 function pause(milliseconds) {
   return new Promise((resolve) => setTimeout(resolve, milliseconds));
@@ -376,7 +275,7 @@ async function runTelegramBroadcast(config) {
           await config.send({ recipient, attempt });
           return { outcome: "delivered" };
         } catch (error) {
-          const failure = classifyTelegramSendFailure(error);
+          const failure = classifyTelegramSendFailure2(error);
           if (failure.recipientUnreachable)
             return { outcome: "unreachable", reason: failure.reason };
           if (failure.reason === "message-invalid")
@@ -444,9 +343,28 @@ function telegramBroadcastSender(config) {
     ...config.fetch && { fetch: config.fetch }
   });
 }
-// src/telegram/init-data.ts
+// src/telegram/crypto.ts
+var encoder = new TextEncoder;
+async function hmacSha256(key, message) {
+  const imported = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return crypto.subtle.sign("HMAC", imported, encoder.encode(message));
+}
+function toHex(buffer) {
+  return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function digestsEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let difference = 0;
+  for (let index = 0;index < a.length; index += 1) {
+    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return difference === 0;
+}
+
+// src/telegram/user.ts
 import { z as z2 } from "zod";
-var TelegramInitDataUserSchema = z2.object({
+var TelegramUserSchema = z2.object({
   id: z2.int(),
   is_bot: z2.boolean().optional(),
   first_name: z2.string(),
@@ -467,28 +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 }
 }));
-var encoder = new TextEncoder;
-async function hmacSha256(key, message) {
-  const imported = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-  return crypto.subtle.sign("HMAC", imported, encoder.encode(message));
-}
-function toHex(buffer) {
-  return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-function digestsEqual(a, b) {
-  if (a.length !== b.length)
-    return false;
-  let difference = 0;
-  for (let index = 0;index < a.length; index += 1) {
-    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
-  }
-  return difference === 0;
+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)
@@ -508,7 +419,7 @@ async function verifyTelegramInitData(options) {
   }
   const dataCheckString = Object.keys(signed).sort().map((key) => `${key}=${signed[key]}`).join(`
 `);
-  const secretKey = await hmacSha256(encoder.encode("WebAppData"), options.botToken);
+  const secretKey = await hmacSha256(encoder2.encode("WebAppData"), options.botToken);
   const expected = toHex(await hmacSha256(secretKey, dataCheckString));
   if (!digestsEqual(expected, hash.toLowerCase())) {
     return { valid: false, reason: "signature-mismatch" };
@@ -634,8 +545,57 @@ function createTelegramLocalFiles(config) {
     }
   };
 }
+// 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 createTelegramOperatorDedupe(options = {}) {
+  const windowMs = options.windowMs ?? 600000;
+  const maxPerWindow = options.maxPerWindow ?? 20;
+  const fingerprint = options.fingerprint ?? defaultFingerprint;
+  const now = options.now ?? Date.now;
+  const repeatedLine = options.repeatedLine ?? ((count) => `(+${count} more like this)`);
+  const overBudgetLine = options.overBudgetLine ?? ((count) => `(+${count} more messages over the limit)`);
+  const recent = new Map;
+  let windowStart = Number.NEGATIVE_INFINITY;
+  let sentInWindow = 0;
+  let overBudget = 0;
+  return (text, topic) => {
+    const at = now();
+    const key = fingerprint(text, topic);
+    const previous = recent.get(key);
+    if (previous && at - previous.sentAt < windowMs) {
+      previous.held += 1;
+      return { send: false, reason: "repeated" };
+    }
+    if (at - windowStart >= windowMs) {
+      windowStart = at;
+      sentInWindow = 0;
+    }
+    if (sentInWindow >= maxPerWindow) {
+      overBudget += 1;
+      return { send: false, reason: "over-budget" };
+    }
+    sentInWindow += 1;
+    for (const [stale, entry] of recent) {
+      if (at - entry.sentAt >= windowMs)
+        recent.delete(stale);
+    }
+    recent.set(key, { sentAt: at, held: 0 });
+    const lines = [text];
+    if (previous?.held)
+      lines.push(repeatedLine(previous.held));
+    if (overBudget > 0)
+      lines.push(overBudgetLine(overBudget));
+    overBudget = 0;
+    return { send: true, text: lines.join(`
+
+`) };
+  };
+}
+
 // src/telegram/operator-channel.ts
-var TEXT_LIMIT = 4096;
 var MASK = "[redacted]";
 function masked(text, patterns) {
   let output = text;
@@ -648,12 +608,12 @@ function literal(value) {
   return new RegExp(value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
 }
 function timer(milliseconds, signal) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve, reject) => {
     if (signal.aborted)
       return reject(signal.reason);
     const handle = setTimeout(() => {
       signal.removeEventListener("abort", stop);
-      resolve2();
+      resolve();
     }, milliseconds);
     const stop = () => {
       clearTimeout(handle);
@@ -664,14 +624,19 @@ function timer(milliseconds, signal) {
 }
 function fitted(text) {
   const points = Array.from(text);
-  return points.length <= TEXT_LIMIT ? text : `${points.slice(0, TEXT_LIMIT - 1).join("")}…`;
+  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;
   const maxAttempts = config.maxAttempts ?? 3;
   const sleep = config.sleep ?? timer;
-  const patterns = [TELEGRAM_BOT_TOKEN_PATTERN, ...config.sensitivePatterns ?? []];
+  const patterns = [
+    TELEGRAM_BOT_TOKEN_PATTERN,
+    ...config.sensitivePatterns ?? [],
+    ...[...config.sensitiveValues ?? []].filter((value) => value !== "").sort((left, right) => right.length - left.length).map(literal)
+  ];
+  const admit = config.dedupe ? createTelegramOperatorDedupe(config.dedupe) : undefined;
   const queue = [];
   const idle = new Set;
   let lifetime = new AbortController;
@@ -708,7 +673,7 @@ function createTelegramOperatorChannel(config) {
     } catch (error) {
       if (signal.aborted)
         throw error;
-      const failure = classifyTelegramSendFailure(error);
+      const failure = classifyTelegramSendFailure2(error);
       if (!failure.retryable) {
         drop(item, "refused", failure);
         return;
@@ -759,6 +724,13 @@ function createTelegramOperatorChannel(config) {
           drop(item, "closed");
           return;
         }
+        const verdict = admit?.(item.text, topic);
+        if (verdict && !verdict.send) {
+          drop(item, verdict.reason);
+          return;
+        }
+        if (verdict)
+          item.text = verdict.text;
         queue.push(item);
         while (queue.length > maxQueued) {
           const oldest = queue.shift();
@@ -777,11 +749,11 @@ function createTelegramOperatorChannel(config) {
     drain(signal) {
       if (queue.length === 0 && inFlight === 0)
         return Promise.resolve();
-      return new Promise((resolve2) => {
+      return new Promise((resolve) => {
         const done = () => {
           signal?.removeEventListener("abort", done);
           idle.delete(done);
-          resolve2();
+          resolve();
         };
         idle.add(done);
         signal?.addEventListener("abort", done, { once: true });
@@ -797,6 +769,9 @@ function createTelegramOperatorChannel(config) {
     }
   };
 }
+function markupFitted(text, parseMode) {
+  return parseMode === "HTML" ? truncateTelegramHtml2(text) : text;
+}
 function telegramOperatorSender(config) {
   const token = literal(config.token);
   return (message, signal) => callTelegramBotApi({
@@ -804,7 +779,7 @@ function telegramOperatorSender(config) {
     method: "sendMessage",
     params: {
       chat_id: message.chatId,
-      text: masked(message.text, [token]),
+      text: markupFitted(masked(message.text, [token]), config.parseMode),
       ...message.threadId !== undefined && { message_thread_id: message.threadId },
       ...config.parseMode && { parse_mode: config.parseMode },
       link_preview_options: { is_disabled: true }
@@ -814,16 +789,661 @@ function telegramOperatorSender(config) {
     ...config.fetch && { fetch: config.fetch }
   });
 }
+// src/telegram/update-intake.ts
+var SWEEP_BATCH = 100;
+function defaultRetry(error, attempt) {
+  const failure = classifyTelegramSendFailure2(error);
+  if (failure.evidence !== "none" && !failure.retryable)
+    return false;
+  const backoff = Math.min(5000 * 4 ** (attempt - 1), 15 * 60000);
+  return Math.max(backoff, (failure.retryAfterSeconds ?? 0) * 1000);
+}
+function lineOf(update) {
+  for (const [key, payload] of Object.entries(update)) {
+    if (key === "update_id" || !isRecord(payload))
+      continue;
+    const message = isRecord(payload.message) ? payload.message : undefined;
+    for (const holder of [
+      payload.chat,
+      message?.chat,
+      payload.from,
+      payload.user,
+      payload.voter_chat
+    ]) {
+      if (isRecord(holder) && (typeof holder.id === "number" || typeof holder.id === "string")) {
+        return `chat:${holder.id}`;
+      }
+    }
+  }
+  return `update:${String(update.update_id)}`;
+}
+function parsed(body) {
+  try {
+    const value = JSON.parse(body);
+    return isRecord(value) && Number.isSafeInteger(value.update_id) && Number(value.update_id) >= 0 ? value : undefined;
+  } catch {
+    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`);
+  }
+  return value;
+}
+function createTelegramUpdateIntake(config) {
+  const { store } = config;
+  const now = config.now ?? Date.now;
+  const retry = config.retry ?? defaultRetry;
+  const maxAttempts = positive("maxAttempts", config.maxAttempts ?? 5);
+  const leaseMs = positive("leaseMs", config.leaseMs ?? 120000);
+  const pendingGraceMs = config.pendingGraceMs ?? 60000;
+  const sweepEveryMs = positive("sweepEveryMs", config.sweepEveryMs ?? 30000);
+  const retainMs = config.retainMs ?? 86400000;
+  const maxConcurrent = positive("maxConcurrent", config.maxConcurrent ?? 32);
+  const lines = new Map;
+  const scheduled = new Set;
+  const waiting = [];
+  let running = 0;
+  let started = false;
+  let timer;
+  const storeError = (error, step) => {
+    try {
+      config.onStoreError?.(error, step);
+    } catch {}
+  };
+  const slot = async () => {
+    if (running < maxConcurrent) {
+      running += 1;
+      return;
+    }
+    await new Promise((resolve) => waiting.push(resolve));
+  };
+  const release = () => {
+    const next = waiting.shift();
+    if (next)
+      next();
+    else
+      running -= 1;
+  };
+  const attempt = async (update, updateId) => {
+    const taken = now();
+    const number = await store.claim(updateId, { now: taken, leaseUntil: taken + leaseMs, maxAttempts }).catch((error) => storeError(error, "claim"));
+    if (number === undefined)
+      return;
+    const renewal = setInterval(() => {
+      store.renew(updateId, number, now() + leaseMs).catch((error) => storeError(error, "renew"));
+    }, Math.max(1, Math.floor(leaseMs / 4)));
+    let settlement;
+    try {
+      await config.handle(transportResult(update));
+      settlement = { state: "completed", at: now() };
+    } 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 };
+      try {
+        config.onFailure?.({ updateId, attempt: number, error, retrying: delay !== false });
+      } catch {}
+    } finally {
+      clearInterval(renewal);
+    }
+    await store.settle(updateId, number, settlement).catch((error) => storeError(error, "settle"));
+  };
+  const schedule = (update) => {
+    const updateId = Number(update.update_id);
+    if (!started || scheduled.has(updateId))
+      return;
+    scheduled.add(updateId);
+    const line = lineOf(update);
+    const next = (lines.get(line) ?? Promise.resolve()).then(async () => {
+      await slot();
+      try {
+        await attempt(update, updateId);
+      } finally {
+        release();
+      }
+    }).finally(() => {
+      scheduled.delete(updateId);
+      if (lines.get(line) === next)
+        lines.delete(line);
+    });
+    lines.set(line, next);
+  };
+  const sweep = async (pendingBefore) => {
+    const at = now();
+    const due = await store.due({ now: at, pendingBefore, limit: SWEEP_BATCH });
+    let count = 0;
+    for (const row of due) {
+      const update = parsed(row.body);
+      if (update && !scheduled.has(row.updateId)) {
+        schedule(update);
+        count += 1;
+      }
+    }
+    await store.prune(at - retainMs);
+    return count;
+  };
+  return {
+    async accept(body) {
+      const update = parsed(body);
+      if (!update)
+        return "invalid";
+      const updateId = Number(update.update_id);
+      const added = await store.add({ updateId, body, receivedAt: now() });
+      if (!added)
+        return "duplicate";
+      schedule(update);
+      return "accepted";
+    },
+    async start() {
+      if (started)
+        return;
+      started = true;
+      await sweep(now());
+      timer = setInterval(() => {
+        sweep(now() - pendingGraceMs).catch((error) => storeError(error, "sweep"));
+      }, sweepEveryMs);
+      timer.unref?.();
+    },
+    sweep: () => sweep(now() - pendingGraceMs),
+    async idle() {
+      while (lines.size > 0)
+        await Promise.all(lines.values());
+    },
+    async close() {
+      started = false;
+      if (timer)
+        clearInterval(timer);
+      timer = undefined;
+      while (lines.size > 0)
+        await Promise.all(lines.values());
+    }
+  };
+}
+// src/telegram/update-store.ts
+function isClaimable(record, now) {
+  if (record.state === "pending")
+    return true;
+  if (record.state === "failed")
+    return record.dueAt <= now;
+  return record.state === "processing" && record.dueAt < now;
+}
+function memoryTelegramUpdateStore() {
+  const records = new Map;
+  const holding = (updateId, attempt) => {
+    const record = records.get(updateId);
+    return record?.state === "processing" && record.attempts === attempt ? record : undefined;
+  };
+  return {
+    async add(update) {
+      if (records.has(update.updateId))
+        return false;
+      records.set(update.updateId, {
+        ...update,
+        state: "pending",
+        attempts: 0,
+        dueAt: update.receivedAt,
+        settledAt: undefined,
+        error: undefined
+      });
+      return true;
+    },
+    async claim(updateId, options) {
+      const record = records.get(updateId);
+      if (!record || !isClaimable(record, options.now))
+        return;
+      if (record.attempts >= options.maxAttempts) {
+        Object.assign(record, {
+          state: "abandoned",
+          settledAt: options.now,
+          error: "attempts spent"
+        });
+        return;
+      }
+      record.state = "processing";
+      record.attempts += 1;
+      record.dueAt = options.leaseUntil;
+      return record.attempts;
+    },
+    async renew(updateId, attempt, leaseUntil) {
+      const record = holding(updateId, attempt);
+      if (record)
+        record.dueAt = leaseUntil;
+      return record !== undefined;
+    },
+    async settle(updateId, attempt, settlement) {
+      const record = holding(updateId, attempt);
+      if (!record)
+        return;
+      record.state = settlement.state;
+      record.error = settlement.state === "completed" ? undefined : settlement.error;
+      if (settlement.state === "failed")
+        record.dueAt = settlement.retryAt;
+      else
+        record.settledAt = settlement.at;
+    },
+    async due(query) {
+      return [...records.values()].filter((record) => record.state === "pending" ? record.receivedAt <= query.pendingBefore : isClaimable(record, query.now)).sort((left, right) => left.updateId - right.updateId).slice(0, query.limit).map(({ updateId, body }) => ({ updateId, body }));
+    },
+    async prune(before) {
+      let pruned = 0;
+      for (const [updateId, record] of records) {
+        if (record.settledAt !== undefined && record.settledAt < before) {
+          records.delete(updateId);
+          pruned += 1;
+        }
+      }
+      return pruned;
+    }
+  };
+}
+// 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}$/;
+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)
+    return;
+  const updateId = "update_id" in row ? row.update_id : undefined;
+  const body = "body" in row ? row.body : undefined;
+  return typeof updateId === "number" && typeof body === "string" ? { updateId, body } : undefined;
+}
+function sqliteTelegramUpdateStore(config) {
+  const table = config.table ?? "telegram_updates";
+  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;
+  database.exec(`CREATE TABLE IF NOT EXISTS ${table} (
+    update_id INTEGER PRIMARY KEY,
+    body TEXT NOT NULL,
+    state TEXT NOT NULL,
+    attempts INTEGER NOT NULL,
+    due_at INTEGER NOT NULL,
+    received_at INTEGER NOT NULL,
+    settled_at INTEGER,
+    error TEXT
+  );
+  CREATE INDEX IF NOT EXISTS ${table}_due ON ${table} (state, due_at);`);
+  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 ${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 ${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 ${CLAIMABLE2})
+     ORDER BY update_id LIMIT ?3`);
+  const prune = database.prepare(`DELETE FROM ${table} WHERE state IN ('completed', 'abandoned') AND settled_at < ?1`);
+  return {
+    async add(update) {
+      return Number(insert.run(update.updateId, update.body, update.receivedAt).changes) > 0;
+    },
+    async claim(updateId, options) {
+      const [row] = take.all(options.now, options.leaseUntil, updateId, options.maxAttempts);
+      const attempts = typeof row === "object" && row !== null && "attempts" in row ? row.attempts : undefined;
+      if (typeof attempts === "number")
+        return attempts;
+      spend.run(options.now, updateId, options.maxAttempts);
+      return;
+    },
+    async renew(updateId, attempt, leaseUntil) {
+      return Number(renew.run(leaseUntil, updateId, attempt).changes) > 0;
+    },
+    async settle(updateId, attempt, settlement) {
+      settle.run(settlement.state, settlement.state === "failed" ? settlement.retryAt : null, settlement.state === "failed" ? null : settlement.at, settlement.state === "completed" ? null : settlement.error, updateId, attempt);
+    },
+    async due(query) {
+      return due.all(query.now, query.pendingBefore, query.limit).flatMap((row) => rowOf(row) ?? []);
+    },
+    async prune(before) {
+      return Number(prune.run(before).changes);
+    }
+  };
+}
+// src/telegram/webhook.ts
+var OWNER_PARAMETER = "owner";
+var OWNER_CONTEXT = "stitchkit:telegram-webhook-owner";
+var SECRET_SHAPE = /^[A-Za-z0-9_-]{1,256}$/;
+var SECRET_HEADER = "x-telegram-bot-api-secret-token";
+var TELEGRAM_WEBHOOK_NONE = "none";
+
+class TelegramWebhookClaimError extends Error {
+  reason;
+  ownerHost;
+  constructor(reason, ownerHost) {
+    super(reason === "not-confirmed" ? `Telegram webhook was set but points to ${ownerHost} after it` : reason === "other-secret" ? `Telegram webhook at ${ownerHost} is registered with another secret; refusing to ` + `replace it. takeoverFrom: '${ownerHost}' replaces it` : `Telegram webhook belongs to ${ownerHost}; refusing to take it over. ` + `takeoverFrom: '${ownerHost}' moves it here`);
+    this.name = "TelegramWebhookClaimError";
+    this.reason = reason;
+    this.ownerHost = ownerHost;
+  }
+}
+function hostOf(url) {
+  if (url === "")
+    return TELEGRAM_WEBHOOK_NONE;
+  return URL.canParse(url) ? new URL(url).host : "unknown";
+}
+function withoutTag(url) {
+  if (!URL.canParse(url))
+    return url;
+  const parsed = new URL(url);
+  parsed.searchParams.delete(OWNER_PARAMETER);
+  return parsed.toString();
+}
+async function telegramWebhookUrl(url, secret) {
+  if (!SECRET_SHAPE.test(secret)) {
+    throw new TypeError("[stitchkit] telegram webhook: a secret is 1–256 of A-Z, a-z, 0-9, _ and -");
+  }
+  const tagged = new URL(url);
+  const tag = toHex(await hmacSha256(new TextEncoder().encode(secret), OWNER_CONTEXT));
+  tagged.searchParams.set(OWNER_PARAMETER, tag.slice(0, 16));
+  return tagged.toString();
+}
+async function webhookInfo(config) {
+  const result = await callTelegramBotApi({ ...botCall(config), method: "getWebhookInfo" });
+  const info = isRecord(result) ? result : {};
+  const at = info.last_error_date;
+  const message = info.last_error_message;
+  return {
+    url: typeof info.url === "string" ? info.url : "",
+    pendingUpdates: typeof info.pending_update_count === "number" ? info.pending_update_count : 0,
+    ...typeof at === "number" && typeof message === "string" && { lastError: { at: at * 1000, message } }
+  };
+}
+function botCall(config) {
+  return {
+    token: config.token,
+    ...config.apiRoot && { apiRoot: config.apiRoot },
+    ...config.fetch && { fetch: config.fetch },
+    ...config.signal && { signal: config.signal }
+  };
+}
+async function claimTelegramWebhook(config) {
+  const url = await telegramWebhookUrl(config.url, config.secret);
+  const current = await webhookInfo(config);
+  const ownerHost = hostOf(current.url);
+  const owned = current.url === url;
+  if (!owned && config.takeoverFrom !== ownerHost) {
+    const sameAddress = current.url !== "" && withoutTag(current.url) === withoutTag(url);
+    throw new TelegramWebhookClaimError(sameAddress ? "other-secret" : "owned-elsewhere", ownerHost);
+  }
+  await callTelegramBotApi({
+    ...botCall(config),
+    method: "setWebhook",
+    params: {
+      url,
+      secret_token: config.secret,
+      drop_pending_updates: config.dropPendingUpdates ?? false,
+      ...config.allowedUpdates && { allowed_updates: config.allowedUpdates },
+      ...config.maxConnections !== undefined && { max_connections: config.maxConnections }
+    }
+  });
+  const confirmed = await webhookInfo(config);
+  if (confirmed.url !== url) {
+    throw new TelegramWebhookClaimError("not-confirmed", hostOf(confirmed.url));
+  }
+  return {
+    url,
+    ...!owned && { takenFrom: ownerHost },
+    pendingUpdates: confirmed.pendingUpdates
+  };
+}
+async function checkTelegramWebhook(config) {
+  const url = await telegramWebhookUrl(config.url, config.secret);
+  const info = await webhookInfo(config);
+  return {
+    owned: info.url === url,
+    ownerHost: hostOf(info.url),
+    pendingUpdates: info.pendingUpdates,
+    ...info.lastError && { lastError: info.lastError }
+  };
+}
+async function receiveTelegramWebhook(request, options) {
+  if (request.method !== "POST") {
+    return new Response(null, { status: 405, headers: { allow: "POST" } });
+  }
+  const secret = request.headers.get(SECRET_HEADER);
+  if (secret === null || !digestsEqual(secret, options.secret)) {
+    return new Response(null, { status: 403 });
+  }
+  const acceptance = await options.accept(await request.text());
+  return new Response(null, { status: acceptance === "invalid" ? 400 : 200 });
+}
 export {
-  verifyTelegramInitData,
-  telegramOperatorSender,
-  telegramBroadcastSender,
-  runTelegramBroadcast,
-  createTelegramOperatorChannel,
-  createTelegramLocalFiles,
-  classifyTelegramSendFailure,
-  callTelegramBotApi,
-  TelegramLocalFileError,
+  TELEGRAM_BOT_TOKEN_PATTERN,
+  TELEGRAM_SEND_FAILURE_REASONS2 as TELEGRAM_SEND_FAILURE_REASONS,
+  TELEGRAM_WEBHOOK_NONE,
   TelegramBotApiError,
-  TELEGRAM_BOT_TOKEN_PATTERN
+  TelegramLocalFileError,
+  TelegramWebhookClaimError,
+  callTelegramBotApi,
+  checkTelegramUpdateStore,
+  checkTelegramWebhook,
+  claimTelegramWebhook,
+  classifyTelegramSendFailure2 as classifyTelegramSendFailure,
+  createTelegramLocalFiles,
+  createTelegramOperatorChannel,
+  createTelegramOperatorDedupe,
+  createTelegramUpdateIntake,
+  memoryTelegramUpdateStore,
+  parseTelegramUser,
+  postgresTelegramUpdateStore,
+  postgresTelegramUpdateStoreSchema,
+  receiveTelegramWebhook,
+  redactTelegramBotToken,
+  runTelegramBroadcast,
+  sqliteTelegramUpdateStore,
+  telegramBroadcastSender,
+  telegramOperatorSender,
+  telegramWebhookUrl,
+  verifyTelegramInitData
 };