@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/schema/tables.js

@@ -0,0 +1,327 @@
+import { SCHEMA_VERSION } from "./version.js";
+import { sql } from "drizzle-orm";
+import { index, integer, primaryKey, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
+// src/schema/tables.ts
+/**
+* Drizzle (sqlite-core) definitions of every plugin table (docs/03). The host re-exports them in its schema and
+* generates + commits the migration. Changes are add-only. Flags are INTEGER 0/1, times are epoch ms, JSON is TEXT.
+* Table and index names are fixed (`tg_*`): the runtime's SQL uses these names, so they cannot be renamed.
+*/
+function telegramTables() {
+	const n = (name) => `tg_${name}`;
+	const tenant = () => text("tenant").notNull().default("");
+	return {
+		tgBot: sqliteTable(n("bot"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			name: text("name").notNull(),
+			tgBotId: text("tg_bot_id").notNull(),
+			username: text("username").notNull(),
+			tokenEnc: text("token_enc").notNull(),
+			webhookSecretEnc: text("webhook_secret_enc"),
+			mode: text("mode").notNull().default("webhook"),
+			status: text("status").notNull().default("active"),
+			statusDetail: text("status_detail"),
+			checkedAt: integer("checked_at"),
+			defaultLocale: text("default_locale").notNull().default("en"),
+			featuresJson: text("features_json"),
+			ratePerSec: integer("rate_per_sec").notNull().default(25),
+			pausedUntil: integer("paused_until"),
+			drainLeaseUntil: integer("drain_lease_until"),
+			drainToken: text("drain_token"),
+			commandsSyncedHash: text("commands_synced_hash"),
+			createdBy: text("created_by"),
+			createdAt: integer("created_at").notNull(),
+			updatedAt: integer("updated_at").notNull(),
+			deletedAt: integer("deleted_at")
+		}, (t) => [index(n("bot_tenant_status_idx")).on(t.tenant, t.status), uniqueIndex(n("bot_tg_bot_uq")).on(t.tenant, t.tgBotId).where(sql`deleted_at IS NULL`)]),
+		tgChat: sqliteTable(n("chat"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			botId: text("bot_id").notNull(),
+			chatId: text("chat_id").notNull(),
+			kind: text("kind").notNull(),
+			title: text("title"),
+			username: text("username"),
+			userId: text("user_id"),
+			audienceJson: text("audience_json"),
+			status: text("status").notNull().default("pending"),
+			locale: text("locale"),
+			timezone: text("timezone"),
+			topicsJson: text("topics_json"),
+			nextAllowedAt: integer("next_allowed_at"),
+			minuteWindowStart: integer("minute_window_start"),
+			minuteCount: integer("minute_count").notNull().default(0),
+			linkedBy: text("linked_by"),
+			linkedAt: integer("linked_at"),
+			createdAt: integer("created_at").notNull(),
+			updatedAt: integer("updated_at").notNull()
+		}, (t) => [
+			uniqueIndex(n("chat_bot_chat_uq")).on(t.tenant, t.botId, t.chatId),
+			index(n("chat_user_idx")).on(t.userId),
+			index(n("chat_bot_status_idx")).on(t.botId, t.status)
+		]),
+		tgLinkCode: sqliteTable(n("link_code"), {
+			codeHash: text("code_hash").primaryKey().notNull(),
+			tenant: tenant(),
+			botId: text("bot_id").notNull(),
+			purpose: text("purpose").notNull(),
+			userId: text("user_id"),
+			audienceJson: text("audience_json"),
+			expiresAt: integer("expires_at").notNull(),
+			usedAt: integer("used_at"),
+			usedByChat: text("used_by_chat"),
+			createdBy: text("created_by"),
+			createdAt: integer("created_at").notNull()
+		}, (t) => [index(n("link_code_expires_idx")).on(t.expiresAt)]),
+		tgDestination: sqliteTable(n("destination"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			name: text("name").notNull(),
+			slug: text("slug").notNull(),
+			botId: text("bot_id").notNull(),
+			chatRef: text("chat_ref").notNull(),
+			messageThreadId: integer("message_thread_id"),
+			aiAllowed: integer("ai_allowed").notNull().default(0),
+			createdBy: text("created_by"),
+			createdAt: integer("created_at").notNull(),
+			updatedAt: integer("updated_at").notNull(),
+			deletedAt: integer("deleted_at")
+		}, (t) => [uniqueIndex(n("destination_slug_uq")).on(t.tenant, t.slug)]),
+		tgCommand: sqliteTable(n("command"), {
+			tenant: tenant(),
+			botId: text("bot_id").notNull(),
+			command: text("command").notNull(),
+			enabled: integer("enabled").notNull().default(1),
+			rolesJson: text("roles_json"),
+			aliasesJson: text("aliases_json"),
+			descriptionJson: text("description_json"),
+			showInMenu: integer("show_in_menu").notNull().default(1),
+			sort: integer("sort").notNull().default(0),
+			updatedBy: text("updated_by"),
+			updatedAt: integer("updated_at").notNull()
+		}, (t) => [primaryKey({ columns: [
+			t.tenant,
+			t.botId,
+			t.command
+		] })]),
+		tgTemplate: sqliteTable(n("template"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			key: text("key").notNull(),
+			name: text("name").notNull(),
+			kind: text("kind").notNull().default("message"),
+			provider: text("provider"),
+			providerParamsJson: text("provider_params_json"),
+			bodyJson: text("body_json").notNull(),
+			format: text("format").notNull().default("html"),
+			reportJson: text("report_json"),
+			buttonsJson: text("buttons_json"),
+			optionsJson: text("options_json"),
+			version: integer("version").notNull().default(1),
+			createdBy: text("created_by"),
+			createdAt: integer("created_at").notNull(),
+			updatedBy: text("updated_by"),
+			updatedAt: integer("updated_at").notNull(),
+			deletedAt: integer("deleted_at")
+		}, (t) => [uniqueIndex(n("template_key_uq")).on(t.tenant, t.key)]),
+		tgTemplateVersion: sqliteTable(n("template_version"), {
+			tenant: tenant(),
+			templateId: text("template_id").notNull(),
+			version: integer("version").notNull(),
+			bodyJson: text("body_json").notNull(),
+			reportJson: text("report_json"),
+			buttonsJson: text("buttons_json"),
+			savedBy: text("saved_by"),
+			savedAt: integer("saved_at").notNull()
+		}, (t) => [primaryKey({ columns: [t.templateId, t.version] })]),
+		tgSubscription: sqliteTable(n("subscription"), {
+			tenant: tenant(),
+			chatRef: text("chat_ref").notNull(),
+			topic: text("topic").notNull(),
+			muted: integer("muted").notNull().default(0),
+			quietJson: text("quiet_json"),
+			updatedAt: integer("updated_at").notNull()
+		}, (t) => [primaryKey({ columns: [
+			t.tenant,
+			t.chatRef,
+			t.topic
+		] })]),
+		tgSchedule: sqliteTable(n("schedule"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			name: text("name").notNull(),
+			ruleJson: text("rule_json").notNull(),
+			timezone: text("timezone").notNull(),
+			templateId: text("template_id").notNull(),
+			paramsJson: text("params_json"),
+			recipientsJson: text("recipients_json").notNull(),
+			personalize: integer("personalize").notNull().default(1),
+			missedPolicy: text("missed_policy").notNull().default("run_once"),
+			missedGraceMin: integer("missed_grace_min").notNull().default(30),
+			enabled: integer("enabled").notNull().default(1),
+			pausedUntil: integer("paused_until"),
+			nextRunAt: integer("next_run_at"),
+			claimUntil: integer("claim_until"),
+			claimToken: text("claim_token"),
+			lastRunAt: integer("last_run_at"),
+			lastStatus: text("last_status"),
+			createdBy: text("created_by"),
+			createdAt: integer("created_at").notNull(),
+			updatedAt: integer("updated_at").notNull(),
+			deletedAt: integer("deleted_at")
+		}, (t) => [index(n("schedule_due_idx")).on(t.enabled, t.nextRunAt)]),
+		tgScheduleRun: sqliteTable(n("schedule_run"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			scheduleId: text("schedule_id").notNull(),
+			slotAt: integer("slot_at").notNull(),
+			trigger: text("trigger").notNull().default("schedule"),
+			startedAt: integer("started_at").notNull(),
+			finishedAt: integer("finished_at"),
+			status: text("status").notNull().default("running"),
+			deliveries: integer("deliveries").notNull().default(0),
+			error: text("error"),
+			templateVersion: integer("template_version")
+		}, (t) => [uniqueIndex(n("schedule_run_slot_uq")).on(t.scheduleId, t.slotAt)]),
+		tgEventRule: sqliteTable(n("event_rule"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			event: text("event").notNull(),
+			name: text("name").notNull(),
+			filterJson: text("filter_json"),
+			templateId: text("template_id").notNull(),
+			recipientsJson: text("recipients_json").notNull(),
+			throttleJson: text("throttle_json"),
+			enabled: integer("enabled").notNull().default(1),
+			createdBy: text("created_by"),
+			createdAt: integer("created_at").notNull(),
+			updatedAt: integer("updated_at").notNull(),
+			deletedAt: integer("deleted_at")
+		}, (t) => [index(n("event_rule_event_idx")).on(t.tenant, t.event, t.enabled)]),
+		tgEvent: sqliteTable(n("event"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			event: text("event").notNull(),
+			payloadJson: text("payload_json").notNull(),
+			dedupeKey: text("dedupe_key").notNull(),
+			occurredAt: integer("occurred_at").notNull(),
+			status: text("status").notNull().default("pending"),
+			attempts: integer("attempts").notNull().default(0),
+			claimUntil: integer("claim_until"),
+			claimToken: text("claim_token"),
+			processedAt: integer("processed_at"),
+			error: text("error")
+		}, (t) => [uniqueIndex(n("event_dedupe_uq")).on(t.tenant, t.dedupeKey), index(n("event_status_idx")).on(t.status, t.occurredAt)]),
+		tgBroadcast: sqliteTable(n("broadcast"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			title: text("title").notNull(),
+			templateId: text("template_id"),
+			bodyJson: text("body_json"),
+			paramsJson: text("params_json"),
+			fileRef: text("file_ref"),
+			recipientsJson: text("recipients_json").notNull(),
+			status: text("status").notNull().default("draft"),
+			statsJson: text("stats_json"),
+			createdBy: text("created_by"),
+			createdAt: integer("created_at").notNull(),
+			updatedAt: integer("updated_at").notNull(),
+			sentAt: integer("sent_at"),
+			deletedAt: integer("deleted_at")
+		}),
+		tgDelivery: sqliteTable(n("delivery"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			botId: text("bot_id").notNull(),
+			chatRef: text("chat_ref").notNull(),
+			messageThreadId: integer("message_thread_id"),
+			source: text("source").notNull(),
+			sourceId: text("source_id"),
+			kind: text("kind").notNull().default("text"),
+			bodyHtml: text("body_html"),
+			part: integer("part").notNull().default(0),
+			parts: integer("parts").notNull().default(1),
+			fileRef: text("file_ref"),
+			fileName: text("file_name"),
+			fileMime: text("file_mime"),
+			replyMarkupJson: text("reply_markup_json"),
+			optionsJson: text("options_json"),
+			/** What to render when `body_html` is still null (template, params, audience, locale). */
+			renderJson: text("render_json"),
+			/** Target message for `edit` / `delete`. */
+			targetMessageId: integer("target_message_id"),
+			dedupeKey: text("dedupe_key").notNull(),
+			status: text("status").notNull().default("queued"),
+			attempts: integer("attempts").notNull().default(0),
+			nextAttemptAt: integer("next_attempt_at").notNull(),
+			leaseUntil: integer("lease_until"),
+			leaseToken: text("lease_token"),
+			tgMessageId: integer("tg_message_id"),
+			errorCode: text("error_code"),
+			errorDetail: text("error_detail"),
+			createdAt: integer("created_at").notNull(),
+			updatedAt: integer("updated_at").notNull(),
+			sentAt: integer("sent_at")
+		}, (t) => [
+			uniqueIndex(n("delivery_dedupe_uq")).on(t.tenant, t.dedupeKey),
+			index(n("delivery_due_idx")).on(t.botId, t.status, t.nextAttemptAt),
+			index(n("delivery_source_idx")).on(t.source, t.sourceId)
+		]),
+		tgUpdate: sqliteTable(n("update"), {
+			tenant: tenant(),
+			botId: text("bot_id").notNull(),
+			updateId: integer("update_id").notNull(),
+			kind: text("kind"),
+			chatId: text("chat_id"),
+			status: text("status").notNull().default("received"),
+			attempts: integer("attempts").notNull().default(0),
+			receivedAt: integer("received_at").notNull(),
+			processedAt: integer("processed_at"),
+			error: text("error")
+		}, (t) => [primaryKey({ columns: [t.botId, t.updateId] }), index(n("update_status_idx")).on(t.status, t.receivedAt)]),
+		tgActionToken: sqliteTable(n("action_token"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			botId: text("bot_id").notNull(),
+			action: text("action").notNull(),
+			paramsJson: text("params_json"),
+			chatRef: text("chat_ref"),
+			userId: text("user_id"),
+			singleUse: integer("single_use").notNull().default(1),
+			confirmedAt: integer("confirmed_at"),
+			expiresAt: integer("expires_at").notNull(),
+			usedAt: integer("used_at"),
+			result: text("result"),
+			createdAt: integer("created_at").notNull()
+		}, (t) => [index(n("action_token_expires_idx")).on(t.expiresAt)]),
+		tgDialog: sqliteTable(n("dialog"), {
+			tenant: tenant(),
+			chatRef: text("chat_ref").notNull(),
+			dialog: text("dialog").notNull(),
+			userId: text("user_id"),
+			step: text("step").notNull(),
+			stateJson: text("state_json").notNull().default("{}"),
+			expiresAt: integer("expires_at").notNull(),
+			startedAt: integer("started_at").notNull(),
+			updatedAt: integer("updated_at").notNull()
+		}, (t) => [primaryKey({ columns: [t.tenant, t.chatRef] }), index(n("dialog_expires_idx")).on(t.expiresAt)]),
+		tgState: sqliteTable(n("state"), {
+			tenant: tenant(),
+			key: text("key").notNull(),
+			value: text("value").notNull(),
+			updatedAt: integer("updated_at").notNull()
+		}, (t) => [primaryKey({ columns: [t.tenant, t.key] })]),
+		tgAudit: sqliteTable(n("audit"), {
+			id: text("id").primaryKey().notNull(),
+			tenant: tenant(),
+			actor: text("actor"),
+			entity: text("entity").notNull(),
+			entityId: text("entity_id"),
+			action: text("action").notNull(),
+			diffJson: text("diff_json"),
+			at: integer("at").notNull()
+		}, (t) => [index(n("audit_entity_idx")).on(t.entity, t.entityId)])
+	};
+}
+export { SCHEMA_VERSION, telegramTables };

package/dist/schema/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Bump when a table or column is added (add-only). `GET /admin/meta` reports it, and the plugin refuses to run on a
+ * DB that is behind. Kept free of drizzle-orm so `server` can import it without the optional peer.
+ */
+export declare const SCHEMA_VERSION = 2;

package/dist/schema/version.js

@@ -0,0 +1,7 @@
+// src/schema/version.ts
+/**
+* Bump when a table or column is added (add-only). `GET /admin/meta` reports it, and the plugin refuses to run on a
+* DB that is behind. Kept free of drizzle-orm so `server` can import it without the optional peer.
+*/
+const SCHEMA_VERSION = 2;
+export { SCHEMA_VERSION };

package/dist/server/index.d.ts

@@ -0,0 +1,55 @@
+import { CoreTemplateError, TemplateAst } from "../core/template/ast.js";
+import { BUILTIN_FILTERS, FilterDef, FilterFn, FilterRegistry, defineFilter } from "../core/template/filters.js";
+import { SqlFragment, SqlInput, SqlValue, isSqlFragment, sql } from "../ports/sql.js";
+import { DbPort, RunResult } from "../ports/db.js";
+import { TelegramConfigError, TelegramPluginError, TelegramProblemExtensions, featureDisabled, isTelegramPluginError, toPluginError } from "../engine/errors.js";
+import { ActorInfo, ActorPort, AuditEntry, AuditPort, AuthorizePort, ClockPort, ErrorsPort, FilesPort, I18nPort, IdsPort, KeyringPort, LogFields, LogPort, MetricsPort, OpenedFile, PortOrFactory, RenderInput, RenderedFile, RendererPort, SchedulerPort, SettingsPort, StoredFile, TransportPort, UserInfo, UsersPort } from "../ports/ports.js";
+import { ParsedUpdate, TgCallbackQuery, TgChat, TgChatMember, TgChatMemberUpdated, TgDocument, TgForumTopicCreated, TgMessage, TgMessageEntity, TgPhotoSize, TgUpdate, TgUser, parseUpdate } from "../telegram/update.js";
+import { AnswerCallbackQueryParams, BotCommand, BotCommandScope, BotUser, ButtonStyle, ChatAction, ChatFullInfo, ChatId, CommandScopeParams, DeleteMessageParams, DeleteWebhookParams, EditMessageReplyMarkupParams, EditMessageTextParams, ForceReply, GetUpdatesParams, InlineKeyboardButton, InlineKeyboardMarkup, InputFile, InputFileUpload, KeyboardButton, LinkPreviewOptions, MethodName, MethodResults, ParseMode, ReplyKeyboardMarkup, ReplyKeyboardRemove, ReplyMarkup, ReplyParameters, SendChatActionParams, SendDocumentParams, SendMessageParams, SendOptions, SendPhotoParams, SetMyCommandsParams, SetWebhookParams, TgFile, UpdateType, WebhookInfo } from "../telegram/types.js";
+import { BotApi, CallOptions, DEFAULT_TELEGRAM_BASE_URL, DEFAULT_TELEGRAM_TIMEOUT_MS, FetchLike, TelegramClient, TelegramClientOptions, TokenGetter, fetchTelegram } from "../telegram/client.js";
+import { ANY_ROLE, ActionContext, ActionDef, ActionResult, AudienceDef, CommandContext, CommandDef, DialogChoice, DialogDef, DialogFinishContext, DialogStepDef, EventDef, FileSourceContext, FileSourceDef, ProviderContext, ProviderDef, RESERVED_COMMANDS, Registry, ReplyApi, ReplyOptions, defineAction, defineAudience, defineCommand, defineDialog, defineEvent, defineFileSource, defineProvider, definitions } from "../engine/registry.js";
+import { DEFAULT_LIMITS, DEFAULT_RETENTION, FeatureFlags, FreeTextContext, InboundContext, InboundFile, TelegramAiOptions, TelegramCrons, TelegramEnv, TelegramFeaturesInput, TelegramGroupOptions, TelegramHooks, TelegramInboundOptions, TelegramLimits, TelegramLogLevel, TelegramPluginOptions, TelegramPorts, TelegramRetention, TransportChoice } from "../engine/options.js";
+import { Runtime } from "../engine/runtime.js";
+import { BotDoHost, registerTelegramPlugin } from "../engine/outbox/do-registry.js";
+import { DoTransport, botStub, doTransport, isDoTransport } from "../engine/outbox/do-transport.js";
+import { SCHEMA_VERSION } from "../schema/version.js";
+import { systemClock } from "../adapters/clock.js";
+import { consoleLog, redactSecrets, silentLog } from "../adapters/console-log.js";
+import { D1_MAX_PARAMS, d1Db } from "../adapters/d1-db.js";
+import { uuidv7, uuidv7Ids } from "../adapters/ids.js";
+import { AnalyticsEngineLike, AnalyticsEngineMetricsOptions, analyticsEngineMetrics, noopMetrics } from "../adapters/metrics.js";
+import { R2FilesOptions, r2Files } from "../adapters/r2-files.js";
+import { KeyringError, KeyringSecret, WebCryptoKeyring, base64ToBytes, bytesToBase64Url, generateKeyringSecret, kidOfCiphertext, parseKeyringSecret, randomBase64Url, timingSafeEqualStrings, webCryptoKeyring } from "../adapters/keyring.js";
+import { checkAiText } from "../core/guards.js";
+import { escapeHtml } from "../core/html/escape.js";
+import { describeRule } from "../core/schedule/describe.js";
+import { nextRuns, validateRule } from "../core/schedule/rule.js";
+import { isValidTimeZone } from "../core/schedule/tz.js";
+import { toPlainText } from "../core/split/plain.js";
+import { CAPTION_LIMIT, TEXT_LIMIT, splitMessage, visibleLength } from "../core/split/split.js";
+import { validateTemplate } from "../core/template/validate.js";
+import { parseTemplate } from "../core/template/parse.js";
+import { RenderContext, renderTemplate } from "../core/template/render.js";
+import { Shape, shapeVariables, zodToShape } from "../core/template/shape.js";
+import { VariableRef, listVariables } from "../core/template/variables.js";
+import { CompileResult, compileTemplate } from "../core/template/index.js";
+import { ACTION_PREFIX } from "../engine/actions/tokens.js";
+import { ProviderTimeout } from "../engine/content/providers.js";
+import { ParsedCommand, UpdateClass, classifyUpdate, isLifecycleMessage, isValidStartPayload, parseCommand, parseStartPayload, updateChat, updateFrom, updateMessage, updateType } from "../telegram/inbound.js";
+import { untrustedWrap } from "../engine/dispatch/context.js";
+import { DIALOG_PREFIX } from "../engine/dialogs/dialog.js";
+import { matchFilter, matchFilters } from "../engine/events/filters.js";
+import { stripSensitive } from "../engine/events/payload.js";
+import { TelegramJob, TelegramJobContext, TelegramJobResult } from "../engine/jobs.js";
+import { PluginQueueMessage, cronTransport, isPluginMessage, queueTransport } from "../engine/outbox/transport.js";
+import { SchemaState } from "../engine/state.js";
+import { TelegramRoutesApp } from "../routes/app.js";
+import { AiSendKind, AiToolDestination, AiToolSpec } from "../services/ai-tool.js";
+import { intersectData } from "../engine/content/intersect.js";
+import { EnqueueOptions, recordProviderKey } from "../services/send.js";
+import { TelegramOutcome, TelegramOutcomeKind, TelegramOutcomeReason, classifyTelegramError, settle } from "../telegram/classify.js";
+import { TelegramApiError, TelegramNetworkError, isTelegramApiError } from "../telegram/errors.js";
+import { inputFile, isInputFileUpload } from "../telegram/multipart.js";
+import { ExecLike, TelegramPlugin, createTelegramPlugin } from "./plugin.js";
+import { PLUGIN_VERSION } from "./version.js";
+export { ACTION_PREFIX, ANY_ROLE, type ActionContext, type ActionDef, type ActionResult, type ActorInfo, type ActorPort, type AiSendKind, type AiToolDestination, type AiToolSpec, type AnalyticsEngineLike, type AnalyticsEngineMetricsOptions, type AnswerCallbackQueryParams, type AudienceDef, type AuditEntry, type AuditPort, type AuthorizePort, BUILTIN_FILTERS, BotApi, type BotCommand, type BotCommandScope, type BotDoHost, type BotUser, type ButtonStyle, CAPTION_LIMIT, CallOptions, type ChatAction, type ChatFullInfo, type ChatId, type ClockPort, type CommandContext, type CommandDef, type CommandScopeParams, type CompileResult, type CoreTemplateError, D1_MAX_PARAMS, DEFAULT_LIMITS, DEFAULT_RETENTION, DEFAULT_TELEGRAM_BASE_URL, DEFAULT_TELEGRAM_TIMEOUT_MS, DIALOG_PREFIX, type DbPort, type DeleteMessageParams, type DeleteWebhookParams, type DialogChoice, type DialogDef, type DialogFinishContext, type DialogStepDef, type DoTransport, type EditMessageReplyMarkupParams, type EditMessageTextParams, type EnqueueOptions, type ErrorsPort, type EventDef, type ExecLike, type FeatureFlags, FetchLike, type FileSourceContext, type FileSourceDef, type FilesPort, type FilterDef, type FilterFn, type FilterRegistry, type ForceReply, type FreeTextContext, type GetUpdatesParams, type I18nPort, type IdsPort, type InboundContext, type InboundFile, type InlineKeyboardButton, type InlineKeyboardMarkup, type InputFile, type InputFileUpload, type KeyboardButton, KeyringError, type KeyringPort, KeyringSecret, type LinkPreviewOptions, type LogFields, type LogPort, type MethodName, type MethodResults, type MetricsPort, type OpenedFile, PLUGIN_VERSION, type ParseMode, ParsedCommand, ParsedUpdate, type PluginQueueMessage, type PortOrFactory, type ProviderContext, type ProviderDef, ProviderTimeout, type R2FilesOptions, RESERVED_COMMANDS, type Registry, type RenderContext, type RenderInput, type RenderedFile, type RendererPort, type ReplyApi, type ReplyKeyboardMarkup, type ReplyKeyboardRemove, type ReplyMarkup, type ReplyOptions, type ReplyParameters, type RunResult, type Runtime, SCHEMA_VERSION, type SchedulerPort, type SchemaState, type SendChatActionParams, type SendDocumentParams, type SendMessageParams, type SendOptions, type SendPhotoParams, type SetMyCommandsParams, type SetWebhookParams, type SettingsPort, type Shape, type SqlFragment, type SqlInput, type SqlValue, type StoredFile, TEXT_LIMIT, type TelegramAiOptions, TelegramApiError, TelegramClient, TelegramClientOptions, TelegramConfigError, type TelegramCrons, type TelegramEnv, type TelegramFeaturesInput, type TelegramGroupOptions, type TelegramHooks, type TelegramInboundOptions, type TelegramJob, type TelegramJobContext, type TelegramJobResult, type TelegramLimits, type TelegramLogLevel, TelegramNetworkError, TelegramOutcome, TelegramOutcomeKind, TelegramOutcomeReason, type TelegramPlugin, TelegramPluginError, type TelegramPluginOptions, type TelegramPorts, type TelegramProblemExtensions, type TelegramRetention, type TelegramRoutesApp, type TemplateAst, TgCallbackQuery, TgChat, TgChatMember, TgChatMemberUpdated, TgDocument, type TgFile, TgForumTopicCreated, TgMessage, TgMessageEntity, TgPhotoSize, TgUpdate, TgUser, TokenGetter, type TransportChoice, type TransportPort, UpdateClass, type UpdateType, type UserInfo, type UsersPort, type VariableRef, WebCryptoKeyring, type WebhookInfo, analyticsEngineMetrics, base64ToBytes, botStub, bytesToBase64Url, checkAiText, classifyTelegramError, classifyUpdate, compileTemplate, consoleLog, createTelegramPlugin, cronTransport, d1Db, defineAction, defineAudience, defineCommand, defineDialog, defineEvent, defineFileSource, defineFilter, defineProvider, definitions, describeRule, doTransport, escapeHtml, featureDisabled, fetchTelegram, generateKeyringSecret, inputFile, intersectData, isDoTransport, isInputFileUpload, isLifecycleMessage, isPluginMessage, isSqlFragment, isTelegramApiError, isTelegramPluginError, isValidStartPayload, isValidTimeZone, kidOfCiphertext, listVariables, matchFilter, matchFilters, nextRuns, noopMetrics, parseCommand, parseKeyringSecret, parseStartPayload, parseTemplate, parseUpdate, queueTransport, r2Files, randomBase64Url, recordProviderKey, redactSecrets, registerTelegramPlugin, renderTemplate, settle, shapeVariables, silentLog, splitMessage, sql, stripSensitive, systemClock, timingSafeEqualStrings, toPlainText, toPluginError, untrustedWrap, updateChat, updateFrom, updateMessage, updateType, uuidv7, uuidv7Ids, validateRule, validateTemplate, visibleLength, webCryptoKeyring, zodToShape };

package/dist/server/index.js

@@ -0,0 +1,46 @@
+import { SCHEMA_VERSION } from "../schema/version.js";
+import { systemClock } from "../adapters/clock.js";
+import { consoleLog, redactSecrets, silentLog } from "../adapters/console-log.js";
+import { D1_MAX_PARAMS, d1Db } from "../adapters/d1-db.js";
+import { uuidv7, uuidv7Ids } from "../adapters/ids.js";
+import { analyticsEngineMetrics, noopMetrics } from "../adapters/metrics.js";
+import { r2Files } from "../adapters/r2-files.js";
+import { KeyringError, base64ToBytes, bytesToBase64Url, generateKeyringSecret, kidOfCiphertext, parseKeyringSecret, randomBase64Url, timingSafeEqualStrings, webCryptoKeyring } from "../adapters/keyring.js";
+import { checkAiText } from "../core/guards.js";
+import { escapeHtml } from "../core/html/escape.js";
+import { isValidTimeZone } from "../core/schedule/tz.js";
+import { describeRule } from "../core/schedule/describe.js";
+import { nextRuns, validateRule } from "../core/schedule/rule.js";
+import { toPlainText } from "../core/split/plain.js";
+import { CAPTION_LIMIT, TEXT_LIMIT, splitMessage, visibleLength } from "../core/split/split.js";
+import { parseTemplate } from "../core/template/parse.js";
+import { BUILTIN_FILTERS, defineFilter } from "../core/template/filters.js";
+import { shapeVariables, zodToShape } from "../core/template/shape.js";
+import { validateTemplate } from "../core/template/validate.js";
+import { renderTemplate } from "../core/template/render.js";
+import { listVariables } from "../core/template/variables.js";
+import { compileTemplate } from "../core/template/index.js";
+import { isSqlFragment, sql } from "../ports/sql.js";
+import { TelegramConfigError, TelegramPluginError, featureDisabled, isTelegramPluginError, toPluginError } from "../engine/errors.js";
+import { ACTION_PREFIX } from "../engine/actions/tokens.js";
+import { ProviderTimeout } from "../engine/content/providers.js";
+import { TelegramApiError, TelegramNetworkError, isTelegramApiError } from "../telegram/errors.js";
+import { classifyTelegramError, settle } from "../telegram/classify.js";
+import { DIALOG_PREFIX } from "../engine/dialogs/dialog.js";
+import { classifyUpdate, isLifecycleMessage, isValidStartPayload, parseCommand, parseStartPayload, updateChat, updateFrom, updateMessage, updateType } from "../telegram/inbound.js";
+import { intersectData } from "../engine/content/intersect.js";
+import { ANY_ROLE, RESERVED_COMMANDS, defineAction, defineAudience, defineCommand, defineDialog, defineEvent, defineFileSource, defineProvider, definitions } from "../engine/registry.js";
+import { recordProviderKey } from "../services/send.js";
+import { untrustedWrap } from "../engine/dispatch/context.js";
+import { matchFilter, matchFilters } from "../engine/events/filters.js";
+import { stripSensitive } from "../engine/events/payload.js";
+import { DEFAULT_LIMITS, DEFAULT_RETENTION } from "../engine/options.js";
+import { registerTelegramPlugin } from "../engine/outbox/do-registry.js";
+import { inputFile, isInputFileUpload } from "../telegram/multipart.js";
+import { botStub, doTransport, isDoTransport } from "../engine/outbox/do-transport.js";
+import { TgCallbackQuery, TgChat, TgChatMember, TgChatMemberUpdated, TgDocument, TgForumTopicCreated, TgMessage, TgMessageEntity, TgPhotoSize, TgUpdate, TgUser, parseUpdate } from "../telegram/update.js";
+import { cronTransport, isPluginMessage, queueTransport } from "../engine/outbox/transport.js";
+import { DEFAULT_TELEGRAM_BASE_URL, DEFAULT_TELEGRAM_TIMEOUT_MS, fetchTelegram } from "../telegram/client.js";
+import { PLUGIN_VERSION } from "./version.js";
+import { createTelegramPlugin } from "./plugin.js";
+export { ACTION_PREFIX, ANY_ROLE, BUILTIN_FILTERS, CAPTION_LIMIT, D1_MAX_PARAMS, DEFAULT_LIMITS, DEFAULT_RETENTION, DEFAULT_TELEGRAM_BASE_URL, DEFAULT_TELEGRAM_TIMEOUT_MS, DIALOG_PREFIX, KeyringError, PLUGIN_VERSION, ProviderTimeout, RESERVED_COMMANDS, SCHEMA_VERSION, TEXT_LIMIT, TelegramApiError, TelegramConfigError, TelegramNetworkError, TelegramPluginError, TgCallbackQuery, TgChat, TgChatMember, TgChatMemberUpdated, TgDocument, TgForumTopicCreated, TgMessage, TgMessageEntity, TgPhotoSize, TgUpdate, TgUser, analyticsEngineMetrics, base64ToBytes, botStub, bytesToBase64Url, checkAiText, classifyTelegramError, classifyUpdate, compileTemplate, consoleLog, createTelegramPlugin, cronTransport, d1Db, defineAction, defineAudience, defineCommand, defineDialog, defineEvent, defineFileSource, defineFilter, defineProvider, definitions, describeRule, doTransport, escapeHtml, featureDisabled, fetchTelegram, generateKeyringSecret, inputFile, intersectData, isDoTransport, isInputFileUpload, isLifecycleMessage, isPluginMessage, isSqlFragment, isTelegramApiError, isTelegramPluginError, isValidStartPayload, isValidTimeZone, kidOfCiphertext, listVariables, matchFilter, matchFilters, nextRuns, noopMetrics, parseCommand, parseKeyringSecret, parseStartPayload, parseTemplate, parseUpdate, queueTransport, r2Files, randomBase64Url, recordProviderKey, redactSecrets, registerTelegramPlugin, renderTemplate, settle, shapeVariables, silentLog, splitMessage, sql, stripSensitive, systemClock, timingSafeEqualStrings, toPlainText, toPluginError, untrustedWrap, updateChat, updateFrom, updateMessage, updateType, uuidv7, uuidv7Ids, validateRule, validateTemplate, visibleLength, webCryptoKeyring, zodToShape };

package/dist/server/plugin.d.ts

@@ -0,0 +1,81 @@
+import { PluginMeta } from "../contracts/meta.js";
+import { SendIntent, SendPreview } from "../contracts/send.js";
+import { SqlFragment } from "../ports/sql.js";
+import { TelegramPluginOptions } from "../engine/options.js";
+import { Runtime } from "../engine/runtime.js";
+import { TelegramJob } from "../engine/jobs.js";
+import { SchemaState } from "../engine/state.js";
+import { TgEnv } from "../routes/http.js";
+import { buildRoutes } from "../routes/app.js";
+import { AiToolSpec } from "../services/ai-tool.js";
+import { EnqueueOptions } from "../services/send.js";
+import { Hono } from "hono";
+/** The part of a Workers `ExecutionContext` the plugin uses (background work after the response). */
+export type ExecLike = {
+  /** Keeps the invocation alive until `p` settles. */
+  waitUntil(p: Promise<unknown>): void;
+};
+/**
+ * What `createTelegramPlugin()` returns: the routes to mount, the jobs to schedule, the queue consumer and the
+ * programmatic API. Every method that takes `env` builds a fresh per-invocation runtime from it. Methods of the
+ * programmatic API (`emit`, `preview`, `enqueue`, `kick`, `aiToolSpec`) throw only `TelegramPluginError`.
+ */
+export interface TelegramPlugin<E, A> {
+  /** The Hono sub-app (webhook, admin API, self-service). Mount it: `app.route("/api/telegram", telegram.routes)`. */
+  readonly routes: ReturnType<typeof buildRoutes> & Hono<TgEnv>;
+  /** `telegram:tick` (every minute), `telegram:cleanup` and `telegram:rekey` (daily); run them from `scheduled`. */
+  readonly jobs: readonly TelegramJob<E>[];
+  /**
+   * Queue consumer: `if (await telegram.queue(batch, env, ctx)) return;`. Handles (acks / retries one by one) the
+   * plugin's messages in any batch and resolves `true` only when EVERY message was the plugin's. On `false`, handle
+   * only the messages with `!isPluginMessage(m.body)` and ack them one by one (never `ackAll()` / `retryAll()`).
+   * A dedicated queue for the plugin is simpler.
+   */
+  queue(batch: MessageBatch<unknown>, env: E, ctx?: ExecLike): Promise<boolean>;
+  /**
+   * SQL for the host's batch: a `tg_event` row (features.events), so the event commits with the host's write.
+   * The payload is validated against the event's schema (`validation_failed`). Fan-out runs on the tick, or at
+   * once after `kick` under the queue / DO transports. `dedupeKey` makes a repeated emit a no-op.
+   */
+  emit(event: string, payload: unknown, opts?: {
+    dedupeKey?: string;
+  }): SqlFragment[];
+  /**
+   * Validates and previews a send intent as `actor` (destination, rendered parts, file, confirm sentence) without
+   * writing anything. Use it for confirm cards (AI propose); `enqueue` does the actual send. Throws
+   * `TelegramPluginError` (`destination_not_allowed`, `forbidden`, `send_text_rejected` with `reasons`, …).
+   */
+  preview(env: E, intent: SendIntent, actor: A, opts?: Omit<EnqueueOptions, "dedupeKey">): Promise<SendPreview>;
+  /**
+   * SQL for the host's batch: the outbox rows of a send intent, re-checked as the live `actor`. `opts.dedupeKey`
+   * (required) makes a retried commit send once. Call `kick` after the batch commits.
+   */
+  enqueue(env: E, intent: SendIntent, actor: A, opts: EnqueueOptions): Promise<SqlFragment[]>;
+  /**
+   * features.ai: JSON-schema description of a generic `send_to_telegram` tool for this actor (its `ai_allowed`
+   * destinations, `me`, enabled kinds). The tool proposes; wire it as propose (`preview` with `source: "ai"`) →
+   * the host's confirm card (`preview.consequence`) → commit (`enqueue` with `dedupeKey: "ai:" + nonce` in the host
+   * batch, then `kick`). See `services/ai-tool.ts`.
+   */
+  aiToolSpec(env: E, actor: A): Promise<AiToolSpec>;
+  /** Starts a drain (and event fan-out) now; use it in `waitUntil` after a commit. `botIds` limits the drain. */
+  kick(env: E, opts?: {
+    botIds?: string[];
+    ctx?: ExecLike;
+  }): Promise<void>;
+  /** Features, versions and registered keys (permissions are empty here; `GET /admin/meta` adds the caller's). */
+  meta(): PluginMeta;
+  /** Records `SCHEMA_VERSION` in `tg_state` when the tables are current; reports what is missing otherwise. */
+  ensureState(env: E): Promise<SchemaState>;
+  /**
+   * @internal The resolved runtime for one invocation (tests and plugin internals). It gives raw access to the
+   * database and ports and performs NO permission checks; its shape may change in any release. Use `routes`,
+   * `preview`, `enqueue`, `emit` and `kick` in host code.
+   */
+  runtime(env: E, ctx?: ExecLike): Runtime<A>;
+}
+/**
+ * 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.
+ */
+export declare function createTelegramPlugin<E, A>(options: TelegramPluginOptions<E, A>): TelegramPlugin<E, A>;