@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/engine/events/tick.js

@@ -0,0 +1,208 @@
+import { nextBackoff, throttleKey } from "../../core/pacing.js";
+import { topics } from "../../core/recipients.js";
+import { sql } from "../../ports/sql.js";
+import { isTelegramPluginError } from "../errors.js";
+import { templateById, templateModel } from "../content/template-rows.js";
+import { matchFilters } from "./filters.js";
+import { payloadVarsFor } from "./payload.js";
+import { TRANSIENT_FANOUT_ERRORS, fanOut } from "../content/fanout.js";
+import { resolveRecipients } from "../content/recipients.js";
+import { eventProvider, eventRuleModel } from "../../services/event-rules.js";
+// src/engine/events/tick.ts
+/** How long a claimed event stays with one processor before another may re-claim it. */
+const EVENT_CLAIM_MS = 12e4;
+/** Pending events that are due (no backoff, or its time has come), or processing ones with an expired claim. */
+function claimableEvents(rt, now) {
+	return sql`tenant = ${rt.tenant} AND ((status = 'pending' AND (claim_until IS NULL OR claim_until <= ${now}))
+    OR (status = 'processing' AND claim_until < ${now}))`;
+}
+/** Atomically claims up to `limits.eventClaim` due events. */
+async function claimEvents(rt, now, token) {
+	const claimable = claimableEvents(rt, now);
+	return rt.db.all(sql`UPDATE tg_event SET status = 'processing', claim_until = ${now + EVENT_CLAIM_MS}, claim_token = ${token},
+          attempts = attempts + 1
+        WHERE id IN (SELECT id FROM tg_event WHERE ${claimable} ORDER BY occurred_at, id LIMIT ${rt.limits.eventClaim})
+          AND ${claimable}
+        RETURNING id, event, payload_json, occurred_at, attempts`);
+}
+/**
+* Throttle as one conditional upsert in `tg_state` (`thr:<rule>:<value>` → last event id, `updated_at` = its
+* time). It passes when the key is new, its window has passed, or this same event took it (re-processing after a
+* crash), so two processors can never both pass in one window.
+*/
+async function takeThrottle(rt, rule, ev, payload) {
+	if (!rule.throttle) return true;
+	const key = throttleKey(rule.id, rule.throttle, payload);
+	const since = ev.occurred_at - rule.throttle.perMinutes * 6e4;
+	return (await rt.db.all(sql`INSERT INTO tg_state (tenant, key, value, updated_at) VALUES (${rt.tenant}, ${key}, ${ev.id}, ${ev.occurred_at})
+        ON CONFLICT (tenant, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+        WHERE tg_state.updated_at <= ${since} OR tg_state.value = excluded.value
+        RETURNING key`)).length > 0;
+}
+async function rulesFor(rt, events) {
+	const out = /* @__PURE__ */ new Map();
+	const keys = [...new Set(events)];
+	if (keys.length === 0) return out;
+	const rows = await rt.db.all(sql`SELECT * FROM tg_event_rule WHERE tenant = ${rt.tenant} AND event IN (${sql.join(keys)})
+          AND enabled = 1 AND deleted_at IS NULL ORDER BY created_at, id`);
+	for (const r of rows) out.set(r.event, [...out.get(r.event) ?? [], eventRuleModel(r)]);
+	return out;
+}
+const ignored = (error) => ({
+	status: "ignored",
+	error,
+	botIds: [],
+	deliveries: 0,
+	retry: false
+});
+async function processOne(rt, ev, rules, templates) {
+	const def = rt.registry.events.get(ev.event);
+	if (!def) return ignored("event_unknown");
+	let raw;
+	try {
+		raw = JSON.parse(ev.payload_json);
+	} catch {
+		return ignored("payload_invalid");
+	}
+	const parsed = def.payload.safeParse(raw);
+	if (!parsed.success) return ignored("payload_invalid");
+	const payload = parsed.data;
+	const errors = /* @__PURE__ */ new Set();
+	const botIds = /* @__PURE__ */ new Set();
+	let deliveries = 0;
+	for (const rule of rules) {
+		if (!matchFilters(rule.filters, payload)) continue;
+		let template = templates.get(rule.templateId);
+		if (template === void 0) {
+			const row = await templateById(rt, rule.templateId);
+			template = row ? templateModel(row) : null;
+			templates.set(rule.templateId, template);
+		}
+		if (!template) {
+			rt.log.warn("tg.event_rule_template_missing", {
+				rule: rule.id,
+				code: "not_found"
+			});
+			errors.add("template_missing");
+			continue;
+		}
+		if (!await takeThrottle(rt, rule, ev, payload)) continue;
+		const now = rt.clock.now();
+		const recipients = await resolveRecipients(rt, rule.recipients, {
+			topic: topics.event(def.key),
+			now
+		});
+		if (recipients.send.length + recipients.held.length === 0) continue;
+		const r = await fanOut(rt, {
+			template,
+			provider: eventProvider(def, template, payload),
+			recipients,
+			personalize: true,
+			source: "event",
+			sourceId: ev.id,
+			dedupeKey: (chat) => `evt:${ev.id}:${rule.id}:${chat.chatRef}${chat.messageThreadId ? `#${chat.messageThreadId}` : ""}`,
+			now,
+			tz: rt.settings.timezone,
+			vars: (aud) => payloadVarsFor(rt, def, payload, aud.actor),
+			meta: {
+				event: def.key,
+				rule: rule.id
+			}
+		});
+		deliveries += r.deliveries;
+		for (const e of r.errors) errors.add(e);
+		if (r.chats > 0) for (const c of [...recipients.send, ...recipients.held.map((h) => h.chat)]) botIds.add(c.botId);
+	}
+	const error = errors.size > 0 ? [...errors].join(",").slice(0, 200) : null;
+	const retry = [...errors].some((e) => TRANSIENT_FANOUT_ERRORS.includes(e));
+	return {
+		status: "done",
+		error,
+		botIds: [...botIds],
+		deliveries,
+		retry
+	};
+}
+/** Claims and processes due events. Safe to run concurrently (claims + dedupe keys + the throttle upsert). */
+async function runEvents(rt, now) {
+	const result = {
+		claimed: 0,
+		done: 0,
+		ignored: 0,
+		failed: 0,
+		retried: 0,
+		deliveries: 0
+	};
+	if (!rt.features.events) return result;
+	const token = rt.ids.uuid();
+	const claimed = await claimEvents(rt, now, token);
+	result.claimed = claimed.length;
+	if (claimed.length === 0) return result;
+	const rules = await rulesFor(rt, claimed.map((e) => e.event));
+	const templates = /* @__PURE__ */ new Map();
+	const botIds = /* @__PURE__ */ new Set();
+	const started = rt.clock.now();
+	const budget = rt.limits.tickBudgetMs / 2;
+	const fenced = (id) => sql`WHERE tenant = ${rt.tenant} AND id = ${id} AND claim_token = ${token}`;
+	/** Puts the event back to `pending` with a backoff, or ends it as `finalStatus` after the last attempt. */
+	const backOff = async (ev, finalStatus, code) => {
+		const final = ev.attempts >= 5;
+		const at = rt.clock.now();
+		const notBefore = final ? null : at + nextBackoff(ev.attempts - 1, Math.random);
+		await rt.db.run(sql`UPDATE tg_event SET status = ${final ? finalStatus : "pending"}, error = ${code.slice(0, 200)},
+            claim_until = ${notBefore}, claim_token = NULL, processed_at = ${final ? at : null} ${fenced(ev.id)}`);
+		return final;
+	};
+	for (const [i, ev] of claimed.entries()) {
+		if (rt.clock.now() - started > budget) {
+			const rest = claimed.slice(i).map((e) => e.id);
+			await rt.db.run(sql`UPDATE tg_event SET status = 'pending', claim_until = NULL, claim_token = NULL, attempts = attempts - 1
+            WHERE tenant = ${rt.tenant} AND claim_token = ${token} AND id IN (${sql.join(rest)})`);
+			result.retried += rest.length;
+			break;
+		}
+		let outcome;
+		try {
+			outcome = await processOne(rt, ev, rules.get(ev.event) ?? [], templates);
+		} catch (e) {
+			const code = isTelegramPluginError(e) ? e.code : e instanceof Error ? e.name : "error";
+			rt.log.error("tg.event_failed", {
+				event: ev.event,
+				attempts: ev.attempts,
+				code
+			});
+			if (await backOff(ev, "failed", code)) result.failed++;
+			else result.retried++;
+			continue;
+		}
+		result.deliveries += outcome.deliveries;
+		for (const b of outcome.botIds) botIds.add(b);
+		if (outcome.retry && ev.attempts < 5) {
+			rt.log.warn("tg.event_retry", {
+				event: ev.event,
+				attempts: ev.attempts,
+				code: outcome.error ?? "error"
+			});
+			await backOff(ev, "done", outcome.error ?? "provider_error");
+			result.retried++;
+			continue;
+		}
+		if (outcome.retry) rt.log.warn("tg.event_retry_exhausted", {
+			event: ev.event,
+			attempts: ev.attempts
+		});
+		await rt.db.run(sql`UPDATE tg_event SET status = ${outcome.status}, error = ${outcome.error}, processed_at = ${rt.clock.now()},
+            claim_until = NULL, claim_token = NULL ${fenced(ev.id)}`);
+		if (outcome.status === "done") result.done++;
+		else result.ignored++;
+	}
+	if (botIds.size > 0 && rt.transport.name !== "outbox") await rt.transport.kick([...botIds]);
+	rt.log.info("tg.events", { ...result });
+	return result;
+}
+/** The tick stage (`tickStages()`): `runEvents` without the summary. */
+async function processEvents(rt, now) {
+	if (!rt.features.events) return;
+	await runEvents(rt, now);
+}
+export { EVENT_CLAIM_MS, claimableEvents, processEvents, runEvents };

