@hostwebhook/node-types 1.52.10 → 1.52.12

package/dist/drive-operations.d.ts

@@ -20,3 +20,84 @@ export declare const DRIVE_OPERATIONS: readonly ["upload", "download", "copy", "
 export type DriveOperation = (typeof DRIVE_OPERATIONS)[number];
 /** Type guard — useful when validating untrusted input (DTOs, tool calls). */
 export declare function isDriveOperation(value: unknown): value is DriveOperation;
+export type DriveParamType = 
+/** Live file picker (needs a credential) + templated paste. */
+'driveFile'
+/** Text input with `{{payload.*}}` autocomplete. */
+ | 'template'
+/** Plain `<select>`; the labels are not the values, so `options` is required. */
+ | 'select'
+/**
+ * Searchable mime-type dropdown. The option list is long and shared with
+ * other screens, so it stays in the dashboard (`lib/drive-mime-options`)
+ * and the schema only says "this field is a mime picker".
+ */
+ | 'mimeSelect' | 'number'
+/**
+ * A `<select>` whose values are `''` / `'true'` / `'false'` but which is
+ * stored as a BOOLEAN, or omitted entirely when `''`.
+ *
+ * This is the shape that keeps `starred` honest: the api applies it with
+ * `typeof config.starred === 'boolean'`, so "— don't change —" has to mean
+ * *no key at all*. A plain Switch cannot express that third state, and
+ * storing `''` or `'false'` would silently stop the star from ever changing.
+ */
+ | 'booleanSelect'
+/**
+ * Full-width explainer card that toggles: icon, title, prose and bullets,
+ * with the switch on the right. The card's rich body is JSX, so it lives in
+ * the page keyed by param name — the schema only declares the field.
+ */
+ | 'switchCard'
+/** Live multi-select of the starting folder's immediate children. */
+ | 'driveSubfolders';
+export interface DriveParamSpec {
+    /** The `operationConfig` key. This is what the api reads — not a UI name. */
+    name: string;
+    label: string;
+    type: DriveParamType;
+    required?: boolean;
+    /**
+     * Help text under the field. Plain text on purpose: the package holds no
+     * React, so the `<code>` spans the page used to have are gone. Deliberate.
+     */
+    description?: string;
+    placeholder?: string;
+    /** Prefilled when the saved config has no value for this key. */
+    default?: string | number;
+    /** Required for `select` and `booleanSelect` — label and value differ. */
+    options?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    min?: number;
+    max?: number;
+    /**
+     * Renders in the "Advanced" tab instead of "Config". The page used to keep
+     * a two-name `ADVANCED_FIELDS` array while the advanced *tab* actually held
+     * four fields, so `recursive` and `subfolderIds` only showed up because
+     * `list` happened to also carry one of the two named fields. Marking all
+     * four here removes that coincidence.
+     */
+    advanced?: boolean;
+    /**
+     * Only shown when a sibling field holds one of these values. No other node's
+     * schema needed this yet; Drive has three cases (the two share targets and
+     * the subfolder scope).
+     */
+    showWhen?: {
+        field: string;
+        in: ReadonlyArray<string>;
+    };
+}
+export interface DriveOperationSpec {
+    /** UI label for the operation dropdown row. */
+    label: string;
+    /** Sub-line under the label in the dropdown. */
+    description: string;
+    /** Drive API method it maps to (developers.google.com/drive/api/reference). */
+    apiMethod: string;
+    /** Parameter schema. Order matters: it is the on-screen order. */
+    params: DriveParamSpec[];
+}
+export declare const DRIVE_OPERATION_SPECS: Record<DriveOperation, DriveOperationSpec>;

package/dist/drive-operations.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DRIVE_OPERATIONS = void 0;
+exports.DRIVE_OPERATION_SPECS = exports.DRIVE_OPERATIONS = void 0;
 exports.isDriveOperation = isDriveOperation;
 /**
  * Google Drive operation enum — single source of truth across the API,
@@ -38,3 +38,286 @@ exports.DRIVE_OPERATIONS = [
 function isDriveOperation(value) {
     return typeof value === 'string' && exports.DRIVE_OPERATIONS.includes(value);
 }
+/* Fábricas de los campos que se repiten, para que un cambio de copy no haya
+   que perseguirlo por doce operaciones. */
+const fileId = () => ({
+    name: 'fileId',
+    label: 'Drive File',
+    type: 'driveFile',
+    required: true,
+    description: 'Pick a file from Drive or paste a templated value like {{payload.driveFileId}}.',
+});
+const parentFolderId = () => ({
+    name: 'parentFolderId',
+    label: 'Parent Folder ID (override)',
+    type: 'template',
+    advanced: true,
+    placeholder: 'Empty = use Default Folder above',
+    description: "Folder id used for this operation only. Leave empty to use the action's Default Folder. Templates work — e.g. {{payload.folderId}}.",
+});
+/** El filtro por tipo de upload/list. En `export` el mismo `mimeType` es otra
+    cosa y se declara aparte. */
+const mimeTypeFilter = () => ({
+    name: 'mimeType',
+    label: 'File type filter (optional)',
+    type: 'mimeSelect',
+    description: 'Restrict the operation to files of this type. Leave as "Any" to match every file.',
+});
+const ORDER_BY_OPTIONS = [
+    { value: 'modifiedTime desc', label: 'Modified time (newest first)' },
+    { value: 'modifiedTime', label: 'Modified time (oldest first)' },
+    { value: 'createdTime desc', label: 'Created time (newest first)' },
+    { value: 'createdTime', label: 'Created time (oldest first)' },
+    { value: 'name', label: 'Name (A→Z)' },
+    { value: 'name desc', label: 'Name (Z→A)' },
+];
+const EXPORT_FORMAT_OPTIONS = [
+    { value: 'application/pdf', label: 'PDF (.pdf)' },
+    {
+        value: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        label: 'Word (.docx) — for Google Docs',
+    },
+    {
+        value: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        label: 'Excel (.xlsx) — for Google Sheets',
+    },
+    {
+        value: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        label: 'PowerPoint (.pptx) — for Google Slides',
+    },
+    { value: 'text/plain', label: 'Plain text (.txt)' },
+    { value: 'text/csv', label: 'CSV (.csv) — for Google Sheets' },
+    { value: 'text/html', label: 'HTML (.html)' },
+];
+exports.DRIVE_OPERATION_SPECS = {
+    upload: {
+        label: 'Upload File',
+        description: 'Stream a file from a payload _file ref into Drive',
+        apiMethod: 'files.create',
+        params: [
+            {
+                name: 'fileName',
+                label: 'Destination File Name',
+                type: 'template',
+                placeholder: '{{payload.name}} — leave blank to use _file.originalName',
+            },
+            {
+                name: 'sourceField',
+                label: 'Source Field (payload path)',
+                type: 'template',
+                placeholder: '_file',
+                default: '_file',
+                description: 'Where the _file ref lives in the incoming payload. Default _file. For nested refs use a dotted path (e.g. doc if upstream is { doc: { _file: ... } }).',
+            },
+            mimeTypeFilter(),
+            parentFolderId(),
+        ],
+    },
+    download: {
+        label: 'Download File',
+        description: 'Fetch a Drive file → payload _file ref for downstream nodes',
+        apiMethod: 'files.get (alt=media)',
+        params: [fileId()],
+    },
+    list: {
+        label: 'List / Search',
+        description: 'List or search files (iterable output)',
+        apiMethod: 'files.list',
+        params: [
+            {
+                name: 'query',
+                label: 'Search Query',
+                type: 'template',
+                placeholder: 'Substring to match against file names — empty = list all',
+            },
+            mimeTypeFilter(),
+            {
+                name: 'pageSize',
+                label: 'Max Results',
+                type: 'number',
+                min: 1,
+                max: 100,
+                default: 50,
+                description: 'Up to 100 per call. Output is iterable — downstream nodes process each file independently.',
+            },
+            {
+                name: 'orderBy',
+                label: 'Order By',
+                type: 'select',
+                default: 'modifiedTime desc',
+                options: ORDER_BY_OPTIONS,
+            },
+            parentFolderId(),
+            { name: 'recursive', label: 'Search subfolders too', type: 'switchCard', advanced: true },
+            {
+                name: 'subfolderIds',
+                label: 'Limit to specific subfolders',
+                type: 'driveSubfolders',
+                advanced: true,
+                showWhen: { field: 'recursive', in: ['true'] },
+            },
+            {
+                name: 'downloadResults',
+                label: 'Auto-download matching files',
+                type: 'switchCard',
+                advanced: true,
+            },
+        ],
+    },
+    get: {
+        label: 'Get Metadata',
+        description: 'Read metadata for one file (no bytes)',
+        apiMethod: 'files.get',
+        params: [fileId()],
+    },
+    copy: {
+        label: 'Copy File',
+        description: 'Duplicate a file, optionally rename and/or move',
+        apiMethod: 'files.copy',
+        params: [
+            fileId(),
+            {
+                name: 'newName',
+                label: 'New File Name',
+                type: 'template',
+                placeholder: "Optional — defaults to 'Copy of <original>'",
+            },
+            parentFolderId(),
+        ],
+    },
+    move: {
+        label: 'Move File',
+        description: 'Move a file to a different folder',
+        apiMethod: 'files.update (addParents / removeParents)',
+        params: [fileId(), parentFolderId()],
+    },
+    delete: {
+        label: 'Delete (Trash)',
+        description: 'Move to trash — recoverable for 30 days',
+        apiMethod: 'files.update (trashed) / files.delete when permanent',
+        params: [
+            fileId(),
+            {
+                name: 'permanent',
+                label: 'Delete Permanently?',
+                type: 'booleanSelect',
+                options: [
+                    { value: '', label: 'No — move to trash (recoverable)' },
+                    { value: 'true', label: '⚠️ Yes — erase forever (irreversible)' },
+                ],
+            },
+        ],
+    },
+    share: {
+        label: 'Share File',
+        description: 'Grant viewer / commenter / editor permission',
+        apiMethod: 'permissions.create',
+        params: [
+            fileId(),
+            {
+                name: 'type',
+                label: 'Share With',
+                type: 'select',
+                default: 'user',
+                options: [
+                    { value: 'user', label: 'Specific user (email)' },
+                    { value: 'group', label: 'Group (email)' },
+                    { value: 'domain', label: 'Entire domain' },
+                    { value: 'anyone', label: '⚠️ Anyone with the link (public)' },
+                ],
+            },
+            {
+                name: 'role',
+                label: 'Permission Role',
+                type: 'select',
+                default: 'reader',
+                options: [
+                    { value: 'reader', label: 'Viewer (read-only)' },
+                    { value: 'commenter', label: 'Commenter' },
+                    { value: 'writer', label: 'Editor' },
+                ],
+            },
+            {
+                name: 'emailAddress',
+                label: 'Email Address',
+                type: 'template',
+                placeholder: 'user@example.com or {{payload.email}}',
+                showWhen: { field: 'type', in: ['user', 'group'] },
+            },
+            {
+                name: 'domain',
+                label: 'Domain',
+                type: 'template',
+                placeholder: 'example.com',
+                showWhen: { field: 'type', in: ['domain'] },
+            },
+            {
+                name: 'sendNotificationEmail',
+                label: 'Notify Recipient',
+                type: 'booleanSelect',
+                options: [
+                    { value: '', label: "No — don't send email" },
+                    { value: 'true', label: 'Yes — send share notification email' },
+                ],
+            },
+        ],
+    },
+    update: {
+        label: 'Update Metadata',
+        description: 'Rename, set description, or star/unstar',
+        apiMethod: 'files.update',
+        params: [
+            fileId(),
+            { name: 'name', label: 'New Name', type: 'template', placeholder: '{{payload.title}}' },
+            {
+                name: 'description',
+                label: 'Description (optional)',
+                type: 'template',
+                placeholder: '{{payload.description}}',
+            },
+            {
+                name: 'starred',
+                label: 'Starred (optional)',
+                type: 'booleanSelect',
+                options: [
+                    { value: '', label: "— don't change —" },
+                    { value: 'true', label: '⭐ Star' },
+                    { value: 'false', label: 'Un-star' },
+                ],
+            },
+        ],
+    },
+    createFolder: {
+        label: 'Create Folder',
+        description: 'Create a new folder, optionally inside a parent',
+        apiMethod: 'files.create (folder mimeType)',
+        params: [
+            /* Mismo `name` que en update, con otra etiqueta y otro placeholder: por
+               eso los params son por operación y no un registro global de campos. */
+            { name: 'name', label: 'Folder Name', type: 'template', placeholder: 'Reports' },
+            parentFolderId(),
+        ],
+    },
+    export: {
+        label: 'Export Google Doc',
+        description: 'Export a Doc / Sheet / Slide to PDF / DOCX / XLSX',
+        apiMethod: 'files.export',
+        params: [
+            fileId(),
+            {
+                name: 'mimeType',
+                label: 'Export Format',
+                type: 'select',
+                default: 'application/pdf',
+                options: EXPORT_FORMAT_OPTIONS,
+                description: 'Export only works on Google native docs (Docs, Sheets, Slides, Drawings). For regular files use Download instead.',
+            },
+        ],
+    },
+    getPermissions: {
+        label: 'List Permissions',
+        description: 'List who has access (audit before changing)',
+        apiMethod: 'permissions.list',
+        params: [fileId()],
+    },
+};

package/dist/drive-toolkit.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Drive AI Toolkit — las herramientas que un driveAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez**, como el de Sheets y el de Telegram. Antes vivía
+ * TRES veces, y las tres a mano:
+ *
+ *   1. `dashboard/components/drive-actions/drive-operations-schemas.ts`
+ *   2. `api/src/mcp-servers/toolkit-specs.ts`
+ *   3. la página de detalle, que pintaba las doce herramientas como doce
+ *      `<li>` escritos a mano, con el número `12` también a mano en tres sitios
+ *
+ * La 1 y la 2 no habían derivado todavía (medido el 2026-08-10: cero
+ * diferencias, al contrario que Slack con 13 y WhatsApp con 4). Esto es lo que
+ * hace que sigan sin derivar.
+ *
+ * El ORDEN de este array importa: `AiToolkitPreview` pinta el encabezado de
+ * grupo sólo cuando cambia respecto a la fila anterior, así que las
+ * herramientas del mismo grupo tienen que ir seguidas. Los tres grupos son los
+ * que ya inventaba el JSX que sustituye.
+ */
+import type { DriveOperation } from './drive-operations';
+export interface DriveToolkitParameter {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    required: boolean;
+}
+export interface DriveToolkitSpec {
+    operation: DriveOperation;
+    /** Etiqueta corta de la fila en la lista de herramientas. */
+    label: string;
+    /**
+     * Nombre con el que el LLM llama a la herramienta. Todas llevan `_drive_` o
+     * `_to_drive` para no chocar con las de Gmail, Sheets o 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: DriveToolkitParameter[];
+    /** Encabezado de grupo de la página de detalle. El orden es el que agrupa. */
+    group?: string;
+    /**
+     * Marca que la herramienta cambia algo difícil de deshacer, para que la página
+     * lo enseñe y el AI Node pida confirmación. Son **dos**, las mismas que ya
+     * estaban marcadas: `delete_drive_file` y `share_drive_file`. `move` no lo
+     * lleva, y es defendible — deshacerlo es otro move.
+     */
+    destructive?: boolean;
+}
+export declare const DRIVE_TOOLKIT_SPECS: DriveToolkitSpec[];
+/** Índice por nombre de herramienta, para enrutar un `tools/call` sin recorrer. */
+export declare const DRIVE_TOOLKIT_BY_TOOL_NAME: Record<string, DriveToolkitSpec>;

package/dist/drive-toolkit.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Drive AI Toolkit — las herramientas que un driveAction expone cuando
+ * `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez**, como el de Sheets y el de Telegram. Antes vivía
+ * TRES veces, y las tres a mano:
+ *
+ *   1. `dashboard/components/drive-actions/drive-operations-schemas.ts`
+ *   2. `api/src/mcp-servers/toolkit-specs.ts`
+ *   3. la página de detalle, que pintaba las doce herramientas como doce
+ *      `<li>` escritos a mano, con el número `12` también a mano en tres sitios
+ *
+ * La 1 y la 2 no habían derivado todavía (medido el 2026-08-10: cero
+ * diferencias, al contrario que Slack con 13 y WhatsApp con 4). Esto es lo que
+ * hace que sigan sin derivar.
+ *
+ * El ORDEN de este array importa: `AiToolkitPreview` pinta el encabezado de
+ * grupo sólo cuando cambia respecto a la fila anterior, así que las
+ * herramientas del mismo grupo tienen que ir seguidas. Los tres grupos son los
+ * que ya inventaba el JSX que sustituye.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRIVE_TOOLKIT_BY_TOOL_NAME = exports.DRIVE_TOOLKIT_SPECS = void 0;
+const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
+const ENTRAN_Y_SALEN = 'Files in / out';
+const DESCUBRIR = 'Discovery';
+const MUTACIONES = 'Mutations (LLM confirms first)';
+exports.DRIVE_TOOLKIT_SPECS = [
+    /* ── Files in / out ─────────────────────────────────────────────────── */
+    {
+        operation: 'upload',
+        label: 'Upload file',
+        toolName: 'upload_to_drive',
+        group: ENTRAN_Y_SALEN,
+        description: 'Upload a file from the current event payload into Google Drive. Requires an `_file` ref in the payload (created by an upstream node — multipart ingress, File Transform, or another Drive download). Streams from R2; never holds the full file in memory.',
+        parameters: [
+            p('fileName', 'Optional. Override the destination file name. Defaults to the _file ref originalName.', false),
+            p('sourceField', 'Optional. Payload field path holding the _file ref. Defaults to "_file".', false),
+            p('parentFolderId', 'Optional. Drive folder ID to upload into. Empty = root.', false),
+            p('mimeType', 'Optional. Override the MIME type. Defaults to the _file ref mimeType.', false),
+        ],
+    },
+    {
+        operation: 'download',
+        label: 'Download file',
+        toolName: 'download_from_drive',
+        group: ENTRAN_Y_SALEN,
+        description: 'Download a Drive file to HostWebhook storage and return a `_file` ref the next pipeline node can consume (FileTransform, AI vision, HTTP body). Use the file ID from list_drive_files / search.',
+        parameters: [p('fileId', 'The Drive file ID to download.')],
+    },
+    {
+        operation: 'export',
+        label: 'Export Google doc',
+        toolName: 'export_drive_file',
+        group: ENTRAN_Y_SALEN,
+        description: 'Export a Google native document (Doc / Sheet / Slide / Drawing) to a downloadable format like PDF or DOCX, returning a `_file` ref the next pipeline node can consume. Does NOT work on regular files (those use download_from_drive).',
+        parameters: [
+            p('fileId', 'The Drive file ID (must be a Google native doc).'),
+            /* De las dos copias me quedo con la de la api, que es la que dice qué
+               formato de origen va a cada destino. La del dashboard se había quedado
+               sin esa parte. Es la única deriva que tenían Drive y, como estaba en la
+               descripción de un PARÁMETRO, ningún conteo la miraba. */
+            p('mimeType', 'Target MIME type. Common: "application/pdf" (Doc/Slide → PDF), "application/vnd.openxmlformats-officedocument.wordprocessingml.document" (Doc → DOCX), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" (Sheet → XLSX), "text/plain", "text/csv".'),
+        ],
+    },
+    /* ── Discovery ──────────────────────────────────────────────────────── */
+    {
+        operation: 'list',
+        label: 'List / search files',
+        toolName: 'list_drive_files',
+        group: DESCUBRIR,
+        description: "Search the user's Drive (or shared drive). Returns up to N matching files with id, name, mimeType, size, modifiedTime. Use this BEFORE any operation that needs a fileId — never invent IDs.",
+        parameters: [
+            p('query', 'Optional. Substring to match against file names.', false),
+            p('parentFolderId', 'Optional. Restrict search to a single folder.', false),
+            p('mimeType', 'Optional. Filter by MIME type (e.g. "application/pdf", "application/vnd.google-apps.folder").', false),
+            p('pageSize', 'Optional. Max results (default 50, max 100).', false, 'number'),
+            p('orderBy', 'Optional. Drive ordering string (default "modifiedTime desc").', false),
+        ],
+    },
+    {
+        operation: 'get',
+        label: 'Get file metadata',
+        toolName: 'get_drive_file',
+        group: DESCUBRIR,
+        description: 'Read full metadata for one Drive file (name, mimeType, size, parents, owners, starred, trashed). Does NOT download the bytes — use download_from_drive for that.',
+        parameters: [p('fileId', 'The Drive file ID.')],
+    },
+    {
+        operation: 'getPermissions',
+        label: 'List file permissions',
+        toolName: 'get_drive_permissions',
+        group: DESCUBRIR,
+        description: 'List who has access to a Drive file (id, type, role, emailAddress/domain, displayName). Use to audit sharing before changing permissions.',
+        parameters: [p('fileId', 'The Drive file ID.')],
+    },
+    /* ── Mutations ──────────────────────────────────────────────────────── */
+    {
+        operation: 'copy',
+        label: 'Copy file',
+        toolName: 'copy_drive_file',
+        group: MUTACIONES,
+        description: 'Duplicate a Drive file. Optionally rename and/or move into a different folder in one step.',
+        parameters: [
+            p('fileId', 'The source Drive file ID.'),
+            p('newName', 'Optional. Name for the copy. Defaults to "Copy of <original>".', false),
+            p('parentFolderId', 'Optional. Folder ID to place the copy into. Defaults to the source folder.', false),
+        ],
+    },
+    {
+        operation: 'move',
+        label: 'Move file',
+        toolName: 'move_drive_file',
+        group: MUTACIONES,
+        description: 'Move a Drive file to a different folder. The current parents are removed; the file is added to the new parent.',
+        parameters: [
+            p('fileId', 'The Drive file ID to move.'),
+            p('parentFolderId', 'Destination folder ID.'),
+        ],
+    },
+    {
+        operation: 'update',
+        label: 'Update file metadata',
+        toolName: 'update_drive_file',
+        group: MUTACIONES,
+        description: 'Rename a Drive file or change its description / starred status. Use list_drive_files first to find the fileId.',
+        parameters: [
+            p('fileId', 'The Drive file ID.'),
+            p('name', 'Optional. New name.', false),
+            p('description', 'Optional. New description.', false),
+            p('starred', 'Optional. Star/unstar.', false, 'boolean'),
+        ],
+    },
+    {
+        operation: 'createFolder',
+        label: 'Create folder',
+        toolName: 'create_drive_folder',
+        group: MUTACIONES,
+        description: 'Create a new folder in Drive. Use this BEFORE upload_to_drive when the user asks to put a file in a specific named folder that does not yet exist.',
+        parameters: [
+            p('name', 'Folder name.'),
+            p('parentFolderId', 'Optional. Parent folder ID. Empty = root.', false),
+        ],
+    },
+    {
+        operation: 'delete',
+        label: 'Delete file (trash)',
+        toolName: 'delete_drive_file',
+        group: MUTACIONES,
+        description: 'Move a Drive file to trash (recoverable for 30 days). Set permanent=true ONLY when the user explicitly confirms a permanent delete — irreversible. ALWAYS confirm with the user before calling this with permanent=true.',
+        parameters: [
+            p('fileId', 'The Drive file ID to delete.'),
+            p('permanent', 'Optional. true = bypass trash and erase forever (irreversible). Default false.', false, 'boolean'),
+        ],
+        destructive: true,
+    },
+    {
+        operation: 'share',
+        label: 'Share file',
+        toolName: 'share_drive_file',
+        group: MUTACIONES,
+        description: 'Grant a permission on a Drive file. CONFIRM with the user before calling this — sharing externally is sensitive. Public sharing (type="anyone") is especially dangerous; only use when the user explicitly says "make it public" or similar.',
+        parameters: [
+            p('fileId', 'The Drive file ID to share.'),
+            p('type', 'One of: "user" | "group" | "domain" | "anyone". Use "anyone" only with explicit user confirmation.'),
+            p('role', 'One of: "reader" | "commenter" | "writer".'),
+            p('emailAddress', 'Required when type=user|group.', false),
+            p('domain', 'Required when type=domain.', false),
+            p('sendNotificationEmail', 'Optional. true = email the recipient about the share.', false, 'boolean'),
+        ],
+        destructive: true,
+    },
+];
+/** Índice por nombre de herramienta, para enrutar un `tools/call` sin recorrer. */
+exports.DRIVE_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(exports.DRIVE_TOOLKIT_SPECS.map((s) => [s.toolName, s]));

package/dist/index.d.ts

@@ -9,10 +9,14 @@ export { GMAIL_OPERATIONS, isGmailOperation, } from './gmail-operations';
 export type { GmailOperation } from './gmail-operations';
 export { GOOGLE_CALENDAR_OPERATIONS, isGoogleCalendarOperation, } from './calendar-operations';
 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 { DRIVE_OPERATIONS, DRIVE_OPERATION_SPECS, isDriveOperation, } from './drive-operations';
+export type { DriveOperation, DriveParamType, DriveParamSpec, DriveOperationSpec, } from './drive-operations';
+export { DRIVE_TOOLKIT_SPECS, DRIVE_TOOLKIT_BY_TOOL_NAME, } from './drive-toolkit';
+export type { DriveToolkitSpec, DriveToolkitParameter, } from './drive-toolkit';
+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.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.DRIVE_TOOLKIT_BY_TOOL_NAME = exports.DRIVE_TOOLKIT_SPECS = exports.isDriveOperation = exports.DRIVE_OPERATION_SPECS = 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 = exports.GOOGLE_CONTACTS_OPERATIONS_V2 = exports.GOOGLE_CONTACTS_OPERATIONS_V1 = exports.GOOGLE_CONTACTS_OPERATIONS = 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; } });
@@ -41,10 +41,18 @@ Object.defineProperty(exports, "GOOGLE_CALENDAR_OPERATIONS", { enumerable: true,
 Object.defineProperty(exports, "isGoogleCalendarOperation", { enumerable: true, get: function () { return calendar_operations_1.isGoogleCalendarOperation; } });
 var drive_operations_1 = require("./drive-operations");
 Object.defineProperty(exports, "DRIVE_OPERATIONS", { enumerable: true, get: function () { return drive_operations_1.DRIVE_OPERATIONS; } });
+Object.defineProperty(exports, "DRIVE_OPERATION_SPECS", { enumerable: true, get: function () { return drive_operations_1.DRIVE_OPERATION_SPECS; } });
 Object.defineProperty(exports, "isDriveOperation", { enumerable: true, get: function () { return drive_operations_1.isDriveOperation; } });
+var drive_toolkit_1 = require("./drive-toolkit");
+Object.defineProperty(exports, "DRIVE_TOOLKIT_SPECS", { enumerable: true, get: function () { return drive_toolkit_1.DRIVE_TOOLKIT_SPECS; } });
+Object.defineProperty(exports, "DRIVE_TOOLKIT_BY_TOOL_NAME", { enumerable: true, get: function () { return drive_toolkit_1.DRIVE_TOOLKIT_BY_TOOL_NAME; } });
 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/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.10",
+  "version": "1.52.12",
   "description": "Shared node type definitions, connection rules, and dispatch config for HostWebhook",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",