@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/engine/registry.js

@@ -0,0 +1,258 @@
+import { Key, LocalizedText } from "../contracts/common.js";
+import { BUILTIN_COMMANDS, CommandName } from "../contracts/commands.js";
+import { TelegramConfigError } from "./errors.js";
+import { z } from "zod";
+// src/engine/registry.ts
+/** `defaultRoles` / per-bot roles entry meaning "any role". */
+const ANY_ROLE = "*";
+/** Names the plugin answers itself; host commands may not reuse them. */
+const RESERVED_COMMANDS = [
+	...BUILTIN_COMMANDS,
+	"here",
+	"cancel",
+	"skip",
+	"report"
+];
+function fail(what, msg) {
+	throw new TelegramConfigError(`${what}: ${msg}`);
+}
+function checkKey(what, key) {
+	if (!Key.safeParse(key).success) fail(what, `invalid key "${key}" (lowercase [a-z0-9._:-], ≤ 64)`);
+}
+function checkLabel(what, label) {
+	if (!LocalizedText.safeParse(label).success) fail(what, "label must be { en: '…', … } with at least one locale");
+}
+function checkPermission(what, permission) {
+	if (permission !== void 0 && (typeof permission !== "string" || permission.trim() === "")) fail(what, "permission must be a non-empty string");
+}
+function isZod(v) {
+	return v instanceof z.ZodType;
+}
+function objectKeys(schema) {
+	return schema instanceof z.ZodObject ? Object.keys(schema.shape) : null;
+}
+/** Validates and freezes a provider definition. Throws `TelegramConfigError` on an invalid key, label or schema. */
+function defineProvider(def) {
+	const what = `provider ${def.key}`;
+	checkKey(what, def.key);
+	checkLabel(what, def.label);
+	checkPermission(what, def.permission);
+	if (!isZod(def.variables)) fail(what, "variables must be a Zod schema");
+	if (def.params !== void 0 && !isZod(def.params)) fail(what, "params must be a Zod schema");
+	if (typeof def.run !== "function") fail(what, "run() is required");
+	const { sample, run } = def;
+	return Object.freeze({
+		key: def.key,
+		label: def.label,
+		params: def.params,
+		permission: def.permission ?? null,
+		variables: def.variables,
+		cacheFor: def.cacheFor ?? "none",
+		...sample ? { sample } : {},
+		run
+	});
+}
+/**
+* Validates and freezes a command definition. Throws `TelegramConfigError` on a bad or reserved name or alias, or
+* when not exactly one of `template` / `handle` is given.
+*/
+function defineCommand(def) {
+	const what = `command /${def.command}`;
+	if (!CommandName.safeParse(def.command).success) fail(what, "name must match [a-z0-9_]{1,32}");
+	if (RESERVED_COMMANDS.includes(def.command)) fail(what, "is a built-in command");
+	checkLabel(what, def.description);
+	checkPermission(what, def.permission);
+	if (def.args !== void 0 && !isZod(def.args)) fail(what, "args must be a Zod schema");
+	if (def.template === void 0 === (def.handle === void 0)) fail(what, "give exactly one of template or handle");
+	if (def.template !== void 0) checkKey(what, def.template);
+	for (const a of def.aliases ?? []) if (!CommandName.safeParse(a).success || RESERVED_COMMANDS.includes(a)) fail(what, `invalid alias "${a}"`);
+	const scope = def.scope ?? [
+		"private",
+		"group",
+		"supergroup"
+	];
+	if (scope.length === 0) fail(what, "scope is empty");
+	if (def.groupMembers !== void 0 && def.groupMembers !== "linked" && def.groupMembers !== "any") fail(what, "groupMembers must be \"linked\" or \"any\"");
+	const { parseArgs, handle } = def;
+	return Object.freeze({
+		command: def.command,
+		description: def.description,
+		permission: def.permission ?? null,
+		defaultRoles: Object.freeze([...def.defaultRoles ?? ["*"]]),
+		groupMembers: def.groupMembers,
+		args: def.args,
+		scope: Object.freeze(scope.includes("group") && !scope.includes("supergroup") ? [...scope, "supergroup"] : [...scope]),
+		template: def.template ?? null,
+		aliases: Object.freeze([...def.aliases ?? []]),
+		showInMenu: def.showInMenu ?? true,
+		sort: def.sort ?? 0,
+		...parseArgs ? { parseArgs } : {},
+		...handle ? { handle } : {}
+	});
+}
+/**
+* Validates and freezes an event definition. Throws `TelegramConfigError` on a bad key or label, or a
+* filterable / sensitive field missing from an object payload.
+*/
+function defineEvent(def) {
+	const what = `event ${def.key}`;
+	checkKey(what, def.key);
+	checkLabel(what, def.label);
+	if (!isZod(def.payload)) fail(what, "payload must be a Zod schema");
+	if (def.provider !== void 0) checkKey(what, def.provider);
+	const keys = objectKeys(def.payload);
+	for (const f of [...def.filterable ?? [], ...def.sensitive ?? []]) if (keys && !keys.includes(f)) fail(what, `field "${f}" is not in the payload schema`);
+	return Object.freeze({
+		key: def.key,
+		label: def.label,
+		payload: def.payload,
+		provider: def.provider ?? null,
+		filterable: Object.freeze([...def.filterable ?? []]),
+		sensitive: Object.freeze([...def.sensitive ?? []]),
+		sensitivePermission: def.sensitivePermission ?? null
+	});
+}
+/** Validates and freezes an action definition. Throws `TelegramConfigError` if invalid. */
+function defineAction(def) {
+	const what = `action ${def.key}`;
+	checkKey(what, def.key);
+	checkPermission(what, def.permission);
+	if (!isZod(def.params)) fail(what, "params must be a Zod schema");
+	if (def.confirm !== void 0) checkLabel(what, def.confirm);
+	if (def.result !== void 0) checkLabel(what, def.result);
+	if (typeof def.run !== "function") fail(what, "run() is required");
+	const ttl = def.ttlMinutes ?? 10080;
+	if (!Number.isInteger(ttl) || ttl < 1) fail(what, "ttlMinutes must be a positive integer");
+	const { run } = def;
+	return Object.freeze({
+		key: def.key,
+		permission: def.permission ?? null,
+		params: def.params,
+		confirm: def.confirm ?? null,
+		result: def.result ?? null,
+		singleUse: def.singleUse ?? true,
+		ttlMinutes: ttl,
+		run
+	});
+}
+/** Validates and freezes a dialog definition (unique step ids, positive timeout). Throws `TelegramConfigError`. */
+function defineDialog(def) {
+	const what = `dialog ${def.key}`;
+	checkKey(what, def.key);
+	checkPermission(what, def.permission);
+	if (!Array.isArray(def.steps) || def.steps.length === 0) fail(what, "needs at least one step");
+	const ids = /* @__PURE__ */ new Set();
+	const steps = def.steps.map((s) => {
+		if (!/^[a-zA-Z][a-zA-Z0-9_]{0,31}$/.test(s.id)) fail(what, `invalid step id "${s.id}"`);
+		if (ids.has(s.id)) fail(what, `duplicate step id "${s.id}"`);
+		ids.add(s.id);
+		checkLabel(`${what} step ${s.id}`, s.ask);
+		const input = s.input ?? "text";
+		if (typeof input !== "string" && !isZod(input)) fail(what, `step ${s.id}: input must be a Zod schema or a kind`);
+		const { choices } = s;
+		return Object.freeze({
+			id: s.id,
+			ask: s.ask,
+			input,
+			optional: s.optional ?? false,
+			...choices ? { choices } : {}
+		});
+	});
+	const timeout = def.timeoutMinutes ?? 30;
+	if (!Number.isInteger(timeout) || timeout < 1) fail(what, "timeoutMinutes must be a positive integer");
+	const { finish } = def;
+	return Object.freeze({
+		key: def.key,
+		permission: def.permission ?? null,
+		steps: Object.freeze(steps),
+		timeoutMinutes: timeout,
+		finish
+	});
+}
+/** Validates and freezes a recipient-kind definition. Throws `TelegramConfigError` if invalid. */
+function defineAudience(def) {
+	const what = `audience ${def.key}`;
+	if (!/^[a-zA-Z][a-zA-Z0-9_]{0,31}$/.test(def.key)) fail(what, "key must match [a-zA-Z][a-zA-Z0-9_]{0,31}");
+	checkLabel(what, def.label);
+	if (typeof def.resolve !== "function") fail(what, "resolve() is required");
+	const { resolve, audienceFor } = def;
+	return Object.freeze({
+		key: def.key,
+		label: def.label,
+		resolve,
+		...audienceFor ? { audienceFor } : {}
+	});
+}
+/** Validates and freezes a file-source definition. Throws `TelegramConfigError` if invalid. */
+function defineFileSource(def) {
+	const what = `file source ${def.key}`;
+	checkKey(what, def.key);
+	if (def.label !== void 0) checkLabel(what, def.label);
+	if (typeof def.resolve !== "function") fail(what, "resolve() is required");
+	const { resolve } = def;
+	return Object.freeze({
+		key: def.key,
+		label: def.label ?? null,
+		resolve
+	});
+}
+/**
+* All `define*` helpers typed for one host actor and (optionally) the Worker env type that every context's `env` has:
+* `const d = definitions<HostActor, Env>(); d.command({…})`.
+*/
+function definitions() {
+	return {
+		provider: (def) => defineProvider(def),
+		command: (def) => defineCommand(def),
+		event: (def) => defineEvent(def),
+		action: (def) => defineAction(def),
+		dialog: (def) => defineDialog(def),
+		audience: (def) => defineAudience(def),
+		fileSource: (def) => defineFileSource(def)
+	};
+}
+function index(kind, list, keyOf) {
+	const map = /* @__PURE__ */ new Map();
+	for (const item of list ?? []) {
+		if (typeof item !== "object" || item === null) throw new TelegramConfigError(`${kind}: entries must be define*()d`);
+		const key = keyOf(item);
+		if (map.has(key)) throw new TelegramConfigError(`${kind}: duplicate key "${key}"`);
+		map.set(key, item);
+	}
+	return map;
+}
+/** Indexes the host's definitions. Throws `TelegramConfigError` on duplicates or dangling references. */
+function createRegistry(input) {
+	const providers = index("providers", input.providers, (p) => p.key);
+	const commandList = input.commands ?? [];
+	const commands = index("commands", commandList, (c) => c.command);
+	for (const c of commandList) for (const alias of c.aliases) {
+		if (commands.has(alias)) throw new TelegramConfigError(`commands: alias "${alias}" is taken`);
+		commands.set(alias, c);
+	}
+	const events = index("events", input.events, (e) => e.key);
+	for (const e of events.values()) if (e.provider !== null && !providers.has(e.provider)) throw new TelegramConfigError(`event ${e.key}: provider "${e.provider}" is not registered`);
+	return {
+		providers,
+		commands,
+		commandList,
+		events,
+		actions: index("actions", input.actions, (a) => a.key),
+		dialogs: index("dialogs", input.dialogs, (d) => d.key),
+		audiences: index("audiences", input.audiences, (a) => a.key),
+		fileSources: index("fileSources", input.fileSources, (f) => f.key)
+	};
+}
+/** JSON Schema of a Zod schema for meta (never throws; unrepresentable parts become `{}`). */
+function jsonSchemaOf(schema) {
+	if (!schema) return {};
+	try {
+		return z.toJSONSchema(schema, {
+			unrepresentable: "any",
+			io: "input"
+		});
+	} catch {
+		return {};
+	}
+}
+export { ANY_ROLE, RESERVED_COMMANDS, createRegistry, defineAction, defineAudience, defineCommand, defineDialog, defineEvent, defineFileSource, defineProvider, definitions, jsonSchemaOf };

