@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/engine/dispatch/commands.js

@@ -0,0 +1,194 @@
+import { escapeHtml } from "../../core/html/escape.js";
+import { sql } from "../../ports/sql.js";
+import { isTelegramPluginError } from "../errors.js";
+import { ProviderTimeout, hostCan } from "../content/providers.js";
+import { botDto, chatDto } from "../rows.js";
+import { templateModel } from "../content/template-rows.js";
+import { commandRows, describe, effectiveCommands, findCommand, rolesAllow } from "../../services/commands.js";
+import { replyReport } from "../content/reply.js";
+import { hostContext, senderMayAct } from "./context.js";
+import { z } from "zod";
+// src/engine/dispatch/commands.ts
+function chatKind(ctx) {
+	const t = ctx.tgChat?.type;
+	return t === "group" || t === "supergroup" || t === "channel" ? t : "private";
+}
+/** Default args parser: tokens fill the object's keys in order; the last key takes the rest. */
+function defaultParseArgs(schema, text) {
+	if (!(schema instanceof z.ZodObject)) return text.trim() === "" ? {} : { text: text.trim() };
+	const keys = Object.keys(schema.shape);
+	const tokens = text.trim() === "" ? [] : text.trim().split(/\s+/);
+	const out = {};
+	keys.forEach((k, i) => {
+		const v = i === keys.length - 1 ? tokens.slice(i).join(" ") : tokens[i];
+		if (v !== void 0 && v !== "") out[k] = v;
+	});
+	return out;
+}
+function usageOf(schema) {
+	if (!(schema instanceof z.ZodObject)) return "";
+	return Object.entries(schema.shape).map(([k, s]) => s.safeParse(void 0).success ? `[${k}]` : `<${k}>`).join(" ");
+}
+/** Roles (`"*"` any, `[]` none) + host permission for an actor. Groups use their audience's role. */
+async function commandAllowed(ctx, cmd, actor) {
+	if (!rolesAllow(cmd.roles, ctx.rt.describe(actor).role)) return false;
+	return hostCan(ctx.rt, actor, cmd.def.permission);
+}
+async function replyError(ctx, e, report) {
+	if (isTelegramPluginError(e) && (e.code === "provider_forbidden" || e.code === "forbidden")) {
+		await ctx.reply(await ctx.t("bot.error.forbidden"));
+		return;
+	}
+	const code = isTelegramPluginError(e) ? e.code : e instanceof ProviderTimeout ? "provider_timeout" : "error";
+	ctx.rt.log.warn("tg.command_failed", {
+		botId: ctx.bot.id,
+		code
+	});
+	if (report) await ctx.reply(await ctx.t("bot.report.failed"));
+	else if (code === "provider_timeout" || code === "error") await ctx.reply(await ctx.t("bot.data.failed"));
+	else await ctx.reply(await ctx.t("bot.error.generic"));
+}
+/** `key=value` tokens → params (numbers stay strings; the provider's Zod params coerce them). */
+function kvParams(tokens) {
+	const out = {};
+	for (const t of tokens) {
+		const i = t.indexOf("=");
+		if (i > 0) out[t.slice(0, i)] = t.slice(i + 1);
+	}
+	return out;
+}
+/** Up to {@link REPORT_LIST_MAX} report lines this actor may read (keyset pages, so hidden rows do not end it). */
+async function reportLines(ctx, actor) {
+	const { rt } = ctx;
+	const lines = [];
+	let after = "";
+	for (;;) {
+		const page = await rt.db.all(sql`SELECT * FROM tg_template WHERE tenant = ${rt.tenant} AND kind = 'report' AND deleted_at IS NULL
+          AND key > ${after} ORDER BY key LIMIT 100`);
+		for (const r of page) {
+			const def = r.provider ? rt.registry.providers.get(r.provider) : void 0;
+			if (r.provider && (!def || !await hostCan(rt, actor, def.permission))) continue;
+			if (lines.length === 30) return {
+				lines,
+				more: true
+			};
+			lines.push(`/report ${escapeHtml(r.key)} — ${escapeHtml(r.name)}`);
+		}
+		const last = page.at(-1);
+		if (page.length < 100 || !last) return {
+			lines,
+			more: false
+		};
+		after = last.key;
+	}
+}
+/** `/report` lists the report templates this audience may read; `/report <key> [k=v…]` sends one. */
+async function reportCommand(ctx) {
+	const { rt } = ctx;
+	const actor = await ctx.actor();
+	if (actor === null) {
+		await ctx.reply(await ctx.t(chatKind(ctx) === "private" ? "bot.start.unlinked" : "bot.error.not_linked"));
+		return "handled";
+	}
+	if (!await senderMayAct(ctx)) {
+		await ctx.reply(await ctx.t("bot.error.sender_not_linked"));
+		return "handled";
+	}
+	const args = ctx.command?.args ?? [];
+	const name = args[0]?.toLowerCase();
+	if (!name) {
+		const { lines, more } = await reportLines(ctx, actor);
+		if (lines.length === 0) {
+			await ctx.reply(await ctx.t("bot.report.none"));
+			return "handled";
+		}
+		const tail = more ? `\n${await ctx.t("bot.report.more")}` : "";
+		await ctx.reply(`${await ctx.t("bot.report.list_header")}\n${lines.join("\n")}${tail}`);
+		return "handled";
+	}
+	const row = await rt.db.first(sql`SELECT * FROM tg_template WHERE tenant = ${rt.tenant} AND kind = 'report' AND deleted_at IS NULL
+        AND key = ${name}`);
+	if (!row) {
+		await ctx.reply(await ctx.t("bot.report.unknown"));
+		return "handled";
+	}
+	try {
+		await replyReport(ctx, templateModel(row), actor, kvParams(args.slice(1)));
+	} catch (e) {
+		await replyError(ctx, e, true);
+	}
+	return "handled";
+}
+/**
+* Update handler for host commands (features.commands) and the built-in `/report`: runs the checks in order
+* (enabled, scope, linked audience, roles, permission, Zod args) and replies through the outbox. `"next"` when the
+* update is not a host command.
+*/
+async function hostCommandsHandler(ctx) {
+	const { rt } = ctx;
+	const cmd = ctx.command;
+	if (!rt.features.commands || ctx.cls !== "command" || !cmd || cmd.mentionedOther) return "next";
+	if (cmd.command === "report" && rt.features.reports) return reportCommand(ctx);
+	if (rt.registry.commandList.length === 0) return "next";
+	const found = findCommand(effectiveCommands(rt, await commandRows(rt, ctx.bot.id)), cmd.command);
+	if (!found) return "next";
+	const kind = chatKind(ctx);
+	if (!found.def.scope.includes(kind)) {
+		if (kind === "private" || cmd.mention !== null) await ctx.reply(await ctx.t("bot.command.wrong_chat"));
+		return "handled";
+	}
+	const actor = await ctx.actor();
+	if (actor === null) {
+		await ctx.reply(await ctx.t(kind === "private" ? "bot.start.unlinked" : "bot.error.not_linked"));
+		return "handled";
+	}
+	if (!await senderMayAct(ctx, found.def.groupMembers)) {
+		await ctx.reply(await ctx.t("bot.error.sender_not_linked"));
+		return "handled";
+	}
+	if (!await commandAllowed(ctx, found, actor)) {
+		await ctx.reply(await ctx.t("bot.error.forbidden"));
+		return "handled";
+	}
+	const def = found.def;
+	const raw = def.parseArgs ? def.parseArgs(cmd.argsText) : defaultParseArgs(def.args, cmd.argsText);
+	let args = raw;
+	if (def.args) {
+		const parsed = def.args.safeParse(raw);
+		if (!parsed.success) {
+			const locale = await ctx.locale();
+			const usage = `/${def.command} ${usageOf(def.args)}`.trim();
+			await ctx.reply(`${rt.i18n.t(locale, "bot.command.usage", { usage })}\n${escapeHtml(describe(found.description, locale))}`);
+			return "handled";
+		}
+		args = parsed.data;
+	}
+	try {
+		if (def.template !== null) {
+			const host = await hostContext(ctx, ctx.message?.text ?? "");
+			const params = args !== null && typeof args === "object" ? args : {};
+			await host.reply.template(def.template, params);
+		} else if (def.handle) {
+			const host = await hostContext(ctx, ctx.message?.text ?? "");
+			const cctx = {
+				actor,
+				chat: ctx.chat ? chatDto(ctx.chat) : null,
+				bot: botDto(ctx.bot),
+				args,
+				argsText: cmd.argsText,
+				locale: host.locale,
+				t: host.t,
+				reply: host.reply,
+				startDialog: host.startDialog,
+				db: host.db,
+				now: host.now,
+				env: host.env
+			};
+			await def.handle(cctx);
+		}
+	} catch (e) {
+		await replyError(ctx, e, false);
+	}
+	return "handled";
+}
+export { commandAllowed, defaultParseArgs, hostCommandsHandler };

