@hostwebhook/node-types 1.85.0 → 1.87.0

package/dist/telegram-toolkit.d.ts

@@ -39,6 +39,9 @@ export interface TelegramToolkitSpec {
     /** Descripción (más reglas de uso) que ve el LLM. */
     description: string;
     parameters: TelegramToolkitParameter[];
+    /** Pisa o borra. Lo pone `marcarDestructivas` leyendo el verbo del
+     *  nombre (ver `clase-de-herramienta.ts`), no se escribe a mano. */
+    destructive?: boolean;
     /**
      * 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

package/dist/telegram-toolkit.js

@@ -22,6 +22,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TELEGRAM_TOOLKIT_BY_TOOL_NAME = exports.TELEGRAM_TOOLKIT_SPECS = void 0;
+const clase_de_herramienta_js_1 = require("./clase-de-herramienta.js");
 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
@@ -36,7 +37,7 @@ const p = (name, description, required = true, type = 'string') => ({ name, type
  * 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 = [
+exports.TELEGRAM_TOOLKIT_SPECS = (0, clase_de_herramienta_js_1.marcarDestructivas)([
     {
         operation: 'sendMessage',
         label: 'Send message',
@@ -181,6 +182,6 @@ exports.TELEGRAM_TOOLKIT_SPECS = [
             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/dist/toolkits.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Los toolkits por tipo de nodo: qué herramientas expone cada nodo en modo
+ * AI toolkit, en un solo sitio.
+ *
+ * ## Para qué (2026-09-24)
+ *
+ * Para que el gate «Block destructive tool calls» del AI Node pueda preguntar
+ * por la OPERACIÓN y no sólo por el nombre. Hasta hoy sólo miraba el nombre
+ * contra unos patrones (`delete_*`, `drop_*`…), así que `update_row` de Sheets
+ * —que pisa una fila— pasaba con el gate encendido. Con esto, la herramienta
+ * que el AI Node guardó al conectar (`nodeRefType` + `operationOverride`) se
+ * resuelve aquí a su operación, y su `destructive` —que sale del verbo, ver
+ * `clase-de-herramienta.ts`— decide.
+ *
+ * ## Lo que falta aquí, a propósito
+ *
+ * WhatsApp y Contacts siguen con sus specs escritos a mano en la api y en el
+ * dashboard, no en este paquete. Hasta que se muden, quien consulte este
+ * registro tiene que componerlos por su lado — {@link esOperacionDestructiva}
+ * devuelve `null` para ellos, que significa «no lo sé», no «no es
+ * destructiva».
+ */
+/** Lo mínimo de una herramienta de toolkit que hace falta para decidir. */
+export interface OperacionDeToolkit {
+    operation: string;
+    toolName: string;
+    label: string;
+    destructive?: boolean;
+}
+export declare const TOOLKITS_POR_TIPO: Readonly<Record<string, readonly OperacionDeToolkit[]>>;
+/**
+ * La operación de un toolkit, buscada por su nombre interno (`updateRow`) O
+ * por el nombre de su herramienta (`update_row`).
+ *
+ * Las dos formas porque las dos llegan: el AI Node guarda `operationOverride`
+ * con el nombre interno, y el servidor MCP recibe el nombre de la herramienta.
+ */
+export declare function operacionDeToolkit(nodeType: string | undefined | null, operacionONombre: string | undefined | null): OperacionDeToolkit | null;
+/**
+ * ¿Es destructiva esta operación de toolkit?
+ *
+ * `null` cuando no se sabe —el tipo no es un toolkit de este paquete, o la
+ * operación no existe en él—. Quien llama decide qué hace con el «no sé»; el
+ * gate del AI Node lo combina con los patrones de nombre, que siguen ahí para
+ * las herramientas que no son de toolkit (MCP, HTTP…).
+ */
+export declare function esOperacionDestructiva(nodeType: string | undefined | null, operacionONombre: string | undefined | null): boolean | null;

package/dist/toolkits.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Los toolkits por tipo de nodo: qué herramientas expone cada nodo en modo
+ * AI toolkit, en un solo sitio.
+ *
+ * ## Para qué (2026-09-24)
+ *
+ * Para que el gate «Block destructive tool calls» del AI Node pueda preguntar
+ * por la OPERACIÓN y no sólo por el nombre. Hasta hoy sólo miraba el nombre
+ * contra unos patrones (`delete_*`, `drop_*`…), así que `update_row` de Sheets
+ * —que pisa una fila— pasaba con el gate encendido. Con esto, la herramienta
+ * que el AI Node guardó al conectar (`nodeRefType` + `operationOverride`) se
+ * resuelve aquí a su operación, y su `destructive` —que sale del verbo, ver
+ * `clase-de-herramienta.ts`— decide.
+ *
+ * ## Lo que falta aquí, a propósito
+ *
+ * WhatsApp y Contacts siguen con sus specs escritos a mano en la api y en el
+ * dashboard, no en este paquete. Hasta que se muden, quien consulte este
+ * registro tiene que componerlos por su lado — {@link esOperacionDestructiva}
+ * devuelve `null` para ellos, que significa «no lo sé», no «no es
+ * destructiva».
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOLKITS_POR_TIPO = void 0;
+exports.operacionDeToolkit = operacionDeToolkit;
+exports.esOperacionDestructiva = esOperacionDestructiva;
+const gmail_operations_js_1 = require("./gmail-operations.js");
+const calendar_toolkit_js_1 = require("./calendar-toolkit.js");
+const drive_toolkit_js_1 = require("./drive-toolkit.js");
+const telegram_toolkit_js_1 = require("./telegram-toolkit.js");
+const discord_toolkit_js_1 = require("./discord-toolkit.js");
+const slack_toolkit_js_1 = require("./slack-toolkit.js");
+const sheets_toolkit_js_1 = require("./sheets-toolkit.js");
+const docs_toolkit_js_1 = require("./docs-toolkit.js");
+const mongo_toolkit_js_1 = require("./mongo-toolkit.js");
+const postgres_toolkit_js_1 = require("./postgres-toolkit.js");
+exports.TOOLKITS_POR_TIPO = Object.freeze({
+    gmailAction: gmail_operations_js_1.GMAIL_ALL_TOOLKIT_SPECS,
+    emailAction: gmail_operations_js_1.NATIVE_EMAIL_TOOLKIT_SPECS,
+    calendarAction: calendar_toolkit_js_1.GOOGLE_CALENDAR_TOOLKIT_SPECS,
+    driveAction: drive_toolkit_js_1.DRIVE_TOOLKIT_SPECS,
+    telegramAction: telegram_toolkit_js_1.TELEGRAM_TOOLKIT_SPECS,
+    discordAction: discord_toolkit_js_1.DISCORD_TOOLKIT_SPECS,
+    slackAction: slack_toolkit_js_1.SLACK_TOOLKIT_SPECS,
+    sheetsAction: sheets_toolkit_js_1.SHEETS_TOOLKIT_SPECS,
+    docsAction: docs_toolkit_js_1.DOCS_TOOLKIT_SPECS,
+    mongoAction: mongo_toolkit_js_1.MONGO_TOOLKIT_SPECS,
+    postgresAction: postgres_toolkit_js_1.POSTGRES_TOOLKIT_SPECS,
+});
+/**
+ * La operación de un toolkit, buscada por su nombre interno (`updateRow`) O
+ * por el nombre de su herramienta (`update_row`).
+ *
+ * Las dos formas porque las dos llegan: el AI Node guarda `operationOverride`
+ * con el nombre interno, y el servidor MCP recibe el nombre de la herramienta.
+ */
+function operacionDeToolkit(nodeType, operacionONombre) {
+    if (!nodeType || !operacionONombre)
+        return null;
+    const toolkit = exports.TOOLKITS_POR_TIPO[nodeType];
+    if (!toolkit)
+        return null;
+    return (toolkit.find((s) => s.operation === operacionONombre) ??
+        toolkit.find((s) => s.toolName === operacionONombre) ??
+        null);
+}
+/**
+ * ¿Es destructiva esta operación de toolkit?
+ *
+ * `null` cuando no se sabe —el tipo no es un toolkit de este paquete, o la
+ * operación no existe en él—. Quien llama decide qué hace con el «no sé»; el
+ * gate del AI Node lo combina con los patrones de nombre, que siguen ahí para
+ * las herramientas que no son de toolkit (MCP, HTTP…).
+ */
+function esOperacionDestructiva(nodeType, operacionONombre) {
+    const op = operacionDeToolkit(nodeType, operacionONombre);
+    return op ? op.destructive === true : null;
+}

package/dist/types.d.ts

@@ -54,83 +54,15 @@ export interface NodeUIConfig {
         connectModal?: 'branch' | 'output-group';
         routerTargetLabel?: string;
         /**
-         * Generic named output groups — used by connectModal: 'output-group'.
-         * The modal reads entity[outputGroupsField] as an array of groups,
-         * each with a name (outputGroupNameField), a summary (outputGroupSummaryField),
-         * and its own outputNodes[].
-         * Works for Split (outputs[]), Conditional (branches[]), or any future branching node.
+         * Los juegos de salidas de un nodo que ramifica: UNO, o VARIOS con su
+         * `gate` cada uno [2026-09-22]. Con varios, quien pregunta se queda con
+         * el PRIMERO cuya puerta pasa — ver `outputGroupsFor`. El AI Node los
+         * necesita porque ramifica de dos maneras según el modo: por las
+         * categorías que escribe el usuario (`classifier`) o por los cuatro
+         * puertos fijos del análisis de sentimiento (`sentiment`). La forma
+         * vieja (un objeto suelto) sigue valiendo y significa «sin alternativas».
          */
-        outputGroups?: {
-            /** Entity field containing the array of groups (e.g. 'outputs', 'branches') */
-            field?: string;
-            /** Field within each group for display name (e.g. 'name') */
-            nameField?: string;
-            /** Field within each group for summary/description (e.g. 'field', 'filterMode') */
-            summaryField?: string;
-            /**
-             * Varios campos del grupo, unidos por espacios, cuando el resumen que
-             * de verdad identifica al grupo no cabe en uno solo.
-             *
-             * Existe por las reglas del router: su condición son TRES campos
-             * (`field`, `operator`, `value`) y el modal a medida que se retiró las
-             * pintaba juntas — «status eq active». Con un único `summaryField` una
-             * regla sin `label` quedaba en «rule 1» y «status», que no dice a qué
-             * se está conectando uno.
-             *
-             * Los campos vacíos se saltan, para que una regla con operador
-             * `exists` no salga con un espacio colgando al final.
-             */
-            summaryFields?: string[];
-            /** Label shown in the modal (e.g. 'output', 'branch') */
-            label: string;
-            /** Entity field for the fallback/else path (e.g. 'elseOutputNodes') */
-            elseField?: string;
-            /**
-             * Fixed output groups — for nodes with a static set of outputs (e.g. approval: approve/reject).
-             * Each entry maps to a top-level entity field that holds outputNodes[].
-             * When set, `field`/`nameField` are ignored — modal shows these fixed options.
-             */
-            fixedGroups?: Array<{
-                name: string;
-                field: string;
-            }>;
-            /**
-             * Optional content-aware gate — the output-group modal only opens
-             * when `entity[gate.field] === gate.value`. Lets a node opt into
-             * multi-branch routing only in some modes (e.g. AI Node in
-             * classifier mode) without trapping every connection in the
-             * picker the rest of the time. When the gate fails, the
-             * FlowCanvas falls through to the universal
-             * `entity.outputNodes` connect path.
-             */
-            gate?: {
-                field: string;
-                value: unknown;
-            };
-            /**
-             * Qué es el puerto `main` de este nodo MIENTRAS su contenedor está
-             * vacío. Sin esto, conectar a un nodo que ramifica y todavía no tiene
-             * ninguna salida escribía una arista en `main` **en silencio**, y el
-             * usuario no tenía forma de saber qué había pasado con ella.
-             *
-             * No hay una respuesta única, y por eso es un dato y no una regla.
-             * Medido en `api/src/common/pipeline-run.service.ts`:
-             *
-             *   'passthrough'       — router sin reglas: `rules.length === 0
-             *                         ? refsForPort(entity, MAIN_PORT) : []`. La
-             *                         arista SÍ dispara... hasta que se cree la
-             *                         primera regla, y entonces deja de hacerlo
-             *                         sin avisar.
-             *   'never-dispatched'  — split: no tiene salida `main`, y el propio
-             *                         despachador registra un warning por cada
-             *                         arista que se quedó en ese puerto.
-             *
-             * Se declara sólo donde se ha medido. Sin declarar, el lienzo se
-             * comporta como siempre: conecta por el camino universal y no dice
-             * nada, que es lo que hacía antes de existir este campo.
-             */
-            emptyContainerMain?: 'passthrough' | 'never-dispatched';
-        };
+        outputGroups?: OutputGroupsConfig | OutputGroupsConfig[];
         /**
          * Maps output fields to alternate payload fields on the source entity.
          * When a downstream node is connected via a specific output field,
@@ -224,3 +156,106 @@ export interface PrefixMapping {
     /** Canvas node type used in React Flow nodeTypes map (e.g. "cache-node", "email-action") */
     canvasType: string;
 }
+/**
+ * Un juego de salidas de un nodo que ramifica.
+ *
+ * Vivía dentro de `NodeUIConfig.special` como un objeto anónimo; sale aquí
+ * [2026-09-22] para poder declarar varios por nodo y para que quien los lea
+ * nombre el tipo en vez de repetir su forma.
+ */
+export interface OutputGroupsConfig {
+    /** Entity field containing the array of groups (e.g. 'outputs', 'branches') */
+    field?: string;
+    /** Field within each group for display name (e.g. 'name') */
+    nameField?: string;
+    /** Field within each group for summary/description (e.g. 'field', 'filterMode') */
+    summaryField?: string;
+    /**
+     * Varios campos del grupo, unidos por espacios, cuando el resumen que
+     * de verdad identifica al grupo no cabe en uno solo.
+     *
+     * Existe por las reglas del router: su condición son TRES campos
+     * (`field`, `operator`, `value`) y el modal a medida que se retiró las
+     * pintaba juntas — «status eq active». Con un único `summaryField` una
+     * regla sin `label` quedaba en «rule 1» y «status», que no dice a qué
+     * se está conectando uno.
+     *
+     * Los campos vacíos se saltan, para que una regla con operador
+     * `exists` no salga con un espacio colgando al final.
+     */
+    summaryFields?: string[];
+    /** Label shown in the modal (e.g. 'output', 'branch') */
+    label: string;
+    /** Entity field for the fallback/else path (e.g. 'elseOutputNodes') */
+    elseField?: string;
+    /**
+     * Fixed output groups — for nodes with a static set of outputs (e.g. approval: approve/reject).
+     * When set, `field`/`nameField` are ignored — modal shows these fixed options.
+     *
+     * Cada entrada nombra su puerto de una de dos formas, y sólo una:
+     *   · `field` — un campo de primer nivel de los de ANTES de que los puertos
+     *     existieran (`rejectionOutputNodes` → puerto `rejected`); se traduce
+     *     con el mapa de campos heredados.
+     *   · `port`  — el puerto, tal cual. Es lo que usan las salidas nacidas ya
+     *     con puertos (las cuatro de sentiment): inventarles un campo heredado
+     *     que nunca existió sería mentir en el registro.
+     */
+    fixedGroups?: Array<{
+        name: string;
+        field?: string;
+        port?: string;
+        /** Una línea de qué entrega ese puerto, para el modal de conexión. */
+        summary?: string;
+    }>;
+    /**
+     * Optional content-aware gate — the output-group modal only opens
+     * when `entity[gate.field] === gate.value`. Lets a node opt into
+     * multi-branch routing only in some modes (e.g. AI Node in
+     * classifier mode) without trapping every connection in the
+     * picker the rest of the time. When the gate fails, the
+     * FlowCanvas falls through to the universal
+     * `entity.outputNodes` connect path.
+     */
+    gate?: {
+        field: string;
+        value: unknown;
+    };
+    /**
+     * Qué es el puerto `main` de este nodo MIENTRAS su contenedor está
+     * vacío. Sin esto, conectar a un nodo que ramifica y todavía no tiene
+     * ninguna salida escribía una arista en `main` **en silencio**, y el
+     * usuario no tenía forma de saber qué había pasado con ella.
+     *
+     * No hay una respuesta única, y por eso es un dato y no una regla.
+     * Medido en `api/src/common/pipeline-run.service.ts`:
+     *
+     *   'passthrough'       — router sin reglas: `rules.length === 0
+     *                         ? refsForPort(entity, MAIN_PORT) : []`. La
+     *                         arista SÍ dispara... hasta que se cree la
+     *                         primera regla, y entonces deja de hacerlo
+     *                         sin avisar.
+     *   'never-dispatched'  — split: no tiene salida `main`, y el propio
+     *                         despachador registra un warning por cada
+     *                         arista que se quedó en ese puerto.
+     *
+     * Se declara sólo donde se ha medido. Sin declarar, el lienzo se
+     * comporta como siempre: conecta por el camino universal y no dice
+     * nada, que es lo que hacía antes de existir este campo.
+     */
+    emptyContainerMain?: 'passthrough' | 'never-dispatched';
+}
+/**
+ * El juego de salidas que aplica AHORA a esta entidad, o `undefined` si el
+ * nodo no ramifica en este momento.
+ *
+ * Es la única lectura de `special.outputGroups` que entiende las dos formas
+ * (uno o varios) y las dos puertas (con `gate` o sin ella). Todo el que
+ * pregunte tiene que pasar por aquí: el lienzo, el modal de conexión y el
+ * despachador. Escribirlo cada uno a su manera es como el router acabó con un
+ * camino propio que nadie arregló al arreglar el de los demás.
+ */
+export declare function outputGroupsFor(config: NodeUIConfig | undefined | null, entity: Record<string, unknown> | undefined | null): OutputGroupsConfig | undefined;
+/** Todos los juegos declarados, pasen o no su puerta. Para quien necesita el
+ *  UNIVERSO de puertos que un tipo puede emitir (la auditoría de puertos),
+ *  no el de ahora mismo. */
+export declare function todosLosOutputGroups(config: NodeUIConfig | undefined | null): OutputGroupsConfig[];

package/dist/types.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.singleMeta = singleMeta;
 exports.iterableMeta = iterableMeta;
+exports.outputGroupsFor = outputGroupsFor;
+exports.todosLosOutputGroups = todosLosOutputGroups;
 /** Helper to create _meta for single-object outputs */
 function singleMeta() {
     return { iterable: false, count: 1 };
@@ -10,3 +12,29 @@ function singleMeta() {
 function iterableMeta(field, count) {
     return { iterable: true, iterateField: field, count };
 }
+/**
+ * El juego de salidas que aplica AHORA a esta entidad, o `undefined` si el
+ * nodo no ramifica en este momento.
+ *
+ * Es la única lectura de `special.outputGroups` que entiende las dos formas
+ * (uno o varios) y las dos puertas (con `gate` o sin ella). Todo el que
+ * pregunte tiene que pasar por aquí: el lienzo, el modal de conexión y el
+ * despachador. Escribirlo cada uno a su manera es como el router acabó con un
+ * camino propio que nadie arregló al arreglar el de los demás.
+ */
+function outputGroupsFor(config, entity) {
+    const declarado = config?.special?.outputGroups;
+    if (!declarado)
+        return undefined;
+    const lista = Array.isArray(declarado) ? declarado : [declarado];
+    return lista.find((c) => !c.gate || entity?.[c.gate.field] === c.gate.value);
+}
+/** Todos los juegos declarados, pasen o no su puerta. Para quien necesita el
+ *  UNIVERSO de puertos que un tipo puede emitir (la auditoría de puertos),
+ *  no el de ahora mismo. */
+function todosLosOutputGroups(config) {
+    const declarado = config?.special?.outputGroups;
+    if (!declarado)
+        return [];
+    return Array.isArray(declarado) ? declarado : [declarado];
+}

package/dist/ui.js

@@ -6,6 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PREFIX_TO_TYPE = exports.NODE_UI = void 0;
 exports.resolveNodeId = resolveNodeId;
+const sentiment_js_1 = require("./sentiment.js");
 exports.NODE_UI = {
     // ── Source nodes ──
     // Una fuente arranca el flujo: `fromNodes: false` significa que nada puede
@@ -49,7 +50,15 @@ exports.NODE_UI = {
     // no handle and no route. In any other outputMode the node falls back to
     // the single right-out handle NodeShell renders when no dynamic outputs
     // materialize.
-    ai: { fromNodes: true, toNodes: true, outputHandles: ['right'], special: { loopBackAllowed: true, connectModal: 'output-group', outputGroups: { field: 'categories', nameField: 'name', summaryField: 'description', label: 'category', gate: { field: 'outputMode', value: 'classifier' } } } },
+    // En modo `sentiment` (2026-09-22) el abanico son CUATRO puertos fijos
+    // —negative / neutral / positive / unclear— y no un contenedor del usuario:
+    // el modelo elige entre las tres primeras y el nodo manda a `unclear` lo que
+    // no llega al umbral de confianza. Por eso el AI Node declara DOS juegos de
+    // salidas, uno por modo; `outputGroupsFor` elige el que toca.
+    ai: { fromNodes: true, toNodes: true, outputHandles: ['right'], special: { loopBackAllowed: true, connectModal: 'output-group', outputGroups: [
+                { field: 'categories', nameField: 'name', summaryField: 'description', label: 'category', gate: { field: 'outputMode', value: 'classifier' } },
+                { label: 'sentiment', gate: { field: 'outputMode', value: 'sentiment' }, fixedGroups: sentiment_js_1.SENTIMENT_PORTS.map((p) => ({ name: sentiment_js_1.SENTIMENT_PORT_LABEL[p], port: p, summary: sentiment_js_1.SENTIMENT_PORT_SUMMARY[p] })) },
+            ] } },
     markdown: { fromNodes: true, toNodes: true, special: { loopBackAllowed: true } },
     fileTransform: { fromNodes: true, toNodes: true },
     limit: { fromNodes: true, toNodes: true, special: { loopBackAllowed: true } },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/node-types",
-  "version": "1.85.0",
+  "version": "1.87.0",
   "description": "Shared node type definitions, connection rules, and dispatch config for HostWebhook",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",