@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/adapters/metrics.js

@@ -0,0 +1,48 @@
+// src/adapters/metrics.ts
+/** Discards everything (the default when `ports.metrics` is not set). */
+const noopMetrics = {
+	count() {},
+	timing() {}
+};
+/** Tag keys that would raise cardinality or leak personal data; they are dropped. */
+const BLOCKED_TAG = /chat|user|text|token|phone|email/i;
+const MAX_BLOB = 96;
+const clean = (v) => (v ?? "").slice(0, MAX_BLOB);
+/**
+* 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`.
+*/
+function analyticsEngineMetrics(dataset, opts = {}) {
+	const write = (type, name, value, tags = {}) => {
+		const { botId, outcome, code, ...rest } = {
+			...opts.tags,
+			...tags
+		};
+		const extra = Object.keys(rest).filter((k) => !BLOCKED_TAG.test(k)).sort().map((k) => `${k}=${rest[k]}`).join(";");
+		try {
+			dataset.writeDataPoint({
+				indexes: [clean(name)],
+				blobs: [
+					clean(name),
+					type,
+					clean(botId),
+					clean(outcome),
+					clean(code),
+					extra.slice(0, 256)
+				],
+				doubles: [Number.isFinite(value) ? value : 0]
+			});
+		} catch {}
+	};
+	return {
+		count: (name, value = 1, tags) => write("count", name, value, tags),
+		timing: (name, ms, tags) => write("timing", name, ms, tags)
+	};
+}
+export { analyticsEngineMetrics, noopMetrics };

package/dist/adapters/r2-files.d.ts

@@ -0,0 +1,20 @@
+import { FilesPort } from "../ports/ports.js";
+/** Options of `r2Files`. */
+export interface R2FilesOptions {
+  /** Key prefix. Default `telegram/`. */
+  prefix?: string;
+  /** Builds a link to a stored file (for files over Telegram's 50 MB limit). */
+  url?: (ref: string) => string | null;
+  /** Key ids (default `crypto.randomUUID()`). */
+  id?: () => string;
+  /**
+   * Read check for file sends by ref (`{ file: { source: "files", ref } }`). Default: deny every ref. The plugin's
+   * own re-opens (report files, queued documents) never call it.
+   */
+  canRead?: (actor: unknown, ref: string) => boolean | Promise<boolean>;
+}
+/**
+ * Minimal `FilesPort` over an R2 bucket: `put` buffers the body in memory and writes `<prefix><id>/<name>` with the
+ * tags as custom metadata; `open` only serves keys under `prefix`. File sends by ref need `opts.canRead` (default deny).
+ */
+export declare function r2Files(bucket: R2Bucket, opts?: R2FilesOptions): FilesPort<unknown>;

package/dist/adapters/r2-files.js

@@ -0,0 +1,53 @@
+// src/adapters/r2-files.ts
+function safeName(name) {
+	const n = [...name].map((ch) => ch === "/" || ch === "\\" || ch.charCodeAt(0) < 32 ? "_" : ch).join("").trim();
+	return n === "" ? "file" : n.slice(0, 128);
+}
+async function toBytes(body) {
+	if (body instanceof Uint8Array) return body;
+	if (body instanceof ArrayBuffer) return new Uint8Array(body);
+	return new Uint8Array(await new Response(body).arrayBuffer());
+}
+/**
+* Minimal `FilesPort` over an R2 bucket: `put` buffers the body in memory and writes `<prefix><id>/<name>` with the
+* tags as custom metadata; `open` only serves keys under `prefix`. File sends by ref need `opts.canRead` (default deny).
+*/
+function r2Files(bucket, opts = {}) {
+	const prefix = opts.prefix ?? "telegram/";
+	const id = opts.id ?? (() => crypto.randomUUID());
+	return {
+		async put(input) {
+			const name = safeName(input.name);
+			const key = `${prefix}${id()}/${name}`;
+			const bytes = await toBytes(input.body);
+			await bucket.put(key, bytes, {
+				httpMetadata: { contentType: input.mime },
+				customMetadata: {
+					...input.tags,
+					name
+				}
+			});
+			return {
+				ref: key,
+				name,
+				mime: input.mime,
+				size: bytes.byteLength
+			};
+		},
+		async open(ref) {
+			if (!ref.startsWith(prefix)) return null;
+			const obj = await bucket.get(ref);
+			if (!obj) return null;
+			return {
+				ref,
+				name: obj.customMetadata?.name ?? ref.slice(ref.lastIndexOf("/") + 1),
+				mime: obj.httpMetadata?.contentType ?? "application/octet-stream",
+				size: obj.size,
+				body: obj.body
+			};
+		},
+		canRead: async (actor, ref) => ref.startsWith(prefix) && (opts.canRead ? await opts.canRead(actor, ref) === true : false),
+		...opts.url ? { url: opts.url } : {}
+	};
+}
+export { r2Files };

