@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/contracts/health.js

@@ -0,0 +1,58 @@
+import { EpochMs, Id } from "./common.js";
+import { BotStatus } from "./bots.js";
+import { z } from "zod";
+// src/contracts/health.ts
+/** `GET /admin/health` (permission `telegram.ops.view`): tick freshness, outbox backlog, stuck schedule runs, bots, keyring and schema state. */
+const HealthDto = z.object({
+	ok: z.boolean(),
+	/** Last cron/DO tick (epoch ms UTC), or null. */
+	lastTickAt: EpochMs.nullable(),
+	/** True when the last tick is older than 5 minutes. */
+	tickStale: z.boolean(),
+	deliveries: z.object({
+		queued: z.number().int().nonnegative(),
+		failed24h: z.number().int().nonnegative(),
+		oldestQueuedAgeMs: z.number().int().nonnegative().nullable()
+	}),
+	/** Schedule runs that need attention (the tick resumes stuck runs, then fails them with `run_stuck`). */
+	schedules: z.object({
+		/** Runs still `running` after `STUCK_RUN_MS` (10 min). */
+		stuckRuns: z.number().int().nonnegative(),
+		/** Runs marked `failed` with `run_stuck` in the last 24 h. */
+		runStuckFailed24h: z.number().int().nonnegative()
+	}),
+	bots: z.array(z.object({
+		id: Id,
+		username: z.string(),
+		status: BotStatus,
+		pendingUpdateCount: z.number().int().nonnegative().nullable()
+	})),
+	/** Active key id and encrypted row counts per key id (for rekey progress). */
+	keyring: z.object({
+		activeKid: z.string().nullable(),
+		rowsByKid: z.record(z.string(), z.number().int())
+	}),
+	/** Required vs applied plugin schema version. */
+	schema: z.object({
+		required: z.number().int(),
+		current: z.number().int().nullable(),
+		ok: z.boolean()
+	})
+});
+/** `GET /admin/stats?from=&to=`: window in epoch ms UTC, `[from, to)`. */
+const StatsQuery = z.object({
+	from: z.coerce.number().int(),
+	to: z.coerce.number().int()
+});
+/** Delivery counts in `[from, to)`. `rateLimited` = deliveries whose last error was a 429; `updates` = inbound updates. */
+const StatsDto = z.object({
+	from: EpochMs,
+	to: EpochMs,
+	sent: z.number().int().nonnegative(),
+	failed: z.number().int().nonnegative(),
+	dropped: z.number().int().nonnegative(),
+	rateLimited: z.number().int().nonnegative(),
+	bySource: z.record(z.string(), z.number().int().nonnegative()),
+	updates: z.number().int().nonnegative()
+});
+export { HealthDto, StatsDto, StatsQuery };

package/dist/contracts/index.d.ts

