@hostwebhook/node-sdk 0.5.0 → 0.7.0

package/dist/credential-references.d.ts

@@ -37,23 +37,70 @@ export type CredRefShape =
 {
     kind: 'scalar';
     path: string;
+    soloLectura?: boolean;
 }
 /** `extraCredentialIds: ObjectId[]` */
  | {
     kind: 'array';
     path: string;
+    soloLectura?: boolean;
 }
 /** `credentialIds: { plataforma: id | id[] }` */
  | {
     kind: 'map';
     path: string;
+    soloLectura?: boolean;
+}
+/**
+ * `tools: [{ credentialId, ... }]` — un array de OBJETOS, cada uno con su
+ * propia referencia. No es `array`: ahí los elementos SON el id.
+ *
+ * ⚠️ `campo` no es opcional a propósito. Una forma que no dice dónde mirar
+ * dentro del objeto no puede mirar en ningún sitio, y el fallo sería
+ * silencioso: `formasQueReferencian` devolvería vacío y el documento pasaría
+ * por «no usa esta credencial».
+ */
+ | {
+    kind: 'arrayDeObjetos';
+    path: string;
+    campo: string;
+    soloLectura?: boolean;
 };
 /**
- * Las cinco formas que existen hoy.
+ * Las nueve 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.
+ *
+ * ## Las cuatro que faltaban, y lo que costaban
+ *
+ * Eran cinco, y se quedaban cortas exactamente igual que la versión anterior a
+ * ésta — aquélla miraba dos campos escritos a mano en la consulta, y por eso
+ * nació este fichero. Las que faltaban:
+ *
+ *   `tools[].credentialId`          las credenciales de las TOOLS del AI Node:
+ *                                   toda tool MCP y todo puente de audio
+ *   `audioTranscribeCredentialId`   el puente de transcripción del AI Node
+ *   `embedding.credentialId`        la clave que paga cada `embed` del vector store
+ *   `backend.config.credentialId`   la conexión del backend del vector store
+ *   `results[].credentialId`        a qué cuenta se publicó cada fila de un post
+ *
+ * Consecuencia medible y VIVA: `findConsumers` usa esta misma lista, así que
+ * borrar una credencial `mcp_server` usada sólo por una tool encontraba CERO
+ * consumidores — ni 409, ni desatachado, ni marcador. La credencial
+ * desaparecía y el nodo se quedaba con un id que ya no resuelve. Es el mismo
+ * fallo por el que se perdió la de Mastodon el 12-ago, con otro campo.
+ *
+ * ## ⚠️ `soloLectura`: referenciar no es lo mismo que desatachar
+ *
+ * `results[]` de un post es un REGISTRO HISTÓRICO: dice a qué cuenta se
+ * publicó cada fila. Tiene que contar para encontrar consumidores —que salte
+ * el 409— pero reescribirlo al desatachar sería falsear lo que pasó: una
+ * publicación que SÍ ocurrió quedaría sin decir con qué cuenta.
+ *
+ * Sin esta marca, ampliar la lista habría arreglado el borrado silencioso y
+ * roto el historial en el mismo movimiento.
  */
 export declare const CREDENTIAL_REF_SHAPES: readonly CredRefShape[];
 /** Lee un camino con puntos. Devuelve `undefined` si algo del medio falta. */
@@ -65,7 +112,7 @@ export declare function leerCamino(doc: unknown, path: string): unknown;
  * formas conviven en datos reales (`credentialIds` está declarado como
  * `Record<string, string[] | string>` justamente por eso).
  */
-export declare function valorReferencia(valor: unknown, id: string, kind: CredRefShape['kind']): boolean;
+export declare function valorReferencia(valor: unknown, id: string, forma: CredRefShape): boolean;
 /** Las formas por las que ESTE documento referencia la credencial. */
 export declare function formasQueReferencian(doc: Record<string, unknown>, id: string): CredRefShape[];
 /**
@@ -78,7 +125,7 @@ export declare function formasQueReferencian(doc: Record<string, unknown>, id: s
  * con `[]` haría que el trigger siguiera anunciando que vigila Mastodon sin
  * ninguna cuenta con la que hacerlo.
  */
-export declare function valorTrasDesatacar(valor: unknown, id: string, kind: CredRefShape['kind']): unknown;
+export declare function valorTrasDesatacar(valor: unknown, id: string, forma: CredRefShape): unknown;
 /**
  * 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
@@ -88,7 +135,7 @@ export declare const CAMPOS_MARCADOR_DETACH: readonly ["credentialDetachedAt", "
 /** El `$unset` que los quita. */
 export declare const UNSET_MARCADOR_DETACH: Record<string, ''>;
 /** ¿Este valor trae al menos una credencial puesta? */