package/dist/bin/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/bin/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { KeyringError, generateKeyringSecret } from "../adapters/keyring.js";
+// src/bin/cli.ts
+const proc = globalThis.process;
+const USAGE = [
+	"Usage:",
+	"  telegram-plugin keyring new [--kid <id>]",
+	"  telegram-plugin keyring rotate [--kid <id>] < current-keyring.json",
+	"",
+	"Store the output with: wrangler secret put TELEGRAM_KEYRING --env <env>"
+].join("\n");
+async function readStdin() {
+	const dec = new TextDecoder();
+	let text = "";
+	for await (const chunk of proc.stdin) text += typeof chunk === "string" ? chunk : dec.decode(chunk, { stream: true });
+	return text + dec.decode();
+}
+async function main(args) {
+	const [group, cmd, ...rest] = args;
+	let kid;
+	for (let i = 0; i < rest.length; i++) if (rest[i] === "--kid") kid = rest[++i];
+	if (group !== "keyring" || cmd !== "new" && cmd !== "rotate") {
+		console.error(USAGE);
+		return group === void 0 || group === "--help" || group === "-h" ? 0 : 1;
+	}
+	try {
+		if (cmd === "new") console.log(generateKeyringSecret(kid === void 0 ? {} : { kid }));
+		else {
+			const existing = (await readStdin()).trim();
+			if (existing === "") {
+				console.error(USAGE);
+				return 1;
+			}
+			console.log(generateKeyringSecret(kid === void 0 ? { existing } : {
+				kid,
+				existing
+			}));
+		}
+		return 0;
+	} catch (e) {
+		console.error(e instanceof KeyringError ? e.message : "failed to generate keyring");
+		return 1;
+	}
+}
+proc.exitCode = await main(proc.argv.slice(2));

package/dist/client/broadcasts.d.ts

@@ -0,0 +1,35 @@
+import { BroadcastDto, BroadcastPreviewRequest, BroadcastSave, BroadcastStats, BroadcastStatus } from "../contracts/broadcasts.js";
+import { Page } from "../contracts/common.js";
+import { TemplatePreviewResponse } from "../contracts/templates.js";
+import { Endpoint, Id, Ok, PageIn } from "./endpoint.js";
+/** Hono schema of the `/admin/broadcasts` routes (permission `telegram.broadcasts.send`). */
+export type BroadcastsSchema = {
+  "/admin/broadcasts": {
+    $get: Endpoint<{
+      query: PageIn & {
+        status?: BroadcastStatus;
+      };
+    }, Page<BroadcastDto>>;
+    $post: Endpoint<{
+      json: BroadcastSave;
+    }, BroadcastDto, 201>;
+  };
+  "/admin/broadcasts/:id": {
+    $get: Endpoint<Id, BroadcastDto>;
+    $put: Endpoint<Id & {
+      json: BroadcastSave;
+    }, BroadcastDto>;
+    $delete: Endpoint<Id, Ok>;
+  };
+  "/admin/broadcasts/:id/preview": {
+    $post: Endpoint<Id & {
+      json: BroadcastPreviewRequest;
+    }, TemplatePreviewResponse>;
+  };
+  "/admin/broadcasts/:id/send": {
+    $post: Endpoint<Id, BroadcastDto>;
+  };
+  "/admin/broadcasts/:id/report": {
+    $get: Endpoint<Id, BroadcastStats>;
+  };
+};

