@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/services/chats.js

@@ -0,0 +1,83 @@
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { chatDto } from "../engine/rows.js";
+import { actorId } from "./bots.js";
+import { cancelQueuedSql } from "../engine/chat-state.js";
+// src/services/chats.ts
+async function listChats(rt, q, page) {
+	const where = [sql`c.tenant = ${rt.tenant}`, sql`b.deleted_at IS NULL`];
+	if (q.bot) where.push(sql`c.bot_id = ${q.bot}`);
+	if (q.kind) where.push(sql`c.kind = ${q.kind}`);
+	if (q.status) where.push(sql`c.status = ${q.status}`);
+	if (q.user) where.push(sql`c.user_id = ${q.user}`);
+	if (page.cursor) where.push(sql`c.id < ${page.cursor}`);
+	return rt.db.all(sql`SELECT c.* FROM tg_chat c JOIN tg_bot b ON b.id = c.bot_id WHERE ${sql.join(where, " AND ")}
+        ORDER BY c.id DESC LIMIT ${page.limit + 1}`);
+}
+async function requireChat(rt, id) {
+	const row = await rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND id = ${id}`);
+	if (!row) throw new TelegramPluginError("chat_not_found", "chat not found");
+	return row;
+}
+async function patchChat(rt, actor, id, patch) {
+	const chat = await requireChat(rt, id);
+	const sets = [];
+	if (patch.audience !== void 0) {
+		if (chat.kind === "private" && patch.audience !== null) throw new TelegramPluginError("validation_failed", "private chats use their linked user", { extensions: { issues: [{
+			path: "audience",
+			message: "only groups have an audience"
+		}] } });
+		sets.push(sql`audience_json = ${patch.audience === null ? null : JSON.stringify(patch.audience)}`);
+	}
+	if (patch.locale !== void 0) sets.push(sql`locale = ${patch.locale === null ? null : rt.i18n.pick(patch.locale)}`);
+	if (patch.timezone !== void 0) sets.push(sql`timezone = ${patch.timezone}`);
+	if (patch.topics !== void 0) sets.push(sql`topics_json = ${JSON.stringify(patch.topics)}`);
+	if (sets.length > 0) {
+		const now = rt.clock.now();
+		await rt.db.batch([sql`UPDATE tg_chat SET ${sql.join(sets)}, updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${id}`, ...rt.audit({
+			actor: actorId(rt, actor),
+			entity: "telegram_chat",
+			entityId: id,
+			action: "update",
+			diff: { fields: Object.keys(patch) },
+			at: now
+		})]);
+	}
+	return chatDto(await requireChat(rt, id));
+}
+/** Unlink: the row stays (pacing, history) as `pending` without user / audience; its queue is cancelled. */
+async function unlinkChat(rt, actor, id) {
+	const chat = await requireChat(rt, id);
+	const now = rt.clock.now();
+	await rt.db.batch([
+		sql`UPDATE tg_chat SET user_id = NULL, audience_json = NULL, status = CASE WHEN status = 'active' THEN 'pending' ELSE status END,
+          updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${id}`,
+		cancelQueuedSql(rt, id, "chat_unlinked", now),
+		...rt.audit({
+			actor: actorId(rt, actor),
+			entity: "telegram_chat",
+			entityId: id,
+			action: "unlink",
+			at: now
+		})
+	]);
+	const dto = chatDto({
+		...chat,
+		user_id: null,
+		audience_json: null,
+		status: "pending",
+		updated_at: now
+	});
+	await rt.hook("onUnlinked", (fn) => fn(dto));
+}
+/** Private chats linked to this user (`/me/chats`). */
+async function myChats(rt, userId) {
+	return rt.db.all(sql`SELECT c.* FROM tg_chat c JOIN tg_bot b ON b.id = c.bot_id
+        WHERE c.tenant = ${rt.tenant} AND c.user_id = ${userId} AND b.deleted_at IS NULL ORDER BY c.id DESC`);
+}
+async function requireOwnChat(rt, userId, id) {
+	const chat = await rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND id = ${id} AND user_id = ${userId}`);
+	if (!chat) throw new TelegramPluginError("chat_not_found", "chat not found");
+	return chat;
+}
+export { listChats, myChats, patchChat, requireChat, requireOwnChat, unlinkChat };

package/dist/services/cleanup.js

