@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/engine/content/fanout.js

@@ -0,0 +1,284 @@
+import { escapeHtml } from "../../core/html/escape.js";
+import { isTelegramPluginError } from "../errors.js";
+import { pickVariant, renderBody } from "./render.js";
+import { ProviderTimeout, hostCan, parseProviderParams, requireProvider, runProvider } from "./providers.js";
+import { buildButtons, orphanTokenGuard } from "./buttons.js";
+import { fileUrl, renderReportFile, storeReportFile } from "./report-files.js";
+import { audienceOf } from "./audience.js";
+import { deliveryFragments } from "../outbox/enqueue.js";
+// src/engine/content/fanout.ts
+const BATCH_STATEMENTS = 50;
+/**
+* Failure codes worth another attempt later (a provider that threw or timed out). Everything else (forbidden,
+* invalid data, a render error) fails the same way again.
+*/
+const TRANSIENT_FANOUT_ERRORS = ["provider_timeout", "provider_error"];
+function errorCode(e) {
+	if (isTelegramPluginError(e)) return e.code;
+	if (e instanceof ProviderTimeout) return "provider_timeout";
+	return "provider_error";
+}
+/** Writes per-chat statement groups in batches of ≤ 50 statements (a chat's rows always share a batch). */
+async function insertGroups(rt, groups) {
+	let inserted = 0;
+	let batch = [];
+	let counted = [];
+	const flush = async () => {
+		if (batch.length === 0) return;
+		(await rt.db.batch(batch)).forEach((r, i) => {
+			if (counted[i]) inserted += r.changes;
+		});
+		batch = [];
+		counted = [];
+	};
+	for (const g of groups) {
+		const size = g.before.length + g.rows.length + g.after.length;
+		if (batch.length + size > BATCH_STATEMENTS) await flush();
+		const parts = [
+			[g.before, false],
+			[g.rows, true],
+			[g.after, false]
+		];
+		for (const [list, count] of parts) for (const q of list) {
+			batch.push(q);
+			counted.push(count);
+		}
+	}
+	await flush();
+	return inserted;
+}
+/**
+* Renders a template per audience and locale and inserts `tg_delivery` rows (chunked `db.batch()`es of ≤ 50
+* statements, plus action tokens). Runs host providers as each audience; stores report files through the files
+* port. Does not kick the transport. Per-audience failures are counted in the result, not thrown.
+*/
+async function fanOut(rt, input) {
+	const result = {
+		deliveries: 0,
+		chats: 0,
+		held: input.recipients.held.length,
+		muted: input.recipients.muted.length,
+		skipped: 0,
+		failed: 0,
+		errors: [],
+		files: []
+	};
+	const fail = (code, n) => {
+		result.failed += n;
+		if (!result.errors.includes(code)) result.errors.push(code);
+	};
+	const t = input.template;
+	let def = null;
+	let params = {};
+	try {
+		if (input.provider === void 0) {
+			if (t.provider) {
+				def = requireProvider(rt, t.provider);
+				params = parseProviderParams(def, {
+					...t.providerParams,
+					...input.params
+				});
+			}
+		} else if (input.provider !== null) {
+			def = requireProvider(rt, input.provider.key);
+			params = parseProviderParams(def, input.provider.params);
+		}
+	} catch (e) {
+		const all = input.recipients.send.length + input.recipients.held.length;
+		fail(errorCode(e), all);
+		return result;
+	}
+	const byRole = !input.personalize || def?.cacheFor === "audience-role";
+	const groups = /* @__PURE__ */ new Map();
+	const targets = [...input.recipients.send.map((chat) => ({
+		chat,
+		notBefore: void 0
+	})), ...input.recipients.held.map((h) => ({
+		chat: h.chat,
+		notBefore: h.until
+	}))];
+	for (const target of targets) {
+		const aud = await audienceOf(rt, target.chat.row, byRole);
+		if (!aud) {
+			result.skipped++;
+			continue;
+		}
+		const g = groups.get(aud.key);
+		if (g) g.targets.push(target);
+		else groups.set(aud.key, {
+			aud,
+			targets: [target]
+		});
+	}
+	const cache = input.cache ?? /* @__PURE__ */ new Map();
+	const statements = [];
+	for (const { aud, targets: chats } of groups.values()) {
+		let vars = {};
+		try {
+			if (def) {
+				if (!await hostCan(rt, aud.actor, def.permission)) {
+					fail("provider_forbidden", chats.length);
+					continue;
+				}
+				vars = await runProvider(rt, {
+					def,
+					actor: aud.actor,
+					params,
+					now: input.now,
+					tz: input.tz,
+					locale: rt.i18n.pick(aud.info.locale),
+					audienceKey: aud.key,
+					role: byRole ? aud.role : null,
+					cache,
+					checked: true
+				});
+			}
+			if (input.vars) {
+				const extra = await input.vars(aud);
+				if (extra === null) {
+					result.skipped += chats.length;
+					continue;
+				}
+				vars = {
+					...extra,
+					...vars
+				};
+			}
+		} catch (e) {
+			const code = errorCode(e);
+			rt.log.warn("tg.fanout_provider_failed", {
+				provider: def?.key ?? null,
+				code
+			});
+			fail(code, chats.length);
+			continue;
+		}
+		const rendered = /* @__PURE__ */ new Map();
+		for (const { chat, notBefore } of chats) {
+			const tz = chat.row.timezone ?? input.tz;
+			const locale = pickVariant(t.body, [
+				chat.row.locale,
+				aud.info.locale,
+				chat.bot.default_locale,
+				rt.i18n.defaultLocale
+			])?.locale ?? rt.i18n.defaultLocale;
+			const rkey = `${locale}|${tz}`;
+			let r = rendered.get(rkey);
+			if (r === void 0) {
+				try {
+					const body = renderBody(rt, {
+						body: t.body,
+						format: t.format,
+						vars,
+						locales: [locale],
+						tz
+					});
+					let file = null;
+					if (t.kind === "report") {
+						const out = await renderReportFile(rt, {
+							template: t,
+							vars,
+							locale,
+							tz,
+							format: input.format,
+							html: body.html
+						});
+						file = await storeReportFile(rt, out, {
+							template: t.key,
+							...input.fileTags
+						});
+						result.files.push(file);
+					}
+					r = body.parts.length === 0 && !file ? "empty" : {
+						html: body.html,
+						parts: body.parts,
+						file,
+						locale
+					};
+				} catch (e) {
+					const code = isTelegramPluginError(e) ? e.code : "render_failed";
+					rt.log.warn("tg.fanout_render_failed", {
+						template: t.key,
+						code
+					});
+					r = "failed";
+					fail(code, 0);
+				}
+				rendered.set(rkey, r);
+			}
+			if (r === "failed") {
+				result.failed++;
+				continue;
+			}
+			if (r === "empty") {
+				result.skipped++;
+				continue;
+			}
+			const buttons = await buildButtons(rt, t.buttons, {
+				vars,
+				locale: r.locale,
+				tz,
+				botId: chat.botId,
+				chatRef: chat.chatRef,
+				userId: aud.userId,
+				now: input.now
+			});
+			const base = {
+				botId: chat.botId,
+				chatRef: chat.chatRef,
+				threadId: chat.messageThreadId ?? null,
+				source: input.source,
+				sourceId: input.sourceId,
+				html: r.html,
+				replyMarkup: buttons.markup,
+				options: t.options,
+				dedupeKey: input.dedupeKey(chat),
+				notBefore,
+				render: {
+					template: t.key,
+					templateVersion: t.version,
+					...input.meta
+				}
+			};
+			let delivery;
+			if (r.file && r.file.size !== null && r.file.size > 52428800) {
+				rt.log.warn("tg.file_too_large", {
+					template: t.key,
+					size: r.file.size,
+					code: "file_too_large"
+				});
+				const url = await fileUrl(rt, r.file.ref);
+				const note = rt.i18n.t(r.locale, "bot.report.too_large");
+				const link = url ? `\n${rt.i18n.t(r.locale, "bot.report.download")} <a href="${escapeHtml(url)}">${escapeHtml(r.file.name)}</a>` : "";
+				delivery = {
+					...base,
+					kind: "text",
+					html: [r.html, `${note}${link}`].filter(Boolean).join("\n\n")
+				};
+			} else if (r.file) delivery = {
+				...base,
+				kind: "document",
+				file: {
+					ref: r.file.ref,
+					name: r.file.name,
+					mime: r.file.mime
+				}
+			};
+			else delivery = {
+				...base,
+				kind: "text"
+			};
+			const rows = deliveryFragments(rt, delivery, rt.clock.now());
+			const guard = orphanTokenGuard(rt, buttons.markup, `${delivery.dedupeKey}:${rows.length - 1}`);
+			statements.push({
+				before: buttons.sql,
+				rows,
+				after: guard
+			});
+			result.chats++;
+		}
+	}
+	result.deliveries = await insertGroups(rt, statements);
+	return result;
+}
+export { TRANSIENT_FANOUT_ERRORS, fanOut };

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

