@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/engine/actions/callback.js

@@ -0,0 +1,256 @@
+import { shortId } from "../../core/random.js";
+import { sql } from "../../ports/sql.js";
+import { pickVariant, renderInline } from "../content/render.js";
+import { hostCan } from "../content/providers.js";
+import { settle } from "../../telegram/classify.js";
+import { withToken } from "../bot-api.js";
+import { botDto, chatDto, parseJson } from "../rows.js";
+import { z } from "zod";
+// src/engine/actions/callback.ts
+const Markup = z.looseObject({ inline_keyboard: z.array(z.array(z.looseObject({ text: z.string() }))) });
+const ActionResultShape = z.looseObject({
+	text: z.string().optional(),
+	sql: z.array(z.unknown()).optional()
+});
+/**
+* Cuts text to at most `max` UTF-16 code units without splitting a grapheme (emoji, combined Devanagari) or a
+* surrogate pair. Uses `Intl.Segmenter` when available, else whole code points.
+*/
+function cutText(text, max = 200) {
+	if (text.length <= max) return text;
+	const pieces = typeof Intl.Segmenter === "function" ? Array.from(new Intl.Segmenter(void 0, { granularity: "grapheme" }).segment(text), (s) => s.segment) : Array.from(text);
+	let out = "";
+	for (const p of pieces) {
+		if (out.length + p.length > max) break;
+		out += p;
+	}
+	return out;
+}
+/** `answerCallbackQuery`, sent directly (never through the outbox), text cut to 200 chars (grapheme-safe). */
+async function answer(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 });
+	});
+}
+async function say(ctx, key) {
+	await answer(ctx, ctx.rt.i18n.plain(await ctx.locale(), key));
+	return "handled";
+}
+/** The keyboard the tapped message had: from the update, else from the delivery row that sent it. */
+async function originalMarkup(ctx, fromDelivery) {
+	const msg = ctx.update.callback_query?.message;
+	if (!msg || !ctx.chat) return null;
+	if (!fromDelivery) {
+		const live = Markup.safeParse(msg.reply_markup);
+		if (live.success) return live.data;
+	}
+	const row = await ctx.rt.db.first(sql`SELECT reply_markup_json FROM tg_delivery WHERE tenant = ${ctx.rt.tenant} AND chat_ref = ${ctx.chat.id}
+        AND tg_message_id = ${msg.message_id} AND reply_markup_json IS NOT NULL ORDER BY part DESC LIMIT 1`);
+	const parsed = Markup.safeParse(parseJson(row?.reply_markup_json ?? null, z.unknown(), null));
+	return parsed.success ? parsed.data : null;
+}
+async function editMarkup(ctx, markup) {
+	const msg = ctx.update.callback_query?.message;
+	if (!msg || msg.date === 0) return false;
+	return withToken(ctx.rt, ctx.bot, async (api) => {
+		const r = await settle(api.editMessageReplyMarkup({
+			chat_id: msg.chat.id,
+			message_id: msg.message_id,
+			...markup ? { reply_markup: markup } : {}
+		}));
+		if (r.outcome.kind !== "ok") ctx.rt.log.debug("tg.callback_edit_failed", { code: r.outcome.reason ?? r.outcome.kind });
+		return r.outcome.kind === "ok";
+	});
+}
+const isCallback = (b) => "callback_data" in b;
+/** Every callback button disabled; the tapped one shows the result. Fallback: no keyboard. */
+async function finishKeyboard(ctx, tokenId, label, original) {
+	if (original) {
+		if (await editMarkup(ctx, { inline_keyboard: original.inline_keyboard.map((row) => row.map((b) => {
+			if (!isCallback(b)) return b;
+			const mine = b.callback_data === `a:${tokenId}`;
+			return {
+				...b,
+				...mine ? { text: `✓ ${label}`.slice(0, 64) } : {},
+				disabled: true
+			};
+		})) })) return;
+	}
+	await editMarkup(ctx, null);
+}
+function localized(ctx, text, locale, vars) {
+	const src = pickVariant(text, [locale])?.source ?? "";
+	try {
+		return renderInline(ctx.rt, src, vars, {
+			locale,
+			tz: ctx.chat?.timezone ?? ctx.rt.settings.timezone
+		});
+	} catch {
+		return src;
+	}
+}
+/** Who may tap: the token's user (private chats), or in groups any member whose own linked account may run it. */
+async function tapper(ctx, token) {
+	const sender = await ctx.senderActor();
+	if (token.user_id !== null) {
+		if (!sender) return ctx.chat?.kind === "private" ? "not_yours" : "unlinked";
+		return sender.userId === token.user_id ? sender.actor : "not_yours";
+	}
+	return sender ? sender.actor : "unlinked";
+}
+/** How long a tap holds a single-use token while the host action runs. A crashed run frees it after this. */
+const ACTION_LEASE_MS = 6e4;
+const LEASE = "~lease:";
+/** `~lease:<15-digit expiry>:<nonce>` in `tg_action_token.result` while a tap runs (no extra column). */
+function leaseValue(until, nonce) {
+	return `${LEASE}${String(until).padStart(15, "0")}:${nonce}`;
+}
+/** A live lease on the token: another tap is running it right now. */
+function leaseActive(result, now) {
+	if (!result?.startsWith(LEASE)) return false;
+	return Number(result.slice(7, 22)) > now;
+}
+/** The `a:<id>` tokens of the other callback buttons on the same message (siblings of the tapped one). */
+function siblingTokenIds(markup, tokenId) {
+	if (!markup) return [];
+	const ids = /* @__PURE__ */ new Set();
+	for (const row of markup.inline_keyboard) for (const b of row) {
+		if (!isCallback(b) || !b.callback_data.startsWith("a:")) continue;
+		const id = b.callback_data.slice(2).split(":")[0] ?? "";
+		if (id !== tokenId && /^[A-Za-z0-9]{10}$/.test(id)) ids.add(id);
+	}
+	return [...ids];
+}
+/**
+* Single-use flow: (1) lease the token (`used_at IS NULL`, no live lease), so two quick taps never run the action
+* at the same time; (2) run the host action; (3) ONE batch: a guard that aborts the batch when the lease was lost,
+* the token marked used, sibling tokens of the same message expired, and the host's `sql`. So the token claim and
+* the host's SQL commit together: a crash before (3) leaves both undone and the lease frees the token again after
+* `ACTION_LEASE_MS`. Actions that write on their own inside `run` (no returned `sql`) are at-least-once: a crash
+* between their write and (3) lets a later tap run them again, so make those writes idempotent.
+*/
+async function runAction(ctx, def, token, actor, params) {
+	const { rt } = ctx;
+	const now = rt.clock.now();
+	const locale = await ctx.locale();
+	const chat = ctx.chat;
+	if (!chat) return say(ctx, "bot.action.expired");
+	const single = token.single_use === 1;
+	const lease = leaseValue(now + ACTION_LEASE_MS, shortId(rt.rand, 10));
+	if (single) {
+		if (!await rt.db.first(sql`UPDATE tg_action_token SET result = ${lease} WHERE tenant = ${rt.tenant} AND id = ${token.id}
+          AND used_at IS NULL AND (result IS NULL OR result NOT LIKE '~lease:%'
+            OR CAST(substr(result, 8, 15) AS INTEGER) <= ${now})
+          RETURNING id`)) return say(ctx, "bot.action.used");
+	}
+	const original = await originalMarkup(ctx, false);
+	const siblings = siblingTokenIds(original, token.id);
+	let result = {};
+	try {
+		const out = await def.run({
+			actor,
+			params,
+			chat: chatDto(chat),
+			bot: botDto(ctx.bot),
+			locale,
+			now,
+			db: rt.db,
+			env: rt.env
+		});
+		const shaped = ActionResultShape.safeParse(out);
+		if (shaped.success) result = shaped.data;
+		const label = def.result ? localized(ctx, def.result, locale, params) : rt.i18n.plain(locale, "bot.action.done");
+		const guardKey = `actguard:${token.id}`;
+		await rt.db.batch([
+			...single ? [sql`INSERT INTO tg_state (tenant, key, value, updated_at) VALUES (${rt.tenant}, ${guardKey},
+                (SELECT id FROM tg_action_token WHERE tenant = ${rt.tenant} AND id = ${token.id}
+                   AND used_at IS NULL AND result = ${lease}), ${now})`, sql`DELETE FROM tg_state WHERE tenant = ${rt.tenant} AND key = ${guardKey}`] : [],
+			sql`UPDATE tg_action_token SET used_at = ${now}, result = ${cutText(label)}
+          WHERE tenant = ${rt.tenant} AND id = ${token.id}`,
+			...siblings.length > 0 ? [sql`UPDATE tg_action_token SET used_at = COALESCE(used_at, ${now}), expires_at = MIN(expires_at, ${now}),
+                  result = COALESCE(result, 'superseded')
+                WHERE tenant = ${rt.tenant} AND bot_id = ${ctx.bot.id} AND chat_ref = ${chat.id}
+                  AND id IN (${sql.join(siblings)})`] : [],
+			...result.sql ?? []
+		]);
+		rt.log.info("tg.action", {
+			botId: ctx.bot.id,
+			action: def.key,
+			outcome: "done"
+		});
+		await answer(ctx, label);
+		await finishKeyboard(ctx, token.id, label, original);
+		if (result.text) await ctx.reply(result.text);
+	} catch (e) {
+		rt.log.warn("tg.action_failed", {
+			botId: ctx.bot.id,
+			action: def.key,
+			error: e instanceof Error ? e.name : "error"
+		});
+		if (single) await rt.db.run(sql`UPDATE tg_action_token SET result = NULL WHERE tenant = ${rt.tenant} AND id = ${token.id}
+              AND used_at IS NULL AND result = ${lease}`).catch(() => {});
+		await answer(ctx, rt.i18n.plain(locale, "bot.action.failed"));
+	}
+	return "handled";
+}
+/** First tap of a confirm action: the tapped button becomes Confirm (green) + Cancel (red). */
+async function askConfirm(ctx, def, token, params) {
+	const { rt } = ctx;
+	const locale = await ctx.locale();
+	const now = rt.clock.now();
+	await rt.db.run(sql`UPDATE tg_action_token SET confirmed_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${token.id}
+        AND used_at IS NULL`);
+	const data = `a:${token.id}`;
+	const confirm = [{
+		text: rt.i18n.plain(locale, "bot.action.confirm_button"),
+		callback_data: data,
+		style: "success"
+	}, {
+		text: rt.i18n.plain(locale, "bot.action.cancel_button"),
+		callback_data: `${data}:x`,
+		style: "danger"
+	}];
+	const original = await originalMarkup(ctx, false);
+	await editMarkup(ctx, { inline_keyboard: original ? original.inline_keyboard.flatMap((row) => row.some((b) => isCallback(b) && b.callback_data === data) ? [confirm] : [row.map((b) => isCallback(b) ? {
+		...b,
+		disabled: true
+	} : b)]) : [confirm] });
+	await answer(ctx, (def.confirm ? localized(ctx, def.confirm, locale, params) : "") || rt.i18n.plain(locale, "bot.action.confirm"));
+	return "handled";
+}
+async function cancelConfirm(ctx, token) {
+	const { rt } = ctx;
+	await rt.db.run(sql`UPDATE tg_action_token SET confirmed_at = NULL WHERE tenant = ${rt.tenant} AND id = ${token.id}
+        AND used_at IS NULL`);
+	await editMarkup(ctx, await originalMarkup(ctx, true));
+	return say(ctx, "bot.action.cancelled");
+}
+async function actionCallback(ctx, data) {
+	const { rt } = ctx;
+	if (!rt.features.actions) return say(ctx, "bot.action.expired");
+	const cancel = data.endsWith(":x");
+	const id = data.slice(2, cancel ? -2 : void 0);
+	if (!/^[A-Za-z0-9]{10}$/.test(id)) return say(ctx, "bot.action.expired");
+	const token = await rt.db.first(sql`SELECT * FROM tg_action_token WHERE tenant = ${rt.tenant} AND id = ${id} AND bot_id = ${ctx.bot.id}`);
+	const now = rt.clock.now();
+	if (!token || token.expires_at <= now || !ctx.chat || token.chat_ref !== ctx.chat.id || ctx.chat.status !== "active") return say(ctx, "bot.action.expired");
+	if (token.single_use === 1 && (token.used_at !== null || leaseActive(token.result, now))) return say(ctx, "bot.action.used");
+	const def = rt.registry.actions.get(token.action);
+	if (!def) return say(ctx, "bot.action.expired");
+	const who = await tapper(ctx, token);
+	if (who === "unlinked") return say(ctx, "bot.action.link_first");
+	if (who === "not_yours") return say(ctx, "bot.action.not_yours");
+	if (!await hostCan(rt, who, def.permission)) return say(ctx, "bot.error.forbidden");
+	const params = def.params.safeParse(parseJson(token.params_json, z.unknown(), {}));
+	if (!params.success) return say(ctx, "bot.action.expired");
+	if (cancel) return cancelConfirm(ctx, token);
+	if (def.confirm !== null && token.confirmed_at === null) return askConfirm(ctx, def, token, params.data);
+	return runAction(ctx, def, token, who, params.data);
+}
+export { ACTION_LEASE_MS, actionCallback, answer, cutText, leaseActive };

