@hostwebhook/node-types 1.69.0 → 1.70.0

package/dist/esm/telegram-operations.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Telegram Bot API operation enum — single source of truth across the API,
+ * Dashboard, and any future consumers (Message Broker, MCP server). Used by:
+ *   - telegramAction entity / DTO (api): operation field + validation
+ *   - dashboard TelegramAction operation picker
+ *   - MCP toolkit-specs expansion (one aiEnabled telegramAction → N tools)
+ *
+ * Phase 1 covers the eight ops that handle ~95% of bot send use cases.
+ * Phase 2 candidates (sendMediaGroup, voice/video uploads, chat admin,
+ * setMyCommands, message reactions, inline-mode answers) get added by
+ * extending this list, bumping the package, and re-installing in
+ * consumers — same pattern as Gmail / Calendar / Drive.
+ */
+export declare const TELEGRAM_OPERATIONS: readonly ["sendMessage", "replyToMessage", "sendPhoto", "sendDocument", "sendVoice", "sendAndWaitForResponse", "editMessageText", "deleteMessage", "answerCallbackQuery", "forwardMessage", "sendPoll"];
+export type TelegramOperation = (typeof TELEGRAM_OPERATIONS)[number];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export declare function isTelegramOperation(value: unknown): value is TelegramOperation;
+/**
+ * Per-operation form schema, same idea as SLACK_OPERATION_SPECS and
+ * DISCORD_OPERATION_SPECS: the detail page renders it with one loop instead of
+ * a branch per operation. It replaces 12 branches and a local `OPERATIONS`
+ * array of 11 entries whose count had already drifted from the truth — the
+ * mode chip read "Choose 1 of 10 ops" while the page painted 11 cards.
+ *
+ * Two things about this node's schema are worth knowing before writing a
+ * renderer for it:
+ *
+ * 1. **`chatId` is per-operation, not global.** The page used to hoist one
+ *    shared field to the top of every form, but `answerCallbackQuery` has no
+ *    chat at all (it answers a callback id) and `forwardMessage` needs two
+ *    chats with their own labels — "Destination" and "Source". So it is
+ *    declared op by op, and where it repeats it repeats on purpose.
+ * 2. **Three booleans default to ON.** See the note on `default` below; a
+ *    renderer that coerces with `!!config[name]` silently turns them off.
+ */
+export interface TelegramParamSpec {
+    /** Field key — the property name inside `operationConfig`. */
+    name: string;
+    /** UI label shown above the control. */
+    label: string;
+    /**
+     * Param type for form rendering.
+     *
+     * - `string` — one-line input with `{{payload.x}}` templating.
+     * - `text` — the same input, multiline; `rows` sets its height.
+     * - `select` — fixed option list (only `parseMode` today).
+     * - `boolean` — a Switch. Read it as `config[name] ?? default`, never as
+     *   `!!config[name]`: see `default`.
+     * - `number` — numeric input clamped to `min`/`max` as it is typed.
+     * - `linesList` — **stored as an array of strings, edited as one per
+     *   line.** Telegram's poll options. The cousin of Contacts' `csvList`,
+     *   split on newlines instead of commas. A renderer that treats it as text
+     *   turns the array into a string on the first save and `sendPoll` starts
+     *   failing.
+     */
+    type: 'string' | 'text' | 'select' | 'boolean' | 'number' | 'linesList';
+    /** Required by the operation. Metadata — the form does not gate on it. */
+    required?: boolean;
+    /** Help text under the control. Absent where the form shows none. */
+    description?: string;
+    /** Hint shown inside the input. May contain newlines for `linesList`. */
+    placeholder?: string;
+    /**
+     * Value to show when the stored one is `undefined`.
+     *
+     * `includeDisapprove`, `isAnonymous` and `parseMode` all have one, and the
+     * first two default to **true**: the stored config only ever holds `false`
+     * when the user turned them off. `config[name] ?? default` reproduces that
+     * exactly; `!!config[name]` does not, and getting it wrong strips the
+     * Disapprove button off every approval flow that already exists.
+     */
+    default?: string | number | boolean;
+    /** `select` only — the fixed option list, in display order. */
+    options?: string[];
+    /** `number` only — the input clamps to these while typing. */
+    min?: number;
+    max?: number;
+    /** `text` only — height of the textarea. */
+    rows?: number;
+    /**
+     * Renders side by side with the next field in a two-column row. Only the
+     * Approve / Disapprove button labels use it — they are one decision split
+     * in two, and stacking them reads as two unrelated fields.
+     */
+    pairedWithNext?: boolean;
+}
+export interface TelegramOperationSpec {
+    /** UI label for the operation picker card. */
+    label: string;
+    /** Sub-line under the label in the picker. */
+    description: string;
+    /** Bot API method the operation maps to (core.telegram.org/bots/api). */
+    apiMethod: string;
+    /**
+     * The op accepts `reply_markup`, so the page offers the inline-keyboard
+     * builder for it. Used to live as a hardcoded array of five strings in the
+     * detail page. `sendAndWaitForResponse` is deliberately absent: it builds
+     * its own Approve / Disapprove keyboard and a second one would collide.
+     */
+    supportsInlineKeyboard?: boolean;
+    /** Parameter schema. Order matters for form rendering. */
+    params: TelegramParamSpec[];
+}
+export declare const TELEGRAM_OPERATION_SPECS: Record<TelegramOperation, TelegramOperationSpec>;