@@ -0,0 +1,6 @@
+/**
+ * Keeps only what both views contain (objects by key, arrays index-wise); values come from `b` (the audience).
+ * A field is kept only when BOTH sides returned it with a non-null value of the same kind: `null` / `undefined` on
+ * either side means "not visible" (hosts redact by nulling), so a field redacted for the sender never leaks.
+ */
+export declare function intersectData(a: unknown, b: unknown): unknown;

package/dist/engine/content/intersect.js

@@ -0,0 +1,26 @@
+// src/engine/content/intersect.ts
+/**
+* Keeps only what both views contain (objects by key, arrays index-wise); values come from `b` (the audience).
+* A field is kept only when BOTH sides returned it with a non-null value of the same kind: `null` / `undefined` on
+* either side means "not visible" (hosts redact by nulling), so a field redacted for the sender never leaks.
+*/
+function intersectData(a, b) {
+	if (a === void 0 || b === void 0 || a === null || b === null) return void 0;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		const n = Math.min(a.length, b.length);
+		return b.slice(0, n).map((v, i) => intersectData(a[i], v) ?? null);
+	}
+	const isObj = (v) => typeof v === "object" && !Array.isArray(v);
+	if (isObj(a) && isObj(b)) {
+		const out = {};
+		for (const [k, v] of Object.entries(b)) {
+			if (!Object.hasOwn(a, k)) continue;
+			const r = intersectData(a[k], v);
+			if (r !== void 0) out[k] = r;
+		}
+		return out;
+	}
+	if (isObj(a) || isObj(b) || Array.isArray(a) || Array.isArray(b)) return void 0;
+	return typeof a === typeof b ? b : void 0;
+}
+export { intersectData };

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

