@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/contracts/send.d.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+/** Where a send goes. The AI may use only `ai_allowed` destinations. */
+export declare const SendTarget: z.ZodUnion<readonly [z.ZodObject<{
+  destination: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  user: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  me: z.ZodLiteral<true>;
+}, z.core.$strict>]>;
+export type SendTarget = z.infer<typeof SendTarget>;
+/** What is sent. */
+export declare const SendWhat: z.ZodUnion<readonly [z.ZodObject<{
+  record: z.ZodObject<{
+    type: z.ZodString;
+    key: z.ZodString;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+  template: z.ZodString;
+  params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+  report: z.ZodString;
+  params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  format: z.ZodEnum<{
+    pdf: "pdf";
+    csv: "csv";
+  }>;
+}, z.core.$strict>, z.ZodObject<{
+  file: z.ZodObject<{
+    source: z.ZodString;
+    ref: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strict>, z.ZodObject<{
+  text: z.ZodString;
+}, z.core.$strict>]>;
+export type SendWhat = z.infer<typeof SendWhat>;
+/** The one shape the AI layer, host code and the UI "Send to Telegram" button share. */
+export declare const SendIntent: z.ZodObject<{
+  to: z.ZodUnion<readonly [z.ZodObject<{
+    destination: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    user: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    me: z.ZodLiteral<true>;
+  }, z.core.$strict>]>;
+  what: z.ZodUnion<readonly [z.ZodObject<{
+    record: z.ZodObject<{
+      type: z.ZodString;
+      key: z.ZodString;
+      fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+  }, z.core.$strict>, z.ZodObject<{
+    template: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strict>, z.ZodObject<{
+    report: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    format: z.ZodEnum<{
+      pdf: "pdf";
+      csv: "csv";
+    }>;
+  }, z.core.$strict>, z.ZodObject<{
+    file: z.ZodObject<{
+      source: z.ZodString;
+      ref: z.ZodString;
+    }, z.core.$strip>;
+  }, z.core.$strict>, z.ZodObject<{
+    text: z.ZodString;
+  }, z.core.$strict>]>;
+  note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SendIntent = z.infer<typeof SendIntent>;
+/** `POST /admin/send/preview` (permission `telegram.send`): exactly what a send would deliver, nothing queued. */
+export declare const SendPreview: z.ZodObject<{
+  to: z.ZodObject<{
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+      private: "private";
+      group: "group";
+      supergroup: "supergroup";
+      channel: "channel";
+    }>;
+    botUsername: z.ZodString;
+    destination: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+  audience: z.ZodString;
+  parts: z.ZodArray<z.ZodString>;
+  buttons: z.ZodNullable<z.ZodArray<z.ZodArray<z.ZodObject<{
+    text: z.ZodString;
+    kind: z.ZodEnum<{
+      action: "action";
+      url: "url";
+    }>;
+    url: z.ZodNullable<z.ZodString>;
+    style: z.ZodNullable<z.ZodEnum<{
+      success: "success";
+      primary: "primary";
+      danger: "danger";
+    }>>;
+    disabled: z.ZodBoolean;
+  }, z.core.$strip>>>>;
+  file: z.ZodNullable<z.ZodObject<{
+    name: z.ZodString;
+    mime: z.ZodString;
+    size: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  attachments: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    mime: z.ZodString;
+    size: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  consequence: z.ZodString;
+  chats: z.ZodNumber;
+  source: z.ZodEnum<{
+    ai: "ai";
+    api: "api";
+  }>;
+  warnings: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type SendPreview = z.infer<typeof SendPreview>;
+/** `POST /admin/send`: rows queued (parts × chats; 0 when the same key was already sent). */
+export declare const SendResult: z.ZodObject<{
+  queued: z.ZodNumber;
+  dedupeKey: z.ZodString;
+}, z.core.$strip>;
+export type SendResult = z.infer<typeof SendResult>;

package/dist/contracts/send.js

@@ -0,0 +1,69 @@
+import { JsonObject, Key } from "./common.js";
+import { Slug } from "./destinations.js";
+import { PreviewButton, PreviewFile, ReportFormat } from "./templates.js";
+import { FileRef } from "./broadcasts.js";
+import { ChatKind } from "./chats.js";
+import { z } from "zod";
+// src/contracts/send.ts
+/** Where a send goes. The AI may use only `ai_allowed` destinations. */
+const SendTarget = z.union([
+	z.strictObject({ destination: Slug }),
+	z.strictObject({ user: z.string().min(1) }),
+	z.strictObject({ me: z.literal(true) })
+]);
+/** What is sent. */
+const SendWhat = z.union([
+	z.strictObject({ record: z.object({
+		type: Key,
+		key: z.string().min(1).max(128),
+		fields: z.array(z.string()).max(50).optional()
+	}) }),
+	z.strictObject({
+		template: Key,
+		params: JsonObject.optional()
+	}),
+	z.strictObject({
+		report: Key,
+		params: JsonObject.optional(),
+		format: ReportFormat
+	}),
+	z.strictObject({ file: FileRef }),
+	z.strictObject({ text: z.string().min(1).max(1e3) })
+]);
+/** The one shape the AI layer, host code and the UI "Send to Telegram" button share. */
+const SendIntent = z.object({
+	to: SendTarget,
+	what: SendWhat,
+	/** Optional short text sent with it (the caption of a file send); AI-written notes pass the content checks. */
+	note: z.string().max(500).optional()
+});
+/** `POST /admin/send/preview` (permission `telegram.send`): exactly what a send would deliver, nothing queued. */
+const SendPreview = z.object({
+	to: z.object({
+		name: z.string(),
+		kind: ChatKind,
+		botUsername: z.string(),
+		destination: Slug.nullable()
+	}),
+	/** Who will see it, in the caller's locale ("Only Asha will see it.", "Everyone in this group…"). */
+	audience: z.string(),
+	/** Telegram HTML, one entry per message part. */
+	parts: z.array(z.string()),
+	/** Inline keyboard rows, or null. */
+	buttons: z.array(z.array(PreviewButton)).nullable(),
+	file: PreviewFile.nullable(),
+	/** Every file the send carries (today at most one: `file`). */
+	attachments: z.array(PreviewFile),
+	/** One sentence for a confirm card, in the caller's locale: what goes where and who sees it. */
+	consequence: z.string(),
+	/** Number of chats the send reaches (`me` can mean one chat per bot). */
+	chats: z.number().int().positive(),
+	source: z.enum(["api", "ai"]),
+	warnings: z.array(z.string())
+});
+/** `POST /admin/send`: rows queued (parts × chats; 0 when the same key was already sent). */
+const SendResult = z.object({
+	queued: z.number().int().nonnegative(),
+	dedupeKey: z.string()
+});
+export { SendIntent, SendPreview, SendResult, SendTarget, SendWhat };

package/dist/contracts/subscriptions.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+/** Quiet hours window, local to `tz` (default: the chat's zone). `from` > `to` wraps past midnight. */
+export declare const QuietHours: z.ZodObject<{
+  from: z.ZodString;
+  to: z.ZodString;
+  tz: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type QuietHours = z.infer<typeof QuietHours>;
+/** `schedule:<id>`, `event:<key>`, `broadcast`, or `*` (all). */
+export declare const SubscriptionTopic: z.ZodString;
+export type SubscriptionTopic = z.infer<typeof SubscriptionTopic>;
+/** One chat's preference for one topic. */
+export declare const SubscriptionDto: z.ZodObject<{
+  chatRef: z.ZodString;
+  topic: z.ZodString;
+  muted: z.ZodBoolean;
+  quiet: z.ZodNullable<z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    tz: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type SubscriptionDto = z.infer<typeof SubscriptionDto>;
+/** `PUT /me/subscriptions` and `PUT /admin/chats/:id/subscriptions`: replaces the chat's list. */
+export declare const SubscriptionSave: z.ZodObject<{
+  chatRef: z.ZodString;
+  items: z.ZodArray<z.ZodObject<{
+    topic: z.ZodString;
+    muted: z.ZodBoolean;
+    quiet: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+      from: z.ZodString;
+      to: z.ZodString;
+      tz: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SubscriptionSave = z.infer<typeof SubscriptionSave>;

package/dist/contracts/subscriptions.js

@@ -0,0 +1,31 @@
+import { ClockTime, EpochMs, Id, TimeZone } from "./common.js";
+import { z } from "zod";
+// src/contracts/subscriptions.ts
+/** Quiet hours window, local to `tz` (default: the chat's zone). `from` > `to` wraps past midnight. */
+const QuietHours = z.object({
+	from: ClockTime,
+	to: ClockTime,
+	tz: TimeZone.optional()
+});
+/** `schedule:<id>`, `event:<key>`, `broadcast`, or `*` (all). */
+const SubscriptionTopic = z.string().regex(/^(\*|broadcast|schedule:[A-Za-z0-9_-]{1,64}|event:[a-z0-9._:-]{1,64})$/);
+/** One chat's preference for one topic. */
+const SubscriptionDto = z.object({
+	/** Plugin chat row id. */
+	chatRef: Id,
+	topic: SubscriptionTopic,
+	muted: z.boolean(),
+	/** Quiet hours (messages are held until they end), or null. */
+	quiet: QuietHours.nullable(),
+	updatedAt: EpochMs
+});
+/** `PUT /me/subscriptions` and `PUT /admin/chats/:id/subscriptions`: replaces the chat's list. */
+const SubscriptionSave = z.object({
+	chatRef: Id,
+	items: z.array(z.object({
+		topic: SubscriptionTopic,
+		muted: z.boolean(),
+		quiet: QuietHours.nullable().default(null)
+	})).max(200)
+});
+export { QuietHours, SubscriptionDto, SubscriptionSave, SubscriptionTopic };

package/dist/contracts/templates.d.ts

@@ -0,0 +1,358 @@
+import { z } from "zod";
+/** `message` renders chat text; `report` renders a file (PDF/CSV) with a caption. */
+export declare const TEMPLATE_KINDS: readonly ["message", "report"];
+/** Zod enum of {@link TEMPLATE_KINDS}. */
+export declare const TemplateKind: z.ZodEnum<{
+  message: "message";
+  report: "report";
+}>;
+export type TemplateKind = z.infer<typeof TemplateKind>;
+/** Body syntax: Telegram HTML subset, or plain text (escaped on send). */
+export declare const TEMPLATE_FORMATS: readonly ["html", "text"];
+/** Zod enum of {@link TEMPLATE_FORMATS}. */
+export declare const TemplateFormat: z.ZodEnum<{
+  text: "text";
+  html: "html";
+}>;
+export type TemplateFormat = z.infer<typeof TemplateFormat>;
+/** Report file formats with built-in renderers. */
+export declare const REPORT_FORMATS: readonly ["pdf", "csv"];
+/** Zod enum of {@link REPORT_FORMATS}. */
+export declare const ReportFormat: z.ZodEnum<{
+  pdf: "pdf";
+  csv: "csv";
+}>;
+export type ReportFormat = z.infer<typeof ReportFormat>;
+/** Optional inline button styles. */
+export declare const BUTTON_STYLES: readonly ["primary", "success", "danger"];
+/** Zod enum of {@link BUTTON_STYLES}. */
+export declare const ButtonStyle: z.ZodEnum<{
+  success: "success";
+  primary: "primary";
+  danger: "danger";
+}>;
+export type ButtonStyle = z.infer<typeof ButtonStyle>;
+/** One inline button in a template. Exactly one of `action` or `url`. Params may hold `{{variables}}`. */
+export declare const ButtonSpec: z.ZodObject<{
+  text: z.ZodRecord<z.ZodString, z.ZodString>;
+  action: z.ZodOptional<z.ZodString>;
+  params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  url: z.ZodOptional<z.ZodString>;
+  style: z.ZodOptional<z.ZodEnum<{
+    success: "success";
+    primary: "primary";
+    danger: "danger";
+  }>>;
+  disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ButtonSpec = z.infer<typeof ButtonSpec>;
+/** Rows of buttons (Telegram: ≤ 8 per row, ≤ 100 total). */
+export declare const ButtonRows: z.ZodArray<z.ZodArray<z.ZodObject<{
+  text: z.ZodRecord<z.ZodString, z.ZodString>;
+  action: z.ZodOptional<z.ZodString>;
+  params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  url: z.ZodOptional<z.ZodString>;
+  style: z.ZodOptional<z.ZodEnum<{
+    success: "success";
+    primary: "primary";
+    danger: "danger";
+  }>>;
+  disabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>>;
+export type ButtonRows = z.infer<typeof ButtonRows>;
+/** How a `report` template renders its file. */
+export declare const ReportSpec: z.ZodObject<{
+  renderer: z.ZodEnum<{
+    pdf: "pdf";
+    csv: "csv";
+  }>;
+  fileName: z.ZodString;
+  layout: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ReportSpec = z.infer<typeof ReportSpec>;
+/** Bot API send options: `silent` = `disable_notification`, `protectContent`, `linkPreview` (default off). */
+export declare const TemplateOptions: z.ZodObject<{
+  silent: z.ZodOptional<z.ZodBoolean>;
+  protectContent: z.ZodOptional<z.ZodBoolean>;
+  linkPreview: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type TemplateOptions = z.infer<typeof TemplateOptions>;
+/** A saved template (`/admin/templates`, permission `telegram.templates.manage`). */
+export declare const TemplateDto: z.ZodObject<{
+  id: z.ZodString;
+  key: z.ZodString;
+  name: z.ZodString;
+  kind: z.ZodEnum<{
+    message: "message";
+    report: "report";
+  }>;
+  provider: z.ZodNullable<z.ZodString>;
+  providerParams: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  body: z.ZodRecord<z.ZodString, z.ZodString>;
+  format: z.ZodEnum<{
+    text: "text";
+    html: "html";
+  }>;
+  report: z.ZodNullable<z.ZodObject<{
+    renderer: z.ZodEnum<{
+      pdf: "pdf";
+      csv: "csv";
+    }>;
+    fileName: z.ZodString;
+    layout: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>;
+  buttons: z.ZodNullable<z.ZodArray<z.ZodArray<z.ZodObject<{
+    text: z.ZodRecord<z.ZodString, z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    url: z.ZodOptional<z.ZodString>;
+    style: z.ZodOptional<z.ZodEnum<{
+      success: "success";
+      primary: "primary";
+      danger: "danger";
+    }>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>>>;
+  options: z.ZodObject<{
+    silent: z.ZodOptional<z.ZodBoolean>;
+    protectContent: z.ZodOptional<z.ZodBoolean>;
+    linkPreview: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>;
+  version: z.ZodNumber;
+  updatedBy: z.ZodNullable<z.ZodString>;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type TemplateDto = z.infer<typeof TemplateDto>;
+/** `POST`/`PUT /admin/templates` body (defaults: `message`, `html`, no provider, no buttons). Invalid source fails with `template_invalid`. */
+export declare const TemplateSave: z.ZodObject<{
+  key: z.ZodString;
+  name: z.ZodString;
+  kind: z.ZodDefault<z.ZodEnum<{
+    message: "message";
+    report: "report";
+  }>>;
+  provider: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+  providerParams: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  body: z.ZodRecord<z.ZodString, z.ZodString>;
+  format: z.ZodDefault<z.ZodEnum<{
+    text: "text";
+    html: "html";
+  }>>;
+  report: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+    renderer: z.ZodEnum<{
+      pdf: "pdf";
+      csv: "csv";
+    }>;
+    fileName: z.ZodString;
+    layout: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>>;
+  buttons: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodArray<z.ZodObject<{
+    text: z.ZodRecord<z.ZodString, z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    url: z.ZodOptional<z.ZodString>;
+    style: z.ZodOptional<z.ZodEnum<{
+      success: "success";
+      primary: "primary";
+      danger: "danger";
+    }>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>>>>;
+  options: z.ZodDefault<z.ZodObject<{
+    silent: z.ZodOptional<z.ZodBoolean>;
+    protectContent: z.ZodOptional<z.ZodBoolean>;
+    linkPreview: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TemplateSave = z.infer<typeof TemplateSave>;
+/** One saved version (`GET /admin/templates/:id/versions`; restore with `POST …/restore/:version`). */
+export declare const TemplateVersionDto: z.ZodObject<{
+  templateId: z.ZodString;
+  version: z.ZodNumber;
+  body: z.ZodRecord<z.ZodString, z.ZodString>;
+  report: z.ZodNullable<z.ZodObject<{
+    renderer: z.ZodEnum<{
+      pdf: "pdf";
+      csv: "csv";
+    }>;
+    fileName: z.ZodString;
+    layout: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>>;
+  buttons: z.ZodNullable<z.ZodArray<z.ZodArray<z.ZodObject<{
+    text: z.ZodRecord<z.ZodString, z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    url: z.ZodOptional<z.ZodString>;
+    style: z.ZodOptional<z.ZodEnum<{
+      success: "success";
+      primary: "primary";
+      danger: "danger";
+    }>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>>>;
+  savedBy: z.ZodNullable<z.ZodString>;
+  savedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type TemplateVersionDto = z.infer<typeof TemplateVersionDto>;
+/** Preview as a role or a user, so the admin sees exactly what that audience gets. */
+export declare const PreviewAs: z.ZodUnion<readonly [z.ZodObject<{
+  role: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  userId: z.ZodString;
+}, z.core.$strict>]>;
+export type PreviewAs = z.infer<typeof PreviewAs>;
+/** `POST /admin/templates/preview`: render a saved template (`templateId`) or unsaved `source`. */
+export declare const TemplatePreviewRequest: z.ZodObject<{
+  templateId: z.ZodOptional<z.ZodString>;
+  source: z.ZodOptional<z.ZodString>;
+  buttons: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodObject<{
+    text: z.ZodRecord<z.ZodString, z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    url: z.ZodOptional<z.ZodString>;
+    style: z.ZodOptional<z.ZodEnum<{
+      success: "success";
+      primary: "primary";
+      danger: "danger";
+    }>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>>>;
+  format: z.ZodOptional<z.ZodEnum<{
+    text: "text";
+    html: "html";
+  }>>;
+  provider: z.ZodOptional<z.ZodString>;
+  params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  as: z.ZodUnion<readonly [z.ZodObject<{
+    role: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    userId: z.ZodString;
+  }, z.core.$strict>]>;
+  locale: z.ZodString;
+  sample: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type TemplatePreviewRequest = z.infer<typeof TemplatePreviewRequest>;
+/** A rendered inline button (callback data is not exposed in previews). */
+export declare const PreviewButton: z.ZodObject<{
+  text: z.ZodString;
+  kind: z.ZodEnum<{
+    action: "action";
+    url: "url";
+  }>;
+  url: z.ZodNullable<z.ZodString>;
+  style: z.ZodNullable<z.ZodEnum<{
+    success: "success";
+    primary: "primary";
+    danger: "danger";
+  }>>;
+  disabled: z.ZodBoolean;
+}, z.core.$strip>;
+export type PreviewButton = z.infer<typeof PreviewButton>;
+/** A file a preview would attach (`size` in bytes, null if unknown). */
+export declare const PreviewFile: z.ZodObject<{
+  name: z.ZodString;
+  mime: z.ZodString;
+  size: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type PreviewFile = z.infer<typeof PreviewFile>;
+/** Rendered preview; `warnings` are non-fatal template issues. */
+export declare const TemplatePreviewResponse: z.ZodObject<{
+  parts: z.ZodArray<z.ZodString>;
+  buttons: z.ZodNullable<z.ZodArray<z.ZodArray<z.ZodObject<{
+    text: z.ZodString;
+    kind: z.ZodEnum<{
+      action: "action";
+      url: "url";
+    }>;
+    url: z.ZodNullable<z.ZodString>;
+    style: z.ZodNullable<z.ZodEnum<{
+      success: "success";
+      primary: "primary";
+      danger: "danger";
+    }>>;
+    disabled: z.ZodBoolean;
+  }, z.core.$strip>>>>;
+  file: z.ZodNullable<z.ZodObject<{
+    name: z.ZodString;
+    mime: z.ZodString;
+    size: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  warnings: z.ZodArray<z.ZodObject<{
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+    message: z.ZodString;
+    locale: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TemplatePreviewResponse = z.infer<typeof TemplatePreviewResponse>;
+/** Cell formats. `money` reads integer minor units; `date`/`datetime` read epoch ms (or ISO) in the report's zone. */
+export declare const REPORT_COLUMN_FORMATS: readonly ["text", "number", "money", "date", "datetime", "yesno"];
+/** Zod enum of {@link REPORT_COLUMN_FORMATS}. */
+export declare const ReportColumnFormat: z.ZodEnum<{
+  number: "number";
+  date: "date";
+  datetime: "datetime";
+  text: "text";
+  money: "money";
+  yesno: "yesno";
+}>;
+export type ReportColumnFormat = z.infer<typeof ReportColumnFormat>;
+/** One report column: a field of each row (dotted path), its header and how the value is written. */
+export declare const ReportColumn: z.ZodObject<{
+  key: z.ZodString;
+  label: z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodString>, z.ZodString]>;
+  format: z.ZodDefault<z.ZodEnum<{
+    number: "number";
+    date: "date";
+    datetime: "datetime";
+    text: "text";
+    money: "money";
+    yesno: "yesno";
+  }>>;
+}, z.core.$strip>;
+export type ReportColumn = z.infer<typeof ReportColumn>;
+/**
+ * `report_json.layout` for the built-in renderers: `rows` names the provider variable holding the row array
+ * (default: the first array variable); `columns` picks and labels fields (default: every field of the first row).
+ */
+export declare const ReportLayout: z.ZodObject<{
+  rows: z.ZodOptional<z.ZodString>;
+  columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodString>, z.ZodString]>;
+    format: z.ZodDefault<z.ZodEnum<{
+      number: "number";
+      date: "date";
+      datetime: "datetime";
+      text: "text";
+      money: "money";
+      yesno: "yesno";
+    }>>;
+  }, z.core.$strip>>>;
+  title: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type ReportLayout = z.infer<typeof ReportLayout>;
+/** Filters for `GET /admin/templates`. */
+export declare const TemplateQuery: z.ZodObject<{
+  kind: z.ZodOptional<z.ZodEnum<{
+    message: "message";
+    report: "report";
+  }>>;
+}, z.core.$strip>;
+export type TemplateQuery = z.infer<typeof TemplateQuery>;
+/** `POST /admin/reports/render`: the same file the bot would send, as a download. */
+export declare const ReportRenderRequest: z.ZodObject<{
+  template: z.ZodString;
+  params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  as: z.ZodUnion<readonly [z.ZodObject<{
+    role: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    userId: z.ZodString;
+  }, z.core.$strict>]>;
+  format: z.ZodOptional<z.ZodEnum<{
+    pdf: "pdf";
+    csv: "csv";
+  }>>;
+  locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReportRenderRequest = z.infer<typeof ReportRenderRequest>;