@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/services/bots.js

@@ -0,0 +1,300 @@
+import { BotToken } from "../contracts/bots.js";
+import { webhookSecret } from "../core/random.js";
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { settle } from "../telegram/classify.js";
+import { isBotUsable, loadBot, tokenAad, webhookAad, withToken } from "../engine/bot-api.js";
+import { botDto } from "../engine/rows.js";
+import { checkBotFeatures } from "../engine/bot-features.js";
+import { STATE_KEYS, setStateSql } from "../engine/state.js";
+import { syncCommandMenu } from "./menu.js";
+// src/services/bots.ts
+const ALLOWED_UPDATES = [
+	"message",
+	"edited_message",
+	"callback_query",
+	"my_chat_member"
+];
+function actorId(rt, actor) {
+	return rt.describe(actor).userId;
+}
+function webhookUrl(rt, botId) {
+	return rt.publicBaseUrl ? `${rt.publicBaseUrl}/webhook/${botId}` : null;
+}
+function unreachable(o) {
+	return o.kind === "network" || o.kind === "timeout" || o.kind === "server_error" || o.kind === "retry_after";
+}
+async function requireBot(rt, id) {
+	const bot = await loadBot(rt, id);
+	if (!bot) throw new TelegramPluginError("not_found", "bot not found");
+	return bot;
+}
+/** Bot API handle for a plaintext token (connect / rotate only, before it is stored). */
+function withPlainToken(rt, token, fn) {
+	return rt.tg.withToken(() => token, fn);
+}
+/** Checks the format, calls getMe and checks that the id matches the token prefix. */
+async function verifyToken(rt, token, mismatch, expectId) {
+	if (!BotToken.safeParse(token).success) throw new TelegramPluginError("bot_token_invalid", "token format is not valid");
+	const prefix = token.slice(0, token.indexOf(":"));
+	const r = await withPlainToken(rt, token, (api) => settle(api.getMe()));
+	if (r.outcome.kind !== "ok" || !r.value) {
+		if (unreachable(r.outcome)) throw new TelegramPluginError("bot_unreachable", "Telegram could not be reached");
+		throw new TelegramPluginError("bot_token_invalid", "Telegram rejected the token");
+	}
+	const me = r.value;
+	if (String(me.id) !== prefix) throw new TelegramPluginError(mismatch, "token does not match the bot id");
+	if (expectId !== void 0 && String(me.id) !== expectId) throw new TelegramPluginError("bot_token_mismatch", "this token belongs to a different bot");
+	return {
+		tgBotId: String(me.id),
+		username: me.username ?? ""
+	};
+}
+/** setWebhook (webhook mode) or deleteWebhook (polling mode). Returns the status to store. */
+async function applyWebhook(rt, bot, secret, dropPending) {
+	const url = webhookUrl(rt, bot.id);
+	return withToken(rt, bot, async (api) => {
+		if (!url) {
+			const r = await settle(api.deleteWebhook({ drop_pending_updates: false }));
+			return {
+				mode: "polling",
+				status: "active",
+				detail: r.outcome.kind === "ok" ? null : r.outcome.description ?? null
+			};
+		}
+		const r = await settle(api.setWebhook({
+			url,
+			secret_token: secret,
+			allowed_updates: ALLOWED_UPDATES,
+			drop_pending_updates: dropPending,
+			max_connections: 40
+		}));
+		if (r.outcome.kind === "ok") return {
+			mode: "webhook",
+			status: "active",
+			detail: null
+		};
+		rt.log.warn("tg.webhook_failed", {
+			botId: bot.id,
+			code: r.outcome.reason ?? r.outcome.kind
+		});
+		return {
+			mode: "webhook",
+			status: "webhook_error",
+			detail: (r.outcome.description ?? "setWebhook failed").slice(0, 300)
+		};
+	});
+}
+function alreadyConnected() {
+	return new TelegramPluginError("validation_failed", "this bot is already connected", { extensions: { issues: [{
+		path: "token",
+		message: "bot already connected"
+	}] } });
+}
+function isBotUniqueViolation(e) {
+	const msg = e instanceof Error ? `${e.message} ${e.cause instanceof Error ? e.cause.message : ""}` : "";
+	return /UNIQUE constraint failed: tg_bot\.|tg_bot_tg_bot_uq/.test(msg);
+}
+async function listBots(rt, opts) {
+	return await rt.db.all(sql`SELECT * FROM tg_bot WHERE tenant = ${rt.tenant} AND deleted_at IS NULL
+        ${opts.cursor ? sql`AND id < ${opts.cursor}` : sql.empty} ORDER BY id DESC LIMIT ${opts.limit + 1}`);
+}
+async function getBot(rt, id) {
+	return botDto(await requireBot(rt, id));
+}
+async function connectBot(rt, actor, input) {
+	if (!rt.publicBaseUrl && rt.appEnv === "production") throw new TelegramPluginError("webhook_url_missing", "publicBaseUrl is required in production");
+	const me = await verifyToken(rt, input.token, "bot_token_invalid");
+	if (await rt.db.first(sql`SELECT id FROM tg_bot WHERE tenant = ${rt.tenant} AND tg_bot_id = ${me.tgBotId} AND deleted_at IS NULL`)) throw alreadyConnected();
+	const now = rt.clock.now();
+	const id = rt.ids.uuid();
+	const secret = webhookSecret(rt.rand);
+	const tokenEnc = await rt.keyring.encrypt(input.token, tokenAad(id));
+	const secretEnc = await rt.keyring.encrypt(secret, webhookAad(id));
+	const by = actorId(rt, actor);
+	const locale = rt.i18n.pick(input.defaultLocale);
+	await rt.db.batch([sql`INSERT INTO tg_bot (id, tenant, name, tg_bot_id, username, token_enc, webhook_secret_enc, mode, status,
+          default_locale, rate_per_sec, created_by, created_at, updated_at)
+        VALUES (${id}, ${rt.tenant}, ${input.name}, ${me.tgBotId}, ${me.username}, ${tokenEnc}, ${secretEnc},
+          ${rt.publicBaseUrl ? "webhook" : "polling"}, 'active', ${locale}, ${rt.limits.perBotPerSec}, ${by}, ${now}, ${now})`, ...rt.audit({
+		actor: by,
+		entity: "telegram_bot",
+		entityId: id,
+		action: "connect",
+		diff: { username: me.username },
+		at: now
+	})]).catch((e) => {
+		throw isBotUniqueViolation(e) ? alreadyConnected() : e;
+	});
+	const hook = await applyWebhook(rt, {
+		id,
+		token_enc: tokenEnc
+	}, secret, true);
+	await rt.db.run(sql`UPDATE tg_bot SET mode = ${hook.mode}, status = ${hook.status}, status_detail = ${hook.detail},
+          checked_at = ${now}, updated_at = ${now} WHERE id = ${id}`);
+	const bot = await requireBot(rt, id);
+	await syncCommandMenu(rt, bot);
+	rt.log.info("tg.bot_connected", {
+		botId: id,
+		mode: hook.mode,
+		status: hook.status
+	});
+	return botDto(await loadBot(rt, id) ?? bot);
+}
+async function patchBot(rt, actor, id, patch) {
+	const bot = await requireBot(rt, id);
+	if (patch.features !== void 0) checkBotFeatures(rt.features, patch.features);
+	const now = rt.clock.now();
+	const sets = [];
+	if (patch.name !== void 0) sets.push(sql`name = ${patch.name}`);
+	if (patch.defaultLocale !== void 0) sets.push(sql`default_locale = ${rt.i18n.pick(patch.defaultLocale)}`);
+	if (patch.features !== void 0) sets.push(sql`features_json = ${JSON.stringify(patch.features)}`);
+	if (patch.ratePerSec !== void 0) sets.push(sql`rate_per_sec = ${patch.ratePerSec}`);
+	if (patch.enabled === false && bot.status !== "disabled") sets.push(sql`status = 'disabled'`);
+	if (patch.enabled === true && bot.status === "disabled") sets.push(sql`status = 'active', paused_until = NULL`);
+	if (sets.length > 0) {
+		const by = actorId(rt, actor);
+		await rt.db.batch([sql`UPDATE tg_bot SET ${sql.join(sets)}, updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${id}`, ...rt.audit({
+			actor: by,
+			entity: "telegram_bot",
+			entityId: id,
+			action: "update",
+			diff: { fields: Object.keys(patch) },
+			at: now
+		})]);
+	}
+	const updated = await requireBot(rt, id);
+	if (updated.status !== bot.status) await rt.hook("onBotStatus", (fn) => fn(botDto(updated)));
+	if ((patch.defaultLocale !== void 0 || patch.features !== void 0) && isBotUsable(updated)) await syncCommandMenu(rt, updated);
+	return botDto(updated);
+}
+/** Soft delete: deleteWebhook (best effort), status disabled, queued deliveries cancelled. */
+async function deleteBot(rt, actor, id) {
+	const bot = await requireBot(rt, id);
+	const now = rt.clock.now();
+	await withToken(rt, bot, (api) => settle(api.deleteWebhook({ drop_pending_updates: true }))).catch(() => null);
+	const by = actorId(rt, actor);
+	await rt.db.batch([
+		sql`UPDATE tg_bot SET status = 'disabled', deleted_at = ${now}, updated_at = ${now}, drain_lease_until = NULL,
+          drain_token = NULL WHERE tenant = ${rt.tenant} AND id = ${id}`,
+		sql`UPDATE tg_delivery SET status = 'cancelled', error_code = 'bot_deleted', updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND bot_id = ${id} AND status IN ('queued', 'sending')`,
+		...rt.audit({
+			actor: by,
+			entity: "telegram_bot",
+			entityId: id,
+			action: "delete",
+			at: now
+		})
+	]);
+	rt.log.info("tg.bot_deleted", { botId: id });
+}
+/** getMe + getWebhookInfo; records status and health (no secrets). */
+async function testBot(rt, id) {
+	const bot = await requireBot(rt, id);
+	const now = rt.clock.now();
+	const expectedUrl = webhookUrl(rt, bot.id);
+	const out = await withToken(rt, bot, async (api) => {
+		const me = await settle(api.getMe());
+		return {
+			me,
+			info: me.outcome.kind === "ok" ? await settle(api.getWebhookInfo()) : null
+		};
+	});
+	let status = bot.status === "disabled" ? "disabled" : "active";
+	let detail = null;
+	const health = {
+		pendingUpdateCount: null,
+		lastErrorAt: null,
+		lastErrorMessage: null,
+		webhookUrlSet: false,
+		checkedAt: now
+	};
+	if (out.me.outcome.kind !== "ok") {
+		if (out.me.outcome.kind === "unauthorized") {
+			status = "invalid_token";
+			detail = out.me.outcome.description ?? "Unauthorized";
+		} else throw new TelegramPluginError("bot_unreachable", "Telegram could not be reached");
+	} else if (out.info?.value) {
+		const w = out.info.value;
+		health.pendingUpdateCount = w.pending_update_count ?? null;
+		health.lastErrorAt = w.last_error_date ? w.last_error_date * 1e3 : null;
+		health.lastErrorMessage = w.last_error_message ?? null;
+		health.webhookUrlSet = w.url !== "" && w.url === expectedUrl;
+		if (bot.mode === "webhook" && !health.webhookUrlSet && status !== "disabled") {
+			status = "webhook_error";
+			detail = "webhook is not set to this app";
+		} else detail = health.lastErrorMessage;
+	}
+	await rt.db.batch([sql`UPDATE tg_bot SET status = ${status}, status_detail = ${detail ? detail.slice(0, 300) : null},
+          checked_at = ${now}, updated_at = ${now},
+          paused_until = CASE WHEN ${status} = 'active' AND status = 'invalid_token' THEN NULL ELSE paused_until END
+        WHERE tenant = ${rt.tenant} AND id = ${id}`, setStateSql(rt, STATE_KEYS.botHealth(id), JSON.stringify(health), now)]);
+	if (status !== bot.status) await rt.hook("onBotStatus", (fn) => fn({
+		...botDto(bot),
+		status,
+		updatedAt: now
+	}));
+	return {
+		ok: status === "active",
+		status,
+		username: out.me.value?.username ?? null,
+		webhookUrlSet: health.webhookUrlSet,
+		pendingUpdateCount: health.pendingUpdateCount,
+		lastErrorAt: health.lastErrorAt,
+		lastErrorMessage: health.lastErrorMessage
+	};
+}
+/** New token from BotFather for the same bot (same `tg_bot_id`); re-encrypt and set the webhook again. */
+async function rotateToken(rt, actor, id, token) {
+	const bot = await requireBot(rt, id);
+	const me = await verifyToken(rt, token, "bot_token_mismatch", bot.tg_bot_id);
+	const now = rt.clock.now();
+	const tokenEnc = await rt.keyring.encrypt(token, tokenAad(id));
+	const secret = bot.webhook_secret_enc ? await rt.keyring.decrypt(bot.webhook_secret_enc, webhookAad(id)) : webhookSecret(rt.rand);
+	const secretEnc = await rt.keyring.encrypt(secret, webhookAad(id));
+	const by = actorId(rt, actor);
+	await rt.db.batch([sql`UPDATE tg_bot SET token_enc = ${tokenEnc}, webhook_secret_enc = ${secretEnc}, username = ${me.username},
+          status = CASE WHEN status = 'disabled' THEN 'disabled' ELSE 'active' END, status_detail = NULL,
+          paused_until = NULL, updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${id}`, ...rt.audit({
+		actor: by,
+		entity: "telegram_bot",
+		entityId: id,
+		action: "rotate_token",
+		at: now
+	})]);
+	const hook = await applyWebhook(rt, {
+		id,
+		token_enc: tokenEnc
+	}, secret, false);
+	await rt.db.run(sql`UPDATE tg_bot SET mode = ${hook.mode},
+          status = CASE WHEN status = 'disabled' THEN 'disabled' ELSE ${hook.status} END,
+          status_detail = ${hook.detail}, checked_at = ${now} WHERE id = ${id}`);
+	const updated = await requireBot(rt, id);
+	if (updated.status !== bot.status) await rt.hook("onBotStatus", (fn) => fn(botDto(updated)));
+	await syncCommandMenu(rt, updated, { force: true });
+	return botDto(updated);
+}
+/** New webhook secret and setWebhook again (also switches polling → webhook once publicBaseUrl is set). */
+async function resetWebhook(rt, actor, id) {
+	const bot = await requireBot(rt, id);
+	const now = rt.clock.now();
+	const secret = webhookSecret(rt.rand);
+	const secretEnc = await rt.keyring.encrypt(secret, webhookAad(id));
+	const by = actorId(rt, actor);
+	await rt.db.batch([sql`UPDATE tg_bot SET webhook_secret_enc = ${secretEnc}, updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${id}`, ...rt.audit({
+		actor: by,
+		entity: "telegram_bot",
+		entityId: id,
+		action: "webhook_reset",
+		at: now
+	})]);
+	const hook = await applyWebhook(rt, bot, secret, false);
+	await rt.db.run(sql`UPDATE tg_bot SET mode = ${hook.mode},
+          status = CASE WHEN status IN ('disabled', 'invalid_token') THEN status ELSE ${hook.status} END,
+          status_detail = ${hook.detail}, checked_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${id}`);
+	const updated = await requireBot(rt, id);
+	if (updated.status !== bot.status) await rt.hook("onBotStatus", (fn) => fn(botDto(updated)));
+	return botDto(updated);
+}
+export { ALLOWED_UPDATES, actorId, connectBot, deleteBot, getBot, listBots, patchBot, resetWebhook, rotateToken, testBot, webhookUrl };