package/dist/client/commands.d.ts

@@ -0,0 +1,23 @@
+import { CommandConfigDto, CommandConfigSave, CommandSyncResult } from "../contracts/commands.js";
+import { Endpoint, Id } from "./endpoint.js";
+/** Hono schema of the per-bot command routes (permission `telegram.commands.manage`). */
+export type CommandsSchema = {
+  "/admin/bots/:id/commands": {
+    $get: Endpoint<Id, {
+      items: CommandConfigDto[];
+    }>;
+  };
+  "/admin/bots/:id/commands/sync": {
+    $post: Endpoint<Id, CommandSyncResult>;
+  };
+  "/admin/bots/:id/commands/:command": {
+    $put: Endpoint<{
+      param: {
+        id: string;
+        command: string;
+      };
+    } & {
+      json: CommandConfigSave;
+    }, CommandConfigDto>;
+  };
+};

package/dist/client/endpoint.d.ts

@@ -0,0 +1,34 @@
+/** No input / empty Hono env. */
+export type Empty = Record<never, never>;
+/** One Hono schema endpoint: input `I`, JSON output `O`, HTTP status `S` (default 200). */
+export type Endpoint<I, O, S extends number = 200> = {
+  input: I;
+  output: O;
+  outputFormat: "json";
+  status: S;
+};
+/**
+ * An endpoint that answers with raw bytes (not JSON): read it with `res.blob()` / `res.arrayBuffer()`; the
+ * `content-type` / `content-disposition` headers carry the file's mime and name.
+ */
+export type BinaryEndpoint<I> = {
+  input: I;
+  output: Record<never, never>;
+  outputFormat: "binary";
+  status: 200;
+};
+/** `:id` path param input. */
+export type Id = {
+  param: {
+    id: string;
+  };
+};
+/** `?cursor=&limit=` query input (strings, as sent on the wire). */
+export type PageIn = {
+  cursor?: string;
+  limit?: string;
+};
+/** `{ ok: true }` result of deletes. */
+export type Ok = {
+  ok: true;
+};

package/dist/client/events.d.ts

@@ -0,0 +1,33 @@
+import { Page } from "../contracts/common.js";
+import { EventRuleDto, EventRuleSave, EventRuleTestRequest, EventRuleTestResult, RegisteredEventDto } from "../contracts/events.js";
+import { Empty, Endpoint, Id, Ok, PageIn } from "./endpoint.js";
+/** Hono schema of the event and event-rule routes (permission `telegram.events.manage`). */
+export type EventsSchema = {
+  "/admin/events": {
+    $get: Endpoint<Empty, {
+      items: RegisteredEventDto[];
+    }>;
+  };
+  "/admin/event-rules": {
+    $get: Endpoint<{
+      query: PageIn & {
+        event?: string;
+      };
+    }, Page<EventRuleDto>>;
+    $post: Endpoint<{
+      json: EventRuleSave;
+    }, EventRuleDto, 201>;
+  };
+  "/admin/event-rules/:id": {
+    $get: Endpoint<Id, EventRuleDto>;
+    $put: Endpoint<Id & {
+      json: EventRuleSave;
+    }, EventRuleDto>;
+    $delete: Endpoint<Id, Ok>;
+  };
+  "/admin/event-rules/:id/test": {
+    $post: Endpoint<Id & {
+      json: EventRuleTestRequest;
+    }, EventRuleTestResult>;
+  };
+};

package/dist/client/index.d.ts