@@ -0,0 +1,22 @@
+import { BOT_MODES, BOT_STATUSES, BotCreate, BotDto, BotFeatures, BotMode, BotPatch, BotRotateToken, BotStatus, BotTestResult, BotToken } from "./bots.js";
+import { BROADCAST_STATUSES, BroadcastDto, BroadcastPreviewRequest, BroadcastQuery, BroadcastSave, BroadcastStats, BroadcastStatus, FileRef } from "./broadcasts.js";
+import { Audience, CHAT_KINDS, CHAT_STATUSES, ChatDto, ChatKind, ChatPatch, ChatQuery, ChatStatus, ChatTopics } from "./chats.js";
+import { BUILTIN_COMMANDS, BuiltinCommand, CommandConfigDto, CommandConfigSave, CommandName, CommandSyncResult } from "./commands.js";
+import { ClockTime, EpochMs, Id, JsonObject, Key, Locale, LocalizedText, Page, PageQuery, TelegramChatId, TimeZone, page } from "./common.js";
+import { DELIVERY_KINDS, DELIVERY_SOURCES, DELIVERY_STATUSES, DeliveryDto, DeliveryKind, DeliveryQuery, DeliverySource, DeliveryStatus } from "./deliveries.js";
+import { DestinationDto, DestinationSave, Slug } from "./destinations.js";
+import { EVENT_STATUSES, EventFilter, EventRuleDto, EventRuleQuery, EventRuleSave, EventRuleTestRequest, EventRuleTestResult, EventStatus, FILTER_OPS, FilterOp, RegisteredEventDto, Throttle } from "./events.js";
+import { FEATURE_KEYS, FeatureKey } from "./features.js";
+import { HealthDto, StatsDto, StatsQuery } from "./health.js";
+import { LABELLED_ENUMS, LabelGroup, labelKey } from "./labels.js";
+import { LINK_PURPOSES, LinkCreate, LinkPurpose, LinkResult, PendingLinkDto, SelfLinkCreate } from "./links.js";
+import { JsonSchema, MetaAction, MetaAudience, MetaCommand, MetaDialog, MetaEvent, MetaFilter, MetaProvider, PluginMeta } from "./meta.js";
+import { PERMISSION_NAMES, PermissionName, permissionName } from "./permissions.js";
+import { FieldIssue, PROBLEM_CONTENT_TYPE, PROBLEM_STATUS, TELEGRAM_PROBLEM_CODES, TelegramProblem, TelegramProblemCode, TemplateError } from "./problems.js";
+import { RecipientSpec, Recipients } from "./recipients.js";
+import { CronExpr, LocalDateTime, MISSED_POLICIES, MissedPolicy, NextRunsRequest, NextRunsResponse, PAUSED_INDEFINITELY, SCHEDULE_RULE_KINDS, SCHEDULE_RUN_STATUSES, SCHEDULE_RUN_TRIGGERS, ScheduleDto, SchedulePause, ScheduleRule, ScheduleRuleKind, ScheduleRunDto, ScheduleRunStatus, ScheduleRunTrigger, ScheduleSave, WEEKDAYS, Weekday } from "./schedules.js";
+import { SendIntent, SendPreview, SendResult, SendTarget, SendWhat } from "./send.js";
+import { QuietHours, SubscriptionDto, SubscriptionSave, SubscriptionTopic } from "./subscriptions.js";
+import { BUTTON_STYLES, ButtonRows, ButtonSpec, ButtonStyle, PreviewAs, PreviewButton, PreviewFile, REPORT_COLUMN_FORMATS, REPORT_FORMATS, ReportColumn, ReportColumnFormat, ReportFormat, ReportLayout, ReportRenderRequest, ReportSpec, TEMPLATE_FORMATS, TEMPLATE_KINDS, TemplateDto, TemplateFormat, TemplateKind, TemplateOptions, TemplatePreviewRequest, TemplatePreviewResponse, TemplateQuery, TemplateSave, TemplateVersionDto } from "./templates.js";
+import { UserDto, UserQuery } from "./users.js";
+export { Audience, BOT_MODES, BOT_STATUSES, BROADCAST_STATUSES, BUILTIN_COMMANDS, BUTTON_STYLES, BotCreate, BotDto, BotFeatures, BotMode, BotPatch, BotRotateToken, BotStatus, BotTestResult, BotToken, BroadcastDto, BroadcastPreviewRequest, BroadcastQuery, BroadcastSave, BroadcastStats, BroadcastStatus, BuiltinCommand, ButtonRows, ButtonSpec, ButtonStyle, CHAT_KINDS, CHAT_STATUSES, ChatDto, ChatKind, ChatPatch, ChatQuery, ChatStatus, ChatTopics, ClockTime, CommandConfigDto, CommandConfigSave, CommandName, CommandSyncResult, CronExpr, DELIVERY_KINDS, DELIVERY_SOURCES, DELIVERY_STATUSES, DeliveryDto, DeliveryKind, DeliveryQuery, DeliverySource, DeliveryStatus, DestinationDto, DestinationSave, EVENT_STATUSES, EpochMs, EventFilter, EventRuleDto, EventRuleQuery, EventRuleSave, EventRuleTestRequest, EventRuleTestResult, EventStatus, FEATURE_KEYS, FILTER_OPS, FeatureKey, FieldIssue, FileRef, FilterOp, HealthDto, Id, JsonObject, JsonSchema, Key, LABELLED_ENUMS, LINK_PURPOSES, LabelGroup, LinkCreate, LinkPurpose, LinkResult, LocalDateTime, Locale, LocalizedText, MISSED_POLICIES, MetaAction, MetaAudience, MetaCommand, MetaDialog, MetaEvent, MetaFilter, MetaProvider, MissedPolicy, NextRunsRequest, NextRunsResponse, PAUSED_INDEFINITELY, PERMISSION_NAMES, PROBLEM_CONTENT_TYPE, PROBLEM_STATUS, Page, PageQuery, PendingLinkDto, PermissionName, PluginMeta, PreviewAs, PreviewButton, PreviewFile, QuietHours, REPORT_COLUMN_FORMATS, REPORT_FORMATS, RecipientSpec, Recipients, RegisteredEventDto, ReportColumn, ReportColumnFormat, ReportFormat, ReportLayout, ReportRenderRequest, ReportSpec, SCHEDULE_RULE_KINDS, SCHEDULE_RUN_STATUSES, SCHEDULE_RUN_TRIGGERS, ScheduleDto, SchedulePause, ScheduleRule, ScheduleRuleKind, ScheduleRunDto, ScheduleRunStatus, ScheduleRunTrigger, ScheduleSave, SelfLinkCreate, SendIntent, SendPreview, SendResult, SendTarget, SendWhat, Slug, StatsDto, StatsQuery, SubscriptionDto, SubscriptionSave, SubscriptionTopic, TELEGRAM_PROBLEM_CODES, TEMPLATE_FORMATS, TEMPLATE_KINDS, TelegramChatId, TelegramProblem, TelegramProblemCode, TemplateDto, TemplateError, TemplateFormat, TemplateKind, TemplateOptions, TemplatePreviewRequest, TemplatePreviewResponse, TemplateQuery, TemplateSave, TemplateVersionDto, Throttle, TimeZone, UserDto, UserQuery, WEEKDAYS, Weekday, labelKey, page, permissionName };