@@ -0,0 +1,6 @@
+/** Thrown by `runProvider` when a provider exceeds `limits.providerTimeoutMs` (counted as `provider_timeout`). */
+export declare class ProviderTimeout extends Error {
+  /** Always `"ProviderTimeout"`. */
+  readonly name = "ProviderTimeout";
+  constructor(key: string);
+}

package/dist/engine/content/providers.js

@@ -0,0 +1,142 @@
+import { zodToShape } from "../../core/template/shape.js";
+import { TelegramPluginError } from "../errors.js";
+// src/engine/content/providers.ts
+function requireProvider(rt, key) {
+	const def = rt.registry.providers.get(key);
+	if (!def) throw new TelegramPluginError("provider_unknown", `provider "${key}" is not registered`);
+	return def;
+}
+/** Host data permission (not prefixed); errors count as "no". */
+async function hostCan(rt, actor, permission) {
+	if (permission === null) return true;
+	try {
+		return await rt.authorize(actor, permission) === true;
+	} catch (e) {
+		rt.log.error("tg.authorize_error", {
+			permission,
+			error: e instanceof Error ? e.name : "unknown"
+		});
+		return false;
+	}
+}
+/** Validates provider params (defaults applied). Throws `validation_failed` with the issues. */
+function parseProviderParams(def, params) {
+	if (!def.params) return params ?? {};
+	const r = def.params.safeParse(params ?? {});
+	if (r.success) return r.data;
+	throw new TelegramPluginError("validation_failed", `params of provider "${def.key}" are not valid`, { extensions: { issues: r.error.issues.slice(0, 20).map((i) => ({
+		path: ["params", ...i.path.map(String)].join("."),
+		message: i.message
+	})) } });
+}
+const shapes = /* @__PURE__ */ new WeakMap();
+function shapeOf(schema) {
+	let s = shapes.get(schema);
+	if (!s) {
+		s = zodToShape(schema);
+		shapes.set(schema, s);
+	}
+	return s;
+}
+/** Keeps only what the shape declares (objects recursively, arrays per item). */
+function stripToShape(value, shape) {
+	if (value === null || value === void 0) return value;
+	if (shape.kind === "object") {
+		if (typeof value !== "object" || Array.isArray(value)) return void 0;
+		const out = {};
+		for (const [k, s] of Object.entries(shape.fields)) {
+			if (!Object.hasOwn(value, k)) continue;
+			const v = stripToShape(value[k], s);
+			if (v !== void 0) out[k] = v;
+		}
+		return out;
+	}
+	if (shape.kind === "array") return Array.isArray(value) ? value.map((v) => stripToShape(v, shape.item)) : void 0;
+	return value;
+}
+/**
+* Drops every variable the provider did not declare. A value that passes the schema is used as parsed (defaults,
+* coercions); otherwise it is stripped structurally so a slightly off provider still renders what it declared.
+*/
+function declaredOnly(rt, def, data) {
+	const parsed = def.variables.safeParse(data);
+	const value = parsed.success ? parsed.data : stripToShape(data, shapeOf(def.variables));
+	if (!parsed.success) rt.log.warn("tg.provider_shape", {
+		provider: def.key,
+		issues: parsed.error.issues.length
+	});
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? stripToShape(value, shapeOf(def.variables)) : {};
+}
+function stableJson(v) {
+	if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
+	if (Array.isArray(v)) return `[${v.map(stableJson).join(",")}]`;
+	const o = v;
+	return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stableJson(o[k])}`).join(",")}}`;
+}
+function withTimeout(p, ms, key) {
+	let timer;
+	const timeout = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(new ProviderTimeout(key)), ms);
+	});
+	return Promise.race([p, timeout]).finally(() => {
+		if (timer !== void 0) clearTimeout(timer);
+	});
+}
+/** Thrown by `runProvider` when a provider exceeds `limits.providerTimeoutMs` (counted as `provider_timeout`). */
+var ProviderTimeout = class extends Error {
+	/** Always `"ProviderTimeout"`. */
+	name = "ProviderTimeout";
+	constructor(key) {
+		super(`provider ${key} timed out`);
+	}
+};
+function cacheKey(input) {
+	const p = `${input.def.key}|${stableJson(input.params)}|${input.locale}|${input.tz}`;
+	switch (input.def.cacheFor) {
+		case "params": return p;
+		case "audience-role": return input.role ? `${p}|r:${input.role}` : input.audienceKey ? `${p}|${input.audienceKey}` : null;
+		default: return input.audienceKey ? `${p}|${input.audienceKey}` : null;
+	}
+}
+/**
+* Runs a provider as `actor`. Throws `provider_forbidden` when the actor lacks the provider's permission,
+* `ProviderTimeout` after `limits.providerTimeoutMs`, or whatever the provider throws.
+*/
+async function runProvider(rt, input) {
+	const { def } = input;
+	if (!input.checked && !await hostCan(rt, input.actor, def.permission)) throw new TelegramPluginError("provider_forbidden", `the audience may not read "${def.key}"`);
+	const key = input.cache ? cacheKey(input) : null;
+	if (key && input.cache) {
+		const hit = input.cache.get(key);
+		if (hit) return hit;
+	}
+	const db = rt.db;
+	const started = rt.clock.now();
+	const run = withTimeout(Promise.resolve().then(() => def.run({
+		actor: input.actor,
+		params: input.params,
+		now: input.now,
+		tz: input.tz,
+		locale: input.locale,
+		db,
+		env: rt.env
+	})), rt.limits.providerTimeoutMs, def.key).then((data) => declaredOnly(rt, def, data));
+	if (key && input.cache) {
+		input.cache.set(key, run);
+		run.catch(() => input.cache?.delete(key));
+	}
+	try {
+		return await run;
+	} finally {
+		rt.log.debug("tg.provider", {
+			provider: def.key,
+			ms: rt.clock.now() - started
+		});
+	}
+}
+/** Sample data for previews (`provider.sample()`), stripped like live data. */
+function sampleData(rt, def) {
+	if (!def.sample) throw new TelegramPluginError("validation_failed", `provider "${def.key}" has no sample()`);
+	return declaredOnly(rt, def, def.sample());
+}
+export { ProviderTimeout, declaredOnly, hostCan, parseProviderParams, requireProvider, runProvider, sampleData, stripToShape };