package/dist/esm/telegram-operations.js

@@ -0,0 +1,351 @@
+/**
+ * Telegram Bot API operation enum — single source of truth across the API,
+ * Dashboard, and any future consumers (Message Broker, MCP server). Used by:
+ *   - telegramAction entity / DTO (api): operation field + validation
+ *   - dashboard TelegramAction operation picker
+ *   - MCP toolkit-specs expansion (one aiEnabled telegramAction → N tools)
+ *
+ * Phase 1 covers the eight ops that handle ~95% of bot send use cases.
+ * Phase 2 candidates (sendMediaGroup, voice/video uploads, chat admin,
+ * setMyCommands, message reactions, inline-mode answers) get added by
+ * extending this list, bumping the package, and re-installing in
+ * consumers — same pattern as Gmail / Calendar / Drive.
+ */
+export const TELEGRAM_OPERATIONS = [
+    'sendMessage',
+    'replyToMessage',
+    'sendPhoto',
+    'sendDocument',
+    'sendVoice',
+    // Pause-the-pipeline op — sends a Telegram message with Approve /
+    // (optional) Disapprove inline buttons and waits for the recipient to
+    // tap one. When `allowFreeText` is on, a text reply in the same chat
+    // also resolves the wait. Backed by the same shared PendingApproval +
+    // send-and-wait infra emailAction uses, with a Telegram-specific
+    // resume path through triggers.processTelegramPush (intercepts
+    // callback_query.data === "swat:{token}:a|r" before normal dispatch).
+    // Output of the node carries `payload._waitResponse = { approved,
+    // decidedAt, ipAddress, comment?, responseText?, timedOut? }` for
+    // downstream Conditional nodes.
+    'sendAndWaitForResponse',
+    'editMessageText',
+    'deleteMessage',
+    'answerCallbackQuery',
+    'forwardMessage',
+    'sendPoll',
+];
+/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
+export function isTelegramOperation(value) {
+    return (typeof value === 'string' &&
+        TELEGRAM_OPERATIONS.includes(value));
+}
+/* Los campos que se repiten entre operaciones. Fábricas y no constantes
+   compartidas: cada op recibe su propia copia y puede cambiarle la etiqueta o
+   la ayuda sin tocar a las demás. */
+const chatId = () => ({
+    name: 'chatId',
+    label: 'Chat ID',
+    type: 'string',
+    required: true,
+    description: 'Numeric chat id (from a Telegram trigger payload — usually {{payload.chatId}}) or @channelusername.',
+    placeholder: '{{payload.chatId}}',
+});
+const parseMode = (description) => ({
+    name: 'parseMode',
+    label: 'Parse mode',
+    type: 'select',
+    options: ['HTML', 'MarkdownV2', 'none'],
+    // Se enseña como VALOR, no como placeholder: el campo sale relleno con HTML
+    // aunque nunca se haya guardado nada.
+    default: 'HTML',
+    ...(description ? { description } : {}),
+});
+const messageId = (label, description, placeholder = '{{payload.messageId}}') => ({
+    name: 'messageId',
+    label,
+    type: 'string',
+    required: true,
+    placeholder,
+    ...(description ? { description } : {}),
+});
+const caption = (description, rows) => ({
+    name: 'caption',
+    label: 'Caption',
+    type: 'text',
+    rows,
+    description,
+    placeholder: rows > 2 ? 'Optional caption' : 'Optional',
+});
+export const TELEGRAM_OPERATION_SPECS = {
+    sendMessage: {
+        label: 'Send message',
+        description: 'Text reply with optional inline keyboard',
+        apiMethod: 'POST /sendMessage',
+        supportsInlineKeyboard: true,
+        params: [
+            chatId(),
+            {
+                name: 'text',
+                label: 'Text',
+                type: 'text',
+                required: true,
+                rows: 4,
+                description: 'Message body. HTML by default — escape <, >, & in user-supplied content.',
+                placeholder: 'Hi {{payload.fromUsername}}, thanks for your message!',
+            },
+            parseMode('HTML / MarkdownV2 / none.'),
+            {
+                name: 'replyToMessageId',
+                label: 'Reply to message ID',
+                type: 'string',
+                description: "Optional. Numeric id of the message you're replying to. For a fully-required quote-reply, use the dedicated 'Reply to message' op instead.",
+                placeholder: '{{payload.messageId}}',
+            },
+        ],
+    },
+    replyToMessage: {
+        label: 'Reply to message',
+        description: "Quote-reply with the threaded indicator above the bot's message",
+        apiMethod: 'POST /sendMessage (reply_to_message_id)',
+        supportsInlineKeyboard: true,
+        params: [
+            chatId(),
+            messageId('Message ID to reply to', "Numeric id of the user message you're quote-replying to. From a Telegram trigger this is typically {{payload.message.message_id}}.", '{{payload.message.message_id}}'),
+            {
+                name: 'text',
+                label: 'Text',
+                type: 'text',
+                required: true,
+                rows: 4,
+                description: 'Reply body. HTML by default — escape <, >, & in user-supplied content.',
+                placeholder: 'Yes, I understood your question about {{payload.text}}',
+            },
+            parseMode('HTML / MarkdownV2 / none.'),
+        ],
+    },
+    sendPhoto: {
+        label: 'Send photo',
+        description: 'Image by URL or _file ref',
+        apiMethod: 'POST /sendPhoto',
+        supportsInlineKeyboard: true,
+        params: [
+            chatId(),
+            {
+                name: 'photo',
+                label: 'Photo URL or file_id',
+                type: 'string',
+                required: true,
+                description: 'Public URL Telegram can fetch, or a file_id from a prior send.',
+                placeholder: '{{payload.attachment._file.downloadUrl}}',
+            },
+            caption('Optional. HTML supported. Max 1024 chars.', 3),
+        ],
+    },
+    sendDocument: {
+        label: 'Send document',
+        description: 'File of any type by URL',
+        apiMethod: 'POST /sendDocument',
+        supportsInlineKeyboard: true,
+        params: [
+            chatId(),
+            {
+                name: 'document',
+                label: 'Document URL or file_id',
+                type: 'string',
+                required: true,
+                description: 'Public URL or file_id. Max 50MB when fetching by URL.',
+                placeholder: '{{payload.file._file.downloadUrl}}',
+            },
+            caption('Optional. HTML supported.', 2),
+        ],
+    },
+    sendVoice: {
+        label: 'Send voice',
+        description: 'Send a voice bubble — pass a URL / file_id (or chain from the AI Node synthesize_voice tool)',
+        apiMethod: 'POST /sendVoice',
+        params: [
+            chatId(),
+            {
+                name: 'voice',
+                label: 'Voice URL or file_id',
+                type: 'string',
+                required: true,
+                description: 'OGG/OPUS audio URL Telegram can fetch, or a file_id from a prior /sendVoice for cheap re-sends. To synthesize from text, add the AI Node `synthesize_voice` tool (Tools tab → + Add → Voice synthesis) and pass its result here via `{{payload.voice}}` or chain through the LLM.',
+                placeholder: 'https://… .ogg  or  {{payload.voice}}',
+            },
+        ],
+    },
+    sendAndWaitForResponse: {
+        label: 'Send & wait for response',
+        description: 'Sends a message with Approve / Disapprove buttons (and optional free-text reply) — pipeline pauses until the user responds',
+        apiMethod: 'POST /sendMessage + PendingApproval',
+        params: [
+            chatId(),
+            {
+                name: 'text',
+                label: 'Message',
+                type: 'text',
+                required: true,
+                rows: 4,
+                description: 'Body of the prompt shown above the Approve / Disapprove buttons. HTML supported by default.',
+                placeholder: 'Approve the ${{payload.amount}} payment to {{payload.vendor}}?',
+            },
+            parseMode('HTML / MarkdownV2 / none.'),
+            {
+                name: 'approveLabel',
+                label: 'Approve button label',
+                type: 'string',
+                description: 'Tap = approved.',
+                placeholder: 'Approve',
+                pairedWithNext: true,
+            },
+            {
+                name: 'disapproveLabel',
+                label: 'Disapprove button label',
+                type: 'string',
+                description: "Tap = rejected. Hidden when 'Include disapprove' is off.",
+                placeholder: 'Reject',
+            },
+            {
+                name: 'includeDisapprove',
+                label: 'Include disapprove button',
+                type: 'boolean',
+                default: true,
+                description: 'Off = approval-only (single button). Default on.',
+            },
+            {
+                name: 'allowFreeText',
+                label: 'Allow free-text reply',
+                type: 'boolean',
+                default: false,
+                description: "When on, a plain text reply in the same chat also resolves the wait — _waitResponse.responseText carries the typed message. Useful for capturing context ('approved with comment'). Default off.",
+            },
+            {
+                name: 'timeoutMinutes',
+                label: 'Timeout (minutes)',
+                type: 'number',
+                min: 1,
+                max: 20160,
+                default: 1440,
+                description: 'Pipeline auto-resumes (rejected) after this many minutes if no response. Default 1440 (24h).',
+            },
+        ],
+    },
+    editMessageText: {
+        label: 'Edit message',
+        description: 'Replace text of a previously-sent message',
+        apiMethod: 'POST /editMessageText',
+        supportsInlineKeyboard: true,
+        params: [
+            chatId(),
+            messageId('Message ID', 'Id of the message to edit (from a prior sendMessage result).'),
+            {
+                name: 'text',
+                label: 'New text',
+                type: 'text',
+                required: true,
+                rows: 3,
+                description: 'Replacement text for the message.',
+                placeholder: 'Updated content',
+            },
+            // Sin ayuda a propósito: es la única op donde el formulario nunca la ha
+            // enseñado, y no me invento copy nueva al mudar el campo.
+            parseMode(),
+        ],
+    },
+    deleteMessage: {
+        label: 'Delete message',
+        description: 'Remove a message from a chat',
+        apiMethod: 'POST /deleteMessage',
+        params: [
+            chatId(),
+            messageId('Message ID', 'Id of the message to delete.'),
+        ],
+    },
+    answerCallbackQuery: {
+        label: 'Answer callback',
+        description: 'Acknowledge an inline-button press (REQUIRED after callback_query)',
+        apiMethod: 'POST /answerCallbackQuery',
+        params: [
+            {
+                name: 'callbackQueryId',
+                label: 'Callback query ID',
+                type: 'string',
+                required: true,
+                description: 'From the trigger payload — usually {{payload.callbackQueryId}} when responding to an inline-button press.',
+                placeholder: '{{payload.callbackQueryId}}',
+            },
+            {
+                name: 'text',
+                label: 'Text',
+                type: 'string',
+                description: 'Optional. Toast (or alert if showAlert is on). Max 200 chars.',
+                placeholder: 'Saved!',
+            },
+            {
+                name: 'showAlert',
+                label: 'Show as alert',
+                type: 'boolean',
+                default: false,
+                description: 'When on, shows a modal alert above the chat instead of a toast.',
+            },
+        ],
+    },
+    forwardMessage: {
+        label: 'Forward message',
+        description: 'Forward an existing message to another chat',
+        apiMethod: 'POST /forwardMessage',
+        // Las tres sin ayuda: las etiquetas ya dicen cuál es cuál, y así estaba.
+        params: [
+            {
+                name: 'chatId',
+                label: 'Destination chat ID',
+                type: 'string',
+                required: true,
+                placeholder: '{{payload.targetChatId}}',
+            },
+            {
+                name: 'fromChatId',
+                label: 'Source chat ID',
+                type: 'string',
+                required: true,
+                placeholder: '{{payload.chatId}}',
+            },
+            messageId('Source message ID'),
+        ],
+    },
+    sendPoll: {
+        label: 'Send poll',
+        description: 'Multi-option poll (regular or quiz)',
+        apiMethod: 'POST /sendPoll',
+        params: [
+            chatId(),
+            {
+                name: 'question',
+                label: 'Question',
+                type: 'text',
+                required: true,
+                rows: 2,
+                description: 'Max 300 chars.',
+                placeholder: 'Which option?',
+            },
+            {
+                name: 'options',
+                label: 'Options (2-10)',
+                type: 'linesList',
+                required: true,
+                rows: 5,
+                description: 'One per line. Max 100 chars each.',
+                placeholder: 'Option A\nOption B\nOption C',
+            },
+            {
+                name: 'isAnonymous',
+                label: 'Anonymous',
+                type: 'boolean',
+                // Defecto ENCENDIDO, como includeDisapprove.
+                default: true,
+                description: 'Default true. Set false to expose voter identities.',
+            },
+        ],
+    },
+};