@@ -0,0 +1,11 @@
+import { BotDto } from "../contracts/bots.js";
+import { ChatDto } from "../contracts/chats.js";
+import { DestinationDto } from "../contracts/destinations.js";
+import { labelKey } from "../contracts/labels.js";
+import { PluginMeta } from "../contracts/meta.js";
+import { PROBLEM_CONTENT_TYPE, TelegramProblem } from "../contracts/problems.js";
+import { ScheduleDto } from "../contracts/schedules.js";
+import { TemplateDto } from "../contracts/templates.js";
+import { UserDto } from "../contracts/users.js";
+import { TelegramAdminApp, TelegramAdminClient, TelegramAdminSchema } from "./schema.js";
+export { type BotDto, type ChatDto, type DestinationDto, PROBLEM_CONTENT_TYPE, type PluginMeta, type ScheduleDto, type TelegramAdminApp, type TelegramAdminClient, type TelegramAdminSchema, type TelegramProblem, type TemplateDto, type UserDto, labelKey };

package/dist/client/index.js

@@ -0,0 +1,3 @@
+import { PROBLEM_CONTENT_TYPE } from "../contracts/problems.js";
+import { labelKey } from "../contracts/labels.js";
+export { PROBLEM_CONTENT_TYPE, labelKey };

package/dist/client/schedules.d.ts

@@ -0,0 +1,42 @@
+import { Page } from "../contracts/common.js";
+import { NextRunsRequest, NextRunsResponse, ScheduleDto, SchedulePause, ScheduleRunDto, ScheduleSave } from "../contracts/schedules.js";
+import { Endpoint, Id, Ok, PageIn } from "./endpoint.js";
+/** Hono schema of the `/admin/schedules` routes (permission `telegram.schedules.manage`). */
+export type SchedulesSchema = {
+  "/admin/schedules": {
+    $get: Endpoint<{
+      query: PageIn;
+    }, Page<ScheduleDto>>;
+    $post: Endpoint<{
+      json: ScheduleSave;
+    }, ScheduleDto, 201>;
+  };
+  "/admin/schedules/next-runs": {
+    $post: Endpoint<{
+      json: NextRunsRequest;
+    }, NextRunsResponse>;
+  };
+  "/admin/schedules/:id": {
+    $get: Endpoint<Id, ScheduleDto>;
+    $put: Endpoint<Id & {
+      json: ScheduleSave;
+    }, ScheduleDto>;
+    $delete: Endpoint<Id, Ok>;
+  };
+  "/admin/schedules/:id/pause": {
+    $post: Endpoint<Id & {
+      json?: SchedulePause;
+    }, ScheduleDto>;
+  };
+  "/admin/schedules/:id/resume": {
+    $post: Endpoint<Id, ScheduleDto>;
+  };
+  "/admin/schedules/:id/run-now": {
+    $post: Endpoint<Id, ScheduleRunDto>;
+  };
+  "/admin/schedules/:id/runs": {
+    $get: Endpoint<Id & {
+      query: PageIn;
+    }, Page<ScheduleRunDto>>;
+  };
+};

package/dist/client/schema.d.ts