package/dist/contracts/index.js

@@ -0,0 +1,22 @@
+import { ClockTime, EpochMs, Id, JsonObject, Key, Locale, LocalizedText, PageQuery, TelegramChatId, TimeZone, page } from "./common.js";
+import { FEATURE_KEYS, FeatureKey } from "./features.js";
+import { BOT_MODES, BOT_STATUSES, BotCreate, BotDto, BotFeatures, BotMode, BotPatch, BotRotateToken, BotStatus, BotTestResult, BotToken } from "./bots.js";
+import { DestinationDto, DestinationSave, Slug } from "./destinations.js";
+import { RecipientSpec, Recipients } from "./recipients.js";
+import { FieldIssue, PROBLEM_CONTENT_TYPE, PROBLEM_STATUS, TELEGRAM_PROBLEM_CODES, TelegramProblem, TelegramProblemCode, TemplateError } from "./problems.js";
+import { BUTTON_STYLES, ButtonRows, ButtonSpec, ButtonStyle, PreviewAs, PreviewButton, PreviewFile, REPORT_COLUMN_FORMATS, REPORT_FORMATS, ReportColumn, ReportColumnFormat, ReportFormat, ReportLayout, ReportRenderRequest, ReportSpec, TEMPLATE_FORMATS, TEMPLATE_KINDS, TemplateDto, TemplateFormat, TemplateKind, TemplateOptions, TemplatePreviewRequest, TemplatePreviewResponse, TemplateQuery, TemplateSave, TemplateVersionDto } from "./templates.js";
+import { BROADCAST_STATUSES, BroadcastDto, BroadcastPreviewRequest, BroadcastQuery, BroadcastSave, BroadcastStats, BroadcastStatus, FileRef } from "./broadcasts.js";
+import { Audience, CHAT_KINDS, CHAT_STATUSES, ChatDto, ChatKind, ChatPatch, ChatQuery, ChatStatus, ChatTopics } from "./chats.js";
+import { BUILTIN_COMMANDS, BuiltinCommand, CommandConfigDto, CommandConfigSave, CommandName, CommandSyncResult } from "./commands.js";
+import { DELIVERY_KINDS, DELIVERY_SOURCES, DELIVERY_STATUSES, DeliveryDto, DeliveryKind, DeliveryQuery, DeliverySource, DeliveryStatus } from "./deliveries.js";
+import { EVENT_STATUSES, EventFilter, EventRuleDto, EventRuleQuery, EventRuleSave, EventRuleTestRequest, EventRuleTestResult, EventStatus, FILTER_OPS, FilterOp, RegisteredEventDto, Throttle } from "./events.js";
+import { HealthDto, StatsDto, StatsQuery } from "./health.js";
+import { LINK_PURPOSES, LinkCreate, LinkPurpose, LinkResult, PendingLinkDto, SelfLinkCreate } from "./links.js";
+import { PERMISSION_NAMES, PermissionName, permissionName } from "./permissions.js";
+import { CronExpr, LocalDateTime, MISSED_POLICIES, MissedPolicy, NextRunsRequest, NextRunsResponse, PAUSED_INDEFINITELY, SCHEDULE_RULE_KINDS, SCHEDULE_RUN_STATUSES, SCHEDULE_RUN_TRIGGERS, ScheduleDto, SchedulePause, ScheduleRule, ScheduleRuleKind, ScheduleRunDto, ScheduleRunStatus, ScheduleRunTrigger, ScheduleSave, WEEKDAYS, Weekday } from "./schedules.js";
+import { LABELLED_ENUMS, labelKey } from "./labels.js";
+import { JsonSchema, MetaAction, MetaAudience, MetaCommand, MetaDialog, MetaEvent, MetaFilter, MetaProvider, PluginMeta } from "./meta.js";
+import { SendIntent, SendPreview, SendResult, SendTarget, SendWhat } from "./send.js";
+import { QuietHours, SubscriptionDto, SubscriptionSave, SubscriptionTopic } from "./subscriptions.js";
+import { UserDto, UserQuery } from "./users.js";
+export { Audience, BOT_MODES, BOT_STATUSES, BROADCAST_STATUSES, BUILTIN_COMMANDS, BUTTON_STYLES, BotCreate, BotDto, BotFeatures, BotMode, BotPatch, BotRotateToken, BotStatus, BotTestResult, BotToken, BroadcastDto, BroadcastPreviewRequest, BroadcastQuery, BroadcastSave, BroadcastStats, BroadcastStatus, BuiltinCommand, ButtonRows, ButtonSpec, ButtonStyle, CHAT_KINDS, CHAT_STATUSES, ChatDto, ChatKind, ChatPatch, ChatQuery, ChatStatus, ChatTopics, ClockTime, CommandConfigDto, CommandConfigSave, CommandName, CommandSyncResult, CronExpr, DELIVERY_KINDS, DELIVERY_SOURCES, DELIVERY_STATUSES, DeliveryDto, DeliveryKind, DeliveryQuery, DeliverySource, DeliveryStatus, DestinationDto, DestinationSave, EVENT_STATUSES, EpochMs, EventFilter, EventRuleDto, EventRuleQuery, EventRuleSave, EventRuleTestRequest, EventRuleTestResult, EventStatus, FEATURE_KEYS, FILTER_OPS, FeatureKey, FieldIssue, FileRef, FilterOp, HealthDto, Id, JsonObject, JsonSchema, Key, LABELLED_ENUMS, LINK_PURPOSES, LinkCreate, LinkPurpose, LinkResult, LocalDateTime, Locale, LocalizedText, MISSED_POLICIES, MetaAction, MetaAudience, MetaCommand, MetaDialog, MetaEvent, MetaFilter, MetaProvider, MissedPolicy, NextRunsRequest, NextRunsResponse, PAUSED_INDEFINITELY, PERMISSION_NAMES, PROBLEM_CONTENT_TYPE, PROBLEM_STATUS, PageQuery, PendingLinkDto, PermissionName, PluginMeta, PreviewAs, PreviewButton, PreviewFile, QuietHours, REPORT_COLUMN_FORMATS, REPORT_FORMATS, RecipientSpec, Recipients, RegisteredEventDto, ReportColumn, ReportColumnFormat, ReportFormat, ReportLayout, ReportRenderRequest, ReportSpec, SCHEDULE_RULE_KINDS, SCHEDULE_RUN_STATUSES, SCHEDULE_RUN_TRIGGERS, ScheduleDto, SchedulePause, ScheduleRule, ScheduleRuleKind, ScheduleRunDto, ScheduleRunStatus, ScheduleRunTrigger, ScheduleSave, SelfLinkCreate, SendIntent, SendPreview, SendResult, SendTarget, SendWhat, Slug, StatsDto, StatsQuery, SubscriptionDto, SubscriptionSave, SubscriptionTopic, TELEGRAM_PROBLEM_CODES, TEMPLATE_FORMATS, TEMPLATE_KINDS, TelegramChatId, TelegramProblem, TelegramProblemCode, TemplateDto, TemplateError, TemplateFormat, TemplateKind, TemplateOptions, TemplatePreviewRequest, TemplatePreviewResponse, TemplateQuery, TemplateSave, TemplateVersionDto, Throttle, TimeZone, UserDto, UserQuery, WEEKDAYS, Weekday, labelKey, page, permissionName };