package/dist/engine/actions/tokens.d.ts

@@ -0,0 +1,2 @@
+/** `callback_data` prefix of action buttons (`a:<token id>`); host buttons must not use it. */
+export declare const ACTION_PREFIX = "a:";

package/dist/engine/actions/tokens.js

@@ -0,0 +1,51 @@
+import { shortId } from "../../core/random.js";
+import { sql } from "../../ports/sql.js";
+import { renderInline } from "../content/render.js";
+// src/engine/actions/tokens.ts
+/** `callback_data` prefix of action buttons (`a:<token id>`); host buttons must not use it. */
+const ACTION_PREFIX = "a:";
+/** Renders `{{vars}}` inside string params (deep), so `{ key: "{{key}}" }` becomes the record key. */
+function renderParams(rt, value, ctx) {
+	if (typeof value === "string") return value.includes("{{") ? renderInline(rt, value, ctx.vars, {
+		locale: ctx.locale,
+		tz: ctx.tz
+	}) : value;
+	if (Array.isArray(value)) return value.map((v) => renderParams(rt, v, ctx));
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, renderParams(rt, v, ctx)]));
+	return value;
+}
+async function actionButton(rt, spec, text, ctx) {
+	if (!rt.features.actions || spec.action === void 0 || ctx.chatRef === null) return null;
+	const def = rt.registry.actions.get(spec.action);
+	if (!def) {
+		rt.log.warn("tg.action_unknown", { action: spec.action });
+		return null;
+	}
+	let params;
+	try {
+		params = renderParams(rt, spec.params ?? {}, ctx);
+	} catch {
+		rt.log.warn("tg.action_params_invalid", { action: def.key });
+		return null;
+	}
+	const parsed = def.params.safeParse(params);
+	if (!parsed.success) {
+		rt.log.warn("tg.action_params_invalid", { action: def.key });
+		return null;
+	}
+	const id = shortId(rt.rand, 10);
+	const expires = ctx.now + def.ttlMinutes * 6e4;
+	return {
+		button: {
+			text,
+			callback_data: `a:${id}`,
+			...spec.style ? { style: spec.style } : {},
+			...spec.disabled ? { disabled: true } : {}
+		},
+		sql: [sql`INSERT INTO tg_action_token (id, tenant, bot_id, action, params_json, chat_ref, user_id, single_use,
+            expires_at, created_at)
+          VALUES (${id}, ${rt.tenant}, ${ctx.botId}, ${def.key}, ${JSON.stringify(parsed.data ?? {})}, ${ctx.chatRef},
+                  ${ctx.userId}, ${def.singleUse}, ${expires}, ${ctx.now})`]
+	};
+}
+export { ACTION_PREFIX, actionButton };