package/dist/engine/content/recipients.js

@@ -0,0 +1,128 @@
+import { QuietHours } from "../../contracts/subscriptions.js";
+import { applySubscriptions, dedupeChats, planRecipients } from "../../core/recipients.js";
+import { sql } from "../../ports/sql.js";
+import { parseJson } from "../rows.js";
+// src/engine/content/recipients.ts
+const CHUNK = 80;
+async function chunked(rt, ids, q) {
+	const out = [];
+	for (let i = 0; i < ids.length; i += CHUNK) out.push(...await rt.db.all(q(ids.slice(i, i + CHUNK))));
+	return out;
+}
+const ACTIVE_CHAT = sql`c.status = 'active' AND b.deleted_at IS NULL AND b.status IN ('active', 'webhook_error')`;
+function chatsSql(rt, where) {
+	return sql`SELECT c.* FROM tg_chat c JOIN tg_bot b ON b.id = c.bot_id
+             WHERE c.tenant = ${rt.tenant} AND ${ACTIVE_CHAT} AND ${where} ORDER BY c.id`;
+}
+/** Active private chats of these users (every bot they linked). */
+async function privateChatsOf(rt, userIds) {
+	return chunked(rt, [...new Set(userIds)], (ids) => chatsSql(rt, sql`c.kind = 'private' AND c.user_id IN (${sql.join(ids)})`));
+}
+async function usersWithRole(rt, role) {
+	if (rt.users?.byRole) return [...await rt.users.byRole(role)];
+	const chats = await rt.db.all(chatsSql(rt, sql`c.kind = 'private' AND c.user_id IS NOT NULL`));
+	const out = [];
+	for (const userId of new Set(chats.map((c) => c.user_id))) {
+		const actor = await rt.actor.forUser(userId);
+		if (actor !== null && rt.describe(actor).role === role) out.push(userId);
+	}
+	return out;
+}
+async function botsOf(rt, ids) {
+	const rows = await chunked(rt, [...new Set(ids)], (chunk) => sql`SELECT * FROM tg_bot WHERE tenant = ${rt.tenant} AND id IN (${sql.join(chunk)})`);
+	return new Map(rows.map((b) => [b.id, b]));
+}
+function resolved(row, via, threadId) {
+	return {
+		chatRef: row.id,
+		botId: row.bot_id,
+		kind: row.kind === "group" || row.kind === "supergroup" || row.kind === "channel" ? row.kind : "private",
+		status: "active",
+		userId: row.user_id,
+		messageThreadId: threadId,
+		locale: row.locale,
+		timezone: row.timezone,
+		via: [via],
+		row
+	};
+}
+/** Every active chat the specs name, deduped per chat + topic thread. Unknown names resolve to nothing. */
+async function resolveChats(rt, specs, now) {
+	const plan = planRecipients(specs);
+	const found = [];
+	if (plan.destinations.length > 0) {
+		const dests = await chunked(rt, plan.destinations, (slugs) => sql`SELECT * FROM tg_destination WHERE tenant = ${rt.tenant} AND deleted_at IS NULL AND slug IN (${sql.join(slugs)})`);
+		const chats = await chunked(rt, [...new Set(dests.map((d) => d.chat_ref))], (ids) => chatsSql(rt, sql`c.id IN (${sql.join(ids)})`));
+		const byId = new Map(chats.map((c) => [c.id, c]));
+		for (const d of dests) {
+			const c = byId.get(d.chat_ref);
+			if (c) found.push(resolved(c, { destination: d.slug }, d.message_thread_id));
+		}
+	}
+	if (plan.chats.length > 0) {
+		const chats = await chunked(rt, plan.chats, (ids) => chatsSql(rt, sql`c.id IN (${sql.join(ids)})`));
+		for (const c of chats) found.push(resolved(c, { chat: c.id }, null));
+	}
+	const userVia = /* @__PURE__ */ new Map();
+	for (const u of plan.users) userVia.set(u, { user: u });
+	for (const role of plan.roles) for (const u of await usersWithRole(rt, role)) if (!userVia.has(u)) userVia.set(u, { role });
+	for (const [key, refs] of Object.entries(plan.audiences)) {
+		const def = rt.registry.audiences.get(key);
+		if (!def) {
+			rt.log.warn("tg.audience_unknown", { audience: key });
+			continue;
+		}
+		for (const ref of refs) for (const u of await def.resolve({
+			ref,
+			db: rt.db,
+			now,
+			env: rt.env
+		})) if (!userVia.has(u)) userVia.set(u, {
+			audience: key,
+			ref
+		});
+	}
+	if (userVia.size > 0) for (const c of await privateChatsOf(rt, [...userVia.keys()])) found.push(resolved(c, userVia.get(c.user_id), null));
+	if (plan.allLinked) {
+		const all = await rt.db.all(chatsSql(rt, sql`(c.kind != 'private' OR c.user_id IS NOT NULL) AND c.kind != 'channel'`));
+		for (const c of all) found.push(resolved(c, { allLinked: true }, null));
+	}
+	const bots = await botsOf(rt, found.map((f) => f.botId));
+	const out = [];
+	for (const f of dedupeChats(found)) {
+		const bot = bots.get(f.botId);
+		if (bot) out.push({
+			...f,
+			bot
+		});
+	}
+	return out;
+}
+async function subscriptionsOf(rt, chatRefs) {
+	return (await chunked(rt, [...new Set(chatRefs)], (ids) => sql`SELECT chat_ref, topic, muted, quiet_json FROM tg_subscription
+          WHERE tenant = ${rt.tenant} AND chat_ref IN (${sql.join(ids)})`)).map((r) => ({
+		chatRef: r.chat_ref,
+		topic: r.topic,
+		muted: r.muted === 1,
+		quiet: parseJson(r.quiet_json, QuietHours.nullable(), null)
+	}));
+}
+/**
+* Specs → chats → subscriptions for `topic` (`schedule:<id>`, `event:<key>`, `broadcast`). Muted chats are
+* dropped; chats in quiet hours are held until the window ends (chat zone, else the host zone).
+*/
+async function resolveRecipients(rt, specs, opts) {
+	const chats = await resolveChats(rt, specs, opts.now);
+	if (chats.length === 0) return {
+		send: [],
+		held: [],
+		muted: []
+	};
+	const subs = await subscriptionsOf(rt, chats.map((c) => c.chatRef));
+	return applySubscriptions(chats, subs, {
+		topic: opts.topic,
+		now: opts.now,
+		defaultTz: rt.settings.timezone
+	});
+}
+export { privateChatsOf, resolveChats, resolveRecipients, subscriptionsOf };