@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/contracts/common.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+/** Plugin row id (UUIDv7 text). */
+export declare const Id: z.ZodString;
+/** Epoch milliseconds, UTC. */
+export declare const EpochMs: z.ZodNumber;
+/** BCP 47-ish locale tag the plugin understands (`en`, `mr`, `pt-BR`). */
+export declare const Locale: z.ZodString;
+export type Locale = z.infer<typeof Locale>;
+/** Text in several locales, for example `{ en: "Approve", mr: "मंजूर" }`. At least one entry. */
+export declare const LocalizedText: z.ZodRecord<z.ZodString, z.ZodString>;
+export type LocalizedText = z.infer<typeof LocalizedText>;
+/** IANA time zone name (`Asia/Kolkata`). Checked with `Intl`. */
+export declare const TimeZone: z.ZodString;
+/** Local wall-clock time `HH:MM` (24 h). */
+export declare const ClockTime: z.ZodString;
+/** Telegram chat id as text (ids exceed 2^53 in JS). */
+export declare const TelegramChatId: z.ZodString;
+/** Stable machine key (`daily-summary`, `payment.received`). */
+export declare const Key: z.ZodString;
+/** Free-form JSON object (provider params, action params). */
+export declare const JsonObject: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type JsonObject = z.infer<typeof JsonObject>;
+/** `?cursor=&limit=` for every list. */
+export declare const PageQuery: z.ZodObject<{
+  cursor: z.ZodOptional<z.ZodString>;
+  limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type PageQuery = z.infer<typeof PageQuery>;
+/** `{ items, next }` page wrapper. `next` is the cursor for the following page, or null at the end. */
+export declare function page<T extends z.ZodType>(item: T): z.ZodObject<{
+  items: z.ZodArray<T>;
+  next: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** Inferred shape of a {@link page} response. */
+export type Page<T> = {
+  items: T[];
+  next: string | null;
+};

package/dist/contracts/common.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+// src/contracts/common.ts
+/** Plugin row id (UUIDv7 text). */
+const Id = z.string().min(1).max(64);
+/** Epoch milliseconds, UTC. */
+const EpochMs = z.number().int().nonnegative();
+/** BCP 47-ish locale tag the plugin understands (`en`, `mr`, `pt-BR`). */
+const Locale = z.string().regex(/^[a-z]{2,3}(-[A-Za-z]{2,4})?$/, "locale");
+/** Text in several locales, for example `{ en: "Approve", mr: "मंजूर" }`. At least one entry. */
+const LocalizedText = z.record(Locale, z.string().min(1).max(4096)).refine((v) => Object.keys(v).length > 0, "at least one locale");
+function isTimeZone(tz) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: tz });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** IANA time zone name (`Asia/Kolkata`). Checked with `Intl`. */
+const TimeZone = z.string().min(1).max(64).refine(isTimeZone, "timezone_invalid");
+/** Local wall-clock time `HH:MM` (24 h). */
+const ClockTime = z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "HH:MM");
+/** Telegram chat id as text (ids exceed 2^53 in JS). */
+const TelegramChatId = z.string().regex(/^-?\d{1,20}$/, "chat id");
+/** Stable machine key (`daily-summary`, `payment.received`). */
+const Key = z.string().regex(/^[a-z0-9][a-z0-9._:-]{0,63}$/, "key");
+/** Free-form JSON object (provider params, action params). */
+const JsonObject = z.record(z.string(), z.unknown());
+/** `?cursor=&limit=` for every list. */
+const PageQuery = z.object({
+	cursor: z.string().max(512).optional(),
+	limit: z.coerce.number().int().min(1).max(200).default(50)
+});
+/** `{ items, next }` page wrapper. `next` is the cursor for the following page, or null at the end. */
+function page(item) {
+	return z.object({
+		items: z.array(item),
+		next: z.string().nullable()
+	});
+}
+export { ClockTime, EpochMs, Id, JsonObject, Key, Locale, LocalizedText, PageQuery, TelegramChatId, TimeZone, page };