@@ -0,0 +1,83 @@
+import { sql } from "../ports/sql.js";
+import { isBotUsable } from "../engine/bot-api.js";
+import { STATE_KEYS, setState } from "../engine/state.js";
+import { syncCommandMenu } from "./menu.js";
+import { testBot } from "./bots.js";
+import { PENDING_LINK_PREFIX, PENDING_LINK_TTL_MS } from "../engine/link-codes.js";
+import { IDEMPOTENCY_PREFIX, IDEMPOTENCY_TTL_MS } from "./idempotency.js";
+// src/services/cleanup.ts
+const DAY = 864e5;
+/** Event throttle rows in `tg_state` (`thr:<rule>:<value>`, see engine/events/tick.ts). */
+const THROTTLE_PREFIX = "thr:";
+/** Longest throttle window a rule may set (contracts/events.ts `perMinutes` ≤ 10 080 = 7 days). */
+const MAX_THROTTLE_MS = 7 * DAY;
+const CHUNK = 500;
+const MAX_PER_TABLE = 2e4;
+/** Deletes in chunks of 500 rows (bounded per run) so one statement never holds D1 for long. */
+async function deleteWhere(rt, table, where) {
+	let total = 0;
+	for (;;) {
+		const r = await rt.db.run(sql`DELETE FROM ${sql.ident(table)} WHERE rowid IN (SELECT rowid FROM ${sql.ident(table)} WHERE ${where} LIMIT ${CHUNK})`);
+		total += r.changes;
+		if (r.changes < CHUNK || total >= MAX_PER_TABLE) return total;
+	}
+}
+async function cleanup(rt) {
+	const now = rt.clock.now();
+	const r = rt.retention;
+	const t = rt.tenant;
+	const deleted = {};
+	const add = (k, n) => {
+		deleted[k] = (deleted[k] ?? 0) + n;
+	};
+	add("delivery", await deleteWhere(rt, "tg_delivery", sql`tenant = ${t} AND status IN ('sent', 'dropped', 'cancelled') AND updated_at < ${now - r.sentDays * DAY}`));
+	add("delivery", await deleteWhere(rt, "tg_delivery", sql`tenant = ${t} AND status = 'failed' AND updated_at < ${now - r.failedDays * DAY}`));
+	add("update", await deleteWhere(rt, "tg_update", sql`tenant = ${t} AND received_at < ${now - r.updateDays * DAY}`));
+	add("event", await deleteWhere(rt, "tg_event", sql`tenant = ${t} AND status IN ('done', 'ignored', 'failed') AND COALESCE(processed_at, occurred_at) < ${now - r.eventDays * DAY}`));
+	add("schedule_run", await deleteWhere(rt, "tg_schedule_run", sql`tenant = ${t} AND started_at < ${now - r.runDays * DAY}`));
+	const expired = now - r.expiredDays * DAY;
+	add("link_code", await deleteWhere(rt, "tg_link_code", sql`tenant = ${t} AND expires_at < ${expired}`));
+	add("action_token", await deleteWhere(rt, "tg_action_token", sql`tenant = ${t} AND expires_at < ${expired}`));
+	add("dialog", await deleteWhere(rt, "tg_dialog", sql`tenant = ${t} AND expires_at < ${expired}`));
+	add("audit", await deleteWhere(rt, "tg_audit", sql`tenant = ${t} AND at < ${now - r.auditDays * DAY}`));
+	add("idempotency", await deleteWhere(rt, "tg_state", sql`tenant = ${t} AND substr(key, 1, ${IDEMPOTENCY_PREFIX.length}) = ${IDEMPOTENCY_PREFIX} AND updated_at < ${now - IDEMPOTENCY_TTL_MS}`));
+	add("pending_link", await deleteWhere(rt, "tg_state", sql`tenant = ${t} AND substr(key, 1, ${PENDING_LINK_PREFIX.length}) = ${PENDING_LINK_PREFIX} AND updated_at < ${now - PENDING_LINK_TTL_MS}`));
+	add("throttle", await deleteWhere(rt, "tg_state", sql`tenant = ${t} AND substr(key, 1, ${4}) = ${THROTTLE_PREFIX}
+            AND updated_at < ${now - Math.max(r.eventDays * DAY, MAX_THROTTLE_MS)}`));
+	let bodiesCleared = 0;
+	for (;;) {
+		const res = await rt.db.run(sql`UPDATE tg_delivery SET body_html = NULL WHERE rowid IN (SELECT rowid FROM tg_delivery
+          WHERE tenant = ${t} AND status IN ('sent', 'dropped', 'cancelled', 'failed') AND body_html IS NOT NULL
+            AND updated_at < ${now - r.bodyDays * DAY} LIMIT ${CHUNK})`);
+		bodiesCleared += res.changes;
+		if (res.changes < CHUNK || bodiesCleared >= MAX_PER_TABLE) break;
+	}
+	let botsChecked = 0;
+	const bots = await rt.db.all(sql`SELECT * FROM tg_bot WHERE tenant = ${t} AND deleted_at IS NULL`);
+	for (const bot of bots) {
+		if (!isBotUsable(bot)) continue;
+		try {
+			await testBot(rt, bot.id);
+			botsChecked++;
+			const fresh = await rt.db.first(sql`SELECT * FROM tg_bot WHERE id = ${bot.id}`);
+			if (fresh && isBotUsable(fresh)) await syncCommandMenu(rt, fresh);
+		} catch (e) {
+			rt.log.warn("tg.cleanup_bot_check_failed", {
+				botId: bot.id,
+				error: e instanceof Error ? e.name : "error"
+			});
+		}
+	}
+	await setState(rt, STATE_KEYS.lastCleanupAt, String(rt.clock.now()), rt.clock.now());
+	rt.log.info("tg.cleanup", {
+		...deleted,
+		bodiesCleared,
+		botsChecked
+	});
+	return {
+		deleted,
+		bodiesCleared,
+		botsChecked
+	};
+}
+export { cleanup };

