@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/core/template/tags.js

@@ -0,0 +1,105 @@
+// src/core/template/tags.ts
+const ALLOWED_TAGS = [
+	"b",
+	"strong",
+	"i",
+	"em",
+	"u",
+	"ins",
+	"s",
+	"strike",
+	"del",
+	"code",
+	"pre",
+	"a",
+	"blockquote",
+	"tg-spoiler",
+	"span",
+	"tg-emoji",
+	"tg-time"
+];
+const TAG_SET = new Set(ALLOWED_TAGS);
+function isAllowedTag(name) {
+	return TAG_SET.has(name);
+}
+/** Schemes allowed in `<a href>`. */
+const SAFE_URL_RE = /^(?:https?:\/\/|tg:\/\/)/i;
+const TIME_FORMAT_RE = /^(?:r|w?[dD]?[tT]?)$/;
+const LANGUAGE_RE = /^language-[A-Za-z0-9_+#.-]{1,32}$/;
+/** Literal text of an attribute, or null when it contains a variable. */
+function literalValue(attr) {
+	if (attr.value === null) return "";
+	let out = "";
+	for (const p of attr.value) {
+		if (p.type !== "text") return null;
+		out += p.value;
+	}
+	return out;
+}
+const RULES = {
+	a: { href: {
+		required: true,
+		vars: true,
+		check: (v) => SAFE_URL_RE.test(v) ? null : "href must start with https://, http:// or tg://"
+	} },
+	blockquote: { expandable: { boolean: true } },
+	span: { class: {
+		required: true,
+		check: (v) => v === "tg-spoiler" ? null : "span needs class=\"tg-spoiler\""
+	} },
+	code: { class: { check: (v) => LANGUAGE_RE.test(v) ? null : "code class must be \"language-…\"" } },
+	"tg-emoji": { "emoji-id": {
+		required: true,
+		vars: true,
+		check: (v) => /^\d+$/.test(v) ? null : "emoji-id must be digits"
+	} },
+	"tg-time": {
+		unix: {
+			required: true,
+			vars: true,
+			check: (v) => /^\d+$/.test(v) ? null : "unix must be digits"
+		},
+		format: { check: (v) => TIME_FORMAT_RE.test(v) ? null : "format must match r|w?[dD]?[tT]?" }
+	}
+};
+/** Checks one element's attributes. Returns error messages (empty when valid). */
+function checkAttrs(tag, attrs) {
+	const rules = RULES[tag] ?? {};
+	const errors = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const attr of attrs) {
+		const rule = rules[attr.name];
+		if (!rule) {
+			errors.push(`attribute "${attr.name}" is not allowed on <${tag}>`);
+			continue;
+		}
+		if (seen.has(attr.name)) errors.push(`duplicate attribute "${attr.name}"`);
+		seen.add(attr.name);
+		if (rule.boolean) {
+			if (attr.value !== null) errors.push(`"${attr.name}" takes no value`);
+			continue;
+		}
+		if (attr.value === null) {
+			errors.push(`"${attr.name}" needs a value`);
+			continue;
+		}
+		const literal = literalValue(attr);
+		if (literal === null) {
+			if (!rule.vars) errors.push(`"${attr.name}" cannot contain variables`);
+			const first = attr.value[0];
+			if (tag === "a" && first?.type === "text" && !SAFE_URL_RE.test(first.value)) errors.push("href must start with https://, http:// or tg://");
+			continue;
+		}
+		const msg = rule.check?.(literal);
+		if (msg) errors.push(msg);
+	}
+	for (const [name, rule] of Object.entries(rules)) if (rule.required && !seen.has(name)) errors.push(`<${tag}> needs "${name}"`);
+	return errors;
+}
+/** Values checked again after rendering (variables are allowed in these). */
+function renderedAttrOk(tag, attr, value) {
+	if (tag === "a" && attr === "href") return SAFE_URL_RE.test(value);
+	if (tag === "tg-emoji" && attr === "emoji-id" || tag === "tg-time" && attr === "unix") return /^\d+$/.test(value);
+	return true;
+}
+export { ALLOWED_TAGS, SAFE_URL_RE, checkAttrs, isAllowedTag, literalValue, renderedAttrOk };

