@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/engine/options.d.ts

@@ -0,0 +1,369 @@
+import { BotDto } from "../contracts/bots.js";
+import { ChatDto } from "../contracts/chats.js";
+import { DeliveryDto } from "../contracts/deliveries.js";
+import { FeatureKey } from "../contracts/features.js";
+import { PendingLinkDto } from "../contracts/links.js";
+import { FilterRegistry } from "../core/template/filters.js";
+import { DbPort } from "../ports/db.js";
+import { ActorPort, AuditPort, AuthorizePort, ClockPort, ErrorsPort, FilesPort, I18nPort, IdsPort, KeyringPort, LogPort, MetricsPort, PortOrFactory, RendererPort, SettingsPort, StoredFile, TransportPort, UsersPort } from "../ports/ports.js";
+import { TelegramClient, TelegramClientOptions } from "../telegram/client.js";
+import { ActionDef, AudienceDef, CommandContext, CommandDef, DialogDef, EventDef, FileSourceDef, ProviderDef } from "./registry.js";
+import { Runtime } from "./runtime.js";
+type MaybePromise<T> = T | Promise<T>;
+/** What the `env` mapper returns (evaluated per invocation; never read globals). */
+export interface TelegramEnv {
+  /** D1 binding (or a D1 session), or any `DbPort`. */
+  db: D1Database | D1DatabaseSession | DbPort;
+  /** `TELEGRAM_KEYRING` secret JSON (`{ active, keys }`), or a `KeyringPort`. */
+  keyring: string | {
+    active: string;
+    keys: Record<string, string>;
+  } | KeyringPort;
+  /** Optional Queue producer → queue transport (kick messages, retries). */
+  queue?: Queue<unknown> | undefined;
+  /** Optional TelegramBotDO namespace → DO transport (strict per-bot sender) and DO scheduler wakes. */
+  botDO?: DurableObjectNamespace | undefined;
+  /** Optional Browser Rendering binding (PDF renderer: `browserRunPdf` is used when no pdf renderer is given). */
+  browser?: unknown;
+  /** Optional R2 bucket for report files when the host has no `ports.files` (`r2Files` adapter). */
+  files?: R2Bucket | undefined;
+  /** Public URL where the plugin routes are mounted, for `setWebhook` (`https://app.example.com/api/telegram`). */
+  publicBaseUrl?: string | undefined;
+  /** `production` disables the dev polling route. Default `production`. */
+  appEnv?: string | undefined;
+}
+/** Log level for the default `consoleLog`, or `silent` to drop everything. */
+export type TelegramLogLevel = "debug" | "info" | "warn" | "error" | "silent";
+/**
+ * The host's services (docs/04 §9). `actor` and `authorize` are required; everything else has a default.
+ * `E` is the host's Worker env type (inferred from `options.env`).
+ */
+export interface TelegramPorts<A, E = unknown> {
+  /** Who is calling (admin API) and who a linked Telegram user is. Required. */
+  actor: ActorPort<A>;
+  /** Permission check for plugin permissions (`telegram.*`, with `permissions.prefix`) and host data permissions. Required. */
+  authorize: AuthorizePort<A>;
+  /** User lookup for admin linking (`find`), the user picker (`search` → `GET /admin/users`) and `{ role }` recipients (`byRole`). */
+  users?: UsersPort;
+  /**
+   * File storage for inbound media, dialog uploads and report files. A port, or `(env) => port` for per-request
+   * bindings. Default: `r2Files(env.files)` when the env mapper returns `files`, else none (file features answer
+   * `renderer_unavailable` / "not handled").
+   */
+  files?: PortOrFactory<FilesPort<A>, E>;
+  /** SQL for audit rows in the same batch as each admin write. Default: insert into `tg_audit`. */
+  audit?: AuditPort;
+  /**
+   * Maps plugin problems to the host's error type for the admin/me routes (gets the full problem body). Default:
+   * the routes answer `application/problem+json` themselves. Not used by the programmatic API, which throws
+   * `TelegramPluginError` (map it yourself with `isTelegramPluginError`).
+   */
+  errors?: ErrorsPort;
+  /**
+   * Structured log: a `LogPort`, or a level for the built-in JSON-lines `consoleLog` (with token redaction).
+   * Default `"info"`. Use `"silent"` to drop everything.
+   */
+  log?: LogPort | TelegramLogLevel;
+  /** Time source. Default `Date.now` + `setTimeout`. */
+  clock?: ClockPort;
+  /** Id generator. Default UUIDv7 on the clock. */
+  ids?: IdsPort;
+  /** Locales and optional host translations. Default `{ locales: ["en", "mr"], defaultLocale: "en" }`. */
+  i18n?: I18nPort;
+  /** Default time zone and money formatting. Default `{ timezone: "UTC" }`. */
+  settings?: SettingsPort;
+  /** Counters and timings: a port, or `(env) => port` (for example an Analytics Engine binding). Default none. */
+  metrics?: PortOrFactory<MetricsPort, E>;
+  /** Extra report renderers (receive the invocation's env in `render`). Built-in: `csv`, and `pdf` over `env.browser`. */
+  renderers?: readonly RendererPort<E>[];
+}
+/**
+ * Feature switches (docs/02 §6). Anything not listed is off, except `core` (always on) and `ops` (on by default).
+ * Routes of a disabled feature answer 404 `feature_disabled`. A bot can switch a feature off for itself
+ * (`tg_bot.features_json`) but never on when it is off here.
+ */
+export interface TelegramFeaturesInput {
+  /** Host bot commands (`defineCommand`) and the per-bot command admin. Default off. */
+  commands?: boolean;
+  /** Message templates (`tg_template`) with versions, validation and previews. Default off. */
+  templates?: boolean;
+  /** Recurring schedules (`tg_schedule`) fired by the tick or DO alarms. Default off. */
+  schedules?: boolean;
+  /**
+   * Report templates rendered to files and `/report`. `{ renderers }` limits the formats listed in meta (default:
+   * `csv` plus every `ports.renderers` format). Default off.
+   */
+  reports?: boolean | {
+    renderers?: string[];
+  };
+  /** Host events (`defineEvent`, `plugin.emit()`) routed by event rules. Default off. */
+  events?: boolean;
+  /** One-off broadcasts to many recipients, with preview and progress. Default off. */
+  broadcasts?: boolean;
+  /** Inline-button actions (`defineAction`). Default off. */
+  actions?: boolean;
+  /** Multi-step dialogs (`defineDialog`). Default off. */
+  dialogs?: boolean;
+  /** Photos / documents sent outside dialogs, stored via the files port and passed to `hooks.onInbound`. Default off. */
+  inbound?: boolean;
+  /** Per-chat subscriptions (mute, quiet hours) applied after recipients resolve. Default off. */
+  subscriptions?: boolean;
+  /**
+   * AI bridge. `true` = send intents only (`sendIntent` on, `freeText` off). In object form `sendIntent` defaults
+   * to true (`aiToolSpec`, AI `send`/`enqueue`) and `freeText` to false (`hooks.onFreeText`). Default off.
+   */
+  ai?: boolean | {
+    sendIntent?: boolean;
+    freeText?: boolean;
+  };
+  /** Ops admin routes (`/admin/health`, `/admin/stats`, `/admin/deliveries`). Default on. */
+  ops?: boolean;
+}
+/** Pacing, retry and budget limits (`options.limits`; defaults in `DEFAULT_LIMITS`). */
+export interface TelegramLimits {
+  /** Per-bot send rate (Telegram allows ~30/s). Default 25. */
+  perBotPerSec: number;
+  /** Per-chat interval between messages. Default 1100 ms. */
+  perChatIntervalMs: number;
+  /** Groups / channels per minute. Default 18. */
+  perGroupPerMin: number;
+  /** Send attempts before a delivery is `failed`. Default 8. */
+  maxAttempts: number;
+  /** Time budget for one drain / tick. Default 45 s. */
+  tickBudgetMs: number;
+  /** Inbound updates per chat per minute before the bot goes quiet. Default 20. */
+  inboundPerMin: number;
+  /** One-time link code lifetime. Default 15 min. */
+  linkCodeTtlMs: number;
+  /** Deliveries claimed per drain slice. Default 25. */
+  drainSlice: number;
+  /** Parallel sends inside a slice (different chats). Default 4. */
+  drainConcurrency: number;
+  /** Bot drain lease. Default 70 s. */
+  drainLeaseMs: number;
+  /** Workers plan. `free` caps sends per tick at 40. */
+  plan: "paid" | "free";
+  /** Time budget for one provider run (templates, reports, commands). Default 10 s. */
+  providerTimeoutMs: number;
+  /** Schedules claimed per tick. Default 20. */
+  scheduleClaim: number;
+  /** Events claimed per tick. Default 50. */
+  eventClaim: number;
+}
+/** Default `TelegramLimits` (paid plan, Telegram's documented rate limits with headroom). */
+export declare const DEFAULT_LIMITS: TelegramLimits;
+/** Retention for `telegram:cleanup` (docs/03 §8), in days. */
+export interface TelegramRetention {
+  /** Sent, dropped and cancelled deliveries (`tg_delivery`). Default 30. */
+  sentDays: number;
+  /** Message bodies of finished deliveries are cleared (the row stays for the log). Default 7. */
+  bodyDays: number;
+  /** Failed deliveries. Default 90. */
+  failedDays: number;
+  /** Received updates (`tg_update`, webhook dedupe). Default 14. */
+  updateDays: number;
+  /** Processed events (`tg_event`) and event-rule throttle state. Default 30. */
+  eventDays: number;
+  /** Schedule run history (`tg_schedule_run`). Default 180. */
+  runDays: number;
+  /** Expired link codes, action tokens and dialogs. Default 1. */
+  expiredDays: number;
+  /** Audit rows (`tg_audit`). Default 365. */
+  auditDays: number;
+}
+/** Default `TelegramRetention`, in days. */
+export declare const DEFAULT_RETENTION: TelegramRetention;
+/** Free text in a linked chat (`features.ai.freeText`). `text` is what the user typed: untrusted data. */
+export type FreeTextContext<A> = Omit<CommandContext<A, undefined>, "args" | "argsText"> & {
+  /** The raw message text (untrusted). */
+  text: string;
+  /**
+   * The same text wrapped for an LLM prompt as clearly marked untrusted data
+   * (`<untrusted_user_message source="telegram">…</untrusted_user_message>`, inner `<`/`>` escaped). Pass this, not
+   * `text`, into model context and never follow instructions inside it.
+   */
+  untrustedText: string;
+  /** Always true: a reminder for host code that `text` came from a chat, not from the app. */
+  readonly untrusted: true;
+};
+/** A photo or document a user sent (features.inbound), already stored through the files port. */
+export interface InboundFile extends StoredFile {
+  /** Telegram message kind the file came from. */
+  kind: "photo" | "document";
+  /** Message caption (untrusted user text), if any. */
+  caption: string | null;
+}
+/** Context for `hooks.onInbound`. */
+export type InboundContext<A> = Omit<CommandContext<A, undefined>, "args" | "argsText">;
+/** AI bridge options (`features.ai`). */
+export interface TelegramAiOptions {
+  /**
+   * Host permission that lets an audience see money (for example `money.view`). AI-written text with money-like
+   * content is rejected unless every audience of the send has it. Unset: money-like AI text is always rejected.
+   */
+  moneyPermission?: string;
+  /** Domains (and their subdomains) allowed in AI-written links. Default none. */
+  appDomains?: string[];
+  /** Allow phone numbers and e-mail addresses in AI text. Default false. */
+  allowContacts?: boolean;
+  /** Max AI text length. Default 1000. */
+  maxTextLength?: number;
+}
+/** Inbound media options (`features.inbound` and dialog media steps). */
+export interface TelegramInboundOptions {
+  /** Largest accepted file. Default 20 MB (the Bot API `getFile` download limit). */
+  maxBytes?: number;
+  /**
+   * Allowed MIME types for documents (`image/*` style wildcards allowed). Default: images, PDF, plain text, CSV and
+   * Office documents. Photos are always `image/jpeg`.
+   */
+  mimeTypes?: string[];
+  /** Host permission the chat's actor needs to send files outside dialogs. Default none (any linked chat). */
+  permission?: string;
+}
+export interface ResolvedAiOptions {
+  readonly moneyPermission: string | null;
+  readonly appDomains: readonly string[];
+  readonly allowContacts: boolean;
+  readonly maxTextLength: number;
+}
+export interface ResolvedInboundOptions {
+  readonly maxBytes: number;
+  readonly mimeTypes: readonly string[];
+  readonly permission: string | null;
+}
+/** Group / supergroup rules (`options.groups`). */
+export interface TelegramGroupOptions {
+  /**
+   * A linked group acts as its audience (data visibility = the audience). With `true` (default), host commands,
+   * `/report`, inbound files and AI free text in a group also need the SENDER to have linked their own Telegram on
+   * this bot (like action taps and dialogs); unlinked members get a "link your account first" reply. `false` lets
+   * every member of a linked group act as the group's audience. Commands can override this with `groupMembers`.
+   */
+  requireLinkedSender?: boolean;
+}
+/** `options.groups` after defaults. */
+export interface ResolvedGroupOptions {
+  readonly requireLinkedSender: boolean;
+}
+/** Optional hooks (docs/04 §10). They run in the plugin's waitUntil budget; errors are logged, never thrown. */
+export interface TelegramHooks<A> {
+  /** A chat was linked to an app user (link code, deep link or admin link). */
+  onLinked?(chat: ChatDto, actor: A): MaybePromise<void>;
+  /**
+   * An admin invite for `userId` was used in Telegram and now waits for that user's confirmation in the app
+   * (`/me/links/pending`). Show an in-app notice; if the user already has a linked chat on this bot, the plugin
+   * also tells them there.
+   */
+  onPendingLink?(pending: PendingLinkDto, userId: string): MaybePromise<void>;
+  /** A chat was unlinked or left (`/unlink`, admin unlink, or the bot was removed from the group). */
+  onUnlinked?(chat: ChatDto): MaybePromise<void>;
+  /** The user blocked the bot (Telegram 403 or `my_chat_member`); queued sends to it are cancelled. */
+  onBlocked?(chat: ChatDto): MaybePromise<void>;
+  /** A delivery reached `failed` (permanent error or `limits.maxAttempts` used up). */
+  onDeliveryFailed?(delivery: DeliveryDto): MaybePromise<void>;
+  /** A bot's status changed (for example the token was revoked). */
+  onBotStatus?(bot: BotDto): MaybePromise<void>;
+  /** Last chance to cancel a send: resolve to `false`. Any other value lets it go. */
+  beforeSend?(delivery: DeliveryDto): MaybePromise<unknown>;
+  /** Free text in a linked chat (needs `features.ai.freeText`); reply through `ctx.reply`. */
+  onFreeText?(ctx: FreeTextContext<A>): MaybePromise<void>;
+  /** A `/command` no built-in or host command handles (`text` is the full message). */
+  onUnknownCommand?(ctx: FreeTextContext<A>): MaybePromise<void>;
+  /**
+   * A photo or document outside a dialog (features.inbound), stored through the files port. Resolve to `false`
+   * when the host did not handle it (the user gets a polite "not handled" reply); anything else counts as handled.
+   */
+  onInbound?(ctx: InboundContext<A>, file: InboundFile): MaybePromise<unknown>;
+}
+/**
+ * How queued deliveries are drained: `auto` (default: `do` when `env.botDO` is set, else `queue` when `env.queue` is
+ * set, else `cron`), a fixed choice, or a factory that builds a custom `TransportPort` from the invocation runtime.
+ */
+export type TransportChoice<A = unknown> = "auto" | "cron" | "queue" | "do" | ((rt: Runtime<A>) => TransportPort);
+/** Cron expressions (UTC, croner syntax) of the plugin's jobs; must match the Worker's `triggers.crons`. */
+export interface TelegramCrons {
+  /** Default every minute. */
+  tick: string;
+  /** Default 03:15 UTC daily. */
+  cleanup: string;
+  /** Default 03:45 UTC daily. */
+  rekey: string;
+}
+/**
+ * Options for `createTelegramPlugin<E, A>()`. `E` is the host's Worker env type, `A` the host's actor type.
+ * Only `env` and `ports` (`actor`, `authorize`) are required; every other option is off or defaulted as noted.
+ * Options are validated once at construction (`TelegramConfigError`).
+ */
+export interface TelegramPluginOptions<E, A> {
+  /** Maps the Worker env to what the plugin needs (D1, keyring, optional Queue/DO/R2/Browser), per invocation. Required. */
+  env: (env: E) => TelegramEnv;
+  /** The host's services. `actor` and `authorize` are required. */
+  ports: TelegramPorts<A, E>;
+  /** Feature switches. Default: only `core` (linking, /start, /help) and `ops`. */
+  features?: TelegramFeaturesInput;
+  /** Data providers (`defineProvider`) for templates, reports, commands and events. Default none. */
+  providers?: readonly ProviderDef<unknown, unknown, A>[];
+  /** Host bot commands (`defineCommand`, features.commands). Default none. */
+  commands?: readonly CommandDef<unknown, A>[];
+  /** Host events (`defineEvent`, features.events) emitted with `emit()`. Default none. */
+  events?: readonly EventDef<unknown>[];
+  /** Inline-button actions (`defineAction`, features.actions). Default none. */
+  actions?: readonly ActionDef<unknown, A>[];
+  /** Multi-step dialogs (`defineDialog`, features.dialogs). Default none. */
+  dialogs?: readonly DialogDef<A>[];
+  /** Recipient kinds beyond users/roles/chats (`defineAudience`). Default none. */
+  audiences?: readonly AudienceDef[];
+  /** Host file sources (`defineFileSource`) for file sends; `resolve` gets the invocation env. Default none. */
+  fileSources?: readonly FileSourceDef<A, E>[];
+  /**
+   * Custom template filters by name (`{{ amount | lakh }}`), built with `defineFilter` or a plain function. Used
+   * when rendering, validating and previewing templates and listed in `GET /admin/meta`. Names match
+   * `[a-z][a-zA-Z0-9_]{0,31}` and may not shadow a built-in filter. Default none.
+   */
+  filters?: FilterRegistry;
+  /** Pacing, retries and budgets. Defaults in `DEFAULT_LIMITS`. */
+  limits?: Partial<TelegramLimits>;
+  /** Cleanup retention in days. Defaults in `DEFAULT_RETENTION`. */
+  retention?: Partial<TelegramRetention>;
+  /** Plugin permission names: `prefix` replaces `telegram` (`ops.bots.manage`). Default `telegram`. */
+  permissions?: {
+    prefix?: string;
+  };
+  /** Lifecycle hooks (errors are logged, never thrown). Default none. */
+  hooks?: TelegramHooks<A>;
+  /** Bot API client: a `TelegramClient` (for example over `FakeTelegram`) or options for `fetchTelegram`. Default `fetchTelegram()`. */
+  telegram?: TelegramClient | TelegramClientOptions;
+  /**
+   * Drain transport. `auto` (default): `do` when `env.botDO` is set, else `queue` when `env.queue` is set, else
+   * `cron` (the tick drains). `queue` / `do` throw a config error when their binding is missing.
+   */
+  transport?: TransportChoice<A>;
+  /**
+   * Name of the dead-letter queue whose consumer is this Worker. Plugin messages arriving from it are logged and
+   * their rows marked failed (`error_code = 'dead_letter'`) instead of being retried. Default none.
+   */
+  deadLetterQueue?: string;
+  /** Cron expressions of the three jobs (match them in `wrangler.jsonc` `triggers.crons`). Defaults in `TelegramCrons`. */
+  crons?: Partial<TelegramCrons>;
+  /** Tenant column value (docs/10 D-12), ≤ 64 chars. Default `''`. */
+  tenant?: string;
+  /** Allow one app user to link more than one Telegram account per bot. Default false (relinking replaces). */
+  allowMultipleChatsPerUser?: boolean;
+  /** AI bridge rules (features.ai). */
+  ai?: TelegramAiOptions;
+  /** Inbound media limits (features.inbound and dialog media steps). */
+  inbound?: TelegramInboundOptions;
+  /** Rules for group and supergroup chats. */
+  groups?: TelegramGroupOptions;
+}
+/** Feature flags after defaults. */
+export type FeatureFlags = Readonly<Record<FeatureKey, boolean>> & {
+  /** `features.ai.freeText` resolved (false unless `ai` is on). */
+  readonly aiFreeText: boolean;
+  /** `features.ai.sendIntent` resolved (false unless `ai` is on). */
+  readonly aiSendIntent: boolean;
+  /** `features.reports.renderers`; empty = all available renderers. */
+  readonly reportRenderers: readonly string[];
+};
+export {};

