@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/locales/mr.json

@@ -0,0 +1,341 @@
+{
+  "labels": {
+    "botMode": {
+      "webhook": "वेबहुक",
+      "polling": "पोलिंग (डेव्हलपमेंट)"
+    },
+    "botStatus": {
+      "active": "सक्रिय",
+      "disabled": "बंद",
+      "invalid_token": "अवैध टोकन",
+      "webhook_error": "वेबहुक त्रुटी"
+    },
+    "chatKind": {
+      "private": "खाजगी चॅट",
+      "group": "गट",
+      "supergroup": "सुपरग्रुप",
+      "channel": "चॅनेल"
+    },
+    "chatStatus": {
+      "pending": "प्रलंबित",
+      "active": "सक्रिय",
+      "blocked": "बॉट ब्लॉक केला",
+      "left": "बाहेर पडले",
+      "migrated": "सुपरग्रुपमध्ये हलवले"
+    },
+    "linkPurpose": {
+      "user": "व्यक्ती",
+      "group": "गट"
+    },
+    "builtinCommand": {
+      "start": "सुरू करा",
+      "help": "मदत",
+      "stop": "संदेश थांबवा",
+      "settings": "सेटिंग्ज",
+      "whoami": "मी कोण आहे",
+      "language": "भाषा"
+    },
+    "templateKind": {
+      "message": "संदेश",
+      "report": "अहवाल फाइल"
+    },
+    "templateFormat": {
+      "html": "फॉरमॅट केलेले (HTML)",
+      "text": "साधा मजकूर"
+    },
+    "reportFormat": {
+      "pdf": "PDF",
+      "csv": "CSV"
+    },
+    "buttonStyle": {
+      "primary": "मुख्य",
+      "success": "यश (हिरवा)",
+      "danger": "धोका (लाल)"
+    },
+    "weekday": {
+      "mon": "सोमवार",
+      "tue": "मंगळवार",
+      "wed": "बुधवार",
+      "thu": "गुरुवार",
+      "fri": "शुक्रवार",
+      "sat": "शनिवार",
+      "sun": "रविवार"
+    },
+    "scheduleRuleKind": {
+      "daily": "दररोज",
+      "weekly": "साप्ताहिक",
+      "monthly": "मासिक",
+      "cron": "सानुकूल (cron)",
+      "once": "एकदाच"
+    },
+    "missedPolicy": {
+      "skip": "चुकलेले रन वगळा",
+      "run_once": "चुकल्यास एकदा चालवा"
+    },
+    "scheduleRunStatus": {
+      "running": "चालू आहे",
+      "done": "पूर्ण",
+      "partial": "अंशतः पाठवले",
+      "failed": "अयशस्वी",
+      "skipped": "वगळले"
+    },
+    "scheduleRunTrigger": {
+      "schedule": "वेळापत्रकानुसार",
+      "manual": "आता चालवले"
+    },
+    "filterOp": {
+      "eq": "बरोबर",
+      "ne": "नाही",
+      "gt": "पेक्षा जास्त",
+      "gte": "किमान",
+      "lt": "पेक्षा कमी",
+      "lte": "कमाल",
+      "in": "यापैकी एक",
+      "contains": "समाविष्ट आहे"
+    },
+    "eventStatus": {
+      "pending": "प्रलंबित",
+      "processing": "प्रक्रिया सुरू",
+      "done": "पूर्ण",
+      "failed": "अयशस्वी",
+      "ignored": "दुर्लक्षित"
+    },
+    "broadcastStatus": {
+      "draft": "मसुदा",
+      "queued": "रांगेत",
+      "sending": "पाठवत आहे",
+      "done": "पूर्ण"
+    },
+    "deliverySource": {
+      "schedule": "वेळापत्रक",
+      "event": "घटना सूचना",
+      "broadcast": "प्रसारण",
+      "command": "कमांड उत्तर",
+      "ai": "AI सहाय्यक",
+      "api": "ॲप",
+      "system": "सिस्टम"
+    },
+    "deliveryKind": {
+      "text": "मजकूर",
+      "document": "दस्तऐवज",
+      "photo": "फोटो",
+      "edit": "संपादन",
+      "delete": "हटवणे"
+    },
+    "deliveryStatus": {
+      "queued": "रांगेत",
+      "sending": "पाठवत आहे",
+      "sent": "पाठवले",
+      "failed": "अयशस्वी",
+      "dropped": "रद्द झाले",
+      "cancelled": "रद्द केले"
+    },
+    "feature": {
+      "core": "बॉट आणि चॅट",
+      "commands": "कमांड",
+      "templates": "साचे",
+      "schedules": "वेळापत्रके",
+      "reports": "अहवाल फाइल्स",
+      "events": "घटना सूचना",
+      "broadcasts": "प्रसारणे",
+      "actions": "बटणे आणि मंजुरी",
+      "dialogs": "संवाद",
+      "inbound": "मिळालेल्या फाइल्स",
+      "subscriptions": "प्राधान्ये",
+      "ai": "AI सहाय्यक",
+      "ops": "कामकाज"
+    },
+    "permission": {
+      "telegram_view": "टेलिग्राम सेटिंग्ज पहा",
+      "telegram_bots_manage": "बॉट व्यवस्थापित करा",
+      "telegram_chats_manage": "जोडलेले चॅट व्यवस्थापित करा",
+      "telegram_self_link": "माझे टेलिग्राम जोडा",
+      "telegram_destinations_manage": "गंतव्ये व्यवस्थापित करा",
+      "telegram_commands_manage": "कमांड व्यवस्थापित करा",
+      "telegram_templates_manage": "साचे व्यवस्थापित करा",
+      "telegram_schedules_manage": "वेळापत्रके व्यवस्थापित करा",
+      "telegram_events_manage": "घटना सूचना व्यवस्थापित करा",
+      "telegram_broadcasts_send": "प्रसारणे पाठवा",
+      "telegram_reports_run": "अहवाल चालवा",
+      "telegram_send": "टेलिग्रामवर पाठवा",
+      "telegram_ops_view": "वितरण स्थिती पहा",
+      "telegram_ops_manage": "वितरण पुन्हा करा किंवा रद्द करा",
+      "telegram_ops_content": "संदेशाचा मजकूर पहा"
+    },
+    "problem": {
+      "feature_disabled": "हे वैशिष्ट्य बंद आहे.",
+      "bot_token_invalid": "बॉट टोकन वैध नाही.",
+      "bot_token_mismatch": "हे टोकन दुसऱ्या बॉटचे आहे.",
+      "bot_unreachable": "टेलिग्रामशी संपर्क झाला नाही. पुन्हा प्रयत्न करा.",
+      "webhook_url_missing": "ॲपचा सार्वजनिक पत्ता सेट केलेला नाही.",
+      "webhook_failed": "टेलिग्रामने वेबहुक स्वीकारला नाही.",
+      "chat_not_found": "चॅट सापडले नाही.",
+      "chat_blocked": "या व्यक्तीने बॉट ब्लॉक केला आहे.",
+      "link_expired": "ही लिंक कालबाह्य झाली आहे.",
+      "link_used": "ही लिंक आधीच वापरली आहे.",
+      "destination_not_allowed": "तिथे पाठवण्याची परवानगी नाही.",
+      "template_invalid": "साच्यात त्रुटी आहेत.",
+      "template_variable_unknown": "साच्यात अज्ञात फील्ड वापरले आहे.",
+      "provider_unknown": "अज्ञात डेटा स्रोत.",
+      "provider_forbidden": "या प्रेक्षकांना हा डेटा पाहण्याची परवानगी नाही.",
+      "schedule_rule_invalid": "वेळापत्रकाची वेळ वैध नाही.",
+      "timezone_invalid": "अज्ञात वेळ क्षेत्र.",
+      "recipient_empty": "किमान एक प्राप्तकर्ता निवडा.",
+      "send_text_rejected": "हा मजकूर जसा आहे तसा पाठवता येत नाही.",
+      "file_too_large": "टेलिग्रामसाठी फाइल खूप मोठी आहे.",
+      "renderer_unavailable": "हा फाइल प्रकार उपलब्ध नाही.",
+      "delivery_not_retryable": "हा संदेश पुन्हा पाठवता येत नाही.",
+      "schema_outdated": "डेटाबेस अपडेट करणे आवश्यक आहे.",
+      "unauthenticated": "पुढे जाण्यासाठी साइन इन करा.",
+      "forbidden": "तुम्हाला परवानगी नाही.",
+      "not_found": "सापडले नाही.",
+      "validation_failed": "काही फील्ड वैध नाहीत.",
+      "rate_limited": "खूप विनंत्या. थोडा वेळ थांबा.",
+      "internal_error": "काहीतरी चुकले. नंतर पुन्हा प्रयत्न करा."
+    },
+    "reportColumnFormat": {
+      "text": "मजकूर",
+      "number": "संख्या",
+      "money": "रक्कम",
+      "date": "तारीख",
+      "datetime": "तारीख आणि वेळ",
+      "yesno": "हो / नाही"
+    }
+  },
+  "bot": {
+    "cmd": {
+      "start": "सुरू करा आणि खाते जोडा",
+      "help": "मी काय करू शकतो",
+      "stop": "सर्व संदेश थांबवा",
+      "settings": "तुमची संदेश सेटिंग्ज",
+      "whoami": "तुमचे जोडलेले खाते दाखवा",
+      "language": "भाषा बदला",
+      "report": "अहवाल मिळवा"
+    },
+    "start": {
+      "unlinked": "हा बॉट खाजगी आहे. तुमच्या ॲडमिनकडे लिंक मागा, किंवा ॲप उघडून \"टेलिग्राम जोडा\" निवडा.",
+      "linked": "{{name}} ({{role}}) म्हणून जोडले.",
+      "group_linked": "हा गट जोडला आहे. याला यांच्यासाठी संदेश मिळतील: {{audience}}.",
+      "already_linked": "तुम्ही आधीच {{name}} म्हणून जोडलेले आहात.",
+      "unmuted": "संदेश पुन्हा सुरू झाले.",
+      "audience_users": "{{count}} लोक"
+    },
+    "link": {
+      "expired": "ही लिंक कालबाह्य झाली आहे. ॲपमध्ये नवीन लिंक मागा.",
+      "used": "ही लिंक आधीच वापरली आहे.",
+      "other_account": "हे टेलिग्राम खाते आधीच दुसऱ्या कोणाशी जोडलेले आहे.",
+      "not_creator": "ज्याने ही लिंक बनवली तेच ती गटात वापरू शकतात.",
+      "pending_confirm": "हे आमंत्रण {{name}} यांच्यासाठी आहे. {{name}} यांनी ॲपमध्ये पुष्टी करण्याची वाट पाहत आहोत; पुष्टी झाल्यावर तुम्हाला इथे संदेश येईल.",
+      "confirmed_hint": "तुम्ही काय करू शकता ते पाहण्यासाठी /help पाठवा.",
+      "pending_notice": "{{admin}} यांच्याकडून तुमच्यासाठी टेलिग्राम लिंक प्रलंबित आहे. खाते तुमचे असल्यास ॲपमध्ये पुष्टी करा.",
+      "an_admin": "एक ॲडमिन"
+    },
+    "help": {
+      "header": "तुम्ही वापरू शकता अशा कमांड:",
+      "none": "तुमच्यासाठी अजून कोणत्याही कमांड नाहीत."
+    },
+    "stop": {
+      "done": "संदेश थांबवले आहेत. पुन्हा सुरू करण्यासाठी /start पाठवा."
+    },
+    "settings": {
+      "header": "तुमची संदेश सेटिंग्ज:",
+      "muted": "म्यूट",
+      "unmuted": "चालू",
+      "all": "सर्व संदेश: {{state}}",
+      "language": "भाषा: {{language}}"
+    },
+    "whoami": {
+      "linked": "तुम्ही {{name}} ({{role}}) आहात.",
+      "unlinked": "हे चॅट कोणत्याही खात्याशी जोडलेले नाही."
+    },
+    "language": {
+      "choose": "भाषा निवडा:",
+      "set": "भाषा मराठी केली.",
+      "unknown": "अज्ञात भाषा. यापैकी एक निवडा: {{list}}",
+      "names": {
+        "en": "English (इंग्रजी)",
+        "mr": "मराठी"
+      }
+    },
+    "error": {
+      "forbidden": "तुम्हाला यासाठी परवानगी नाही.",
+      "generic": "काहीतरी चुकले. नंतर पुन्हा प्रयत्न करा.",
+      "unknown_command": "अज्ञात कमांड. मी काय करू शकतो हे पाहण्यासाठी /help पाठवा.",
+      "feature_disabled": "हे बंद आहे.",
+      "rate_limited": "तुम्ही खूप वेगाने संदेश पाठवत आहात. एक मिनिट थांबा.",
+      "not_linked": "आधी हे चॅट जोडा: ॲप उघडून \"टेलिग्राम जोडा\" निवडा.",
+      "sender_not_linked": "आधी तुमचे स्वतःचे टेलिग्राम खाते जोडा: ॲप उघडून \"टेलिग्राम जोडा\" निवडा, मग इथे पुन्हा प्रयत्न करा."
+    },
+    "action": {
+      "expired": "हे बटण कालबाह्य झाले आहे.",
+      "used": "हे आधीच केले आहे.",
+      "confirm": "खात्री करण्यासाठी पुन्हा टॅप करा.",
+      "done": "झाले.",
+      "not_yours": "हे बटण तुमच्यासाठी नाही.",
+      "link_first": "आधी ॲपमध्ये तुमचे टेलिग्राम खाते जोडा.",
+      "failed": "हे झाले नाही. नंतर पुन्हा प्रयत्न करा.",
+      "cancelled": "रद्द केले.",
+      "confirm_button": "खात्री करा",
+      "cancel_button": "रद्द करा"
+    },
+    "dialog": {
+      "cancelled": "रद्द केले.",
+      "timeout": "हा संवाद कालबाह्य झाला.",
+      "invalid": "हे बरोबर वाटत नाही. पुन्हा प्रयत्न करा.",
+      "cancel_hint": "थांबवण्यासाठी /cancel पाठवा.",
+      "skip_hint": "हे वगळण्यासाठी /skip पाठवा.",
+      "send_photo": "एक फोटो पाठवा.",
+      "send_document": "एक फाइल पाठवा.",
+      "pick_choice": "कृपया एक बटण निवडा.",
+      "required": "ही पायरी आवश्यक आहे, ती वगळता येणार नाही.",
+      "nothing": "रद्द करण्यासारखे काही नाही.",
+      "done": "जतन केले. धन्यवाद.",
+      "failed": "हे जतन करता आले नाही. नंतर पुन्हा प्रयत्न करा."
+    },
+    "here": {
+      "saved": "हा विषय \"{{name}}\" म्हणून जतन केला.",
+      "not_topic": "जोडलेल्या गटाच्या फोरम विषयात /here आणि नाव पाठवा."
+    },
+    "command": {
+      "usage": "वापर: {{usage}}",
+      "wrong_chat": "ही आज्ञा या चॅटमध्ये चालत नाही."
+    },
+    "report": {
+      "list_header": "तुम्ही मिळवू शकता असे अहवाल:",
+      "none": "तुमच्यासाठी कोणतेही अहवाल नाहीत.",
+      "unknown": "अज्ञात अहवाल. यादी पाहण्यासाठी /report पाठवा.",
+      "failed": "अहवाल तयार होऊ शकला नाही. नंतर पुन्हा प्रयत्न करा.",
+      "too_large": "ही फाइल Telegram साठी खूप मोठी आहे.",
+      "download": "येथे डाउनलोड करा:",
+      "yes": "हो",
+      "no": "नाही",
+      "more": "आणखी अहवाल उपलब्ध आहेत. एखादा अहवाल मिळवण्यासाठी /report नंतर त्याचे नाव पाठवा."
+    },
+    "data": {
+      "failed": "माहिती आणता आली नाही. नंतर पुन्हा प्रयत्न करा."
+    },
+    "inbound": {
+      "not_handled": "धन्यवाद, पण मी इथे फाइल्स वापरू शकत नाही.",
+      "too_large": "ही फाइल खूप मोठी आहे.",
+      "type_not_allowed": "अशा प्रकारची फाइल स्वीकारली जात नाही.",
+      "unavailable": "सध्या फाइल्स स्वीकारता येत नाहीत.",
+      "download_failed": "फाइल डाउनलोड करता आली नाही. पुन्हा पाठवून पहा."
+    },
+    "ai": {
+      "consequence": "हे टेलिग्रामवर (@{{bot}}) {{name}} यांना {{what}} पाठवेल. {{audience}}",
+      "what": {
+        "text": "एक संदेश",
+        "file": "फाइल {{name}}",
+        "record": "{{type}} {{key}}",
+        "template": "संदेश \"{{name}}\"",
+        "report": "अहवाल {{name}}"
+      },
+      "audience": {
+        "user": "फक्त {{name}} हे पाहतील.",
+        "role": "या गटातील सर्वजण हे पाहतील ({{role}} म्हणून).",
+        "group": "या गटातील सर्वजण हे पाहतील."
+      },
+      "chats": "हे {{count}} चॅटवर जाईल."
+    }
+  }
+}