package/dist/services/broadcasts.js

@@ -0,0 +1,390 @@
+import { LocalizedText } from "../contracts/common.js";
+import { Recipients } from "../contracts/recipients.js";
+import { BroadcastStats, FileRef } from "../contracts/broadcasts.js";
+import { topics } from "../core/recipients.js";
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { checkBody, renderBody, templateProblem } from "../engine/content/render.js";
+import { hostCan, parseProviderParams, requireProvider, sampleData } from "../engine/content/providers.js";
+import { parseJson, parseObject } from "../engine/rows.js";
+import { buildButtons } from "../engine/content/buttons.js";
+import { viewerData } from "./reports.js";
+import { audienceForPreview, audienceOf } from "../engine/content/audience.js";
+import { templateById, templateModel } from "../engine/content/template-rows.js";
+import { deliveryFragments } from "../engine/outbox/enqueue.js";
+import { actorId } from "./bots.js";
+import { fanOut } from "../engine/content/fanout.js";
+import { resolveRecipients } from "../engine/content/recipients.js";
+// src/services/broadcasts.ts
+const STATUSES = [
+	"draft",
+	"queued",
+	"sending",
+	"done"
+];
+function broadcastDto(r) {
+	return {
+		id: r.id,
+		title: r.title,
+		templateId: r.template_id,
+		body: parseJson(r.body_json, LocalizedText.nullable(), null),
+		params: parseObject(r.params_json),
+		file: parseJson(r.file_ref, FileRef.nullable(), null),
+		recipients: parseJson(r.recipients_json, Recipients, []),
+		status: STATUSES.includes(r.status) ? r.status : "draft",
+		stats: parseJson(r.stats_json, BroadcastStats.nullable(), null),
+		createdBy: r.created_by,
+		createdAt: r.created_at,
+		sentAt: r.sent_at
+	};
+}
+function issue(path, message) {
+	return new TelegramPluginError("validation_failed", message, { extensions: { issues: [{
+		path,
+		message
+	}] } });
+}
+const json = (v) => v === null || v === void 0 ? null : JSON.stringify(v);
+async function validateSave(rt, save) {
+	if (save.templateId !== null) {
+		if (save.file !== null) throw issue("body.file", "a file broadcast takes an inline caption body, not a template");
+		const row = await templateById(rt, save.templateId);
+		if (!row) throw issue("body.templateId", "template not found");
+		const t = templateModel(row);
+		if (t.kind === "report") throw issue("body.templateId", "broadcasts use message templates");
+		if (t.provider) parseProviderParams(requireProvider(rt, t.provider), {
+			...t.providerParams,
+			...save.params
+		});
+	}
+	if (save.body !== null) {
+		const errors = checkBody(save.body, "html", { filters: rt.filters });
+		if (errors.length > 0) throw templateProblem(errors);
+	}
+	if (save.file !== null && !rt.registry.fileSources.has(save.file.source)) {
+		if (save.file.source !== "files" || !rt.files) throw issue("body.file.source", `unknown file source "${save.file.source}"`);
+	}
+}
+async function listBroadcasts(rt, q, page) {
+	return rt.db.all(sql`SELECT * FROM tg_broadcast WHERE tenant = ${rt.tenant} AND deleted_at IS NULL
+        ${q.status ? sql`AND status = ${q.status}` : sql.empty}
+        ${page.cursor ? sql`AND id < ${page.cursor}` : sql.empty} ORDER BY id DESC LIMIT ${page.limit + 1}`);
+}
+async function requireBroadcast(rt, id) {
+	const row = await rt.db.first(sql`SELECT * FROM tg_broadcast WHERE tenant = ${rt.tenant} AND id = ${id} AND deleted_at IS NULL`);
+	if (!row) throw new TelegramPluginError("not_found", "broadcast not found");
+	return row;
+}
+async function requireDraft(rt, id) {
+	const row = await requireBroadcast(rt, id);
+	if (row.status !== "draft") throw new TelegramPluginError("validation_failed", "only drafts can be changed");
+	return row;
+}
+async function createBroadcast(rt, actor, save) {
+	await validateSave(rt, save);
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	const id = rt.ids.uuid();
+	await rt.db.batch([sql`INSERT INTO tg_broadcast (id, tenant, title, template_id, body_json, params_json, file_ref, recipients_json, status,
+          created_by, created_at, updated_at)
+        VALUES (${id}, ${rt.tenant}, ${save.title}, ${save.templateId}, ${json(save.body)}, ${json(save.params)},
+          ${json(save.file)}, ${JSON.stringify(save.recipients)}, 'draft', ${by}, ${now}, ${now})`, ...rt.audit({
+		actor: by,
+		entity: "telegram_broadcast",
+		entityId: id,
+		action: "create",
+		at: now
+	})]);
+	return broadcastDto(await requireBroadcast(rt, id));
+}
+async function updateBroadcast(rt, actor, id, save) {
+	await requireDraft(rt, id);
+	await validateSave(rt, save);
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	if ((await rt.db.batch([sql`UPDATE tg_broadcast SET title = ${save.title}, template_id = ${save.templateId}, body_json = ${json(save.body)},
+          params_json = ${json(save.params)}, file_ref = ${json(save.file)}, recipients_json = ${JSON.stringify(save.recipients)},
+          updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id} AND status = 'draft' AND deleted_at IS NULL`, ...rt.audit({
+		actor: by,
+		entity: "telegram_broadcast",
+		entityId: id,
+		action: "update",
+		at: now
+	})]))[0]?.changes === 0) throw new TelegramPluginError("validation_failed", "only drafts can be changed");
+	return broadcastDto(await requireBroadcast(rt, id));
+}
+async function deleteBroadcast(rt, actor, id) {
+	await requireDraft(rt, id);
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	await rt.db.batch([sql`UPDATE tg_broadcast SET deleted_at = ${now}, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id} AND status = 'draft'`, ...rt.audit({
+		actor: by,
+		entity: "telegram_broadcast",
+		entityId: id,
+		action: "delete",
+		at: now
+	})]);
+}
+/** Opens a file through its source as `actor` (null at send time re-opens without the check). */
+async function openFile(rt, actor, ref) {
+	let file = null;
+	const def = rt.registry.fileSources.get(ref.source);
+	if (def) file = await def.resolve({
+		actor,
+		ref: ref.ref,
+		env: rt.env
+	});
+	else if (ref.source === "files" && rt.files) {
+		if (!rt.files.canRead || !await rt.files.canRead(actor, ref.ref)) throw new TelegramPluginError("forbidden", "file not readable");
+		file = await rt.files.open(ref.ref, actor);
+	} else throw new TelegramPluginError("validation_failed", `unknown file source "${ref.source}"`);
+	if (!file) throw new TelegramPluginError("not_found", "file not found");
+	await file.body.cancel().catch(() => {});
+	return file;
+}
+/** The message content: a saved template, or an inline body as an ad-hoc template (no provider). */
+async function contentModel(rt, b) {
+	if (b.templateId) {
+		const row = await templateById(rt, b.templateId);
+		if (!row) throw new TelegramPluginError("not_found", "the broadcast's template is gone");
+		return templateModel(row);
+	}
+	if (!b.body) return null;
+	return {
+		id: `broadcast:${b.id}`,
+		key: `broadcast:${b.id}`,
+		name: b.title,
+		kind: "message",
+		provider: null,
+		providerParams: null,
+		body: b.body,
+		format: "html",
+		report: null,
+		layout: null,
+		buttons: null,
+		options: {},
+		version: 1
+	};
+}
+/** What the role / user would get (live provider data, or the provider's sample). Writes nothing. */
+async function previewBroadcast(rt, actor, id, req) {
+	const b = broadcastDto(await requireBroadcast(rt, id));
+	const t = await contentModel(rt, b);
+	const aud = await audienceForPreview(rt, req.as);
+	const tz = rt.settings.timezone;
+	const now = rt.clock.now();
+	let vars = b.templateId ? {} : { ...b.params };
+	if (t?.provider) {
+		const def = requireProvider(rt, t.provider);
+		if (req.sample) vars = sampleData(rt, def);
+		else {
+			if (!await hostCan(rt, aud, def.permission)) throw new TelegramPluginError("provider_forbidden", `this audience may not read "${def.key}"`);
+			const params = parseProviderParams(def, {
+				...t.providerParams,
+				...b.params
+			});
+			vars = await viewerData(rt, {
+				def,
+				actor: aud,
+				viewer: actor,
+				params,
+				now,
+				tz,
+				locale: req.locale
+			});
+		}
+	}
+	const body = t ? renderBody(rt, {
+		body: t.body,
+		format: t.format,
+		vars,
+		locales: [req.locale],
+		tz
+	}) : null;
+	const buttons = await buildButtons(rt, t?.buttons ?? null, {
+		vars,
+		locale: body?.locale ?? req.locale,
+		tz,
+		botId: "",
+		chatRef: null,
+		userId: null,
+		now
+	});
+	let file = null;
+	if (b.file) {
+		const f = await openFile(rt, actor, b.file);
+		file = {
+			name: f.name,
+			mime: f.mime,
+			size: f.size
+		};
+	}
+	return {
+		parts: body?.parts ?? [],
+		buttons: buttons.preview,
+		file,
+		warnings: body?.warnings ?? []
+	};
+}
+function dedupeBase(id, chat) {
+	return `bc:${id}:${chat.chatRef}${chat.messageThreadId ? `#${chat.messageThreadId}` : ""}`;
+}
+const BATCH_STATEMENTS = 50;
+/** File broadcast: one document per chat (caption = the inline body in the chat's locale). */
+async function fanOutFile(rt, b, file, source, targets) {
+	const now = rt.clock.now();
+	let deliveries = 0;
+	let chats = 0;
+	let skipped = 0;
+	let batch = [];
+	const flush = async () => {
+		if (batch.length === 0) return;
+		for (const r of await rt.db.batch(batch)) deliveries += r.changes;
+		batch = [];
+	};
+	for (const { chat, notBefore } of targets) {
+		const aud = await audienceOf(rt, chat.row, false);
+		if (!aud) {
+			skipped++;
+			continue;
+		}
+		const tz = chat.row.timezone ?? rt.settings.timezone;
+		const caption = b.body ? renderBody(rt, {
+			body: b.body,
+			format: "html",
+			vars: { ...b.params },
+			locales: [
+				chat.row.locale,
+				aud.info.locale,
+				chat.bot.default_locale
+			],
+			tz,
+			noSplit: true
+		}).html : "";
+		const rows = deliveryFragments(rt, {
+			botId: chat.botId,
+			chatRef: chat.chatRef,
+			threadId: chat.messageThreadId ?? null,
+			source: "broadcast",
+			sourceId: b.id,
+			kind: "document",
+			html: caption,
+			file: {
+				ref: file.ref,
+				name: file.name,
+				mime: file.mime,
+				source
+			},
+			dedupeKey: dedupeBase(b.id, chat),
+			notBefore,
+			render: { broadcast: b.id }
+		}, now);
+		if (batch.length + rows.length > BATCH_STATEMENTS) await flush();
+		batch.push(...rows);
+		chats++;
+	}
+	await flush();
+	return {
+		deliveries,
+		chats,
+		skipped
+	};
+}
+/**
+* Sends a broadcast: draft → sending → done. A broadcast left in `sending` (a crash mid-way) can be sent again
+* and resumes; dedupe keys make that safe. Sending a `done` broadcast again changes nothing.
+*/
+async function sendBroadcast(rt, actor, id) {
+	const current = await requireBroadcast(rt, id);
+	if (current.status === "done") return broadcastDto(current);
+	const b = broadcastDto(current);
+	const template = await contentModel(rt, b);
+	const file = b.file ? await openFile(rt, actor, b.file) : null;
+	if (file && file.size !== null && file.size > 52428800) throw new TelegramPluginError("file_too_large", "the file is over Telegram's 50 MB upload limit");
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	const [claimed] = await rt.db.batch([sql`UPDATE tg_broadcast SET status = 'sending', updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id} AND deleted_at IS NULL AND status IN ('draft', 'sending')`, ...rt.audit({
+		actor: by,
+		entity: "telegram_broadcast",
+		entityId: id,
+		action: "send",
+		at: now
+	})]);
+	if (!claimed || claimed.changes === 0) return broadcastDto(await requireBroadcast(rt, id));
+	const recipients = await resolveRecipients(rt, b.recipients, {
+		topic: topics.broadcast(),
+		now
+	});
+	const targets = [...recipients.send.map((chat) => ({
+		chat,
+		notBefore: void 0
+	})), ...recipients.held.map((h) => ({
+		chat: h.chat,
+		notBefore: h.until
+	}))];
+	if (file && b.file) await fanOutFile(rt, b, file, b.file.source, targets);
+	else if (template) await fanOut(rt, {
+		template,
+		params: b.templateId ? b.params : null,
+		...b.templateId ? {} : {
+			provider: null,
+			vars: () => ({ ...b.params })
+		},
+		recipients,
+		personalize: true,
+		source: "broadcast",
+		sourceId: b.id,
+		dedupeKey: (chat) => dedupeBase(b.id, chat),
+		now,
+		tz: rt.settings.timezone,
+		meta: { broadcast: b.id }
+	});
+	const stats = await broadcastStats(rt, id);
+	const done = rt.clock.now();
+	await rt.db.run(sql`UPDATE tg_broadcast SET status = 'done', sent_at = COALESCE(sent_at, ${done}), stats_json = ${JSON.stringify(stats)},
+          updated_at = ${done}
+        WHERE tenant = ${rt.tenant} AND id = ${id}`);
+	const bots = [...new Set(targets.map((t) => t.chat.botId))];
+	if (bots.length > 0) rt.waitUntil(rt.transport.kick(bots));
+	return broadcastDto(await requireBroadcast(rt, id));
+}
+/**
+* Per-chat outcome from `tg_delivery` (source `broadcast`, source_id = the broadcast). Counts chats (a message to
+* one chat + topic thread), not parts: any failed part → failed, any dropped / cancelled part → dropped, all
+* parts sent → sent, otherwise queued.
+*/
+async function broadcastStats(rt, id) {
+	const rows = await rt.db.all(sql`SELECT COUNT(*) AS n, SUM(status = 'sent') AS sent, SUM(status = 'failed') AS failed,
+          SUM(status IN ('dropped', 'cancelled')) AS dropped
+        FROM tg_delivery WHERE tenant = ${rt.tenant} AND source = 'broadcast' AND source_id = ${id}
+        GROUP BY chat_ref, message_thread_id`);
+	const stats = {
+		total: rows.length,
+		queued: 0,
+		sent: 0,
+		failed: 0,
+		dropped: 0
+	};
+	for (const r of rows) if (r.failed > 0) stats.failed++;
+	else if (r.dropped > 0) stats.dropped++;
+	else if (r.sent === r.n) stats.sent++;
+	else stats.queued++;
+	return stats;
+}
+/** `GET /admin/broadcasts/:id/report`: fresh stats, also stored on the row. */
+async function broadcastReport(rt, id) {
+	if ((await requireBroadcast(rt, id)).status === "draft") return {
+		total: 0,
+		queued: 0,
+		sent: 0,
+		failed: 0,
+		dropped: 0
+	};
+	const stats = await broadcastStats(rt, id);
+	await rt.db.run(sql`UPDATE tg_broadcast SET stats_json = ${JSON.stringify(stats)} WHERE tenant = ${rt.tenant} AND id = ${id}`);
+	return stats;
+}
+export { broadcastDto, broadcastReport, createBroadcast, deleteBroadcast, listBroadcasts, previewBroadcast, requireBroadcast, sendBroadcast, updateBroadcast };