package/dist/engine/options.js

@@ -0,0 +1,81 @@
+// src/engine/options.ts
+/** Default `TelegramLimits` (paid plan, Telegram's documented rate limits with headroom). */
+const DEFAULT_LIMITS = {
+	perBotPerSec: 25,
+	perChatIntervalMs: 1100,
+	perGroupPerMin: 18,
+	maxAttempts: 8,
+	tickBudgetMs: 45e3,
+	inboundPerMin: 20,
+	linkCodeTtlMs: 9e5,
+	drainSlice: 25,
+	drainConcurrency: 4,
+	drainLeaseMs: 7e4,
+	plan: "paid",
+	providerTimeoutMs: 1e4,
+	scheduleClaim: 20,
+	eventClaim: 50
+};
+/** Default `TelegramRetention`, in days. */
+const DEFAULT_RETENTION = {
+	sentDays: 30,
+	bodyDays: 7,
+	failedDays: 90,
+	updateDays: 14,
+	eventDays: 30,
+	runDays: 180,
+	expiredDays: 1,
+	auditDays: 365
+};
+const DEFAULT_INBOUND_MIME = [
+	"image/*",
+	"application/pdf",
+	"text/plain",
+	"text/csv",
+	"application/vnd.openxmlformats-officedocument.*",
+	"application/msword",
+	"application/vnd.ms-excel"
+];
+function resolveAiOptions(o = {}) {
+	return Object.freeze({
+		moneyPermission: o.moneyPermission ?? null,
+		appDomains: Object.freeze([...o.appDomains ?? []]),
+		allowContacts: o.allowContacts === true,
+		maxTextLength: o.maxTextLength ?? 1e3
+	});
+}
+function resolveInboundOptions(o = {}) {
+	return Object.freeze({
+		maxBytes: o.maxBytes ?? 20971520,
+		mimeTypes: Object.freeze([...o.mimeTypes ?? DEFAULT_INBOUND_MIME]),
+		permission: o.permission ?? null
+	});
+}
+function resolveGroupOptions(o = {}) {
+	return Object.freeze({ requireLinkedSender: o.requireLinkedSender !== false });
+}
+function resolveFeatures(input = {}) {
+	const on = (v, dflt = false) => v === void 0 ? dflt : v !== false;
+	const ai = input.ai;
+	const aiObj = typeof ai === "object" ? ai : null;
+	const reports = input.reports;
+	return Object.freeze({
+		core: true,
+		commands: on(input.commands),
+		templates: on(input.templates),
+		schedules: on(input.schedules),
+		reports: on(reports),
+		events: on(input.events),
+		broadcasts: on(input.broadcasts),
+		actions: on(input.actions),
+		dialogs: on(input.dialogs),
+		inbound: on(input.inbound),
+		subscriptions: on(input.subscriptions),
+		ai: on(ai),
+		ops: on(input.ops, true),
+		aiFreeText: aiObj ? aiObj.freeText === true : false,
+		aiSendIntent: aiObj ? aiObj.sendIntent !== false : ai === true,
+		reportRenderers: Object.freeze(typeof reports === "object" ? [...reports.renderers ?? []] : [])
+	});
+}
+export { DEFAULT_INBOUND_MIME, DEFAULT_LIMITS, DEFAULT_RETENTION, resolveAiOptions, resolveFeatures, resolveGroupOptions, resolveInboundOptions };