package/dist/ports/db.d.ts

@@ -0,0 +1,22 @@
+import { SqlFragment } from "./sql.js";
+/** Result of `DbPort.run`. */
+export interface RunResult {
+  /** Rows written by the statement. */
+  changes: number;
+  /** Rowid of the last inserted row, or null. */
+  lastRowId: number | null;
+}
+/** The database port. `d1Db(env.DB)` is the default; hosts may pass their own (for example a D1 session). */
+export interface DbPort {
+  /** All result rows. */
+  all<T = Record<string, unknown>>(q: SqlFragment): Promise<T[]>;
+  /** The first row, or null. */
+  first<T = Record<string, unknown>>(q: SqlFragment): Promise<T | null>;
+  /** Runs a write statement. */
+  run(q: SqlFragment): Promise<RunResult>;
+  /** One atomic batch (D1 has no interactive transactions). Returns the rows of each statement. */
+  batch<T = Record<string, unknown>>(qs: readonly SqlFragment[]): Promise<{
+    rows: T[];
+    changes: number;
+  }[]>;
+}

package/dist/ports/index.d.ts

@@ -0,0 +1,4 @@
+import { SqlFragment, SqlInput, SqlValue, isSqlFragment, sql } from "./sql.js";
+import { DbPort, RunResult } from "./db.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.js";
+export { type ActorInfo, type ActorPort, type AuditEntry, type AuditPort, type AuthorizePort, type ClockPort, type DbPort, type ErrorsPort, type FilesPort, type I18nPort, type IdsPort, type KeyringPort, type LogFields, type LogPort, type MetricsPort, type OpenedFile, type PortOrFactory, type RenderInput, type RenderedFile, type RendererPort, type RunResult, type SchedulerPort, type SettingsPort, type SqlFragment, type SqlInput, type SqlValue, type StoredFile, type TransportPort, type UserInfo, type UsersPort, isSqlFragment, sql };

