@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/ports/sql.d.ts

@@ -0,0 +1,39 @@
+/** One SQL statement with positional `?` params. Producers return these so a host can batch them with its writes. */
+export interface SqlFragment {
+  /** SQL text with `?` placeholders. */
+  readonly text: string;
+  /** Bound values, in placeholder order. */
+  readonly params: readonly SqlValue[];
+}
+/** Values D1 can bind. Booleans are bound as 0/1. */
+export type SqlValue = string | number | bigint | null | ArrayBuffer | Uint8Array;
+/** Anything that may appear inside `sql\`…\``. */
+export type SqlInput = SqlValue | boolean | SqlFragment;
+/** True for fragments made by `sql` (or its helpers); plain `{ text, params }` objects are not fragments. */
+export declare function isSqlFragment(value: unknown): value is SqlFragment;
+/**
+ * Tagged template that builds a parameterized statement. Every interpolated value becomes a `?` param;
+ * nested fragments (from `sql`, `sql.join`, `sql.ident`, `sql.raw`) are inlined with their params.
+ *
+ * ```ts
+ * sql`SELECT * FROM tg_chat WHERE bot_id = ${botId} AND status IN (${sql.join(statuses)})`
+ * ```
+ */
+declare function sqlTag(strings: TemplateStringsArray, ...values: (SqlInput | undefined)[]): SqlFragment;
+/** Join values or fragments with a separator (default `, `). Plain values become `?` params. */
+declare function join(items: readonly SqlInput[], separator?: SqlFragment | string): SqlFragment;
+/** A quoted identifier (table / column). Only `[A-Za-z_][A-Za-z0-9_]*` is accepted. */
+declare function ident(name: string): SqlFragment;
+/** Trusted SQL text with no params. Never pass user input. */
+declare function raw(text: string): SqlFragment;
+/**
+ * Tagged template that builds a parameterized `SqlFragment` (`undefined` and non-finite numbers throw, booleans
+ * bind as 0/1), plus `sql.join`, `sql.ident` (quoted identifier), `sql.raw` (trusted text) and `sql.empty`.
+ */
+export declare const sql: typeof sqlTag & {
+  join: typeof join;
+  ident: typeof ident;
+  raw: typeof raw;
+  empty: SqlFragment;
+};
+export {};

package/dist/ports/sql.js

@@ -0,0 +1,76 @@
+// src/ports/sql.ts
+const FRAGMENT = Symbol.for("cf-telegram-plugin.sql");
+function make(text, params) {
+	return Object.freeze({
+		text,
+		params,
+		[FRAGMENT]: true
+	});
+}
+/** True for fragments made by `sql` (or its helpers); plain `{ text, params }` objects are not fragments. */
+function isSqlFragment(value) {
+	return typeof value === "object" && value !== null && FRAGMENT in value;
+}
+function bindValue(value) {
+	if (value === void 0) throw new TypeError("sql: undefined cannot be bound (use null)");
+	if (typeof value === "boolean") return value ? 1 : 0;
+	if (typeof value === "number" && !Number.isFinite(value)) throw new TypeError("sql: non-finite number");
+	return value;
+}
+function append(texts, params, value) {
+	if (isSqlFragment(value)) {
+		texts.push(value.text);
+		params.push(...value.params);
+	} else {
+		texts.push("?");
+		params.push(bindValue(value));
+	}
+}
+/**
+* Tagged template that builds a parameterized statement. Every interpolated value becomes a `?` param;
+* nested fragments (from `sql`, `sql.join`, `sql.ident`, `sql.raw`) are inlined with their params.
+*
+* ```ts
+* sql`SELECT * FROM tg_chat WHERE bot_id = ${botId} AND status IN (${sql.join(statuses)})`
+* ```
+*/
+function sqlTag(strings, ...values) {
+	const texts = [];
+	const params = [];
+	strings.forEach((s, i) => {
+		texts.push(s);
+		if (i < values.length) append(texts, params, values[i]);
+	});
+	return make(texts.join(""), params);
+}
+/** Join values or fragments with a separator (default `, `). Plain values become `?` params. */
+function join(items, separator = ", ") {
+	const sep = typeof separator === "string" ? make(separator, []) : separator;
+	const texts = [];
+	const params = [];
+	items.forEach((item, i) => {
+		if (i > 0) append(texts, params, sep);
+		append(texts, params, item);
+	});
+	return make(texts.join(""), params);
+}
+/** A quoted identifier (table / column). Only `[A-Za-z_][A-Za-z0-9_]*` is accepted. */
+function ident(name) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new TypeError(`sql: invalid identifier ${name}`);
+	return make(`"${name}"`, []);
+}
+/** Trusted SQL text with no params. Never pass user input. */
+function raw(text) {
+	return make(text, []);
+}
+/**
+* Tagged template that builds a parameterized `SqlFragment` (`undefined` and non-finite numbers throw, booleans
+* bind as 0/1), plus `sql.join`, `sql.ident` (quoted identifier), `sql.raw` (trusted text) and `sql.empty`.
+*/
+const sql = Object.assign(sqlTag, {
+	join,
+	ident,
+	raw,
+	empty: make("", [])
+});
+export { isSqlFragment, sql };

