@hostwebhook/node-sdk 0.3.0 → 0.5.0

package/dist/credential-references.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Dónde guarda un nodo la referencia a una credencial — TODAS las formas.
+ *
+ * ## Por qué existe
+ *
+ * `findConsumers` buscaba en dos campos, `credentialId` y `memoryCredentialId`,
+ * y con eso decidía si una credencial estaba en uso. Los nodos que pueden usar
+ * VARIAS credenciales no las guardan así:
+ *
+ *   - `socialMediaAction.credentialIds` — un mapa `plataforma → id | id[]`;
+ *   - `socialMediaAction.extraCredentialIds` — un array;
+ *   - `trigger.serviceConfig.social_media.credentialIds` — el mismo mapa,
+ *     pero anidado dentro de `serviceConfig`.
+ *
+ * Así que borrar una credencial usada SÓLO por esas vías encontraba cero
+ * consumidores: ni 409, ni desatacado, ni aviso. La credencial desaparecía y el
+ * nodo se quedaba con un id que ya no resuelve — que es como Ariel perdió la de
+ * Mastodon el 2026-08-12, y el trigger siguió mostrando `…c0fac6` sin decir
+ * nada.
+ *
+ * No es la primera vez: la cabecera de `remove()` cuenta que esta misma clase
+ * de fallo dejó «19 nodos vivos en 5 workspaces apuntando a tres credenciales
+ * que no existían». Aquel arreglo cubrió los dos campos planos y se olvidó de
+ * los múltiples, porque la lista de campos estaba escrita a mano en la consulta.
+ * Ahora está declarada aquí, y `credential-references.spec.ts` la prueba con la
+ * forma real de cada documento.
+ *
+ * ## Cómo se compara
+ *
+ * Siempre por `String(...)`. Estos campos son `Mixed` en Mongoose, así que el
+ * mismo id vive como `ObjectId` en unos documentos y como `string` en otros —
+ * ver `reference-id.ts`. Comparar por valor fallaría en la mitad.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNSET_MARCADOR_DETACH = exports.CAMPOS_MARCADOR_DETACH = exports.CREDENTIAL_REF_SHAPES = void 0;
+exports.leerCamino = leerCamino;
+exports.valorReferencia = valorReferencia;
+exports.formasQueReferencian = formasQueReferencian;
+exports.valorTrasDesatacar = valorTrasDesatacar;
+exports.valorTieneCredencial = valorTieneCredencial;
+exports.tieneAlgunaCredencial = tieneAlgunaCredencial;
+exports.marcadorEsFosil = marcadorEsFosil;
+exports.dtoTocaCredencial = dtoTocaCredencial;
+/**
+ * Las cinco formas que existen hoy.
+ *
+ * Se barren en TODAS las colecciones de nodos, no sólo en las que declaran el
+ * campo: una consulta por un campo que la colección no tiene simplemente no
+ * devuelve nada, y así añadir el campo a otro nodo no obliga a tocar esta lista.
+ */
+exports.CREDENTIAL_REF_SHAPES = [
+    { kind: 'scalar', path: 'credentialId' },
+    { kind: 'scalar', path: 'memoryCredentialId' },
+    { kind: 'array', path: 'extraCredentialIds' },
+    { kind: 'map', path: 'credentialIds' },
+    { kind: 'map', path: 'serviceConfig.social_media.credentialIds' },
+];
+const mismoId = (v, id) => v !== null && v !== undefined && String(v) === id;
+/** Lee un camino con puntos. Devuelve `undefined` si algo del medio falta. */
+function leerCamino(doc, path) {
+    let actual = doc;
+    for (const parte of path.split('.')) {
+        if (actual === null || typeof actual !== 'object')
+            return undefined;
+        actual = actual[parte];
+    }
+    return actual;
+}
+/**
+ * ¿El valor de este campo referencia la credencial?
+ *
+ * Un mapa puede tener el id como string suelto o dentro de un array: las dos
+ * formas conviven en datos reales (`credentialIds` está declarado como
+ * `Record<string, string[] | string>` justamente por eso).
+ */
+function valorReferencia(valor, id, kind) {
+    if (valor === null || valor === undefined)
+        return false;
+    if (kind === 'scalar')
+        return mismoId(valor, id);
+    if (kind === 'array')
+        return Array.isArray(valor) && valor.some((v) => mismoId(v, id));
+    // map
+    if (typeof valor !== 'object' || Array.isArray(valor))
+        return false;
+    return Object.values(valor).some((v) => Array.isArray(v) ? v.some((x) => mismoId(x, id)) : mismoId(v, id));
+}
+/** Las formas por las que ESTE documento referencia la credencial. */
+function formasQueReferencian(doc, id) {
+    return exports.CREDENTIAL_REF_SHAPES.filter((forma) => valorReferencia(leerCamino(doc, forma.path), id, forma.kind));
+}
+/**
+ * El valor que hay que dejar en el campo al quitar la credencial.
+ *
+ * Devuelve `null` cuando el campo se queda sin nada, para que el documento no
+ * conserve un `{}` o un `[]` que se lee como «configurado, pero vacío».
+ *
+ * En el mapa, una plataforma que se queda sin cuentas **desaparece**: dejarla
+ * con `[]` haría que el trigger siguiera anunciando que vigila Mastodon sin
+ * ninguna cuenta con la que hacerlo.
+ */
+function valorTrasDesatacar(valor, id, kind) {
+    if (kind === 'scalar')
+        return null;
+    if (kind === 'array') {
+        const resto = Array.isArray(valor)
+            ? valor.filter((v) => !mismoId(v, id))
+            : [];
+        return resto.length > 0 ? resto : null;
+    }
+    // map
+    if (valor === null || typeof valor !== 'object' || Array.isArray(valor))
+        return null;
+    const salida = {};
+    for (const [clave, v] of Object.entries(valor)) {
+        if (Array.isArray(v)) {
+            const resto = v.filter((x) => !mismoId(x, id));
+            if (resto.length > 0)
+                salida[clave] = resto;
+        }
+        else if (!mismoId(v, id)) {
+            salida[clave] = v;
+        }
+    }
+    return Object.keys(salida).length > 0 ? salida : null;
+}
+/* ── El marcador de «tu credencial se borró» ────────────────────── */
+/**
+ * Los dos campos que `credentials.service.remove` escribe en cada nodo que se
+ * queda huérfano, para que la pantalla pueda decir QUÉ credencial era y
+ * cuándo desapareció (después de desatacar ya no queda id al que preguntar).
+ */
+exports.CAMPOS_MARCADOR_DETACH = [
+    'credentialDetachedAt',
+    'credentialDetachedName',
+];
+/** El `$unset` que los quita. */
+exports.UNSET_MARCADOR_DETACH = {
+    credentialDetachedAt: '',
+    credentialDetachedName: '',
+};
+/** ¿Este valor trae al menos una credencial puesta? */
+function valorTieneCredencial(valor, kind) {
+    if (valor === null || valor === undefined || valor === '')
+        return false;
+    if (kind === 'scalar')
+        return true;
+    if (kind === 'array')
+        return Array.isArray(valor) && valor.length > 0;
+    // map
+    if (typeof valor !== 'object' || Array.isArray(valor))
+        return false;
+    return Object.values(valor).some((v) => Array.isArray(v) ? v.length > 0 : v !== null && v !== undefined && v !== '');
+}
+/**
+ * ¿El nodo tiene AHORA alguna credencial, por cualquiera de las cinco formas?
+ *
+ * Es la pregunta que decide si el aviso «se borró tu credencial» sigue
+ * teniendo sentido. El dashboard hace este mismo cálculo para ocultarlo
+ * (`hooks/useNodeErrors.ts`); aquí sirve para BORRAR el marcador, que es lo
+ * que faltaba: ocultarlo lo dejaba vivo, y volvía a salir en cuanto el nodo
+ * se quedaba sin credencial otra vez — aunque fuera por un «Disconnect» a
+ * mano, y enseñando la fecha de un borrado de días atrás.
+ */
+function tieneAlgunaCredencial(doc) {
+    if (!doc || typeof doc !== 'object')
+        return false;
+    return exports.CREDENTIAL_REF_SHAPES.some((forma) => valorTieneCredencial(leerCamino(doc, forma.path), forma.kind));
+}
+/**
+ * ¿Hay que quitarle el marcador a este documento?
+ *
+ * Sólo cuando el marcador está Y el nodo volvió a tener credencial. Si sigue
+ * huérfano el aviso es legítimo y se queda: alguien le borró la credencial de
+ * verdad y todavía no ha elegido otra.
+ */
+function marcadorEsFosil(doc, tocoCredencial = false) {
+    if (!doc || typeof doc !== 'object')
+        return false;
+    const nombre = doc.credentialDetachedName;
+    if (typeof nombre !== 'string' || !nombre)
+        return false;
+    return tieneAlgunaCredencial(doc) || tocoCredencial;
+}
+/**
+ * ¿Este dto toca el campo de la credencial, sea para poner una o para
+ * quitarla?
+ *
+ * ⚠️ Ésta es la mitad que faltaba, y se vio en cuanto llegó a producción.
+ *
+ * «Es fósil si el nodo VOLVIÓ a tener credencial» arregla el caso de elegir
+ * otra, pero deja fuera el que lo destapó: Ariel pulsó «Disconnect» y el nodo
+ * se quedó SIN credencial, así que seguía contando como huérfano legítimo y
+ * el aviso del día 20 seguía en pantalla. Su queja fue literal: «y sigue».
+ *
+ * La distinción buena no es «tiene credencial» sino «¿sigue siendo verdad que
+ * te la quitaron sin que tú hicieras nada?». En cuanto la persona toca ese
+ * campo —ponga una o la vacíe— ya vio el aviso y actuó: a partir de ahí el
+ * estado lo eligió ella, y seguir diciéndole que se lo borraron el día 20 es
+ * hablarle de otra cosa.
+ *
+ * `!== undefined` y no un truthy: `credentialId: null` es exactamente el caso
+ * de desconectar, y es el que hay que reconocer.
+ */
+function dtoTocaCredencial(dto) {
+    if (!dto || typeof dto !== 'object')
+        return false;
+    return exports.CREDENTIAL_REF_SHAPES.some((forma) => leerCamino(dto, forma.path) !== undefined);
+}