package/dist/engine/i18n.d.ts

@@ -0,0 +1,12 @@
+export interface Translator {
+  /** HTML-safe text (variables escaped). */
+  t(locale: string, key: string, vars?: Record<string, unknown>): string;
+  /** Raw text (variables not escaped), for menus and plain-text fields. */
+  plain(locale: string, key: string, vars?: Record<string, unknown>): string;
+  /** First supported locale out of the candidates (exact, then language part), else the default. */
+  pick(...candidates: (string | null | undefined)[]): string;
+  /** The supported locale for a tag (exact, then language part), or null. */
+  match(candidate: string | null | undefined): string | null;
+  readonly locales: readonly string[];
+  readonly defaultLocale: string;
+}

package/dist/engine/i18n.js

@@ -0,0 +1,55 @@
+import { escapeHtml } from "../core/html/escape.js";
+import en_default from "../locales/en.js";
+import mr_default from "../locales/mr.js";
+// src/engine/i18n.ts
+const BUILTIN = {
+	en: en_default,
+	mr: mr_default
+};
+Object.keys(BUILTIN);
+function lookup(tree, key) {
+	let node = tree;
+	for (const part of key.split(".")) {
+		if (typeof node !== "object" || node === null) return void 0;
+		node = node[part];
+	}
+	return typeof node === "string" ? node : void 0;
+}
+function interpolate(text, vars, escapeVars) {
+	if (!vars) return text;
+	return text.replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g, (_, name) => {
+		const v = Object.hasOwn(vars, name) ? vars[name] : void 0;
+		const s = v === void 0 || v === null ? "" : String(v);
+		return escapeVars ? escapeHtml(s) : s;
+	});
+}
+function createTranslator(port) {
+	const locales = port.locales.length > 0 ? port.locales : ["en"];
+	const supported = new Set(locales);
+	const base = (locale, key, vars, escapeVars) => {
+		const host = port.t?.(locale, key, vars);
+		if (host !== void 0) return host;
+		return interpolate(lookup(BUILTIN[locale], key) ?? lookup(BUILTIN[locale.split("-")[0] ?? ""], key) ?? lookup(en_default, key) ?? key, vars, escapeVars);
+	};
+	const match = (c) => {
+		if (!c) return null;
+		if (supported.has(c)) return c;
+		const lang = c.split("-")[0]?.toLowerCase();
+		return lang && supported.has(lang) ? lang : null;
+	};
+	return {
+		locales,
+		defaultLocale: port.defaultLocale,
+		t: (locale, key, vars) => base(locale, key, vars, true),
+		plain: (locale, key, vars) => base(locale, key, vars, false),
+		match,
+		pick(...candidates) {
+			for (const c of candidates) {
+				const m = match(c);
+				if (m) return m;
+			}
+			return port.defaultLocale;
+		}
+	};
+}
+export { createTranslator };

