@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.0

package/dist/contracts/bots.d.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+/** How a bot receives updates: Telegram webhook, or `getUpdates` polling. */
+export declare const BOT_MODES: readonly ["webhook", "polling"];
+/** Zod enum of {@link BOT_MODES}. */
+export declare const BotMode: z.ZodEnum<{
+  webhook: "webhook";
+  polling: "polling";
+}>;
+export type BotMode = z.infer<typeof BotMode>;
+/** Bot health: `invalid_token` after a 401 from Telegram, `webhook_error` when the webhook could not be set. */
+export declare const BOT_STATUSES: readonly ["active", "disabled", "invalid_token", "webhook_error"];
+/** Zod enum of {@link BOT_STATUSES}. */
+export declare const BotStatus: z.ZodEnum<{
+  active: "active";
+  disabled: "disabled";
+  invalid_token: "invalid_token";
+  webhook_error: "webhook_error";
+}>;
+export type BotStatus = z.infer<typeof BotStatus>;
+/** BotFather token shape. Never returned by the API. */
+export declare const BotToken: z.ZodString;
+/** Per-bot feature overrides (for example commands off on a broadcast-only bot). */
+export declare const BotFeatures: z.ZodRecord<z.ZodEnum<{
+  core: "core";
+  commands: "commands";
+  templates: "templates";
+  schedules: "schedules";
+  reports: "reports";
+  events: "events";
+  broadcasts: "broadcasts";
+  actions: "actions";
+  dialogs: "dialogs";
+  inbound: "inbound";
+  subscriptions: "subscriptions";
+  ai: "ai";
+  ops: "ops";
+}> & z.core.$partial, z.ZodBoolean>;
+export type BotFeatures = z.infer<typeof BotFeatures>;
+/** A bot as the admin UI sees it. No token, no webhook secret. */
+export declare const BotDto: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  username: z.ZodString;
+  tgBotId: z.ZodString;
+  mode: z.ZodEnum<{
+    webhook: "webhook";
+    polling: "polling";
+  }>;
+  status: z.ZodEnum<{
+    active: "active";
+    disabled: "disabled";
+    invalid_token: "invalid_token";
+    webhook_error: "webhook_error";
+  }>;
+  statusDetail: z.ZodNullable<z.ZodString>;
+  checkedAt: z.ZodNullable<z.ZodNumber>;
+  defaultLocale: z.ZodString;
+  features: z.ZodRecord<z.ZodEnum<{
+    core: "core";
+    commands: "commands";
+    templates: "templates";
+    schedules: "schedules";
+    reports: "reports";
+    events: "events";
+    broadcasts: "broadcasts";
+    actions: "actions";
+    dialogs: "dialogs";
+    inbound: "inbound";
+    subscriptions: "subscriptions";
+    ai: "ai";
+    ops: "ops";
+  }> & z.core.$partial, z.ZodBoolean>;
+  ratePerSec: z.ZodNumber;
+  pausedUntil: z.ZodNullable<z.ZodNumber>;
+  createdAt: z.ZodNumber;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type BotDto = z.infer<typeof BotDto>;
+/** `POST /admin/bots` body. The token is verified with `getMe` and stored encrypted. */
+export declare const BotCreate: z.ZodObject<{
+  name: z.ZodString;
+  token: z.ZodString;
+  defaultLocale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BotCreate = z.infer<typeof BotCreate>;
+/** `PATCH /admin/bots/:id` body; every field optional. `ratePerSec` is 1–30, `enabled: false` disables the bot. */
+export declare const BotPatch: z.ZodObject<{
+  name: z.ZodOptional<z.ZodString>;
+  defaultLocale: z.ZodOptional<z.ZodString>;
+  features: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+    core: "core";
+    commands: "commands";
+    templates: "templates";
+    schedules: "schedules";
+    reports: "reports";
+    events: "events";
+    broadcasts: "broadcasts";
+    actions: "actions";
+    dialogs: "dialogs";
+    inbound: "inbound";
+    subscriptions: "subscriptions";
+    ai: "ai";
+    ops: "ops";
+  }> & z.core.$partial, z.ZodBoolean>>;
+  ratePerSec: z.ZodOptional<z.ZodNumber>;
+  enabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type BotPatch = z.infer<typeof BotPatch>;
+/** `POST /admin/bots/:id/rotate-token` body. The new token must belong to the same Telegram bot (`bot_token_mismatch`). */
+export declare const BotRotateToken: z.ZodObject<{
+  token: z.ZodString;
+}, z.core.$strip>;
+export type BotRotateToken = z.infer<typeof BotRotateToken>;
+/** `POST /admin/bots/:id/test` result (`getMe` + `getWebhookInfo`, no secrets). */
+export declare const BotTestResult: z.ZodObject<{
+  ok: z.ZodBoolean;
+  status: z.ZodEnum<{
+    active: "active";
+    disabled: "disabled";
+    invalid_token: "invalid_token";
+    webhook_error: "webhook_error";
+  }>;
+  username: z.ZodNullable<z.ZodString>;
+  webhookUrlSet: z.ZodBoolean;
+  pendingUpdateCount: z.ZodNullable<z.ZodNumber>;
+  lastErrorAt: z.ZodNullable<z.ZodNumber>;
+  lastErrorMessage: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type BotTestResult = z.infer<typeof BotTestResult>;

package/dist/contracts/bots.js

@@ -0,0 +1,70 @@
+import { EpochMs, Id, Locale } from "./common.js";
+import { FeatureKey } from "./features.js";
+import { z } from "zod";
+// src/contracts/bots.ts
+/** How a bot receives updates: Telegram webhook, or `getUpdates` polling. */
+const BOT_MODES = ["webhook", "polling"];
+/** Zod enum of {@link BOT_MODES}. */
+const BotMode = z.enum(BOT_MODES);
+/** Bot health: `invalid_token` after a 401 from Telegram, `webhook_error` when the webhook could not be set. */
+const BOT_STATUSES = [
+	"active",
+	"disabled",
+	"invalid_token",
+	"webhook_error"
+];
+/** Zod enum of {@link BOT_STATUSES}. */
+const BotStatus = z.enum(BOT_STATUSES);
+/** BotFather token shape. Never returned by the API. */
+const BotToken = z.string().regex(/^\d{1,20}:[A-Za-z0-9_-]{30,}$/, "bot_token_invalid");
+/** Per-bot feature overrides (for example commands off on a broadcast-only bot). */
+const BotFeatures = z.partialRecord(FeatureKey, z.boolean());
+/** A bot as the admin UI sees it. No token, no webhook secret. */
+const BotDto = z.object({
+	id: Id,
+	name: z.string(),
+	username: z.string(),
+	/** Telegram's numeric bot id, as text. */
+	tgBotId: z.string(),
+	mode: BotMode,
+	status: BotStatus,
+	/** Human-readable reason for a non-`active` status, or null. */
+	statusDetail: z.string().nullable(),
+	/** Last `getMe` / webhook check (epoch ms UTC), or null if never checked. */
+	checkedAt: EpochMs.nullable(),
+	defaultLocale: Locale,
+	features: BotFeatures,
+	/** Per-bot send rate limit (messages per second). */
+	ratePerSec: z.number().int(),
+	/** Sending is paused until this time after a Telegram 429 (epoch ms UTC), or null. */
+	pausedUntil: EpochMs.nullable(),
+	createdAt: EpochMs,
+	updatedAt: EpochMs
+});
+/** `POST /admin/bots` body. The token is verified with `getMe` and stored encrypted. */
+const BotCreate = z.object({
+	name: z.string().trim().min(1).max(80),
+	token: BotToken,
+	defaultLocale: Locale.optional()
+});
+/** `PATCH /admin/bots/:id` body; every field optional. `ratePerSec` is 1–30, `enabled: false` disables the bot. */
+const BotPatch = z.object({
+	name: z.string().trim().min(1).max(80),
+	defaultLocale: Locale,
+	features: BotFeatures,
+	ratePerSec: z.number().int().min(1).max(30),
+	enabled: z.boolean()
+}).partial();
+/** `POST /admin/bots/:id/rotate-token` body. The new token must belong to the same Telegram bot (`bot_token_mismatch`). */
+const BotRotateToken = z.object({ token: BotToken });
+/** `POST /admin/bots/:id/test` result (`getMe` + `getWebhookInfo`, no secrets). */
+const BotTestResult = z.object({
+	ok: z.boolean(),
+	status: BotStatus,
+	username: z.string().nullable(),
+	webhookUrlSet: z.boolean(),
+	pendingUpdateCount: z.number().int().nonnegative().nullable(),
+	lastErrorAt: EpochMs.nullable(),
+	lastErrorMessage: z.string().nullable()
+});
+export { BOT_MODES, BOT_STATUSES, BotCreate, BotDto, BotFeatures, BotMode, BotPatch, BotRotateToken, BotStatus, BotTestResult, BotToken };

package/dist/contracts/broadcasts.d.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+/** Broadcast lifecycle: `draft` → `queued` (fan-out pending) → `sending` → `done`. */
+export declare const BROADCAST_STATUSES: readonly ["draft", "queued", "sending", "done"];
+/** Zod enum of {@link BROADCAST_STATUSES}. */
+export declare const BroadcastStatus: z.ZodEnum<{
+  draft: "draft";
+  queued: "queued";
+  sending: "sending";
+  done: "done";
+}>;
+export type BroadcastStatus = z.infer<typeof BroadcastStatus>;
+/** Delivery counters for one broadcast (null on the DTO until it is sent). */
+export declare const BroadcastStats: z.ZodObject<{
+  total: z.ZodNumber;
+  queued: z.ZodNumber;
+  sent: z.ZodNumber;
+  failed: z.ZodNumber;
+  dropped: z.ZodNumber;
+}, z.core.$strip>;
+export type BroadcastStats = z.infer<typeof BroadcastStats>;
+/** A file to attach: a host file-source reference. */
+export declare const FileRef: z.ZodObject<{
+  source: z.ZodString;
+  ref: z.ZodString;
+}, z.core.$strip>;
+export type FileRef = z.infer<typeof FileRef>;
+/** A broadcast as the admin UI sees it (`/admin/broadcasts`, permission `telegram.broadcasts.send`). */
+export declare const BroadcastDto: z.ZodObject<{
+  id: z.ZodString;
+  title: z.ZodString;
+  templateId: z.ZodNullable<z.ZodString>;
+  body: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>;
+  params: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  file: z.ZodNullable<z.ZodObject<{
+    source: z.ZodString;
+    ref: z.ZodString;
+  }, z.core.$strip>>;
+  recipients: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    destination: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    chat: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    user: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    role: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    allLinked: z.ZodLiteral<true>;
+  }, z.core.$strict>, z.ZodObject<{
+    audience: z.ZodString;
+    ref: z.ZodString;
+  }, z.core.$strict>]>>;
+  status: z.ZodEnum<{
+    draft: "draft";
+    queued: "queued";
+    sending: "sending";
+    done: "done";
+  }>;
+  stats: z.ZodNullable<z.ZodObject<{
+    total: z.ZodNumber;
+    queued: z.ZodNumber;
+    sent: z.ZodNumber;
+    failed: z.ZodNumber;
+    dropped: z.ZodNumber;
+  }, z.core.$strip>>;
+  createdBy: z.ZodNullable<z.ZodString>;
+  createdAt: z.ZodNumber;
+  sentAt: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type BroadcastDto = z.infer<typeof BroadcastDto>;
+/** Either a template or an inline body (or only a file). */
+export declare const BroadcastSave: z.ZodObject<{
+  title: z.ZodString;
+  templateId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+  body: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+  params: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  file: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+    source: z.ZodString;
+    ref: z.ZodString;
+  }, z.core.$strip>>>;
+  recipients: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    destination: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    chat: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    user: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    role: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    allLinked: z.ZodLiteral<true>;
+  }, z.core.$strict>, z.ZodObject<{
+    audience: z.ZodString;
+    ref: z.ZodString;
+  }, z.core.$strict>]>>;
+}, z.core.$strip>;
+export type BroadcastSave = z.infer<typeof BroadcastSave>;
+/** `GET /admin/broadcasts?status=`. */
+export declare const BroadcastQuery: z.ZodObject<{
+  status: z.ZodOptional<z.ZodEnum<{
+    draft: "draft";
+    queued: "queued";
+    sending: "sending";
+    done: "done";
+  }>>;
+}, z.core.$strip>;
+export type BroadcastQuery = z.infer<typeof BroadcastQuery>;
+/** `POST /admin/broadcasts/:id/preview`: render as a role or a user (like the template preview). */
+export declare const BroadcastPreviewRequest: z.ZodObject<{
+  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 BroadcastPreviewRequest = z.infer<typeof BroadcastPreviewRequest>;

package/dist/contracts/broadcasts.js

@@ -0,0 +1,63 @@
+import { EpochMs, Id, JsonObject, Locale, LocalizedText } from "./common.js";
+import { Recipients } from "./recipients.js";
+import { PreviewAs } from "./templates.js";
+import { z } from "zod";
+// src/contracts/broadcasts.ts
+/** Broadcast lifecycle: `draft` → `queued` (fan-out pending) → `sending` → `done`. */
+const BROADCAST_STATUSES = [
+	"draft",
+	"queued",
+	"sending",
+	"done"
+];
+/** Zod enum of {@link BROADCAST_STATUSES}. */
+const BroadcastStatus = z.enum(BROADCAST_STATUSES);
+/** Delivery counters for one broadcast (null on the DTO until it is sent). */
+const BroadcastStats = z.object({
+	total: z.number().int().nonnegative(),
+	queued: z.number().int().nonnegative(),
+	sent: z.number().int().nonnegative(),
+	failed: z.number().int().nonnegative(),
+	dropped: z.number().int().nonnegative()
+});
+/** A file to attach: a host file-source reference. */
+const FileRef = z.object({
+	source: z.string().min(1).max(64),
+	ref: z.string().min(1).max(512)
+});
+/** A broadcast as the admin UI sees it (`/admin/broadcasts`, permission `telegram.broadcasts.send`). */
+const BroadcastDto = z.object({
+	id: Id,
+	title: z.string(),
+	templateId: Id.nullable(),
+	body: LocalizedText.nullable(),
+	params: JsonObject.nullable(),
+	file: FileRef.nullable(),
+	recipients: Recipients,
+	status: BroadcastStatus,
+	stats: BroadcastStats.nullable(),
+	/** Host user id of the creator, or null. */
+	createdBy: z.string().nullable(),
+	createdAt: EpochMs,
+	/** When `send` was requested (epoch ms UTC), or null for drafts. */
+	sentAt: EpochMs.nullable()
+});
+/** Either a template or an inline body (or only a file). */
+const BroadcastSave = z.object({
+	title: z.string().trim().min(1).max(120),
+	templateId: Id.nullable().default(null),
+	body: LocalizedText.nullable().default(null),
+	params: JsonObject.nullable().default(null),
+	file: FileRef.nullable().default(null),
+	recipients: Recipients
+}).refine((b) => b.templateId !== null || b.body !== null || b.file !== null, "template, body or file required").refine((b) => b.templateId === null || b.body === null, "template or body, not both");
+/** `GET /admin/broadcasts?status=`. */
+const BroadcastQuery = z.object({ status: BroadcastStatus.optional() });
+/** `POST /admin/broadcasts/:id/preview`: render as a role or a user (like the template preview). */
+const BroadcastPreviewRequest = z.object({
+	as: PreviewAs,
+	locale: Locale,
+	/** Use the provider's `sample()` instead of live data (template broadcasts). */
+	sample: z.boolean().optional()
+});
+export { BROADCAST_STATUSES, BroadcastDto, BroadcastPreviewRequest, BroadcastQuery, BroadcastSave, BroadcastStats, BroadcastStatus, FileRef };

package/dist/contracts/chats.d.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+/** Telegram chat types. */
+export declare const CHAT_KINDS: readonly ["private", "group", "supergroup", "channel"];
+/** Zod enum of {@link CHAT_KINDS}. */
+export declare const ChatKind: z.ZodEnum<{
+  private: "private";
+  group: "group";
+  supergroup: "supergroup";
+  channel: "channel";
+}>;
+export type ChatKind = z.infer<typeof ChatKind>;
+/** Chat lifecycle: `pending` until linked, `blocked`/`left` when the bot can no longer post, `migrated` after a group → supergroup upgrade. */
+export declare const CHAT_STATUSES: readonly ["pending", "active", "blocked", "left", "migrated"];
+/** Zod enum of {@link CHAT_STATUSES}. */
+export declare const ChatStatus: z.ZodEnum<{
+  active: "active";
+  pending: "pending";
+  blocked: "blocked";
+  left: "left";
+  migrated: "migrated";
+}>;
+export type ChatStatus = z.infer<typeof ChatStatus>;
+/** Whose permissions apply to what a group sees: a host role, or a fixed list of users. */
+export declare const Audience: z.ZodUnion<readonly [z.ZodObject<{
+  role: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  users: z.ZodArray<z.ZodString>;
+}, z.core.$strict>]>;
+export type Audience = z.infer<typeof Audience>;
+/** Forum topics known for a chat: name → `message_thread_id`. */
+export declare const ChatTopics: z.ZodRecord<z.ZodString, z.ZodNumber>;
+export type ChatTopics = z.infer<typeof ChatTopics>;
+/** A chat the bot knows (`/admin/chats`, permission `telegram.chats.manage`). */
+export declare const ChatDto: z.ZodObject<{
+  id: z.ZodString;
+  botId: z.ZodString;
+  chatId: z.ZodString;
+  kind: z.ZodEnum<{
+    private: "private";
+    group: "group";
+    supergroup: "supergroup";
+    channel: "channel";
+  }>;
+  title: z.ZodNullable<z.ZodString>;
+  username: z.ZodNullable<z.ZodString>;
+  userId: z.ZodNullable<z.ZodString>;
+  audience: z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+    role: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    users: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>]>>;
+  status: z.ZodEnum<{
+    active: "active";
+    pending: "pending";
+    blocked: "blocked";
+    left: "left";
+    migrated: "migrated";
+  }>;
+  locale: z.ZodNullable<z.ZodString>;
+  timezone: z.ZodNullable<z.ZodString>;
+  topics: z.ZodRecord<z.ZodString, z.ZodNumber>;
+  linkedBy: z.ZodNullable<z.ZodString>;
+  linkedAt: z.ZodNullable<z.ZodNumber>;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type ChatDto = z.infer<typeof ChatDto>;
+/** `PATCH /admin/chats/:id` body; every field optional, `null` clears an override. */
+export declare const ChatPatch: z.ZodObject<{
+  audience: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+    role: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    users: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>]>>>;
+  locale: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  timezone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  topics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>;
+export type ChatPatch = z.infer<typeof ChatPatch>;
+/** Filters for `GET /admin/chats` (`user` = host user id). */
+export declare const ChatQuery: z.ZodObject<{
+  bot: z.ZodOptional<z.ZodString>;
+  kind: z.ZodOptional<z.ZodEnum<{
+    private: "private";
+    group: "group";
+    supergroup: "supergroup";
+    channel: "channel";
+  }>>;
+  status: z.ZodOptional<z.ZodEnum<{
+    active: "active";
+    pending: "pending";
+    blocked: "blocked";
+    left: "left";
+    migrated: "migrated";
+  }>>;
+  user: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChatQuery = z.infer<typeof ChatQuery>;

package/dist/contracts/chats.js

@@ -0,0 +1,66 @@
+import { EpochMs, Id, Locale, TelegramChatId, TimeZone } from "./common.js";
+import { z } from "zod";
+// src/contracts/chats.ts
+/** Telegram chat types. */
+const CHAT_KINDS = [
+	"private",
+	"group",
+	"supergroup",
+	"channel"
+];
+/** Zod enum of {@link CHAT_KINDS}. */
+const ChatKind = z.enum(CHAT_KINDS);
+/** Chat lifecycle: `pending` until linked, `blocked`/`left` when the bot can no longer post, `migrated` after a group → supergroup upgrade. */
+const CHAT_STATUSES = [
+	"pending",
+	"active",
+	"blocked",
+	"left",
+	"migrated"
+];
+/** Zod enum of {@link CHAT_STATUSES}. */
+const ChatStatus = z.enum(CHAT_STATUSES);
+/** Whose permissions apply to what a group sees: a host role, or a fixed list of users. */
+const Audience = z.union([z.strictObject({ role: z.string().min(1).max(64) }), z.strictObject({ users: z.array(z.string().min(1)).min(1).max(100) })]);
+/** Forum topics known for a chat: name → `message_thread_id`. */
+const ChatTopics = z.record(z.string().min(1).max(128), z.number().int().positive());
+/** A chat the bot knows (`/admin/chats`, permission `telegram.chats.manage`). */
+const ChatDto = z.object({
+	id: Id,
+	botId: Id,
+	/** Telegram chat id (text). */
+	chatId: TelegramChatId,
+	kind: ChatKind,
+	title: z.string().nullable(),
+	username: z.string().nullable(),
+	/** Host user linked to a private chat, or null. */
+	userId: z.string().nullable(),
+	/** Whose permissions a group or channel sees; null for private chats or unset groups. */
+	audience: Audience.nullable(),
+	status: ChatStatus,
+	/** Locale override, or null for the bot default. */
+	locale: Locale.nullable(),
+	/** IANA zone override for this chat, or null for the bot/host default. */
+	timezone: z.string().nullable(),
+	topics: ChatTopics,
+	/** Host user id who linked the chat, or null. */
+	linkedBy: z.string().nullable(),
+	/** When the chat was linked (epoch ms UTC), or null. */
+	linkedAt: EpochMs.nullable(),
+	updatedAt: EpochMs
+});
+/** `PATCH /admin/chats/:id` body; every field optional, `null` clears an override. */
+const ChatPatch = z.object({
+	audience: Audience.nullable(),
+	locale: Locale.nullable(),
+	timezone: TimeZone.nullable(),
+	topics: ChatTopics
+}).partial();
+/** Filters for `GET /admin/chats` (`user` = host user id). */
+const ChatQuery = z.object({
+	bot: Id.optional(),
+	kind: ChatKind.optional(),
+	status: ChatStatus.optional(),
+	user: z.string().optional()
+});
+export { Audience, CHAT_KINDS, CHAT_STATUSES, ChatDto, ChatKind, ChatPatch, ChatQuery, ChatStatus, ChatTopics };

package/dist/contracts/commands.d.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+/** Telegram command name: lowercase, ≤ 32 chars, `[a-z0-9_]`. */
+export declare const CommandName: z.ZodString;
+/** Commands the plugin implements itself. */
+export declare const BUILTIN_COMMANDS: readonly ["start", "help", "stop", "settings", "whoami", "language"];
+/** Zod enum of {@link BUILTIN_COMMANDS}. */
+export declare const BuiltinCommand: z.ZodEnum<{
+  start: "start";
+  help: "help";
+  stop: "stop";
+  settings: "settings";
+  whoami: "whoami";
+  language: "language";
+}>;
+export type BuiltinCommand = z.infer<typeof BuiltinCommand>;
+/** A registered command and its per-bot configuration (`tg_command`). */
+export declare const CommandConfigDto: z.ZodObject<{
+  command: z.ZodString;
+  builtin: z.ZodBoolean;
+  enabled: z.ZodBoolean;
+  roles: z.ZodNullable<z.ZodArray<z.ZodString>>;
+  defaultRoles: z.ZodArray<z.ZodString>;
+  aliases: z.ZodArray<z.ZodString>;
+  description: z.ZodRecord<z.ZodString, z.ZodString>;
+  showInMenu: z.ZodBoolean;
+  sort: z.ZodNumber;
+  scope: z.ZodArray<z.ZodEnum<{
+    private: "private";
+    group: "group";
+    supergroup: "supergroup";
+    channel: "channel";
+  }>>;
+  permission: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type CommandConfigDto = z.infer<typeof CommandConfigDto>;
+/** `PUT /admin/bots/:id/commands/:command` body (permission `telegram.commands.manage`); every field optional. */
+export declare const CommandConfigSave: z.ZodObject<{
+  enabled: z.ZodOptional<z.ZodBoolean>;
+  roles: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+  aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  description: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+  showInMenu: z.ZodOptional<z.ZodBoolean>;
+  sort: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CommandConfigSave = z.infer<typeof CommandConfigSave>;
+/** `POST /admin/bots/:id/commands/sync`. */
+export declare const CommandSyncResult: z.ZodObject<{
+  synced: z.ZodBoolean;
+  calls: z.ZodNumber;
+  failed: z.ZodNumber;
+}, z.core.$strip>;
+export type CommandSyncResult = z.infer<typeof CommandSyncResult>;

package/dist/contracts/commands.js

@@ -0,0 +1,53 @@
+import { LocalizedText } from "./common.js";
+import { ChatKind } from "./chats.js";
+import { z } from "zod";
+// src/contracts/commands.ts
+/** Telegram command name: lowercase, ≤ 32 chars, `[a-z0-9_]`. */
+const CommandName = z.string().regex(/^[a-z0-9_]{1,32}$/, "command");
+/** Commands the plugin implements itself. */
+const BUILTIN_COMMANDS = [
+	"start",
+	"help",
+	"stop",
+	"settings",
+	"whoami",
+	"language"
+];
+/** Zod enum of {@link BUILTIN_COMMANDS}. */
+const BuiltinCommand = z.enum(BUILTIN_COMMANDS);
+/** A registered command and its per-bot configuration (`tg_command`). */
+const CommandConfigDto = z.object({
+	command: CommandName,
+	builtin: z.boolean(),
+	enabled: z.boolean(),
+	/** Per-bot roles: `["*"]` = any role, `[]` = no role, null = the code's `defaultRoles`. */
+	roles: z.array(z.string()).nullable(),
+	/** Roles from the command's code definition (`["*"]` = any role, `[]` = no role). */
+	defaultRoles: z.array(z.string()),
+	aliases: z.array(CommandName),
+	description: LocalizedText,
+	showInMenu: z.boolean(),
+	/** Menu order (ascending). */
+	sort: z.number().int(),
+	/** Chat kinds where the command is available. */
+	scope: z.array(ChatKind),
+	/** Host permission required to run it, or null. */
+	permission: z.string().nullable()
+});
+/** `PUT /admin/bots/:id/commands/:command` body (permission `telegram.commands.manage`); every field optional. */
+const CommandConfigSave = z.object({
+	enabled: z.boolean(),
+	/** `["*"]` = any role, `[]` = nobody, null = back to the code's `defaultRoles`. */
+	roles: z.array(z.string().min(1)).nullable(),
+	aliases: z.array(CommandName).max(10),
+	description: LocalizedText.nullable(),
+	showInMenu: z.boolean(),
+	sort: z.number().int().min(0).max(1e3)
+}).partial();
+/** `POST /admin/bots/:id/commands/sync`. */
+const CommandSyncResult = z.object({
+	synced: z.boolean(),
+	calls: z.number().int().nonnegative(),
+	failed: z.number().int().nonnegative()
+});
+export { BUILTIN_COMMANDS, BuiltinCommand, CommandConfigDto, CommandConfigSave, CommandName, CommandSyncResult };