package/dist/contracts/deliveries.d.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+/** What produced a delivery row. */
+export declare const DELIVERY_SOURCES: readonly ["schedule", "event", "broadcast", "command", "ai", "api", "system"];
+/** Zod enum of {@link DELIVERY_SOURCES}. */
+export declare const DeliverySource: z.ZodEnum<{
+  command: "command";
+  schedule: "schedule";
+  event: "event";
+  broadcast: "broadcast";
+  ai: "ai";
+  api: "api";
+  system: "system";
+}>;
+export type DeliverySource = z.infer<typeof DeliverySource>;
+/** Bot API operation a delivery performs (`edit`/`delete` act on an earlier message). */
+export declare const DELIVERY_KINDS: readonly ["text", "document", "photo", "edit", "delete"];
+/** Zod enum of {@link DELIVERY_KINDS}. */
+export declare const DeliveryKind: z.ZodEnum<{
+  text: "text";
+  document: "document";
+  photo: "photo";
+  edit: "edit";
+  delete: "delete";
+}>;
+export type DeliveryKind = z.infer<typeof DeliveryKind>;
+/** Outbox row status. `dropped` = not deliverable (chat not active); `cancelled` = cancelled by an operator or the source. */
+export declare const DELIVERY_STATUSES: readonly ["queued", "sending", "sent", "failed", "dropped", "cancelled"];
+/** Zod enum of {@link DELIVERY_STATUSES}. */
+export declare const DeliveryStatus: z.ZodEnum<{
+  queued: "queued";
+  sending: "sending";
+  sent: "sent";
+  failed: "failed";
+  dropped: "dropped";
+  cancelled: "cancelled";
+}>;
+export type DeliveryStatus = z.infer<typeof DeliveryStatus>;
+/** One outbox row (`/admin/deliveries`, permission `telegram.ops.view`). */
+export declare const DeliveryDto: z.ZodObject<{
+  id: z.ZodString;
+  botId: z.ZodString;
+  chatRef: z.ZodString;
+  messageThreadId: z.ZodNullable<z.ZodNumber>;
+  source: z.ZodEnum<{
+    command: "command";
+    schedule: "schedule";
+    event: "event";
+    broadcast: "broadcast";
+    ai: "ai";
+    api: "api";
+    system: "system";
+  }>;
+  sourceId: z.ZodNullable<z.ZodString>;
+  kind: z.ZodEnum<{
+    text: "text";
+    document: "document";
+    photo: "photo";
+    edit: "edit";
+    delete: "delete";
+  }>;
+  bodyHtml: z.ZodNullable<z.ZodString>;
+  part: z.ZodNumber;
+  parts: z.ZodNumber;
+  fileName: z.ZodNullable<z.ZodString>;
+  status: z.ZodEnum<{
+    queued: "queued";
+    sending: "sending";
+    sent: "sent";
+    failed: "failed";
+    dropped: "dropped";
+    cancelled: "cancelled";
+  }>;
+  attempts: z.ZodNumber;
+  nextAttemptAt: z.ZodNullable<z.ZodNumber>;
+  tgMessageId: z.ZodNullable<z.ZodNumber>;
+  errorCode: z.ZodNullable<z.ZodString>;
+  errorDetail: z.ZodNullable<z.ZodString>;
+  createdAt: z.ZodNumber;
+  sentAt: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type DeliveryDto = z.infer<typeof DeliveryDto>;
+/** Filters for `GET /admin/deliveries`. */
+export declare const DeliveryQuery: z.ZodObject<{
+  status: z.ZodOptional<z.ZodEnum<{
+    queued: "queued";
+    sending: "sending";
+    sent: "sent";
+    failed: "failed";
+    dropped: "dropped";
+    cancelled: "cancelled";
+  }>>;
+  source: z.ZodOptional<z.ZodEnum<{
+    command: "command";
+    schedule: "schedule";
+    event: "event";
+    broadcast: "broadcast";
+    ai: "ai";
+    api: "api";
+    system: "system";
+  }>>;
+  bot: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DeliveryQuery = z.infer<typeof DeliveryQuery>;

package/dist/contracts/deliveries.js

@@ -0,0 +1,74 @@
+import { EpochMs, Id } from "./common.js";
+import { z } from "zod";
+// src/contracts/deliveries.ts
+/** What produced a delivery row. */
+const DELIVERY_SOURCES = [
+	"schedule",
+	"event",
+	"broadcast",
+	"command",
+	"ai",
+	"api",
+	"system"
+];
+/** Zod enum of {@link DELIVERY_SOURCES}. */
+const DeliverySource = z.enum(DELIVERY_SOURCES);
+/** Bot API operation a delivery performs (`edit`/`delete` act on an earlier message). */
+const DELIVERY_KINDS = [
+	"text",
+	"document",
+	"photo",
+	"edit",
+	"delete"
+];
+/** Zod enum of {@link DELIVERY_KINDS}. */
+const DeliveryKind = z.enum(DELIVERY_KINDS);
+/** Outbox row status. `dropped` = not deliverable (chat not active); `cancelled` = cancelled by an operator or the source. */
+const DELIVERY_STATUSES = [
+	"queued",
+	"sending",
+	"sent",
+	"failed",
+	"dropped",
+	"cancelled"
+];
+/** Zod enum of {@link DELIVERY_STATUSES}. */
+const DeliveryStatus = z.enum(DELIVERY_STATUSES);
+/** One outbox row (`/admin/deliveries`, permission `telegram.ops.view`). */
+const DeliveryDto = z.object({
+	id: Id,
+	botId: Id,
+	/** Plugin chat row id (not the Telegram chat id). */
+	chatRef: Id,
+	/** Forum topic id, or null. */
+	messageThreadId: z.number().int().nullable(),
+	source: DeliverySource,
+	/** Id of the schedule run, event, broadcast… that produced it, or null. */
+	sourceId: z.string().nullable(),
+	kind: DeliveryKind,
+	/** Only for callers with `telegram.ops.content`; otherwise null. */
+	bodyHtml: z.string().nullable(),
+	/** 0-based part index of a split message. */
+	part: z.number().int().nonnegative(),
+	/** Total parts of the split message. */
+	parts: z.number().int().positive(),
+	fileName: z.string().nullable(),
+	status: DeliveryStatus,
+	attempts: z.number().int().nonnegative(),
+	/** Next retry time (epoch ms UTC), or null. */
+	nextAttemptAt: EpochMs.nullable(),
+	/** Telegram `message_id` once sent. */
+	tgMessageId: z.number().int().nullable(),
+	/** Last error code (plugin problem code or `chat_<status>`), or null. */
+	errorCode: z.string().nullable(),
+	errorDetail: z.string().nullable(),
+	createdAt: EpochMs,
+	sentAt: EpochMs.nullable()
+});
+/** Filters for `GET /admin/deliveries`. */
+const DeliveryQuery = z.object({
+	status: DeliveryStatus.optional(),
+	source: DeliverySource.optional(),
+	bot: Id.optional()
+});
+export { DELIVERY_KINDS, DELIVERY_SOURCES, DELIVERY_STATUSES, DeliveryDto, DeliveryKind, DeliveryQuery, DeliverySource, DeliveryStatus };

package/dist/contracts/destinations.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/** URL-safe slug: lowercase letters, digits, `-`; ≤ 63 chars. */
+export declare const Slug: z.ZodString;
+/** A named, reusable target ("Site Team group"). */
+export declare const DestinationDto: z.ZodObject<{
+  id: z.ZodString;
+  name: z.ZodString;
+  slug: z.ZodString;
+  botId: z.ZodString;
+  chatRef: z.ZodString;
+  messageThreadId: z.ZodNullable<z.ZodNumber>;
+  aiAllowed: z.ZodBoolean;
+  createdAt: z.ZodNumber;
+}, z.core.$strip>;
+export type DestinationDto = z.infer<typeof DestinationDto>;
+/** Body to create or replace a destination (defaults: no topic, `aiAllowed: false`). */
+export declare const DestinationSave: z.ZodObject<{
+  name: z.ZodString;
+  slug: z.ZodString;
+  chatRef: z.ZodString;
+  messageThreadId: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+  aiAllowed: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type DestinationSave = z.infer<typeof DestinationSave>;

package/dist/contracts/destinations.js

@@ -0,0 +1,28 @@
+import { EpochMs, Id } from "./common.js";
+import { z } from "zod";
+// src/contracts/destinations.ts
+/** URL-safe slug: lowercase letters, digits, `-`; ≤ 63 chars. */
+const Slug = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/, "slug");
+/** A named, reusable target ("Site Team group"). */
+const DestinationDto = z.object({
+	id: Id,
+	name: z.string(),
+	slug: Slug,
+	botId: Id,
+	/** Plugin chat row id. */
+	chatRef: Id,
+	/** Forum topic to post in, or null. */
+	messageThreadId: z.number().int().positive().nullable(),
+	/** Whether the AI send tool may target this destination. */
+	aiAllowed: z.boolean(),
+	createdAt: EpochMs
+});
+/** Body to create or replace a destination (defaults: no topic, `aiAllowed: false`). */
+const DestinationSave = z.object({
+	name: z.string().trim().min(1).max(80),
+	slug: Slug,
+	chatRef: Id,
+	messageThreadId: z.number().int().positive().nullable().default(null),
+	aiAllowed: z.boolean().default(false)
+});
+export { DestinationDto, DestinationSave, Slug };

package/dist/contracts/events.d.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+/** Comparison operators for {@link EventFilter}. */
+export declare const FILTER_OPS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "contains"];
+/** Zod enum of {@link FILTER_OPS}. */
+export declare const FilterOp: z.ZodEnum<{
+  in: "in";
+  eq: "eq";
+  ne: "ne";
+  gt: "gt";
+  gte: "gte";
+  lt: "lt";
+  lte: "lte";
+  contains: "contains";
+}>;
+export type FilterOp = z.infer<typeof FilterOp>;
+/** One condition on an event payload field (only fields the event marks `filterable`). All conditions must hold. */
+export declare const EventFilter: z.ZodObject<{
+  field: z.ZodString;
+  op: z.ZodEnum<{
+    in: "in";
+    eq: "eq";
+    ne: "ne";
+    gt: "gt";
+    gte: "gte";
+    lt: "lt";
+    lte: "lte";
+    contains: "contains";
+  }>;
+  value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>;
+}, z.core.$strip>;
+export type EventFilter = z.infer<typeof EventFilter>;
+/** At most one message per `key` (a payload field, or the whole rule when absent) every `perMinutes`. */
+export declare const Throttle: z.ZodObject<{
+  perMinutes: z.ZodNumber;
+  key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Throttle = z.infer<typeof Throttle>;
+/** Lifecycle of an emitted event row; `ignored` = processed but nothing was sent (see its error). */
+export declare const EVENT_STATUSES: readonly ["pending", "processing", "done", "failed", "ignored"];
+/** Zod enum of {@link EVENT_STATUSES}. */
+export declare const EventStatus: z.ZodEnum<{
+  pending: "pending";
+  failed: "failed";
+  done: "done";
+  processing: "processing";
+  ignored: "ignored";
+}>;
+export type EventStatus = z.infer<typeof EventStatus>;
+/** A rule that turns a host event into messages (`/admin/event-rules`, permission `telegram.events.manage`). */
+export declare const EventRuleDto: z.ZodObject<{
+  id: z.ZodString;
+  event: z.ZodString;
+  name: z.ZodString;
+  filters: z.ZodArray<z.ZodObject<{
+    field: z.ZodString;
+    op: z.ZodEnum<{
+      in: "in";
+      eq: "eq";
+      ne: "ne";
+      gt: "gt";
+      gte: "gte";
+      lt: "lt";
+      lte: "lte";
+      contains: "contains";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>;
+  }, z.core.$strip>>;
+  templateId: z.ZodString;
+  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>]>>;
+  throttle: z.ZodNullable<z.ZodObject<{
+    perMinutes: z.ZodNumber;
+    key: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  enabled: z.ZodBoolean;
+  createdBy: z.ZodNullable<z.ZodString>;
+  updatedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type EventRuleDto = z.infer<typeof EventRuleDto>;
+/** `POST`/`PUT /admin/event-rules` body (defaults: no filters, no throttle, enabled). */
+export declare const EventRuleSave: z.ZodObject<{
+  event: z.ZodString;
+  name: z.ZodString;
+  filters: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    field: z.ZodString;
+    op: z.ZodEnum<{
+      in: "in";
+      eq: "eq";
+      ne: "ne";
+      gt: "gt";
+      gte: "gte";
+      lt: "lt";
+      lte: "lte";
+      contains: "contains";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>;
+  }, z.core.$strip>>>;
+  templateId: z.ZodString;
+  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>]>>;
+  throttle: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+    perMinutes: z.ZodNumber;
+    key: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type EventRuleSave = z.infer<typeof EventRuleSave>;
+/** A host-registered event, as listed by `GET /admin/events`. */
+export declare const RegisteredEventDto: z.ZodObject<{
+  key: z.ZodString;
+  label: z.ZodRecord<z.ZodString, z.ZodString>;
+  filterable: z.ZodArray<z.ZodString>;
+  sensitive: z.ZodArray<z.ZodString>;
+  provider: z.ZodNullable<z.ZodString>;
+  payloadSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type RegisteredEventDto = z.infer<typeof RegisteredEventDto>;
+/** `GET /admin/event-rules?event=`. */
+export declare const EventRuleQuery: z.ZodObject<{
+  event: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EventRuleQuery = z.infer<typeof EventRuleQuery>;
+/** `POST /admin/event-rules/:id/test`: a sample payload, validated by the event's schema. */
+export declare const EventRuleTestRequest: z.ZodObject<{
+  payload: z.ZodUnknown;
+}, z.core.$strip>;
+export type EventRuleTestRequest = z.infer<typeof EventRuleTestRequest>;
+/** What a rule test queued to the caller's own private chats, and how it rendered for the caller. */
+export declare const EventRuleTestResult: z.ZodObject<{
+  filtersMatch: z.ZodBoolean;
+  chats: z.ZodNumber;
+  deliveries: z.ZodNumber;
+  parts: z.ZodArray<z.ZodString>;
+  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 EventRuleTestResult = z.infer<typeof EventRuleTestResult>;

package/dist/contracts/events.js

@@ -0,0 +1,98 @@
+import { EpochMs, Id, Key, LocalizedText } from "./common.js";
+import { Recipients } from "./recipients.js";
+import { TemplateError } from "./problems.js";
+import { z } from "zod";
+// src/contracts/events.ts
+/** Comparison operators for {@link EventFilter}. */
+const FILTER_OPS = [
+	"eq",
+	"ne",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"contains"
+];
+/** Zod enum of {@link FILTER_OPS}. */
+const FilterOp = z.enum(FILTER_OPS);
+const FilterValue = z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.array(z.union([z.string(), z.number()]))
+]);
+/** One condition on an event payload field (only fields the event marks `filterable`). All conditions must hold. */
+const EventFilter = z.object({
+	field: z.string().min(1).max(64),
+	op: FilterOp,
+	value: FilterValue
+});
+/** At most one message per `key` (a payload field, or the whole rule when absent) every `perMinutes`. */
+const Throttle = z.object({
+	perMinutes: z.number().int().min(1).max(10080),
+	key: z.string().max(64).optional()
+});
+/** Lifecycle of an emitted event row; `ignored` = processed but nothing was sent (see its error). */
+const EVENT_STATUSES = [
+	"pending",
+	"processing",
+	"done",
+	"failed",
+	"ignored"
+];
+/** Zod enum of {@link EVENT_STATUSES}. */
+const EventStatus = z.enum(EVENT_STATUSES);
+/** A rule that turns a host event into messages (`/admin/event-rules`, permission `telegram.events.manage`). */
+const EventRuleDto = z.object({
+	id: Id,
+	event: Key,
+	name: z.string(),
+	filters: z.array(EventFilter),
+	templateId: Id,
+	recipients: Recipients,
+	throttle: Throttle.nullable(),
+	enabled: z.boolean(),
+	createdBy: z.string().nullable(),
+	updatedAt: EpochMs
+});
+/** `POST`/`PUT /admin/event-rules` body (defaults: no filters, no throttle, enabled). */
+const EventRuleSave = z.object({
+	event: Key,
+	name: z.string().trim().min(1).max(120),
+	filters: z.array(EventFilter).max(10).default([]),
+	templateId: Id,
+	recipients: Recipients,
+	throttle: Throttle.nullable().default(null),
+	enabled: z.boolean().default(true)
+});
+/** A host-registered event, as listed by `GET /admin/events`. */
+const RegisteredEventDto = z.object({
+	key: Key,
+	label: LocalizedText,
+	/** Payload fields rules may filter on. */
+	filterable: z.array(z.string()),
+	/** Payload fields hidden from audiences without the event's `sensitivePermission`. */
+	sensitive: z.array(z.string()),
+	/** Provider that supplies extra template data, or null. */
+	provider: Key.nullable(),
+	/** JSON Schema of the event payload. */
+	payloadSchema: z.record(z.string(), z.unknown())
+});
+/** `GET /admin/event-rules?event=`. */
+const EventRuleQuery = z.object({ event: Key.optional() });
+/** `POST /admin/event-rules/:id/test`: a sample payload, validated by the event's schema. */
+const EventRuleTestRequest = z.object({ payload: z.unknown() });
+/** What a rule test queued to the caller's own private chats, and how it rendered for the caller. */
+const EventRuleTestResult = z.object({
+	/** Whether the sample payload passes the rule's filters (the test sends either way). */
+	filtersMatch: z.boolean(),
+	/** Chats that got messages (the caller's linked private chats). */
+	chats: z.number().int().nonnegative(),
+	/** Delivery rows queued (parts × chats). */
+	deliveries: z.number().int().nonnegative(),
+	/** Telegram HTML as the caller sees it, one entry per part. */
+	parts: z.array(z.string()),
+	warnings: z.array(TemplateError)
+});
+export { EVENT_STATUSES, EventFilter, EventRuleDto, EventRuleQuery, EventRuleSave, EventRuleTestRequest, EventRuleTestResult, EventStatus, FILTER_OPS, FilterOp, RegisteredEventDto, Throttle };

package/dist/contracts/features.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+/** Feature modules (docs/01 §3). `core` is always on. */
+export declare const FEATURE_KEYS: readonly ["core", "commands", "templates", "schedules", "reports", "events", "broadcasts", "actions", "dialogs", "inbound", "subscriptions", "ai", "ops"];
+/** Zod enum of {@link FEATURE_KEYS}. */
+export declare const FeatureKey: 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";
+}>;
+export type FeatureKey = z.infer<typeof FeatureKey>;

package/dist/contracts/features.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+// src/contracts/features.ts
+/** Feature modules (docs/01 §3). `core` is always on. */
+const FEATURE_KEYS = [
+	"core",
+	"commands",
+	"templates",
+	"schedules",
+	"reports",
+	"events",
+	"broadcasts",
+	"actions",
+	"dialogs",
+	"inbound",
+	"subscriptions",
+	"ai",
+	"ops"
+];
+/** Zod enum of {@link FEATURE_KEYS}. */
+const FeatureKey = z.enum(FEATURE_KEYS);
+export { FEATURE_KEYS, FeatureKey };

package/dist/contracts/health.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+/** `GET /admin/health` (permission `telegram.ops.view`): tick freshness, outbox backlog, stuck schedule runs, bots, keyring and schema state. */
+export declare const HealthDto: z.ZodObject<{
+  ok: z.ZodBoolean;
+  lastTickAt: z.ZodNullable<z.ZodNumber>;
+  tickStale: z.ZodBoolean;
+  deliveries: z.ZodObject<{
+    queued: z.ZodNumber;
+    failed24h: z.ZodNumber;
+    oldestQueuedAgeMs: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>;
+  schedules: z.ZodObject<{
+    stuckRuns: z.ZodNumber;
+    runStuckFailed24h: z.ZodNumber;
+  }, z.core.$strip>;
+  bots: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    username: z.ZodString;
+    status: z.ZodEnum<{
+      active: "active";
+      disabled: "disabled";
+      invalid_token: "invalid_token";
+      webhook_error: "webhook_error";
+    }>;
+    pendingUpdateCount: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  keyring: z.ZodObject<{
+    activeKid: z.ZodNullable<z.ZodString>;
+    rowsByKid: z.ZodRecord<z.ZodString, z.ZodNumber>;
+  }, z.core.$strip>;
+  schema: z.ZodObject<{
+    required: z.ZodNumber;
+    current: z.ZodNullable<z.ZodNumber>;
+    ok: z.ZodBoolean;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+export type HealthDto = z.infer<typeof HealthDto>;
+/** `GET /admin/stats?from=&to=`: window in epoch ms UTC, `[from, to)`. */
+export declare const StatsQuery: z.ZodObject<{
+  from: z.ZodCoercedNumber<unknown>;
+  to: z.ZodCoercedNumber<unknown>;
+}, z.core.$strip>;
+export type StatsQuery = z.infer<typeof StatsQuery>;
+/** Delivery counts in `[from, to)`. `rateLimited` = deliveries whose last error was a 429; `updates` = inbound updates. */
+export declare const StatsDto: z.ZodObject<{
+  from: z.ZodNumber;
+  to: z.ZodNumber;
+  sent: z.ZodNumber;
+  failed: z.ZodNumber;
+  dropped: z.ZodNumber;
+  rateLimited: z.ZodNumber;
+  bySource: z.ZodRecord<z.ZodString, z.ZodNumber>;
+  updates: z.ZodNumber;
+}, z.core.$strip>;
+export type StatsDto = z.infer<typeof StatsDto>;