package/dist/services/commands.js

@@ -0,0 +1,140 @@
+import { LocalizedText } from "../contracts/common.js";
+import { BUILTIN_COMMANDS, CommandName } from "../contracts/commands.js";
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { parseJson } from "../engine/rows.js";
+import { botRuntime } from "../engine/bot-features.js";
+import { RESERVED_COMMANDS } from "../engine/registry.js";
+import { BUILTIN_MENU } from "../engine/dispatch/builtins.js";
+import { actorId } from "./bots.js";
+import { z } from "zod";
+// src/services/commands.ts
+const Names = z.array(CommandName);
+const Roles = z.array(z.string().min(1));
+async function commandRows(rt, botId) {
+	return rt.db.all(sql`SELECT * FROM tg_command WHERE tenant = ${rt.tenant} AND bot_id = ${botId}`);
+}
+/** Registered host commands with this bot's configuration applied, menu-sorted (sort, then name). */
+function effectiveCommands(rt, rows) {
+	const byName = new Map(rows.map((r) => [r.command, r]));
+	return rt.registry.commandList.map((def) => {
+		const row = byName.get(def.command);
+		const rolesOverride = row ? parseJson(row.roles_json, Roles.nullable(), null) : null;
+		return {
+			def,
+			enabled: row ? row.enabled === 1 : true,
+			roles: rolesOverride ?? def.defaultRoles,
+			rolesOverride,
+			aliases: row?.aliases_json ? parseJson(row.aliases_json, Names, [...def.aliases]) : def.aliases,
+			description: row?.description_json ? parseJson(row.description_json, LocalizedText, def.description) : def.description,
+			showInMenu: row ? row.show_in_menu === 1 : def.showInMenu,
+			sort: row ? row.sort : def.sort
+		};
+	}).sort((a, b) => a.sort - b.sort || a.def.command.localeCompare(b.def.command));
+}
+/** Whether a role list (`defaultRoles` / per-bot roles) admits `role`: `"*"` = any role, `[]` = none. */
+function rolesAllow(roles, role) {
+	if (roles.includes("*")) return true;
+	return role !== null && roles.includes(role);
+}
+/** The enabled command for a name or alias. */
+function findCommand(list, name) {
+	return list.find((c) => c.enabled && (c.def.command === name || c.aliases.includes(name))) ?? null;
+}
+function describe(description, locale) {
+	return description[locale] ?? description[locale.split("-")[0] ?? ""] ?? Object.values(description)[0] ?? "";
+}
+function builtinDto(rt, command) {
+	const groups = BUILTIN_MENU.group.includes(command) || command === "report";
+	return {
+		command,
+		builtin: true,
+		enabled: rt.features.commands || command === "start" || command === "help",
+		roles: null,
+		defaultRoles: ["*"],
+		aliases: [],
+		description: Object.fromEntries(rt.i18n.locales.map((l) => [l, rt.i18n.plain(l, `bot.cmd.${command}`)])),
+		showInMenu: true,
+		sort: 0,
+		scope: groups ? [
+			"private",
+			"group",
+			"supergroup"
+		] : ["private"],
+		permission: null
+	};
+}
+function hostDto(c) {
+	return {
+		command: c.def.command,
+		builtin: false,
+		enabled: c.enabled,
+		roles: c.rolesOverride,
+		defaultRoles: [...c.def.defaultRoles],
+		aliases: [...c.aliases],
+		description: { ...c.description },
+		showInMenu: c.showInMenu,
+		sort: c.sort,
+		scope: [...c.def.scope],
+		permission: c.def.permission
+	};
+}
+/** Built-ins (incl. `/report` with features.reports) and host commands for one bot. */
+async function listCommandConfigs(base, bot) {
+	const rt = botRuntime(base, bot);
+	return [...[...BUILTIN_COMMANDS, ...rt.features.reports ? ["report"] : []].map((c) => builtinDto(rt, c)), ...effectiveCommands(rt, await commandRows(rt, bot.id)).map(hostDto)];
+}
+function issue(path, message) {
+	return new TelegramPluginError("validation_failed", message, { extensions: { issues: [{
+		path,
+		message
+	}] } });
+}
+/** Upserts a host command's per-bot config (fields not given keep their current value). */
+async function saveCommandConfig(rt, actor, bot, command, save) {
+	if (RESERVED_COMMANDS.includes(command) || BUILTIN_COMMANDS.includes(command)) throw issue("command", "built-in commands cannot be configured per bot");
+	if (!rt.registry.commandList.find((c) => c.command === command)) throw new TelegramPluginError("not_found", `command /${command} is not registered`);
+	const rows = await commandRows(rt, bot.id);
+	const current = effectiveCommands(rt, rows).find((c) => c.def.command === command);
+	if (save.aliases) {
+		const taken = /* @__PURE__ */ new Set();
+		for (const c of effectiveCommands(rt, rows)) {
+			if (c.def.command === command) continue;
+			taken.add(c.def.command);
+			for (const a of c.aliases) taken.add(a);
+		}
+		for (const a of save.aliases) if (a === command || RESERVED_COMMANDS.includes(a) || a === "report" || taken.has(a)) throw issue("body.aliases", `alias "${a}" is taken`);
+	}
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	const next = {
+		enabled: save.enabled ?? current.enabled,
+		roles: save.roles !== void 0 ? save.roles : current.rolesOverride,
+		aliases: save.aliases ?? [...current.aliases],
+		description: save.description !== void 0 ? save.description : parseJson(rows.find((r) => r.command === command)?.description_json, LocalizedText.nullable(), null),
+		showInMenu: save.showInMenu ?? current.showInMenu,
+		sort: save.sort ?? current.sort
+	};
+	const json = (v) => v === null || v === void 0 ? null : JSON.stringify(v);
+	await rt.db.batch([sql`INSERT INTO tg_command (tenant, bot_id, command, enabled, roles_json, aliases_json, description_json, show_in_menu,
+          sort, updated_by, updated_at)
+        VALUES (${rt.tenant}, ${bot.id}, ${command}, ${next.enabled}, ${json(next.roles)}, ${json(next.aliases)},
+          ${json(next.description)}, ${next.showInMenu}, ${next.sort}, ${by}, ${now})
+        ON CONFLICT (tenant, bot_id, command) DO UPDATE SET enabled = excluded.enabled, roles_json = excluded.roles_json,
+          aliases_json = excluded.aliases_json, description_json = excluded.description_json,
+          show_in_menu = excluded.show_in_menu, sort = excluded.sort, updated_by = excluded.updated_by,
+          updated_at = excluded.updated_at`, ...rt.audit({
+		actor: by,
+		entity: "telegram_command",
+		entityId: `${bot.id}:${command}`,
+		action: "update",
+		diff: {
+			enabled: next.enabled,
+			roles: next.roles,
+			aliases: next.aliases
+		},
+		at: now
+	})]);
+	return hostDto(effectiveCommands(rt, await commandRows(rt, bot.id)).find((c) => c.def.command === command));
+}
+export { commandRows, describe, effectiveCommands, findCommand, listCommandConfigs, rolesAllow, saveCommandConfig };

