@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/services/events.js

@@ -0,0 +1,20 @@
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError, featureDisabled } from "../engine/errors.js";
+// src/services/events.ts
+function emitEvent(ctx, event, payload, opts = {}) {
+	if (!ctx.enabled) throw featureDisabled("events");
+	const def = ctx.events.get(event);
+	if (!def) throw new TelegramPluginError("validation_failed", `event "${event}" is not registered`);
+	const parsed = def.payload.safeParse(payload);
+	if (!parsed.success) throw new TelegramPluginError("validation_failed", `payload of "${event}" is not valid`, { extensions: { issues: parsed.error.issues.map((i) => ({
+		path: i.path.join("."),
+		message: i.message
+	})) } });
+	const id = ctx.ids.uuid();
+	const dedupe = opts.dedupeKey ?? `evt:${id}`;
+	if (dedupe.length > 200) throw new TelegramPluginError("validation_failed", "dedupeKey is too long (≤ 200)");
+	return [sql`INSERT INTO tg_event (id, tenant, event, payload_json, dedupe_key, occurred_at, status)
+        VALUES (${id}, ${ctx.tenant}, ${event}, ${JSON.stringify(parsed.data)}, ${dedupe}, ${ctx.now()}, 'pending')
+        ON CONFLICT (tenant, dedupe_key) DO NOTHING`];
+}
+export { emitEvent };

package/dist/services/idempotency.js

@@ -0,0 +1,64 @@
+import { sha256Hex } from "../core/random.js";
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+// src/services/idempotency.ts
+const IDEMPOTENCY_PREFIX = "idem:";
+const IDEMPOTENCY_TTL_MS = 864e5;
+/** Lease of an in-flight (`pending`) entry; a request whose lease ran out (not renewed) can be taken over. */
+const IDEMPOTENCY_PENDING_TTL_MS = 6e4;
+/** How often a running request renews its lease (well inside the TTL). */
+const IDEMPOTENCY_RENEW_MS = 2e4;
+/** Reserves the key. Throws `validation_failed` (409) for a body mismatch or a request still in flight. */
+async function reserveIdempotency(rt, input) {
+	if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(input.key)) throw new TelegramPluginError("validation_failed", "Idempotency-Key must be 1–128 chars [A-Za-z0-9_.:-]");
+	const now = rt.clock.now();
+	const stateKey = IDEMPOTENCY_PREFIX + await sha256Hex(crypto.subtle, `${input.actor}|${input.method}|${input.path}|${input.key}`);
+	const hash = await sha256Hex(crypto.subtle, input.body);
+	const lease = crypto.randomUUID();
+	const pending = {
+		hash,
+		pending: true,
+		lease
+	};
+	const inserted = await rt.db.first(sql`INSERT INTO tg_state (tenant, key, value, updated_at) VALUES (${rt.tenant}, ${stateKey}, ${JSON.stringify(pending)}, ${now})
+        ON CONFLICT (tenant, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+          WHERE tg_state.updated_at < ${now - IDEMPOTENCY_TTL_MS}
+             OR (json_extract(tg_state.value, '$.pending') = 1
+                 AND tg_state.updated_at < ${now - IDEMPOTENCY_PENDING_TTL_MS})
+        RETURNING key`);
+	const mine = sql`tenant = ${rt.tenant} AND key = ${stateKey} AND json_extract(value, '$.lease') = ${lease}`;
+	const owned = {
+		replay: null,
+		async save(response) {
+			const value = JSON.stringify({
+				hash,
+				response
+			});
+			await rt.db.run(sql`UPDATE tg_state SET value = ${value}, updated_at = ${rt.clock.now()} WHERE ${mine}`);
+		},
+		async release() {
+			await rt.db.run(sql`DELETE FROM tg_state WHERE ${mine}`);
+		},
+		async renew() {
+			return await rt.db.first(sql`UPDATE tg_state SET updated_at = ${rt.clock.now()} WHERE ${mine} RETURNING key`) !== null;
+		}
+	};
+	if (inserted) return owned;
+	const row = await rt.db.first(sql`SELECT value FROM tg_state WHERE tenant = ${rt.tenant} AND key = ${stateKey}`);
+	let entry = null;
+	try {
+		entry = row ? JSON.parse(row.value) : null;
+	} catch {
+		entry = null;
+	}
+	if (!entry) return owned;
+	if (entry.hash !== hash) throw new TelegramPluginError("validation_failed", "Idempotency-Key was used with a different request", { status: 422 });
+	if (entry.pending || !entry.response) throw new TelegramPluginError("validation_failed", "a request with this Idempotency-Key is still in progress", { status: 409 });
+	return {
+		replay: entry.response,
+		save: async () => {},
+		release: async () => {},
+		renew: async () => false
+	};
+}
+export { IDEMPOTENCY_PENDING_TTL_MS, IDEMPOTENCY_PREFIX, IDEMPOTENCY_RENEW_MS, IDEMPOTENCY_TTL_MS, reserveIdempotency };