package/dist/engine/bot-api.js

@@ -0,0 +1,20 @@
+import { sql } from "../ports/sql.js";
+// src/engine/bot-api.ts
+/** Keyring AAD for `tg_bot.token_enc`: binds the ciphertext to its row and column (never swappable). */
+const tokenAad = (botId) => `tg_bot.token:${botId}`;
+/** Keyring AAD for `tg_bot.webhook_secret_enc`. */
+const webhookAad = (botId) => `tg_bot.webhook:${botId}`;
+/** Runs `fn` with a Bot API handle for one bot. The token is decrypted per request (AAD = `tokenAad`), never kept. */
+function withToken(rt, bot, fn) {
+	return rt.tg.withToken(() => rt.keyring.decrypt(bot.token_enc, tokenAad(bot.id)), fn);
+}
+/** A bot of this tenant (deleted bots only with `includeDeleted`). */
+async function loadBot(rt, id, opts = {}) {
+	return rt.db.first(sql`SELECT * FROM tg_bot WHERE tenant = ${rt.tenant} AND id = ${id}
+        ${opts.includeDeleted ? sql.empty : sql`AND deleted_at IS NULL`}`);
+}
+/** Bots that can send and receive (not disabled / deleted / invalid). */
+function isBotUsable(bot) {
+	return bot.deleted_at === null && (bot.status === "active" || bot.status === "webhook_error");
+}
+export { isBotUsable, loadBot, tokenAad, webhookAad, withToken };