package/dist/contracts/labels.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Every enum that app UIs show, by label group. Each value has a label in `@prajwalshete/telegram-plugin/locales/{en,mr}.json`
+ * at `labelKey(group, value)`, so app UIs need no literal strings.
+ */
+export declare const LABELLED_ENUMS: {
+  readonly botMode: readonly ["webhook", "polling"];
+  readonly botStatus: readonly ["active", "disabled", "invalid_token", "webhook_error"];
+  readonly chatKind: readonly ["private", "group", "supergroup", "channel"];
+  readonly chatStatus: readonly ["pending", "active", "blocked", "left", "migrated"];
+  readonly linkPurpose: readonly ["user", "group"];
+  readonly builtinCommand: readonly ["start", "help", "stop", "settings", "whoami", "language"];
+  readonly templateKind: readonly ["message", "report"];
+  readonly templateFormat: readonly ["html", "text"];
+  readonly reportFormat: readonly ["pdf", "csv"];
+  readonly reportColumnFormat: readonly ["text", "number", "money", "date", "datetime", "yesno"];
+  readonly buttonStyle: readonly ["primary", "success", "danger"];
+  readonly weekday: readonly ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+  readonly scheduleRuleKind: readonly ["daily", "weekly", "monthly", "cron", "once"];
+  readonly missedPolicy: readonly ["skip", "run_once"];
+  readonly scheduleRunStatus: readonly ["running", "done", "partial", "failed", "skipped"];
+  readonly scheduleRunTrigger: readonly ["schedule", "manual"];
+  readonly filterOp: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "contains"];
+  readonly eventStatus: readonly ["pending", "processing", "done", "failed", "ignored"];
+  readonly broadcastStatus: readonly ["draft", "queued", "sending", "done"];
+  readonly deliverySource: readonly ["schedule", "event", "broadcast", "command", "ai", "api", "system"];
+  readonly deliveryKind: readonly ["text", "document", "photo", "edit", "delete"];
+  readonly deliveryStatus: readonly ["queued", "sending", "sent", "failed", "dropped", "cancelled"];
+  readonly feature: readonly ["core", "commands", "templates", "schedules", "reports", "events", "broadcasts", "actions", "dialogs", "inbound", "subscriptions", "ai", "ops"];
+  readonly permission: readonly ["telegram.view", "telegram.bots.manage", "telegram.chats.manage", "telegram.self.link", "telegram.destinations.manage", "telegram.commands.manage", "telegram.templates.manage", "telegram.schedules.manage", "telegram.events.manage", "telegram.broadcasts.send", "telegram.reports.run", "telegram.send", "telegram.ops.view", "telegram.ops.manage", "telegram.ops.content"];
+  readonly problem: readonly ["feature_disabled", "bot_token_invalid", "bot_token_mismatch", "bot_unreachable", "webhook_url_missing", "webhook_failed", "chat_not_found", "chat_blocked", "link_expired", "link_used", "destination_not_allowed", "template_invalid", "template_variable_unknown", "provider_unknown", "provider_forbidden", "schedule_rule_invalid", "timezone_invalid", "recipient_empty", "send_text_rejected", "file_too_large", "renderer_unavailable", "delivery_not_retryable", "schema_outdated", "unauthenticated", "forbidden", "not_found", "validation_failed", "rate_limited", "internal_error"];
+};
+/** A key of {@link LABELLED_ENUMS}. */
+export type LabelGroup = keyof typeof LABELLED_ENUMS;
+/**
+ * Locale key for an enum value label, for example `labels.botStatus.active`. Dots inside a value become `_`
+ * (`telegram.bots.manage` → `labels.permission.telegram_bots_manage`) so the key works with nested lookups.
+ */
+export declare function labelKey<G extends LabelGroup>(group: G, value: (typeof LABELLED_ENUMS)[G][number]): string;