package/dist/dto-utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Filters out undefined values from an object.
+ * Useful for DTO → Mongoose update where undefined own properties
+ * would overwrite existing values.
+ */
+export declare function definedProps<T extends object>(obj: T): Partial<T>;
+/**
+ * Throws ForbiddenException if the current count has reached the plan limit.
+ * A limit of -1 means unlimited.
+ */
+export declare function checkPlanLimit(count: number, limit: number, resource: string): void;

package/dist/dto-utils.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definedProps = definedProps;
+exports.checkPlanLimit = checkPlanLimit;
+const common_1 = require("@nestjs/common");
+/**
+ * Filters out undefined values from an object.
+ * Useful for DTO → Mongoose update where undefined own properties
+ * would overwrite existing values.
+ */
+function definedProps(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+/**
+ * Throws ForbiddenException if the current count has reached the plan limit.
+ * A limit of -1 means unlimited.
+ */
+function checkPlanLimit(count, limit, resource) {
+    if (limit !== -1 && count >= limit) {
+        throw new common_1.ForbiddenException(`${resource} limit reached (${count}/${limit}). Upgrade your plan.`);
+    }
+}

package/dist/index.d.ts

@@ -50,3 +50,12 @@ export * from "./swallow";
 export * from "./template-render";
 export * from "./try-parse";
 export * from "./workspace-payloads";
+export * from "./base-node.service";
+export * from "./cascade-cleanup";
+export * from "./dto-utils";
+export * from "./sync-connections";
+export * from "./unique-name";
+export * from "./credential-references";
+export * from "./limpiar-marcador-detach";
+export * from "./olvidar-la-colocacion";
+export * from "./acceso-al-workspace";

package/dist/index.js

@@ -72,3 +72,12 @@ __exportStar(require("./swallow"), exports);
 __exportStar(require("./template-render"), exports);
 __exportStar(require("./try-parse"), exports);
 __exportStar(require("./workspace-payloads"), exports);
+__exportStar(require("./base-node.service"), exports);
+__exportStar(require("./cascade-cleanup"), exports);
+__exportStar(require("./dto-utils"), exports);
+__exportStar(require("./sync-connections"), exports);
+__exportStar(require("./unique-name"), exports);
+__exportStar(require("./credential-references"), exports);
+__exportStar(require("./limpiar-marcador-detach"), exports);
+__exportStar(require("./olvidar-la-colocacion"), exports);
+__exportStar(require("./acceso-al-workspace"), exports);

package/dist/limpiar-marcador-detach.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Quita el aviso «se borró tu credencial» cuando el nodo ya tiene otra.
+ *
+ * ## El defecto que arregla
+ *
+ * `credentials.service.remove` escribe dos marcadores en cada nodo que deja
+ * huérfano —`credentialDetachedName` y `credentialDetachedAt`— para que la
+ * pantalla pueda decir qué credencial era y cuándo desapareció. Hasta ahora
+ * eran un `$set` sin pareja: **ningún sitio de la api los borraba**.
+ *
+ * El dashboard sólo los OCULTA mientras el nodo tenga alguna credencial
+ * (`hooks/useNodeErrors.ts`). Ocultar no es borrar: el marcador seguía vivo
+ * debajo y volvía a salir en cuanto el nodo se quedaba sin credencial otra
+ * vez — incluso pulsando «Disconnect», que sólo hace `onChange(null, null)`
+ * y no borra ninguna credencial.
+ *
+ * Lo reportó Ariel el 2026-08-23: desconectó una credencial de Drive y la
+ * pantalla le dijo *«The credential "Google - …" was deleted on Aug 20, 2026»*.
+ * La fecha es la prueba de que el marcador era viejo: si lo hubiera escrito su
+ * clic, diría el 23. Un fósil de otro día conviviendo con el estado de hoy, y
+ * ganando él.
+ *
+ * ## Por qué esta condición y no otra
+ *
+ * Se miran las DOS cosas, y hicieron falta las dos:
+ *
+ *   - el DOCUMENTO tiene credencial → el aviso ya no describe nada; cubre
+ *     también al nodo que sólo cambió de nombre y arrastra el fósil;
+ *   - el DTO tocaba el campo de la credencial → la persona acaba de actuar
+ *     sobre él, ponga una o la vacíe.
+ *
+ * ⚠️ La segunda llegó tarde. Con sólo la primera, pulsar «Disconnect» dejaba
+ * el nodo sin credencial, o sea contando como huérfano legítimo, y el aviso
+ * del día 20 seguía en pantalla — que es exactamente el caso que abrió todo
+ * esto. Ariel lo dijo en dos palabras al probarlo: «y sigue».
+ *
+ * Y sólo se limpia si el nodo VOLVIÓ a tener credencial: si sigue huérfano el
+ * aviso es legítimo —alguien le borró la credencial de verdad y todavía no ha
+ * elegido otra— y tiene que seguir viéndose.
+ *
+ * ## Coste
+ *
+ * Cero en el caso normal. `marcadorEsFosil` mira dos campos en memoria y sale;
+ * sólo hay escritura cuando de verdad hay un fósil que quitar, que es raro.
+ *
+ * El fallo no aborta el PATCH: el usuario venía a guardar su nodo, y que no se
+ * pueda limpiar un aviso cosmético no es motivo para devolverle un 500. Pero
+ * se registra con nombre — ver `common/swallow`.
+ */
+export declare function limpiarMarcadorDetachSiEsFosil(model: {
+    updateOne(filtro: unknown, update: unknown): {
+        exec?: () => Promise<unknown>;
+    } | Promise<unknown>;
+}, doc: unknown, opts?: {
+    /**
+     * ¿El PATCH que trajo hasta aquí tocaba el campo de la credencial?
+     *
+     * Cuando sí, el aviso se retira aunque el nodo se quede SIN credencial:
+     * desconectar a mano es un acto de la persona, y el marcador sólo tiene
+     * sentido mientras describa algo que le pasó SIN que ella hiciera nada.
+     */
+    tocoCredencial?: boolean;
+}): Promise<void>;

package/dist/limpiar-marcador-detach.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.limpiarMarcadorDetachSiEsFosil = limpiarMarcadorDetachSiEsFosil;
+const common_1 = require("@nestjs/common");
+const swallow_1 = require("./swallow");
+const credential_references_1 = require("./credential-references");
+const LOGGER = new common_1.Logger('LimpiarMarcadorDetach');
+/**
+ * Quita el aviso «se borró tu credencial» cuando el nodo ya tiene otra.
+ *
+ * ## El defecto que arregla
+ *
+ * `credentials.service.remove` escribe dos marcadores en cada nodo que deja
+ * huérfano —`credentialDetachedName` y `credentialDetachedAt`— para que la
+ * pantalla pueda decir qué credencial era y cuándo desapareció. Hasta ahora
+ * eran un `$set` sin pareja: **ningún sitio de la api los borraba**.
+ *
+ * El dashboard sólo los OCULTA mientras el nodo tenga alguna credencial
+ * (`hooks/useNodeErrors.ts`). Ocultar no es borrar: el marcador seguía vivo
+ * debajo y volvía a salir en cuanto el nodo se quedaba sin credencial otra
+ * vez — incluso pulsando «Disconnect», que sólo hace `onChange(null, null)`
+ * y no borra ninguna credencial.
+ *
+ * Lo reportó Ariel el 2026-08-23: desconectó una credencial de Drive y la
+ * pantalla le dijo *«The credential "Google - …" was deleted on Aug 20, 2026»*.
+ * La fecha es la prueba de que el marcador era viejo: si lo hubiera escrito su
+ * clic, diría el 23. Un fósil de otro día conviviendo con el estado de hoy, y
+ * ganando él.
+ *
+ * ## Por qué esta condición y no otra
+ *
+ * Se miran las DOS cosas, y hicieron falta las dos:
+ *
+ *   - el DOCUMENTO tiene credencial → el aviso ya no describe nada; cubre
+ *     también al nodo que sólo cambió de nombre y arrastra el fósil;
+ *   - el DTO tocaba el campo de la credencial → la persona acaba de actuar
+ *     sobre él, ponga una o la vacíe.
+ *
+ * ⚠️ La segunda llegó tarde. Con sólo la primera, pulsar «Disconnect» dejaba
+ * el nodo sin credencial, o sea contando como huérfano legítimo, y el aviso
+ * del día 20 seguía en pantalla — que es exactamente el caso que abrió todo
+ * esto. Ariel lo dijo en dos palabras al probarlo: «y sigue».
+ *
+ * Y sólo se limpia si el nodo VOLVIÓ a tener credencial: si sigue huérfano el
+ * aviso es legítimo —alguien le borró la credencial de verdad y todavía no ha
+ * elegido otra— y tiene que seguir viéndose.
+ *
+ * ## Coste
+ *
+ * Cero en el caso normal. `marcadorEsFosil` mira dos campos en memoria y sale;
+ * sólo hay escritura cuando de verdad hay un fósil que quitar, que es raro.
+ *
+ * El fallo no aborta el PATCH: el usuario venía a guardar su nodo, y que no se
+ * pueda limpiar un aviso cosmético no es motivo para devolverle un 500. Pero
+ * se registra con nombre — ver `common/swallow`.
+ */
+async function limpiarMarcadorDetachSiEsFosil(
+/*
+ * ⚠️ `updateOne` va como MÉTODO abreviado y no como propiedad con tipo
+ * función, y la diferencia no es de estilo.
+ *
+ * Con `strictFunctionTypes`, una propiedad cuyo tipo es una función se
+ * comprueba de forma CONTRAVARIANTE en los parámetros: un `updateOne` real
+ * de Mongoose, que declara `filter: _QueryFilter<T>`, no encaja en uno que
+ * declara `filtro: unknown`. Un método abreviado se comprueba de forma
+ * bivariante y sí encaja.
+ *
+ * Salió al mudar esto al paquete: en la api compilaba con mongoose 9.2.1 y
+ * aquí falla con 9.9.4, que estrechó `_QueryFilter`. Como el `peerDependency`
+ * dice `mongoose >=8`, la firma tiene que aguantar las dos — y la bivarianza
+ * es segura aquí porque esta función sólo LLAMA al método, con valores que
+ * construye ella misma.
+ */
+model, doc, opts) {
+    if (!(0, credential_references_1.marcadorEsFosil)(doc, opts?.tocoCredencial))
+        return;
+    const id = doc._id;
+    if (!id)
+        return;
+    const resultado = model.updateOne({ _id: id }, { $unset: credential_references_1.UNSET_MARCADOR_DETACH });
+    const promesa = typeof resultado.exec === 'function'
+        ? resultado.exec()
+        : resultado;
+    await Promise.resolve(promesa).catch((0, swallow_1.onFailure)(LOGGER, `limpiar el marcador de credencial borrada del nodo ${String(id)}`));
+    /* También en el documento que se va a devolver.
+       Sin esto el PATCH responde con el marcador todavía puesto, la pantalla lo
+       pinta una última vez y sólo desaparece al recargar — que es exactamente la
+       clase de «se arregló pero no se ve» que hace dudar de si se arregló. */
+    const d = doc;
+    delete d.credentialDetachedAt;
+    delete d.credentialDetachedName;
+}

package/dist/olvidar-la-colocacion.d.ts

@@ -0,0 +1,23 @@
+import type { Connection } from 'mongoose';
+/**
+ * Borrar un nodo le quita también su sitio en el lienzo.
+ *
+ * Sin esto, la clave se queda para siempre. Es literalmente de donde salió el
+ * mapa viejo: `users.flowLayout` tenía **1 003 de 1 284 nodos referidos que ya
+ * no existían** —el 78 %— porque no había ningún camino que quitara la entrada
+ * al borrar el nodo. Sólo crecía.
+ *
+ * Y ya estaba volviendo a pasar: dos horas después de migrar, `flow_layouts`
+ * tenía 55 posiciones para 53 nodos. Las dos de más eran un Chat Trigger y el
+ * nodo AI que nace con él, creados y borrados por el camino.
+ *
+ * Va por la conexión y no por el servicio a propósito: quien borra un nodo es
+ * `BaseNodeService`, del que heredan los 45 tipos, y meterle una dependencia
+ * nueva al constructor obliga a tocar los 45 módulos. `cascadeCleanupNodeReferences`
+ * —que limpia las conexiones que apuntaban al nodo— resuelve lo mismo por el
+ * mismo sitio.
+ *
+ * No lanza. Que un nodo no se pueda borrar porque su posición se resistió sería
+ * peor que la posición huérfana que esto viene a evitar.
+ */
+export declare function olvidarLaColocacion(connection: Connection, nodeType: string, nodeId: string, workspaceId: string | undefined): Promise<number>;

package/dist/olvidar-la-colocacion.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.olvidarLaColocacion = olvidarLaColocacion;
+const common_1 = require("@nestjs/common");
+const mongoose_1 = require("mongoose");
+const node_types_1 = require("@hostwebhook/node-types");
+const logger = new common_1.Logger('FlowLayouts');
+/**
+ * Borrar un nodo le quita también su sitio en el lienzo.
+ *
+ * Sin esto, la clave se queda para siempre. Es literalmente de donde salió el
+ * mapa viejo: `users.flowLayout` tenía **1 003 de 1 284 nodos referidos que ya
+ * no existían** —el 78 %— porque no había ningún camino que quitara la entrada
+ * al borrar el nodo. Sólo crecía.
+ *
+ * Y ya estaba volviendo a pasar: dos horas después de migrar, `flow_layouts`
+ * tenía 55 posiciones para 53 nodos. Las dos de más eran un Chat Trigger y el
+ * nodo AI que nace con él, creados y borrados por el camino.
+ *
+ * Va por la conexión y no por el servicio a propósito: quien borra un nodo es
+ * `BaseNodeService`, del que heredan los 45 tipos, y meterle una dependencia
+ * nueva al constructor obliga a tocar los 45 módulos. `cascadeCleanupNodeReferences`
+ * —que limpia las conexiones que apuntaban al nodo— resuelve lo mismo por el
+ * mismo sitio.
+ *
+ * No lanza. Que un nodo no se pueda borrar porque su posición se resistió sería
+ * peor que la posición huérfana que esto viene a evitar.
+ */
+async function olvidarLaColocacion(connection, nodeType, nodeId, workspaceId) {
+    if (!workspaceId || !mongoose_1.Types.ObjectId.isValid(workspaceId)) {
+        /* El nodo se borró igual; sólo queda su posición. Decirlo, porque el rastro
+           es lo único que distingue «no había workspace» de «no se limpió». */
+        logger.warn(`olvidarLaColocacion: ${nodeType}/${nodeId} sin workspaceId; su posición se queda`);
+        return 0;
+    }
+    const prefijo = node_types_1.NODE_REGISTRY[nodeType]?.prefix;
+    if (!prefijo) {
+        logger.warn(`olvidarLaColocacion: '${nodeType}' no está en el registro; no sé cómo se llama en el lienzo`);
+        return 0;
+    }
+    /* La clave del lienzo, que es `<prefijo>-<ObjectId>`. Se comprueba en vez de
+       interpolar a ciegas: va dentro de una ruta de `$unset`, donde un punto baja
+       un nivel y un `$` es un operador. */
+    if (!/^[0-9a-fA-F]{24}$/.test(nodeId)) {
+        logger.warn(`olvidarLaColocacion: '${nodeId}' no es un id de nodo`);
+        return 0;
+    }
+    try {
+        /* `updateMany` y sin `userId`: la colocación es de cada persona, y quien
+           borra el nodo no sabe —ni tiene por qué— quién lo había puesto dónde. */
+        const r = await connection
+            .collection('flow_layouts')
+            .updateMany({ workspaceId: new mongoose_1.Types.ObjectId(workspaceId) }, { $unset: { [`positions.${prefijo}-${nodeId}`]: '' } });
+        return r.modifiedCount ?? 0;
+    }
+    catch (err) {
+        logger.error(`olvidarLaColocacion: no pude quitar ${prefijo}-${nodeId} del workspace ${workspaceId}:`, err);
+        return 0;
+    }
+}

package/dist/sync-connections.d.ts

@@ -0,0 +1,73 @@
+import { Connection, Types } from 'mongoose';
+/**
+ * Reject a node wired to itself.
+ *
+ * A canvas drag from a node's own output dot to its own input dot produced a
+ * real, persisted edge: source and target were the same id. Nothing stopped it
+ * — the dashboard assumed the registry prevented invalid connections, and the
+ * registry answers a different question. `canReceiveFrom('transform',
+ * 'transform')` is TRUE, and correctly so: chaining two different Transform
+ * nodes is ordinary. What the type pair cannot express is "not this same
+ * instance", because ids are not types.
+ *
+ * The one legitimate self-edge is the Loop node's loop-back, and the registry
+ * already declares it as `special.hasLoopBack`. So the exception is read from
+ * there rather than hardcoded here — a future node that needs to re-enter
+ * itself declares the flag and both the canvas and this check follow.
+ */
+export declare function assertNoSelfConnection(nodeType: string, nodeId: Types.ObjectId | string, nodes: Array<{
+    nodeType: string;
+    nodeId: any;
+}>): void;
+/**
+ * Rechaza una conexión entre tipos que no pueden conectarse.
+ *
+ * Hasta ahora la compatibilidad de tipos era cosa del lienzo, y estaba escrito
+ * aquí al lado: *"Type compatibility is the registry's job and is checked on
+ * the canvas"*. Eso valía mientras el lienzo fuera el único que escribe, y no
+ * lo es: `/agent-context` le explica a un agente, con ejemplos, que meta
+ * `{ nodeType, nodeId }` a mano en `inputNodes`/`outputNodes`, y cualquier
+ * cliente con la clave y el scope puede hacer lo mismo.
+ *
+ * Lo que se colaba por ahí no revienta: **desaparece**. `dispatchOutputNodes`
+ * cae en su rama por defecto, `getNodeHandler('trigger')` no devuelve nada y
+ * suelta un `logger.warn` —sin evento de telemetría, porque el `telemetry.emit`
+ * está en el `catch` y esto no lanza—. O sea una arista dibujada en el lienzo
+ * que no dispara nunca y que no aparece en ningún sitio donde mirarla.
+ *
+ * ⚠️ **La regla es `fromNodes`/`toNodes` de `NODE_UI`, y no las listas de
+ * `NODE_CONNECTIONS`.** La tentación es usar `acceptsInputFrom`/`canOutputTo`,
+ * que están ahí mismo, las declaran los 43 tipos y parecen más precisas. Están
+ * podridas: medidas contra producción el 2026-08-19 rechazaban **111 de 364**
+ * conexiones que funcionan hoy — `trigger → ai`, `ai → telegramAction`,
+ * `sheetsAction → filter`. `fromNodes`/`toNodes` rechazaba **0**, porque es el
+ * mismo dato que decide qué puntos pinta la tarjeta. Endurecer con eso no
+ * puede romper nada que el usuario haya podido crear desde el lienzo, que es
+ * justo la propiedad que se busca: la api no debe ser más estricta que la
+ * pantalla, sólo igual de estricta en los caminos que la pantalla no cubre.
+ *
+ * De un tipo que el registro no conoce no se opina. Un alias viejo se
+ * normaliza primero (`voiceCall` → `voiceAgent`); lo que ni así aparezca se
+ * deja pasar, porque un 400 sobre datos heredados con autoguardado deja la
+ * página sin poder guardar nunca más.
+ */
+export declare function assertConnectableTypes(ownType: string, refs: {
+    inputNodes?: Array<{
+        nodeType: string;
+    }>;
+    outputNodes?: Array<{
+        nodeType: string;
+    }>;
+}): void;
+/**
+ * Validate that all target nodes belong to the same workspace as the source node.
+ * Throws BadRequestException if any cross-workspace connection is detected.
+ *
+ * This is the ONLY backend connection logic. The frontend owns connection
+ * creation/deletion — it updates both sides (source.outputNodes + target.inputNodes).
+ * The backend just saves what it receives and validates workspace boundaries.
+ */
+export declare function validateConnectionWorkspaces(connection: Connection, sourceWorkspaceId: Types.ObjectId | string | null | undefined, nodes: Array<{
+    nodeType: string;
+    nodeId: any;
+}>): Promise<void>;