package/dist/engine/outbox/dead-letter.js

@@ -0,0 +1,78 @@
+import { sql } from "../../ports/sql.js";
+import { deliveryDto } from "../rows.js";
+import { metricCount } from "../metrics.js";
+import { isPluginMessage } from "./transport.js";
+// src/engine/outbox/dead-letter.ts
+async function handleDeadLetters(rt, batch) {
+	const now = rt.clock.now();
+	for (const m of batch.messages) {
+		if (!isPluginMessage(m.body)) {
+			m.ack();
+			continue;
+		}
+		const body = m.body;
+		if (body.tenant !== rt.tenant) {
+			m.ack();
+			continue;
+		}
+		if (body.type === "events") {
+			rt.log.warn("tg.dead_letter", {
+				type: "events",
+				attempts: m.attempts
+			});
+			m.ack();
+			continue;
+		}
+		try {
+			if (body.type === "update") {
+				const updateId = body.update?.update_id;
+				if (typeof updateId === "number") await rt.db.run(sql`UPDATE tg_update SET status = 'failed', error = 'dead_letter', processed_at = ${now}
+                WHERE tenant = ${rt.tenant} AND bot_id = ${body.botId} AND update_id = ${updateId}
+                  AND status != 'done'`);
+				rt.log.error("tg.dead_letter", {
+					botId: body.botId,
+					type: "update",
+					attempts: m.attempts
+				});
+			} else {
+				const failed = await rt.db.all(sql`UPDATE tg_delivery SET status = 'failed', error_code = 'dead_letter', lease_until = NULL,
+                     lease_token = NULL, updated_at = ${now}
+              WHERE tenant = ${rt.tenant} AND bot_id = ${body.botId} AND status = 'sending'
+                AND lease_token IS NOT (SELECT b.drain_token FROM tg_bot b
+                                        WHERE b.id = ${body.botId} AND b.drain_lease_until > ${now})
+              RETURNING *`);
+				rt.log.error("tg.dead_letter", {
+					botId: body.botId,
+					type: "drain",
+					attempts: m.attempts,
+					failed: failed.length
+				});
+				for (const row of failed) {
+					metricCount(rt, "tg.send", 1, {
+						botId: body.botId,
+						outcome: "failed",
+						code: "dead_letter"
+					});
+					await rt.hook("onDeliveryFailed", (fn) => fn({
+						...deliveryDto(row, false),
+						status: "failed",
+						errorCode: "dead_letter",
+						nextAttemptAt: null
+					}));
+				}
+			}
+			metricCount(rt, "tg.dead_letter", 1, {
+				botId: body.botId,
+				outcome: body.type
+			});
+			m.ack();
+		} catch (e) {
+			rt.log.error("tg.dead_letter_failed", {
+				botId: body.botId,
+				error: e instanceof Error ? e.name : "error"
+			});
+			m.retry({ delaySeconds: 30 });
+		}
+	}
+}
+export { handleDeadLetters };

