@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/server/plugin.js

@@ -0,0 +1,247 @@
+import { FEATURE_KEYS } from "../contracts/features.js";
+import { BUILTIN_COMMANDS } from "../contracts/commands.js";
+import { systemClock } from "../adapters/clock.js";
+import { uuidv7Ids } from "../adapters/ids.js";
+import { BUILTIN_FILTERS } from "../core/template/filters.js";
+import { TelegramConfigError, toPluginError } from "../engine/errors.js";
+import { ensureState } from "../engine/state.js";
+import { createRegistry, jsonSchemaOf } from "../engine/registry.js";
+import { BUILTIN_MENU } from "../engine/dispatch/builtins.js";
+import { enqueueIntent, previewIntent } from "../services/send.js";
+import { resolveAiOptions, resolveFeatures, resolveInboundOptions } from "../engine/options.js";
+import { registerTelegramPlugin } from "../engine/outbox/do-registry.js";
+import { metricCount, metricTiming } from "../engine/metrics.js";
+import { handleQueueBatch } from "../engine/outbox/transport.js";
+import { kickEvents } from "../engine/events/kick.js";
+import { createTranslator } from "../engine/i18n.js";
+import { DEFAULT_CRONS, runCleanup, runRekey, runTick } from "../engine/jobs.js";
+import { selectTransport } from "../engine/outbox/select.js";
+import { createRuntime, defaultLimits, defaultRetention } from "../engine/runtime.js";
+import { buildRoutes } from "../routes/app.js";
+import { aiToolSpec } from "../services/ai-tool.js";
+import { emitEvent } from "../services/events.js";
+import { PLUGIN_VERSION } from "./version.js";
+// src/server/plugin.ts
+function validateOptions(o) {
+	if (typeof o.env !== "function") throw new TelegramConfigError("options.env must be a function (env) => ({ db, keyring, … })");
+	if (!o.ports?.actor || typeof o.ports.actor.fromRequest !== "function" || typeof o.ports.actor.forUser !== "function") throw new TelegramConfigError("ports.actor { fromRequest, forUser, forAudience, describe } is required");
+	if (typeof o.ports.authorize !== "function") throw new TelegramConfigError("ports.authorize is required");
+	const prefix = o.permissions?.prefix;
+	if (prefix !== void 0 && !/^[a-z][a-zA-Z0-9_.-]{0,31}$/.test(prefix)) throw new TelegramConfigError("permissions.prefix must match [a-z][a-zA-Z0-9_.-]{0,31}");
+	if (typeof o.transport === "string" && ![
+		"auto",
+		"cron",
+		"queue",
+		"do"
+	].includes(o.transport)) throw new TelegramConfigError("transport must be \"auto\", \"cron\", \"queue\", \"do\" or a factory");
+	for (const [k, v] of Object.entries(o.limits ?? {})) {
+		if (k === "plan") {
+			if (v !== "free" && v !== "paid") throw new TelegramConfigError("limits.plan must be \"free\" or \"paid\"");
+			continue;
+		}
+		if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) throw new TelegramConfigError(`limits.${k} must be a positive number`);
+	}
+	if (o.tenant !== void 0 && (typeof o.tenant !== "string" || o.tenant.length > 64)) throw new TelegramConfigError("tenant must be a string (≤ 64 chars)");
+	const log = o.ports.log;
+	if (typeof log === "string" && ![
+		"debug",
+		"info",
+		"warn",
+		"error",
+		"silent"
+	].includes(log)) throw new TelegramConfigError("ports.log must be a LogPort or \"debug\" | \"info\" | \"warn\" | \"error\" | \"silent\"");
+	for (const [name, f] of Object.entries(o.filters ?? {})) {
+		if (!/^[a-z][a-zA-Z0-9_]{0,31}$/.test(name)) throw new TelegramConfigError(`filters.${name}: name must match [a-z][a-zA-Z0-9_]{0,31}`);
+		if (Object.hasOwn(BUILTIN_FILTERS, name)) throw new TelegramConfigError(`filters.${name}: shadows a built-in filter`);
+		if (typeof f !== "function" && (typeof f !== "object" || f === null || typeof f.apply !== "function")) throw new TelegramConfigError(`filters.${name}: must be a function or defineFilter({ apply })`);
+	}
+}
+function filterMeta(name, f, builtin) {
+	const def = typeof f === "function" ? { apply: f } : f;
+	return {
+		name,
+		builtin,
+		minArgs: def.minArgs ?? 0,
+		maxArgs: def.maxArgs ?? null
+	};
+}
+/** Runs a programmatic API call so that only `TelegramPluginError`s leave it (others become `internal_error`). */
+async function guarded(op, make, run) {
+	let rt = null;
+	try {
+		rt = make();
+		return await run(rt);
+	} catch (e) {
+		const err = toPluginError(e);
+		if (err.code === "internal_error") rt?.log.error("tg.api_error", {
+			op,
+			error: e instanceof Error ? e.name : "unknown"
+		});
+		throw err;
+	}
+}
+/**
+* Builds the plugin: validates `options` once (throws `TelegramConfigError`), indexes the host definitions and
+* registers the instance for TelegramBotDO under its tenant. No I/O happens until a route, job or method runs.
+*/
+function createTelegramPlugin(options) {
+	validateOptions(options);
+	const features = resolveFeatures(options.features);
+	const registry = createRegistry(options);
+	const shared = {
+		options,
+		features,
+		limits: defaultLimits(options.limits),
+		retention: defaultRetention(options.retention),
+		registry,
+		ai: resolveAiOptions(options.ai),
+		inbound: resolveInboundOptions(options.inbound),
+		keyrings: /* @__PURE__ */ new Map(),
+		filters: Object.freeze({ ...options.filters }),
+		makeTransport: (rt, mapped) => selectTransport(rt, mapped, options.transport)
+	};
+	const runtime = (env, exec) => createRuntime(shared, env, exec);
+	registerTelegramPlugin({ runtime: (env, exec) => runtime(env, exec) }, options.tenant ?? "");
+	const i18n = createTranslator(options.ports.i18n ?? {
+		locales: ["en", "mr"],
+		defaultLocale: "en"
+	});
+	const settings = options.ports.settings ?? { timezone: "UTC" };
+	const localized = (key) => Object.fromEntries(i18n.locales.map((l) => [l, i18n.plain(l, key)]));
+	const metaValue = () => {
+		const builtinScope = (c) => BUILTIN_MENU.group.includes(c) ? [
+			"private",
+			"group",
+			"supergroup"
+		] : ["private"];
+		return {
+			pluginVersion: PLUGIN_VERSION,
+			schemaVersion: 2,
+			features: Object.fromEntries(FEATURE_KEYS.map((k) => [k, { enabled: features[k] }])),
+			locales: [...i18n.locales],
+			defaultLocale: i18n.defaultLocale,
+			timezone: settings.timezone,
+			providers: [...registry.providers.values()].map((p) => ({
+				key: p.key,
+				label: p.label,
+				permission: p.permission,
+				params: jsonSchemaOf(p.params),
+				variables: jsonSchemaOf(p.variables),
+				hasSample: typeof p.sample === "function"
+			})),
+			commands: [...BUILTIN_COMMANDS.map((c) => ({
+				command: c,
+				description: localized(`bot.cmd.${c}`),
+				builtin: true,
+				permission: null,
+				scope: builtinScope(c)
+			})), ...features.commands ? registry.commandList.map((c) => ({
+				command: c.command,
+				description: c.description,
+				builtin: false,
+				permission: c.permission,
+				scope: [...c.scope]
+			})) : []],
+			events: features.events ? [...registry.events.values()].map((e) => ({
+				key: e.key,
+				label: e.label,
+				payload: jsonSchemaOf(e.payload),
+				filterable: [...e.filterable]
+			})) : [],
+			actions: features.actions ? [...registry.actions.values()].map((a) => ({
+				key: a.key,
+				permission: a.permission,
+				confirm: a.confirm !== null
+			})) : [],
+			dialogs: features.dialogs ? [...registry.dialogs.values()].map((d) => ({
+				key: d.key,
+				permission: d.permission,
+				steps: d.steps.map((s) => s.id)
+			})) : [],
+			audiences: [...registry.audiences.values()].map((a) => ({
+				key: a.key,
+				label: a.label
+			})),
+			fileSources: [...registry.fileSources.keys()],
+			renderers: features.reports ? features.reportRenderers.length > 0 ? [...features.reportRenderers] : [.../* @__PURE__ */ new Set(["csv", ...(options.ports.renderers ?? []).map((r) => r.format)])] : [],
+			filters: [...Object.entries(BUILTIN_FILTERS).map(([n, f]) => filterMeta(n, f, true)), ...Object.entries(shared.filters).map(([n, f]) => filterMeta(n, f, false))],
+			userSearch: typeof options.ports.users?.search === "function",
+			permissions: []
+		};
+	};
+	const metaCache = metaValue();
+	const meta = () => structuredClone(metaCache);
+	const deps = {
+		runtime: (env, exec) => runtime(env, exec),
+		features,
+		errors: options.ports.errors,
+		schemaOk: /* @__PURE__ */ new WeakSet(),
+		schemaKey: (env) => {
+			const db = options.env(env).db;
+			return typeof db === "object" && db !== null ? db : void 0;
+		}
+	};
+	const routes = buildRoutes(deps, meta);
+	const crons = {
+		...DEFAULT_CRONS,
+		...options.crons
+	};
+	const job = (name, cron, description, run) => ({
+		name,
+		cron,
+		description,
+		run: async (ctx) => {
+			const rt = runtime(ctx.env, ctx.waitUntil ? { waitUntil: ctx.waitUntil } : void 0);
+			const started = rt.clock.now();
+			const r = await run(rt);
+			metricCount(rt, "tg.job", 1, {
+				job: name,
+				outcome: r.status
+			});
+			metricTiming(rt, "tg.job_ms", rt.clock.now() - started, { job: name });
+			return r;
+		}
+	});
+	return {
+		routes,
+		jobs: Object.freeze([
+			job("telegram:tick", crons.tick, "Telegram: sweep stuck updates, fire due work, drain the outbox", runTick),
+			job("telegram:cleanup", crons.cleanup, "Telegram: retention, expired codes, webhook health, menus", runCleanup),
+			job("telegram:rekey", crons.rekey, "Telegram: re-encrypt bot secrets on old key ids", runRekey)
+		]),
+		async queue(batch, env, ctx) {
+			return handleQueueBatch(runtime(env, ctx), batch, { deadLetterQueue: options.deadLetterQueue });
+		},
+		emit(event, payload, opts) {
+			try {
+				return emitEvent({
+					tenant: options.tenant ?? "",
+					enabled: features.events,
+					events: registry.events,
+					ids: options.ports.ids ?? uuidv7Ids(options.ports.clock),
+					now: () => (options.ports.clock ?? systemClock).now()
+				}, event, payload, opts);
+			} catch (e) {
+				throw toPluginError(e);
+			}
+		},
+		preview(env, intent, actor, opts) {
+			return guarded("preview", () => runtime(env), (rt) => previewIntent(rt, actor, intent, opts));
+		},
+		enqueue(env, intent, actor, opts) {
+			return guarded("enqueue", () => runtime(env), (rt) => enqueueIntent(rt, actor, intent, opts));
+		},
+		aiToolSpec(env, actor) {
+			return guarded("aiToolSpec", () => runtime(env), (rt) => aiToolSpec(rt, actor));
+		},
+		async kick(env, opts) {
+			await guarded("kick", () => runtime(env, opts?.ctx), (rt) => Promise.all([rt.transport.kick(opts?.botIds), kickEvents(rt)]));
+		},
+		meta,
+		async ensureState(env) {
+			return ensureState(runtime(env));
+		},
+		runtime
+	};
+}
+export { createTelegramPlugin };