package/dist/engine/bot-features.js

@@ -0,0 +1,39 @@
+import { FEATURE_KEYS } from "../contracts/features.js";
+import { BotFeatures } from "../contracts/bots.js";
+import { TelegramPluginError } from "./errors.js";
+import { parseJson } from "./rows.js";
+// src/engine/bot-features.ts
+/** Global flags narrowed by one bot's overrides. */
+function effectiveFeatures(global, overrides) {
+	const out = { ...global };
+	for (const k of FEATURE_KEYS) {
+		if (k === "core") continue;
+		out[k] = global[k] && overrides[k] !== false;
+	}
+	out.aiFreeText = global.aiFreeText && out.ai === true;
+	out.aiSendIntent = global.aiSendIntent && out.ai === true;
+	return Object.freeze(out);
+}
+/** The runtime as seen by one bot (same ports, features narrowed by `features_json`). */
+function botRuntime(rt, bot) {
+	const overrides = parseJson(bot.features_json, BotFeatures, {});
+	if (!Object.values(overrides).includes(false)) return rt;
+	return {
+		...rt,
+		features: effectiveFeatures(rt.features, overrides)
+	};
+}
+/** `PATCH` input check: `core` cannot be switched off, and only globally enabled features can be switched on. */
+function checkBotFeatures(global, features) {
+	const issues = [];
+	for (const [k, v] of Object.entries(features)) if (k === "core" && v === false) issues.push({
+		path: "body.features.core",
+		message: "core cannot be turned off"
+	});
+	else if (v === true && global[k] !== true) issues.push({
+		path: `body.features.${k}`,
+		message: `feature "${k}" is not enabled for this app`
+	});
+	if (issues.length > 0) throw new TelegramPluginError("validation_failed", "bot features are not valid", { extensions: { issues } });
+}
+export { botRuntime, checkBotFeatures, effectiveFeatures };

