@prajwalshete/telegram-plugin 0.0.0-stage → 0.1.1

package/dist/engine/registry.d.ts

@@ -0,0 +1,502 @@
+import { BotDto } from "../contracts/bots.js";
+import { Audience, ChatDto, ChatKind } from "../contracts/chats.js";
+import { LocalizedText } from "../contracts/common.js";
+import { ButtonRows } from "../contracts/templates.js";
+import { SqlFragment } from "../ports/sql.js";
+import { DbPort } from "../ports/db.js";
+import { OpenedFile, StoredFile } from "../ports/ports.js";
+import { z } from "zod";
+type MaybePromise<T> = T | Promise<T>;
+/** What a provider's `run` receives. */
+export interface ProviderContext<A, P, E = unknown> {
+  /** The audience actor (linked user, or the group's audience role). Read data only as this actor. */
+  actor: A;
+  /** Parameters, already parsed with the provider's `params` schema. */
+  params: P;
+  /** Epoch ms UTC of this run (the plugin clock). */
+  now: number;
+  /** IANA time zone of the run (schedule / bot zone). */
+  tz: string;
+  /** Locale of the recipient chat (`en`, `mr`, …). */
+  locale: string;
+  /** The plugin's database port, for the host's own read queries. */
+  db: DbPort;
+  /** The Worker env of this invocation (the value the plugin's `env` mapper received), for per-request bindings. */
+  env: E;
+}
+/**
+ * A host data provider (`defineProvider`): data for templates, reports and commands. The plugin runs it as each
+ * audience actor and keeps only the keys declared in `variables`.
+ */
+export interface ProviderDef<P = unknown, V = unknown, A = unknown, E = unknown> {
+  /** Unique provider key (`[a-z0-9._:-]`, ≤ 64), referenced by templates and events. */
+  readonly key: string;
+  /** Name shown in admin pickers. */
+  readonly label: LocalizedText;
+  /** Zod schema of the provider params; `undefined` = no params. */
+  readonly params: z.ZodType<P> | undefined;
+  /** Host data permission the audience must have. */
+  readonly permission: string | null;
+  /** Zod schema of the returned data; drives template validation and the variable picker. */
+  readonly variables: z.ZodType<V>;
+  /**
+   * Fan-out reuse of one result within a run: `"none"` = per audience, `"audience-role"` = per audience role,
+   * `"params"` = one result for everyone with the same params, locale and zone.
+   */
+  readonly cacheFor: "none" | "audience-role" | "params";
+  /** Sample data for previews and template validation. */
+  sample?(): V;
+  /** Loads the data as `ctx.actor` (apply host redaction). Bounded by `limits.providerTimeoutMs`. */
+  run(ctx: ProviderContext<A, P, E>): Promise<V>;
+}
+/** Input of `defineProvider`; see `ProviderDef` for the meaning of each field. */
+export interface ProviderInput<P, V, A, E = unknown> {
+  /** Unique key, `[a-z0-9._:-]`, ≤ 64. */
+  key: string;
+  /** Name shown in admin pickers (at least one locale). */
+  label: LocalizedText;
+  /** Zod schema of the params. Default: no params. */
+  params?: z.ZodType<P>;
+  /** Host data permission the audience must have. Default: none. */
+  permission?: string;
+  /** Zod schema of the returned data. */
+  variables: z.ZodType<V>;
+  /** Sample data for previews. */
+  sample?: () => V;
+  /** Fan-out reuse (see `ProviderDef.cacheFor`). Default `"none"`. */
+  cacheFor?: "none" | "audience-role" | "params";
+  /** Loads the data as `ctx.actor`. */
+  run(ctx: ProviderContext<A, P, E>): Promise<V>;
+}
+/** Options of a `ReplyApi` call. */
+export interface ReplyOptions {
+  /** Inline keyboard rows (template button spec). */
+  buttons?: ButtonRows;
+  /** Send without notification sound (`disable_notification`). Default false. */
+  silent?: boolean;
+  /** Forbid forwarding and saving (`protect_content`). Default false. */
+  protectContent?: boolean;
+  /** Send as plain text (no HTML parse mode). */
+  plain?: boolean;
+}
+/** How a handler answers. Every reply goes through the outbox (pacing + retries). */
+export interface ReplyApi {
+  /** Telegram HTML (escape dynamic values with `escapeHtml`). Long text is split into parts. */
+  text(html: string, opts?: ReplyOptions): Promise<void>;
+  /** Render a template as the chat's audience (Phase 3). */
+  template(key: string, params?: Record<string, unknown>, opts?: ReplyOptions): Promise<void>;
+  /** Send a stored file (host file ref through a file source or the files port). */
+  file(file: {
+    source?: string;
+    ref: string;
+    caption?: string;
+  }, opts?: ReplyOptions): Promise<void>;
+}
+/** What a command's `handle` receives. */
+export interface CommandContext<A, Args, E = unknown> {
+  /** Live actor of the chat (linked user, or the group audience); null in unlinked chats. */
+  actor: A | null;
+  /** The chat the command came from; null when it is not stored yet. */
+  chat: ChatDto | null;
+  /** The bot that received the command. */
+  bot: BotDto;
+  /** Arguments parsed with `parseArgs` (or the default splitter) and validated with `args`. */
+  args: Args;
+  /** Raw text after the command name (and `@bot`), trimmed. */
+  argsText: string;
+  /** Locale of the chat. */
+  locale: string;
+  /** Translates a plugin or host i18n key for `locale`. */
+  t(key: string, vars?: Record<string, unknown>): string;
+  /** Replies in this chat through the outbox. */
+  reply: ReplyApi;
+  /** Start a registered dialog in this chat (Phase 4). */
+  startDialog(key: string, state?: Record<string, unknown>): Promise<void>;
+  /** The plugin's database port for this invocation (read host data as `actor`). */
+  db: DbPort;
+  /** Epoch ms of this update (the plugin clock). */
+  now: number;
+  /** The Worker env of this invocation (the value the plugin's `env` mapper received), for per-request bindings. */
+  env: E;
+}
+/**
+ * A host bot command (`defineCommand`). Checked on every call: enabled → chat scope → linked audience → linked
+ * sender (groups, see `groupMembers`) → roles → host `permission` → Zod `args`. Admins can override roles, aliases, description, menu and sort per bot.
+ */
+export interface CommandDef<Args = unknown, A = unknown, E = unknown> {
+  /** Command name without the slash (`[a-z0-9_]{1,32}`, not a reserved name). */
+  readonly command: string;
+  /** Menu / help description. */
+  readonly description: LocalizedText;
+  /** Host permission the chat's actor must have; null = none. */
+  readonly permission: string | null;
+  /**
+   * Roles allowed by default: `["*"]` = any role (the default), `[]` = no role (nobody may run it until an admin
+   * sets roles per bot), otherwise the listed roles. Overridable per bot (`tg_command.roles_json`, same meaning;
+   * null = this default).
+   */
+  readonly defaultRoles: readonly string[];
+  /**
+   * Who may run it in a linked group: `"linked"` = only members who linked their own Telegram on this bot,
+   * `"any"` = every member (as the group's audience). Undefined = `groups.requireLinkedSender` (default "linked").
+   * The role and permission checks always run against the group's audience.
+   */
+  readonly groupMembers: "linked" | "any" | undefined;
+  /** Zod schema of the arguments; `undefined` = `{ text }` or `{}`. */
+  readonly args: z.ZodType<Args> | undefined;
+  /** Chat kinds where it works (`group` always implies `supergroup`). */
+  readonly scope: readonly ChatKind[];
+  /** Template rendered as the reply (args become its params); null when `handle` is used. */
+  readonly template: string | null;
+  /** Extra names that run the same command. */
+  readonly aliases: readonly string[];
+  /** Listed in the bot's command menu by default. */
+  readonly showInMenu: boolean;
+  /** Menu order (ascending, then by name). */
+  readonly sort: number;
+  /**
+   * Turns the raw argument text into the input of `args`. Default: one whitespace token per object key, the last
+   * key takes the rest.
+   */
+  parseArgs?(text: string): unknown;
+  /** Code handler; absent when `template` is used. */
+  handle?(ctx: CommandContext<A, Args, E>): Promise<void>;
+}
+/** Input of `defineCommand`: give exactly one of `template` or `handle`. Throws `TelegramConfigError` if invalid. */
+export interface CommandInput<Args, A, E = unknown> {
+  /** Name without the slash, `[a-z0-9_]{1,32}`, not in `RESERVED_COMMANDS`. */
+  command: string;
+  /** Menu / help description. */
+  description: LocalizedText;
+  /** Host permission checked on every call. Default: none. */
+  permission?: string;
+  /**
+   * Roles allowed by default. Default `["*"]` (any role). `[]` = no role may run it (until an admin sets roles per
+   * bot); otherwise only the listed roles.
+   */
+  defaultRoles?: string[];
+  /**
+   * In groups: `"linked"` = only members who linked their own Telegram, `"any"` = every member of a linked group
+   * runs it as the group's audience. Default: `groups.requireLinkedSender` (default "linked").
+   */
+  groupMembers?: "linked" | "any";
+  /** Zod schema of the arguments. */
+  args?: z.ZodType<Args>;
+  /** Custom argument parser (see `CommandDef.parseArgs`). */
+  parseArgs?: (text: string) => unknown;
+  /** Chat kinds where it works. `group` also covers supergroups. Default private + groups. */
+  scope?: ChatKind[];
+  /** Template key to render as the reply. */
+  template?: string;
+  /** Code handler. */
+  handle?(ctx: CommandContext<A, Args, E>): Promise<void>;
+  /** Extra names. Default `[]`. */
+  aliases?: string[];
+  /** Listed in the command menu. Default true. */
+  showInMenu?: boolean;
+  /** Menu order. Default 0. */
+  sort?: number;
+}
+/** `defaultRoles` / per-bot roles entry meaning "any role". */
+export declare const ANY_ROLE = "*";
+/** Names the plugin answers itself; host commands may not reuse them. */
+export declare const RESERVED_COMMANDS: readonly string[];
+/** A host event (`defineEvent`) the host emits with `plugin.emit()`; event rules route it to destinations. */
+export interface EventDef<P = unknown> {
+  /** Unique event key (`[a-z0-9._:-]`, ≤ 64). */
+  readonly key: string;
+  /** Name shown in admin pickers. */
+  readonly label: LocalizedText;
+  /** Zod schema of the payload, validated on emit. */
+  readonly payload: z.ZodType<P>;
+  /** Provider that re-reads data as each recipient's audience. */
+  readonly provider: string | null;
+  /** Payload fields admins may filter on in event rules. */
+  readonly filterable: readonly string[];
+  /** Removed for audiences without `sensitivePermission`. */
+  readonly sensitive: readonly string[];
+  /** Permission that may see `sensitive` fields; null = they are stripped for everyone. */
+  readonly sensitivePermission: string | null;
+}
+/** Input of `defineEvent`. Fields in `filterable` / `sensitive` must exist in an object `payload`. */
+export interface EventInput<P> {
+  /** Unique key, `[a-z0-9._:-]`, ≤ 64. */
+  key: string;
+  /** Name shown in admin pickers. */
+  label: LocalizedText;
+  /** Zod schema of the payload. */
+  payload: z.ZodType<P>;
+  /** Registered provider key to re-read data per audience. Default: none. */
+  provider?: string;
+  /** Fields admins may filter on. Default `[]`. */
+  filterable?: string[];
+  /** Fields removed for audiences without `sensitivePermission`. Default `[]`. */
+  sensitive?: string[];
+  /** Permission that may see `sensitive` fields. Default: none (always stripped). */
+  sensitivePermission?: string;
+}
+/** What an action's `run` receives (after the actor, permission and token expiry were re-checked). */
+export interface ActionContext<A, P, E = unknown> {
+  /** Live actor of the user who tapped the button. */
+  actor: A;
+  /** Params stored in the action token, parsed with the action's `params` schema. */
+  params: P;
+  /** The chat of the tapped message. */
+  chat: ChatDto;
+  /** The bot that received the tap. */
+  bot: BotDto;
+  /** Locale of the chat. */
+  locale: string;
+  /** Epoch ms UTC of the tap. */
+  now: number;
+  /** The plugin's database port. */
+  db: DbPort;
+  /** The Worker env of this invocation (the value the plugin's `env` mapper received), for per-request bindings. */
+  env: E;
+}
+/** What an action returns: a reply (HTML) and/or SQL committed with the token update in one batch. */
+export interface ActionResult {
+  /** Telegram HTML shown as the result. */
+  text?: string;
+  /** Host writes committed in the same `db.batch()` as the token update. */
+  sql?: SqlFragment[];
+}
+/** A callback-button action (`defineAction`); buttons carry an opaque `a:<token>` callback. */
+export interface ActionDef<P = unknown, A = unknown, E = unknown> {
+  /** Unique action key (`[a-z0-9._:-]`, ≤ 64), referenced by template buttons. */
+  readonly key: string;
+  /** Host permission re-checked on every tap; null = none. */
+  readonly permission: string | null;
+  /** Zod schema of the button params. */
+  readonly params: z.ZodType<P>;
+  /** Question for a second confirming tap ({{param}} placeholders); null = runs on the first tap. */
+  readonly confirm: LocalizedText | null;
+  /** Callback answer after success; null = the plugin's generic "done". */
+  readonly result: LocalizedText | null;
+  /** The token is consumed after one successful run. */
+  readonly singleUse: boolean;
+  /** Token lifetime in minutes. */
+  readonly ttlMinutes: number;
+  /** Resolves to an `ActionResult`, or nothing. */
+  run(ctx: ActionContext<A, P, E>): Promise<unknown>;
+}
+/** Input of `defineAction`. Throws `TelegramConfigError` if invalid. */
+export interface ActionInput<P, A, E = unknown> {
+  /** Unique key, `[a-z0-9._:-]`, ≤ 64. */
+  key: string;
+  /** Host permission re-checked on every tap. Default: none. */
+  permission?: string;
+  /** Zod schema of the button params. */
+  params: z.ZodType<P>;
+  /** Confirmation question (second tap). Default: none. */
+  confirm?: LocalizedText;
+  /** Callback answer after success. Default: generic "done". */
+  result?: LocalizedText;
+  /** Consume the token after one run. Default true. */
+  singleUse?: boolean;
+  /** Token lifetime. Default 7 days. */
+  ttlMinutes?: number;
+  /** Resolves to an `ActionResult`, or nothing. */
+  run(ctx: ActionContext<A, P, E>): Promise<unknown>;
+}
+/** One choice of a dialog step, shown as an inline button. */
+export interface DialogChoice {
+  /** Value stored in the dialog state when tapped. */
+  value: string;
+  /** Button text (a plain string or localized text). */
+  label: LocalizedText | string;
+}
+/** One question of a dialog. */
+export interface DialogStepDef<A = unknown, E = unknown> {
+  /** Step id, also the state key of the answer (`[a-zA-Z][a-zA-Z0-9_]{0,31}`). */
+  readonly id: string;
+  /** The question sent to the user. */
+  readonly ask: LocalizedText;
+  /** Zod schema for text input, or a media kind. Default `"text"`. */
+  readonly input: z.ZodType | "text" | "photo" | "document";
+  /** The user may `/skip` this step. */
+  readonly optional: boolean;
+  /** Choices offered as buttons, computed from the answers so far. */
+  choices?(ctx: {
+    actor: A;
+    state: Record<string, unknown>;
+    env: E;
+  }): MaybePromise<DialogChoice[]>;
+}
+/** Input of one dialog step; see `DialogStepDef`. */
+export interface DialogStepInput<A, E = unknown> {
+  /** Step id / state key, `[a-zA-Z][a-zA-Z0-9_]{0,31}`, unique in the dialog. */
+  id: string;
+  /** The question. */
+  ask: LocalizedText;
+  /** Zod schema or media kind. Default `"text"`. */
+  input?: z.ZodType | "text" | "photo" | "document";
+  /** May be skipped. Default false. */
+  optional?: boolean;
+  /** Choices offered as buttons. */
+  choices?(ctx: {
+    actor: A;
+    state: Record<string, unknown>;
+    env: E;
+  }): MaybePromise<DialogChoice[]>;
+}
+/** What a dialog's `finish` receives once every step is answered. */
+export interface DialogFinishContext<A, E = unknown> {
+  /** Live actor of the user. */
+  actor: A;
+  /** Answers by step id. */
+  state: Record<string, unknown>;
+  /** Photos / documents received in media steps, already stored through the files port. */
+  files: StoredFile[];
+  /** The chat of the dialog. */
+  chat: ChatDto;
+  /** Locale of the chat. */
+  locale: string;
+  /** The plugin's database port, for the host's own write (Telegram replies go out after `finish` resolves). */
+  db: DbPort;
+  /** Epoch ms UTC of the final answer. */
+  now: number;
+  /** The Worker env of this invocation (the value the plugin's `env` mapper received), for per-request bindings. */
+  env: E;
+}
+/** A multi-step dialog (`defineDialog`), started by `ctx.startDialog()` or `startDialog()`; `/cancel` aborts it. */
+export interface DialogDef<A = unknown, E = unknown> {
+  /** Unique dialog key (`[a-z0-9._:-]`, ≤ 64). */
+  readonly key: string;
+  /** Host permission checked when the dialog starts; null = none. */
+  readonly permission: string | null;
+  /** The questions, asked in order. */
+  readonly steps: readonly DialogStepDef<A, E>[];
+  /** Minutes of inactivity before the dialog expires. */
+  readonly timeoutMinutes: number;
+  /** Resolves to `{ text }` (the reply), or nothing. */
+  finish(ctx: DialogFinishContext<A, E>): Promise<unknown>;
+}
+/** Input of `defineDialog`. Throws `TelegramConfigError` if invalid. */
+export interface DialogInput<A, E = unknown> {
+  /** Unique key, `[a-z0-9._:-]`, ≤ 64. */
+  key: string;
+  /** Host permission checked at start. Default: none. */
+  permission?: string;
+  /** At least one step. */
+  steps: DialogStepInput<A, E>[];
+  /** Inactivity timeout in minutes. Default 30. */
+  timeoutMinutes?: number;
+  /** Resolves to `{ text }` (the reply), or nothing. */
+  finish(ctx: DialogFinishContext<A, E>): Promise<unknown>;
+}
+/** A host recipient kind (`defineAudience`), resolved to user ids at send time. */
+export interface AudienceDef<E = unknown> {
+  /** Recipient kind, used as `{ audience: key, ref }`. */
+  readonly key: string;
+  /** Name shown in admin pickers. */
+  readonly label: LocalizedText;
+  /** User ids for a ref (for example the members of a project team). */
+  resolve(ctx: {
+    ref: string;
+    db: DbPort;
+    now: number;
+    env: E;
+  }): MaybePromise<string[]>;
+  /** Optional group audience for chats bound to this kind. */
+  audienceFor?(ref: string): Audience | null;
+}
+/** Input of `defineAudience`; see `AudienceDef`. */
+export interface AudienceInput<E = unknown> {
+  /** Kind key, `[a-zA-Z][a-zA-Z0-9_]{0,31}`. */
+  key: string;
+  /** Name shown in admin pickers. */
+  label: LocalizedText;
+  /** User ids for a ref. */
+  resolve(ctx: {
+    ref: string;
+    db: DbPort;
+    now: number;
+    env: E;
+  }): MaybePromise<string[]>;
+  /** Optional group audience for chats bound to this kind. */
+  audienceFor?(ref: string): Audience | null;
+}
+/** What `FileSourceDef.resolve` receives. */
+export interface FileSourceContext<A, E = unknown> {
+  /**
+   * The requesting actor (check that it may read the file); null when the plugin re-opens the file at send time
+   * after that check passed.
+   */
+  actor: A | null;
+  /** The host's file reference (as given in the send intent / broadcast). */
+  ref: string;
+  /** The Worker env of this invocation (the value the plugin's `env` mapper received), for per-request bindings. */
+  env: E;
+}
+/** A host file source (`defineFileSource`): opens files by ref for file sends. */
+export interface FileSourceDef<A = unknown, E = unknown> {
+  /** Source key used in send intents. */
+  readonly key: string;
+  /** Name shown in admin pickers; null = the key. */
+  readonly label: LocalizedText | null;
+  /** Opens a file, or null when it does not exist or `actor` may not read it. */
+  resolve(ctx: FileSourceContext<A, E>): Promise<OpenedFile | null>;
+}
+/** Input of `defineFileSource`. */
+export interface FileSourceInput<A, E = unknown> {
+  /** Source key used in send intents (`{ file: { source, ref } }`). */
+  key: string;
+  /** Name shown in admin pickers. */
+  label?: LocalizedText;
+  /** Opens a file, or null when it does not exist or `actor` may not read it. */
+  resolve(ctx: FileSourceContext<A, E>): Promise<OpenedFile | null>;
+}
+/** Validates and freezes a provider definition. Throws `TelegramConfigError` on an invalid key, label or schema. */
+export declare function defineProvider<P = Record<string, never>, V = unknown, A = unknown, E = unknown>(def: ProviderInput<P, V, A, E>): ProviderDef<P, V, A, E>;
+/**
+ * Validates and freezes a command definition. Throws `TelegramConfigError` on a bad or reserved name or alias, or
+ * when not exactly one of `template` / `handle` is given.
+ */
+export declare function defineCommand<Args = Record<string, never>, A = unknown, E = unknown>(def: CommandInput<Args, A, E>): CommandDef<Args, A, E>;
+/**
+ * Validates and freezes an event definition. Throws `TelegramConfigError` on a bad key or label, or a
+ * filterable / sensitive field missing from an object payload.
+ */
+export declare function defineEvent<P = unknown>(def: EventInput<P>): EventDef<P>;
+/** Validates and freezes an action definition. Throws `TelegramConfigError` if invalid. */
+export declare function defineAction<P = unknown, A = unknown, E = unknown>(def: ActionInput<P, A, E>): ActionDef<P, A, E>;
+/** Validates and freezes a dialog definition (unique step ids, positive timeout). Throws `TelegramConfigError`. */
+export declare function defineDialog<A = unknown, E = unknown>(def: DialogInput<A, E>): DialogDef<A, E>;
+/** Validates and freezes a recipient-kind definition. Throws `TelegramConfigError` if invalid. */
+export declare function defineAudience<E = unknown>(def: AudienceInput<E>): AudienceDef<E>;
+/** Validates and freezes a file-source definition. Throws `TelegramConfigError` if invalid. */
+export declare function defineFileSource<A = unknown, E = unknown>(def: FileSourceInput<A, E>): FileSourceDef<A, E>;
+/**
+ * All `define*` helpers typed for one host actor and (optionally) the Worker env type that every context's `env` has:
+ * `const d = definitions<HostActor, Env>(); d.command({…})`.
+ */
+export declare function definitions<A, E = unknown>(): {
+  provider: <P = Record<string, never>, V = unknown>(def: ProviderInput<P, V, A, E>) => ProviderDef<P, V, A, E>;
+  command: <Args = Record<string, never>>(def: CommandInput<Args, A, E>) => CommandDef<Args, A, E>;
+  event: <P = unknown>(def: EventInput<P>) => EventDef<P>;
+  action: <P = unknown>(def: ActionInput<P, A, E>) => ActionDef<P, A, E>;
+  dialog: (def: DialogInput<A, E>) => DialogDef<A, E>;
+  audience: (def: AudienceInput<E>) => AudienceDef<E>;
+  fileSource: (def: FileSourceInput<A, E>) => FileSourceDef<A, E>;
+};
+/** The host definitions indexed by key (read-only, built once by `createRegistry`). */
+export interface Registry<A> {
+  /** Providers by key. */
+  readonly providers: ReadonlyMap<string, ProviderDef<unknown, unknown, A>>;
+  /** By command name and by alias. */
+  readonly commands: ReadonlyMap<string, CommandDef<unknown, A>>;
+  /** Commands in registration order (no alias duplicates). */
+  readonly commandList: readonly CommandDef<unknown, A>[];
+  /** Events by key. */
+  readonly events: ReadonlyMap<string, EventDef<unknown>>;
+  /** Actions by key. */
+  readonly actions: ReadonlyMap<string, ActionDef<unknown, A>>;
+  /** Dialogs by key. */
+  readonly dialogs: ReadonlyMap<string, DialogDef<A>>;
+  /** Recipient kinds by key. */
+  readonly audiences: ReadonlyMap<string, AudienceDef>;
+  /** File sources by key. */
+  readonly fileSources: ReadonlyMap<string, FileSourceDef<A>>;
+}
+export {};