package/dist/services/links.js

@@ -0,0 +1,200 @@
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { isBotUsable, loadBot } from "../engine/bot-api.js";
+import { chatDto } from "../engine/rows.js";
+import { deliveryFragments } from "../engine/outbox/enqueue.js";
+import { actorId } from "./bots.js";
+import { PENDING_LINK_PREFIX, PendingLinkState, hashLinkCode, newLinkCode, pendingLinkDto, pendingLinkKey } from "../engine/link-codes.js";
+import { releaseOtherChatsSql, upsertChatSql } from "../engine/dispatch/link-chat.js";
+// src/services/links.ts
+async function create(rt, input) {
+	const bot = await loadBot(rt, input.bot);
+	if (!bot || !isBotUsable(bot)) throw new TelegramPluginError("not_found", "bot not found or not active");
+	const now = rt.clock.now();
+	const code = newLinkCode(rt.rand);
+	const expiresAt = now + rt.limits.linkCodeTtlMs;
+	await rt.db.batch([sql`INSERT INTO tg_link_code (code_hash, tenant, bot_id, purpose, user_id, audience_json, expires_at, created_by, created_at)
+        VALUES (${await hashLinkCode(code)}, ${rt.tenant}, ${bot.id}, ${input.purpose}, ${input.userId},
+                ${input.audience === null ? null : JSON.stringify(input.audience)}, ${expiresAt}, ${input.createdBy}, ${now})`, ...rt.audit({
+		actor: input.createdBy,
+		entity: "telegram_link",
+		entityId: bot.id,
+		action: `create_${input.purpose}`,
+		diff: input.userId ? { userId: input.userId } : {},
+		at: now
+	})]);
+	const param = input.purpose === "group" ? "startgroup" : "start";
+	const url = `https://t.me/${bot.username}?${param}=${code}`;
+	return {
+		url,
+		qrPayload: url,
+		expiresAt,
+		requiresConfirmation: input.purpose === "user" && input.createdBy !== input.userId
+	};
+}
+/**
+* Admin: invite a user, or make a `startgroup` link for a group with an audience. An invite for another user than
+* the caller links only after that user confirms it in the app (`confirmPendingLink`).
+*/
+async function createLink(rt, actor, input) {
+	const by = actorId(rt, actor);
+	if (input.purpose === "user") {
+		if (rt.users) {
+			if (!await rt.users.find(input.userId)) throw new TelegramPluginError("not_found", "user not found");
+		}
+		return create(rt, {
+			bot: input.bot,
+			purpose: "user",
+			userId: input.userId,
+			audience: null,
+			createdBy: by
+		});
+	}
+	if (!by) throw new TelegramPluginError("forbidden", "group links need a signed-in user (they confirm the link in the group)");
+	return create(rt, {
+		bot: input.bot,
+		purpose: "group",
+		userId: null,
+		audience: input.audience,
+		createdBy: by
+	});
+}
+/** Any user links their own Telegram. */
+async function createSelfLink(rt, actor, botId) {
+	const by = actorId(rt, actor);
+	if (!by) throw new TelegramPluginError("forbidden", "only a signed-in user can link their Telegram");
+	return create(rt, {
+		bot: botId,
+		purpose: "user",
+		userId: by,
+		audience: null,
+		createdBy: by
+	});
+}
+function signedIn(rt, actor) {
+	const by = actorId(rt, actor);
+	if (!by) throw new TelegramPluginError("forbidden", "only a signed-in user can confirm a Telegram link");
+	return by;
+}
+function parsePending(value) {
+	try {
+		const r = PendingLinkState.safeParse(JSON.parse(value));
+		return r.success ? r.data : null;
+	} catch {
+		return null;
+	}
+}
+/** Expired pending invites are removed lazily (they hold no chat yet). */
+async function purgeExpired(rt, now) {
+	await rt.db.run(sql`DELETE FROM tg_state WHERE tenant = ${rt.tenant} AND key LIKE ${`${PENDING_LINK_PREFIX}%`}
+        AND json_extract(value, '$.expiresAt') <= ${now}`);
+}
+/** Pending invites waiting for this user's confirmation (`GET /me/links/pending`). */
+async function listPendingLinks(rt, actor) {
+	const userId = signedIn(rt, actor);
+	const now = rt.clock.now();
+	await purgeExpired(rt, now);
+	return (await rt.db.all(sql`SELECT value FROM tg_state WHERE tenant = ${rt.tenant} AND key LIKE ${`${PENDING_LINK_PREFIX}%`}
+        AND json_extract(value, '$.userId') = ${userId} ORDER BY updated_at DESC LIMIT 50`)).flatMap((r) => {
+		const p = parsePending(r.value);
+		return p && p.userId === userId && p.expiresAt > now ? [pendingLinkDto(p)] : [];
+	});
+}
+/** The caller's own pending invite: not_found when missing, link_expired when expired, forbidden for others. */
+async function ownPending(rt, userId, id, now) {
+	const row = await rt.db.first(sql`SELECT value FROM tg_state WHERE tenant = ${rt.tenant} AND key = ${pendingLinkKey(id)}`);
+	const p = row ? parsePending(row.value) : null;
+	if (!p) throw new TelegramPluginError("not_found", "pending link not found");
+	if (p.userId !== userId) throw new TelegramPluginError("forbidden", "this link is for another user");
+	if (p.expiresAt <= now) {
+		await rt.db.run(sql`DELETE FROM tg_state WHERE tenant = ${rt.tenant} AND key = ${pendingLinkKey(id)}`);
+		throw new TelegramPluginError("link_expired", "this link has expired; ask for a new invite");
+	}
+	return p;
+}
+/**
+* The invited user confirms that the Telegram account is theirs (`POST /me/links/pending/:id/confirm`): the chat
+* is linked to them (same rules as `/start <code>`), a "linked" message is queued, `onLinked` runs.
+*/
+async function confirmPendingLink(rt, actor, id) {
+	const userId = signedIn(rt, actor);
+	const now = rt.clock.now();
+	const p = await ownPending(rt, userId, id, now);
+	const bot = await loadBot(rt, p.botId);
+	if (!bot || !isBotUsable(bot)) throw new TelegramPluginError("not_found", "bot not found or not active");
+	const existing = await rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND bot_id = ${bot.id} AND chat_id = ${p.chatId}`);
+	if (existing?.status === "active" && existing.user_id !== null && existing.user_id !== userId) throw new TelegramPluginError("forbidden", "this Telegram account is already linked to someone else");
+	const chatRef = existing?.id ?? p.chatRef;
+	const info = rt.describe(actor);
+	const locale = existing?.locale ?? p.locale ?? bot.default_locale;
+	const linkedText = rt.i18n.t(locale, "bot.start.linked", {
+		name: info.name ?? "",
+		role: info.role ?? ""
+	});
+	await rt.db.batch([
+		sql`DELETE FROM tg_state WHERE tenant = ${rt.tenant} AND key = ${pendingLinkKey(id)}`,
+		...await releaseOtherChatsSql(rt, bot.id, userId, chatRef, now),
+		upsertChatSql(rt, chatRef, {
+			botId: bot.id,
+			chatId: p.chatId,
+			kind: "private",
+			title: p.tgName,
+			username: p.tgUsername,
+			userId,
+			audienceJson: null,
+			locale: p.locale,
+			linkedBy: userId
+		}, now),
+		...rt.audit({
+			actor: userId,
+			entity: "telegram_chat",
+			entityId: chatRef,
+			action: "link",
+			diff: {
+				kind: "private",
+				userId,
+				botId: bot.id,
+				invitedBy: p.createdBy,
+				confirmed: true
+			},
+			at: now
+		}),
+		...deliveryFragments(rt, {
+			botId: bot.id,
+			chatRef,
+			source: "system",
+			kind: "text",
+			html: `${linkedText}\n\n${rt.i18n.t(locale, "bot.link.confirmed_hint")}`,
+			dedupeKey: `link:${id}`
+		}, now)
+	]);
+	const chat = await rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND id = ${chatRef}`);
+	if (!chat) throw new TelegramPluginError("internal_error", "linked chat not found");
+	rt.log.info("tg.linked", {
+		botId: bot.id,
+		chatRef,
+		kind: "private"
+	});
+	await rt.transport.kick([bot.id]);
+	const dto = chatDto(chat);
+	await rt.hook("onLinked", (fn) => fn(dto, actor));
+	return dto;
+}
+/** The invited user declines (`POST /me/links/pending/:id/decline`): the pending invite is removed, nothing links. */
+async function declinePendingLink(rt, actor, id) {
+	const userId = signedIn(rt, actor);
+	const now = rt.clock.now();
+	const p = await ownPending(rt, userId, id, now);
+	await rt.db.batch([sql`DELETE FROM tg_state WHERE tenant = ${rt.tenant} AND key = ${pendingLinkKey(id)}`, ...rt.audit({
+		actor: userId,
+		entity: "telegram_link",
+		entityId: id,
+		action: "decline",
+		diff: {
+			botId: p.botId,
+			invitedBy: p.createdBy
+		},
+		at: now
+	})]);
+}
+export { confirmPendingLink, createLink, createSelfLink, declinePendingLink, listPendingLinks };

