@hostwebhook/node-types 1.87.0 → 1.89.0

package/dist/esm/postgres-ssl.js

@@ -0,0 +1,276 @@
+/**
+ * El SSL de una cadena de conexión de Postgres: qué hará el driver con ella,
+ * y cómo escribir el modo que se elija.
+ *
+ * ## Por qué vive aquí (2026-09-24)
+ *
+ * Ariel conectó un Postgres de Railway eligiendo «Require» y el panel del nodo
+ * dijo `self-signed certificate in certificate chain`. Medido: el servidor
+ * enseña un certificado `CN=localhost` firmado por su propio `root-ca`, y
+ * «Require» escribía `sslmode=require`, que para `pg` 8 es VERIFICAR el
+ * certificado. Y pidió que, si la cadena ya trae el SSL, el panel lo lea y lo
+ * deje fijo; y si no lo trae, que se elija a mano.
+ *
+ * Para fijarlo, el panel tiene que saber lo que hará EL DRIVER, no lo que
+ * parece que dice la cadena — y el driver tiene reglas que no se adivinan:
+ * `sslmode=prefer` también verifica, `ssl=false` ENCIENDE el SSL (queda como
+ * el texto `"false"`, que es verdadero), y `uselibpqcompat=true` le da la
+ * vuelta a `require`. El panel sólo conocía `require` y `no-verify`; lo demás
+ * lo pintaba como «Off».
+ *
+ * Una sola función para el dashboard y para los servicios, y el api la compara
+ * caso a caso con el `pg` que de verdad corre (`el-ssl-de-postgres-es-el-del-
+ * driver.spec.ts`): si una actualización de `pg` cambia sus reglas, ese spec
+ * se pone rojo antes de que el panel enseñe una cosa y el driver haga otra.
+ *
+ * ## Las reglas, copiadas de `pg-connection-string` 2.12 y `pg` 8.20
+ *
+ *   1. Los parámetros salen de `new URL(cadena, 'postgres://base')` (con el
+ *      mismo arreglo de espacios y el mismo host de relleno para `@/`); si una
+ *      clave se repite, gana la ÚLTIMA. Las claves distinguen mayúsculas:
+ *      `SSLMODE` no existe para el driver.
+ *   2. `ssl=true`/`ssl=1` → sí; `ssl=0` → no; cualquier otro texto se queda
+ *      como texto (`ssl=false` → `"false"` → ENCENDIDO).
+ *   3. Si hay `sslmode` (no vacío) o un fichero (`sslcert`, `sslkey`,
+ *      `sslrootcert`), el SSL pasa a ser un objeto y `ssl=` deja de contar.
+ *   4. `sslmode`: `disable` → no; `no-verify` → cifrar sin comprobar; todo lo
+ *      demás (`prefer`, `require`, `verify-ca`, `verify-full`, y cualquier
+ *      valor raro) → cifrar Y comprobar el certificado.
+ *   5. Con `uselibpqcompat=true`, las de libpq: `prefer` y `require` → sin
+ *      comprobar; `verify-full` → comprobando; `verify-ca` sin `sslrootcert`
+ *      → el driver se NIEGA; `no-verify` no existe en libpq → comprobando.
+ *   6. Sin nada de eso, `pg` mira `PGSSLMODE` del entorno; en los servicios no
+ *      está puesta (medido el 2026-09-24), así que es SIN SSL.
+ *
+ * ## Los ficheros (`sslcert`, `sslkey`, `sslrootcert`)
+ *
+ * El driver los LEE DEL DISCO de quien conecta — nuestro servidor, no la
+ * máquina de quien pegó la cadena. Nunca pueden valer: aquí salen como
+ * `problema` y el panel no deja guardarlos.
+ */
+const FICHEROS = ['sslcert', 'sslkey', 'sslrootcert'];
+/** Los parámetros de la cadena, como los lee `pg-connection-string`. `null`
+ *  si no se puede leer (el driver también fallaría) o si es un socket. */
+function parametrosDe(cadena) {
+    let str = (cadena ?? '').trim();
+    if (!str || str.charAt(0) === '/')
+        return null;
+    if (/ |%[^a-f0-9]|%[a-f0-9][^a-f0-9]/i.test(str)) {
+        str = encodeURI(str).replace(/%25(\d\d)/g, '%$1');
+    }
+    let url;
+    try {
+        try {
+            url = new URL(str, 'postgres://base');
+        }
+        catch {
+            url = new URL(str.replace('@/', '@___DUMMY___/'), 'postgres://base');
+        }
+    }
+    catch {
+        return null;
+    }
+    /* Con `socket:` el driver devuelve antes de mirar el SSL. */
+    if (url.protocol === 'socket:')
+        return null;
+    const p = {};
+    url.searchParams.forEach((valor, clave) => {
+        p[clave] = valor;
+    });
+    return p;
+}
+/**
+ * Qué hará el driver con el SSL de esta cadena.
+ *
+ * `{ dice: false }` cuando la cadena no dice nada: ni `ssl`, ni `sslmode`, ni
+ * ficheros (un `sslmode=` o `ssl=` vacío tampoco dicen nada: el driver los
+ * ignora).
+ */
+export function leerSslPostgres(cadena) {
+    const p = parametrosDe(cadena);
+    if (!p)
+        return { dice: false };
+    const ficheros = FICHEROS.filter((k) => p[k]);
+    if (ficheros.length > 0) {
+        return {
+            dice: true,
+            modo: null,
+            por: `${ficheros[0]}=…`,
+            problema: `\`${ficheros[0]}\` points to a file, and the driver reads it from the disk of the ` +
+                `machine that connects — our servers, not yours. Remove it from the connection string ` +
+                `and pick the SSL mode here instead.`,
+        };
+    }
+    const libpq = p.uselibpqcompat === 'true';
+    const conLibpq = libpq ? ' with uselibpqcompat=true' : '';
+    if (p.sslmode) {
+        const por = `sslmode=${p.sslmode}${conLibpq}`;
+        if (libpq) {
+            switch (p.sslmode) {
+                case 'disable':
+                    return { dice: true, modo: 'off', por };
+                case 'prefer':
+                case 'require':
+                    return { dice: true, modo: 'no-verify', por };
+                case 'verify-ca':
+                    return {
+                        dice: true,
+                        modo: null,
+                        por,
+                        problema: 'With uselibpqcompat=true, sslmode=verify-ca needs sslrootcert, and a certificate file ' +
+                            "can't be read from our servers. Use sslmode=verify-full, or remove sslmode and pick " +
+                            'the SSL mode here.',
+                    };
+                default:
+                    /* `verify-full`, `no-verify` (que libpq no conoce) o un valor raro:
+                       el objeto se queda vacío → comprobar. */
+                    return { dice: true, modo: 'require', por };
+            }
+        }
+        switch (p.sslmode) {
+            case 'disable':
+                return { dice: true, modo: 'off', por };
+            case 'no-verify':
+                return { dice: true, modo: 'no-verify', por };
+            default:
+                return { dice: true, modo: 'require', por };
+        }
+    }
+    if (p.ssl) {
+        const por = `ssl=${p.ssl}`;
+        if (p.ssl === '0')
+            return { dice: true, modo: 'off', por };
+        /* `pg` convierte `ssl=no-verify` en «sin comprobar». */
+        if (p.ssl === 'no-verify')
+            return { dice: true, modo: 'no-verify', por };
+        /* `true`, `1`… y también `false`: queda como el texto `"false"`, que es
+           verdadero, y el driver cifra y comprueba. */
+        return { dice: true, modo: 'require', por };
+    }
+    return { dice: false };
+}
+/**
+ * Escribe el modo elegido en la cadena, quitando antes `ssl` y `sslmode` (en
+ * una cadena que «no dice nada», los que hubiera están vacíos). No toca el
+ * resto de parámetros, ni los recodifica.
+ *
+ * Lo que escribe, y por qué:
+ *   - `off`       → `sslmode=disable`, explícito: la cadena guardada dice lo
+ *                   que hace sin depender de `PGSSLMODE`.
+ *   - `require`   → `sslmode=verify-full`, no `require`: para `pg` 8 es lo
+ *                   mismo, pero `require` avisa en cada conexión de que en la
+ *                   versión 9 pasará a NO comprobar. `verify-full` significa
+ *                   lo mismo en las dos.
+ *   - `no-verify` → `sslmode=no-verify`; con `uselibpqcompat=true`, que no lo
+ *                   conoce, `sslmode=require` (lo mismo en libpq).
+ *
+ * Una cadena vacía se devuelve tal cual.
+ */
+export function ponerSslPostgres(cadena, modo) {
+    if (!cadena)
+        return cadena;
+    const i = cadena.indexOf('?');
+    const base = i >= 0 ? cadena.slice(0, i) : cadena;
+    const partes = i >= 0 ? cadena.slice(i + 1).split('&') : [];
+    const clave = (parte) => {
+        const k = parte.split('=')[0];
+        try {
+            return decodeURIComponent(k);
+        }
+        catch {
+            return k;
+        }
+    };
+    const libpq = partes.some((parte) => clave(parte) === 'uselibpqcompat' && /=true$/.test(parte));
+    const quedan = partes.filter((parte) => parte !== '' && clave(parte) !== 'ssl' && clave(parte) !== 'sslmode');
+    const valor = modo === 'off' ? 'disable' : modo === 'require' ? 'verify-full' : libpq ? 'require' : 'no-verify';
+    quedan.push(`sslmode=${valor}`);
+    return `${base}?${quedan.join('&')}`;
+}
+/**
+ * La frase que le falta a un error de conexión de SSL: qué cambiar. `null` si
+ * el error no es de SSL.
+ *
+ * Los tres casos que se ven al conectar:
+ *   - el certificado no se puede comprobar (autofirmado, CA privada, nombre
+ *     que no casa): Railway (`CN=localhost` de su `root-ca`) y Supabase (su
+ *     `Supabase Root 2021 CA`) —medidos los dos el 2026-09-24—, Heroku y
+ *     RDS. Neon sí se comprueba (Let's Encrypt);
+ *   - el servidor no acepta SSL;
+ *   - el servidor exige SSL y se conectó sin él.
+ */
+export function pistaDeSslPostgres(mensaje) {
+    const m = mensaje ?? '';
+    if (/self[- ]signed certificate|unable to verify the first certificate|unable to get local issuer certificate|certificate has expired|Hostname\/IP does not match certificate|SELF_SIGNED_CERT_IN_CHAIN|DEPTH_ZERO_SELF_SIGNED_CERT|UNABLE_TO_VERIFY_LEAF_SIGNATURE|ERR_TLS_CERT_ALTNAME_INVALID|CERT_HAS_EXPIRED/i.test(m)) {
+        return ("The server's SSL certificate can't be verified (self-signed or from a private CA — Railway, " +
+            'Supabase, Heroku and RDS do this). Set the credential\'s SSL mode to "Require, skip cert" ' +
+            '(sslmode=no-verify): the connection stays encrypted, only the certificate check is skipped.');
+    }
+    if (/server does not support SSL connections/i.test(m)) {
+        return ('This server does not accept SSL. Set the credential\'s SSL mode to "Off" (sslmode=disable) — ' +
+            'only for a private network or a tunnel.');
+    }
+    if (/no pg_hba\.conf entry.*(no encryption|SSL off)|connection is insecure|SSL (connection )?is required|requires? SSL/i.test(m)) {
+        return ('This server requires SSL. Set the credential\'s SSL mode to "Require" (sslmode=verify-full), ' +
+            'or "Require, skip cert" (sslmode=no-verify) if its certificate is self-signed.');
+    }
+    return null;
+}
+/** El mensaje con su pista, si la tiene. Lo que devuelven los servicios. Si el
+ *  error ya pasó por aquí (dos capas que lo envuelven), no la repite. */
+export function conPistaDeSslPostgres(mensaje) {
+    const pista = pistaDeSslPostgres(mensaje);
+    if (!pista || mensaje.includes(pista))
+        return mensaje;
+    return `${mensaje} — ${pista}`;
+}
+/**
+ * Los casos con los que se comprueba la regla — aquí y contra el driver de
+ * verdad en el api (`el-ssl-de-postgres-es-el-del-driver.spec.ts`). Uno nuevo
+ * se añade AQUÍ y lo miran los dos.
+ *
+ * `esperado`: el modo, `'nada'` si la cadena no dice nada, `'problema'` si no
+ * puede funcionar.
+ */
+export const CASOS_DE_SSL_POSTGRES = [
+    { cadena: 'postgresql://u:p@h.example:5432/db', esperado: 'nada' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?application_name=x', esperado: 'nada' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=', esperado: 'nada' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?ssl=', esperado: 'nada' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?SSLMODE=require', esperado: 'nada' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?uselibpqcompat=true', esperado: 'nada' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=disable', esperado: 'off' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=allow', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=prefer', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=require', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=verify-ca', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=verify-full', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=no-verify', esperado: 'no-verify' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=REQUIRE', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?ssl=true', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?ssl=1', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?ssl=false', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?ssl=0', esperado: 'off' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?ssl=no-verify', esperado: 'no-verify' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?ssl=true&sslmode=disable', esperado: 'off' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=disable&ssl=true', esperado: 'off' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=no-verify&ssl=true', esperado: 'no-verify' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=require&sslmode=disable', esperado: 'off' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?uselibpqcompat=true&sslmode=disable', esperado: 'off' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?uselibpqcompat=true&sslmode=prefer', esperado: 'no-verify' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?uselibpqcompat=true&sslmode=require', esperado: 'no-verify' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?uselibpqcompat=true&sslmode=verify-full', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?uselibpqcompat=true&sslmode=no-verify', esperado: 'require' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?uselibpqcompat=true&sslmode=verify-ca', esperado: 'problema' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslrootcert=/etc/ssl/ca.pem', esperado: 'problema' },
+    { cadena: 'postgresql://u:p@h.example:5432/db?sslmode=require&sslkey=key.pem', esperado: 'problema' },
+    { cadena: 'postgres://u:p@h.example/db?sslmode=require', esperado: 'require' },
+    { cadena: 'postgres://u:p%40x@h.example/db?sslmode=no-verify', esperado: 'no-verify' },
+    { cadena: 'postgres://u:p@/db?host=/var/run/postgresql&sslmode=disable', esperado: 'off' },
+    /* Varios hosts: `pg` ni la lee (`ERR_INVALID_URL`), así que no hay SSL que
+       fijar — falla al conectar con su propio error. */
+    { cadena: 'postgres://u:p@h1.example:5432,h2.example:5433/db?sslmode=require', esperado: 'nada' },
+    { cadena: 'postgres://u:p w@h.example/db?sslmode=no-verify', esperado: 'no-verify' },
+    { cadena: '/var/run/postgresql mydb', esperado: 'nada' },
+    { cadena: '', esperado: 'nada' },
+];

package/dist/esm/toolkits.d.ts

@@ -14,11 +14,30 @@
  *
  * ## 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».
+ * WhatsApp y Social siguen con sus specs fuera de este paquete (WhatsApp
+ * escrito a mano en la api y el dashboard; Social armado por entidad desde el
+ * registro de proveedores). 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». Contacts se mudó el
+ * 2026-09-24.
+ *
+ * ## El bloqueo por nodo y la puerta sin herramienta (2026-09-24)
+ *
+ * Abajo viven también las dos reglas que se aplican a TODA llamada a un nodo en
+ * modo toolkit, en un solo sitio para que la api, hw-nodes, node-sdk y el
+ * dashboard pregunten lo mismo:
+ *
+ *   - «Block these tool calls»: el dueño bloquea herramientas en el nodo
+ *     (`blockedTools`, por nombre). Vale para todo tipo de este registro
+ *     ({@link admiteBloqueo}).
+ *   - Sin herramienta no se corre: en modo toolkit un nodo sólo ejecuta la
+ *     herramienta que le nombran en `operation`. Un evento sin ella —una arista
+ *     vieja del lienzo— ya no corre la operación de «Single operation», que en
+ *     ese modo no se ve. Decisión de Ariel para los catorce toolkits
+ *     ({@link TIPOS_CON_TOOLKIT}), no sólo los de este registro.
+ *
+ * {@link motivoParaNoCorrer} junta las dos y la llama node-sdk al registrar
+ * cada handler, así que cubre todo camino que acabe en `handler.execute`.
  */
 /** Lo mínimo de una herramienta de toolkit que hace falta para decidir. */
 export interface OperacionDeToolkit {
@@ -45,3 +64,48 @@ export declare function operacionDeToolkit(nodeType: string | undefined | null,
  * las herramientas que no son de toolkit (MCP, HTTP…).
  */
 export declare function esOperacionDestructiva(nodeType: string | undefined | null, operacionONombre: string | undefined | null): boolean | null;
+/**
+ * Los tipos con modo AI toolkit de VARIAS herramientas: los de este registro
+ * más WhatsApp y Social, cuyas herramientas aún no viven aquí. Es la lista de
+ * quién se niega a correr sin herramienta pedida.
+ *
+ * RSS, Mailchimp o Shopify también tienen `aiEnabled`, pero exponen el nodo
+ * como UNA herramienta sin `operation`: no están aquí a propósito.
+ */
+export declare const TIPOS_CON_TOOLKIT: readonly string[];
+export declare function tieneModoToolkit(nodeType: string | undefined | null): boolean;
+/**
+ * ¿Admite «Block these tool calls»? Los de este registro: para bloquear hay
+ * que saber traducir la operación que guarda el AI Node al nombre de la
+ * herramienta que guarda el nodo, y eso sólo se sabe aquí.
+ */
+export declare function admiteBloqueo(nodeType: string | undefined | null): boolean;
+/** Los nombres de herramienta de un toolkit: lo único que `blockedTools` acepta. */
+export declare function nombresDeHerramientas(nodeType: string | undefined | null): string[];
+/** Los nombres bloqueados de un nodo, tolerando documentos sin el campo. */
+export declare function bloqueadasDe(entidad: unknown): string[];
+/**
+ * ¿Está bloqueada en este nodo? Acepta la operación (`deleteOne`, lo que guarda
+ * el AI Node en `operationOverride`) o el nombre (`delete_document`, lo que
+ * recibe el servidor MCP).
+ */
+export declare function herramientaBloqueadaEn(entidad: unknown, nodeType: string | undefined | null, operacionONombre: string | undefined | null): boolean;
+/** Lo que se contesta a una llamada sin herramienta. Lo lee una persona en el
+ *  historial —una arista vieja— o el modelo, así que dice qué hacer. */
+export declare const MENSAJE_SIN_HERRAMIENTA = "This node is an AI toolkit: it only runs the tool an AI Node or an MCP client names, and this call named none. If a connection in the flow leads here, remove it \u2014 in toolkit mode the node is not part of the pipeline.";
+export declare function mensajeDeHerramientaBloqueada(toolName: string): string;
+/**
+ * Por qué una llamada NO debe correr en este nodo, o `null` si puede.
+ *
+ * Sólo mira nodos en modo toolkit (`aiEnabled` y un tipo de
+ * {@link TIPOS_CON_TOOLKIT}); cualquier otro nodo corre como siempre. En modo
+ * toolkit:
+ *   - sin `operation` → {@link MENSAJE_SIN_HERRAMIENTA};
+ *   - con una herramienta bloqueada en el nodo → su mensaje.
+ *
+ * Una operación que el registro no conoce NO se rechaza aquí: cada servicio
+ * sabe qué operaciones acepta (Mongo y Postgres las validan con más detalle),
+ * y rechazar lo desconocido aquí rompería operaciones legítimas que no son
+ * herramientas.
+ */
+export declare function motivoParaNoCorrer(nodeType: string | undefined | null, entidad: unknown, payload: unknown): string | null;

package/dist/esm/toolkits.js

@@ -14,11 +14,30 @@
  *
  * ## 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».
+ * WhatsApp y Social siguen con sus specs fuera de este paquete (WhatsApp
+ * escrito a mano en la api y el dashboard; Social armado por entidad desde el
+ * registro de proveedores). 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». Contacts se mudó el
+ * 2026-09-24.
+ *
+ * ## El bloqueo por nodo y la puerta sin herramienta (2026-09-24)
+ *
+ * Abajo viven también las dos reglas que se aplican a TODA llamada a un nodo en
+ * modo toolkit, en un solo sitio para que la api, hw-nodes, node-sdk y el
+ * dashboard pregunten lo mismo:
+ *
+ *   - «Block these tool calls»: el dueño bloquea herramientas en el nodo
+ *     (`blockedTools`, por nombre). Vale para todo tipo de este registro
+ *     ({@link admiteBloqueo}).
+ *   - Sin herramienta no se corre: en modo toolkit un nodo sólo ejecuta la
+ *     herramienta que le nombran en `operation`. Un evento sin ella —una arista
+ *     vieja del lienzo— ya no corre la operación de «Single operation», que en
+ *     ese modo no se ve. Decisión de Ariel para los catorce toolkits
+ *     ({@link TIPOS_CON_TOOLKIT}), no sólo los de este registro.
+ *
+ * {@link motivoParaNoCorrer} junta las dos y la llama node-sdk al registrar
+ * cada handler, así que cubre todo camino que acabe en `handler.execute`.
  */
 import { GMAIL_ALL_TOOLKIT_SPECS, NATIVE_EMAIL_TOOLKIT_SPECS } from './gmail-operations.js';
 import { GOOGLE_CALENDAR_TOOLKIT_SPECS } from './calendar-toolkit.js';
@@ -30,6 +49,7 @@ import { SHEETS_TOOLKIT_SPECS } from './sheets-toolkit.js';
 import { DOCS_TOOLKIT_SPECS } from './docs-toolkit.js';
 import { MONGO_TOOLKIT_SPECS } from './mongo-toolkit.js';
 import { POSTGRES_TOOLKIT_SPECS } from './postgres-toolkit.js';
+import { GOOGLE_CONTACTS_TOOLKIT_SPECS } from './google-contacts-toolkit.js';
 export const TOOLKITS_POR_TIPO = Object.freeze({
     gmailAction: GMAIL_ALL_TOOLKIT_SPECS,
     emailAction: NATIVE_EMAIL_TOOLKIT_SPECS,
@@ -42,6 +62,7 @@ export const TOOLKITS_POR_TIPO = Object.freeze({
     docsAction: DOCS_TOOLKIT_SPECS,
     mongoAction: MONGO_TOOLKIT_SPECS,
     postgresAction: POSTGRES_TOOLKIT_SPECS,
+    googleContactsAction: GOOGLE_CONTACTS_TOOLKIT_SPECS,
 });
 /**
  * La operación de un toolkit, buscada por su nombre interno (`updateRow`) O
@@ -72,3 +93,86 @@ export function esOperacionDestructiva(nodeType, operacionONombre) {
     const op = operacionDeToolkit(nodeType, operacionONombre);
     return op ? op.destructive === true : null;
 }
+/* ── Quién tiene toolkit, el bloqueo por nodo y la puerta ───────────────── */
+/**
+ * Los tipos con modo AI toolkit de VARIAS herramientas: los de este registro
+ * más WhatsApp y Social, cuyas herramientas aún no viven aquí. Es la lista de
+ * quién se niega a correr sin herramienta pedida.
+ *
+ * RSS, Mailchimp o Shopify también tienen `aiEnabled`, pero exponen el nodo
+ * como UNA herramienta sin `operation`: no están aquí a propósito.
+ */
+export const TIPOS_CON_TOOLKIT = Object.freeze([
+    ...Object.keys(TOOLKITS_POR_TIPO),
+    'whatsappAction',
+    'socialMediaAction',
+]);
+export function tieneModoToolkit(nodeType) {
+    return !!nodeType && TIPOS_CON_TOOLKIT.includes(nodeType);
+}
+/**
+ * ¿Admite «Block these tool calls»? Los de este registro: para bloquear hay
+ * que saber traducir la operación que guarda el AI Node al nombre de la
+ * herramienta que guarda el nodo, y eso sólo se sabe aquí.
+ */
+export function admiteBloqueo(nodeType) {
+    return !!nodeType && Object.prototype.hasOwnProperty.call(TOOLKITS_POR_TIPO, nodeType);
+}
+/** Los nombres de herramienta de un toolkit: lo único que `blockedTools` acepta. */
+export function nombresDeHerramientas(nodeType) {
+    if (!admiteBloqueo(nodeType))
+        return [];
+    return TOOLKITS_POR_TIPO[nodeType].map((s) => s.toolName);
+}
+/** Los nombres bloqueados de un nodo, tolerando documentos sin el campo. */
+export function bloqueadasDe(entidad) {
+    const lista = entidad?.blockedTools;
+    return Array.isArray(lista) ? lista.filter((x) => typeof x === 'string') : [];
+}
+/**
+ * ¿Está bloqueada en este nodo? Acepta la operación (`deleteOne`, lo que guarda
+ * el AI Node en `operationOverride`) o el nombre (`delete_document`, lo que
+ * recibe el servidor MCP).
+ */
+export function herramientaBloqueadaEn(entidad, nodeType, operacionONombre) {
+    if (!operacionONombre)
+        return false;
+    const bloqueadas = bloqueadasDe(entidad);
+    if (bloqueadas.length === 0)
+        return false;
+    const op = operacionDeToolkit(nodeType, operacionONombre);
+    return bloqueadas.includes(op?.toolName ?? operacionONombre);
+}
+/** Lo que se contesta a una llamada sin herramienta. Lo lee una persona en el
+ *  historial —una arista vieja— o el modelo, así que dice qué hacer. */
+export const MENSAJE_SIN_HERRAMIENTA = 'This node is an AI toolkit: it only runs the tool an AI Node or an MCP client names, and this call named none. If a connection in the flow leads here, remove it — in toolkit mode the node is not part of the pipeline.';
+export function mensajeDeHerramientaBloqueada(toolName) {
+    return `The tool "${toolName}" is blocked on this node by its owner. Do not retry it; tell the user it is not allowed here.`;
+}
+/**
+ * Por qué una llamada NO debe correr en este nodo, o `null` si puede.
+ *
+ * Sólo mira nodos en modo toolkit (`aiEnabled` y un tipo de
+ * {@link TIPOS_CON_TOOLKIT}); cualquier otro nodo corre como siempre. En modo
+ * toolkit:
+ *   - sin `operation` → {@link MENSAJE_SIN_HERRAMIENTA};
+ *   - con una herramienta bloqueada en el nodo → su mensaje.
+ *
+ * Una operación que el registro no conoce NO se rechaza aquí: cada servicio
+ * sabe qué operaciones acepta (Mongo y Postgres las validan con más detalle),
+ * y rechazar lo desconocido aquí rompería operaciones legítimas que no son
+ * herramientas.
+ */
+export function motivoParaNoCorrer(nodeType, entidad, payload) {
+    const e = entidad;
+    if (!e || e.aiEnabled !== true || !tieneModoToolkit(nodeType))
+        return null;
+    const pedida = payload?.operation;
+    if (typeof pedida !== 'string' || !pedida.trim())
+        return MENSAJE_SIN_HERRAMIENTA;
+    if (herramientaBloqueadaEn(entidad, nodeType, pedida)) {
+        const op = operacionDeToolkit(nodeType, pedida);
+        return mensajeDeHerramientaBloqueada(op?.toolName ?? pedida);
+    }
+    return null;
+}

package/dist/google-contacts-toolkit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Google Contacts AI Toolkit — las herramientas que un googleContactsAction
+ * expone cuando `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez** (2026-09-24). Vivía dos veces: en
+ * `api/src/mcp-servers/toolkit-specs.ts` y en
+ * `dashboard/components/google-contacts-actions/google-contacts-operations-schemas.ts`,
+ * las dos a mano. Al mudarlas coincidían exactamente —las 15 operaciones, sus
+ * nombres, textos y parámetros—; el `group` del dashboard ya lo lleva el spec
+ * de formulario (`GOOGLE_CONTACTS_OPERATION_SPECS[op].group`).
+ *
+ * Se llama `GOOGLE_CONTACTS_TOOLKIT_SPECS` y no `…_OPERATION_SPECS` porque ese
+ * nombre ya es el del FORMULARIO del nodo en este paquete — la misma pareja que
+ * Discord y Slack.
+ *
+ * ⚠️ El `destructive` ya no se escribe a mano: lo pone `marcarDestructivas` por
+ * el verbo. Cuatro que la copia vieja marcaba dejan de serlo —crear o añadir no
+ * pisa nada—: `create_contact`, `add_contact_to_group`,
+ * `batch_create_contacts` y `create_contact_group`. El gate del AI Node ya las
+ * leía así (por el verbo del nombre); lo que cambia es la etiqueta del panel.
+ *
+ * Los textos van en inglés porque los lee el modelo.
+ */
+import type { GoogleContactsOperation } from './google-contacts-operations.js';
+export interface GoogleContactsToolkitParameter {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    required: boolean;
+}
+export interface GoogleContactsToolkitSpec {
+    operation: GoogleContactsOperation;
+    /** Etiqueta corta de la fila en la lista de herramientas. */
+    label: string;
+    /** Nombre con el que el LLM llama a la herramienta. */
+    toolName: string;
+    /** Descripción (más reglas de uso) que ve el LLM. */
+    description: string;
+    parameters: GoogleContactsToolkitParameter[];
+    /** Pisa o borra. Lo pone `marcarDestructivas` leyendo el verbo del
+     *  nombre (ver `clase-de-herramienta.ts`), no se escribe a mano. */
+    destructive?: boolean;
+}
+export declare const GOOGLE_CONTACTS_TOOLKIT_SPECS: GoogleContactsToolkitSpec[];
+/** Las herramientas por nombre, para despachar una llamada del modelo. */
+export declare const GOOGLE_CONTACTS_TOOLKIT_BY_TOOL_NAME: Record<string, GoogleContactsToolkitSpec>;