@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/services/schedules.js

@@ -0,0 +1,214 @@
+import { ScheduleError, nextRun, nextRuns, validateRule } from "../core/schedule/rule.js";
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { parseProviderParams, requireProvider } from "../engine/content/providers.js";
+import { templateById } from "../engine/content/template-rows.js";
+import { actorId } from "./bots.js";
+import { requireSchedule, scheduleDto, scheduleRule, scheduleRunDto } from "../engine/schedules/rows.js";
+import { runManual } from "../engine/schedules/fire.js";
+import { armScheduleWake } from "../engine/schedules/wake.js";
+// src/services/schedules.ts
+const ENTITY = "telegram_schedule";
+function issue(path, message) {
+	return new TelegramPluginError("validation_failed", message, { extensions: { issues: [{
+		path,
+		message
+	}] } });
+}
+function scheduleProblem(e) {
+	if (e instanceof ScheduleError) throw new TelegramPluginError(e.code, e.message);
+	throw e;
+}
+const sameRule = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+* Validates a save and returns the zone and the first slot. A `once` rule in the past is rejected unless it is the
+* rule already stored (editing a schedule that already ran), which keeps `next_run_at` null.
+*/
+async function checkSave(rt, save, now, existing) {
+	const tz = save.timezone ?? rt.settings.timezone;
+	const check = validateRule(save.rule, tz);
+	if (!check.ok) throw new TelegramPluginError(check.code, check.message);
+	let next;
+	try {
+		next = nextRun(check.rule, tz, now);
+	} catch (e) {
+		scheduleProblem(e);
+	}
+	if (next === null) {
+		const unchanged = existing !== null && sameRule(scheduleRule(existing), check.rule) && existing.timezone === tz;
+		if (check.rule.kind !== "once") throw new TelegramPluginError("schedule_rule_invalid", "the rule never runs");
+		if (!unchanged) throw new TelegramPluginError("schedule_rule_invalid", "the time is in the past");
+	}
+	if (save.recipients.length === 0) throw new TelegramPluginError("recipient_empty", "pick at least one recipient");
+	const template = await templateById(rt, save.templateId);
+	if (!template) throw issue("body.templateId", "template not found");
+	if (template.provider) {
+		const def = requireProvider(rt, template.provider);
+		let base = {};
+		try {
+			base = template.provider_params_json ? JSON.parse(template.provider_params_json) : {};
+		} catch {
+			base = {};
+		}
+		parseProviderParams(def, {
+			...base,
+			...save.params
+		});
+	}
+	return {
+		tz,
+		next
+	};
+}
+const json = (v) => v === null || v === void 0 ? null : JSON.stringify(v);
+async function listSchedules(rt, page) {
+	return rt.db.all(sql`SELECT * FROM tg_schedule 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 getSchedule(rt, id) {
+	return scheduleDto(await requireSchedule(rt, id));
+}
+/**
+* Creates a schedule (row + audit in one batch) and re-arms the DO scheduler wake if used. Throws
+* `schedule_rule_invalid`, `timezone_invalid`, `recipient_empty` or `validation_failed` (unknown template). No
+* permission check: the routes require `telegram.schedules.manage`.
+*/
+async function createSchedule(rt, actor, save) {
+	const now = rt.clock.now();
+	const { tz, next } = await checkSave(rt, save, now, null);
+	const by = actorId(rt, actor);
+	const id = rt.ids.uuid();
+	await rt.db.batch([sql`INSERT INTO tg_schedule (id, tenant, name, rule_json, timezone, template_id, params_json, recipients_json,
+          personalize, missed_policy, missed_grace_min, enabled, next_run_at, created_by, created_at, updated_at)
+        VALUES (${id}, ${rt.tenant}, ${save.name}, ${JSON.stringify(save.rule)}, ${tz}, ${save.templateId},
+          ${json(save.params)}, ${JSON.stringify(save.recipients)}, ${save.personalize}, ${save.missedPolicy},
+          ${save.missedGraceMin}, ${save.enabled}, ${next}, ${by}, ${now}, ${now})`, ...rt.audit({
+		actor: by,
+		entity: ENTITY,
+		entityId: id,
+		action: "create",
+		diff: { name: save.name },
+		at: now
+	})]);
+	await armScheduleWake(rt);
+	return getSchedule(rt, id);
+}
+/** Replaces a schedule. `next_run_at` is recomputed from now (or from the end of a timed pause). */
+async function updateSchedule(rt, actor, id, save) {
+	const old = await requireSchedule(rt, id);
+	const now = rt.clock.now();
+	const { tz } = await checkSave(rt, save, now, old);
+	const rule = validateRule(save.rule, tz);
+	const from = old.paused_until !== null && old.paused_until > now ? old.paused_until - 1 : now;
+	const next = rule.ok && old.paused_until !== 0xe677d21fdbff ? nextRun(rule.rule, tz, from) : old.next_run_at;
+	const by = actorId(rt, actor);
+	await rt.db.batch([sql`UPDATE tg_schedule SET name = ${save.name}, rule_json = ${JSON.stringify(save.rule)}, timezone = ${tz},
+          template_id = ${save.templateId}, params_json = ${json(save.params)},
+          recipients_json = ${JSON.stringify(save.recipients)}, personalize = ${save.personalize},
+          missed_policy = ${save.missedPolicy}, missed_grace_min = ${save.missedGraceMin}, enabled = ${save.enabled},
+          next_run_at = ${next}, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id} AND deleted_at IS NULL`, ...rt.audit({
+		actor: by,
+		entity: ENTITY,
+		entityId: id,
+		action: "update",
+		diff: { name: save.name },
+		at: now
+	})]);
+	await armScheduleWake(rt);
+	return getSchedule(rt, id);
+}
+async function deleteSchedule(rt, actor, id) {
+	const old = await requireSchedule(rt, id);
+	const now = rt.clock.now();
+	const by = actorId(rt, actor);
+	await rt.db.batch([sql`UPDATE tg_schedule SET deleted_at = ${now}, updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${id}`, ...rt.audit({
+		actor: by,
+		entity: ENTITY,
+		entityId: id,
+		action: "delete",
+		diff: { name: old.name },
+		at: now
+	})]);
+	await armScheduleWake(rt);
+}
+/**
+* Pauses until `until`, or until resumed. A timed pause moves `next_run_at` to the first slot at or after `until`,
+* so slots inside the pause are not caught up.
+*/
+async function pauseSchedule(rt, actor, id, body) {
+	const old = await requireSchedule(rt, id);
+	const now = rt.clock.now();
+	if (body.until !== void 0 && body.until <= now) throw issue("body.until", "until must be in the future");
+	const until = body.until ?? 0xe677d21fdbff;
+	let next = old.next_run_at;
+	if (body.until !== void 0) try {
+		next = nextRun(scheduleRule(old), old.timezone, until - 1);
+	} catch (e) {
+		scheduleProblem(e);
+	}
+	const by = actorId(rt, actor);
+	await rt.db.batch([sql`UPDATE tg_schedule SET paused_until = ${until}, next_run_at = ${next}, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id} AND deleted_at IS NULL`, ...rt.audit({
+		actor: by,
+		entity: ENTITY,
+		entityId: id,
+		action: "pause",
+		diff: { until },
+		at: now
+	})]);
+	await armScheduleWake(rt);
+	return getSchedule(rt, id);
+}
+/** Resumes from now: slots missed while paused are not replayed. */
+async function resumeSchedule(rt, actor, id) {
+	const old = await requireSchedule(rt, id);
+	const now = rt.clock.now();
+	let next;
+	try {
+		next = nextRun(scheduleRule(old), old.timezone, now);
+	} catch (e) {
+		scheduleProblem(e);
+	}
+	const by = actorId(rt, actor);
+	await rt.db.batch([sql`UPDATE tg_schedule SET paused_until = NULL, next_run_at = ${next}, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${id} AND deleted_at IS NULL`, ...rt.audit({
+		actor: by,
+		entity: ENTITY,
+		entityId: id,
+		action: "resume",
+		at: now
+	})]);
+	await armScheduleWake(rt);
+	return getSchedule(rt, id);
+}
+/** Runs the schedule now (a `manual` run). Works on paused or disabled schedules; `next_run_at` is unchanged. */
+async function runScheduleNow(rt, actor, id) {
+	const schedule = await requireSchedule(rt, id);
+	const run = await runManual(rt, schedule);
+	const by = actorId(rt, actor);
+	const audit = rt.audit({
+		actor: by,
+		entity: ENTITY,
+		entityId: id,
+		action: "run_now",
+		diff: { run: run.id },
+		at: run.started_at
+	});
+	if (audit.length > 0) await rt.db.batch(audit);
+	return scheduleRunDto(run);
+}
+async function listRuns(rt, id, page) {
+	await requireSchedule(rt, id);
+	return rt.db.all(sql`SELECT * FROM tg_schedule_run WHERE tenant = ${rt.tenant} AND schedule_id = ${id}
+        ${page.cursor ? sql`AND id < ${page.cursor}` : sql.empty} ORDER BY id DESC LIMIT ${page.limit + 1}`);
+}
+/** Next-runs preview for an editor (strictly after `from`, default now). */
+function previewNextRuns(rt, req) {
+	try {
+		return { runs: nextRuns(req.rule, req.tz, req.from ?? rt.clock.now(), req.count) };
+	} catch (e) {
+		scheduleProblem(e);
+	}
+}
+export { createSchedule, deleteSchedule, getSchedule, listRuns, listSchedules, pauseSchedule, previewNextRuns, resumeSchedule, runScheduleNow, updateSchedule };

package/dist/services/send.d.ts

@@ -0,0 +1,14 @@
+import { DeliverySource } from "../contracts/deliveries.js";
+import { intersectData } from "../engine/content/intersect.js";
+/** Options of `enqueueIntent` / `plugin.enqueue()`. */
+export interface EnqueueOptions {
+  /** Stable key for this send (for example `ai:<nonce>`); retries of the host batch never duplicate messages. */
+  dedupeKey: string;
+  /** Default `api`. `ai` adds the AI rules: ai_allowed destinations and the text checks (docs/07 §2). */
+  source?: DeliverySource;
+  /** Domains allowed in AI text links. */
+  appDomains?: string[];
+}
+/** Provider key convention for `record` sends (docs/04 §9). */
+export declare const recordProviderKey: (type: string) => string;
+export { intersectData };

package/dist/services/send.js

@@ -0,0 +1,421 @@
+import { Audience } from "../contracts/chats.js";
+import { checkAiText } from "../core/guards.js";
+import { escapeHtml } from "../core/html/escape.js";
+import { splitMessage } from "../core/split/split.js";
+import { sql } from "../ports/sql.js";
+import { TelegramPluginError, featureDisabled } 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 { buildButtons, orphanTokenGuard } from "../engine/content/buttons.js";
+import { intersectData } from "../engine/content/intersect.js";
+import { fileUrl, storeReportFile } from "../engine/content/report-files.js";
+import { buildReport, templateData } from "./reports.js";
+import { audienceOf } from "../engine/content/audience.js";
+import { requireTemplateByKey, templateByKey, templateModel } from "../engine/content/template-rows.js";
+import { deliveryFragments } from "../engine/outbox/enqueue.js";
+import { destinationBySlug } from "./destinations.js";
+// src/services/send.ts
+/** The literal file source name for the host files port. */
+const FILES_PORT_SOURCE = "files";
+/** Provider key convention for `record` sends (docs/04 §9). */
+const recordProviderKey = (type) => `record:${type}`;
+async function activeChat(rt, id) {
+	return rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND id = ${id}`);
+}
+async function botOf(rt, id) {
+	const bot = await rt.db.first(sql`SELECT * FROM tg_bot WHERE tenant = ${rt.tenant} AND id = ${id} AND deleted_at IS NULL`);
+	if (!bot) throw new TelegramPluginError("chat_not_found", "the chat's bot is gone");
+	return bot;
+}
+async function resolveTargets(rt, actor, intent, ai) {
+	const to = intent.to;
+	if ("destination" in to) {
+		const dest = await destinationBySlug(rt, to.destination);
+		if (!dest) throw new TelegramPluginError("not_found", "destination not found");
+		if (ai && dest.ai_allowed !== 1) throw new TelegramPluginError("destination_not_allowed", "the AI may not send here");
+		const chat = await activeChat(rt, dest.chat_ref);
+		if (!chat) throw new TelegramPluginError("chat_not_found", "destination chat not found");
+		if (chat.status === "blocked") throw new TelegramPluginError("chat_blocked", "the chat blocked the bot");
+		if (chat.status !== "active") throw new TelegramPluginError("chat_not_found", "destination chat is not active");
+		return [{
+			chat,
+			bot: await botOf(rt, chat.bot_id),
+			destination: dest,
+			threadId: dest.message_thread_id
+		}];
+	}
+	if (ai && !("me" in to)) throw new TelegramPluginError("destination_not_allowed", "the AI sends only to ai_allowed destinations or to me");
+	const userId = "me" in to ? rt.describe(actor).userId : to.user;
+	if (!userId) throw new TelegramPluginError("recipient_empty", "the caller has no user id");
+	const chats = await 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 c.kind = 'private' AND c.status = 'active'
+          AND b.deleted_at IS NULL AND b.status IN ('active', 'webhook_error') ORDER BY c.id`);
+	if (chats.length === 0) throw new TelegramPluginError("recipient_empty", "this user has no linked Telegram chat");
+	const out = [];
+	for (const chat of chats) out.push({
+		chat,
+		bot: await botOf(rt, chat.bot_id),
+		destination: null,
+		threadId: null
+	});
+	return out;
+}
+/** Opens a file through a registered file source, or the files port (`source: "files"`), checking `actor`. */
+async function openSource(rt, actor, source, ref) {
+	let file = null;
+	const def = rt.registry.fileSources.get(source);
+	if (def) file = await def.resolve({
+		actor,
+		ref,
+		env: rt.env
+	});
+	else if (source === "files" && rt.files) {
+		if (!rt.files.canRead || !await rt.files.canRead(actor, ref)) throw new TelegramPluginError("forbidden", "file not readable");
+		file = await rt.files.open(ref, actor);
+	} else throw new TelegramPluginError("validation_failed", `unknown file source "${source}"`);
+	if (!file) throw new TelegramPluginError("not_found", "file not found");
+	return file;
+}
+function text(html, extra = {}) {
+	return {
+		kind: "text",
+		html,
+		parts: html === "" ? [] : splitMessage(html),
+		markup: null,
+		sql: [],
+		buttons: null,
+		...extra
+	};
+}
+async function audienceFor(rt, t) {
+	const aud = await audienceOf(rt, t.chat, false);
+	if (!aud) throw new TelegramPluginError("recipient_empty", "the destination chat has no audience");
+	return aud;
+}
+function localesOf(t, aud) {
+	return [
+		t.chat.locale,
+		aud.info.locale,
+		t.bot.default_locale
+	];
+}
+function defaultRecordHtml(type, key, data) {
+	const lines = [`<b>${escapeHtml(type)} ${escapeHtml(key)}</b>`];
+	for (const [k, v] of Object.entries(data)) {
+		if (v === null || v === void 0 || typeof v === "object") continue;
+		lines.push(`${escapeHtml(k)}: ${escapeHtml(String(v))}`);
+	}
+	return lines.join("\n");
+}
+async function renderMessage(rt, t, vars, c, aud) {
+	const tz = c.target.chat.timezone ?? rt.settings.timezone;
+	const body = renderBody(rt, {
+		body: t.body,
+		format: t.format,
+		vars,
+		locales: localesOf(c.target, aud),
+		tz
+	});
+	const buttons = await buildButtons(rt, t.buttons, {
+		vars,
+		locale: body.locale,
+		tz,
+		botId: c.target.bot.id,
+		chatRef: c.store ? c.target.chat.id : null,
+		userId: aud.userId,
+		now: c.now
+	});
+	return text(body.html, {
+		markup: buttons.markup,
+		sql: buttons.sql,
+		buttons: buttons.preview
+	});
+}
+async function reportContent(rt, t, params, format, c) {
+	if (!rt.features.reports) throw featureDisabled("reports");
+	if (t.kind !== "report") throw new TelegramPluginError("validation_failed", `template "${t.key}" is not a report`);
+	const aud = await audienceFor(rt, c.target);
+	const built = await buildReport(rt, {
+		template: t,
+		actor: aud.actor,
+		params,
+		locales: localesOf(c.target, aud),
+		tz: c.target.chat.timezone ?? rt.settings.timezone,
+		format,
+		now: c.now,
+		viewer: c.store ? void 0 : c.sender
+	});
+	if (!c.store) {
+		if (built.file.body instanceof ReadableStream) await built.file.body.cancel().catch(() => {});
+		const size = built.file.size ?? (built.file.body instanceof Uint8Array ? built.file.body.byteLength : null);
+		return {
+			kind: "document",
+			html: built.caption.html,
+			file: {
+				ref: "",
+				name: built.file.name,
+				mime: built.file.mime,
+				size,
+				source: null
+			}
+		};
+	}
+	const stored = await storeReportFile(rt, built.file, {
+		template: t.key,
+		source_kind: "send"
+	});
+	if (stored.size !== null && stored.size > 52428800) {
+		rt.log.warn("tg.file_too_large", {
+			template: t.key,
+			code: "file_too_large"
+		});
+		const url = await fileUrl(rt, stored.ref);
+		const locale = built.caption.locale;
+		const link = url ? `\n${rt.i18n.t(locale, "bot.report.download")} <a href="${escapeHtml(url)}">${escapeHtml(stored.name)}</a>` : "";
+		return text([built.caption.html, `${rt.i18n.t(locale, "bot.report.too_large")}${link}`].filter(Boolean).join("\n\n"));
+	}
+	return {
+		kind: "document",
+		html: built.caption.html,
+		file: {
+			ref: stored.ref,
+			name: stored.name,
+			mime: stored.mime,
+			size: stored.size,
+			source: null
+		}
+	};
+}
+async function contentFor(rt, intent, c) {
+	const what = intent.what;
+	const note = intent.note ? escapeHtml(intent.note) : "";
+	if ("text" in what) return text(escapeHtml(what.text));
+	if ("file" in what) {
+		const file = await openSource(rt, c.sender, what.file.source, what.file.ref);
+		await file.body.cancel().catch(() => {});
+		if (file.size !== null && file.size > 52428800) throw new TelegramPluginError("file_too_large", "the file is over Telegram's 50 MB limit");
+		return {
+			kind: "document",
+			html: note,
+			file: {
+				ref: file.ref,
+				name: file.name,
+				mime: file.mime,
+				size: file.size,
+				source: what.file.source === "files" ? null : what.file.source
+			}
+		};
+	}
+	if ("template" in what || "report" in what) {
+		const key = "template" in what ? what.template : what.report;
+		if (!rt.features.templates) throw featureDisabled("templates");
+		const t = templateModel(await requireTemplateByKey(rt, key));
+		if (t.provider && !await hostCan(rt, c.sender, requireProvider(rt, t.provider).permission)) throw new TelegramPluginError("provider_forbidden", `you may not read "${t.provider}"`);
+		if ("report" in what || t.kind === "report") return reportContent(rt, t, what.params, "report" in what ? what.format : void 0, c);
+		const aud = await audienceFor(rt, c.target);
+		return renderMessage(rt, t, await templateData(rt, {
+			template: t,
+			actor: aud.actor,
+			params: what.params,
+			tz: c.target.chat.timezone ?? rt.settings.timezone,
+			now: c.now,
+			locale: rt.i18n.pick(...localesOf(c.target, aud)),
+			viewer: c.store ? void 0 : c.sender
+		}), c, aud);
+	}
+	const { type, key, fields } = what.record;
+	const def = rt.registry.providers.get(recordProviderKey(type));
+	if (!def) throw new TelegramPluginError("provider_unknown", `no provider "${recordProviderKey(type)}" for record sends`);
+	const params = parseProviderParams(def, {
+		key,
+		...fields ? { fields } : {}
+	});
+	const aud = await audienceFor(rt, c.target);
+	if (!await hostCan(rt, c.sender, def.permission)) throw new TelegramPluginError("provider_forbidden", `you may not read this ${type}`);
+	if (!await hostCan(rt, aud.actor, def.permission)) throw new TelegramPluginError("provider_forbidden", `the destination may not see this ${type}`);
+	const tz = c.target.chat.timezone ?? rt.settings.timezone;
+	const locale = rt.i18n.pick(...localesOf(c.target, aud));
+	const base = {
+		def,
+		params,
+		now: c.now,
+		tz,
+		locale,
+		checked: true
+	};
+	const [mine, theirs] = await Promise.all([runProvider(rt, {
+		...base,
+		actor: c.sender
+	}), runProvider(rt, {
+		...base,
+		actor: aud.actor
+	})]);
+	let data = intersectData(mine, theirs) ?? {};
+	if (fields && fields.length > 0) data = Object.fromEntries(Object.entries(data).filter(([k]) => fields.includes(k)));
+	const row = await templateByKey(rt, recordProviderKey(type));
+	if (row && row.kind === "message") return renderMessage(rt, templateModel(row), {
+		...data,
+		key,
+		type
+	}, c, aud);
+	return text([defaultRecordHtml(type, key, data), note].filter(Boolean).join("\n\n"));
+}
+/** AI-written `text` and `note` must pass the content checks for every audience the send reaches (docs/07 §2.4). */
+async function checkAiIntent(rt, intent, targets, appDomains) {
+	const texts = [..."text" in intent.what ? [intent.what.text] : [], ...intent.note ? [intent.note] : []];
+	if (texts.length === 0) return;
+	const reasons = /* @__PURE__ */ new Set();
+	const domains = [...rt.ai.appDomains, ...appDomains];
+	for (const t of targets) {
+		const aud = await audienceFor(rt, t);
+		const money = rt.ai.moneyPermission;
+		const seesMoney = money !== null && await hostCan(rt, aud.actor, money);
+		for (const body of texts) {
+			const r = checkAiText(body, {
+				audienceSeesMoney: seesMoney,
+				allowContacts: rt.ai.allowContacts,
+				appDomains: domains,
+				maxLength: rt.ai.maxTextLength
+			});
+			if (!r.ok) for (const reason of r.reasons) reasons.add(reason);
+		}
+	}
+	if (reasons.size === 0) return;
+	const list = [...reasons];
+	rt.log.info("tg.ai_text_rejected", { reasons: list.join(",") });
+	throw new TelegramPluginError("send_text_rejected", `text rejected: ${list.join(", ")}`, { extensions: { reasons: list } });
+}
+async function prepare(rt, actor, intent, source, appDomains = []) {
+	const ai = source === "ai";
+	if (ai && (!rt.features.ai || !rt.features.aiSendIntent)) throw featureDisabled("ai");
+	if (!await rt.can(actor, "telegram.send")) throw new TelegramPluginError("forbidden", "missing telegram.send");
+	const targets = await resolveTargets(rt, actor, intent, ai);
+	if (ai) await checkAiIntent(rt, intent, targets, appDomains);
+	return {
+		ai,
+		targets
+	};
+}
+/** SQL for the host's batch: one row per part and chat. Call `kick(env)` after the batch commits. */
+async function enqueueIntent(rt, actor, intent, opts) {
+	if (!opts.dedupeKey || opts.dedupeKey.length > 200) throw new TelegramPluginError("validation_failed", "dedupeKey is required (≤ 200 chars)");
+	const source = opts.source ?? "api";
+	const { ai, targets } = await prepare(rt, actor, intent, source, opts.appDomains);
+	const dedupeKey = ai && !opts.dedupeKey.startsWith("ai:") ? `ai:${opts.dedupeKey}` : opts.dedupeKey;
+	const now = rt.clock.now();
+	const out = [];
+	for (const t of targets) {
+		const c = await contentFor(rt, intent, {
+			sender: actor,
+			target: t,
+			ai,
+			appDomains: opts.appDomains ?? [],
+			store: true,
+			now
+		});
+		const base = targets.length > 1 ? `${dedupeKey}:${t.chat.id}` : dedupeKey;
+		const common = {
+			botId: t.bot.id,
+			chatRef: t.chat.id,
+			threadId: t.threadId,
+			source,
+			sourceId: base,
+			dedupeKey: base
+		};
+		if (c.kind === "text") {
+			if (c.html === "") continue;
+			const rows = deliveryFragments(rt, {
+				...common,
+				kind: "text",
+				html: c.html,
+				replyMarkup: c.markup
+			}, now);
+			out.push(...c.sql, ...rows, ...orphanTokenGuard(rt, c.markup, `${base}:${rows.length - 1}`));
+			continue;
+		}
+		const input = {
+			...common,
+			kind: "document",
+			html: c.html,
+			file: {
+				ref: c.file.ref,
+				name: c.file.name,
+				mime: c.file.mime,
+				source: c.file.source ?? void 0
+			}
+		};
+		out.push(...deliveryFragments(rt, input, now));
+	}
+	return out;
+}
+function kindOf(kind) {
+	return kind === "group" || kind === "supergroup" || kind === "channel" ? kind : "private";
+}
+/** What `enqueue` would send (rendered for the first target's audience), for the host's confirm card. */
+async function previewIntent(rt, actor, intent, opts = {}) {
+	const { ai, targets } = await prepare(rt, actor, intent, opts.source ?? "api", opts.appDomains);
+	const first = targets[0];
+	const c = await contentFor(rt, intent, {
+		sender: actor,
+		target: first,
+		ai,
+		appDomains: opts.appDomains ?? [],
+		store: false,
+		now: rt.clock.now()
+	});
+	const warnings = [];
+	if (targets.length > 1) warnings.push(`sent to ${targets.length} chats`);
+	const file = c.kind === "document" ? {
+		name: c.file.name,
+		mime: c.file.mime,
+		size: c.file.size
+	} : null;
+	const name = first.destination?.name ?? first.chat.title ?? first.chat.username ?? "";
+	const locale = rt.i18n.pick(rt.describe(actor).locale);
+	const audience = await describeAudience(rt, first, locale);
+	const consequence = [rt.i18n.plain(locale, "bot.ai.consequence", {
+		what: describeWhat(rt, intent, file, locale),
+		name,
+		bot: first.bot.username,
+		audience
+	}), targets.length > 1 ? rt.i18n.plain(locale, "bot.ai.chats", { count: targets.length }) : ""].filter(Boolean).join(" ");
+	return {
+		to: {
+			name,
+			kind: kindOf(first.chat.kind),
+			botUsername: first.bot.username,
+			destination: first.destination?.slug ?? null
+		},
+		audience,
+		parts: c.kind === "text" ? c.parts : c.html === "" ? [] : splitMessage(c.html),
+		buttons: c.kind === "text" ? c.buttons : null,
+		file,
+		attachments: file ? [file] : [],
+		consequence,
+		chats: targets.length,
+		source: ai ? "ai" : "api",
+		warnings
+	};
+}
+/** "Only Asha will see it." / "Everyone in this group will see it (as pm)." in `locale`. */
+async function describeAudience(rt, t, locale) {
+	if (t.chat.kind === "private") {
+		const who = (await audienceOf(rt, t.chat, false))?.info.name ?? t.chat.title ?? t.chat.username ?? "";
+		return rt.i18n.plain(locale, "bot.ai.audience.user", { name: who });
+	}
+	const a = parseJson(t.chat.audience_json, Audience.nullable(), null);
+	return a && "role" in a ? rt.i18n.plain(locale, "bot.ai.audience.role", { role: a.role }) : rt.i18n.plain(locale, "bot.ai.audience.group");
+}
+function describeWhat(rt, intent, file, locale) {
+	const w = intent.what;
+	if ("text" in w) return rt.i18n.plain(locale, "bot.ai.what.text");
+	if ("record" in w) return rt.i18n.plain(locale, "bot.ai.what.record", {
+		type: w.record.type,
+		key: w.record.key
+	});
+	if ("template" in w) return rt.i18n.plain(locale, "bot.ai.what.template", { name: w.template });
+	if ("report" in w) return rt.i18n.plain(locale, "bot.ai.what.report", { name: file?.name ?? w.report });
+	return rt.i18n.plain(locale, "bot.ai.what.file", { name: file?.name ?? w.file.ref });
+}
+export { FILES_PORT_SOURCE, enqueueIntent, intersectData, openSource, previewIntent, recordProviderKey };

package/dist/services/subscriptions.js

@@ -0,0 +1,28 @@
+import { sql } from "../ports/sql.js";
+import { subscriptionDto } from "../engine/rows.js";
+// src/services/subscriptions.ts
+async function listSubscriptions(rt, chatRefs) {
+	if (chatRefs.length === 0) return [];
+	const out = [];
+	for (let i = 0; i < chatRefs.length; i += 50) {
+		const rows = await rt.db.all(sql`SELECT * FROM tg_subscription WHERE tenant = ${rt.tenant} AND chat_ref IN (${sql.join(chatRefs.slice(i, i + 50))})
+          ORDER BY chat_ref, topic`);
+		out.push(...rows.map(subscriptionDto));
+	}
+	return out;
+}
+async function replaceSubscriptions(rt, save) {
+	const now = rt.clock.now();
+	const seen = /* @__PURE__ */ new Set();
+	const inserts = [];
+	for (const item of save.items) {
+		if (seen.has(item.topic)) continue;
+		seen.add(item.topic);
+		inserts.push(sql`INSERT INTO tg_subscription (tenant, chat_ref, topic, muted, quiet_json, updated_at)
+          VALUES (${rt.tenant}, ${save.chatRef}, ${item.topic}, ${item.muted},
+                  ${item.quiet === null ? null : JSON.stringify(item.quiet)}, ${now})`);
+	}
+	await rt.db.batch([sql`DELETE FROM tg_subscription WHERE tenant = ${rt.tenant} AND chat_ref = ${save.chatRef}`, ...inserts]);
+	return listSubscriptions(rt, [save.chatRef]);
+}
+export { listSubscriptions, replaceSubscriptions };