package/dist/services/menu.js

@@ -0,0 +1,95 @@
+import { sha256Hex } from "../core/random.js";
+import { sql } from "../ports/sql.js";
+import { settle } from "../telegram/classify.js";
+import { withToken } from "../engine/bot-api.js";
+import { botRuntime } from "../engine/bot-features.js";
+import { commandRows, describe, effectiveCommands } from "./commands.js";
+import { builtinMenu } from "../engine/dispatch/builtins.js";
+// src/services/menu.ts
+/**
+* Commands shown for a chat kind in a locale: built-ins, `/report` (features.reports), then host commands with
+* this bot's `tg_command` config (enabled, show_in_menu, sort, description). Menus are cosmetic: every call is
+* still checked. Telegram allows 100 commands per scope.
+*/
+function menuCommands(rt, _bot, kind, locale, rows = []) {
+	const out = builtinMenu(rt, kind).map((command) => ({
+		command,
+		description: rt.i18n.plain(locale, `bot.cmd.${command}`).slice(0, 256)
+	}));
+	if (!rt.features.commands) return out;
+	if (rt.features.reports) out.push({
+		command: "report",
+		description: rt.i18n.plain(locale, "bot.cmd.report")
+	});
+	for (const c of effectiveCommands(rt, rows)) {
+		if (!c.enabled || !c.showInMenu) continue;
+		if (!c.def.scope.includes(kind === "private" ? "private" : "group")) continue;
+		const description = describe(c.description, locale).trim().slice(0, 256);
+		out.push({
+			command: c.def.command,
+			description: description === "" ? c.def.command : description
+		});
+	}
+	return out.slice(0, 100);
+}
+function buildMenu(base, bot, rows = []) {
+	const rt = botRuntime(base, bot);
+	const fallback = rt.i18n.pick(bot.default_locale);
+	const scopes = [
+		{
+			scope: { type: "default" },
+			kind: "private"
+		},
+		{
+			scope: { type: "all_private_chats" },
+			kind: "private"
+		},
+		{
+			scope: { type: "all_group_chats" },
+			kind: "group"
+		}
+	];
+	const out = [];
+	for (const { scope, kind } of scopes) {
+		out.push({
+			scope,
+			commands: menuCommands(rt, bot, kind, fallback, rows)
+		});
+		for (const language of rt.i18n.locales) out.push({
+			scope,
+			language,
+			commands: menuCommands(rt, bot, kind, language, rows)
+		});
+	}
+	return out;
+}
+/** Sends the menu when its hash changed (or `force`). Failures are logged, never thrown. */
+async function syncCommandMenu(rt, bot, opts = {}) {
+	const menu = buildMenu(rt, bot, botRuntime(rt, bot).features.commands ? await commandRows(rt, bot.id) : []);
+	const hash = await sha256Hex(crypto.subtle, JSON.stringify(menu));
+	if (!opts.force && bot.commands_synced_hash === hash) return {
+		synced: false,
+		calls: 0,
+		failed: 0
+	};
+	let failed = 0;
+	await withToken(rt, bot, async (api) => {
+		for (const entry of menu) if ((await settle(api.setMyCommands({
+			commands: entry.commands,
+			scope: entry.scope,
+			...entry.language ? { language_code: entry.language } : {}
+		}))).outcome.kind !== "ok") failed++;
+	});
+	if (failed === 0) await rt.db.run(sql`UPDATE tg_bot SET commands_synced_hash = ${hash}, updated_at = ${rt.clock.now()}
+          WHERE tenant = ${rt.tenant} AND id = ${bot.id}`);
+	else rt.log.warn("tg.menu_sync_failed", {
+		botId: bot.id,
+		failed
+	});
+	return {
+		synced: failed === 0,
+		calls: menu.length,
+		failed
+	};
+}
+export { buildMenu, menuCommands, syncCommandMenu };

