@hostwebhook/node-types 1.52.9 → 1.52.11

package/dist/index.d.ts

@@ -11,8 +11,10 @@ export { GOOGLE_CALENDAR_OPERATIONS, isGoogleCalendarOperation, } from './calend
 export type { GoogleCalendarOperation } from './calendar-operations';
 export { DRIVE_OPERATIONS, isDriveOperation, } from './drive-operations';
 export type { DriveOperation } from './drive-operations';
-export { TELEGRAM_OPERATIONS, isTelegramOperation, } from './telegram-operations';
-export type { TelegramOperation } from './telegram-operations';
+export { TELEGRAM_OPERATIONS, TELEGRAM_OPERATION_SPECS, isTelegramOperation, } from './telegram-operations';
+export type { TelegramOperation, TelegramParamSpec, TelegramOperationSpec, } from './telegram-operations';
+export { TELEGRAM_TOOLKIT_SPECS, TELEGRAM_TOOLKIT_BY_TOOL_NAME, } from './telegram-toolkit';
+export type { TelegramToolkitSpec, TelegramToolkitParameter, } from './telegram-toolkit';
 export { WHATSAPP_OPERATIONS, isWhatsAppOperation, } from './whatsapp-operations';
 export type { WhatsAppOperation } from './whatsapp-operations';
 export { DISCORD_OPERATIONS, DISCORD_OPERATION_SPECS, isDiscordOperation, } from './discord-operations';

package/dist/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GOOGLE_CONTACTS_DEFAULT_PERSON_FIELDS = exports.GOOGLE_CONTACTS_OPERATION_GROUPS = exports.GOOGLE_CONTACTS_OPERATION_SPECS = exports.GOOGLE_CONTACTS_OPERATIONS_V2 = exports.GOOGLE_CONTACTS_OPERATIONS_V1 = exports.GOOGLE_CONTACTS_OPERATIONS = exports.SHEETS_TOOLKIT_DEFAULTABLE = exports.SHEETS_TOOLKIT_BY_TOOL_NAME = exports.SHEETS_TOOLKIT_SPECS = exports.isSheetsOperation = exports.SHEETS_OPERATION_SPECS = exports.SHEETS_OPERATIONS = exports.isSlackOperation = exports.SLACK_OPERATION_SPECS = exports.SLACK_OPERATIONS = exports.isDiscordOperation = exports.DISCORD_OPERATION_SPECS = exports.DISCORD_OPERATIONS = exports.isWhatsAppOperation = exports.WHATSAPP_OPERATIONS = exports.isTelegramOperation = exports.TELEGRAM_OPERATIONS = exports.isDriveOperation = exports.DRIVE_OPERATIONS = exports.isGoogleCalendarOperation = exports.GOOGLE_CALENDAR_OPERATIONS = exports.isGmailOperation = exports.GMAIL_OPERATIONS = exports.NODE_TYPE_TO_PREFIX = exports.PREFIX_TO_NODE_TYPE = exports.NODE_STATE_KEYS = exports.NODE_COLORS = exports.NODE_DETAIL_PATHS = exports.getNodeRegistryEntry = exports.NODE_REGISTRY = exports.getNodeDispatchConfig = exports.getAllNodeCollections = exports.NODE_DISPATCH = exports.resolveNodeId = exports.PREFIX_TO_TYPE = exports.NODE_UI = exports.ALL_NODE_TYPES = exports.isNodeType = exports.isTerminal = exports.canSendToNodes = exports.canReceiveFromNodes = exports.canReceiveFrom = exports.NODE_CONNECTIONS = exports.iterableMeta = exports.singleMeta = void 0;
-exports.isCredentialType = exports.getCredentialType = exports.credentialTypeValues = exports.CREDENTIAL_TYPE_VALUES = exports.CREDENTIAL_TYPES = exports.isGoogleContactsOperation = void 0;
+exports.GOOGLE_CONTACTS_OPERATIONS_V2 = exports.GOOGLE_CONTACTS_OPERATIONS_V1 = exports.GOOGLE_CONTACTS_OPERATIONS = exports.SHEETS_TOOLKIT_DEFAULTABLE = exports.SHEETS_TOOLKIT_BY_TOOL_NAME = exports.SHEETS_TOOLKIT_SPECS = exports.isSheetsOperation = exports.SHEETS_OPERATION_SPECS = exports.SHEETS_OPERATIONS = exports.isSlackOperation = exports.SLACK_OPERATION_SPECS = exports.SLACK_OPERATIONS = exports.isDiscordOperation = exports.DISCORD_OPERATION_SPECS = exports.DISCORD_OPERATIONS = exports.isWhatsAppOperation = exports.WHATSAPP_OPERATIONS = exports.TELEGRAM_TOOLKIT_BY_TOOL_NAME = exports.TELEGRAM_TOOLKIT_SPECS = exports.isTelegramOperation = exports.TELEGRAM_OPERATION_SPECS = exports.TELEGRAM_OPERATIONS = exports.isDriveOperation = exports.DRIVE_OPERATIONS = exports.isGoogleCalendarOperation = exports.GOOGLE_CALENDAR_OPERATIONS = exports.isGmailOperation = exports.GMAIL_OPERATIONS = exports.NODE_TYPE_TO_PREFIX = exports.PREFIX_TO_NODE_TYPE = exports.NODE_STATE_KEYS = exports.NODE_COLORS = exports.NODE_DETAIL_PATHS = exports.getNodeRegistryEntry = exports.NODE_REGISTRY = exports.getNodeDispatchConfig = exports.getAllNodeCollections = exports.NODE_DISPATCH = exports.resolveNodeId = exports.PREFIX_TO_TYPE = exports.NODE_UI = exports.ALL_NODE_TYPES = exports.isNodeType = exports.isTerminal = exports.canSendToNodes = exports.canReceiveFromNodes = exports.canReceiveFrom = exports.NODE_CONNECTIONS = exports.iterableMeta = exports.singleMeta = void 0;
+exports.isCredentialType = exports.getCredentialType = exports.credentialTypeValues = exports.CREDENTIAL_TYPE_VALUES = exports.CREDENTIAL_TYPES = exports.isGoogleContactsOperation = exports.GOOGLE_CONTACTS_DEFAULT_PERSON_FIELDS = exports.GOOGLE_CONTACTS_OPERATION_GROUPS = exports.GOOGLE_CONTACTS_OPERATION_SPECS = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "singleMeta", { enumerable: true, get: function () { return types_1.singleMeta; } });
 Object.defineProperty(exports, "iterableMeta", { enumerable: true, get: function () { return types_1.iterableMeta; } });