package/dist/contracts/labels.js

@@ -0,0 +1,52 @@
+import { FEATURE_KEYS } from "./features.js";
+import { BOT_MODES, BOT_STATUSES } from "./bots.js";
+import { TELEGRAM_PROBLEM_CODES } from "./problems.js";
+import { BUTTON_STYLES, REPORT_COLUMN_FORMATS, REPORT_FORMATS, TEMPLATE_FORMATS, TEMPLATE_KINDS } from "./templates.js";
+import { BROADCAST_STATUSES } from "./broadcasts.js";
+import { CHAT_KINDS, CHAT_STATUSES } from "./chats.js";
+import { BUILTIN_COMMANDS } from "./commands.js";
+import { DELIVERY_KINDS, DELIVERY_SOURCES, DELIVERY_STATUSES } from "./deliveries.js";
+import { EVENT_STATUSES, FILTER_OPS } from "./events.js";
+import { LINK_PURPOSES } from "./links.js";
+import { PERMISSION_NAMES } from "./permissions.js";
+import { MISSED_POLICIES, SCHEDULE_RULE_KINDS, SCHEDULE_RUN_STATUSES, SCHEDULE_RUN_TRIGGERS, WEEKDAYS } from "./schedules.js";
+// src/contracts/labels.ts
+/**
+* Every enum that app UIs show, by label group. Each value has a label in `@prajwalshete/telegram-plugin/locales/{en,mr}.json`
+* at `labelKey(group, value)`, so app UIs need no literal strings.
+*/
+const LABELLED_ENUMS = {
+	botMode: BOT_MODES,
+	botStatus: BOT_STATUSES,
+	chatKind: CHAT_KINDS,
+	chatStatus: CHAT_STATUSES,
+	linkPurpose: LINK_PURPOSES,
+	builtinCommand: BUILTIN_COMMANDS,
+	templateKind: TEMPLATE_KINDS,
+	templateFormat: TEMPLATE_FORMATS,
+	reportFormat: REPORT_FORMATS,
+	reportColumnFormat: REPORT_COLUMN_FORMATS,
+	buttonStyle: BUTTON_STYLES,
+	weekday: WEEKDAYS,
+	scheduleRuleKind: SCHEDULE_RULE_KINDS,
+	missedPolicy: MISSED_POLICIES,
+	scheduleRunStatus: SCHEDULE_RUN_STATUSES,
+	scheduleRunTrigger: SCHEDULE_RUN_TRIGGERS,
+	filterOp: FILTER_OPS,
+	eventStatus: EVENT_STATUSES,
+	broadcastStatus: BROADCAST_STATUSES,
+	deliverySource: DELIVERY_SOURCES,
+	deliveryKind: DELIVERY_KINDS,
+	deliveryStatus: DELIVERY_STATUSES,
+	feature: FEATURE_KEYS,
+	permission: PERMISSION_NAMES,
+	problem: TELEGRAM_PROBLEM_CODES
+};
+/**
+* Locale key for an enum value label, for example `labels.botStatus.active`. Dots inside a value become `_`
+* (`telegram.bots.manage` → `labels.permission.telegram_bots_manage`) so the key works with nested lookups.
+*/
+function labelKey(group, value) {
+	return `labels.${group}.${value.replaceAll(".", "_")}`;
+}
+export { LABELLED_ENUMS, labelKey };