package/dist/engine/outbox/do-registry.d.ts

@@ -0,0 +1,10 @@
+import { Runtime } from "../runtime.js";
+/** What a TelegramBotDO needs from the plugin (a `TelegramPlugin` satisfies it). */
+export interface BotDoHost {
+  /** Builds the runtime for one invocation inside the object. */
+  runtime(env: never, exec?: {
+    waitUntil(p: Promise<unknown>): void;
+  }): Runtime<unknown>;
+}
+/** Registers (or replaces) the plugin a TelegramBotDO uses for `tenant`. The last one registered wins. */
+export declare function registerTelegramPlugin(plugin: BotDoHost, tenant?: string): void;

package/dist/engine/outbox/do-registry.js

@@ -0,0 +1,10 @@
+// src/engine/outbox/do-registry.ts
+const hosts = /* @__PURE__ */ new Map();
+/** Registers (or replaces) the plugin a TelegramBotDO uses for `tenant`. The last one registered wins. */
+function registerTelegramPlugin(plugin, tenant = "") {
+	hosts.set(tenant, plugin);
+}
+function registeredTelegramPlugin(tenant) {
+	return hosts.get(tenant);
+}
+export { registerTelegramPlugin, registeredTelegramPlugin };

package/dist/engine/outbox/do-transport.d.ts