package/dist/services/deliveries.js

@@ -0,0 +1,53 @@
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { actorId } from "./bots.js";
+// src/services/deliveries.ts
+async function listDeliveries(rt, q, page) {
+	const where = [sql`tenant = ${rt.tenant}`];
+	if (q.status) where.push(sql`status = ${q.status}`);
+	if (q.source) where.push(sql`source = ${q.source}`);
+	if (q.bot) where.push(sql`bot_id = ${q.bot}`);
+	if (page.cursor) where.push(sql`id < ${page.cursor}`);
+	return rt.db.all(sql`SELECT * FROM tg_delivery WHERE ${sql.join(where, " AND ")} ORDER BY id DESC LIMIT ${page.limit + 1}`);
+}
+async function requireDelivery(rt, id) {
+	const row = await rt.db.first(sql`SELECT * FROM tg_delivery WHERE tenant = ${rt.tenant} AND id = ${id}`);
+	if (!row) throw new TelegramPluginError("not_found", "delivery not found");
+	return row;
+}
+async function retryDelivery(rt, actor, id) {
+	const row = await requireDelivery(rt, id);
+	if (![
+		"failed",
+		"dropped",
+		"cancelled"
+	].includes(row.status)) throw new TelegramPluginError("delivery_not_retryable", `a ${row.status} delivery cannot be retried`);
+	const now = rt.clock.now();
+	if (((await rt.db.batch([sql`UPDATE tg_delivery SET status = 'queued', attempts = 0, next_attempt_at = ${now}, error_code = NULL,
+          error_detail = NULL, lease_until = NULL, lease_token = NULL, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id} AND status = ${row.status}`, ...rt.audit({
+		actor: actorId(rt, actor),
+		entity: "telegram_delivery",
+		entityId: id,
+		action: "retry",
+		at: now
+	})]))[0]?.changes ?? 0) === 0) throw new TelegramPluginError("delivery_not_retryable", "the delivery changed meanwhile");
+	rt.waitUntil(rt.transport.kick([row.bot_id]));
+	return requireDelivery(rt, id);
+}
+async function cancelDelivery(rt, actor, id) {
+	const row = await requireDelivery(rt, id);
+	const now = rt.clock.now();
+	if (!(row.status === "queued" || row.status === "sending" && (row.lease_until ?? 0) < now)) throw new TelegramPluginError("delivery_not_retryable", `a ${row.status} delivery cannot be cancelled`);
+	if (((await rt.db.batch([sql`UPDATE tg_delivery SET status = 'cancelled', error_code = 'cancelled_by_admin', updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id}
+          AND (status = 'queued' OR (status = 'sending' AND lease_until < ${now}))`, ...rt.audit({
+		actor: actorId(rt, actor),
+		entity: "telegram_delivery",
+		entityId: id,
+		action: "cancel",
+		at: now
+	})]))[0]?.changes ?? 0) === 0) throw new TelegramPluginError("delivery_not_retryable", `a ${row.status} delivery cannot be cancelled`);
+	return requireDelivery(rt, id);
+}
+export { cancelDelivery, listDeliveries, requireDelivery, retryDelivery };