package/dist/core/template/validate.d.ts

@@ -0,0 +1,10 @@
+import { CoreTemplateError, TemplateAst } from "./ast.js";
+import { FilterRegistry } from "./filters.js";
+/** Options for {@link validateTemplate}. */
+export interface ValidateOptions {
+  /** A Zod schema or a `Shape`. Without it only filters are checked. */
+  variables?: unknown;
+  filters?: FilterRegistry | undefined;
+}
+/** Checks a parsed template against its variables (unknown paths, type misuse) and filters (unknown names, arg counts). */
+export declare function validateTemplate(ast: TemplateAst, opts?: ValidateOptions): CoreTemplateError[];

package/dist/core/template/validate.js

@@ -0,0 +1,144 @@
+import { pathText } from "./ast.js";
+import { resolveFilter } from "./filters.js";
+import { zodToShape } from "./shape.js";
+// src/core/template/validate.ts
+const UNKNOWN = {
+	kind: "unknown",
+	optional: false
+};
+function isShape(v) {
+	return v !== null && typeof v === "object" && "kind" in v && "optional" in v && !("_zod" in v);
+}
+function resolve(path, stack) {
+	const top = stack[stack.length - 1] ?? UNKNOWN;
+	if (path.length === 0) return { shape: top };
+	const [head, ...rest] = path;
+	let shape;
+	for (let k = stack.length - 1; k >= 0 && head !== void 0; k--) {
+		const s = stack[k];
+		if (!s) continue;
+		if (s.kind === "object" && Object.hasOwn(s.fields, head)) {
+			shape = s.fields[head];
+			break;
+		}
+		if (s.kind === "record" || s.kind === "unknown") {
+			shape = UNKNOWN;
+			break;
+		}
+	}
+	if (!shape) return { error: `unknown variable "${head}"` };
+	let at = head ?? "";
+	for (const key of rest) {
+		if (shape.kind === "object") {
+			const next = Object.hasOwn(shape.fields, key) ? shape.fields[key] : void 0;
+			if (!next) return { error: `unknown variable "${at}.${key}"` };
+			shape = next;
+		} else if (shape.kind === "array" && key === "length") shape = {
+			kind: "number",
+			optional: false
+		};
+		else if (shape.kind === "record" || shape.kind === "unknown") shape = UNKNOWN;
+		else return { error: `"${at}" is a ${shape.kind} and has no field "${key}"` };
+		at += `.${key}`;
+	}
+	return { shape };
+}
+/** Checks a parsed template against its variables (unknown paths, type misuse) and filters (unknown names, arg counts). */
+function validateTemplate(ast, opts = {}) {
+	const errors = [];
+	const root = opts.variables === void 0 ? UNKNOWN : isShape(opts.variables) ? opts.variables : zodToShape(opts.variables);
+	const checkVar = (node, stack) => {
+		const r = resolve(node.path, stack);
+		if ("error" in r) errors.push({
+			code: "variable_unknown",
+			message: r.error,
+			line: node.line,
+			column: node.column
+		});
+		else if (node.filters.length === 0 && r.shape.kind === "object") errors.push({
+			code: "variable_type",
+			message: `"${pathText(node.path)}" is an object; use {{#${pathText(node.path)}}}…{{/${pathText(node.path)}}}`,
+			line: node.line,
+			column: node.column
+		});
+		for (const f of node.filters) {
+			const def = resolveFilter(f.name, opts.filters);
+			if (!def) {
+				errors.push({
+					code: "filter_unknown",
+					message: `unknown filter "${f.name}"`,
+					line: f.line,
+					column: f.column
+				});
+				continue;
+			}
+			const min = def.minArgs ?? 0;
+			const max = def.maxArgs ?? Number.POSITIVE_INFINITY;
+			if (f.args.length < min || f.args.length > max) {
+				const want = min === max ? `${min}` : max === Number.POSITIVE_INFINITY ? `at least ${min}` : `${min}–${max}`;
+				errors.push({
+					code: "filter_args",
+					message: `filter "${f.name}" takes ${want} argument(s), got ${f.args.length}`,
+					line: f.line,
+					column: f.column
+				});
+			}
+		}
+	};
+	const walk = (list, stack) => {
+		for (const node of list) switch (node.type) {
+			case "text": break;
+			case "var":
+				checkVar(node, stack);
+				break;
+			case "element":
+				for (const a of node.attrs) for (const p of a.value ?? []) if (p.type === "var") checkVar(p, stack);
+				walk(node.children, stack);
+				break;
+			case "inverted": {
+				const r = resolve(node.path, stack);
+				if ("error" in r) errors.push({
+					code: "variable_unknown",
+					message: r.error,
+					line: node.line,
+					column: node.column
+				});
+				walk(node.children, stack);
+				break;
+			}
+			case "section": {
+				const r = resolve(node.path, stack);
+				if ("error" in r) {
+					errors.push({
+						code: "variable_unknown",
+						message: r.error,
+						line: node.line,
+						column: node.column
+					});
+					walk(node.children, [...stack, UNKNOWN]);
+					break;
+				}
+				const s = r.shape;
+				if (s.kind === "array") walk(node.children, [...stack, s.item]);
+				else if (s.kind === "boolean") walk(node.children, stack);
+				else if (s.kind === "object" || s.kind === "record" || s.kind === "unknown" || s.optional) walk(node.children, [...stack, {
+					...s,
+					optional: false
+				}]);
+				else {
+					errors.push({
+						code: "section_invalid",
+						message: `{{#${pathText(node.path)}}} needs a list, an object, a boolean or an optional value (it is a ${s.kind})`,
+						line: node.line,
+						column: node.column
+					});
+					walk(node.children, [...stack, s]);
+				}
+				break;
+			}
+		}
+	};
+	walk(ast.children, [root]);
+	return errors;
+}
+export { validateTemplate };