@@ -0,0 +1,33 @@
+import { TransportPort } from "../../ports/ports.js";
+import { Runtime } from "../runtime.js";
+/** The Durable Object transport (`doTransport`): kicks and scheduler wakes go to the bot's TelegramBotDO. */
+export interface DoTransport extends TransportPort {
+  /** Always `"do"`. */
+  readonly name: "do";
+  /** Ask the bot's object to wake at `at` (epoch ms) for due schedules. Earlier wakes win. */
+  scheduleWake(botId: string, at: number): Promise<void>;
+  /**
+   * Replace the object's scheduler wake with `at` (null clears it). Used when the tenant's next schedule moved later
+   * or went away (delete, pause), so a stale earlier wake is dropped instead of firing for nothing.
+   */
+  setWake(botId: string, at: number | null): Promise<void>;
+}
+export interface DoKickBody {
+  tenant: string;
+  botId: string;
+}
+export interface DoWakeBody extends DoKickBody {
+  /** Wake time (epoch ms); null clears the wake (only with `replace`). */
+  at: number | null;
+  /** true: set the wake to `at` exactly. Default false: the earlier of the current wake and `at` wins. */
+  replace?: boolean;
+}
+/** The TelegramBotDO stub of a bot (`idFromName(botId)`). */
+export declare function botStub(ns: DurableObjectNamespace, botId: string): DurableObjectStub;
+/**
+ * Transport over a TelegramBotDO namespace. `kick()` without ids kicks every bot with due work. Kick failures are
+ * logged, never thrown (the minute tick re-kicks).
+ */
+export declare function doTransport<A>(rt: Runtime<A>, ns: DurableObjectNamespace): DoTransport;
+/** True for a `DoTransport` (has `scheduleWake` / `setWake`). */
+export declare function isDoTransport(t: TransportPort): t is DoTransport;

