@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/engine/dialogs/dialog.js

@@ -0,0 +1,375 @@
+import { escapeHtml } from "../../core/html/escape.js";
+import { sql } from "../../ports/sql.js";
+import { TelegramPluginError, featureDisabled } from "../errors.js";
+import { pickVariant } from "../content/render.js";
+import { hostCan } from "../content/providers.js";
+import { chatDto, parseJson } from "../rows.js";
+import { answer } from "../actions/callback.js";
+import { inboundKind, storeFailureKey, storeInbound } from "../inbound/files.js";
+import { z } from "zod";
+// src/engine/dialogs/dialog.ts
+/** `callback_data` prefix of dialog choice buttons (`d:<step>:<index>`); host buttons must not use it. */
+const DIALOG_PREFIX = "d:";
+const MAX_CHOICES = 50;
+const DialogData = z.object({
+	state: z.record(z.string(), z.unknown()).default({}),
+	files: z.array(z.object({
+		ref: z.string(),
+		name: z.string(),
+		mime: z.string(),
+		size: z.number().nullable()
+	})).default([]),
+	/** Choices offered for the current step: value + the label shown. */
+	choices: z.array(z.object({
+		v: z.string(),
+		l: z.string()
+	})).default([])
+});
+const EMPTY = {
+	state: {},
+	files: [],
+	choices: []
+};
+function text(label, locale) {
+	return typeof label === "string" ? label : pickVariant(label, [locale])?.source ?? "";
+}
+async function loadDialog(ctx) {
+	if (!ctx.chat) return null;
+	return ctx.rt.db.first(sql`SELECT * FROM tg_dialog WHERE tenant = ${ctx.rt.tenant} AND chat_ref = ${ctx.chat.id}`);
+}
+async function endDialog(ctx, row) {
+	return (await ctx.rt.db.run(sql`DELETE FROM tg_dialog WHERE tenant = ${ctx.rt.tenant} AND chat_ref = ${row.chat_ref}
+        AND updated_at = ${row.updated_at} AND step = ${row.step}`)).changes > 0;
+}
+/** Sends a step's question (choices as `d:<step>:<i>` buttons). Returns the choices offered. */
+async function askStep(ctx, step, actor, state, prefix = "") {
+	const { rt } = ctx;
+	const locale = await ctx.locale();
+	const choices = [];
+	if (step.choices) for (const c of (await step.choices({
+		actor,
+		state,
+		env: rt.env
+	})).slice(0, MAX_CHOICES)) choices.push({
+		v: String(c.value),
+		l: text(c.label, locale).slice(0, 64) || String(c.value)
+	});
+	const lines = [prefix, escapeHtml(text(step.ask, locale))];
+	if (step.input === "photo") lines.push(rt.i18n.t(locale, "bot.dialog.send_photo"));
+	if (step.input === "document") lines.push(rt.i18n.t(locale, "bot.dialog.send_document"));
+	if (step.optional) lines.push(rt.i18n.t(locale, "bot.dialog.skip_hint"));
+	lines.push(rt.i18n.t(locale, "bot.dialog.cancel_hint"));
+	const markup = choices.length > 0 ? { inline_keyboard: choices.map((c, i) => [{
+		text: c.l,
+		callback_data: `d:${step.id}:${i}`
+	}]) } : null;
+	await ctx.replyDelivery({
+		kind: "text",
+		html: lines.filter(Boolean).join("\n"),
+		replyMarkup: markup
+	});
+	return choices;
+}
+/** Who answers a dialog: the chat's linked user (private) or the sender's own linked account (groups). */
+async function starter(ctx) {
+	if (ctx.chat?.kind === "private") {
+		const actor = await ctx.actor();
+		return actor === null ? null : {
+			actor,
+			userId: ctx.chat.user_id
+		};
+	}
+	return ctx.senderActor();
+}
+/** `ctx.startDialog(key, state?)`: steps already present in `state` are skipped. */
+async function startDialog(ctx, key, initial = {}) {
+	const { rt } = ctx;
+	if (!rt.features.dialogs) throw featureDisabled("dialogs");
+	const def = rt.registry.dialogs.get(key);
+	if (!def) throw new TelegramPluginError("validation_failed", `dialog "${key}" is not registered`);
+	const chat = ctx.chat;
+	const who = chat?.status === "active" ? await starter(ctx) : null;
+	if (!chat || !who) {
+		await ctx.reply(await ctx.t("bot.error.not_linked"));
+		return;
+	}
+	if (!await hostCan(rt, who.actor, def.permission)) {
+		await ctx.reply(await ctx.t("bot.error.forbidden"));
+		return;
+	}
+	const state = { ...initial };
+	const first = def.steps.find((s) => !Object.hasOwn(state, s.id));
+	if (!first) {
+		await finish(ctx, def, who.actor, {
+			state,
+			files: [],
+			choices: []
+		});
+		return;
+	}
+	const now = rt.clock.now();
+	const placeholder = JSON.stringify({
+		state,
+		files: [],
+		choices: []
+	});
+	await rt.db.run(sql`INSERT INTO tg_dialog (tenant, chat_ref, dialog, user_id, step, state_json, expires_at, started_at, updated_at)
+        VALUES (${rt.tenant}, ${chat.id}, ${def.key}, ${who.userId}, ${first.id}, ${placeholder},
+                ${now + def.timeoutMinutes * 6e4}, ${now}, ${now})
+        ON CONFLICT (tenant, chat_ref) DO UPDATE SET dialog = excluded.dialog, user_id = excluded.user_id,
+          step = excluded.step, state_json = excluded.state_json, expires_at = excluded.expires_at,
+          started_at = excluded.started_at, updated_at = excluded.updated_at`);
+	const choices = await askStep(ctx, first, who.actor, state);
+	if (choices.length > 0) await rt.db.run(sql`UPDATE tg_dialog SET state_json = ${JSON.stringify({
+		state,
+		files: [],
+		choices
+	})}
+          WHERE tenant = ${rt.tenant} AND chat_ref = ${chat.id} AND step = ${first.id} AND updated_at = ${now}`);
+	rt.log.info("tg.dialog", {
+		botId: ctx.bot.id,
+		dialog: def.key,
+		outcome: "started"
+	});
+}
+async function finish(ctx, def, starterActor, data) {
+	const { rt } = ctx;
+	const locale = await ctx.locale();
+	const chat = ctx.chat;
+	if (!chat) return;
+	try {
+		const out = await def.finish({
+			actor: starterActor,
+			state: data.state,
+			files: data.files,
+			chat: chatDto(chat),
+			locale,
+			db: rt.db,
+			now: ctx.now,
+			env: rt.env
+		});
+		const reply = z.looseObject({ text: z.string() }).safeParse(out);
+		await ctx.reply(reply.success ? reply.data.text : rt.i18n.t(locale, "bot.dialog.done"));
+		rt.log.info("tg.dialog", {
+			botId: ctx.bot.id,
+			dialog: def.key,
+			outcome: "finished"
+		});
+	} catch (e) {
+		rt.log.warn("tg.dialog_failed", {
+			botId: ctx.bot.id,
+			dialog: def.key,
+			error: e instanceof Error ? e.name : "error"
+		});
+		await ctx.reply(rt.i18n.t(locale, "bot.dialog.failed"));
+	}
+}
+/** Saves the answer and asks the next step, or finishes. */
+async function advance(ctx, def, row, data) {
+	const { rt } = ctx;
+	const actor = row.user_id ? await rt.actor.forUser(row.user_id) : await ctx.actor();
+	if (actor === null || !await hostCan(rt, actor, def.permission)) {
+		await endDialog(ctx, row);
+		await ctx.reply(await ctx.t("bot.error.forbidden"));
+		return "handled";
+	}
+	const index = def.steps.findIndex((s) => s.id === row.step);
+	const next = def.steps.slice(index + 1).find((s) => !Object.hasOwn(data.state, s.id));
+	if (!next) {
+		if (await endDialog(ctx, row)) await finish(ctx, def, actor, data);
+		return "handled";
+	}
+	const now = rt.clock.now();
+	if ((await rt.db.run(sql`UPDATE tg_dialog SET step = ${next.id}, state_json = ${JSON.stringify({
+		...data,
+		choices: []
+	})},
+          expires_at = ${now + def.timeoutMinutes * 6e4}, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND chat_ref = ${row.chat_ref} AND step = ${row.step}
+          AND updated_at = ${row.updated_at}`)).changes === 0) return "handled";
+	const choices = await askStep(ctx, next, actor, data.state);
+	if (choices.length > 0) await rt.db.run(sql`UPDATE tg_dialog SET state_json = ${JSON.stringify({
+		...data,
+		choices
+	})}
+          WHERE tenant = ${rt.tenant} AND chat_ref = ${row.chat_ref} AND step = ${next.id} AND updated_at = ${now}`);
+	return "handled";
+}
+function acceptText(step, input, choices) {
+	const raw = input.trim();
+	if (step.input === "photo") return {
+		ok: false,
+		key: "bot.dialog.send_photo"
+	};
+	if (step.input === "document") return {
+		ok: false,
+		key: "bot.dialog.send_document"
+	};
+	let value = raw;
+	if (choices.length > 0) {
+		const lower = raw.toLowerCase();
+		const hit = choices.find((c) => c.v === raw || c.l.toLowerCase() === lower);
+		if (!hit) return {
+			ok: false,
+			key: "bot.dialog.pick_choice"
+		};
+		value = hit.v;
+	}
+	if (step.input === "text") return raw === "" ? {
+		ok: false,
+		key: "bot.dialog.invalid"
+	} : {
+		ok: true,
+		value
+	};
+	const parsed = step.input.safeParse(value);
+	return parsed.success ? {
+		ok: true,
+		value: parsed.data
+	} : {
+		ok: false,
+		key: "bot.dialog.invalid"
+	};
+}
+async function reask(ctx, step, row, key) {
+	const actor = row.user_id ? await ctx.rt.actor.forUser(row.user_id) : await ctx.actor();
+	if (actor === null) return;
+	await askStep(ctx, step, actor, parseJson(row.state_json, DialogData, EMPTY).state, await ctx.t(key));
+}
+async function dialogHandler(ctx) {
+	const { rt } = ctx;
+	if (!rt.features.dialogs || ctx.chat?.status !== "active") return "next";
+	const q = ctx.update.callback_query;
+	const isChoice = ctx.cls === "callback" && q?.data?.startsWith("d:") === true;
+	if (ctx.cls !== "command" && ctx.cls !== "text" && ctx.cls !== "media" && !isChoice) return "next";
+	const cmd = ctx.cls === "command" ? ctx.command : null;
+	if (cmd?.mentionedOther) return "next";
+	const row = await loadDialog(ctx);
+	if (!row) {
+		if (cmd?.command === "cancel" || cmd?.command === "skip") {
+			await ctx.reply(await ctx.t("bot.dialog.nothing"));
+			return "handled";
+		}
+		return "next";
+	}
+	if (ctx.chat.kind !== "private" && row.user_id !== null) {
+		if ((await ctx.senderActor())?.userId !== row.user_id) {
+			if (isChoice) {
+				await answer(ctx, rt.i18n.plain(await ctx.locale(), "bot.action.not_yours"));
+				return "handled";
+			}
+			return "next";
+		}
+	}
+	const def = rt.registry.dialogs.get(row.dialog);
+	const step = def?.steps.find((s) => s.id === row.step);
+	if (!def || !step) {
+		await endDialog(ctx, row);
+		return "next";
+	}
+	if (row.expires_at <= rt.clock.now()) {
+		await endDialog(ctx, row);
+		if (cmd && cmd.command !== "cancel" && cmd.command !== "skip") return "next";
+		if (isChoice) await answer(ctx, rt.i18n.plain(await ctx.locale(), "bot.dialog.timeout"));
+		else await ctx.reply(await ctx.t("bot.dialog.timeout"));
+		return "handled";
+	}
+	const data = parseJson(row.state_json, DialogData, EMPTY);
+	if (cmd) {
+		if (cmd.command === "cancel") {
+			await endDialog(ctx, row);
+			await ctx.reply(await ctx.t("bot.dialog.cancelled"));
+			rt.log.info("tg.dialog", {
+				botId: ctx.bot.id,
+				dialog: def.key,
+				outcome: "cancelled"
+			});
+			return "handled";
+		}
+		if (cmd.command === "skip") {
+			if (!step.optional) {
+				await ctx.reply(await ctx.t("bot.dialog.required"));
+				return "handled";
+			}
+			return advance(ctx, def, row, data);
+		}
+		await endDialog(ctx, row);
+		rt.log.info("tg.dialog", {
+			botId: ctx.bot.id,
+			dialog: def.key,
+			outcome: "interrupted"
+		});
+		return "next";
+	}
+	if (isChoice && q?.data) {
+		const [stepId, idx] = q.data.slice(2).split(":");
+		const choice = stepId === step.id ? data.choices[Number(idx)] : void 0;
+		if (!choice) {
+			await answer(ctx, rt.i18n.plain(await ctx.locale(), "bot.action.expired"));
+			return "handled";
+		}
+		await answer(ctx, choice.l);
+		const accepted = acceptText(step, choice.v, data.choices);
+		if (!accepted.ok) {
+			await reask(ctx, step, row, accepted.key);
+			return "handled";
+		}
+		return advance(ctx, def, row, {
+			...data,
+			state: {
+				...data.state,
+				[step.id]: accepted.value
+			}
+		});
+	}
+	if (ctx.cls === "media") {
+		const kind = inboundKind(ctx.message);
+		const mime = ctx.message?.document?.mime_type ?? "";
+		if (!(step.input === "photo" && (kind === "photo" || mime.startsWith("image/")) || step.input === "document" && kind === "document")) {
+			await reask(ctx, step, row, "bot.dialog.invalid");
+			return "handled";
+		}
+		const actor = row.user_id ? await rt.actor.forUser(row.user_id) : await ctx.actor();
+		if (actor === null) {
+			await endDialog(ctx, row);
+			await ctx.reply(await ctx.t("bot.error.forbidden"));
+			return "handled";
+		}
+		const stored = await storeInbound(ctx, actor, {
+			source_kind: "dialog",
+			dialog: def.key,
+			step: step.id
+		});
+		if (!stored.ok) {
+			await reask(ctx, step, row, storeFailureKey(stored.reason));
+			return "handled";
+		}
+		const { ref, name, mime: fileMime, size } = stored.file;
+		return advance(ctx, def, row, {
+			...data,
+			state: {
+				...data.state,
+				[step.id]: ref
+			},
+			files: [...data.files, {
+				ref,
+				name,
+				mime: fileMime,
+				size
+			}]
+		});
+	}
+	const accepted = acceptText(step, ctx.message?.text ?? "", data.choices);
+	if (!accepted.ok) {
+		await reask(ctx, step, row, accepted.key);
+		return "handled";
+	}
+	return advance(ctx, def, row, {
+		...data,
+		state: {
+			...data.state,
+			[step.id]: accepted.value
+		}
+	});
+}
+export { DIALOG_PREFIX, dialogHandler, startDialog };