@@ -0,0 +1,181 @@
+import { BotCreate, BotDto, BotPatch, BotRotateToken, BotTestResult } from "../contracts/bots.js";
+import { ChatDto, ChatKind, ChatPatch, ChatStatus } from "../contracts/chats.js";
+import { Page } from "../contracts/common.js";
+import { DeliveryDto, DeliverySource, DeliveryStatus } from "../contracts/deliveries.js";
+import { DestinationDto, DestinationSave } from "../contracts/destinations.js";
+import { HealthDto, StatsDto } from "../contracts/health.js";
+import { LinkCreate, LinkResult, PendingLinkDto, SelfLinkCreate } from "../contracts/links.js";
+import { PluginMeta } from "../contracts/meta.js";
+import { SubscriptionDto, SubscriptionSave } from "../contracts/subscriptions.js";
+import { UserDto } from "../contracts/users.js";
+import { Empty, Endpoint, Id, Ok, PageIn } from "./endpoint.js";
+import { BroadcastsSchema } from "./broadcasts.js";
+import { CommandsSchema } from "./commands.js";
+import { EventsSchema } from "./events.js";
+import { SchedulesSchema } from "./schedules.js";
+import { SendSchema } from "./send.js";
+import { TemplatesSchema } from "./templates.js";
+import { Hono } from "hono";
+import { hc } from "hono/client";
+/** Phase 2 routes (bots, chats, links, destinations, deliveries, ops, self-service). */
+type CoreSchema = {
+  "/admin/meta": {
+    $get: Endpoint<Empty, PluginMeta>;
+  };
+  "/admin/bots": {
+    $get: Endpoint<{
+      query: PageIn;
+    }, Page<BotDto>>;
+    $post: Endpoint<{
+      json: BotCreate;
+    }, BotDto, 201>;
+  };
+  "/admin/bots/:id": {
+    $get: Endpoint<Id, BotDto>;
+    $patch: Endpoint<Id & {
+      json: BotPatch;
+    }, BotDto>;
+    $delete: Endpoint<Id, Ok>;
+  };
+  "/admin/bots/:id/test": {
+    $post: Endpoint<Id, BotTestResult>;
+  };
+  "/admin/bots/:id/rotate-token": {
+    $post: Endpoint<Id & {
+      json: BotRotateToken;
+    }, BotDto>;
+  };
+  "/admin/bots/:id/webhook/reset": {
+    $post: Endpoint<Id, BotDto>;
+  };
+  "/admin/chats": {
+    $get: Endpoint<{
+      query: PageIn & {
+        bot?: string;
+        kind?: ChatKind;
+        status?: ChatStatus;
+        user?: string;
+      };
+    }, Page<ChatDto>>;
+  };
+  "/admin/chats/:id": {
+    $get: Endpoint<Id, ChatDto>;
+    $patch: Endpoint<Id & {
+      json: ChatPatch;
+    }, ChatDto>;
+    $delete: Endpoint<Id, Ok>;
+  };
+  "/admin/chats/:id/subscriptions": {
+    $get: Endpoint<Id, {
+      items: SubscriptionDto[];
+    }>;
+    $put: Endpoint<Id & {
+      json: SubscriptionSave;
+    }, {
+      items: SubscriptionDto[];
+    }>;
+  };
+  "/admin/users": {
+    $get: Endpoint<{
+      query: {
+        q: string;
+        limit?: string;
+      };
+    }, {
+      items: UserDto[];
+    }>;
+  };
+  "/admin/links": {
+    $post: Endpoint<{
+      json: LinkCreate;
+    }, LinkResult, 201>;
+  };
+  "/admin/destinations": {
+    $get: Endpoint<{
+      query: PageIn;
+    }, Page<DestinationDto>>;
+    $post: Endpoint<{
+      json: DestinationSave;
+    }, DestinationDto, 201>;
+  };
+  "/admin/destinations/:id": {
+    $get: Endpoint<Id, DestinationDto>;
+    $put: Endpoint<Id & {
+      json: DestinationSave;
+    }, DestinationDto>;
+    $delete: Endpoint<Id, Ok>;
+  };
+  "/admin/deliveries": {
+    $get: Endpoint<{
+      query: PageIn & {
+        status?: DeliveryStatus;
+        source?: DeliverySource;
+        bot?: string;
+      };
+    }, Page<DeliveryDto>>;
+  };
+  "/admin/deliveries/:id": {
+    $get: Endpoint<Id, DeliveryDto>;
+  };
+  "/admin/deliveries/:id/retry": {
+    $post: Endpoint<Id, DeliveryDto>;
+  };
+  "/admin/deliveries/:id/cancel": {
+    $post: Endpoint<Id, DeliveryDto>;
+  };
+  "/admin/health": {
+    $get: Endpoint<Empty, HealthDto>;
+  };
+  "/admin/stats": {
+    $get: Endpoint<{
+      query: {
+        from: string;
+        to: string;
+      };
+    }, StatsDto>;
+  };
+  "/me/link": {
+    $post: Endpoint<{
+      json: SelfLinkCreate;
+    }, LinkResult, 201>;
+  };
+  "/me/links/pending": {
+    $get: Endpoint<Empty, {
+      items: PendingLinkDto[];
+    }>;
+  };
+  "/me/links/pending/:id/confirm": {
+    $post: Endpoint<Id, {
+      chat: ChatDto;
+    }>;
+  };
+  "/me/links/pending/:id/decline": {
+    $post: Endpoint<Id, Ok>;
+  };
+  "/me/chats": {
+    $get: Endpoint<Empty, Page<ChatDto>>;
+  };
+  "/me/chats/:id": {
+    $delete: Endpoint<Id, Ok>;
+  };
+  "/me/subscriptions": {
+    $get: Endpoint<Empty, {
+      items: SubscriptionDto[];
+    }>;
+    $put: Endpoint<{
+      json: SubscriptionSave;
+    }, {
+      items: SubscriptionDto[];
+    }>;
+  };
+};
+/** Every admin and self-service route (`/admin/*`, `/me/*`) as one Hono schema type. */
+export type TelegramAdminSchema = CoreSchema & TemplatesSchema & CommandsSchema & SchedulesSchema & EventsSchema & BroadcastsSchema & SendSchema;
+/** The plugin routes as a Hono app type (type-only). */
+export type TelegramAdminApp = Hono<Empty, TelegramAdminSchema, "/">;
+/**
+ * Typed `hc` client for the admin API: `hc<TelegramAdminApp>("/api/telegram") as TelegramAdminClient`,
+ * then `client.admin.bots.$get({ query: {} })`.
+ */
+export type TelegramAdminClient = ReturnType<typeof hc<TelegramAdminApp>>;
+export {};