package/dist/engine/chat-state.js

@@ -0,0 +1,66 @@
+import { sql } from "../ports/sql.js";
+import { chatDto } from "./rows.js";
+// src/engine/chat-state.ts
+/** Cancels queued deliveries of a chat (blocked, left, unlinked). `except` keeps the row being processed. */
+function cancelQueuedSql(rt, chatRef, code, now, except) {
+	return sql`UPDATE tg_delivery SET status = 'cancelled', error_code = ${code}, lease_until = NULL,
+               lease_token = NULL, updated_at = ${now}
+             WHERE tenant = ${rt.tenant} AND chat_ref = ${chatRef} AND status = 'queued'
+               ${except ? sql`AND id != ${except}` : sql.empty}`;
+}
+/** Status change for blocked / left (+ cancel the chat's queue). Hooks run after the batch. */
+function chatGoneSql(rt, chat, status, now, except) {
+	return [sql`UPDATE tg_chat SET status = ${status}, updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${chat.id}`, cancelQueuedSql(rt, chat.id, `chat_${status}`, now, except)];
+}
+async function afterChatGone(rt, chat, status, now) {
+	const dto = chatDto({
+		...chat,
+		status,
+		updated_at: now
+	});
+	if (status === "blocked") await rt.hook("onBlocked", (fn) => fn(dto));
+	else await rt.hook("onUnlinked", (fn) => fn(dto));
+}
+/**
+* A group became a supergroup (`migrate_to_chat_id`). The row keeps its id (destinations and subscriptions keep
+* working) and gets the new chat id. If the new chat already has a row, the old one is marked `migrated` and its
+* queue moves over. Returns the chat row that now owns the new id.
+*/
+async function migrateChat(rt, old, newChatId, now) {
+	if (old.chat_id === newChatId) return old;
+	const existing = await rt.db.first(sql`SELECT * FROM tg_chat WHERE tenant = ${rt.tenant} AND bot_id = ${old.bot_id} AND chat_id = ${newChatId}`);
+	if (!existing) {
+		await rt.db.run(sql`UPDATE tg_chat SET chat_id = ${newChatId}, kind = 'supergroup', updated_at = ${now}
+          WHERE tenant = ${rt.tenant} AND id = ${old.id}`);
+		rt.log.info("tg.chat_migrated", {
+			chatRef: old.id,
+			mode: "in_place"
+		});
+		return {
+			...old,
+			chat_id: newChatId,
+			kind: "supergroup",
+			updated_at: now
+		};
+	}
+	if (existing.id === old.id) return existing;
+	await rt.db.batch([
+		sql`UPDATE tg_chat SET status = 'migrated', updated_at = ${now} WHERE tenant = ${rt.tenant} AND id = ${old.id}`,
+		sql`UPDATE tg_chat SET status = CASE WHEN status IN ('pending', 'left') AND ${old.status} = 'active'
+                                     THEN 'active' ELSE status END,
+               audience_json = COALESCE(audience_json, ${old.audience_json}),
+               topics_json = COALESCE(topics_json, ${old.topics_json}),
+               kind = 'supergroup', updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND id = ${existing.id}`,
+		sql`UPDATE tg_delivery SET chat_ref = ${existing.id}, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND chat_ref = ${old.id} AND status IN ('queued', 'sending')`,
+		sql`UPDATE tg_destination SET chat_ref = ${existing.id}, updated_at = ${now}
+        WHERE tenant = ${rt.tenant} AND chat_ref = ${old.id}`
+	]);
+	rt.log.info("tg.chat_migrated", {
+		chatRef: old.id,
+		mode: "merged"
+	});
+	return await rt.db.first(sql`SELECT * FROM tg_chat WHERE id = ${existing.id}`) ?? existing;
+}
+export { afterChatGone, cancelQueuedSql, chatGoneSql, migrateChat };