package/dist/engine/outbox/do-transport.js

@@ -0,0 +1,73 @@
+import { botsWithDueWork } from "./drain.js";
+// src/engine/outbox/do-transport.ts
+/** Internal URL the plugin uses to talk to the object (never leaves the Worker). */
+const DO_ORIGIN = "https://telegram-bot.do";
+/** The TelegramBotDO stub of a bot (`idFromName(botId)`). */
+function botStub(ns, botId) {
+	return ns.get(ns.idFromName(botId));
+}
+async function post(rt, ns, path, body) {
+	try {
+		const res = await botStub(ns, body.botId).fetch(`${DO_ORIGIN}${path}`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body)
+		});
+		await res.body?.cancel();
+		if (!res.ok) rt.log.error("tg.do_kick_failed", {
+			botId: body.botId,
+			status: res.status
+		});
+	} catch (e) {
+		rt.log.error("tg.do_kick_failed", {
+			botId: body.botId,
+			error: e instanceof Error ? e.name : "error"
+		});
+	}
+}
+/**
+* Transport over a TelegramBotDO namespace. `kick()` without ids kicks every bot with due work. Kick failures are
+* logged, never thrown (the minute tick re-kicks).
+*/
+function doTransport(rt, ns) {
+	return {
+		name: "do",
+		async kick(botIds) {
+			const ids = [...new Set(botIds ?? await botsWithDueWork(rt, rt.clock.now()))];
+			await Promise.all(ids.map((botId) => post(rt, ns, "/kick", {
+				tenant: rt.tenant,
+				botId
+			})));
+		},
+		async scheduleWake(botId, at) {
+			await post(rt, ns, "/wake", {
+				tenant: rt.tenant,
+				botId,
+				at
+			});
+		},
+		async setWake(botId, at) {
+			await post(rt, ns, "/wake", {
+				tenant: rt.tenant,
+				botId,
+				at,
+				replace: true
+			});
+		}
+	};
+}
+/** True for a `DoTransport` (has `scheduleWake` / `setWake`). */
+function isDoTransport(t) {
+	const d = t;
+	return t.name === "do" && typeof d.scheduleWake === "function" && typeof d.setWake === "function";
+}
+/**
+* Tell the scheduler that `botId` has work at `at` (a schedule's new `next_run_at`). Returns true when a DO
+* scheduler took it; false means the minute tick handles it (cron / queue transports).
+*/
+async function scheduleBotWake(rt, botId, at) {
+	if (at === null || !isDoTransport(rt.transport)) return false;
+	await rt.transport.scheduleWake(botId, at);
+	return true;
+}
+export { DO_ORIGIN, botStub, doTransport, isDoTransport, scheduleBotWake };

package/dist/engine/outbox/drain.d.ts

@@ -0,0 +1,13 @@
+import { BotRow } from "../rows.js";
+/**
+ * Who guarantees a single sender per bot. Default: the D1 bot lease (`tg_bot.drain_lease_until` + fencing token).
+ * The Durable Object transport passes its own (the object itself is the lease), saving the per-slice renew.
+ */
+export interface DrainLease {
+  /** The bot row when this drain may send (usable, not paused, lease taken); null = stop with `lease`. */
+  acquire(now: number): Promise<BotRow | null>;
+  /** Called before every slice; null = the lease was lost. */
+  renew(now: number): Promise<BotRow | null>;
+  /** Gives the lease up (end of the drain). */
+  release(): Promise<void>;
+}