package/dist/services/ops.js

@@ -0,0 +1,90 @@
+import { BotStatus } from "../contracts/bots.js";
+import { sql } from "../ports/sql.js";
+import { STATE_KEYS, ensureState, getState } from "../engine/state.js";
+import { rowsByKid } from "./rekey.js";
+import { STUCK_RUN_MS } from "../engine/schedules/resume.js";
+// src/services/ops.ts
+const TICK_STALE_MS = 3e5;
+async function health(rt) {
+	const now = rt.clock.now();
+	const lastTick = await getState(rt, STATE_KEYS.lastTickAt);
+	const lastTickAt = lastTick === null ? null : Number(lastTick);
+	const q = await rt.db.first(sql`SELECT COUNT(*) AS queued, MIN(created_at) AS oldest FROM tg_delivery
+        WHERE tenant = ${rt.tenant} AND status IN ('queued', 'sending')`);
+	const f = await rt.db.first(sql`SELECT COUNT(*) AS n FROM tg_delivery WHERE tenant = ${rt.tenant} AND status = 'failed'
+        AND updated_at > ${now - 864e5}`);
+	const runs = await rt.db.first(sql`SELECT SUM(CASE WHEN status = 'running' AND started_at < ${now - STUCK_RUN_MS} THEN 1 ELSE 0 END) AS stuck,
+               SUM(CASE WHEN status = 'failed' AND error = 'run_stuck' AND finished_at > ${now - 864e5}
+                        THEN 1 ELSE 0 END) AS failed
+        FROM tg_schedule_run WHERE tenant = ${rt.tenant} AND status IN ('running', 'failed')`);
+	const bots = await rt.db.all(sql`SELECT id, username, status FROM tg_bot WHERE tenant = ${rt.tenant} AND deleted_at IS NULL ORDER BY id`);
+	const botItems = [];
+	for (const b of bots) {
+		const raw = await getState(rt, STATE_KEYS.botHealth(b.id));
+		let pending = null;
+		if (raw) try {
+			pending = JSON.parse(raw).pendingUpdateCount ?? null;
+		} catch {
+			pending = null;
+		}
+		botItems.push({
+			id: b.id,
+			username: b.username,
+			status: BotStatus.safeParse(b.status).data ?? "active",
+			pendingUpdateCount: pending
+		});
+	}
+	const schema = await ensureState(rt);
+	const tickStale = lastTickAt === null || now - lastTickAt > TICK_STALE_MS;
+	return {
+		ok: schema.ok && !tickStale && botItems.every((b) => b.status === "active" || b.status === "disabled"),
+		lastTickAt,
+		tickStale,
+		deliveries: {
+			queued: q?.queued ?? 0,
+			failed24h: f?.n ?? 0,
+			oldestQueuedAgeMs: q?.oldest === null || q?.oldest === void 0 ? null : Math.max(0, now - q.oldest)
+		},
+		schedules: {
+			stuckRuns: runs?.stuck ?? 0,
+			runStuckFailed24h: runs?.failed ?? 0
+		},
+		bots: botItems,
+		keyring: {
+			activeKid: rt.keyring.activeKid(),
+			rowsByKid: await rowsByKid(rt)
+		},
+		schema: {
+			required: schema.required,
+			current: schema.current,
+			ok: schema.ok
+		}
+	};
+}
+/** Counts in [from, to). `rateLimited` counts deliveries whose last error was a 429. */
+async function stats(rt, from, to) {
+	const rows = await rt.db.all(sql`SELECT status, source, error_code, COUNT(*) AS n FROM tg_delivery
+        WHERE tenant = ${rt.tenant} AND created_at >= ${from} AND created_at < ${to}
+        GROUP BY status, source, error_code`);
+	const out = {
+		from,
+		to,
+		sent: 0,
+		failed: 0,
+		dropped: 0,
+		rateLimited: 0,
+		bySource: {},
+		updates: 0
+	};
+	for (const r of rows) {
+		if (r.status === "sent") {
+			out.sent += r.n;
+			out.bySource[r.source] = (out.bySource[r.source] ?? 0) + r.n;
+		} else if (r.status === "failed") out.failed += r.n;
+		else if (r.status === "dropped") out.dropped += r.n;
+		if (r.error_code === "retry_after") out.rateLimited += r.n;
+	}
+	out.updates = (await rt.db.first(sql`SELECT COUNT(*) AS n FROM tg_update WHERE tenant = ${rt.tenant} AND received_at >= ${from} AND received_at < ${to}`))?.n ?? 0;
+	return out;
+}
+export { health, stats };