package/dist/engine/content/audience.js

@@ -0,0 +1,54 @@
+import { Audience } from "../../contracts/chats.js";
+import { TelegramPluginError } from "../errors.js";
+import { parseJson } from "../rows.js";
+// src/engine/content/audience.ts
+/**
+* The audience of a chat. `byRole` groups by role (one provider run per role, as the role's audience actor);
+* otherwise each linked user is their own audience. The user is always resolved live first, so a disabled user
+* gets nothing even when data is shared per role.
+*/
+async function audienceOf(rt, chat, byRole) {
+	if (chat.status !== "active") return null;
+	if (chat.kind === "private") {
+		if (!chat.user_id) return null;
+		const actor = await rt.actor.forUser(chat.user_id);
+		if (actor === null) return null;
+		const info = rt.describe(actor);
+		if (byRole && info.role) {
+			const roleActor = await rt.actor.forAudience({ role: info.role });
+			if (roleActor !== null) return {
+				key: `r:${info.role}`,
+				actor: roleActor,
+				info: rt.describe(roleActor),
+				role: info.role,
+				userId: chat.user_id
+			};
+		}
+		return {
+			key: `u:${chat.user_id}`,
+			actor,
+			info,
+			role: info.role,
+			userId: chat.user_id
+		};
+	}
+	const audience = parseJson(chat.audience_json, Audience.nullable(), null);
+	if (!audience) return null;
+	const actor = await rt.actor.forAudience(audience);
+	if (actor === null) return null;
+	const info = rt.describe(actor);
+	return {
+		key: "role" in audience ? `r:${audience.role}` : `a:${[...audience.users].sort().join(",")}`,
+		actor,
+		info,
+		role: "role" in audience ? audience.role : info.role,
+		userId: null
+	};
+}
+/** The actor an admin previews as: a role's audience actor, or a user's live actor. */
+async function audienceForPreview(rt, as) {
+	const actor = "role" in as ? await rt.actor.forAudience({ role: as.role }) : await rt.actor.forUser(as.userId);
+	if (actor === null) throw new TelegramPluginError("not_found", "role or user not found");
+	return actor;
+}
+export { audienceForPreview, audienceOf };

package/dist/engine/content/buttons.d.ts

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

package/dist/engine/content/buttons.js