package/dist/client/send.d.ts

@@ -0,0 +1,15 @@
+import { SendIntent, SendPreview, SendResult } from "../contracts/send.js";
+import { Endpoint } from "./endpoint.js";
+/** Hono schema of the send routes (permission `telegram.send`). */
+export type SendSchema = {
+  "/admin/send/preview": {
+    $post: Endpoint<{
+      json: SendIntent;
+    }, SendPreview>;
+  };
+  "/admin/send": {
+    $post: Endpoint<{
+      json: SendIntent;
+    }, SendResult>;
+  };
+};

package/dist/client/templates.d.ts

@@ -0,0 +1,47 @@
+import { Page } from "../contracts/common.js";
+import { ReportRenderRequest, TemplateDto, TemplateKind, TemplatePreviewRequest, TemplatePreviewResponse, TemplateSave, TemplateVersionDto } from "../contracts/templates.js";
+import { BinaryEndpoint, Endpoint, Id, Ok, PageIn } from "./endpoint.js";
+/** Hono schema of the template routes (`telegram.templates.manage`) and report download (`telegram.reports.run`). */
+export type TemplatesSchema = {
+  "/admin/templates": {
+    $get: Endpoint<{
+      query: PageIn & {
+        kind?: TemplateKind;
+      };
+    }, Page<TemplateDto>>;
+    $post: Endpoint<{
+      json: TemplateSave;
+    }, TemplateDto, 201>;
+  };
+  "/admin/templates/preview": {
+    $post: Endpoint<{
+      json: TemplatePreviewRequest;
+    }, TemplatePreviewResponse>;
+  };
+  "/admin/templates/:id": {
+    $get: Endpoint<Id, TemplateDto>;
+    $put: Endpoint<Id & {
+      json: TemplateSave;
+    }, TemplateDto>;
+    $delete: Endpoint<Id, Ok>;
+  };
+  "/admin/templates/:id/versions": {
+    $get: Endpoint<Id, {
+      items: TemplateVersionDto[];
+    }>;
+  };
+  "/admin/templates/:id/restore/:version": {
+    $post: Endpoint<{
+      param: {
+        id: string;
+        version: string;
+      };
+    }, TemplateDto>;
+  };
+  /** Answers with the file bytes (`content-type` = the file's mime): use `res.blob()`, not `res.json()`. */
+  "/admin/reports/render": {
+    $post: BinaryEndpoint<{
+      json: ReportRenderRequest;
+    }>;
+  };
+};