package/dist/esm/telegram-toolkit.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Telegram AI Toolkit — las herramientas que un telegramAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez**, como el de Sheets. Antes vivía dos veces: una
+ * copia en `dashboard/components/telegram-actions/telegram-operations-schemas.ts`
+ * y otra en `api/src/mcp-servers/toolkit-specs.ts`, las dos a mano, las dos con
+ * el mismo TODO escrito pidiendo justo esto. Y ya habían derivado: el
+ * `messageId` de `reply_telegram_message` era `number` en el dashboard y
+ * `string` en la api, mientras en las otras tres ops que lo llevan era `number`
+ * en las dos. Aquí es `number` y punto.
+ *
+ * Hay una TERCERA copia que también desaparece: la página de detalle pintaba la
+ * lista de las diez herramientas como diez `<li>` escritos a mano. Ahora sale de
+ * aquí, contada con `.length`, que es lo que evita que un día anuncie diez y
+ * exponga otra cosa.
+ *
+ * La forma es la que ya consume `toolkitSpecToMcpTool` en la api, para que pueda
+ * usarse sin adaptador. Los textos van en inglés porque los lee el modelo y
+ * quien mire la lista de herramientas del servidor MCP.
+ */
+import type { TelegramOperation } from './telegram-operations.js';
+export interface TelegramToolkitParameter {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    required: boolean;
+}
+export interface TelegramToolkitSpec {
+    operation: TelegramOperation;
+    /** Etiqueta corta de la fila en la lista de herramientas. */
+    label: string;
+    /**
+     * Nombre con el que el LLM llama a la herramienta. Lleva `_telegram_` para
+     * no chocar con el `send_email` de Gmail ni el `create_event` de Calendar
+     * cuando un mismo AI Node tiene varios toolkits encendidos.
+     */
+    toolName: string;
+    /** Descripción (más reglas de uso) que ve el LLM. */
+    description: string;
+    parameters: TelegramToolkitParameter[];
+    /**
+     * Encabezado de grupo para la lista de la página de detalle. Las filas
+     * consecutivas que comparten grupo se pintan bajo un único título, así que el
+     * ORDEN de este array es el que agrupa. Es el mismo que enseñaba el JSX que
+     * sustituye.
+     */
+    group?: string;
+}
+export declare const TELEGRAM_TOOLKIT_SPECS: TelegramToolkitSpec[];
+/** Las herramientas por nombre, para despachar una llamada del modelo. */
+export declare const TELEGRAM_TOOLKIT_BY_TOOL_NAME: Record<string, TelegramToolkitSpec>;