package/dist/engine/rows.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export interface BotRow {
+  id: string;
+  tenant: string;
+  name: string;
+  tg_bot_id: string;
+  username: string;
+  token_enc: string;
+  webhook_secret_enc: string | null;
+  mode: string;
+  status: string;
+  status_detail: string | null;
+  checked_at: number | null;
+  default_locale: string;
+  features_json: string | null;
+  rate_per_sec: number;
+  paused_until: number | null;
+  drain_lease_until: number | null;
+  drain_token: string | null;
+  commands_synced_hash: string | null;
+  created_by: string | null;
+  created_at: number;
+  updated_at: number;
+  deleted_at: number | null;
+}

package/dist/engine/rows.js

@@ -0,0 +1,131 @@
+import { BotDto, BotFeatures } from "../contracts/bots.js";
+import { Audience, ChatDto, ChatTopics } from "../contracts/chats.js";
+import { QuietHours } from "../contracts/subscriptions.js";
+// src/engine/rows.ts
+/** Parses a JSON column with a schema; null / invalid → `fallback`. */
+function parseJson(text, schema, fallback) {
+	if (text === null || text === void 0 || text === "") return fallback;
+	try {
+		const r = schema.safeParse(JSON.parse(text));
+		return r.success ? r.data : fallback;
+	} catch {
+		return fallback;
+	}
+}
+/** A JSON object column, or null when absent / invalid. */
+function parseObject(text) {
+	if (!text) return null;
+	try {
+		const v = JSON.parse(text);
+		return typeof v === "object" && v !== null && !Array.isArray(v) ? v : null;
+	} catch {
+		return null;
+	}
+}
+function botDto(r) {
+	return {
+		id: r.id,
+		name: r.name,
+		username: r.username,
+		tgBotId: r.tg_bot_id,
+		mode: r.mode === "polling" ? "polling" : "webhook",
+		status: BotDto.shape.status.safeParse(r.status).data ?? "active",
+		statusDetail: r.status_detail,
+		checkedAt: r.checked_at,
+		defaultLocale: r.default_locale,
+		features: parseJson(r.features_json, BotFeatures, {}),
+		ratePerSec: r.rate_per_sec,
+		pausedUntil: r.paused_until,
+		createdAt: r.created_at,
+		updatedAt: r.updated_at
+	};
+}
+function chatDto(r) {
+	return {
+		id: r.id,
+		botId: r.bot_id,
+		chatId: r.chat_id,
+		kind: ChatDto.shape.kind.safeParse(r.kind).data ?? "private",
+		title: r.title,
+		username: r.username,
+		userId: r.user_id,
+		audience: parseJson(r.audience_json, Audience.nullable(), null),
+		status: ChatDto.shape.status.safeParse(r.status).data ?? "pending",
+		locale: r.locale,
+		timezone: r.timezone,
+		topics: parseJson(r.topics_json, ChatTopics, {}),
+		linkedBy: r.linked_by,
+		linkedAt: r.linked_at,
+		updatedAt: r.updated_at
+	};
+}
+function destinationDto(r) {
+	return {
+		id: r.id,
+		name: r.name,
+		slug: r.slug,
+		botId: r.bot_id,
+		chatRef: r.chat_ref,
+		messageThreadId: r.message_thread_id,
+		aiAllowed: r.ai_allowed === 1,
+		createdAt: r.created_at
+	};
+}
+function subscriptionDto(r) {
+	return {
+		chatRef: r.chat_ref,
+		topic: r.topic,
+		muted: r.muted === 1,
+		quiet: parseJson(r.quiet_json, QuietHours.nullable(), null),
+		updatedAt: r.updated_at
+	};
+}
+const SOURCES = /* @__PURE__ */ new Set([
+	"schedule",
+	"event",
+	"broadcast",
+	"command",
+	"ai",
+	"api",
+	"system"
+]);
+const KINDS = /* @__PURE__ */ new Set([
+	"text",
+	"document",
+	"photo",
+	"edit",
+	"delete"
+]);
+const STATUSES = /* @__PURE__ */ new Set([
+	"queued",
+	"sending",
+	"sent",
+	"failed",
+	"dropped",
+	"cancelled"
+]);
+/** `withBody`: only for callers with `telegram.ops.content`. */
+function deliveryDto(r, withBody) {
+	return {
+		id: r.id,
+		botId: r.bot_id,
+		chatRef: r.chat_ref,
+		messageThreadId: r.message_thread_id,
+		source: SOURCES.has(r.source) ? r.source : "system",
+		sourceId: r.source_id,
+		kind: KINDS.has(r.kind) ? r.kind : "text",
+		bodyHtml: withBody ? r.body_html : null,
+		part: r.part,
+		parts: r.parts,
+		fileName: r.file_name,
+		status: STATUSES.has(r.status) ? r.status : "failed",
+		attempts: r.attempts,
+		nextAttemptAt: r.status === "queued" ? r.next_attempt_at : null,
+		tgMessageId: r.tg_message_id,
+		errorCode: r.error_code,
+		errorDetail: r.error_detail,
+		createdAt: r.created_at,
+		sentAt: r.sent_at
+	};
+}
+export { botDto, chatDto, deliveryDto, destinationDto, parseJson, parseObject, subscriptionDto };