package/dist/core/template/variables.d.ts

@@ -0,0 +1,15 @@
+import { TemplateAst } from "./ast.js";
+/** One variable use in a template (1-based `line` / `column`). */
+export interface VariableRef {
+  /** Path as written (`name`, `project.stage`, `.`). */
+  path: string;
+  kind: "var" | "section" | "inverted";
+  /** Enclosing section paths, outermost first (`["projects"]` for `{{name}}` inside `{{#projects}}`). */
+  scope: string[];
+  /** Filter names applied, in order. */
+  filters: string[];
+  line: number;
+  column: number;
+}
+/** Every variable and section a template reads, in source order. */
+export declare function listVariables(ast: TemplateAst): VariableRef[];

package/dist/core/template/variables.js

@@ -0,0 +1,41 @@
+import { pathText } from "./ast.js";
+// src/core/template/variables.ts
+/** Every variable and section a template reads, in source order. */
+function listVariables(ast) {
+	const out = [];
+	const walk = (list, scope) => {
+		for (const node of list) if (node.type === "var") out.push({
+			path: pathText(node.path),
+			kind: "var",
+			scope,
+			filters: node.filters.map((f) => f.name),
+			line: node.line,
+			column: node.column
+		});
+		else if (node.type === "section" || node.type === "inverted") {
+			const path = pathText(node.path);
+			out.push({
+				path,
+				kind: node.type,
+				scope,
+				filters: [],
+				line: node.line,
+				column: node.column
+			});
+			walk(node.children, node.type === "section" ? [...scope, path] : scope);
+		} else if (node.type === "element") {
+			for (const a of node.attrs) for (const p of a.value ?? []) if (p.type === "var") out.push({
+				path: pathText(p.path),
+				kind: "var",
+				scope,
+				filters: p.filters.map((f) => f.name),
+				line: p.line,
+				column: p.column
+			});
+			walk(node.children, scope);
+		}
+	};
+	walk(ast.children, []);
+	return out;
+}
+export { listVariables };

package/dist/do/index.d.ts