package/dist/engine/dispatch/context.d.ts

@@ -0,0 +1,2 @@
+/** Wraps chat text for an LLM prompt as clearly marked untrusted data. */
+export declare function untrustedWrap(text: string): string;

package/dist/engine/dispatch/context.js

@@ -0,0 +1,194 @@
+import { Audience } from "../../contracts/chats.js";
+import { escapeHtml } from "../../core/html/escape.js";
+import { splitMessage } from "../../core/split/split.js";
+import { sql } from "../../ports/sql.js";
+import { settle } from "../../telegram/classify.js";
+import { withToken } from "../bot-api.js";
+import { botDto, chatDto, parseJson } from "../rows.js";
+import { startDialog } from "../dialogs/dialog.js";
+import { updateChat, updateFrom, updateMessage } from "../../telegram/inbound.js";
+import { buildButtons, orphanTokenGuard } from "../content/buttons.js";
+import { deliveryFragments } from "../outbox/enqueue.js";
+import { replyFile, replyTemplate } from "../content/reply.js";
+// src/engine/dispatch/context.ts
+/** Wraps chat text for an LLM prompt as clearly marked untrusted data. */
+function untrustedWrap(text) {
+	return `<untrusted_user_message source="telegram">\n${text.replace(/[<>&]/g, (c) => c === "<" ? "&lt;" : c === ">" ? "&gt;" : "&amp;")}\n</untrusted_user_message>`;
+}
+function createUpdateContext(rt, bot, update, cls, command, chat, now) {
+	const message = updateMessage(update);
+	const tgChat = updateChat(update);
+	const from = updateFrom(update);
+	let actorMemo;
+	let senderMemo;
+	let replies = 0;
+	let queued = false;
+	const ctx = {
+		rt,
+		bot,
+		update,
+		cls,
+		message,
+		tgChat,
+		from,
+		command,
+		now,
+		chat,
+		get queued() {
+			return queued;
+		},
+		actor() {
+			actorMemo ??= (async () => {
+				const c = ctx.chat;
+				if (c?.status !== "active") return null;
+				if (c.kind === "private") return c.user_id ? await rt.actor.forUser(c.user_id) : null;
+				const audience = parseJson(c.audience_json, Audience.nullable(), null);
+				return audience ? await rt.actor.forAudience(audience) : null;
+			})();
+			return actorMemo;
+		},
+		senderActor() {
+			senderMemo ??= (async () => {
+				if (!from) return null;
+				const own = ctx.chat?.kind === "private" ? ctx.chat : await rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND bot_id = ${bot.id}
+                    AND chat_id = ${String(from.id)} AND kind = 'private'`);
+				if (own?.status !== "active" || !own.user_id) return null;
+				const actor = await rt.actor.forUser(own.user_id);
+				return actor === null ? null : {
+					actor,
+					userId: own.user_id
+				};
+			})();
+			return senderMemo;
+		},
+		async actorInfo() {
+			const a = await ctx.actor();
+			return a === null ? null : rt.describe(a);
+		},
+		async locale() {
+			const info = await ctx.actorInfo().catch(() => null);
+			return rt.i18n.pick(ctx.chat?.locale, info?.locale, from?.language_code, bot.default_locale);
+		},
+		async t(key, vars) {
+			return rt.i18n.t(await ctx.locale(), key, vars);
+		},
+		async replyDelivery(input) {
+			if (ctx.chat?.status !== "active") {
+				if (input.kind === "text" && input.html !== "") await ctx.reply(input.html);
+				return false;
+			}
+			const n = replies++;
+			const base = n === 0 ? `cmd:${bot.id}:${update.update_id}` : `cmd:${bot.id}:${update.update_id}:r${n}`;
+			const rows = deliveryFragments(rt, {
+				botId: bot.id,
+				chatRef: ctx.chat.id,
+				threadId: message?.message_thread_id ?? null,
+				source: "command",
+				sourceId: n === 0 ? String(update.update_id) : `${update.update_id}:${n}`,
+				kind: input.kind,
+				html: input.html,
+				file: input.file,
+				replyMarkup: input.replyMarkup ?? null,
+				options: input.options,
+				dedupeKey: base,
+				render: input.render
+			}, rt.clock.now());
+			const guard = orphanTokenGuard(rt, input.replyMarkup ?? null, `${base}:${rows.length - 1}`);
+			await rt.db.batch([
+				...input.sql ?? [],
+				...rows,
+				...guard
+			]);
+			queued = true;
+			return true;
+		},
+		async reply(html, opts) {
+			const body = opts?.plain ? escapeHtml(html) : html;
+			const threadId = message?.message_thread_id ?? null;
+			const options = {
+				...opts?.silent ? { silent: true } : {},
+				...opts?.protectContent ? { protectContent: true } : {}
+			};
+			const linked = ctx.chat?.status === "active" ? ctx.chat : null;
+			const built = opts?.buttons ? await buildButtons(rt, opts.buttons, {
+				vars: {},
+				locale: await ctx.locale(),
+				tz: linked?.timezone ?? rt.settings.timezone,
+				botId: bot.id,
+				chatRef: linked?.id ?? null,
+				userId: linked?.kind === "private" ? linked.user_id : null,
+				now: rt.clock.now()
+			}) : null;
+			const markup = built?.markup ?? null;
+			if (linked) {
+				await ctx.replyDelivery({
+					kind: "text",
+					html: body,
+					replyMarkup: markup,
+					options,
+					sql: built?.sql
+				});
+				return;
+			}
+			if (!tgChat) return;
+			await withToken(rt, bot, async (api) => {
+				for (const part of splitMessage(body)) {
+					const r = await settle(api.sendMessage({
+						chat_id: tgChat.id,
+						text: part,
+						parse_mode: "HTML",
+						link_preview_options: { is_disabled: true },
+						...threadId === null ? {} : { message_thread_id: threadId },
+						...markup ? { reply_markup: markup } : {}
+					}));
+					if (r.outcome.kind !== "ok") {
+						rt.log.warn("tg.reply_failed", {
+							botId: bot.id,
+							code: r.outcome.reason ?? r.outcome.kind
+						});
+						return;
+					}
+				}
+			});
+		}
+	};
+	return ctx;
+}
+/** True for group and supergroup chats (where a linked chat acts as its audience). */
+function isGroupChat(ctx) {
+	const t = ctx.tgChat?.type;
+	return t === "group" || t === "supergroup";
+}
+/**
+* In a group, whether the sender may act as the group's audience: with `"linked"` (the default from
+* `groups.requireLinkedSender`) only senders who linked their own Telegram on this bot. Always true outside groups.
+*/
+async function senderMayAct(ctx, mode) {
+	if (!isGroupChat(ctx)) return true;
+	if ((mode ?? (ctx.rt.groups.requireLinkedSender ? "linked" : "any")) === "any") return true;
+	return await ctx.senderActor() !== null;
+}
+/** The host-facing context for hooks (`onFreeText`, `onUnknownCommand`, `onInbound`) and command handlers. */
+async function hostContext(ctx, text) {
+	const locale = await ctx.locale();
+	return {
+		actor: await ctx.actor(),
+		chat: ctx.chat ? chatDto(ctx.chat) : null,
+		bot: botDto(ctx.bot),
+		locale,
+		text,
+		untrustedText: untrustedWrap(text),
+		untrusted: true,
+		t: (key, vars) => ctx.rt.i18n.t(locale, key, vars),
+		reply: {
+			text: (html, opts) => ctx.reply(html, opts),
+			template: (key, params, opts) => replyTemplate(ctx, key, params, opts),
+			file: (file, opts) => replyFile(ctx, file, opts)
+		},
+		startDialog: (key, state) => startDialog(ctx, key, state),
+		db: ctx.rt.db,
+		now: ctx.now,
+		env: ctx.rt.env
+	};
+}
+export { createUpdateContext, hostContext, isGroupChat, senderMayAct, untrustedWrap };

package/dist/engine/dispatch/dispatcher.js

@@ -0,0 +1,66 @@
+import { sql } from "../../ports/sql.js";
+import { classifyUpdate, parseCommand, updateChat, updateMessage, updateType } from "../../telegram/inbound.js";
+import { botRuntime } from "../bot-features.js";
+import { createUpdateContext } from "./context.js";
+import { defaultHandlers } from "./handlers.js";
+// src/engine/dispatch/dispatcher.ts
+/** Inserts the update id. False when Telegram already delivered it (duplicate → drop). */
+async function recordUpdate(rt, botId, update, now) {
+	const chat = updateChat(update);
+	return await rt.db.first(sql`INSERT INTO tg_update (tenant, bot_id, update_id, kind, chat_id, status, attempts, received_at)
+        VALUES (${rt.tenant}, ${botId}, ${update.update_id}, ${updateType(update)},
+                ${chat ? String(chat.id) : null}, 'received', 0, ${now})
+        ON CONFLICT (bot_id, update_id) DO NOTHING RETURNING update_id`) !== null;
+}
+/** Runs the handler chain for one recorded update. Never throws. */
+async function processUpdate(base, bot, update) {
+	const rt = botRuntime(base, bot);
+	const started = rt.clock.now();
+	const cls = classifyUpdate(update);
+	const message = updateMessage(update);
+	const command = cls === "command" ? parseCommand(message?.text, message?.entities, bot.username) : null;
+	let result = "ignored";
+	let error = null;
+	let queued = false;
+	try {
+		await rt.db.run(sql`UPDATE tg_update SET attempts = attempts + 1 WHERE bot_id = ${bot.id} AND update_id = ${update.update_id}`);
+		const tgChat = updateChat(update);
+		const chat = tgChat ? await rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND bot_id = ${bot.id} AND chat_id = ${String(tgChat.id)}`) : null;
+		const ctx = createUpdateContext(rt, bot, update, cls, command, chat, started);
+		let outcome = "ignored";
+		for (const h of defaultHandlers()) {
+			outcome = await h.handle(ctx);
+			if (outcome !== "next") break;
+		}
+		result = outcome === "handled" ? "done" : "ignored";
+		queued = ctx.queued;
+	} catch (e) {
+		result = "failed";
+		error = e instanceof Error ? e.name : "error";
+		rt.log.error("tg.update_failed", {
+			botId: bot.id,
+			updateId: update.update_id,
+			error
+		});
+	}
+	await rt.db.run(sql`UPDATE tg_update SET status = ${result}, processed_at = ${rt.clock.now()}, error = ${error}
+          WHERE bot_id = ${bot.id} AND update_id = ${update.update_id}`).catch(() => {});
+	rt.log.info("tg.update", {
+		botId: bot.id,
+		updateId: update.update_id,
+		kind: cls,
+		status: result,
+		ms: rt.clock.now() - started
+	});
+	if (queued) await rt.transport.kick([bot.id]).catch(() => {});
+	return result;
+}
+/** Updates stuck in `received` (the webhook's waitUntil was cut off). Their bodies are not stored, so they are
+* marked `failed` (Queue mode retries them through the queue instead). */
+async function sweepStuckUpdates(rt, now, olderThanMs = 12e4) {
+	const r = await rt.db.run(sql`UPDATE tg_update SET status = 'failed', error = 'stalled', processed_at = ${now}
+        WHERE tenant = ${rt.tenant} AND status = 'received' AND received_at < ${now - olderThanMs}`);
+	if (r.changes > 0) rt.log.warn("tg.updates_stalled", { count: r.changes });
+	return r.changes;
+}
+export { processUpdate, recordUpdate, sweepStuckUpdates };

package/dist/engine/dispatch/handlers.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/engine/dispatch/handlers.js

@@ -0,0 +1,103 @@
+import { sql } from "../../ports/sql.js";
+import { settle } from "../../telegram/classify.js";
+import { withToken } from "../bot-api.js";
+import { actionCallback, cutText } from "../actions/callback.js";
+import { dialogHandler } from "../dialogs/dialog.js";
+import { hostCommandsHandler } from "./commands.js";
+import { builtinsHandler, fallbackHandler } from "./builtins.js";
+import { hostContext, senderMayAct } from "./context.js";
+import { inboundHandler } from "../inbound/handler.js";
+import { lifecycleHandler } from "./lifecycle.js";
+import { startHandler } from "./linking.js";
+// src/engine/dispatch/handlers.ts
+/** Inbound limit per chat (default 20/min): one "slow down" reply, then silence until the minute passes. */
+async function rateLimitHandler(ctx) {
+	const { rt, tgChat } = ctx;
+	if (!tgChat || ctx.cls === "lifecycle") return "next";
+	const n = (await rt.db.first(sql`SELECT COUNT(*) AS n FROM tg_update WHERE bot_id = ${ctx.bot.id}
+        AND update_id > ${ctx.update.update_id - 5e3} AND update_id <= ${ctx.update.update_id}
+        AND chat_id = ${String(tgChat.id)} AND received_at > ${ctx.now - 6e4} AND kind != 'my_chat_member'`))?.n ?? 0;
+	const limit = rt.limits.inboundPerMin;
+	if (n <= limit) return "next";
+	if (n === limit + 1) {
+		rt.log.warn("tg.inbound_limited", { botId: ctx.bot.id });
+		if (ctx.update.callback_query) await answerCallback(ctx, await ctx.t("bot.error.rate_limited"));
+		else await ctx.reply(await ctx.t("bot.error.rate_limited"));
+	} else if (ctx.update.callback_query) await answerCallback(ctx);
+	return "ignored";
+}
+/** `answerCallbackQuery` is sent directly (time-sensitive), never through the outbox. */
+async function answerCallback(ctx, text) {
+	const q = ctx.update.callback_query;
+	if (!q) return;
+	await withToken(ctx.rt, ctx.bot, async (api) => {
+		const r = await settle(api.answerCallbackQuery({
+			callback_query_id: q.id,
+			...text ? { text: cutText(text) } : {}
+		}));
+		if (r.outcome.kind !== "ok") ctx.rt.log.debug("tg.callback_answer_failed", { code: r.outcome.reason ?? r.outcome.kind });
+	});
+}
+/** `a:<id>` action tokens (features.actions). Any other data only stops the spinner with "expired". */
+async function callbackHandler(ctx) {
+	if (ctx.cls !== "callback") return "next";
+	const data = ctx.update.callback_query?.data ?? "";
+	if (data.startsWith("a:")) return actionCallback(ctx, data);
+	await answerCallback(ctx, ctx.rt.i18n.plain(await ctx.locale(), "bot.action.expired"));
+	return "handled";
+}
+/** AI free text (features.ai.freeText): plain text in a linked chat goes to `hooks.onFreeText`. */
+async function freeTextHandler(ctx) {
+	const { rt } = ctx;
+	if (ctx.cls !== "text" || !rt.features.aiFreeText || !rt.hooks.onFreeText) return "next";
+	if (ctx.chat?.status !== "active" || await ctx.actor() === null) return "next";
+	if (!await senderMayAct(ctx)) return "next";
+	const host = await hostContext(ctx, ctx.message?.text ?? "");
+	await rt.hook("onFreeText", (fn) => fn(host));
+	return "handled";
+}
+function defaultHandlers() {
+	return [
+		{
+			name: "lifecycle",
+			handle: lifecycleHandler
+		},
+		{
+			name: "rate_limit",
+			handle: rateLimitHandler
+		},
+		{
+			name: "dialogs",
+			handle: dialogHandler
+		},
+		{
+			name: "start",
+			handle: startHandler
+		},
+		{
+			name: "builtins",
+			handle: builtinsHandler
+		},
+		{
+			name: "commands",
+			handle: hostCommandsHandler
+		},
+		{
+			name: "callbacks",
+			handle: callbackHandler
+		},
+		{
+			name: "inbound",
+			handle: inboundHandler
+		},
+		{
+			name: "free_text",
+			handle: freeTextHandler
+		},
+		{
+			name: "fallback",
+			handle: fallbackHandler
+		}
+	];
+}
+export { answerCallback, defaultHandlers };

package/dist/engine/dispatch/lifecycle.js

@@ -0,0 +1,85 @@
+import { sql } from "../../ports/sql.js";
+import { afterChatGone, chatGoneSql, migrateChat } from "../chat-state.js";
+// src/engine/dispatch/lifecycle.ts
+const PRESENT = /* @__PURE__ */ new Set([
+	"member",
+	"administrator",
+	"creator",
+	"restricted"
+]);
+const GONE = /* @__PURE__ */ new Set(["left", "kicked"]);
+async function chatByTelegramId(ctx, chatId) {
+	return ctx.rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${ctx.rt.tenant} AND bot_id = ${ctx.bot.id} AND chat_id = ${String(chatId)}`);
+}
+async function markGone(ctx, row, status) {
+	if (row.status === status) return;
+	await ctx.rt.db.batch(chatGoneSql(ctx.rt, row, status, ctx.now));
+	ctx.chat = {
+		...row,
+		status,
+		updated_at: ctx.now
+	};
+	ctx.rt.log.info("tg.chat_status", {
+		botId: ctx.bot.id,
+		chatRef: row.id,
+		status
+	});
+	await afterChatGone(ctx.rt, row, status, ctx.now);
+}
+async function markBack(ctx, row, tgChat) {
+	if (row.status !== "blocked" && row.status !== "left") return;
+	const status = (row.kind === "private" ? row.user_id !== null : row.audience_json !== null) ? "active" : "pending";
+	const title = tgChat.title ?? row.title;
+	await ctx.rt.db.run(sql`UPDATE tg_chat SET status = ${status}, title = ${title}, updated_at = ${ctx.now}
+        WHERE tenant = ${ctx.rt.tenant} AND id = ${row.id}`);
+	ctx.chat = {
+		...row,
+		status,
+		title,
+		updated_at: ctx.now
+	};
+	ctx.rt.log.info("tg.chat_status", {
+		botId: ctx.bot.id,
+		chatRef: row.id,
+		status
+	});
+}
+async function lifecycleHandler(ctx) {
+	if (ctx.cls !== "lifecycle") return "next";
+	const { update, bot } = ctx;
+	const member = update.my_chat_member;
+	if (member) {
+		const row = ctx.chat ?? await chatByTelegramId(ctx, member.chat.id);
+		if (!row) return "ignored";
+		const status = member.new_chat_member.status;
+		if (GONE.has(status)) await markGone(ctx, row, member.chat.type === "private" ? "blocked" : "left");
+		else if (PRESENT.has(status)) await markBack(ctx, row, member.chat);
+		return "handled";
+	}
+	if (update.chat_member) return "ignored";
+	const m = ctx.message;
+	if (!m) return "ignored";
+	if (m.migrate_to_chat_id !== void 0) {
+		const row = ctx.chat ?? await chatByTelegramId(ctx, m.chat.id);
+		if (row) ctx.chat = await migrateChat(ctx.rt, row, String(m.migrate_to_chat_id), ctx.now);
+		return row ? "handled" : "ignored";
+	}
+	if (m.migrate_from_chat_id !== void 0) {
+		const old = await chatByTelegramId(ctx, m.migrate_from_chat_id);
+		if (old) ctx.chat = await migrateChat(ctx.rt, old, String(m.chat.id), ctx.now);
+		return old ? "handled" : "ignored";
+	}
+	const botTgId = Number(bot.tg_bot_id);
+	if (m.left_chat_member?.id === botTgId) {
+		const row = ctx.chat;
+		if (row) await markGone(ctx, row, "left");
+		return row ? "handled" : "ignored";
+	}
+	if (m.new_chat_members?.some((u) => u.id === botTgId)) {
+		const row = ctx.chat;
+		if (row) await markBack(ctx, row, m.chat);
+		return row ? "handled" : "ignored";
+	}
+	return "ignored";
+}
+export { lifecycleHandler };

package/dist/engine/dispatch/link-chat.js

@@ -0,0 +1,31 @@
+import { sql } from "../../ports/sql.js";
+import { cancelQueuedSql } from "../chat-state.js";
+// src/engine/dispatch/link-chat.ts
+/** Inserts the chat as active, or re-links the existing row (its locale is kept). */
+function upsertChatSql(rt, id, f, now) {
+	return sql`INSERT INTO tg_chat (id, tenant, bot_id, chat_id, kind, title, username, user_id, audience_json, status,
+               locale, linked_by, linked_at, created_at, updated_at)
+             VALUES (${id}, ${rt.tenant}, ${f.botId}, ${f.chatId}, ${f.kind}, ${f.title}, ${f.username},
+               ${f.userId}, ${f.audienceJson}, 'active', ${f.locale}, ${f.linkedBy}, ${now}, ${now}, ${now})
+             ON CONFLICT (tenant, bot_id, chat_id) DO UPDATE SET
+               kind = excluded.kind, title = excluded.title, username = excluded.username,
+               user_id = excluded.user_id, audience_json = excluded.audience_json, status = 'active',
+               locale = COALESCE(tg_chat.locale, excluded.locale), linked_by = excluded.linked_by,
+               linked_at = excluded.linked_at, updated_at = excluded.updated_at`;
+}
+/**
+* Without `allowMultipleChatsPerUser`, one Telegram account per user per bot: the user's other private chats on
+* this bot are released (pending, queued messages cancelled).
+*/
+async function releaseOtherChatsSql(rt, botId, userId, keepId, now) {
+	if (rt.allowMultipleChatsPerUser) return [];
+	return (await rt.db.all(sql`SELECT id FROM tg_chat WHERE tenant = ${rt.tenant} AND bot_id = ${botId} AND kind = 'private'
+        AND user_id = ${userId} AND id != ${keepId}`)).flatMap((o) => [sql`UPDATE tg_chat SET user_id = NULL, status = 'pending', updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${o.id}`, cancelQueuedSql(rt, o.id, "chat_unlinked", now)]);
+}
+/** Display name from Telegram first / last name (≤ 128 chars), or null. */
+function displayName(first, last) {
+	const s = [first, last].filter(Boolean).join(" ").trim();
+	return s === "" ? null : s.slice(0, 128);
+}
+export { displayName, releaseOtherChatsSql, upsertChatSql };