@@ -44,7 +44,11 @@ Object.defineProperty(exports, "DRIVE_OPERATIONS", { enumerable: true, get: func
 Object.defineProperty(exports, "isDriveOperation", { enumerable: true, get: function () { return drive_operations_1.isDriveOperation; } });
 var telegram_operations_1 = require("./telegram-operations");
 Object.defineProperty(exports, "TELEGRAM_OPERATIONS", { enumerable: true, get: function () { return telegram_operations_1.TELEGRAM_OPERATIONS; } });
+Object.defineProperty(exports, "TELEGRAM_OPERATION_SPECS", { enumerable: true, get: function () { return telegram_operations_1.TELEGRAM_OPERATION_SPECS; } });
 Object.defineProperty(exports, "isTelegramOperation", { enumerable: true, get: function () { return telegram_operations_1.isTelegramOperation; } });
+var telegram_toolkit_1 = require("./telegram-toolkit");
+Object.defineProperty(exports, "TELEGRAM_TOOLKIT_SPECS", { enumerable: true, get: function () { return telegram_toolkit_1.TELEGRAM_TOOLKIT_SPECS; } });
+Object.defineProperty(exports, "TELEGRAM_TOOLKIT_BY_TOOL_NAME", { enumerable: true, get: function () { return telegram_toolkit_1.TELEGRAM_TOOLKIT_BY_TOOL_NAME; } });
 var whatsapp_operations_1 = require("./whatsapp-operations");
 Object.defineProperty(exports, "WHATSAPP_OPERATIONS", { enumerable: true, get: function () { return whatsapp_operations_1.WHATSAPP_OPERATIONS; } });
 Object.defineProperty(exports, "isWhatsAppOperation", { enumerable: true, get: function () { return whatsapp_operations_1.isWhatsAppOperation; } });

package/dist/sheets-toolkit.js

@@ -96,11 +96,19 @@ exports.SHEETS_TOOLKIT_SPECS = [
         operation: 'createSpreadsheet',
         label: 'Create spreadsheet',
         toolName: 'create_spreadsheet',
-        description: 'Create a new, empty Google Sheets document and return its id and URL. It writes no data: to fill it, call append_row afterwards with the id it returns.',
-        parameters: [
-            p('title', 'Name of the new document.'),
-            p('folderId', 'Id of the Drive folder to create it in. Left out, it lands in the root of My Drive.', false),
-        ],
+        description: "Create a new, empty Google Sheets document and return its id and URL. It writes no data: to fill it, call append_row afterwards with the id it returns. It lands wherever the node's Save Location says — you do not choose that.",
+        /*
+         * Sin `folderId` a propósito, y esta es la excepción a «defecto del nodo que
+         * el modelo puede cambiar».
+         *
+         * La hoja sí se le ofrece porque el modelo tiene de dónde sacar un id: se lo
+         * dice quien escribe, o lo devuelve un get_rows. Un id de carpeta de Drive
+         * no: no hay ninguna herramienta aquí que las liste, así que sólo podría
+         * inventárselo, y un id inventado falla mientras uno real acertado por
+         * casualidad escribe en la carpeta de otro. La carpeta la elige la persona
+         * en el nodo, y la api la aplica.
+         */
+        parameters: [p('title', 'Name of the new document.')],
         destructive: true,
     },
 ];

package/dist/telegram-operations.d.ts

@@ -15,3 +15,90 @@ export declare const TELEGRAM_OPERATIONS: readonly ["sendMessage", "replyToMessa
 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/telegram-operations.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TELEGRAM_OPERATIONS = void 0;
+exports.TELEGRAM_OPERATION_SPECS = exports.TELEGRAM_OPERATIONS = void 0;
 exports.isTelegramOperation = isTelegramOperation;
 /**
  * Telegram Bot API operation enum — single source of truth across the API,
@@ -43,3 +43,313 @@ function isTelegramOperation(value) {
     return (typeof value === 'string' &&
         exports.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',
+});
+exports.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/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';
+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>;

package/dist/telegram-toolkit.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEGRAM_TOOLKIT_BY_TOOL_NAME = exports.TELEGRAM_TOOLKIT_SPECS = void 0;
+const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
+/*
+ * `sendAndWaitForResponse` NO está aquí, y es una decisión, no un olvido: la op
+ * para el pipeline durante minutos u horas esperando que alguien pulse un botón,
+ * y por la vía de una herramienta no espera — el modelo recibe algo inmediato y
+ * acaba diciendo que ya se aprobó. Se usa en modo single-op, con un Conditional
+ * detrás leyendo `_waitResponse.approved`. La espera se resuelve por
+ * `service-triggers.processTelegramPush`, donde el LLM no participa.
+ *
+ * Ninguna lleva `destructive`. `delete_telegram_message` lo merecería —el
+ * toolkit de Drive marca sus borrados— pero hoy la spec de Telegram no tiene ese
+ * campo en ninguna de las dos capas, y añadirlo cambiaría cuándo el AI Node pide
+ * confirmación. Eso es otra decisión, no parte de mudar el esquema de sitio.
+ */
+exports.TELEGRAM_TOOLKIT_SPECS = [
+    {
+        operation: 'sendMessage',
+        label: 'Send message',
+        toolName: 'send_telegram_message',
+        group: 'Sending',
+        description: 'Send a text message via the Telegram bot to a chat. Use for replies, notifications, status updates, or any text-only delivery. ' +
+            'Supports HTML formatting (default parse mode). For inline buttons, supply the replyMarkup arg as a 2D array of buttons. ' +
+            'USAGE RULES: ' +
+            '(1) chatId is REQUIRED — when replying inside a flow triggered by a Telegram message, this is normally `{{payload.chatId}}` from the trigger payload. ' +
+            '(2) Telegram caps text at 4096 chars. Split longer messages or use sendDocument with a text file. ' +
+            '(3) For a quote-style reply that points at a SPECIFIC user message, prefer `reply_telegram_message` so Telegram renders the threaded indicator — this op sends a standalone message.',
+        parameters: [
+            p('chatId', 'Target chat id (number) or @channelusername (string).'),
+            p('text', 'Message text. HTML by default — escape <, >, & in user content.'),
+            p('parseMode', 'Optional. "HTML" (default), "MarkdownV2", or "none".', false),
+            p('replyToMessageId', 'Optional. Reply to a specific message id.', false),
+        ],
+    },
+    {
+        operation: 'replyToMessage',
+        label: 'Reply to message',
+        toolName: 'reply_telegram_message',
+        group: 'Sending',
+        description: 'Reply to a SPECIFIC user message with the quote indicator visible. Telegram renders the bot\'s reply with a small "replying to..." card above it pointing back at the quoted message. ' +
+            'USAGE RULES: ' +
+            '(1) Use this in group chats where multiple users post in parallel — the indicator makes it clear which user the bot is answering. In 1:1 DMs only use it when context disambiguates between several recent questions. ' +
+            '(2) messageId is REQUIRED — pass the id of the user\'s message you\'re responding to (typically `{{payload.message.message_id}}` or `{{payload.message_id}}` from the trigger). ' +
+            '(3) chatId is REQUIRED and must match the chat the original message lives in. ' +
+            '(4) Same Telegram /sendMessage webhook underneath — text limit (4096 chars) and parse modes (HTML / MarkdownV2 / none) work the same.',
+        parameters: [
+            p('chatId', 'Target chat id (number) or @channelusername — must match the chat of the quoted message.'),
+            // `number`, como en las otras tres ops que llevan messageId. La api lo
+            // declaraba `string` por un cuarto argumento que se quedó sin escribir.
+            p('messageId', 'Numeric id of the message to quote-reply to. Telegram renders the threaded indicator from this.', true, 'number'),
+            p('text', 'Reply text. HTML by default.'),
+            p('parseMode', 'Optional. "HTML" (default), "MarkdownV2", or "none".', false),
+        ],
+    },
+    {
+        operation: 'sendPhoto',
+        label: 'Send photo',
+        toolName: 'send_telegram_photo',
+        group: 'Sending',
+        description: 'Send a photo to a chat. The photo arg accepts a public URL (Telegram fetches it) or a Telegram file_id from a previously-sent photo (cheap re-send). ' +
+            'For HW-stored files use the `_file.downloadUrl` template. Max 10MB photo size when fetching by URL. Caption is optional and supports HTML.',
+        parameters: [
+            p('chatId', 'Target chat id or @channelusername.'),
+            p('photo', "Public URL OR file_id from a prior send. URLs must be reachable from Telegram's servers."),
+            p('caption', 'Optional caption (max 1024 chars, HTML supported).', false),
+            p('parseMode', 'Optional caption parse mode: HTML / MarkdownV2 / none.', false),
+        ],
+    },
+    {
+        operation: 'sendDocument',
+        label: 'Send document',
+        toolName: 'send_telegram_document',
+        group: 'Sending',
+        description: 'Send a document (any file type) to a chat. Same URL-or-file_id contract as sendPhoto. Max 50MB when Telegram fetches by URL.',
+        parameters: [
+            p('chatId', 'Target chat id or @channelusername.'),
+            p('document', 'Public URL OR file_id.'),
+            p('caption', 'Optional caption (HTML supported).', false),
+            p('parseMode', 'Optional caption parse mode.', false),
+        ],
+    },
+    {
+        operation: 'sendVoice',
+        label: 'Send voice',
+        toolName: 'send_telegram_voice',
+        group: 'Sending',
+        description: 'Send a voice message — Telegram renders it as a voice bubble with waveform. ' +
+            'USAGE RULES: ' +
+            '(1) chatId is REQUIRED — usually `{{payload.chatId}}` from the trigger. ' +
+            '(2) voice is REQUIRED — pass an OGG/OPUS audio URL Telegram can fetch, OR a `file_id` from a prior /sendVoice for cheap re-sends. ' +
+            '(3) To synthesize from text, FIRST call the `synthesize_voice` tool — it returns a JSON `_file` ref; pass its `downloadUrl` string here as `voice`. NEVER pass the raw `_file` object; Telegram needs a string. ' +
+            '(4) Use this when the user sent voice and wants voice back, or when the operator framed the bot as voice-first. For text replies prefer send_telegram_message.',
+        parameters: [
+            p('chatId', 'Target chat id (number) or @channelusername.'),
+            p('voice', 'OGG/OPUS audio URL or Telegram file_id. Use the `downloadUrl` returned by synthesize_voice when chaining from text.'),
+        ],
+    },
+    {
+        operation: 'sendPoll',
+        label: 'Send poll',
+        toolName: 'send_telegram_poll',
+        group: 'Sending',
+        description: 'Send a poll to a chat. The options arg is an array of strings (2-10 options). For quiz-style polls (single correct answer), pass type="quiz" and a numeric correctOptionId. Polls require group/supergroup/channel chats — DMs reject them.',
+        parameters: [
+            p('chatId', 'Target chat id.'),
+            p('question', 'Poll question (max 300 chars).'),
+            p('options', 'Array of 2-10 answer strings. Pass as a JSON array: ["Option A","Option B"]. Each option max 100 chars.'),
+            p('isAnonymous', 'Optional. Default true. Set false to expose voter identities.', false, 'boolean'),
+            p('type', 'Optional. "regular" (default) or "quiz".', false),
+            p('correctOptionId', 'Required when type="quiz" — zero-indexed correct answer.', false, 'number'),
+        ],
+    },
+    {
+        operation: 'forwardMessage',
+        label: 'Forward message',
+        toolName: 'forward_telegram_message',
+        group: 'Sending',
+        description: 'Forward an existing message from one chat to another. Preserves the original sender attribution. Use for announcements, escalations, or copying a message between groups the bot is in.',
+        parameters: [
+            p('chatId', 'Destination chat id.'),
+            p('fromChatId', 'Source chat id.'),
+            p('messageId', 'Source message id.', true, 'number'),
+        ],
+    },
+    {
+        operation: 'editMessageText',
+        label: 'Edit message text',
+        toolName: 'edit_telegram_message',
+        group: 'Modify / acknowledge',
+        description: 'Replace the text of a previously-sent message. Use for progress updates, fixing typos, removing inline buttons after a press. The bot can only edit messages it sent within the last 48h.',
+        parameters: [
+            p('chatId', 'Chat id of the message.'),
+            p('messageId', 'Message id to edit (returned from a prior sendMessage).', true, 'number'),
+            p('text', 'New text for the message.'),
+            p('parseMode', 'Optional parse mode.', false),
+        ],
+    },
+    {
+        operation: 'deleteMessage',
+        label: 'Delete message',
+        toolName: 'delete_telegram_message',
+        group: 'Modify / acknowledge',
+        description: 'Delete a message. Bots can delete their own messages anytime; messages by users only when the bot has Delete Messages admin permission in that chat. Within 48h for bot-own messages in private chats.',
+        parameters: [
+            p('chatId', 'Chat id where the message lives.'),
+            p('messageId', 'Message id to delete.', true, 'number'),
+        ],
+    },
+    {
+        operation: 'answerCallbackQuery',
+        label: 'Answer callback query',
+        toolName: 'answer_telegram_callback',
+        group: 'Modify / acknowledge',
+        description: 'REQUIRED after a callback_query trigger fires (an inline-keyboard button press) — without this, the user sees a forever-spinner on the button. The text optionally shows as a toast or alert above the chat.',
+        parameters: [
+            p('callbackQueryId', 'The callback_query.id from the trigger payload — usually `{{payload.callbackQueryId}}`.'),
+            p('text', 'Optional toast/alert text shown to the user (max 200 chars).', false),
+            p('showAlert', 'Optional. true = modal alert; false (default) = toast notification.', false, 'boolean'),
+        ],
+    },
+];
+/** Las herramientas por nombre, para despachar una llamada del modelo. */
+exports.TELEGRAM_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(exports.TELEGRAM_TOOLKIT_SPECS.map((s) => [s.toolName, s]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/node-types",
-  "version": "1.52.9",
+  "version": "1.52.11",
   "description": "Shared node type definitions, connection rules, and dispatch config for HostWebhook",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",