package/dist/contracts/links.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+/** What a one-time link code links: a user's private chat, or a group. */
+export declare const LINK_PURPOSES: readonly ["user", "group"];
+/** Zod enum of {@link LINK_PURPOSES}. */
+export declare const LinkPurpose: z.ZodEnum<{
+  group: "group";
+  user: "user";
+}>;
+export type LinkPurpose = z.infer<typeof LinkPurpose>;
+/** `POST /admin/links`: invite a user, or make a `startgroup` link for a group with an audience. */
+export declare const LinkCreate: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  bot: z.ZodString;
+  purpose: z.ZodLiteral<"user">;
+  userId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  bot: z.ZodString;
+  purpose: z.ZodLiteral<"group">;
+  audience: z.ZodUnion<readonly [z.ZodObject<{
+    role: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    users: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>]>;
+}, z.core.$strip>], "purpose">;
+export type LinkCreate = z.infer<typeof LinkCreate>;
+/** `POST /me/link`: link the caller's own Telegram. */
+export declare const SelfLinkCreate: z.ZodObject<{
+  bot: z.ZodString;
+}, z.core.$strip>;
+export type SelfLinkCreate = z.infer<typeof SelfLinkCreate>;
+/** The one-time link. The code inside `url` is shown once and never stored in plain text. */
+export declare const LinkResult: z.ZodObject<{
+  url: z.ZodURL;
+  qrPayload: z.ZodString;
+  expiresAt: z.ZodNumber;
+  requiresConfirmation: z.ZodBoolean;
+}, z.core.$strip>;
+export type LinkResult = z.infer<typeof LinkResult>;
+/**
+ * `GET /me/links/pending`: a Telegram account that redeemed an admin invite for the caller and waits for the
+ * caller's confirmation. Confirm only when the Telegram account is yours.
+ */
+export declare const PendingLinkDto: z.ZodObject<{
+  id: z.ZodString;
+  bot: z.ZodString;
+  telegramName: z.ZodNullable<z.ZodString>;
+  telegramUsername: z.ZodNullable<z.ZodString>;
+  invitedBy: z.ZodNullable<z.ZodString>;
+  createdAt: z.ZodNumber;
+  expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+export type PendingLinkDto = z.infer<typeof PendingLinkDto>;

package/dist/contracts/links.js

@@ -0,0 +1,50 @@
+import { EpochMs, Id } from "./common.js";
+import { Audience } from "./chats.js";
+import { z } from "zod";
+// src/contracts/links.ts
+/** What a one-time link code links: a user's private chat, or a group. */
+const LINK_PURPOSES = ["user", "group"];
+/** Zod enum of {@link LINK_PURPOSES}. */
+const LinkPurpose = z.enum(LINK_PURPOSES);
+/** `POST /admin/links`: invite a user, or make a `startgroup` link for a group with an audience. */
+const LinkCreate = z.discriminatedUnion("purpose", [z.object({
+	bot: Id,
+	purpose: z.literal("user"),
+	userId: z.string().min(1)
+}), z.object({
+	bot: Id,
+	purpose: z.literal("group"),
+	audience: Audience
+})]);
+/** `POST /me/link`: link the caller's own Telegram. */
+const SelfLinkCreate = z.object({ bot: Id });
+/** The one-time link. The code inside `url` is shown once and never stored in plain text. */
+const LinkResult = z.object({
+	url: z.url(),
+	/** Text to encode in a QR code (same deep link as `url`). */
+	qrPayload: z.string(),
+	/** Code expiry (epoch ms UTC). */
+	expiresAt: EpochMs,
+	/**
+	* True for an admin invite for another user: redeeming it in Telegram does not link yet; the invited user
+	* confirms it in the app (`GET /me/links/pending`, `POST /me/links/pending/:id/confirm`).
+	*/
+	requiresConfirmation: z.boolean()
+});
+/**
+* `GET /me/links/pending`: a Telegram account that redeemed an admin invite for the caller and waits for the
+* caller's confirmation. Confirm only when the Telegram account is yours.
+*/
+const PendingLinkDto = z.object({
+	id: z.string(),
+	bot: Id,
+	/** Telegram display name of the account that used the invite. */
+	telegramName: z.string().nullable(),
+	/** Telegram @username (without @), if any. */
+	telegramUsername: z.string().nullable(),
+	/** App user who made the invite, or null (an API key / system actor). */
+	invitedBy: z.string().nullable(),
+	createdAt: EpochMs,
+	expiresAt: EpochMs
+});
+export { LINK_PURPOSES, LinkCreate, LinkPurpose, LinkResult, PendingLinkDto, SelfLinkCreate };

package/dist/contracts/meta.d.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+/** JSON Schema (from Zod) describing params or variables. */
+export declare const JsonSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** A host data provider (`defineProvider`) as listed in {@link PluginMeta}. */
+export declare const MetaProvider: z.ZodObject<{
+  key: z.ZodString;
+  label: z.ZodRecord<z.ZodString, z.ZodString>;
+  permission: z.ZodNullable<z.ZodString>;
+  params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  hasSample: z.ZodBoolean;
+}, z.core.$strip>;
+/** A host or built-in command as listed in {@link PluginMeta}. */
+export declare const MetaCommand: z.ZodObject<{
+  command: z.ZodString;
+  description: z.ZodRecord<z.ZodString, z.ZodString>;
+  builtin: z.ZodBoolean;
+  permission: z.ZodNullable<z.ZodString>;
+  scope: z.ZodArray<z.ZodEnum<{
+    private: "private";
+    group: "group";
+    supergroup: "supergroup";
+    channel: "channel";
+  }>>;
+}, z.core.$strip>;
+/** A host event (`defineEvent`) as listed in {@link PluginMeta}. */
+export declare const MetaEvent: z.ZodObject<{
+  key: z.ZodString;
+  label: z.ZodRecord<z.ZodString, z.ZodString>;
+  payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  filterable: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** A button action (`defineAction`); `confirm` = asks before running. */
+export declare const MetaAction: z.ZodObject<{
+  key: z.ZodString;
+  permission: z.ZodNullable<z.ZodString>;
+  confirm: z.ZodBoolean;
+}, z.core.$strip>;
+/** A dialog (`defineDialog`) with its step keys in order. */
+export declare const MetaDialog: z.ZodObject<{
+  key: z.ZodString;
+  permission: z.ZodNullable<z.ZodString>;
+  steps: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** A named audience (`defineAudience`). */
+export declare const MetaAudience: z.ZodObject<{
+  key: z.ZodString;
+  label: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+/** A template filter usable in `{{ value | name: args }}`: built-in, or the host's (`options.filters`). */
+export declare const MetaFilter: z.ZodObject<{
+  name: z.ZodString;
+  builtin: z.ZodBoolean;
+  minArgs: z.ZodNumber;
+  maxArgs: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/** `GET /admin/meta`: one call to build any settings UI. */
+export declare const PluginMeta: z.ZodObject<{
+  pluginVersion: z.ZodString;
+  schemaVersion: z.ZodNumber;
+  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.ZodObject<{
+    enabled: z.ZodBoolean;
+  }, z.core.$strip>>;
+  locales: z.ZodArray<z.ZodString>;
+  defaultLocale: z.ZodString;
+  timezone: z.ZodString;
+  providers: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodRecord<z.ZodString, z.ZodString>;
+    permission: z.ZodNullable<z.ZodString>;
+    params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    hasSample: z.ZodBoolean;
+  }, z.core.$strip>>;
+  commands: z.ZodArray<z.ZodObject<{
+    command: z.ZodString;
+    description: z.ZodRecord<z.ZodString, z.ZodString>;
+    builtin: z.ZodBoolean;
+    permission: z.ZodNullable<z.ZodString>;
+    scope: z.ZodArray<z.ZodEnum<{
+      private: "private";
+      group: "group";
+      supergroup: "supergroup";
+      channel: "channel";
+    }>>;
+  }, z.core.$strip>>;
+  events: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodRecord<z.ZodString, z.ZodString>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    filterable: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  actions: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    permission: z.ZodNullable<z.ZodString>;
+    confirm: z.ZodBoolean;
+  }, z.core.$strip>>;
+  dialogs: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    permission: z.ZodNullable<z.ZodString>;
+    steps: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+  audiences: z.ZodArray<z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodRecord<z.ZodString, z.ZodString>;
+  }, z.core.$strip>>;
+  fileSources: z.ZodArray<z.ZodString>;
+  renderers: z.ZodArray<z.ZodString>;
+  filters: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    builtin: z.ZodBoolean;
+    minArgs: z.ZodNumber;
+    maxArgs: z.ZodNullable<z.ZodNumber>;
+  }, z.core.$strip>>;
+  userSearch: z.ZodBoolean;
+  permissions: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type PluginMeta = z.infer<typeof PluginMeta>;

package/dist/contracts/meta.js

@@ -0,0 +1,85 @@
+import { Key, LocalizedText } from "./common.js";
+import { FeatureKey } from "./features.js";
+import { ChatKind } from "./chats.js";
+import { CommandName } from "./commands.js";
+import { z } from "zod";
+// src/contracts/meta.ts
+/** JSON Schema (from Zod) describing params or variables. */
+const JsonSchema = z.record(z.string(), z.unknown());
+/** A host data provider (`defineProvider`) as listed in {@link PluginMeta}. */
+const MetaProvider = z.object({
+	key: Key,
+	label: LocalizedText,
+	permission: z.string().nullable(),
+	params: JsonSchema,
+	variables: JsonSchema,
+	/** Whether the provider defines `sample()` for previews. */
+	hasSample: z.boolean()
+});
+/** A host or built-in command as listed in {@link PluginMeta}. */
+const MetaCommand = z.object({
+	command: CommandName,
+	description: LocalizedText,
+	builtin: z.boolean(),
+	permission: z.string().nullable(),
+	scope: z.array(ChatKind)
+});
+/** A host event (`defineEvent`) as listed in {@link PluginMeta}. */
+const MetaEvent = z.object({
+	key: Key,
+	label: LocalizedText,
+	payload: JsonSchema,
+	filterable: z.array(z.string())
+});
+/** A button action (`defineAction`); `confirm` = asks before running. */
+const MetaAction = z.object({
+	key: Key,
+	permission: z.string().nullable(),
+	confirm: z.boolean()
+});
+/** A dialog (`defineDialog`) with its step keys in order. */
+const MetaDialog = z.object({
+	key: Key,
+	permission: z.string().nullable(),
+	steps: z.array(z.string())
+});
+/** A named audience (`defineAudience`). */
+const MetaAudience = z.object({
+	key: z.string(),
+	label: LocalizedText
+});
+/** A template filter usable in `{{ value | name: args }}`: built-in, or the host's (`options.filters`). */
+const MetaFilter = z.object({
+	name: z.string(),
+	builtin: z.boolean(),
+	minArgs: z.number().int().nonnegative(),
+	/** Null = no upper bound. */
+	maxArgs: z.number().int().nonnegative().nullable()
+});
+/** `GET /admin/meta`: one call to build any settings UI. */
+const PluginMeta = z.object({
+	pluginVersion: z.string(),
+	schemaVersion: z.number().int(),
+	features: z.record(FeatureKey, z.object({ enabled: z.boolean() })),
+	locales: z.array(z.string()),
+	defaultLocale: z.string(),
+	/** Plugin default IANA time zone. */
+	timezone: z.string(),
+	providers: z.array(MetaProvider),
+	commands: z.array(MetaCommand),
+	events: z.array(MetaEvent),
+	actions: z.array(MetaAction),
+	dialogs: z.array(MetaDialog),
+	audiences: z.array(MetaAudience),
+	/** Registered file-source keys (`defineFileSource`). */
+	fileSources: z.array(z.string()),
+	/** Report formats with a renderer (`ports.renderers`). */
+	renderers: z.array(z.string()),
+	/** Template filters (built-ins first, then the host's). */
+	filters: z.array(MetaFilter),
+	/** True when `GET /admin/users?q=` works (the host gave `ports.users.search`). */
+	userSearch: z.boolean(),
+	/** Plugin permissions the caller holds. */
+	permissions: z.array(z.string())
+});
+export { JsonSchema, MetaAction, MetaAudience, MetaCommand, MetaDialog, MetaEvent, MetaFilter, MetaProvider, PluginMeta };

package/dist/contracts/permissions.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/** Permission names the plugin checks through `ports.authorize` (docs/05 §4), with the default `telegram` prefix. */
+export declare const PERMISSION_NAMES: readonly ["telegram.view", "telegram.bots.manage", "telegram.chats.manage", "telegram.self.link", "telegram.destinations.manage", "telegram.commands.manage", "telegram.templates.manage", "telegram.schedules.manage", "telegram.events.manage", "telegram.broadcasts.send", "telegram.reports.run", "telegram.send", "telegram.ops.view", "telegram.ops.manage", "telegram.ops.content"];
+/** Zod enum of {@link PERMISSION_NAMES}. */
+export declare const PermissionName: z.ZodEnum<{
+  "telegram.view": "telegram.view";
+  "telegram.bots.manage": "telegram.bots.manage";
+  "telegram.chats.manage": "telegram.chats.manage";
+  "telegram.self.link": "telegram.self.link";
+  "telegram.destinations.manage": "telegram.destinations.manage";
+  "telegram.commands.manage": "telegram.commands.manage";
+  "telegram.templates.manage": "telegram.templates.manage";
+  "telegram.schedules.manage": "telegram.schedules.manage";
+  "telegram.events.manage": "telegram.events.manage";
+  "telegram.broadcasts.send": "telegram.broadcasts.send";
+  "telegram.reports.run": "telegram.reports.run";
+  "telegram.send": "telegram.send";
+  "telegram.ops.view": "telegram.ops.view";
+  "telegram.ops.manage": "telegram.ops.manage";
+  "telegram.ops.content": "telegram.ops.content";
+}>;
+export type PermissionName = z.infer<typeof PermissionName>;
+/** Permission name with a host-chosen prefix (`permissions.prefix`), for example `tg.bots.manage`. */
+export declare function permissionName(name: PermissionName, prefix?: string): string;

package/dist/contracts/permissions.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+// src/contracts/permissions.ts
+/** Permission names the plugin checks through `ports.authorize` (docs/05 §4), with the default `telegram` prefix. */
+const PERMISSION_NAMES = [
+	"telegram.view",
+	"telegram.bots.manage",
+	"telegram.chats.manage",
+	"telegram.self.link",
+	"telegram.destinations.manage",
+	"telegram.commands.manage",
+	"telegram.templates.manage",
+	"telegram.schedules.manage",
+	"telegram.events.manage",
+	"telegram.broadcasts.send",
+	"telegram.reports.run",
+	"telegram.send",
+	"telegram.ops.view",
+	"telegram.ops.manage",
+	"telegram.ops.content"
+];
+/** Zod enum of {@link PERMISSION_NAMES}. */
+const PermissionName = z.enum(PERMISSION_NAMES);
+/** Permission name with a host-chosen prefix (`permissions.prefix`), for example `tg.bots.manage`. */
+function permissionName(name, prefix = "telegram") {
+	return prefix === "telegram" ? name : `${prefix}${name.slice(8)}`;
+}
+export { PERMISSION_NAMES, PermissionName, permissionName };