package/dist/services/rekey.js

@@ -0,0 +1,63 @@
+import { sql } from "../ports/sql.js";
+import { tokenAad, webhookAad } from "../engine/bot-api.js";
+import { STATE_KEYS, setState } from "../engine/state.js";
+// src/services/rekey.ts
+const BATCH = 20;
+async function rekeyBots(rt, opts = {}) {
+	const started = rt.clock.now();
+	const budget = opts.budgetMs ?? rt.limits.tickBudgetMs;
+	const kid = rt.keyring.activeKid();
+	const prefix = `v1.${kid}.`;
+	let rekeyed = 0;
+	let failed = 0;
+	const skip = /* @__PURE__ */ new Set();
+	for (;;) {
+		if (rt.clock.now() - started > budget) break;
+		const todo = (await rt.db.all(sql`SELECT id, token_enc, webhook_secret_enc FROM tg_bot WHERE tenant = ${rt.tenant}
+          AND (substr(token_enc, 1, ${prefix.length}) != ${prefix}
+               OR (webhook_secret_enc IS NOT NULL AND substr(webhook_secret_enc, 1, ${prefix.length}) != ${prefix}))
+          ORDER BY id LIMIT ${BATCH + skip.size}`)).filter((r) => !skip.has(r.id)).slice(0, BATCH);
+		if (todo.length === 0) break;
+		for (const r of todo) try {
+			const token = await rt.keyring.decrypt(r.token_enc, tokenAad(r.id));
+			const secret = r.webhook_secret_enc ? await rt.keyring.decrypt(r.webhook_secret_enc, webhookAad(r.id)) : null;
+			const tokenEnc = await rt.keyring.encrypt(token, tokenAad(r.id));
+			const secretEnc = secret === null ? null : await rt.keyring.encrypt(secret, webhookAad(r.id));
+			if ((await rt.db.run(sql`UPDATE tg_bot SET token_enc = ${tokenEnc}, webhook_secret_enc = ${secretEnc}
+              WHERE id = ${r.id} AND token_enc = ${r.token_enc}
+                AND webhook_secret_enc IS ${r.webhook_secret_enc}`)).changes > 0) rekeyed++;
+		} catch {
+			failed++;
+			skip.add(r.id);
+			rt.log.error("tg.rekey_failed", { botId: r.id });
+		}
+	}
+	const left = await rt.db.first(sql`SELECT COUNT(*) AS n FROM tg_bot WHERE tenant = ${rt.tenant}
+        AND (substr(token_enc, 1, ${prefix.length}) != ${prefix}
+             OR (webhook_secret_enc IS NOT NULL AND substr(webhook_secret_enc, 1, ${prefix.length}) != ${prefix}))`);
+	const now = rt.clock.now();
+	await setState(rt, STATE_KEYS.keyringActiveKid, kid, now);
+	await setState(rt, STATE_KEYS.lastRekeyAt, String(now), now);
+	rt.log.info("tg.rekey", {
+		rekeyed,
+		failed,
+		remaining: left?.n ?? 0
+	});
+	return {
+		rekeyed,
+		failed,
+		remaining: left?.n ?? 0
+	};
+}
+/** Rows per key id (tokens and secrets), for the health page. */
+async function rowsByKid(rt) {
+	const rows = await rt.db.all(sql`SELECT token_enc, webhook_secret_enc FROM tg_bot WHERE tenant = ${rt.tenant}`);
+	const out = {};
+	for (const r of rows) for (const blob of [r.token_enc, r.webhook_secret_enc]) {
+		if (!blob) continue;
+		const kid = rt.keyring.kidOf(blob) ?? "unknown";
+		out[kid] = (out[kid] ?? 0) + 1;
+	}
+	return out;
+}
+export { rekeyBots, rowsByKid };