package/dist/engine/runtime.d.ts

@@ -0,0 +1,95 @@
+import { PermissionName } from "../contracts/permissions.js";
+import { RandomFill } from "../core/random.js";
+import { FilterRegistry } from "../core/template/filters.js";
+import { DbPort } from "../ports/db.js";
+import { ActorInfo, ActorPort, AuditPort, AuthorizePort, ClockPort, ErrorsPort, FilesPort, IdsPort, KeyringPort, LogPort, MetricsPort, RendererPort, SettingsPort, TransportPort, UsersPort } from "../ports/ports.js";
+import { TelegramClient } from "../telegram/client.js";
+import { Translator } from "./i18n.js";
+import { Registry } from "./registry.js";
+import { FeatureFlags, ResolvedAiOptions, ResolvedGroupOptions, ResolvedInboundOptions, TelegramHooks, TelegramLimits, TelegramRetention } from "./options.js";
+/**
+ * The resolved ports and options for one invocation (request, job run or queue batch). Services and the engine
+ * take a `Runtime`; hosts get one from `plugin.runtime(env)` to call exported services directly or in tests.
+ */
+export interface Runtime<A> {
+  /** The raw Worker env of this invocation (what the `env` mapper received). */
+  readonly env: unknown;
+  /** Database port (`d1Db(env.db)` unless the mapper returned a `DbPort`). */
+  readonly db: DbPort;
+  /** Keyring for bot tokens and webhook secrets (built from `env.keyring`, cached per secret value). */
+  readonly keyring: KeyringPort;
+  /** Bot API client (`options.telegram`, default `fetchTelegram()`). */
+  readonly tg: TelegramClient;
+  /** Queue producer from `env.queue`, if any. */
+  readonly queue: Queue<unknown> | undefined;
+  /** Browser Rendering binding from `env.browser` (default pdf renderer), if any. */
+  readonly browser: unknown;
+  /** Without trailing slash, or null (polling mode). */
+  readonly publicBaseUrl: string | null;
+  /** `env.appEnv`, default `"production"` (disables the dev polling route). */
+  readonly appEnv: string;
+  /** Tenant column value (`options.tenant`, default `''`); every query is scoped to it. */
+  readonly tenant: string;
+  /** `ports.actor`. */
+  readonly actor: ActorPort<A>;
+  /** `ports.authorize`. */
+  readonly authorize: AuthorizePort<A>;
+  /** `ports.users`, if given. */
+  readonly users: UsersPort | undefined;
+  /** `ports.files` (or `r2Files(env.files)`), if available in this invocation. */
+  readonly files: FilesPort<A> | undefined;
+  /** `ports.audit`, default insert into `tg_audit`. */
+  readonly audit: AuditPort;
+  /** `ports.errors`, if given. */
+  readonly errors: ErrorsPort | undefined;
+  /** Resolved log port (`ports.log` or `consoleLog` at the given level). */
+  readonly log: LogPort;
+  /** `ports.clock`, default `systemClock`. */
+  readonly clock: ClockPort;
+  /** `ports.ids`, default `uuidv7Ids`. */
+  readonly ids: IdsPort;
+  /** Bot string translator (host `ports.i18n.t` first, then the plugin's `en`/`mr` strings). */
+  readonly i18n: Translator;
+  /** `ports.settings`, default `{ timezone: "UTC" }`. */
+  readonly settings: SettingsPort;
+  /** `ports.metrics`, if available in this invocation. */
+  readonly metrics: MetricsPort | undefined;
+  /** Host report renderers (`ports.renderers`); built-ins are added by `rendererFor`. */
+  readonly renderers: readonly RendererPort[];
+  /** Host template filters (`options.filters`). */
+  readonly filters: FilterRegistry;
+  /** Global feature flags (narrowed per bot inside bot-scoped work). */
+  readonly features: FeatureFlags;
+  /** `options.limits` over `DEFAULT_LIMITS`. */
+  readonly limits: TelegramLimits;
+  /** `options.retention` over `DEFAULT_RETENTION`. */
+  readonly retention: TelegramRetention;
+  /** The host definitions. */
+  readonly registry: Registry<A>;
+  /** `options.hooks` (call them through `hook()`). */
+  readonly hooks: TelegramHooks<A>;
+  /** `options.allowMultipleChatsPerUser`. */
+  readonly allowMultipleChatsPerUser: boolean;
+  /** AI bridge rules (options.ai, defaults applied). */
+  readonly ai: ResolvedAiOptions;
+  /** Inbound media limits (options.inbound, defaults applied). */
+  readonly inbound: ResolvedInboundOptions;
+  /** Group rules (options.groups, defaults applied). */
+  readonly groups: ResolvedGroupOptions;
+  /** Drain transport chosen by `options.transport`. */
+  readonly transport: TransportPort;
+  /** Fills a buffer with secure random bytes (`crypto.getRandomValues`). */
+  readonly rand: RandomFill;
+  /** Full permission name with the host prefix. */
+  perm(name: PermissionName): string;
+  /** `authorize` for a plugin permission. */
+  can(actor: A, name: PermissionName, resource?: unknown): Promise<boolean>;
+  /** `ports.actor.describe`. */
+  describe(actor: A): ActorInfo;
+  /** `clock.sleep`, else a real `setTimeout` wait. */
+  sleep(ms: number): Promise<void>;
+  /** Background work (ctx.waitUntil, or awaited-later promises when there is no execution context). */
+  waitUntil(p: Promise<unknown>): void;
+  /** Runs a hook; errors are logged and swallowed. */
+  hook<K extends keyof TelegramHooks<A>>(name: K, run: (fn: NonNullable<TelegramHooks<A>[K]>) => unknown): Promise<void>;
+}