package/dist/engine/dispatch/builtins.js

@@ -0,0 +1,198 @@
+import { ChatTopics } from "../../contracts/chats.js";
+import { escapeHtml } from "../../core/html/escape.js";
+import { sql } from "../../ports/sql.js";
+import { parseJson } from "../rows.js";
+import { commandRows, describe, effectiveCommands } from "../../services/commands.js";
+import { commandAllowed } from "./commands.js";
+import { hostContext, senderMayAct } from "./context.js";
+// src/engine/dispatch/builtins.ts
+/** Built-in menu entries per chat kind (descriptions: `bot.cmd.<name>`). Phase 3 adds host commands. */
+const BUILTIN_MENU = {
+	private: [
+		"start",
+		"help",
+		"stop",
+		"settings",
+		"whoami",
+		"language"
+	],
+	group: ["help", "whoami"]
+};
+/** Built-ins that work for this runtime: without features.commands only /start and /help. */
+function builtinMenu(rt, kind) {
+	return rt.features.commands ? BUILTIN_MENU[kind] : BUILTIN_MENU[kind].filter((c) => c === "start" || c === "help");
+}
+function isGroupKind(type) {
+	return type === "group" || type === "supergroup";
+}
+/** Help for this chat: built-ins plus registered commands the actor may use. */
+async function helpText(ctx) {
+	const { rt } = ctx;
+	const locale = await ctx.locale();
+	const isPrivate = ctx.tgChat?.type === "private";
+	if (isPrivate && ctx.chat?.status !== "active") return rt.i18n.t(locale, "bot.start.unlinked");
+	const lines = [];
+	for (const name of builtinMenu(rt, isPrivate ? "private" : "group")) lines.push(`/${name} — ${rt.i18n.t(locale, `bot.cmd.${name}`)}`);
+	const actor = await ctx.actor();
+	if (rt.features.commands && actor !== null) {
+		if (rt.features.reports && await senderMayAct(ctx)) lines.push(`/report — ${rt.i18n.t(locale, "bot.cmd.report")}`);
+		const kind = ctx.tgChat?.type ?? "private";
+		for (const c of effectiveCommands(rt, await commandRows(rt, ctx.bot.id))) {
+			if (!c.enabled || !c.showInMenu || !c.def.scope.includes(kind)) continue;
+			if (!await senderMayAct(ctx, c.def.groupMembers)) continue;
+			if (!await commandAllowed(ctx, c, actor)) continue;
+			lines.push(`/${c.def.command} — ${escapeHtml(describe(c.description, locale))}`);
+		}
+	}
+	return lines.length === 0 ? rt.i18n.t(locale, "bot.help.none") : `${rt.i18n.t(locale, "bot.help.header")}\n${lines.join("\n")}`;
+}
+async function isMuted(ctx, chatRef) {
+	return (await ctx.rt.db.first(sql`SELECT muted FROM tg_subscription WHERE tenant = ${ctx.rt.tenant} AND chat_ref = ${chatRef} AND topic = '*'`))?.muted === 1;
+}
+function languageName(ctx, locale, code) {
+	const key = `bot.language.names.${code}`;
+	const name = ctx.rt.i18n.plain(locale, key);
+	return name === key ? code : name;
+}
+async function onHere(ctx) {
+	const { rt } = ctx;
+	const chat = ctx.chat;
+	const thread = ctx.message?.message_thread_id;
+	const name = (ctx.command?.argsText ?? "").trim().slice(0, 128);
+	if (chat?.status !== "active" || !isGroupKind(ctx.tgChat?.type) || thread === void 0 || name === "") {
+		await ctx.reply(await ctx.t("bot.here.not_topic"));
+		return "handled";
+	}
+	const sender = await ctx.senderActor();
+	if (!sender || !await rt.can(sender.actor, "telegram.chats.manage")) {
+		await ctx.reply(await ctx.t("bot.error.forbidden"));
+		return "handled";
+	}
+	const topics = {
+		...parseJson(chat.topics_json, ChatTopics, {}),
+		[name]: thread
+	};
+	await rt.db.batch([sql`UPDATE tg_chat SET topics_json = ${JSON.stringify(topics)}, updated_at = ${ctx.now}
+        WHERE tenant = ${rt.tenant} AND id = ${chat.id}`, ...rt.audit({
+		actor: sender.userId,
+		entity: "telegram_chat",
+		entityId: chat.id,
+		action: "topic",
+		diff: { topic: name },
+		at: ctx.now
+	})]);
+	ctx.chat = {
+		...chat,
+		topics_json: JSON.stringify(topics)
+	};
+	await ctx.reply(await ctx.t("bot.here.saved", { name }));
+	return "handled";
+}
+/** Commands that work in any chat state: /help, /whoami, /here. The rest need a linked chat. */
+async function builtinsHandler(ctx) {
+	const cmd = ctx.command;
+	if (ctx.cls !== "command" || !cmd || cmd.mentionedOther) return "next";
+	const { rt } = ctx;
+	const chat = ctx.chat;
+	const linked = chat?.status === "active";
+	const isPrivate = ctx.tgChat?.type === "private";
+	if (cmd.command === "here") return onHere(ctx);
+	if (!rt.features.commands && cmd.command !== "help") return "next";
+	switch (cmd.command) {
+		case "help":
+			await ctx.reply(await helpText(ctx));
+			return "handled";
+		case "whoami": {
+			const info = linked ? await ctx.actorInfo() : null;
+			if (!info || !chat) {
+				await ctx.reply(await ctx.t("bot.whoami.unlinked"));
+				return "handled";
+			}
+			const name = isPrivate ? info.name ?? "" : chat.title ?? "";
+			await ctx.reply(await ctx.t("bot.whoami.linked", {
+				name,
+				role: info.role ?? ""
+			}));
+			return "handled";
+		}
+		case "stop":
+		case "settings":
+		case "language": break;
+		default: return "next";
+	}
+	if (!linked || !chat) {
+		if (isPrivate) await ctx.reply(await ctx.t("bot.start.unlinked"));
+		return isPrivate ? "handled" : "ignored";
+	}
+	if (!isPrivate && cmd.command !== "settings") {
+		const sender = await ctx.senderActor();
+		if (!sender || !await rt.can(sender.actor, "telegram.chats.manage")) {
+			await ctx.reply(await ctx.t("bot.error.forbidden"));
+			return "handled";
+		}
+	}
+	const locale = await ctx.locale();
+	if (cmd.command === "stop") {
+		await rt.db.run(sql`INSERT INTO tg_subscription (tenant, chat_ref, topic, muted, quiet_json, updated_at)
+          VALUES (${rt.tenant}, ${chat.id}, '*', 1, NULL, ${ctx.now})
+          ON CONFLICT (tenant, chat_ref, topic) DO UPDATE SET muted = 1, updated_at = excluded.updated_at`);
+		rt.log.info("tg.muted", {
+			botId: ctx.bot.id,
+			chatRef: chat.id
+		});
+		await ctx.reply(rt.i18n.t(locale, "bot.stop.done"));
+		return "handled";
+	}
+	if (cmd.command === "settings") {
+		const muted = await isMuted(ctx, chat.id);
+		const state = rt.i18n.plain(locale, muted ? "bot.settings.muted" : "bot.settings.unmuted");
+		await ctx.reply([
+			rt.i18n.t(locale, "bot.settings.header"),
+			rt.i18n.t(locale, "bot.settings.all", { state }),
+			rt.i18n.t(locale, "bot.settings.language", { language: languageName(ctx, locale, locale) })
+		].join("\n"));
+		return "handled";
+	}
+	const wanted = cmd.args[0];
+	if (!wanted) {
+		const list = rt.i18n.locales.map((l) => `/language ${l} — ${escapeHtml(languageName(ctx, locale, l))}`);
+		await ctx.reply(`${rt.i18n.t(locale, "bot.language.choose")}\n${list.join("\n")}`);
+		return "handled";
+	}
+	const match = rt.i18n.match(wanted.toLowerCase());
+	if (!match) {
+		await ctx.reply(rt.i18n.t(locale, "bot.language.unknown", { list: rt.i18n.locales.join(", ") }));
+		return "handled";
+	}
+	await rt.db.run(sql`UPDATE tg_chat SET locale = ${match}, updated_at = ${ctx.now} WHERE tenant = ${rt.tenant} AND id = ${chat.id}`);
+	ctx.chat = {
+		...chat,
+		locale: match
+	};
+	await ctx.reply(rt.i18n.t(match, "bot.language.set"));
+	return "handled";
+}
+/** Last stop: unknown commands get a hint (groups only when addressed to this bot); other text is ignored. */
+async function fallbackHandler(ctx) {
+	const isPrivate = ctx.tgChat?.type === "private";
+	const cmd = ctx.command;
+	if (ctx.cls === "command" && cmd && !cmd.mentionedOther) {
+		if (!isPrivate && cmd.mention === null) return "ignored";
+		if (isPrivate && ctx.chat?.status !== "active") {
+			await ctx.reply(await ctx.t("bot.start.unlinked"));
+			return "handled";
+		}
+		if (ctx.rt.hooks.onUnknownCommand) {
+			const host = await hostContext(ctx, ctx.message?.text ?? "");
+			await ctx.rt.hook("onUnknownCommand", (fn) => fn(host));
+		}
+		await ctx.reply(await ctx.t("bot.error.unknown_command"));
+		return "handled";
+	}
+	if (isPrivate && (ctx.cls === "text" || ctx.cls === "media")) {
+		await ctx.reply(await ctx.t(ctx.chat?.status === "active" ? "bot.error.unknown_command" : "bot.start.unlinked"));
+		return "handled";
+	}
+	return "ignored";
+}
+export { BUILTIN_MENU, builtinMenu, builtinsHandler, fallbackHandler, helpText };