@@ -0,0 +1,113 @@
+import { SAFE_URL_RE } from "../../core/template/tags.js";
+import { sql } from "../../ports/sql.js";
+import { pickVariant, renderInline } from "./render.js";
+import { actionButton } from "../actions/tokens.js";
+// src/engine/content/buttons.ts
+/**
+* features.actions: an action button becomes a `callback_data: "a:<id>"` button plus the `tg_action_token` insert
+* (engine/actions/tokens.ts). Null (button left out) when actions are off, the action is unknown or its params fail.
+*/
+async function buildActionButton(rt, spec, text, ctx) {
+	return actionButton(rt, spec, text, ctx);
+}
+function label(spec, locale) {
+	return (pickVariant(spec.text, [locale])?.source ?? "").slice(0, 64);
+}
+function renderUrl(rt, url, ctx) {
+	try {
+		const out = renderInline(rt, url, ctx.vars, {
+			locale: ctx.locale,
+			tz: ctx.tz
+		}).trim();
+		return SAFE_URL_RE.test(out) ? out : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Template button rows → inline keyboard for one recipient. URL buttons are rendered (unsafe URLs dropped); action
+* buttons become `a:<token>` callbacks with their `tg_action_token` inserts in `sql` (none in previews, where
+* `chatRef` is null). Writes nothing itself.
+*/
+async function buildButtons(rt, rows, ctx) {
+	if (!rows || rows.length === 0) return {
+		markup: null,
+		sql: [],
+		preview: null
+	};
+	const keyboard = [];
+	const preview = [];
+	const sqls = [];
+	for (const row of rows) {
+		const out = [];
+		const pv = [];
+		for (const spec of row) {
+			const text = label(spec, ctx.locale);
+			if (text === "") continue;
+			const common = {
+				...spec.style ? { style: spec.style } : {},
+				...spec.disabled ? { disabled: true } : {}
+			};
+			if (spec.url !== void 0) {
+				const url = renderUrl(rt, spec.url, ctx);
+				if (url === null) {
+					rt.log.debug("tg.button_url_dropped", {});
+					continue;
+				}
+				out.push({
+					text,
+					url,
+					...common
+				});
+				pv.push({
+					text,
+					kind: "url",
+					url,
+					style: spec.style ?? null,
+					disabled: spec.disabled === true
+				});
+				continue;
+			}
+			pv.push({
+				text,
+				kind: "action",
+				url: null,
+				style: spec.style ?? null,
+				disabled: spec.disabled === true
+			});
+			if (ctx.chatRef === null) continue;
+			const built = await buildActionButton(rt, spec, text, ctx);
+			if (built) {
+				out.push(built.button);
+				sqls.push(...built.sql);
+			}
+		}
+		if (out.length > 0) keyboard.push(out);
+		if (pv.length > 0) preview.push(pv);
+	}
+	return {
+		markup: keyboard.length > 0 ? { inline_keyboard: keyboard } : null,
+		sql: sqls,
+		preview: preview.length > 0 ? preview : null
+	};
+}
+/** Action token ids in a keyboard built by `buildButtons` (`callback_data: "a:<id>"`). */
+function actionTokenIds(markup) {
+	if (!markup) return [];
+	const ids = [];
+	for (const row of markup.inline_keyboard) for (const b of row) if ("callback_data" in b && typeof b.callback_data === "string" && b.callback_data.startsWith("a:")) ids.push(b.callback_data.slice(2));
+	return ids;
+}
+/**
+* Put after the delivery INSERTs in the same batch as `BuiltButtons.sql`: deletes this keyboard's action tokens
+* unless the delivery row `lastPartDedupeKey` (the part that carries the keyboard) holds them, i.e. when the
+* INSERT was a dedupe no-op because an earlier run made the row. Empty without action buttons.
+*/
+function orphanTokenGuard(rt, markup, lastPartDedupeKey) {
+	const ids = actionTokenIds(markup);
+	if (ids.length === 0) return [];
+	return [sql`DELETE FROM tg_action_token WHERE tenant = ${rt.tenant} AND id IN (${sql.join(ids)})
+          AND NOT EXISTS (SELECT 1 FROM tg_delivery d WHERE d.tenant = ${rt.tenant} AND d.dedupe_key = ${lastPartDedupeKey}
+                            AND instr(d.reply_markup_json, '"' || ${"a:"} || tg_action_token.id || '"') > 0)`];
+}
+export { actionTokenIds, buildActionButton, buildButtons, orphanTokenGuard };