package/dist/services/reports.js

@@ -0,0 +1,87 @@
+import { TelegramPluginError } from "../engine/errors.js";
+import { renderBody } from "../engine/content/render.js";
+import { hostCan, parseProviderParams, requireProvider, runProvider } from "../engine/content/providers.js";
+import { intersectData } from "../engine/content/intersect.js";
+import { renderReportFile } from "../engine/content/report-files.js";
+// src/services/reports.ts
+/** Provider data as `actor` (permission checked), for a template's provider and params. */
+async function templateData(rt, input) {
+	const t = input.template;
+	if (!t.provider) return {};
+	const def = requireProvider(rt, t.provider);
+	if (!await hostCan(rt, input.actor, def.permission)) throw new TelegramPluginError("provider_forbidden", `this audience may not read "${def.key}"`);
+	const base = {
+		def,
+		params: parseProviderParams(def, {
+			...t.providerParams,
+			...input.params
+		}),
+		now: input.now,
+		tz: input.tz,
+		locale: input.locale,
+		checked: true
+	};
+	if (input.viewer === void 0) return runProvider(rt, {
+		...base,
+		actor: input.actor,
+		cache: input.cache
+	});
+	return viewerData(rt, {
+		...base,
+		actor: input.actor,
+		viewer: input.viewer
+	});
+}
+/**
+* Preview rule (docs/guide 06): the data a caller sees for another audience is the intersection of both views.
+* Throws `provider_forbidden` when the viewer lacks the provider permission. One run when both are the same user.
+*/
+async function viewerData(rt, input) {
+	const { viewer, ...run } = input;
+	if (!await hostCan(rt, viewer, run.def.permission)) throw new TelegramPluginError("provider_forbidden", `you may not read "${run.def.key}"`);
+	const audience = await runProvider(rt, {
+		...run,
+		checked: true
+	});
+	const a = rt.describe(viewer).userId;
+	if (a !== null && a === rt.describe(input.actor).userId) return audience;
+	const mine = await runProvider(rt, {
+		...run,
+		actor: viewer,
+		checked: true
+	});
+	return intersectData(mine, audience) ?? {};
+}
+/**
+* Renders a report template to a file as `actor` (no storage, no Telegram call). Throws `validation_failed` (not a
+* report), `provider_forbidden`, `provider_unknown`, `feature_disabled` (reports off) or `renderer_unavailable`.
+*/
+async function buildReport(rt, input) {
+	const t = input.template;
+	if (t.kind !== "report") throw new TelegramPluginError("validation_failed", `template "${t.key}" is not a report`);
+	const locale = rt.i18n.pick(...input.locales);
+	const vars = await templateData(rt, {
+		...input,
+		locale
+	});
+	const caption = renderBody(rt, {
+		body: t.body,
+		format: t.format,
+		vars,
+		locales: [...input.locales],
+		tz: input.tz
+	});
+	return {
+		file: await renderReportFile(rt, {
+			template: t,
+			vars,
+			locale: caption.locale,
+			tz: input.tz,
+			format: input.format,
+			html: caption.html
+		}),
+		caption,
+		vars
+	};
+}
+export { buildReport, templateData, viewerData };