package/dist/services/destinations.js

@@ -0,0 +1,91 @@
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { destinationDto } from "../engine/rows.js";
+import { actorId } from "./bots.js";
+import { requireChat } from "./chats.js";
+// src/services/destinations.ts
+async function listDestinations(rt, page) {
+	return rt.db.all(sql`SELECT * FROM tg_destination WHERE tenant = ${rt.tenant} AND deleted_at IS NULL
+        ${page.cursor ? sql`AND id < ${page.cursor}` : sql.empty} ORDER BY id DESC LIMIT ${page.limit + 1}`);
+}
+async function requireDestination(rt, id) {
+	const row = await rt.db.first(sql`SELECT * FROM tg_destination WHERE tenant = ${rt.tenant} AND id = ${id} AND deleted_at IS NULL`);
+	if (!row) throw new TelegramPluginError("not_found", "destination not found");
+	return row;
+}
+async function destinationBySlug(rt, slug) {
+	return rt.db.first(sql`SELECT * FROM tg_destination WHERE tenant = ${rt.tenant} AND slug = ${slug} AND deleted_at IS NULL`);
+}
+async function checkSlugFree(rt, slug, exceptId) {
+	const taken = await rt.db.first(sql`SELECT id, deleted_at FROM tg_destination WHERE tenant = ${rt.tenant} AND slug = ${slug}`);
+	if (taken && taken.id !== exceptId && taken.deleted_at === null) throw new TelegramPluginError("validation_failed", "slug is taken", { extensions: { issues: [{
+		path: "slug",
+		message: "already used by another destination"
+	}] } });
+	return taken;
+}
+async function createDestination(rt, actor, input) {
+	const chat = await requireChat(rt, input.chatRef);
+	const taken = await checkSlugFree(rt, input.slug);
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	const free = taken ? [sql`UPDATE tg_destination SET slug = ${`${input.slug}~${taken.id}`.slice(0, 64)} WHERE id = ${taken.id}`] : [];
+	const id = rt.ids.uuid();
+	await rt.db.batch([
+		...free,
+		sql`INSERT INTO tg_destination (id, tenant, name, slug, bot_id, chat_ref, message_thread_id, ai_allowed, created_by,
+          created_at, updated_at)
+        VALUES (${id}, ${rt.tenant}, ${input.name}, ${input.slug}, ${chat.bot_id}, ${chat.id}, ${input.messageThreadId},
+          ${input.aiAllowed}, ${by}, ${now}, ${now})`,
+		...rt.audit({
+			actor: by,
+			entity: "telegram_destination",
+			entityId: id,
+			action: "create",
+			diff: {
+				slug: input.slug,
+				aiAllowed: input.aiAllowed
+			},
+			at: now
+		})
+	]);
+	return destinationDto(await requireDestination(rt, id));
+}
+async function updateDestination(rt, actor, id, input) {
+	await requireDestination(rt, id);
+	const chat = await requireChat(rt, input.chatRef);
+	const taken = await checkSlugFree(rt, input.slug, id);
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	const free = taken && taken.id !== id ? [sql`UPDATE tg_destination SET slug = ${`${input.slug}~${taken.id}`.slice(0, 64)} WHERE id = ${taken.id}`] : [];
+	await rt.db.batch([
+		...free,
+		sql`UPDATE tg_destination SET name = ${input.name}, slug = ${input.slug}, bot_id = ${chat.bot_id}, chat_ref = ${chat.id},
+          message_thread_id = ${input.messageThreadId}, ai_allowed = ${input.aiAllowed}, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id}`,
+		...rt.audit({
+			actor: by,
+			entity: "telegram_destination",
+			entityId: id,
+			action: "update",
+			diff: {
+				slug: input.slug,
+				aiAllowed: input.aiAllowed
+			},
+			at: now
+		})
+	]);
+	return destinationDto(await requireDestination(rt, id));
+}
+async function deleteDestination(rt, actor, id) {
+	await requireDestination(rt, id);
+	const now = rt.clock.now();
+	await rt.db.batch([sql`UPDATE tg_destination SET deleted_at = ${now}, updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${id}`, ...rt.audit({
+		actor: actorId(rt, actor),
+		entity: "telegram_destination",
+		entityId: id,
+		action: "delete",
+		at: now
+	})]);
+}
+export { createDestination, deleteDestination, destinationBySlug, listDestinations, requireDestination, updateDestination };