@@ -0,0 +1,3 @@
+import { BotDoHost, registerTelegramPlugin } from "../engine/outbox/do-registry.js";
+import { BotObjectState, TelegramBotDO, createTelegramBotDO, doLease } from "./telegram-bot-do.js";
+export { type BotDoHost, type BotObjectState, TelegramBotDO, createTelegramBotDO, doLease, registerTelegramPlugin };

package/dist/do/index.js

@@ -0,0 +1,3 @@
+import { registerTelegramPlugin } from "../engine/outbox/do-registry.js";
+import { TelegramBotDO, createTelegramBotDO, doLease } from "./telegram-bot-do.js";
+export { TelegramBotDO, createTelegramBotDO, doLease, registerTelegramPlugin };

package/dist/do/telegram-bot-do.d.ts

@@ -0,0 +1,45 @@
+import { Runtime } from "../engine/runtime.js";
+import { BotDoHost } from "../engine/outbox/do-registry.js";
+import { DoKickBody, DoWakeBody } from "../engine/outbox/do-transport.js";
+import { DrainLease } from "../engine/outbox/drain.js";
+/** What a {@link TelegramBotDO} persists in its storage: which bot it serves and its next alarm reasons. */
+export interface BotObjectState {
+  tenant: string;
+  botId: string;
+  /** Next due delivery (epoch ms, plugin clock), null = nothing queued. */
+  dueAt: number | null;
+  /** Next scheduler wake, null = none. */
+  wakeAt: number | null;
+}
+/** The object is the lease: it only re-reads the bot row now and then to notice a pause, 401 or removal. */
+export declare function doLease<A>(rt: Runtime<A>, botId: string): DrainLease;
+/** Per-bot Durable Object: strict paced sender and per-bot scheduler. Export it from the Worker and bind it as `env.botDO`. */
+export declare class TelegramBotDO<E = unknown> implements DurableObject {
+  #private;
+  protected readonly ctx: DurableObjectState;
+  protected readonly env: E;
+  constructor(ctx: DurableObjectState, env: E);
+  /** The plugin that owns this object. Default: the one `createTelegramPlugin()` registered for the tenant. */
+  protected plugin(tenant: string): BotDoHost;
+  /** Wall-clock alarm time for a delay. Override only in tests (to drive alarms by hand). */
+  protected alarmTime(delayMs: number): number;
+  /** Scheduler role: runs the per-bot wake stages; returns the next wake time. */
+  protected onWake(rt: Runtime<unknown>, botId: string, now: number): Promise<number | null>;
+  /** RPC over fetch: `POST /kick`, `POST /wake` (`{ tenant, botId, at, replace? }`), `GET /state`. Bad input → 400 JSON. */
+  fetch(request: Request): Promise<Response>;
+  /** Alarm handler: runs drain/wake cycles. */
+  alarm(): Promise<void>;
+  /** A drain is wanted now: arm the alarm at once (or loop again if a drain is running). */
+  kick(body: DoKickBody): Promise<void>;
+  /** Scheduler role: wake at `at` (earlier wakes win), or exactly at `at` / never (`replace`). */
+  scheduleWake(body: DoWakeBody): Promise<void>;
+  /** Runs drain cycles until nothing more was asked for. Concurrent callers share the running cycle. */
+  run(): Promise<void>;
+  /** The current state (tests and debugging). */
+  state(): Promise<BotObjectState | null>;
+}
+/**
+ * A TelegramBotDO bound to one plugin instance (explicit wiring, or several plugins per tenant):
+ * `export const TelegramBotDO = createTelegramBotDO(telegram);`
+ */
+export declare function createTelegramBotDO<E>(plugin: BotDoHost): typeof TelegramBotDO<E>;

package/dist/do/telegram-bot-do.js