package/dist/server/version.d.ts

@@ -0,0 +1,2 @@
+/** Kept equal to package.json `version` (a test checks it). Reported by `GET /admin/meta`. */
+export declare const PLUGIN_VERSION = "0.1.0";

package/dist/server/version.js

@@ -0,0 +1,4 @@
+// src/server/version.ts
+/** Kept equal to package.json `version` (a test checks it). Reported by `GET /admin/meta`. */
+const PLUGIN_VERSION = "0.1.0";
+export { PLUGIN_VERSION };

package/dist/services/ai-tool.d.ts

@@ -0,0 +1,26 @@
+/** `what` kinds of a `SendIntent` the AI tool offers. */
+export type AiSendKind = "text" | "record" | "template" | "report" | "file";
+/** One `ai_allowed` destination offered to the AI. */
+export interface AiToolDestination {
+  /** Destination slug used as `to: { destination }`. */
+  slug: string;
+  /** Display name. */
+  name: string;
+  /** Chat kind (`private`, `group`, `supergroup`, `channel`). */
+  kind: string;
+}
+/** A generic `send_to_telegram` tool definition for the host's LLM, scoped to one actor. */
+export interface AiToolSpec {
+  /** Tool name. */
+  name: "send_to_telegram";
+  /** Tool description for the model. */
+  description: string;
+  /** JSON Schema (draft 2020-12) of the tool input; it is a `SendIntent`. */
+  input_schema: Record<string, unknown>;
+  /** `ai_allowed` destinations this actor may use (empty without `telegram.send`). */
+  destinations: AiToolDestination[];
+  /** True when the actor has a linked private chat (`to: { me: true }` works). */
+  me: boolean;
+  /** Kinds available with the current features and registrations (`text` always). */
+  kinds: AiSendKind[];
+}