package/dist/services/event-rules.js

@@ -0,0 +1,229 @@
+import { Recipients } from "../contracts/recipients.js";
+import { EventFilter, Throttle } from "../contracts/events.js";
+import { zodToShape } from "../core/template/shape.js";
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { renderBody } from "../engine/content/render.js";
+import { hostCan, parseProviderParams, requireProvider, runProvider } from "../engine/content/providers.js";
+import { parseJson } from "../engine/rows.js";
+import { templateById, templateModel } from "../engine/content/template-rows.js";
+import { jsonSchemaOf } from "../engine/registry.js";
+import { actorId } from "./bots.js";
+import { checkFilter, matchFilters } from "../engine/events/filters.js";
+import { payloadVarsFor } from "../engine/events/payload.js";
+import { fanOut } from "../engine/content/fanout.js";
+import { resolveChats } from "../engine/content/recipients.js";
+// src/services/event-rules.ts
+function eventRuleModel(r) {
+	return {
+		id: r.id,
+		event: r.event,
+		name: r.name,
+		filters: parseJson(r.filter_json, EventFilter.array(), []),
+		templateId: r.template_id,
+		recipients: parseJson(r.recipients_json, Recipients, []),
+		throttle: parseJson(r.throttle_json, Throttle.nullable(), null),
+		enabled: r.enabled === 1
+	};
+}
+function eventRuleDto(r) {
+	return {
+		...eventRuleModel(r),
+		createdBy: r.created_by,
+		updatedAt: r.updated_at
+	};
+}
+/** The host's registered events as DTOs (payload JSON Schema, filterable / sensitive fields) for admin UIs. */
+function registeredEvents(rt) {
+	return [...rt.registry.events.values()].map((e) => ({
+		key: e.key,
+		label: e.label,
+		filterable: [...e.filterable],
+		sensitive: [...e.sensitive],
+		provider: e.provider,
+		payloadSchema: jsonSchemaOf(e.payload)
+	}));
+}
+function issue(path, message) {
+	return new TelegramPluginError("validation_failed", message, { extensions: { issues: [{
+		path,
+		message
+	}] } });
+}
+function requireEvent(rt, key, path = "body.event") {
+	const def = rt.registry.events.get(key);
+	if (!def) throw issue(path, `event "${key}" is not registered`);
+	return def;
+}
+/** Save-time checks: event registered, filters on `filterable` fields with fitting values, template, throttle key. */
+async function validateRuleSave(rt, save) {
+	const def = requireEvent(rt, save.event);
+	const shape = zodToShape(def.payload);
+	for (const [i, f] of save.filters.entries()) {
+		const err = checkFilter(f, def.filterable, shape);
+		if (err) throw issue(`body.filters.${i}`, err);
+	}
+	if (save.throttle?.key !== void 0 && shape.kind === "object" && !Object.hasOwn(shape.fields, save.throttle.key)) throw issue("body.throttle.key", `"${save.throttle.key}" is not a payload field of "${def.key}"`);
+	if (!await templateById(rt, save.templateId)) throw issue("body.templateId", "template not found");
+}
+async function listRules(rt, q, page) {
+	return rt.db.all(sql`SELECT * FROM tg_event_rule WHERE tenant = ${rt.tenant} AND deleted_at IS NULL
+        ${q.event ? sql`AND event = ${q.event}` : sql.empty}
+        ${page.cursor ? sql`AND id < ${page.cursor}` : sql.empty} ORDER BY id DESC LIMIT ${page.limit + 1}`);
+}
+async function requireRule(rt, id) {
+	const row = await rt.db.first(sql`SELECT * FROM tg_event_rule WHERE tenant = ${rt.tenant} AND id = ${id} AND deleted_at IS NULL`);
+	if (!row) throw new TelegramPluginError("not_found", "event rule not found");
+	return row;
+}
+const throttleJson = (t) => t ? JSON.stringify(t) : null;
+async function createRule(rt, actor, save) {
+	await validateRuleSave(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_event_rule (id, tenant, event, name, filter_json, template_id, recipients_json, throttle_json,
+          enabled, created_by, created_at, updated_at)
+        VALUES (${id}, ${rt.tenant}, ${save.event}, ${save.name}, ${JSON.stringify(save.filters)}, ${save.templateId},
+          ${JSON.stringify(save.recipients)}, ${throttleJson(save.throttle)}, ${save.enabled}, ${by}, ${now}, ${now})`, ...rt.audit({
+		actor: by,
+		entity: "telegram_event_rule",
+		entityId: id,
+		action: "create",
+		diff: { event: save.event },
+		at: now
+	})]);
+	return eventRuleDto(await requireRule(rt, id));
+}
+async function updateRule(rt, actor, id, save) {
+	await requireRule(rt, id);
+	await validateRuleSave(rt, save);
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	await rt.db.batch([sql`UPDATE tg_event_rule SET event = ${save.event}, name = ${save.name}, filter_json = ${JSON.stringify(save.filters)},
+          template_id = ${save.templateId}, recipients_json = ${JSON.stringify(save.recipients)},
+          throttle_json = ${throttleJson(save.throttle)}, enabled = ${save.enabled}, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id} AND deleted_at IS NULL`, ...rt.audit({
+		actor: by,
+		entity: "telegram_event_rule",
+		entityId: id,
+		action: "update",
+		diff: {
+			event: save.event,
+			enabled: save.enabled
+		},
+		at: now
+	})]);
+	return eventRuleDto(await requireRule(rt, id));
+}
+async function deleteRule(rt, actor, id) {
+	const old = await requireRule(rt, id);
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	await rt.db.batch([sql`UPDATE tg_event_rule SET deleted_at = ${now}, updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${id}`, ...rt.audit({
+		actor: by,
+		entity: "telegram_event_rule",
+		entityId: id,
+		action: "delete",
+		diff: { event: old.event },
+		at: now
+	})]);
+}
+/** Parses an event payload with its schema; `validation_failed` with the issues (under `prefix`) otherwise. */
+function parsePayload(def, payload, prefix = "body.payload") {
+	const r = def.payload.safeParse(payload);
+	if (r.success) return r.data;
+	throw new TelegramPluginError("validation_failed", `payload of "${def.key}" is not valid`, { extensions: { issues: r.error.issues.slice(0, 20).map((i) => ({
+		path: [prefix, ...i.path.map(String)].join("."),
+		message: i.message
+	})) } });
+}
+/**
+* Renders `payload` with the rule's template as the caller and queues it to the caller's own linked private chats
+* (filters and throttle are reported, not applied; subscriptions are ignored). Nothing else is sent.
+*/
+async function testRule(rt, actor, id, payload) {
+	const rule = eventRuleModel(await requireRule(rt, id));
+	const def = rt.registry.events.get(rule.event);
+	if (!def) throw new TelegramPluginError("validation_failed", `event "${rule.event}" is no longer registered`);
+	const data = parsePayload(def, payload);
+	const tplRow = await templateById(rt, rule.templateId);
+	if (!tplRow) throw new TelegramPluginError("not_found", "the rule's template is gone");
+	const template = templateModel(tplRow);
+	const info = rt.describe(actor);
+	if (!info.userId) throw new TelegramPluginError("recipient_empty", "the caller has no user id");
+	const now = rt.clock.now();
+	const chats = await resolveChats(rt, [{ user: info.userId }], now);
+	if (chats.length === 0) throw new TelegramPluginError("recipient_empty", "you have no linked Telegram chat");
+	const tz = rt.settings.timezone;
+	const locale = rt.i18n.pick(info.locale);
+	let vars = {};
+	const providerKey = def.provider ?? template.provider;
+	if (providerKey) {
+		const p = requireProvider(rt, providerKey);
+		if (!await hostCan(rt, actor, p.permission)) throw new TelegramPluginError("provider_forbidden", `you may not read "${p.key}"`);
+		const params = parseProviderParams(p, def.provider ? data : { ...template.providerParams });
+		vars = await runProvider(rt, {
+			def: p,
+			actor,
+			params,
+			now,
+			tz,
+			locale,
+			checked: true
+		});
+	}
+	vars = {
+		...await payloadVarsFor(rt, def, data, actor),
+		...vars
+	};
+	const body = renderBody(rt, {
+		body: template.body,
+		format: template.format,
+		vars,
+		locales: [locale],
+		tz
+	});
+	const nonce = rt.ids.uuid();
+	const result = await fanOut(rt, {
+		template,
+		provider: eventProvider(def, template, data),
+		recipients: {
+			send: chats,
+			held: [],
+			muted: []
+		},
+		personalize: true,
+		source: "event",
+		sourceId: `test:${nonce}`,
+		dedupeKey: (chat) => `evtest:${nonce}:${chat.chatRef}`,
+		now,
+		tz,
+		vars: (aud) => payloadVarsFor(rt, def, data, aud.actor),
+		meta: {
+			event: def.key,
+			rule: rule.id,
+			test: true
+		}
+	});
+	if (result.deliveries > 0) rt.waitUntil(rt.transport.kick([...new Set(chats.map((c) => c.botId))]));
+	return {
+		filtersMatch: matchFilters(rule.filters, data),
+		chats: result.chats,
+		deliveries: result.deliveries,
+		parts: body.parts,
+		warnings: body.warnings
+	};
+}
+/**
+* Which provider an event fan-out runs: the event's own provider with the payload as params (data re-read as each
+* audience); else the template's provider with its saved params; else none (payload variables only).
+*/
+function eventProvider(def, template, payload) {
+	if (def.provider) return {
+		key: def.provider,
+		params: payload
+	};
+	return template.provider ? void 0 : null;
+}
+export { createRule, deleteRule, eventProvider, eventRuleDto, eventRuleModel, listRules, parsePayload, registeredEvents, requireRule, testRule, updateRule, validateRuleSave };