package/dist/engine/inbound/files.js

@@ -0,0 +1,121 @@
+import { settle } from "../../telegram/classify.js";
+import { withToken } from "../bot-api.js";
+// src/engine/inbound/files.ts
+function inboundKind(message) {
+	if (message?.photo && message.photo.length > 0) return "photo";
+	if (message?.document) return "document";
+	return null;
+}
+function mimeAllowed(allow, mime) {
+	const m = mime.toLowerCase();
+	return allow.some((a) => {
+		const p = a.toLowerCase();
+		return p.endsWith("*") ? m.startsWith(p.slice(0, -1)) : m === p;
+	});
+}
+/** No path separators or control characters in stored names. */
+function safeName(name) {
+	return Array.from(name, (ch) => ch === "/" || ch === "\\" || ch.charCodeAt(0) < 32 ? "_" : ch).join("").slice(0, 128);
+}
+function pick(message, maxBytes) {
+	if (message.photo && message.photo.length > 0) {
+		const fit = [...message.photo].sort((a, b) => (b.file_size ?? 0) - (a.file_size ?? 0)).find((p) => (p.file_size ?? 0) <= maxBytes);
+		if (!fit) return "too_large";
+		return {
+			kind: "photo",
+			fileId: fit.file_id,
+			name: `photo-${message.message_id}.jpg`,
+			mime: "image/jpeg",
+			size: fit.file_size ?? null
+		};
+	}
+	const d = message.document;
+	if (!d) return null;
+	return {
+		kind: "document",
+		fileId: d.file_id,
+		name: safeName(d.file_name ?? `file-${message.message_id}`),
+		mime: d.mime_type ?? "application/octet-stream",
+		size: d.file_size ?? null
+	};
+}
+/** Downloads the message's photo / document and stores it as `actor`. Never throws for user-caused problems. */
+async function storeInbound(ctx, actor, tags) {
+	const { rt } = ctx;
+	const message = ctx.message;
+	if (!message) return {
+		ok: false,
+		reason: "unavailable"
+	};
+	const files = rt.files;
+	if (!files) return {
+		ok: false,
+		reason: "unavailable"
+	};
+	const max = rt.inbound.maxBytes;
+	const p = pick(message, max);
+	if (p === null) return {
+		ok: false,
+		reason: "unavailable"
+	};
+	if (p === "too_large" || p.size !== null && p.size > max) return {
+		ok: false,
+		reason: "too_large"
+	};
+	if (p.kind === "document" && !mimeAllowed(rt.inbound.mimeTypes, p.mime)) return {
+		ok: false,
+		reason: "type_not_allowed"
+	};
+	const bytes = await withToken(rt, ctx.bot, async (api) => {
+		const info = await settle(api.getFile({ file_id: p.fileId }));
+		if (info.outcome.kind !== "ok" || !info.value?.file_path) return null;
+		if ((info.value.file_size ?? 0) > max) return "too_large";
+		try {
+			const res = await api.downloadFile(info.value.file_path);
+			if (!res.ok) return null;
+			const buf = new Uint8Array(await res.arrayBuffer());
+			return buf.byteLength > max ? "too_large" : buf;
+		} catch {
+			return null;
+		}
+	});
+	if (bytes === "too_large") return {
+		ok: false,
+		reason: "too_large"
+	};
+	if (bytes === null) {
+		rt.log.warn("tg.inbound_download_failed", { botId: ctx.bot.id });
+		return {
+			ok: false,
+			reason: "download_failed"
+		};
+	}
+	const stored = await files.put({
+		name: p.name,
+		mime: p.mime,
+		body: bytes,
+		tags: {
+			source: "telegram",
+			kind: p.kind,
+			...tags
+		}
+	}, actor);
+	rt.log.info("tg.inbound_stored", {
+		botId: ctx.bot.id,
+		kind: p.kind,
+		size: bytes.byteLength
+	});
+	return {
+		ok: true,
+		file: {
+			...stored,
+			kind: p.kind,
+			caption: message.caption ?? null
+		}
+	};
+}
+/** The bot string for a failed store. */
+function storeFailureKey(reason) {
+	return `bot.inbound.${reason}`;
+}
+export { inboundKind, storeFailureKey, storeInbound };