package/dist/renderers/csv.d.ts

@@ -0,0 +1,14 @@
+import { RendererPort } from "../ports/ports.js";
+/** Quotes a field when needed (comma, quote, CR/LF, edge spaces); defuses spreadsheet formulas in text. */
+export declare function csvField(value: string, opts?: {
+  formulaGuard?: boolean;
+}): string;
+/** CSV text (CRLF line ends, trailing CRLF) from a header and string rows; every field goes through {@link csvField}. */
+export declare function toCsv(header: readonly string[], rows: readonly (readonly string[])[]): string;
+/** Options for {@link csvRenderer}. */
+export interface CsvRendererOptions {
+  /** Write the UTF-8 BOM (default true). */
+  bom?: boolean;
+}
+/** Built-in `csv` renderer for `ports.renderers`: money in major units, local dates, `.csv` appended to the file name. */
+export declare function csvRenderer(opts?: CsvRendererOptions): RendererPort;

package/dist/renderers/csv.js

@@ -0,0 +1,51 @@
+import { rawCell, reportTable } from "./table.js";
+// src/renderers/csv.ts
+const BOM = new Uint8Array([
+	239,
+	187,
+	191
+]);
+/** Quotes a field when needed (comma, quote, CR/LF, edge spaces); defuses spreadsheet formulas in text. */
+function csvField(value, opts = {}) {
+	let v = value;
+	if (opts.formulaGuard !== false && /^[=+\-@\t\r]/.test(v) && !/^[+-]?\d+(\.\d+)?$/.test(v)) v = `'${v}`;
+	return /[",\r\n]|^\s|\s$/.test(v) ? `"${v.replaceAll("\"", "\"\"")}"` : v;
+}
+/** CSV text (CRLF line ends, trailing CRLF) from a header and string rows; every field goes through {@link csvField}. */
+function toCsv(header, rows) {
+	return `${[header, ...rows].map((r) => r.map((c) => csvField(c)).join(",")).join("\r\n")}\r\n`;
+}
+function withExt(name, ext) {
+	return name.toLowerCase().endsWith(`.${ext}`) ? name : `${name}.${ext}`;
+}
+/** Built-in `csv` renderer for `ports.renderers`: money in major units, local dates, `.csv` appended to the file name. */
+function csvRenderer(opts = {}) {
+	return {
+		format: "csv",
+		mime: "text/csv",
+		async render(input) {
+			const table = reportTable(input.data, input.layout ?? null, input.locale);
+			const ctx = {
+				locale: input.locale,
+				tz: input.timezone,
+				currency: input.currency,
+				minorDigits: input.minorDigits,
+				labels: input.labels
+			};
+			const text = toCsv(table.columns.map((c) => c.label), table.rows.map((r) => r.map((v, i) => rawCell(v, table.columns[i]?.format ?? "text", ctx))));
+			const body = new TextEncoder().encode(text);
+			const bytes = opts.bom === false ? body : new Uint8Array(BOM.length + body.length);
+			if (opts.bom !== false) {
+				bytes.set(BOM, 0);
+				bytes.set(body, BOM.length);
+			}
+			return {
+				name: withExt(input.fileName, "csv"),
+				mime: "text/csv",
+				body: bytes,
+				size: bytes.byteLength
+			};
+		}
+	};
+}
+export { csvField, csvRenderer, toCsv };

package/dist/renderers/html.d.ts

@@ -0,0 +1,44 @@
+import { RenderInput, RendererPort } from "../ports/ports.js";
+import { CellContext, ReportTable } from "./table.js";
+/** Input for {@link htmlReport}. */
+export interface HtmlReportInput {
+  title: string;
+  /** Telegram HTML from the template (a safe subset of HTML). */
+  intro?: string | undefined;
+  /** Data table; omitted or column-less = no table. */
+  table?: ReportTable | undefined;
+  /** `lang` attribute (`en`, `mr`). */
+  lang: string;
+  /** Cell formatting context. */
+  cell: CellContext;
+  /** Extra CSS, for example `@font-face` with an embedded Noto Sans Devanagari. */
+  css?: string | undefined;
+}
+/** A self-contained HTML report (title, intro, table). Title and cells are escaped; `intro` and `css` are inserted as-is. */
+export declare function htmlReport(input: HtmlReportInput): string;
+/** The report document for a render input (title + template HTML + table from the layout). */
+export declare function reportDocument(input: RenderInput, css?: string): string;
+/** What an HTML → PDF function may return. A non-OK `Response` throws. */
+export type PdfBytes = Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | Response;
+/** Options for {@link htmlTemplatePdf}. */
+export interface HtmlPdfOptions {
+  /** Extra CSS for the default document (fonts). */
+  css?: string;
+  /** Build the HTML yourself instead of `reportDocument`. */
+  document?: (input: RenderInput) => string;
+}
+/** A pdf renderer from any HTML → PDF function (Browser Rendering, an external service, a WASM engine). */
+export declare function htmlTemplatePdf(render: (html: string) => Promise<PdfBytes>, opts?: HtmlPdfOptions): RendererPort;
+/** The Browser Rendering binding surface used here (`env.BROWSER`). */
+export interface BrowserRunBinding {
+  quickAction(action: "pdf", options: Record<string, unknown>): Promise<unknown>;
+}
+/** Type guard: does `v` look like a Browser Rendering binding (has `quickAction`)? */
+export declare function isBrowserRunBinding(v: unknown): v is BrowserRunBinding;
+/** Options for {@link browserRunPdf}. */
+export interface BrowserRunPdfOptions extends HtmlPdfOptions {
+  /** Passed as `pdfOptions` (format, margins…). Default A4 with background graphics. */
+  pdfOptions?: Record<string, unknown>;
+}
+/** PDF through Browser Rendering (`env.BROWSER.quickAction("pdf", { html })`): Chromium shapes Devanagari. */
+export declare function browserRunPdf(binding: BrowserRunBinding, opts?: BrowserRunPdfOptions): RendererPort;

package/dist/renderers/html.js

@@ -0,0 +1,81 @@
+import { escapeHtml } from "../core/html/escape.js";
+import { displayCell, reportTable } from "./table.js";
+// src/renderers/html.ts
+const BASE_CSS = `
+body { font-family: "Noto Sans", "Noto Sans Devanagari", system-ui, sans-serif; font-size: 11pt; color: #111; margin: 24px; }
+h1 { font-size: 16pt; margin: 0 0 12px; }
+.intro { margin: 0 0 16px; white-space: pre-wrap; }
+table { border-collapse: collapse; width: 100%; }
+th, td { border: 1px solid #bbb; padding: 4px 6px; text-align: left; vertical-align: top; }
+th { background: #f1f1f1; }
+td.num { text-align: right; white-space: nowrap; }
+`;
+/** A self-contained HTML report (title, intro, table). Title and cells are escaped; `intro` and `css` are inserted as-is. */
+function htmlReport(input) {
+	const t = input.table;
+	const table = t && t.columns.length > 0 ? `<table><thead><tr>${t.columns.map((c) => `<th>${escapeHtml(c.label)}</th>`).join("")}</tr></thead><tbody>${t.rows.map((r) => `<tr>${r.map((v, i) => {
+		const fmt = t.columns[i]?.format ?? "text";
+		return `<td${fmt === "money" || fmt === "number" ? " class=\"num\"" : ""}>${escapeHtml(displayCell(v, fmt, input.cell))}</td>`;
+	}).join("")}</tr>`).join("")}</tbody></table>` : "";
+	const intro = input.intro ? `<div class="intro">${input.intro}</div>` : "";
+	return `<!doctype html><html lang="${escapeHtml(input.lang)}"><head><meta charset="utf-8"><title>${escapeHtml(input.title)}</title><style>${BASE_CSS}${input.css ?? ""}</style></head><body><h1>${escapeHtml(input.title)}</h1>${intro}${table}</body></html>`;
+}
+/** The report document for a render input (title + template HTML + table from the layout). */
+function reportDocument(input, css) {
+	return htmlReport({
+		title: input.title ?? input.fileName.replace(/\.[a-z0-9]+$/i, ""),
+		intro: input.html,
+		table: reportTable(input.data, input.layout ?? null, input.locale),
+		lang: input.locale,
+		cell: {
+			locale: input.locale,
+			tz: input.timezone,
+			currency: input.currency,
+			minorDigits: input.minorDigits,
+			labels: input.labels
+		},
+		css
+	});
+}
+async function toBytes(out) {
+	if (out instanceof Uint8Array) return out;
+	if (out instanceof ArrayBuffer) return new Uint8Array(out);
+	if (out instanceof Response) {
+		if (!out.ok) throw new Error(`pdf renderer answered ${out.status}`);
+		return new Uint8Array(await out.arrayBuffer());
+	}
+	return new Uint8Array(await new Response(out).arrayBuffer());
+}
+/** A pdf renderer from any HTML → PDF function (Browser Rendering, an external service, a WASM engine). */
+function htmlTemplatePdf(render, opts = {}) {
+	return {
+		format: "pdf",
+		mime: "application/pdf",
+		async render(input) {
+			const body = await toBytes(await render(opts.document ? opts.document(input) : reportDocument(input, opts.css)));
+			return {
+				name: input.fileName.toLowerCase().endsWith(".pdf") ? input.fileName : `${input.fileName}.pdf`,
+				mime: "application/pdf",
+				body,
+				size: body.byteLength
+			};
+		}
+	};
+}
+/** Type guard: does `v` look like a Browser Rendering binding (has `quickAction`)? */
+function isBrowserRunBinding(v) {
+	return typeof v === "object" && v !== null && typeof v.quickAction === "function";
+}
+/** PDF through Browser Rendering (`env.BROWSER.quickAction("pdf", { html })`): Chromium shapes Devanagari. */
+function browserRunPdf(binding, opts = {}) {
+	return htmlTemplatePdf(async (html) => {
+		return await binding.quickAction("pdf", {
+			html,
+			pdfOptions: opts.pdfOptions ?? {
+				format: "a4",
+				printBackground: true
+			}
+		});
+	}, opts);
+}
+export { browserRunPdf, htmlReport, htmlTemplatePdf, isBrowserRunBinding, reportDocument };

package/dist/renderers/index.d.ts

@@ -0,0 +1,5 @@
+import { RenderInput, RenderedFile, RendererPort } from "../ports/ports.js";
+import { CsvRendererOptions, csvField, csvRenderer, toCsv } from "./csv.js";
+import { CellContext, ReportTable, TableColumn, displayCell, rawCell, reportTable } from "./table.js";
+import { BrowserRunBinding, BrowserRunPdfOptions, HtmlPdfOptions, HtmlReportInput, PdfBytes, browserRunPdf, htmlReport, htmlTemplatePdf, isBrowserRunBinding, reportDocument } from "./html.js";
+export { type BrowserRunBinding, type BrowserRunPdfOptions, type CellContext, type CsvRendererOptions, type HtmlPdfOptions, type HtmlReportInput, type PdfBytes, type RenderInput, type RenderedFile, type RendererPort, type ReportTable, type TableColumn, browserRunPdf, csvField, csvRenderer, displayCell, htmlReport, htmlTemplatePdf, isBrowserRunBinding, rawCell, reportDocument, reportTable, toCsv };

package/dist/renderers/index.js

@@ -0,0 +1,4 @@
+import { displayCell, rawCell, reportTable } from "./table.js";
+import { csvField, csvRenderer, toCsv } from "./csv.js";
+import { browserRunPdf, htmlReport, htmlTemplatePdf, isBrowserRunBinding, reportDocument } from "./html.js";
+export { browserRunPdf, csvField, csvRenderer, displayCell, htmlReport, htmlTemplatePdf, isBrowserRunBinding, rawCell, reportDocument, reportTable, toCsv };

package/dist/renderers/table.d.ts

@@ -0,0 +1,30 @@
+import { ReportColumnFormat } from "../contracts/templates.js";
+/** One resolved report column: dotted field path, localized header, cell format. */
+export interface TableColumn {
+  key: string;
+  label: string;
+  format: ReportColumnFormat;
+}
+/** A report as columns plus raw row values (from {@link reportTable}). */
+export interface ReportTable {
+  columns: TableColumn[];
+  /** Raw values per row, in column order. */
+  rows: unknown[][];
+}
+/** Formatting context for cells: locale, IANA zone, ISO 4217 currency, minor-unit digits (default 2), yes/no labels. */
+export interface CellContext {
+  locale: string;
+  tz: string;
+  currency?: string | undefined;
+  minorDigits?: number | undefined;
+  labels?: {
+    yes: string;
+    no: string;
+  } | undefined;
+}
+/** `layout` is `report_json.layout` (validated here; an invalid layout falls back to the defaults). */
+export declare function reportTable(data: unknown, layoutInput: unknown, locale: string): ReportTable;
+/** Machine-friendly cell text (CSV): plain numbers, money in major units, ISO-like local dates. */
+export declare function rawCell(value: unknown, format: ReportColumnFormat, ctx: CellContext): string;
+/** Human cell text (HTML / PDF): locale formatting through Intl. */
+export declare function displayCell(value: unknown, format: ReportColumnFormat, ctx: CellContext): string;

package/dist/renderers/table.js

@@ -0,0 +1,114 @@
+import { ReportLayout } from "../contracts/templates.js";
+import { localParts } from "../core/schedule/tz.js";
+import { formatDateTime, formatMoney, formatNumber, toEpoch, toNumber } from "../core/template/format.js";
+// src/renderers/table.ts
+function at(value, path) {
+	let v = value;
+	for (const k of path.split(".")) {
+		if (v === null || typeof v !== "object" || !Object.hasOwn(v, k)) return void 0;
+		v = v[k];
+	}
+	return v;
+}
+function labelOf(label, locale) {
+	if (typeof label === "string") return label;
+	return label[locale] ?? label[locale.split("-")[0] ?? ""] ?? Object.values(label)[0] ?? "";
+}
+function rowsOf(data, path) {
+	if (Array.isArray(data)) return data;
+	if (path) {
+		const v = at(data, path);
+		return Array.isArray(v) ? v : [];
+	}
+	if (data !== null && typeof data === "object") {
+		for (const v of Object.values(data)) if (Array.isArray(v)) return v;
+	}
+	return [];
+}
+/** `layout` is `report_json.layout` (validated here; an invalid layout falls back to the defaults). */
+function reportTable(data, layoutInput, locale) {
+	const layout = layoutInput ? ReportLayout.safeParse(layoutInput).data ?? null : null;
+	const rows = rowsOf(data, layout?.rows);
+	let columns;
+	if (layout?.columns) columns = layout.columns.map((c) => ({
+		key: c.key,
+		label: labelOf(c.label, locale),
+		format: c.format
+	}));
+	else {
+		const first = rows.find((r) => r !== null && typeof r === "object" && !Array.isArray(r));
+		columns = first ? Object.entries(first).filter(([, v]) => v === null || typeof v !== "object").map(([key, v]) => ({
+			key,
+			label: key,
+			format: typeof v === "number" ? "number" : "text"
+		})) : [];
+	}
+	return {
+		columns,
+		rows: rows.map((r) => columns.map((c) => at(r, c.key)))
+	};
+}
+const pad = (n) => String(n).padStart(2, "0");
+/** Machine-friendly cell text (CSV): plain numbers, money in major units, ISO-like local dates. */
+function rawCell(value, format, ctx) {
+	if (value === null || value === void 0) return "";
+	switch (format) {
+		case "money": {
+			const n = toNumber(value);
+			const digits = ctx.minorDigits ?? 2;
+			return n === null ? "" : (n / 10 ** digits).toFixed(digits);
+		}
+		case "number": {
+			const n = toNumber(value);
+			return n === null ? "" : String(n);
+		}
+		case "date":
+		case "datetime": {
+			const ms = toEpoch(value);
+			if (ms === null) return "";
+			const p = localParts(ms, ctx.tz);
+			const date = `${p.year}-${pad(p.month)}-${pad(p.day)}`;
+			return format === "date" ? date : `${date} ${pad(p.hour)}:${pad(p.minute)}`;
+		}
+		case "yesno": return value ? ctx.labels?.yes ?? "Yes" : ctx.labels?.no ?? "No";
+		default: return text(value);
+	}
+}
+/** Human cell text (HTML / PDF): locale formatting through Intl. */
+function displayCell(value, format, ctx) {
+	if (value === null || value === void 0) return "";
+	const fctx = {
+		locale: ctx.locale,
+		tz: ctx.tz,
+		currency: ctx.currency,
+		minorDigits: ctx.minorDigits
+	};
+	switch (format) {
+		case "money": {
+			const n = toNumber(value);
+			return n === null ? "" : formatMoney(n, fctx);
+		}
+		case "number": {
+			const n = toNumber(value);
+			return n === null ? "" : formatNumber(n, fctx);
+		}
+		case "date":
+		case "datetime": {
+			const ms = toEpoch(value);
+			if (ms === null) return "";
+			return formatDateTime(ms, fctx, format === "date" ? { dateStyle: "medium" } : {
+				dateStyle: "medium",
+				timeStyle: "short"
+			});
+		}
+		default: return rawCell(value, format, ctx);
+	}
+}
+function text(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : "";
+	if (typeof value === "boolean" || typeof value === "bigint") return String(value);
+	if (Array.isArray(value)) return value.map(text).filter(Boolean).join(", ");
+	return "";
+}
+export { displayCell, rawCell, reportTable };

package/dist/routes/admin.js

@@ -0,0 +1,146 @@
+import { PageQuery } from "../contracts/common.js";
+import { BotCreate, BotPatch, BotRotateToken } from "../contracts/bots.js";
+import { DestinationSave } from "../contracts/destinations.js";
+import { ChatPatch, ChatQuery } from "../contracts/chats.js";
+import { DeliveryQuery } from "../contracts/deliveries.js";
+import { StatsQuery } from "../contracts/health.js";
+import { LinkCreate } from "../contracts/links.js";
+import { PERMISSION_NAMES } from "../contracts/permissions.js";
+import { SubscriptionSave } from "../contracts/subscriptions.js";
+import { UserQuery } from "../contracts/users.js";
+import { TelegramPluginError, featureDisabled } from "../engine/errors.js";
+import { botDto, chatDto, deliveryDto, destinationDto } from "../engine/rows.js";
+import { connectBot, deleteBot, getBot, listBots, patchBot, resetWebhook, rotateToken, testBot } from "../services/bots.js";
+import { listChats, patchChat, requireChat, unlinkChat } from "../services/chats.js";
+import { createDestination, deleteDestination, listDestinations, requireDestination, updateDestination } from "../services/destinations.js";
+import { cancelDelivery, listDeliveries, requireDelivery, retryDelivery } from "../services/deliveries.js";
+import { createLink } from "../services/links.js";
+import { health, stats } from "../services/ops.js";
+import { listSubscriptions, replaceSubscriptions } from "../services/subscriptions.js";
+import { actorMiddleware, decodeCursor, errorHandler, featureGate, idParam, idempotencyMiddleware, pageOf, requirePermission, runtimeMiddleware, schemaGuard, skipIdempotencyStore, zJson, zQuery } from "./http.js";
+import { contentRoutes } from "./content.js";
+import { Hono } from "hono";
+// src/routes/admin.ts
+const BotListQuery = PageQuery;
+const ChatListQuery = ChatQuery.extend(PageQuery.shape);
+const DeliveryListQuery = DeliveryQuery.extend(PageQuery.shape);
+function adminRoutes(deps, meta) {
+	const f = deps.features;
+	const app = new Hono();
+	app.onError(errorHandler(deps.errors));
+	app.use("/admin/*", runtimeMiddleware(deps), schemaGuard(deps), actorMiddleware, idempotencyMiddleware);
+	app.use("/admin/chats/:id/subscriptions", featureGate(f, "subscriptions"));
+	app.use("/admin/deliveries/*", featureGate(f, "ops"));
+	app.use("/admin/deliveries", featureGate(f, "ops"));
+	app.use("/admin/health", featureGate(f, "ops"));
+	app.use("/admin/stats", featureGate(f, "ops"));
+	return app.get("/admin/meta", requirePermission("telegram.view"), async (c) => {
+		const rt = c.var.tg;
+		const held = [];
+		for (const p of PERMISSION_NAMES) if (await rt.can(c.var.tgActor, p)) held.push(rt.perm(p));
+		return c.json({
+			...meta(),
+			permissions: held
+		});
+	}).get("/admin/bots", requirePermission("telegram.bots.manage"), zQuery(BotListQuery), async (c) => {
+		const q = c.req.valid("query");
+		const rows = await listBots(c.var.tg, {
+			cursor: decodeCursor(q.cursor),
+			limit: q.limit
+		});
+		return c.json(pageOf(rows, q.limit, botDto));
+	}).post("/admin/bots", requirePermission("telegram.bots.manage"), zJson(BotCreate), async (c) => {
+		return c.json(await connectBot(c.var.tg, c.var.tgActor, c.req.valid("json")), 201);
+	}).get("/admin/bots/:id", requirePermission("telegram.bots.manage"), async (c) => {
+		return c.json(await getBot(c.var.tg, idParam(c)));
+	}).patch("/admin/bots/:id", requirePermission("telegram.bots.manage"), zJson(BotPatch), async (c) => {
+		return c.json(await patchBot(c.var.tg, c.var.tgActor, idParam(c), c.req.valid("json")));
+	}).delete("/admin/bots/:id", requirePermission("telegram.bots.manage"), async (c) => {
+		await deleteBot(c.var.tg, c.var.tgActor, idParam(c));
+		return c.json({ ok: true });
+	}).post("/admin/bots/:id/test", requirePermission("telegram.bots.manage"), async (c) => {
+		return c.json(await testBot(c.var.tg, idParam(c)));
+	}).post("/admin/bots/:id/rotate-token", requirePermission("telegram.bots.manage"), zJson(BotRotateToken), async (c) => {
+		return c.json(await rotateToken(c.var.tg, c.var.tgActor, idParam(c), c.req.valid("json").token));
+	}).post("/admin/bots/:id/webhook/reset", requirePermission("telegram.bots.manage"), async (c) => {
+		return c.json(await resetWebhook(c.var.tg, c.var.tgActor, idParam(c)));
+	}).get("/admin/chats", requirePermission("telegram.chats.manage"), zQuery(ChatListQuery), async (c) => {
+		const q = c.req.valid("query");
+		const rows = await listChats(c.var.tg, q, {
+			cursor: decodeCursor(q.cursor),
+			limit: q.limit
+		});
+		return c.json(pageOf(rows, q.limit, chatDto));
+	}).get("/admin/chats/:id", requirePermission("telegram.chats.manage"), async (c) => {
+		return c.json(chatDto(await requireChat(c.var.tg, idParam(c))));
+	}).patch("/admin/chats/:id", requirePermission("telegram.chats.manage"), zJson(ChatPatch), async (c) => {
+		return c.json(await patchChat(c.var.tg, c.var.tgActor, idParam(c), c.req.valid("json")));
+	}).delete("/admin/chats/:id", requirePermission("telegram.chats.manage"), async (c) => {
+		await unlinkChat(c.var.tg, c.var.tgActor, idParam(c));
+		return c.json({ ok: true });
+	}).get("/admin/chats/:id/subscriptions", requirePermission("telegram.chats.manage"), async (c) => {
+		const chat = await requireChat(c.var.tg, idParam(c));
+		return c.json({ items: await listSubscriptions(c.var.tg, [chat.id]) });
+	}).put("/admin/chats/:id/subscriptions", requirePermission("telegram.chats.manage"), zJson(SubscriptionSave), async (c) => {
+		const chat = await requireChat(c.var.tg, idParam(c));
+		const body = c.req.valid("json");
+		if (body.chatRef !== chat.id) throw new TelegramPluginError("validation_failed", "chatRef must match the path");
+		return c.json({ items: await replaceSubscriptions(c.var.tg, body) });
+	}).get("/admin/users", requirePermission("telegram.chats.manage"), zQuery(UserQuery), async (c) => {
+		const rt = c.var.tg;
+		const search = rt.users?.search;
+		if (!search) throw featureDisabled("users.search", "user search needs ports.users.search");
+		const q = c.req.valid("query");
+		const items = (await search.call(rt.users, q.q, { limit: q.limit })).slice(0, q.limit).map((u) => ({
+			id: u.id,
+			name: u.name,
+			role: u.role,
+			...u.locale ? { locale: u.locale } : {}
+		}));
+		return c.json({ items });
+	}).post("/admin/links", requirePermission("telegram.chats.manage"), zJson(LinkCreate), async (c) => {
+		return c.json(await createLink(c.var.tg, c.var.tgActor, c.req.valid("json")), 201);
+	}).get("/admin/destinations", requirePermission("telegram.destinations.manage"), zQuery(PageQuery), async (c) => {
+		const q = c.req.valid("query");
+		const rows = await listDestinations(c.var.tg, {
+			cursor: decodeCursor(q.cursor),
+			limit: q.limit
+		});
+		return c.json(pageOf(rows, q.limit, destinationDto));
+	}).post("/admin/destinations", requirePermission("telegram.destinations.manage"), zJson(DestinationSave), async (c) => {
+		return c.json(await createDestination(c.var.tg, c.var.tgActor, c.req.valid("json")), 201);
+	}).get("/admin/destinations/:id", requirePermission("telegram.destinations.manage"), async (c) => {
+		return c.json(destinationDto(await requireDestination(c.var.tg, idParam(c))));
+	}).put("/admin/destinations/:id", requirePermission("telegram.destinations.manage"), zJson(DestinationSave), async (c) => {
+		return c.json(await updateDestination(c.var.tg, c.var.tgActor, idParam(c), c.req.valid("json")));
+	}).delete("/admin/destinations/:id", requirePermission("telegram.destinations.manage"), async (c) => {
+		await deleteDestination(c.var.tg, c.var.tgActor, idParam(c));
+		return c.json({ ok: true });
+	}).get("/admin/deliveries", requirePermission("telegram.ops.view"), zQuery(DeliveryListQuery), async (c) => {
+		const q = c.req.valid("query");
+		const withBody = await c.var.tg.can(c.var.tgActor, "telegram.ops.content");
+		const rows = await listDeliveries(c.var.tg, q, {
+			cursor: decodeCursor(q.cursor),
+			limit: q.limit
+		});
+		return c.json(pageOf(rows, q.limit, (r) => deliveryDto(r, withBody)));
+	}).get("/admin/deliveries/:id", requirePermission("telegram.ops.view"), async (c) => {
+		const withBody = await c.var.tg.can(c.var.tgActor, "telegram.ops.content");
+		return c.json(deliveryDto(await requireDelivery(c.var.tg, idParam(c)), withBody));
+	}).post("/admin/deliveries/:id/retry", requirePermission("telegram.ops.manage"), async (c) => {
+		const withBody = await c.var.tg.can(c.var.tgActor, "telegram.ops.content");
+		if (withBody) skipIdempotencyStore(c);
+		return c.json(deliveryDto(await retryDelivery(c.var.tg, c.var.tgActor, idParam(c)), withBody));
+	}).post("/admin/deliveries/:id/cancel", requirePermission("telegram.ops.manage"), async (c) => {
+		const withBody = await c.var.tg.can(c.var.tgActor, "telegram.ops.content");
+		if (withBody) skipIdempotencyStore(c);
+		return c.json(deliveryDto(await cancelDelivery(c.var.tg, c.var.tgActor, idParam(c)), withBody));
+	}).get("/admin/health", requirePermission("telegram.ops.view"), async (c) => {
+		return c.json(await health(c.var.tg));
+	}).get("/admin/stats", requirePermission("telegram.ops.view"), zQuery(StatsQuery), async (c) => {
+		const q = c.req.valid("query");
+		if (q.to <= q.from) throw new TelegramPluginError("validation_failed", "`to` must be after `from`");
+		return c.json(await stats(c.var.tg, q.from, q.to));
+	}).route("/", contentRoutes(deps));
+}
+export { adminRoutes };