package/dist/services/ai-tool.js

@@ -0,0 +1,148 @@
+import { sql } from "../ports/sql.js";
+import { featureDisabled } from "../engine/errors.js";
+import { FILES_PORT_SOURCE, recordProviderKey } from "./send.js";
+// src/services/ai-tool.ts
+/**
+* The AI tool spec for `actor` (read-only: D1 reads, no Telegram calls). Throws `feature_disabled` unless
+* `features.ai` with `sendIntent` is on. Destinations need `telegram.send`.
+*/
+async function aiToolSpec(rt, actor) {
+	if (!rt.features.ai || !rt.features.aiSendIntent) throw featureDisabled("ai");
+	const allowed = await rt.can(actor, "telegram.send");
+	const rows = allowed ? await rt.db.all(sql`SELECT d.*, c.kind AS chat_kind FROM tg_destination d JOIN tg_chat c ON c.id = d.chat_ref
+            WHERE d.tenant = ${rt.tenant} AND d.deleted_at IS NULL AND d.ai_allowed = 1 AND c.status = 'active'
+            ORDER BY d.name LIMIT 100`) : [];
+	const userId = rt.describe(actor).userId;
+	const mine = allowed && userId ? await rt.db.first(sql`SELECT id FROM tg_chat WHERE tenant = ${rt.tenant} AND user_id = ${userId} AND kind = 'private'
+              AND status = 'active' LIMIT 1`) : null;
+	const destinations = rows.map((r) => ({
+		slug: r.slug,
+		name: r.name,
+		kind: r.chat_kind
+	}));
+	const recordTypes = [...rt.registry.providers.keys()].filter((k) => k.startsWith(recordProviderKey(""))).map((k) => k.slice(recordProviderKey("").length));
+	const kinds = ["text"];
+	if (recordTypes.length > 0) kinds.push("record");
+	if (rt.features.templates) kinds.push("template");
+	if (rt.features.templates && rt.features.reports) kinds.push("report");
+	if (rt.registry.fileSources.size > 0 || rt.files) kinds.push("file");
+	const to = [];
+	if (destinations.length > 0) to.push({
+		type: "object",
+		properties: { destination: {
+			type: "string",
+			enum: destinations.map((d) => d.slug)
+		} },
+		required: ["destination"],
+		additionalProperties: false
+	});
+	if (mine) to.push({
+		type: "object",
+		properties: { me: { const: true } },
+		required: ["me"],
+		additionalProperties: false
+	});
+	const what = [{
+		type: "object",
+		description: "A short plain-text message you write. No links outside the app, no prices unless allowed.",
+		properties: { text: {
+			type: "string",
+			minLength: 1,
+			maxLength: rt.ai.maxTextLength
+		} },
+		required: ["text"],
+		additionalProperties: false
+	}];
+	if (kinds.includes("record")) what.push({
+		type: "object",
+		description: "An app record (for example an order), shown with the fields the recipients may see.",
+		properties: { record: {
+			type: "object",
+			properties: {
+				type: {
+					type: "string",
+					enum: recordTypes
+				},
+				key: {
+					type: "string",
+					minLength: 1,
+					maxLength: 128
+				},
+				fields: {
+					type: "array",
+					items: { type: "string" },
+					maxItems: 50
+				}
+			},
+			required: ["type", "key"],
+			additionalProperties: false
+		} },
+		required: ["record"],
+		additionalProperties: false
+	});
+	if (kinds.includes("template")) what.push({
+		type: "object",
+		description: "A saved message template by key, with optional params.",
+		properties: {
+			template: { type: "string" },
+			params: { type: "object" }
+		},
+		required: ["template"],
+		additionalProperties: false
+	});
+	if (kinds.includes("report")) what.push({
+		type: "object",
+		description: "A report file made from a report template.",
+		properties: {
+			report: { type: "string" },
+			params: { type: "object" },
+			format: {
+				type: "string",
+				enum: ["pdf", "csv"]
+			}
+		},
+		required: ["report", "format"],
+		additionalProperties: false
+	});
+	if (kinds.includes("file")) what.push({
+		type: "object",
+		description: "An existing app file.",
+		properties: { file: {
+			type: "object",
+			properties: {
+				source: {
+					type: "string",
+					enum: [...rt.registry.fileSources.keys(), ...rt.files ? [FILES_PORT_SOURCE] : []]
+				},
+				ref: { type: "string" }
+			},
+			required: ["source", "ref"],
+			additionalProperties: false
+		} },
+		required: ["file"],
+		additionalProperties: false
+	});
+	return {
+		name: "send_to_telegram",
+		description: "Propose sending something to a Telegram chat. Nothing is sent until the user confirms the preview. " + (to.length === 0 ? "There are no Telegram destinations available to you right now." : `Destinations: ${[...destinations.map((d) => `${d.slug} (${d.name})`), ...mine ? ["me (your own chat)"] : []].join(", ")}.`),
+		input_schema: {
+			$schema: "https://json-schema.org/draft/2020-12/schema",
+			type: "object",
+			properties: {
+				to: to.length === 1 ? to[0] : { oneOf: to },
+				what: { oneOf: what },
+				note: {
+					type: "string",
+					maxLength: 500,
+					description: "Optional short note sent with a record or file."
+				}
+			},
+			required: ["to", "what"],
+			additionalProperties: false
+		},
+		destinations,
+		me: mine !== null,
+		kinds
+	};
+}
+export { aiToolSpec };