package/dist/engine/inbound/handler.js

@@ -0,0 +1,46 @@
+import { hostCan } from "../content/providers.js";
+import { storeFailureKey, storeInbound } from "./files.js";
+import { hostContext, senderMayAct } from "../dispatch/context.js";
+// src/engine/inbound/handler.ts
+async function inboundHandler(ctx) {
+	const { rt } = ctx;
+	if (ctx.cls !== "media" || !rt.features.inbound) return "next";
+	const actor = await ctx.actor();
+	if (actor === null) {
+		await ctx.reply(await ctx.t(ctx.tgChat?.type === "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";
+	}
+	if (!await hostCan(rt, actor, rt.inbound.permission)) {
+		await ctx.reply(await ctx.t("bot.error.forbidden"));
+		return "handled";
+	}
+	const onInbound = rt.hooks.onInbound;
+	if (!onInbound) {
+		await ctx.reply(await ctx.t("bot.inbound.not_handled"));
+		return "handled";
+	}
+	const stored = await storeInbound(ctx, actor, { source_kind: "inbound" });
+	if (!stored.ok) {
+		await ctx.reply(await ctx.t(storeFailureKey(stored.reason)));
+		return "handled";
+	}
+	const host = await hostContext(ctx, stored.file.caption ?? "");
+	let handled = true;
+	try {
+		handled = await onInbound(host, stored.file) !== false;
+	} catch (e) {
+		rt.log.warn("tg.hook_error", {
+			hook: "onInbound",
+			error: e instanceof Error ? e.name : "unknown"
+		});
+		await ctx.reply(await ctx.t("bot.error.generic"));
+		return "handled";
+	}
+	if (!handled) await ctx.reply(await ctx.t("bot.inbound.not_handled"));
+	return "handled";
+}
+export { inboundHandler };

package/dist/engine/jobs.d.ts

@@ -0,0 +1,32 @@
+/** What a plugin job's `run` receives from the host's cron dispatcher. */
+export interface TelegramJobContext<E> {
+  /** The Worker env of the scheduled invocation. */
+  env: E;
+  /** Scheduled time (ms or Date); default now. */
+  now?: number | Date;
+  /** `ctx.waitUntil` of the scheduled event, for hook and kick work. */
+  waitUntil?: (p: Promise<unknown>) => void;
+  /** The cron expression that fired (informational). */
+  cron?: string;
+}
+/** Outcome of one job run (for the host's job log). */
+export interface TelegramJobResult {
+  /** `ok` = did work, `noop` = nothing to do, `skipped` = not run (for example `schema_outdated`). */
+  status: "ok" | "noop" | "skipped";
+  /** Short summary without personal data (`sent 3`, `deleted 12…`). */
+  detail?: string;
+}
+/**
+ * A plugin cron job (`telegram:tick`, `telegram:cleanup`, `telegram:rekey`), structural so it fits a host `Job`
+ * registry. Every job checks the schema version first and skips when it is outdated.
+ */
+export interface TelegramJob<E> {
+  /** Job name (`telegram:tick`, …). */
+  readonly name: string;
+  /** Cron expression (`options.crons`); the Worker's `triggers.crons` must include it. */
+  readonly cron: string;
+  /** One-line description for admin job lists. */
+  readonly description: string;
+  /** Runs the job: D1 reads/writes and, for the tick, Telegram sends. */
+  run(ctx: TelegramJobContext<E>): Promise<TelegramJobResult>;
+}

package/dist/engine/jobs.js

@@ -0,0 +1,85 @@
+import { STATE_KEYS, ensureState, setState } from "./state.js";
+import { sweepStuckUpdates } from "./dispatch/dispatcher.js";
+import { processEvents } from "./events/tick.js";
+import { drainBots } from "./outbox/transport.js";
+import { cleanup } from "../services/cleanup.js";
+import { rekeyBots } from "../services/rekey.js";
+import { resumeStuckRuns } from "./schedules/resume.js";
+import { fireDueSchedules } from "./schedules/tick.js";
+import { armScheduleWake } from "./schedules/wake.js";
+// src/engine/jobs.ts
+/**
+* Schedules stage: fire what is due (under the DO transport re-arm the scheduler bot after a fire), then resume
+* runs cut off mid fan-out (`schedules/resume.ts`).
+*/
+async function scheduleStage(rt, now) {
+	if (await fireDueSchedules(rt, now) > 0) await armScheduleWake(rt);
+	await resumeStuckRuns(rt, now);
+}
+function tickStages() {
+	return [scheduleStage, processEvents];
+}
+const DEFAULT_CRONS = {
+	tick: "* * * * *",
+	cleanup: "15 3 * * *",
+	rekey: "45 3 * * *"
+};
+async function runTick(rt) {
+	const started = rt.clock.now();
+	const schema = await ensureState(rt);
+	if (!schema.ok) {
+		rt.log.error("tg.schema_outdated", {
+			required: schema.required,
+			current: schema.current
+		});
+		return {
+			status: "skipped",
+			detail: "schema_outdated"
+		};
+	}
+	await setState(rt, STATE_KEYS.lastTickAt, String(started), started);
+	const swept = await sweepStuckUpdates(rt, started);
+	for (const stage of tickStages()) try {
+		await stage(rt, rt.clock.now());
+	} catch (e) {
+		rt.log.error("tg.tick_stage_failed", { error: e instanceof Error ? e.name : "error" });
+	}
+	let sent = 0;
+	if (rt.transport.name === "queue" || rt.transport.name === "do") await rt.transport.kick();
+	else {
+		const left = rt.limits.tickBudgetMs - (rt.clock.now() - started);
+		for (const r of await drainBots(rt, void 0, left)) sent += r.sent;
+	}
+	rt.log.info("tg.tick", {
+		swept,
+		sent,
+		ms: rt.clock.now() - started
+	});
+	return {
+		status: sent > 0 || swept > 0 ? "ok" : "noop",
+		detail: `sent ${sent}`
+	};
+}
+async function runCleanup(rt) {
+	if (!(await ensureState(rt)).ok) return {
+		status: "skipped",
+		detail: "schema_outdated"
+	};
+	const r = await cleanup(rt);
+	return {
+		status: "ok",
+		detail: `deleted ${Object.values(r.deleted).reduce((a, b) => a + b, 0)}, bodies ${r.bodiesCleared}, bots ${r.botsChecked}`
+	};
+}
+async function runRekey(rt) {
+	if (!(await ensureState(rt)).ok) return {
+		status: "skipped",
+		detail: "schema_outdated"
+	};
+	const r = await rekeyBots(rt);
+	return {
+		status: r.rekeyed > 0 ? "ok" : "noop",
+		detail: `rekeyed ${r.rekeyed}, remaining ${r.remaining}`
+	};
+}
+export { DEFAULT_CRONS, runCleanup, runRekey, runTick, tickStages };

package/dist/engine/link-codes.js

@@ -0,0 +1,46 @@
+import { randomCode, sha256Hex } from "../core/random.js";
+import { z } from "zod";
+// src/engine/link-codes.ts
+function newLinkCode(rand) {
+	return randomCode(rand, 32);
+}
+function hashLinkCode(code) {
+	return sha256Hex(crypto.subtle, `tg-link:${code}`);
+}
+/** `tg_state` key prefix of pending invites. */
+const PENDING_LINK_PREFIX = "link_pending:";
+/** How long a redeemed invite waits for the target user's confirmation. */
+const PENDING_LINK_TTL_MS = 864e5;
+/** `tg_state` key of one pending invite. */
+function pendingLinkKey(id) {
+	return `${PENDING_LINK_PREFIX}${id}`;
+}
+/** Stored value of a pending invite (`tg_state.value`, JSON). */
+const PendingLinkState = z.object({
+	id: z.string(),
+	botId: z.string(),
+	/** Telegram chat id of the private chat that redeemed the code. */
+	chatId: z.string(),
+	/** `tg_chat.id` to use (the existing row's id, or a fresh one). */
+	chatRef: z.string(),
+	userId: z.string(),
+	createdBy: z.string().nullable(),
+	tgName: z.string().nullable(),
+	tgUsername: z.string().nullable(),
+	locale: z.string().nullable(),
+	createdAt: z.number(),
+	expiresAt: z.number()
+});
+/** API view of a pending invite (`GET /me/links/pending`, `hooks.onPendingLink`). */
+function pendingLinkDto(p) {
+	return {
+		id: p.id,
+		bot: p.botId,
+		telegramName: p.tgName,
+		telegramUsername: p.tgUsername,
+		invitedBy: p.createdBy,
+		createdAt: p.createdAt,
+		expiresAt: p.expiresAt
+	};
+}
+export { PENDING_LINK_PREFIX, PENDING_LINK_TTL_MS, PendingLinkState, hashLinkCode, newLinkCode, pendingLinkDto, pendingLinkKey };

package/dist/engine/metrics.js

@@ -0,0 +1,12 @@
+// src/engine/metrics.ts
+function metricCount(rt, name, n = 1, tags = {}) {
+	try {
+		rt.metrics?.count(name, n, tags);
+	} catch {}
+}
+function metricTiming(rt, name, ms, tags = {}) {
+	try {
+		rt.metrics?.timing(name, ms, tags);
+	} catch {}
+}
+export { metricCount, metricTiming };