package/dist/engine/runtime.js

@@ -0,0 +1,149 @@
+import { permissionName } from "../contracts/permissions.js";
+import { systemClock } from "../adapters/clock.js";
+import { consoleLog, silentLog } from "../adapters/console-log.js";
+import { d1Db } from "../adapters/d1-db.js";
+import { uuidv7Ids } from "../adapters/ids.js";
+import { r2Files } from "../adapters/r2-files.js";
+import { webCryptoKeyring } from "../adapters/keyring.js";
+import { sql } from "../ports/sql.js";
+import { DEFAULT_LIMITS, DEFAULT_RETENTION, resolveGroupOptions } from "./options.js";
+import { fetchTelegram } from "../telegram/client.js";
+import { createTranslator } from "./i18n.js";
+// src/engine/runtime.ts
+function isDbPort(db) {
+	return typeof db.all === "function" && typeof db.run === "function";
+}
+function isKeyringPort(k) {
+	return typeof k === "object" && k !== null && typeof k.encrypt === "function";
+}
+function isClient(t) {
+	return typeof t === "object" && t !== null && typeof t.bot === "function";
+}
+function defaultLimits(input) {
+	return {
+		...DEFAULT_LIMITS,
+		...input
+	};
+}
+function defaultRetention(input) {
+	return {
+		...DEFAULT_RETENTION,
+		...input
+	};
+}
+/** `ports.log` → a `LogPort` (default: `consoleLog` at `info`). */
+function resolveLog(log) {
+	if (log === void 0) return consoleLog();
+	if (log === "silent") return silentLog;
+	if (typeof log === "string") return consoleLog({ level: log });
+	return log;
+}
+function fromFactory(p, env) {
+	return typeof p === "function" ? p(env) : p;
+}
+const realSleep = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)));
+function createRuntime(shared, env, exec) {
+	const { options } = shared;
+	const mapped = options.env(env);
+	const ports = options.ports;
+	const tenant = options.tenant ?? "";
+	const db = isDbPort(mapped.db) ? mapped.db : d1Db(mapped.db);
+	const log = resolveLog(ports.log);
+	const clock = ports.clock ?? systemClock;
+	const ids = ports.ids ?? uuidv7Ids(clock);
+	let keyring;
+	if (isKeyringPort(mapped.keyring)) keyring = mapped.keyring;
+	else {
+		const cacheKey = typeof mapped.keyring === "string" ? mapped.keyring : JSON.stringify(mapped.keyring);
+		const cached = shared.keyrings.get(cacheKey);
+		keyring = cached ?? webCryptoKeyring(mapped.keyring);
+		if (!cached) shared.keyrings.set(cacheKey, keyring);
+	}
+	const tgOpt = options.telegram;
+	const tg = isClient(tgOpt) ? tgOpt : fetchTelegram({
+		log,
+		...tgOpt
+	});
+	const prefix = options.permissions?.prefix ?? "telegram";
+	const audit = ports.audit ?? ((e) => [sql`INSERT INTO tg_audit (id, tenant, actor, entity, entity_id, action, diff_json, at)
+          VALUES (${ids.uuid()}, ${tenant}, ${e.actor}, ${e.entity}, ${e.entityId}, ${e.action},
+                  ${e.diff ? JSON.stringify(e.diff) : null}, ${e.at})`]);
+	const rand = (buf) => crypto.getRandomValues(buf);
+	const base = mapped.publicBaseUrl?.trim();
+	const files = fromFactory(ports.files, env) ?? (mapped.files ? r2Files(mapped.files) : void 0);
+	const rt = {
+		env,
+		db,
+		keyring,
+		tg,
+		queue: mapped.queue,
+		browser: mapped.browser,
+		publicBaseUrl: base ? base.replace(/\/+$/, "") : null,
+		appEnv: mapped.appEnv ?? "production",
+		tenant,
+		actor: ports.actor,
+		authorize: ports.authorize,
+		users: ports.users,
+		files,
+		audit,
+		errors: ports.errors,
+		log,
+		clock,
+		ids,
+		i18n: createTranslator(ports.i18n ?? {
+			locales: ["en", "mr"],
+			defaultLocale: "en"
+		}),
+		settings: ports.settings ?? { timezone: "UTC" },
+		metrics: fromFactory(ports.metrics, env),
+		renderers: ports.renderers ?? [],
+		filters: shared.filters,
+		features: shared.features,
+		limits: shared.limits,
+		retention: shared.retention,
+		registry: shared.registry,
+		hooks: options.hooks ?? {},
+		allowMultipleChatsPerUser: options.allowMultipleChatsPerUser ?? false,
+		ai: shared.ai,
+		inbound: shared.inbound,
+		groups: resolveGroupOptions(options.groups),
+		transport: {
+			name: "outbox",
+			kick: async () => {}
+		},
+		rand,
+		perm: (name) => permissionName(name, prefix),
+		async can(actor, name, resource) {
+			try {
+				return await ports.authorize(actor, permissionName(name, prefix), resource) === true;
+			} catch (e) {
+				log.error("tg.authorize_error", {
+					permission: name,
+					error: e instanceof Error ? e.name : "unknown"
+				});
+				return false;
+			}
+		},
+		describe: (actor) => ports.actor.describe(actor),
+		sleep: (ms) => clock.sleep ? clock.sleep(ms) : realSleep(ms),
+		waitUntil(p) {
+			const safe = p.catch((e) => log.error("tg.background_error", { error: e instanceof Error ? e.name : "unknown" }));
+			exec?.waitUntil(safe);
+		},
+		async hook(name, run) {
+			const fn = options.hooks?.[name];
+			if (!fn) return;
+			try {
+				await run(fn);
+			} catch (e) {
+				log.warn("tg.hook_error", {
+					hook: name,
+					error: e instanceof Error ? e.name : "unknown"
+				});
+			}
+		}
+	};
+	rt.transport = shared.makeTransport(rt, mapped);
+	return rt;
+}
+export { createRuntime, defaultLimits, defaultRetention, resolveLog };