@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to `@prajwalshete/telegram-plugin` (working name before the first release: `cf-telegram-plugin`). The format follows [Keep a Changelog](https://keepachangelog.com/),
+and the package uses [semantic versioning](https://semver.org/) (0.x: minor versions may break).
+
+Schema changes are listed under **Schema**. Upgrade by applying the new `reference.sql` statements (or
+regenerating your Drizzle migration); the plugin answers `schema_outdated` until the tables match.
+
+## 0.1.1 (2026-10-28)
+
+No code changes: first release published from GitHub Actions with npm Trusted Publishing.
+
+## 0.1.0 (2026-10-28)
+
+First release.
+
+### Added
+
+- `createTelegramPlugin()` with routes (admin, me, webhook, dev poll), jobs (`telegram:tick`, `telegram:cleanup`,
+  `telegram:rekey`), `emit`, `preview`, `enqueue`, `kick`, `queue`, `meta`, `aiToolSpec`.
+- `define{Provider,Command,Event,Action,Dialog,Audience,FileSource}` and `definitions<Actor, Env>()`.
+- `TelegramPluginError` (`code`, `status`, `detail`, `extensions`, `toProblem()`), the only error type the
+  programmatic API throws (unexpected failures: `internal_error` with `cause`); `isTelegramPluginError`,
+  `toPluginError`. `ports.errors(problem, error)` receives the full problem body including extension members.
+- Problem codes `unauthenticated` (401, signed out) and `internal_error` (500), with en/mr labels.
+- Per-invocation env for ports: `ports.files` / `ports.metrics` accept `(env) => port`, renderers get
+  `render(input, env)`, file sources get `resolve({ actor, ref, env })`.
+- Per-bot feature switches (`PATCH /admin/bots/:id { features }`, off only, validated against the app's features).
+- Custom template filters (`options.filters`, `defineFilter`) in rendering, validation, preview and `/admin/meta`.
+- `GET /admin/users?q=` (user picker over `ports.users.search`); meta `filters` and `userSearch`.
+- Default log is `consoleLog` at `info` (token redaction); `ports.log` also takes a level or `"silent"`.
+- Bots (encrypted tokens, webhook or polling), linking, chats, forum topics, destinations, subscriptions.
+- Commands, templates (versions, preview), schedules (daily/weekly/monthly/cron/once, any IANA zone), reports
+  (CSV built in, PDF via Browser Rendering or a host renderer), events, broadcasts, send intents.
+- Actions (confirm, single use, live permission checks), dialogs (text, choice, photo, document steps), inbound
+  files, AI send bridge with per-audience guards.
+- Outbox with pacing, retries and Telegram error handling; transports `cron`, `queue` (+ DLQ) and `do`
+  (`TelegramBotDO`); Analytics Engine metrics adapter; delivery log and health.
+- Subpaths `server`, `do`, `renderers`, `schema` (+ `reference.sql`), `contracts`, `client`, `locales`, `testing`
+  (`FakeTelegram`, `createTestPlugin`). CLI `cf-telegram-plugin keyring new|rotate`.
+
+### Behaviour notes
+
+- Finishing an action on a message also invalidates the other action buttons of that message.
+- A single-use action's claim and the SQL the action returns commit in one batch. Actions that write on their own
+  inside `run` are at-least-once (make those writes idempotent).
+- Deleting or pausing a schedule moves or clears the Durable Object scheduler wake.
+
+- Pre-release review fixes (docs/REVIEW-0.1.0.md):
+  - **Security:** record sends keep a field only when both the sender's and the audience's provider runs returned
+    it with a non-null value (null redaction no longer leaks). Previews and renders for another audience
+    (`preview()`, `/admin/send/preview`, `/admin/templates/preview`, `/admin/broadcasts/:id/preview`,
+    `/admin/reports/render`) show the caller ∩ audience view and need the provider permission.
+  - **Security:** in groups, host commands, `/report`, inbound files and AI free text need a linked sender
+    (`groups.requireLinkedSender`, default true; per command `groupMembers: "any"`). Group `/start` unmute is
+    guarded like `/stop`. An admin invite code for another user parks a pending link the invited user confirms
+    (`/me/links/pending…`; `LinkResult.requiresConfirmation`).
+  - **Security:** `Idempotency-Key` is per caller/route/body, replays only JSON after the permission check, never
+    stores link codes or files, and in-flight keys expire after 60 s. `/admin/send` dedupe keys are per caller.
+    Encrypted bot columns use per-column AAD (`tg_bot.token:<id>`, `tg_bot.webhook:<id>`).
+  - **Security:** file sends by ref need `FilesPort.canRead`; `r2Files` denies by default (`r2Files(b, { canRead })`).
+  - Queue mode: a failed `queue.send` un-records the update and answers 500 so Telegram retries. `queue()` handles
+    the plugin's messages in mixed batches and returns `true` only for an all-plugin batch.
+  - Reliability: stuck schedule runs are resumed by the tick (same slot; `failed` / `run_stuck` after 3 tries or
+    1 h); the drain commits sends every 5 sends / 1 s; events retry transient provider failures; provider data wins
+    over payload fields; no orphan action tokens on deduped sends.
+  - `/report <key>` finds any key (the list is capped at 30 with a hint); `/help` lists only runnable commands;
+    callback answers are cut on grapheme boundaries. Schema check is cached per database.
+- Review follow-ups:
+  - A used admin invite tells the invited user in their already-linked chat on that bot (en/mr
+    `bot.link.pending_notice`) and calls the new hook `onPendingLink(pending, userId)` (show an in-app notice).
+  - `Idempotency-Key`: the in-flight entry is a lease with a fencing token, renewed every 20 s while the request
+    runs, so a request longer than 60 s is never taken over by a retry (409 instead), and a request that lost its
+    lease cannot overwrite or delete the new holder's entry.
+  - Queue mode: when `queue.send` fails **and** un-recording the update fails too, the update is processed in
+    `waitUntil` (logged `tg.webhook_unrecord_failed`, metric outcome `queue_fallback`) instead of being lost.
+  - Command replies use the orphan action-token guard (a re-processed update leaves no extra tokens).
+  - `HealthDto.schedules`: `stuckRuns` (`running` > 10 min) and `runStuckFailed24h`.
+- **Breaking (pre-release):** command `defaultRoles: []` now means **no** role (omit it or use `["*"]` = `ANY_ROLE`
+  for any role; per-bot overrides alike). Every host context (`ProviderContext`, `CommandContext`, `ActionContext`,
+  `DialogFinishContext`, dialog `choices`, audience `resolve`) gets `env`. `./server` no longer exports the raw
+  services and engine stages (they check no permissions); `plugin.runtime()` is internal. The client declares
+  `/admin/reports/render` as a `BinaryEndpoint`. Non-plugin render errors in events are `render_failed`.
+  `engines.node` is `>=20` (CLI only; the library runs on Workers).
+
+### Schema
+
+- Schema version 2 (19 `tg_*` tables). Table names are fixed; `telegramTables()` takes no options.
+- v2 adds `CREATE UNIQUE INDEX IF NOT EXISTS tg_bot_tg_bot_uq ON tg_bot (tenant, tg_bot_id) WHERE deleted_at IS NULL`
+  (one live row per Telegram bot and tenant). Soft-delete duplicates before applying it; until then routes answer
+  `503 schema_outdated` with `missing: ["index:tg_bot_tg_bot_uq"]`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prajwal Shete
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# telegram-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Telegram bots for apps on **Cloudflare Workers + Hono + D1 (+ R2)**. Logic only, no UI: you get an HTTP API,
+Zod contracts, permission names and en/mr labels, and your app draws its own screens.
+- **Bots and people:** connect bots (tokens encrypted with a keyring), link app users with a one-time `/start`
+  code, register groups and forum topics, named destinations.
+- **Content:** host-defined commands, templates (safe Telegram HTML, Mustache subset), schedules in any IANA zone,
+  CSV/PDF reports, event alerts emitted inside your own D1 batch, broadcasts, subscriptions and quiet hours.
+- **Interactive:** action buttons (confirm, single use, re-checked permissions), multi-step dialogs with photo and
+  document steps, inbound files.
+- **AI bridge:** a "send to Telegram" preview → confirm → commit flow with guards (allowed destinations, money and
+  link checks per audience), plus a JSON Schema tool spec.
+- **Delivery:** a D1 outbox with pacing, retries, 429/migration/blocked handling. Transports: cron tick, Queues,
+  or one Durable Object per bot. Delivery log, health, metrics.
+
+## Install
+
+```sh
+pnpm add @prajwalshete/telegram-plugin hono zod     # drizzle-orm is an optional peer (only for @prajwalshete/telegram-plugin/schema)
+npx @prajwalshete/telegram-plugin keyring new       # → TELEGRAM_KEYRING in .dev.vars / wrangler secret put
+cp node_modules/@prajwalshete/telegram-plugin/dist/schema/reference.sql migrations/0001_telegram.sql
+```
+
+Peers: `hono` ^4.13, `zod` ^4.6, `drizzle-orm` ^1.0.0-rc.5 (optional). Runtime dependency: `croner`. Node ≥ 20 for the CLI (the library runs on the Workers runtime).
+
+## Quick start
+
+```ts
+import { createTelegramPlugin } from "@prajwalshete/telegram-plugin/server";
+import { Hono } from "hono";
+
+interface Env {
+  DB: D1Database;
+  TELEGRAM_KEYRING: string;
+  PUBLIC_BASE_URL?: string;
+}
+interface Actor {
+  userId: string;
+  role: string;
+}
+
+const telegram = createTelegramPlugin<Env, Actor>({
+  env: (env) => ({ db: env.DB, keyring: env.TELEGRAM_KEYRING, publicBaseUrl: env.PUBLIC_BASE_URL }),
+  ports: {
+    actor: {
+      fromRequest: async (c) => yourSession(c), // who is calling the admin API (null = signed out)
+      forUser: (userId) => yourUserById(userId), // a linked Telegram user's live app actor
+      forAudience: () => null,
+      describe: (a) => ({ userId: a.userId, role: a.role }),
+    },
+    authorize: (actor, permission) => can(actor.role, permission), // "telegram.bots.manage", your own perms…
+  },
+  features: { commands: true, templates: true, schedules: true },
+});
+
+const app = new Hono<{ Bindings: Env }>().route("/api/telegram", telegram.routes);
+
+export default {
+  fetch: app.fetch,
+  scheduled: async (c, env, ctx) => {
+    for (const job of telegram.jobs.filter((j) => j.cron === c.cron))
+      ctx.waitUntil(job.run({ env, now: c.scheduledTime, cron: c.cron }));
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+`yourSession`, `yourUserById` and `can` are your app's own code. A complete, tested app is in
+[`examples/reference-host`](https://github.com/PrajwalShete/telegram-plugin/tree/main/examples/reference-host).
+
+## Subpaths
+
+| Import                                               | Runs in              | Contents                                                   |
+| ---------------------------------------------------- | -------------------- | ---------------------------------------------------------- |
+| `@prajwalshete/telegram-plugin/server`               | worker               | `createTelegramPlugin`, `define*` helpers, ports, adapters |
+| `@prajwalshete/telegram-plugin/do`                   | worker               | `TelegramBotDO` (optional per-bot Durable Object)          |
+| `@prajwalshete/telegram-plugin/renderers`            | worker               | CSV and PDF report renderers                               |
+| `@prajwalshete/telegram-plugin/schema`               | worker / drizzle-kit | Drizzle tables (`tg_*`), `referenceSql()`                  |
+| `@prajwalshete/telegram-plugin/schema/reference.sql` | —                    | Plain SQL schema for hosts without Drizzle                 |
+| `@prajwalshete/telegram-plugin/contracts`            | browser + worker     | Zod DTOs, feature keys, permissions, problem codes         |
+| `@prajwalshete/telegram-plugin/client`               | browser              | Typed admin API client types (Hono `hc`)                   |
+| `@prajwalshete/telegram-plugin/locales/{en,mr}.json` | any                  | Labels for every enum + bot strings                        |
+| `@prajwalshete/telegram-plugin/testing`              | tests                | `FakeTelegram`, `createTestPlugin`, update builders        |
+
+## Errors and logs
+
+Admin routes answer RFC 9457 `application/problem+json` with a stable `code` (`unauthenticated` 401, `forbidden`
+403, `validation_failed` with `issues[]`, `template_invalid` with `errors[]`, `send_text_rejected` with `reasons[]`, …),
+or throw your own error type when you set `ports.errors(problem, error)`. The programmatic API (`emit`, `preview`,
+`enqueue`, `kick`, `aiToolSpec`) throws only `TelegramPluginError` (`code`, `status`, `extensions`, `toProblem()`);
+check with `isTelegramPluginError`. Logs go to the built-in `consoleLog` (JSON lines, tokens redacted) at `info`
+unless you pass `ports.log` (a `LogPort` or `"debug" | "info" | "warn" | "error" | "silent"`).
+
+## Data protection
+
+- Every provider runs as the recipient's audience. Record sends keep a field only when both the sender and the
+  audience got it with a non-null value; previews and renders for another audience show the caller ∩ audience view.
+- In groups, members must link their own Telegram before commands, `/report`, files or AI free text run as the
+  group's audience (`groups.requireLinkedSender`, default on). An admin invite for another user waits for that
+  user's confirmation in the app.
+- `./server` exports only entry points that check permissions (routes and plugin methods) plus pure helpers.
+
+## Documentation
+
+The [integration guide](https://github.com/PrajwalShete/telegram-plugin/tree/main/docs/guide) covers install,
+schema, Worker wiring, ports, permissions, providers/commands/events/actions/dialogs, features, building a settings
+UI, the AI bridge, local development, going live, operations, troubleshooting and a full reference.
+
+## License
+
+MIT. See [CHANGELOG.md](CHANGELOG.md) for changes.

package/dist/adapters/clock.d.ts

@@ -0,0 +1,3 @@
+import { ClockPort } from "../ports/ports.js";
+/** Default clock: `Date.now()` (epoch ms UTC); no `sleep`, so the runtime waits with `setTimeout`. */
+export declare const systemClock: ClockPort;

package/dist/adapters/clock.js

@@ -0,0 +1,4 @@
+// src/adapters/clock.ts
+/** Default clock: `Date.now()` (epoch ms UTC); no `sleep`, so the runtime waits with `setTimeout`. */
+const systemClock = { now: () => Date.now() };
+export { systemClock };

package/dist/adapters/console-log.d.ts

@@ -0,0 +1,13 @@
+import { LogFields, LogPort } from "../ports/ports.js";
+declare const LEVELS: readonly ["debug", "info", "warn", "error"];
+type Level = (typeof LEVELS)[number];
+/** Strips anything shaped like a bot token or a Bot API URL. A safety net; callers must not log them at all. */
+export declare function redactSecrets(text: string): string;
+/** JSON-lines logger on `console` (Workers Logs picks it up). */
+export declare function consoleLog(opts?: {
+  level?: Level;
+  base?: LogFields;
+}): LogPort;
+/** Logger that drops everything. */
+export declare const silentLog: LogPort;
+export {};

package/dist/adapters/console-log.js

@@ -0,0 +1,41 @@
+// src/adapters/console-log.ts
+const LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+/** Strips anything shaped like a bot token or a Bot API URL. A safety net; callers must not log them at all. */
+function redactSecrets(text) {
+	return text.replace(/api\.telegram\.org\/(file\/)?bot[^\s"'/]*/gi, "api.telegram.org/$1bot<redacted>").replace(/\b\d{5,20}:[A-Za-z0-9_-]{30,}\b/g, "<redacted-token>");
+}
+/** JSON-lines logger on `console` (Workers Logs picks it up). */
+function consoleLog(opts = {}) {
+	const min = LEVELS.indexOf(opts.level ?? "info");
+	const write = (level, evt, fields) => {
+		if (LEVELS.indexOf(level) < min) return;
+		const line = redactSecrets(JSON.stringify({
+			level,
+			evt,
+			...opts.base,
+			...fields
+		}));
+		if (level === "error") console.error(line);
+		else if (level === "warn") console.warn(line);
+		else console.log(line);
+	};
+	return {
+		debug: (evt, fields) => write("debug", evt, fields),
+		info: (evt, fields) => write("info", evt, fields),
+		warn: (evt, fields) => write("warn", evt, fields),
+		error: (evt, fields) => write("error", evt, fields)
+	};
+}
+/** Logger that drops everything. */
+const silentLog = {
+	debug() {},
+	info() {},
+	warn() {},
+	error() {}
+};
+export { consoleLog, redactSecrets, silentLog };

package/dist/adapters/d1-db.d.ts

@@ -0,0 +1,5 @@
+import { DbPort } from "../ports/db.js";
+/** D1 allows at most 100 bound parameters per statement. */
+export declare const D1_MAX_PARAMS = 100;
+/** The default `DbPort` over a D1 binding (or a D1 session). */
+export declare function d1Db(db: D1Database | D1DatabaseSession): DbPort;

package/dist/adapters/d1-db.js

@@ -0,0 +1,37 @@
+// src/adapters/d1-db.ts
+/** D1 allows at most 100 bound parameters per statement. */
+const D1_MAX_PARAMS = 100;
+function prepare(db, q) {
+	if (q.params.length > 100) throw new RangeError(`statement has ${q.params.length} params; D1 allows 100 (chunk the insert)`);
+	const stmt = db.prepare(q.text);
+	return q.params.length > 0 ? stmt.bind(...q.params) : stmt;
+}
+function runResult(meta) {
+	return {
+		changes: meta.changes ?? 0,
+		lastRowId: meta.last_row_id ?? null
+	};
+}
+/** The default `DbPort` over a D1 binding (or a D1 session). */
+function d1Db(db) {
+	const d = db;
+	return {
+		async all(q) {
+			return (await prepare(d, q).all()).results;
+		},
+		async first(q) {
+			return await prepare(d, q).first() ?? null;
+		},
+		async run(q) {
+			return runResult((await prepare(d, q).run()).meta);
+		},
+		async batch(qs) {
+			if (qs.length === 0) return [];
+			return (await d.batch(qs.map((q) => prepare(d, q)))).map((r) => ({
+				rows: r.results ?? [],
+				changes: r.meta.changes ?? 0
+			}));
+		}
+	};
+}
+export { D1_MAX_PARAMS, d1Db };

package/dist/adapters/ids.d.ts

@@ -0,0 +1,5 @@
+import { ClockPort, IdsPort } from "../ports/ports.js";
+/** RFC 9562 UUIDv7: 48-bit ms timestamp, version 7, variant 10, 74 random bits. */
+export declare function uuidv7(now?: number): string;
+/** Default ids port (UUIDv7 from the given clock). */
+export declare function uuidv7Ids(clock?: ClockPort): IdsPort;

package/dist/adapters/ids.js

@@ -0,0 +1,25 @@
+// src/adapters/ids.ts
+const HEX = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+/** RFC 9562 UUIDv7: 48-bit ms timestamp, version 7, variant 10, 74 random bits. */
+function uuidv7(now = Date.now()) {
+	const b = /* @__PURE__ */ new Uint8Array(16);
+	crypto.getRandomValues(b);
+	let ts = Math.max(0, Math.floor(now));
+	for (let i = 5; i >= 0; i--) {
+		b[i] = ts % 256;
+		ts = Math.floor(ts / 256);
+	}
+	b[6] = (b[6] ?? 0) & 15 | 112;
+	b[8] = (b[8] ?? 0) & 63 | 128;
+	let s = "";
+	for (let i = 0; i < 16; i++) {
+		if (i === 4 || i === 6 || i === 8 || i === 10) s += "-";
+		s += HEX[b[i] ?? 0];
+	}
+	return s;
+}
+/** Default ids port (UUIDv7 from the given clock). */
+function uuidv7Ids(clock) {
+	return { uuid: () => uuidv7(clock ? clock.now() : Date.now()) };
+}
+export { uuidv7, uuidv7Ids };

package/dist/adapters/index.d.ts

@@ -0,0 +1,7 @@
+import { systemClock } from "./clock.js";
+import { consoleLog, redactSecrets, silentLog } from "./console-log.js";
+import { D1_MAX_PARAMS, d1Db } from "./d1-db.js";
+import { uuidv7, uuidv7Ids } from "./ids.js";
+import { AnalyticsEngineLike, AnalyticsEngineMetricsOptions, analyticsEngineMetrics, noopMetrics } from "./metrics.js";
+import { R2FilesOptions, r2Files } from "./r2-files.js";
+export { type AnalyticsEngineLike, type AnalyticsEngineMetricsOptions, D1_MAX_PARAMS, type R2FilesOptions, analyticsEngineMetrics, consoleLog, d1Db, noopMetrics, r2Files, redactSecrets, silentLog, systemClock, uuidv7, uuidv7Ids };

package/dist/adapters/keyring.d.ts

@@ -0,0 +1,50 @@
+import { KeyringPort } from "../ports/ports.js";
+/** Shape of the `TELEGRAM_KEYRING` secret. */
+export interface KeyringSecret {
+  /** Key id used for new ciphertexts; must be in `keys`. */
+  active: string;
+  /** Master keys by id (`[A-Za-z0-9_-]{1,32}`), base64 or base64url, at least 32 bytes each. */
+  keys: Record<string, string>;
+}
+/** The default `KeyringPort` (`webCryptoKeyring`), plus rekey helpers. */
+export interface WebCryptoKeyring extends KeyringPort {
+  /** True when the blob was written with a key other than the active one (the rekey job re-encrypts it). */
+  needsRekey(ciphertext: string): boolean;
+  /** All key ids in the secret. */
+  readonly kids: readonly string[];
+}
+/** Thrown for an invalid keyring secret, an unknown key id, or a ciphertext that fails to decrypt. */
+export declare class KeyringError extends Error {
+  /** Always `"KeyringError"`. */
+  readonly name = "KeyringError";
+}
+/** Unpadded base64url encoding of bytes. */
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+/** Accepts base64 and base64url, with or without padding. Throws on other characters. */
+export declare function base64ToBytes(text: string): Uint8Array;
+/** Validates the secret JSON (string or parsed object). Error messages never include key material. */
+export declare function parseKeyringSecret(input: string | KeyringSecret): {
+  active: string;
+  keys: Map<string, Uint8Array>;
+};
+/** Key id of a `v1.<kid>.…` blob, or null when the shape is wrong. */
+export declare function kidOfCiphertext(ciphertext: string): string | null;
+/**
+ * The default keyring: HKDF-SHA-256 per key id → AES-256-GCM, format `v1.<kid>.<iv>.<ct>`. Throws `KeyringError`
+ * on an invalid secret (bad JSON, short keys, `active` missing from `keys`).
+ */
+export declare function webCryptoKeyring(secret: string | KeyringSecret): WebCryptoKeyring;
+/** Random bytes as base64url (for webhook secrets and link codes). */
+export declare function randomBase64Url(bytes?: number): string;
+/**
+ * A fresh keyring secret JSON. Pass the current secret to add a new active key and keep the old ones (rotation).
+ */
+export declare function generateKeyringSecret(opts?: {
+  kid?: string;
+  existing?: string | KeyringSecret;
+}): string;
+/**
+ * Constant-time string comparison (webhook secrets). Both sides are hashed first, so different lengths take the
+ * same time and reveal nothing. Uses `crypto.subtle.timingSafeEqual` in workerd, a XOR loop elsewhere.
+ */
+export declare function timingSafeEqualStrings(a: string, b: string): Promise<boolean>;

package/dist/adapters/keyring.js

@@ -0,0 +1,174 @@
+// src/adapters/keyring.ts
+/** Thrown for an invalid keyring secret, an unknown key id, or a ciphertext that fails to decrypt. */
+var KeyringError = class extends Error {
+	/** Always `"KeyringError"`. */
+	name = "KeyringError";
+};
+const VERSION = "v1";
+const KID_RE = /^[A-Za-z0-9_-]{1,32}$/;
+const HKDF_SALT = new TextEncoder().encode("cf-telegram-plugin/keyring/v1");
+const MIN_KEY_BYTES = 32;
+const IV_BYTES = 12;
+/** Unpadded base64url encoding of bytes. */
+function bytesToBase64Url(bytes) {
+	let s = "";
+	for (const b of bytes) s += String.fromCharCode(b);
+	return btoa(s).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/** Accepts base64 and base64url, with or without padding. Throws on other characters. */
+function base64ToBytes(text) {
+	const clean = text.trim().replaceAll("-", "+").replaceAll("_", "/");
+	if (!/^[A-Za-z0-9+/]*={0,2}$/.test(clean)) throw new KeyringError("invalid base64");
+	const bin = atob(clean.padEnd(Math.ceil(clean.length / 4) * 4, "="));
+	const out = new Uint8Array(bin.length);
+	for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+	return out;
+}
+/** Validates the secret JSON (string or parsed object). Error messages never include key material. */
+function parseKeyringSecret(input) {
+	let raw = input;
+	if (typeof input === "string") try {
+		raw = JSON.parse(input);
+	} catch {
+		throw new KeyringError("keyring secret is not valid JSON");
+	}
+	if (typeof raw !== "object" || raw === null) throw new KeyringError("keyring secret must be an object");
+	const { active, keys } = raw;
+	if (typeof keys !== "object" || keys === null || Array.isArray(keys)) throw new KeyringError("keyring secret needs \"keys\": { kid: base64 }");
+	const map = /* @__PURE__ */ new Map();
+	for (const [kid, value] of Object.entries(keys)) {
+		if (!KID_RE.test(kid)) throw new KeyringError(`key id "${kid.slice(0, 32)}" must match [A-Za-z0-9_-]{1,32}`);
+		if (typeof value !== "string") throw new KeyringError(`key "${kid}" must be a base64 string`);
+		let bytes;
+		try {
+			bytes = base64ToBytes(value);
+		} catch {
+			throw new KeyringError(`key "${kid}" is not valid base64`);
+		}
+		if (bytes.length < MIN_KEY_BYTES) throw new KeyringError(`key "${kid}" must be at least ${MIN_KEY_BYTES} bytes`);
+		map.set(kid, bytes);
+	}
+	if (map.size === 0) throw new KeyringError("keyring secret has no keys");
+	if (typeof active !== "string" || !map.has(active)) throw new KeyringError("keyring secret \"active\" must name one of its keys");
+	return {
+		active,
+		keys: map
+	};
+}
+/** Key id of a `v1.<kid>.…` blob, or null when the shape is wrong. */
+function kidOfCiphertext(ciphertext) {
+	const parts = ciphertext.split(".");
+	if (parts.length !== 4 || parts[0] !== VERSION) return null;
+	const kid = parts[1] ?? "";
+	return KID_RE.test(kid) ? kid : null;
+}
+/**
+* The default keyring: HKDF-SHA-256 per key id → AES-256-GCM, format `v1.<kid>.<iv>.<ct>`. Throws `KeyringError`
+* on an invalid secret (bad JSON, short keys, `active` missing from `keys`).
+*/
+function webCryptoKeyring(secret) {
+	const { active, keys } = parseKeyringSecret(secret);
+	const derived = /* @__PURE__ */ new Map();
+	const enc = new TextEncoder();
+	function keyFor(kid) {
+		let key = derived.get(kid);
+		if (!key) {
+			const master = keys.get(kid);
+			if (!master) throw new KeyringError(`unknown key id "${kid}"`);
+			key = crypto.subtle.importKey("raw", master.slice(), "HKDF", false, ["deriveKey"]).then((ikm) => crypto.subtle.deriveKey({
+				name: "HKDF",
+				hash: "SHA-256",
+				salt: HKDF_SALT,
+				info: enc.encode(`aes-256-gcm:${kid}`)
+			}, ikm, {
+				name: "AES-GCM",
+				length: 256
+			}, false, ["encrypt", "decrypt"]));
+			derived.set(kid, key);
+		}
+		return key;
+	}
+	return {
+		kids: [...keys.keys()],
+		activeKid: () => active,
+		kidOf: kidOfCiphertext,
+		needsRekey: (ciphertext) => kidOfCiphertext(ciphertext) !== active,
+		async encrypt(plaintext, aad) {
+			const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+			const ct = await crypto.subtle.encrypt({
+				name: "AES-GCM",
+				iv,
+				additionalData: enc.encode(aad)
+			}, await keyFor(active), enc.encode(plaintext));
+			return `${VERSION}.${active}.${bytesToBase64Url(iv)}.${bytesToBase64Url(new Uint8Array(ct))}`;
+		},
+		async decrypt(ciphertext, aad) {
+			const kid = kidOfCiphertext(ciphertext);
+			if (!kid) throw new KeyringError("malformed ciphertext");
+			if (!keys.has(kid)) throw new KeyringError(`ciphertext uses key "${kid}", which is not in the keyring`);
+			const [, , ivText = "", ctText = ""] = ciphertext.split(".");
+			let iv;
+			let ct;
+			try {
+				iv = base64ToBytes(ivText);
+				ct = base64ToBytes(ctText);
+			} catch {
+				throw new KeyringError("malformed ciphertext");
+			}
+			if (iv.length !== IV_BYTES || ct.length < 16) throw new KeyringError("malformed ciphertext");
+			try {
+				const pt = await crypto.subtle.decrypt({
+					name: "AES-GCM",
+					iv: iv.slice(),
+					additionalData: enc.encode(aad)
+				}, await keyFor(kid), ct.slice());
+				return new TextDecoder().decode(pt);
+			} catch {
+				throw new KeyringError("decryption failed (wrong key, wrong AAD or tampered ciphertext)");
+			}
+		}
+	};
+}
+/** Random bytes as base64url (for webhook secrets and link codes). */
+function randomBase64Url(bytes = 32) {
+	return bytesToBase64Url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+/**
+* A fresh keyring secret JSON. Pass the current secret to add a new active key and keep the old ones (rotation).
+*/
+function generateKeyringSecret(opts = {}) {
+	const keys = {};
+	if (opts.existing !== void 0) {
+		const parsed = parseKeyringSecret(opts.existing);
+		for (const [kid, bytes] of parsed.keys) keys[kid] = bytesToBase64Url(bytes);
+	}
+	let kid = opts.kid;
+	if (kid === void 0) {
+		let n = Object.keys(keys).length + 1;
+		while (`k${n}` in keys) n++;
+		kid = `k${n}`;
+	}
+	if (!KID_RE.test(kid)) throw new KeyringError("key id must match [A-Za-z0-9_-]{1,32}");
+	if (kid in keys) throw new KeyringError(`key id "${kid}" already exists`);
+	keys[kid] = randomBase64Url(32);
+	return JSON.stringify({
+		active: kid,
+		keys
+	});
+}
+/**
+* Constant-time string comparison (webhook secrets). Both sides are hashed first, so different lengths take the
+* same time and reveal nothing. Uses `crypto.subtle.timingSafeEqual` in workerd, a XOR loop elsewhere.
+*/
+async function timingSafeEqualStrings(a, b) {
+	const enc = new TextEncoder();
+	const [ha, hb] = await Promise.all([crypto.subtle.digest("SHA-256", enc.encode(a)), crypto.subtle.digest("SHA-256", enc.encode(b))]);
+	const subtle = crypto.subtle;
+	if (typeof subtle.timingSafeEqual === "function") return subtle.timingSafeEqual(ha, hb);
+	const x = new Uint8Array(ha);
+	const y = new Uint8Array(hb);
+	let diff = 0;
+	for (let i = 0; i < x.length; i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+	return diff === 0;
+}
+export { KeyringError, base64ToBytes, bytesToBase64Url, generateKeyringSecret, kidOfCiphertext, parseKeyringSecret, randomBase64Url, timingSafeEqualStrings, webCryptoKeyring };

package/dist/adapters/metrics.d.ts

@@ -0,0 +1,28 @@
+import { MetricsPort } from "../ports/ports.js";
+/** Discards everything (the default when `ports.metrics` is not set). */
+export declare const noopMetrics: MetricsPort;
+/** The part of an Analytics Engine dataset binding the adapter uses. */
+export interface AnalyticsEngineLike {
+  /** Writes one data point (fire-and-forget). */
+  writeDataPoint(point: {
+    indexes?: string[];
+    blobs?: string[];
+    doubles?: number[];
+  }): void;
+}
+/** Options of `analyticsEngineMetrics`. */
+export interface AnalyticsEngineMetricsOptions {
+  /** Added to every data point's tags (for example `{ app: "my-app" }`). */
+  tags?: Record<string, string>;
+}
+/**
+ * Writes one data point per call. Layout (query with SQL over the dataset):
+ * - `index1` = metric name (the sampling key)
+ * - `blob1` = name, `blob2` = `count` | `timing`, `blob3` = botId, `blob4` = outcome, `blob5` = code,
+ *   `blob6` = other tags as sorted `k=v;k=v`
+ * - `double1` = value (count n, or ms)
+ *
+ * Example: `SELECT blob4 AS outcome, SUM(_sample_interval * double1) AS n FROM tg_metrics
+ *           WHERE blob1 = 'tg.send' AND timestamp > NOW() - INTERVAL '1' DAY GROUP BY outcome`.
+ */
+export declare function analyticsEngineMetrics(dataset: AnalyticsEngineLike, opts?: AnalyticsEngineMetricsOptions): MetricsPort;