-export declare function valorTieneCredencial(valor: unknown, kind: CredRefShape['kind']): boolean;
+export declare function valorTieneCredencial(valor: unknown, forma: CredRefShape): boolean;
 /**
  * ¿El nodo tiene AHORA alguna credencial, por cualquiera de las cinco formas?
  *

package/dist/credential-references.js

@@ -43,11 +43,40 @@ exports.tieneAlgunaCredencial = tieneAlgunaCredencial;
 exports.marcadorEsFosil = marcadorEsFosil;
 exports.dtoTocaCredencial = dtoTocaCredencial;
 /**
- * Las cinco formas que existen hoy.
+ * Las nueve 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.
+ *
+ * ## Las cuatro que faltaban, y lo que costaban
+ *
+ * Eran cinco, y se quedaban cortas exactamente igual que la versión anterior a
+ * ésta — aquélla miraba dos campos escritos a mano en la consulta, y por eso
+ * nació este fichero. Las que faltaban:
+ *
+ *   `tools[].credentialId`          las credenciales de las TOOLS del AI Node:
+ *                                   toda tool MCP y todo puente de audio
+ *   `audioTranscribeCredentialId`   el puente de transcripción del AI Node
+ *   `embedding.credentialId`        la clave que paga cada `embed` del vector store
+ *   `backend.config.credentialId`   la conexión del backend del vector store
+ *   `results[].credentialId`        a qué cuenta se publicó cada fila de un post
+ *
+ * Consecuencia medible y VIVA: `findConsumers` usa esta misma lista, así que
+ * borrar una credencial `mcp_server` usada sólo por una tool encontraba CERO
+ * consumidores — ni 409, ni desatachado, ni marcador. La credencial
+ * desaparecía y el nodo se quedaba con un id que ya no resuelve. Es el mismo
+ * fallo por el que se perdió la de Mastodon el 12-ago, con otro campo.
+ *
+ * ## ⚠️ `soloLectura`: referenciar no es lo mismo que desatachar
+ *
+ * `results[]` de un post es un REGISTRO HISTÓRICO: dice a qué cuenta se
+ * publicó cada fila. Tiene que contar para encontrar consumidores —que salte
+ * el 409— pero reescribirlo al desatachar sería falsear lo que pasó: una
+ * publicación que SÍ ocurrió quedaría sin decir con qué cuenta.
+ *
+ * Sin esta marca, ampliar la lista habría arreglado el borrado silencioso y
+ * roto el historial en el mismo movimiento.
  */
 exports.CREDENTIAL_REF_SHAPES = [
     { kind: 'scalar', path: 'credentialId' },
@@ -55,6 +84,16 @@ exports.CREDENTIAL_REF_SHAPES = [
     { kind: 'array', path: 'extraCredentialIds' },
     { kind: 'map', path: 'credentialIds' },
     { kind: 'map', path: 'serviceConfig.social_media.credentialIds' },
+    { kind: 'arrayDeObjetos', path: 'tools', campo: 'credentialId' },
+    { kind: 'scalar', path: 'audioTranscribeCredentialId' },
+    { kind: 'scalar', path: 'embedding.credentialId' },
+    { kind: 'scalar', path: 'backend.config.credentialId' },
+    {
+        kind: 'arrayDeObjetos',
+        path: 'results',
+        campo: 'credentialId',
+        soloLectura: true,
+    },
 ];
 const mismoId = (v, id) => v !== null && v !== undefined && String(v) === id;
 /** Lee un camino con puntos. Devuelve `undefined` si algo del medio falta. */
@@ -74,13 +113,19 @@ function leerCamino(doc, path) {
  * formas conviven en datos reales (`credentialIds` está declarado como
  * `Record<string, string[] | string>` justamente por eso).
  */
-function valorReferencia(valor, id, kind) {
+function valorReferencia(valor, id, forma) {
     if (valor === null || valor === undefined)
         return false;
-    if (kind === 'scalar')
+    if (forma.kind === 'scalar')
         return mismoId(valor, id);
-    if (kind === 'array')
+    if (forma.kind === 'array')
         return Array.isArray(valor) && valor.some((v) => mismoId(v, id));
+    if (forma.kind === 'arrayDeObjetos') {
+        return (Array.isArray(valor) &&
+            valor.some((o) => o !== null &&
+                typeof o === 'object' &&
+                mismoId(o[forma.campo], id)));
+    }
     // map
     if (typeof valor !== 'object' || Array.isArray(valor))
         return false;
@@ -88,7 +133,7 @@ function valorReferencia(valor, id, kind) {
 }
 /** 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));
+    return exports.CREDENTIAL_REF_SHAPES.filter((forma) => valorReferencia(leerCamino(doc, forma.path), id, forma));
 }
 /**
  * El valor que hay que dejar en el campo al quitar la credencial.
@@ -100,7 +145,22 @@ function formasQueReferencian(doc, id) {
  * con `[]` haría que el trigger siguiera anunciando que vigila Mastodon sin
  * ninguna cuenta con la que hacerlo.
  */
-function valorTrasDesatacar(valor, id, kind) {
+function valorTrasDesatacar(valor, id, forma) {
+    const kind = forma.kind;
+    if (kind === 'arrayDeObjetos') {
+        /* ⚠️ Se le quita el id a la fila, pero la fila SE QUEDA. Borrar la tool
+           entera sería borrarle al usuario algo que él configuró porque nosotros
+           borramos otra cosa; sin credencial dará un error con nombre, que es lo
+           que toca. */
+        if (!Array.isArray(valor))
+            return null;
+        const resto = valor.map((o) => o !== null &&
+            typeof o === 'object' &&
+            mismoId(o[forma.campo], id)
+            ? { ...o, [forma.campo]: null }
+            : o);
+        return resto.length > 0 ? resto : null;
+    }
     if (kind === 'scalar')
         return null;
     if (kind === 'array') {
@@ -141,9 +201,19 @@ exports.UNSET_MARCADOR_DETACH = {
     credentialDetachedName: '',
 };
 /** ¿Este valor trae al menos una credencial puesta? */
-function valorTieneCredencial(valor, kind) {
+function valorTieneCredencial(valor, forma) {
     if (valor === null || valor === undefined || valor === '')
         return false;
+    const kind = forma.kind;
+    if (kind === 'arrayDeObjetos') {
+        return (Array.isArray(valor) &&
+            valor.some((o) => {
+                if (o === null || typeof o !== 'object')
+                    return false;
+                const v = o[forma.campo];
+                return v !== null && v !== undefined && v !== '';
+            }));
+    }
     if (kind === 'scalar')
         return true;
     if (kind === 'array')
@@ -166,7 +236,7 @@ function valorTieneCredencial(valor, kind) {
 function tieneAlgunaCredencial(doc) {
     if (!doc || typeof doc !== 'object')
         return false;
-    return exports.CREDENTIAL_REF_SHAPES.some((forma) => valorTieneCredencial(leerCamino(doc, forma.path), forma.kind));
+    return exports.CREDENTIAL_REF_SHAPES.some((forma) => valorTieneCredencial(leerCamino(doc, forma.path), forma));
 }
 /**
  * ¿Hay que quitarle el marcador a este documento?

package/dist/execute-with-iteration.d.ts

@@ -5,14 +5,7 @@
  * _meta.iterable and automatically iterates, aggregating results.
  * Nodes never see _meta — they receive clean individual payloads.
  */
-type SingleExecutor = (payload: Record<string, unknown>) => Promise<{
-    statusCode: number;
-    responseBody: string;
-    latencyMs: number;
-}>;
-export declare function executeWithIteration(payload: Record<string, unknown>, executeSingle: SingleExecutor): Promise<{
-    statusCode: number;
-    responseBody: string;
-    latencyMs: number;
-}>;
+import type { NodeResult } from './retry-transient';
+type SingleExecutor = (payload: Record<string, unknown>) => Promise<NodeResult>;
+export declare function executeWithIteration(payload: Record<string, unknown>, executeSingle: SingleExecutor): Promise<NodeResult>;
 export {};

package/dist/execute-with-iteration.js

@@ -14,7 +14,46 @@ async function executeWithIteration(payload, executeSingle) {
         const items = payload[meta.iterateField] ?? [];
         const results = [];
         let totalLatency = 0;
-        let lastStatus = 200;
+        /* El estado que se reporta hacia arriba.
+         *
+         * ⚠️ Antes se guardaba el del ÚLTIMO item, a secas. Cuatro llamadas donde
+         * la 2ª daba 500 y la 4ª daba 200 se reportaban como ÉXITO —el fallo
+         * desaparecía sin dejar rastro— y al revés, tres éxitos y un fallo al final
+         * teñían de rojo la tanda entera.
+         *
+         * Ahora manda el PRIMER fallo; si no hubo ninguno se conserva el último
+         * estado, que es exactamente lo que ya se devolvía cuando todo iba bien.
+         *
+         * ## Lo que esto NO pisa, y lo que sí
+         *
+         * NO pisa el «Never error on non-2xx» del nodo HTTP, y el motivo es el
+         * orden de anidamiento, no una casualidad: la máscara vive en
+         * `executeOnce`, la función MÁS interna —dentro del retry, que a su vez
+         * está dentro de este bucle—, y axios va con `validateStatus: () => true`,
+         * así que TODO código de estado pasa por ella antes de que nadie más lo
+         * vea. Aquí llega un 200 y `primerFallo` no se marca.
+         *
+         * ⚠️ Lo que sí cambia, y conviene saberlo: el ajuste sólo enmascara
+         * `response.status >= 400`. Un timeout, un DNS caído o un fallo de
+         * configuración salen por otro camino (500 del `catch`, 520 del guion de
+         * pre-petición o del firmado) sin pasar por la máscara. Antes esos se
+         * tragaban si no eran el último item; ahora detienen la tanda aunque el
+         * ajuste esté encendido. Es el comportamiento correcto —un timeout no es
+         * «un non-2xx que quiero ignorar»— pero es un cambio observable. */
+        let ultimoStatus = 200;
+        let primerFallo = null;
+        /* Plano de control. No viaja en el payload, pero decide qué hace el Loop
+         * cuando una iteración falla.
+         *
+         * ⚠️ La agregación construía un objeto literal nuevo y estos dos campos se
+         * caían por el camino. Daba casi igual mientras el fallo de enmedio se
+         * perdía, porque esa rama no se alcanzaba; en cuanto manda el primer
+         * fallo, `node-lifecycle` lee `_retriedTransient` para degradar la política
+         * `retry` a `skip`, y sin él RE-DESPACHA la iteración entera: se reenvían
+         * también los items que ya habían salido bien. Un 429 que ya quemó sus
+         * tres intentos le llegaba al Loop como «esto ni se ha reintentado». */
+        let algunoReintento = false;
+        let esperaPedida;
         for (const item of items) {
             const clean = typeof item === 'object' && item !== null
                 ? { ...item }
@@ -22,7 +61,17 @@ async function executeWithIteration(payload, executeSingle) {
             delete clean._meta;
             const res = await executeSingle(clean);
             totalLatency += res.latencyMs;
-            lastStatus = res.statusCode;
+            ultimoStatus = res.statusCode;
+            if (primerFallo === null && res.statusCode >= 400) {
+                primerFallo = res.statusCode;
+            }
+            if (res._retriedTransient)
+                algunoReintento = true;
+            if (typeof res.retryAfterMs === 'number') {
+                /* El mayor de los que se pidieron: esperar MENOS de lo que el servidor
+                   dijo sólo quema un intento. */
+                esperaPedida = Math.max(esperaPedida ?? 0, res.retryAfterMs);
+            }
             try {
                 const parsed = JSON.parse(res.responseBody);
                 // If executor returns an array, spread its items instead of nesting [[...]]
@@ -38,15 +87,23 @@ async function executeWithIteration(payload, executeSingle) {
                 results.push(res.responseBody);
             }
         }
+        const estadoDeLaTanda = primerFallo ?? ultimoStatus;
+        /* Se omiten cuando no hay nada que decir, para no ensuciar el resultado con
+           `_retriedTransient: false` donde antes no había clave ninguna. */
+        const planoDeControl = {
+            ...(algunoReintento ? { _retriedTransient: true } : {}),
+            ...(esperaPedida !== undefined ? { retryAfterMs: esperaPedida } : {}),
+        };
         // Single result from single iteration → unwrap as plain object
         if (results.length === 1 &&
             typeof results[0] === 'object' &&
             results[0] !== null) {
             const single = { _meta: { iterable: false, count: 1 }, ...results[0] };
             return {
-                statusCode: lastStatus,
+                statusCode: estadoDeLaTanda,
                 responseBody: JSON.stringify(single),
                 latencyMs: totalLatency,
+                ...planoDeControl,
             };
         }
         const aggregated = {
@@ -54,9 +111,10 @@ async function executeWithIteration(payload, executeSingle) {
             results,
         };
         return {
-            statusCode: lastStatus,
+            statusCode: estadoDeLaTanda,
             responseBody: JSON.stringify(aggregated),
             latencyMs: totalLatency,
+            ...planoDeControl,
         };
     }
     // Single item — strip _meta and execute

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/node-sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "El SDK de un nodo de HostWebhook: ciclo de vida, ejecución con iteración, reintentos, filtros y validación de esquema — lo que comparten la api y el futuro servicio de nodos",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",