@@ -0,0 +1,219 @@
+import { sql } from "../ports/sql.js";
+import { TelegramConfigError } from "../engine/errors.js";
+import { registeredTelegramPlugin } from "../engine/outbox/do-registry.js";
+import { drainBot } from "../engine/outbox/drain.js";
+import { runWake } from "../engine/outbox/wake.js";
+// src/do/telegram-bot-do.ts
+/** Longest the object waits in-loop for the next due row; anything later is an alarm. */
+const DO_IDLE_WAIT_MS = 1500;
+/** How often the DO lease re-reads the bot row (status, pause) during a drain. */
+const BOT_REFRESH_MS = 5e3;
+const STATE_KEY = "tg:state";
+const minOf = (a, b) => a === null ? b : b === null ? a : Math.min(a, b);
+/** The object is the lease: it only re-reads the bot row now and then to notice a pause, 401 or removal. */
+function doLease(rt, botId) {
+	let bot = null;
+	let readAt = Number.NEGATIVE_INFINITY;
+	const read = async (now) => {
+		readAt = now;
+		bot = await rt.db.first(sql`SELECT * FROM tg_bot WHERE tenant = ${rt.tenant} AND id = ${botId} AND deleted_at IS NULL
+            AND status IN ('active', 'webhook_error') AND (paused_until IS NULL OR paused_until < ${now})`);
+		return bot;
+	};
+	return {
+		acquire: read,
+		renew: async (now) => now - readAt >= BOT_REFRESH_MS ? read(now) : bot,
+		release: async () => {}
+	};
+}
+function bodyOf(v) {
+	if (typeof v !== "object" || v === null) return null;
+	const o = v;
+	if (typeof o.tenant !== "string" || typeof o.botId !== "string" || o.botId === "") return null;
+	return {
+		tenant: o.tenant,
+		botId: o.botId
+	};
+}
+const json = (v, status = 200) => new Response(JSON.stringify(v), {
+	status,
+	headers: { "content-type": "application/json" }
+});
+/** Per-bot Durable Object: strict paced sender and per-bot scheduler. Export it from the Worker and bind it as `env.botDO`. */
+var TelegramBotDO = class {
+	ctx;
+	env;
+	#state;
+	#running = null;
+	#again = false;
+	constructor(ctx, env) {
+		this.ctx = ctx;
+		this.env = env;
+	}
+	/** The plugin that owns this object. Default: the one `createTelegramPlugin()` registered for the tenant. */
+	plugin(tenant) {
+		const host = registeredTelegramPlugin(tenant);
+		if (!host) throw new TelegramConfigError("TelegramBotDO: no plugin registered for this tenant (create the plugin at module scope, or use createTelegramBotDO(plugin))");
+		return host;
+	}
+	/** Wall-clock alarm time for a delay. Override only in tests (to drive alarms by hand). */
+	alarmTime(delayMs) {
+		return Date.now() + Math.max(0, delayMs);
+	}
+	/** Scheduler role: runs the per-bot wake stages; returns the next wake time. */
+	onWake(rt, botId, now) {
+		return runWake(rt, botId, now);
+	}
+	/** RPC over fetch: `POST /kick`, `POST /wake` (`{ tenant, botId, at, replace? }`), `GET /state`. Bad input → 400 JSON. */
+	async fetch(request) {
+		const url = new URL(request.url);
+		if (request.method === "GET" && url.pathname === "/state") return json(await this.#load());
+		if (request.method !== "POST") return json({ error: "method" }, 405);
+		let raw;
+		try {
+			raw = await request.json();
+		} catch {
+			return json({ error: "body" }, 400);
+		}
+		const body = bodyOf(raw);
+		if (!body) return json({ error: "body" }, 400);
+		if (url.pathname === "/kick") {
+			await this.kick(body);
+			return json({ ok: true });
+		}
+		if (url.pathname === "/wake") {
+			const { at, replace } = raw;
+			if (!(typeof at === "number" && Number.isFinite(at)) && !(replace === true && at === null)) return json({ error: "at" }, 400);
+			await this.scheduleWake({
+				...body,
+				at: at ?? null,
+				replace: replace === true
+			});
+			return json({ ok: true });
+		}
+		return json({ error: "not_found" }, 404);
+	}
+	/** Alarm handler: runs drain/wake cycles. */
+	async alarm() {
+		await this.run();
+	}
+	/** A drain is wanted now: arm the alarm at once (or loop again if a drain is running). */
+	async kick(body) {
+		const st = await this.#remember(body);
+		if (this.#running) {
+			this.#again = true;
+			return;
+		}
+		const rt = this.#runtime(st);
+		st.dueAt = rt.clock.now();
+		await this.#save(rt);
+	}
+	/** Scheduler role: wake at `at` (earlier wakes win), or exactly at `at` / never (`replace`). */
+	async scheduleWake(body) {
+		const st = await this.#remember(body);
+		st.wakeAt = body.replace === true ? body.at : minOf(st.wakeAt, body.at);
+		if (this.#running) {
+			this.#again = true;
+			return;
+		}
+		await this.#save(this.#runtime(st));
+	}
+	/** Runs drain cycles until nothing more was asked for. Concurrent callers share the running cycle. */
+	run() {
+		if (this.#running) {
+			this.#again = true;
+			return this.#running;
+		}
+		const loop = async () => {
+			try {
+				do {
+					this.#again = false;
+					await this.#cycle();
+				} while (this.#again);
+			} finally {
+				this.#running = null;
+			}
+		};
+		this.#running = loop();
+		return this.#running;
+	}
+	/** The current state (tests and debugging). */
+	async state() {
+		return this.#load();
+	}
+	async #cycle() {
+		const st = await this.#load();
+		if (!st) return;
+		const rt = this.#runtime(st);
+		const now = rt.clock.now();
+		if (st.wakeAt !== null && st.wakeAt <= now) {
+			st.wakeAt = null;
+			st.wakeAt = minOf(st.wakeAt, await this.onWake(rt, st.botId, now));
+		}
+		const r = await drainBot(rt, st.botId, {
+			lease: () => doLease(rt, st.botId),
+			strictPacing: true,
+			maxIdleWaitMs: DO_IDLE_WAIT_MS,
+			budgetMs: rt.limits.tickBudgetMs
+		});
+		st.dueAt = await this.#nextDue(rt, st.botId, r);
+		await this.#save(rt);
+	}
+	async #nextDue(rt, botId, r) {
+		const now = rt.clock.now();
+		switch (r.stoppedBy) {
+			case "budget":
+			case "cap": return now;
+			case "idle": return r.nextDueAt;
+			case "paused":
+			case "lease": {
+				if (r.nextDueAt === null) return null;
+				const bot = await rt.db.first(sql`SELECT paused_until FROM tg_bot WHERE tenant = ${rt.tenant} AND id = ${botId}
+                AND deleted_at IS NULL AND status IN ('active', 'webhook_error')`);
+				if (!bot) return null;
+				return Math.max(r.nextDueAt, bot.paused_until ?? 0, now);
+			}
+			default: return null;
+		}
+	}
+	#runtime(st) {
+		return this.plugin(st.tenant).runtime(this.env, { waitUntil: (p) => this.ctx.waitUntil(p) });
+	}
+	async #load() {
+		if (this.#state === void 0) this.#state = await this.ctx.storage.get(STATE_KEY) ?? null;
+		return this.#state;
+	}
+	async #remember(body) {
+		const st = await this.#load();
+		if (st && st.botId === body.botId && st.tenant === body.tenant) return st;
+		const fresh = {
+			tenant: body.tenant,
+			botId: body.botId,
+			dueAt: null,
+			wakeAt: null
+		};
+		this.#state = fresh;
+		return fresh;
+	}
+	/** Persists the state and arms the alarm at the earliest of `dueAt` / `wakeAt`. */
+	async #save(rt) {
+		const st = this.#state;
+		if (!st) return;
+		await this.ctx.storage.put(STATE_KEY, st);
+		const at = minOf(st.dueAt, st.wakeAt);
+		if (at === null) await this.ctx.storage.deleteAlarm();
+		else await this.ctx.storage.setAlarm(this.alarmTime(at - rt.clock.now()));
+	}
+};
+/**
+* A TelegramBotDO bound to one plugin instance (explicit wiring, or several plugins per tenant):
+* `export const TelegramBotDO = createTelegramBotDO(telegram);`
+*/
+function createTelegramBotDO(plugin) {
+	return class BoundTelegramBotDO extends TelegramBotDO {
+		plugin() {
+			return plugin;
+		}
+	};
+}
+export { TelegramBotDO, createTelegramBotDO, doLease };