package/dist/ports/ports.d.ts

@@ -0,0 +1,257 @@
+import { Audience } from "../contracts/chats.js";
+import { TelegramProblem } from "../contracts/problems.js";
+import { SqlFragment } from "./sql.js";
+import { TelegramPluginError } from "../engine/errors.js";
+import { Context } from "hono";
+type MaybePromise<T> = T | Promise<T>;
+/** What the plugin needs to know about an actor (for replies and menus). */
+export interface ActorInfo {
+  /** Host user id; null for a synthetic group-audience actor. */
+  userId: string | null;
+  /** Host role (matched against command roles and `cacheFor: "audience-role"`); null when none. */
+  role: string | null;
+  /** Preferred locale (`en`, `mr`, …); falls back to the chat / default locale. */
+  locale?: string | undefined;
+  /** Display name for replies and admin screens. */
+  name?: string | undefined;
+}
+/** Who is calling (admin API) and who a Telegram user is (live, every time). Required. */
+export interface ActorPort<A> {
+  /** Host session → actor, or null when not signed in (gives 401 `unauthenticated`). */
+  fromRequest(c: Context): MaybePromise<A | null>;
+  /** Linked app user → live actor, or null when the user is disabled or gone. */
+  forUser(userId: string): MaybePromise<A | null>;
+  /** Group audience → synthetic actor with no personal scopes. */
+  forAudience(audience: Audience): MaybePromise<A | null>;
+  /** Plain facts about an actor (sync, cheap; called often). */
+  describe(actor: A): ActorInfo;
+}
+/**
+ * Host permission check. `permission` is a plugin name (`telegram.bots.manage`) or a host data permission;
+ * `resource` is an optional object the check is about. False gives 403 `forbidden` on admin routes. Required.
+ */
+export type AuthorizePort<A> = (actor: A, permission: string, resource?: unknown) => MaybePromise<boolean>;
+/** A host user as shown in linking screens. */
+export interface UserInfo {
+  /** Host user id (the value stored in `tg_chat.user_id`). */
+  id: string;
+  /** Display name. */
+  name: string;
+  /** Host role, or null. */
+  role: string | null;
+  /** Preferred locale. */
+  locale?: string | undefined;
+}
+/** The host's users, for linking screens and `{ role }` recipients. Optional. */
+export interface UsersPort {
+  /** One user by id (checked before an admin link code is issued: unknown → 404 `not_found`). */
+  find(ref: string): MaybePromise<UserInfo | null>;
+  /**
+   * Users matching a search string, for the "link a user" picker (`GET /admin/users?q=`, needs
+   * `telegram.chats.manage`). Without it that route answers 404 `feature_disabled` and meta has `userSearch: false`.
+   * `limit` is 1–50 (default 20); return at most that many.
+   */
+  search?(query: string, opts: {
+    limit: number;
+  }): MaybePromise<UserInfo[]>;
+  /** All user ids with a role (for `{ role }` recipients). */
+  byRole?(role: string): MaybePromise<string[]>;
+}
+/** A file kept by the host's files port. */
+export interface StoredFile {
+  /** Host file id or R2 key. */
+  ref: string;
+  /** File name including extension. */
+  name: string;
+  /** MIME type. */
+  mime: string;
+  /** Size in bytes, or null when unknown. */
+  size: number | null;
+}
+/** A stored file opened for reading. */
+export interface OpenedFile extends StoredFile {
+  /** File contents (consumed once). */
+  body: ReadableStream<Uint8Array>;
+}
+/** The host's file service over R2 (+ its permissions). Optional; `r2Files` is the minimal adapter. */
+export interface FilesPort<A = unknown> {
+  /**
+   * Stores a file (inbound photos / documents, rendered reports). `tags` always include `source: "telegram"`.
+   * `actor` is the user the file belongs to, or null for system writes.
+   */
+  put(input: {
+    name: string;
+    mime: string;
+    body: ReadableStream<Uint8Array> | ArrayBuffer | Uint8Array;
+    tags?: Record<string, string>;
+  }, actor: A | null): Promise<StoredFile>;
+  /** Opens a file by ref, or null when missing. `actor` null = a send after the read check already passed. */
+  open(ref: string, actor: A | null): Promise<OpenedFile | null>;
+  /**
+   * Read check for file sends by ref (false gives 403 `forbidden`). Required for `source: "files"` sends: without it
+   * every such send is refused (deny by default).
+   */
+  canRead?(actor: A, ref: string): MaybePromise<boolean>;
+  /** A link to the file in the app (sent instead of files over Telegram's 50 MB upload limit). */
+  url?(ref: string): MaybePromise<string | null>;
+}
+/** One audit entry. Never contains tokens, message text or chat ids. */
+export interface AuditEntry {
+  /** Host user id of the actor; null for system jobs. */
+  actor: string | null;
+  /** Entity kind (`bot`, `template`, `schedule`, …). */
+  entity: string;
+  /** Id of the entity, or null. */
+  entityId: string | null;
+  /** What happened (`create`, `update`, `delete`, `rekey`, …). */
+  action: string;
+  /** Changed fields (secrets removed). */
+  diff?: Record<string, unknown> | undefined;
+  /** Epoch ms UTC. */
+  at: number;
+}
+/** Returns SQL to add to the same batch as the write it records. Default: insert into `tg_audit`. */
+export type AuditPort = (entry: AuditEntry) => SqlFragment[];
+/**
+ * Maps a plugin problem to the host's error type. When set, the plugin's routes throw what it returns (so the
+ * host's `onError` renders it) instead of answering problem+json themselves. `problem` is the full RFC 9457 body
+ * (`code`, `title`, `status`, `detail`, `instance` and extension members such as `issues`, `errors`, `reasons`,
+ * `retryAfter`); `error` is the original `TelegramPluginError`. Optional.
+ */
+export type ErrorsPort = (problem: TelegramProblem, error: TelegramPluginError) => Error;
+/** Structured log fields (JSON-serializable values). */
+export type LogFields = Record<string, unknown>;
+/**
+ * Structured log. `evt` is a stable name (`tg.send`, `tg.tick`). Never pass tokens, URLs, text or chat ids. Calls
+ * must not throw. Default `consoleLog` (JSON lines, secrets redacted).
+ */
+export interface LogPort {
+  /** Verbose detail (off unless `logLevel: "debug"`). */
+  debug(evt: string, fields?: LogFields): void;
+  /** Normal operations. */
+  info(evt: string, fields?: LogFields): void;
+  /** Recoverable problems (retries, skipped deliveries). */
+  warn(evt: string, fields?: LogFields): void;
+  /** Failures that need attention. */
+  error(evt: string, fields?: LogFields): void;
+}
+/** Time source. Default `systemClock`; tests use `TestClock`. */
+export interface ClockPort {
+  /** Epoch ms, UTC. */
+  now(): number;
+  /** Waits (drain pacing). Default `setTimeout`; tests pass a fake that advances `now()`. */
+  sleep?(ms: number): Promise<void>;
+}
+/** Id generator. Default `uuidv7Ids`. */
+export interface IdsPort {
+  /** UUIDv7 (time-ordered) text id. */
+  uuid(): string;
+}
+/** Host locales and optional host translations of bot strings. */
+export interface I18nPort {
+  /** Locales the bot offers (`/language`). The plugin ships `en` and `mr` strings. */
+  locales: readonly string[];
+  /** Locale for chats and users without one; must be in `locales`. */
+  defaultLocale: string;
+  /** Host translation; return undefined to fall back to the plugin's strings. */
+  t?(locale: string, key: string, vars?: Record<string, unknown>): string | undefined;
+}
+/** Host-wide formatting defaults. */
+export interface SettingsPort {
+  /** Default IANA zone for schedules and dates. */
+  timezone: string;
+  /** ISO 4217 code for the `money` filter. */
+  currency?: string;
+  /** Digits in the minor unit (INR paise = 2). */
+  minorUnitDigits?: number;
+  /** Locale used for number formatting when the chat has none. */
+  numberLocale?: string;
+}
+/** Encrypts bot tokens and webhook secrets. Format `v1.<kid>.<iv>.<ct>`; AAD binds a ciphertext to its row. */
+export interface KeyringPort {
+  /** Key id used for new ciphertexts. */
+  activeKid(): string;
+  /** Encrypts with the active key; `aad` is the row binding (for example the bot id). */
+  encrypt(plaintext: string, aad: string): Promise<string>;
+  /** Decrypts with the key named in the ciphertext. Throws on an unknown key or a wrong `aad`. */
+  decrypt(ciphertext: string, aad: string): Promise<string>;
+  /** Key id inside a ciphertext (for the rekey job and health). */
+  kidOf(ciphertext: string): string | null;
+}
+/** How queued deliveries get drained: by the tick (default), a Queue, or a Durable Object. */
+export interface TransportPort {
+  /** Transport id, shown in meta and health. */
+  readonly name: "outbox" | "queue" | "do" | (string & {});
+  /** Ask for a drain soon (after a commit). Must be cheap and safe to call often. */
+  kick(botIds?: readonly string[]): Promise<void>;
+}
+/** How due schedules get fired: the minute tick (default) or DO alarms. */
+export interface SchedulerPort {
+  /** Scheduler id, shown in meta and health. */
+  readonly name: "cron" | "do" | (string & {});
+  /** Called after a schedule's `next_run_at` changes (DO scheduler sets an alarm). */
+  scheduled?(scheduleId: string, nextRunAt: number | null): Promise<void>;
+}
+/** What a `RendererPort` receives for one report file. */
+export interface RenderInput {
+  /** Rendered data rows / document model from the provider. */
+  data: unknown;
+  /** Output file name including extension. */
+  fileName: string;
+  /** Locale of the recipient. */
+  locale: string;
+  /** IANA zone for dates. */
+  timezone: string;
+  /** The template's layout options (columns, orientation…), renderer-specific. */
+  layout?: Record<string, unknown> | undefined;
+  /** For HTML-based renderers: the rendered template HTML. */
+  html?: string | undefined;
+  /** Report title (rendered file name without extension, or the layout title). */
+  title?: string | undefined;
+  /** ISO 4217 code and minor digits for money columns (host settings). */
+  currency?: string | undefined;
+  /** Digits in the currency's minor unit (money values are integer minor units). */
+  minorDigits?: number | undefined;
+  /** Localized words for `yesno` columns. */
+  labels?: {
+    yes: string;
+    no: string;
+  } | undefined;
+}
+/** A renderer's output. */
+export interface RenderedFile {
+  /** File name including extension. */
+  name: string;
+  /** MIME type. */
+  mime: string;
+  /** File contents. */
+  body: Uint8Array | ReadableStream<Uint8Array>;
+  /** Size in bytes, when known (needed to pick upload vs link over 50 MB). */
+  size?: number | undefined;
+}
+/**
+ * Report file renderer (`csv`, `pdf`, or host custom). `env` is the Worker env of the current invocation (the
+ * value the plugin's `env` mapper received), so a renderer can use per-request bindings such as Browser Rendering.
+ */
+export interface RendererPort<E = unknown> {
+  /** File format key used by templates (`csv`, `pdf`, `xlsx`, …). */
+  readonly format: string;
+  /** MIME type of the produced file. */
+  readonly mime: string;
+  /** Produces the file. A throw fails the report delivery (logged, retried by the outbox). */
+  render(input: RenderInput, env: E): Promise<RenderedFile>;
+}
+/** Optional counters (for example Analytics Engine via `analyticsEngineMetrics`). Calls must not throw. */
+export interface MetricsPort {
+  /** Adds `value` (default 1) to a counter. */
+  count(name: string, value?: number, tags?: Record<string, string>): void;
+  /** Records a duration in ms. */
+  timing(name: string, ms: number, tags?: Record<string, string>): void;
+}
+/**
+ * A port given directly, or built per invocation from the Worker env (`(env) => analyticsEngineMetrics(env.AE)`),
+ * so it can use per-request bindings without capturing them globally. The factory runs once per request, job run
+ * or queue batch; returning undefined means "not available in this invocation".
+ */
+export type PortOrFactory<P, E> = P | ((env: E) => P | undefined);
+export {};