@hostwebhook/node-sdk 0.1.0

package/dist/code-runner.d.ts

@@ -0,0 +1,20 @@
+import { type CodeRunnerContext, type CodeRunnerResult } from './pre-request-pool';
+/**
+ * Un fallo del CÓDIGO del inquilino, no del transporte.
+ *
+ * Se distingue a propósito: que el código del usuario lance no es motivo para
+ * caer al hijo — allí lanzaría igual, y reintentarlo sólo duplicaría efectos.
+ * Sólo el transporte justifica el respaldo.
+ */
+export declare class CodeNodeError extends Error {
+    readonly logs: string[];
+    constructor(message: string, logs: string[], name?: string);
+}
+/**
+ * Ejecutar el código, por el camino más seguro que esté disponible.
+ *
+ * Devuelve la misma forma corra donde corra — el llamante no se entera de
+ * cuál fue, que es la condición para que el respaldo sea un respaldo y no
+ * otro comportamiento.
+ */
+export declare function runTenantCode(code: string, ctx: CodeRunnerContext, timeoutMs: number): Promise<CodeRunnerResult>;

package/dist/code-runner.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeNodeError = void 0;
+exports.runTenantCode = runTenantCode;
+const common_1 = require("@nestjs/common");
+const pre_request_pool_1 = require("./pre-request-pool");
+/**
+ * Dónde corre el código de un nodo de código.
+ *
+ * ## Por qué hay dos sitios
+ *
+ * Sacarlo del proceso de la API quitó los secretos y el disco: el hijo arranca
+ * con entorno vacío y, donde el runtime lo soporta, con ficheros denegados.
+ * Pero el modelo de permisos de Node NO cubre la red — medido: un escape del
+ * vm dentro del hijo encuentra `require('http')` disponible. Y ese hijo corre
+ * DENTRO de la red privada.
+ *
+ * El worker de Cloudflare no arregla el sandbox, arregla la POSICIÓN: allí no
+ * hay red privada que alcanzar. Por eso es el camino preferido.
+ *
+ * ## El respaldo, y por qué incomoda
+ *
+ * Si el worker no responde se cae al hijo. Eso protege la disponibilidad y
+ * cede exactamente lo que el worker vino a comprar, así que no puede ser
+ * silencioso ni permanente:
+ *
+ *   - cada caída se registra a nivel ERROR, con el motivo. Un fallo sostenido
+ *     tiene que verse, no acumularse;
+ *   - `CODE_RUNNER_STRICT=1` lo desactiva. Con eso puesto, si el worker falla
+ *     el nodo falla — que es lo que querrás en producción el día que confíes
+ *     en el worker, porque así la seguridad deja de depender de que un
+ *     servicio externo esté sano.
+ *
+ * Sin worker configurado no hay aviso ninguno: es el caso de desarrollo, y
+ * ahí el hijo es el camino normal, no una degradación.
+ */
+const logger = new common_1.Logger('CodeRunner');
+/** Margen sobre el timeout del propio código, para distinguir "tu bucle no
+ *  terminó" de "el worker no contestó". */
+const MARGEN_DE_RED_MS = 3_000;
+function urlDelWorker() {
+    return (process.env.CLOUDFLARE_CODE_RUNNER_URL ?? '').trim() || null;
+}
+function secretoDelWorker() {
+    return (process.env.CLOUDFLARE_CODE_RUNNER_SECRET ?? '').trim() || null;
+}
+/** Con esto puesto, un worker caído hace fallar el nodo en vez de caer al hijo. */
+function esEstricto() {
+    const raw = (process.env.CODE_RUNNER_STRICT ?? '').trim().toLowerCase();
+    return raw === '1' || raw === 'true';
+}
+/**
+ * Un fallo del CÓDIGO del inquilino, no del transporte.
+ *
+ * Se distingue a propósito: que el código del usuario lance no es motivo para
+ * caer al hijo — allí lanzaría igual, y reintentarlo sólo duplicaría efectos.
+ * Sólo el transporte justifica el respaldo.
+ */
+class CodeNodeError extends Error {
+    logs;
+    constructor(message, logs, name = 'Error') {
+        super(message);
+        this.logs = logs;
+        this.name = name;
+    }
+}
+exports.CodeNodeError = CodeNodeError;
+async function correrEnWorker(url, secreto, code, ctx, timeoutMs) {
+    const abort = new AbortController();
+    const corte = setTimeout(() => abort.abort(), timeoutMs + MARGEN_DE_RED_MS);
+    let res;
+    try {
+        res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${secreto}`,
+            },
+            body: JSON.stringify({
+                code,
+                payload: ctx.payload,
+                workspacePayloads: ctx.workspacePayloads,
+                timeoutMs,
+            }),
+            signal: abort.signal,
+        });
+    }
+    finally {
+        clearTimeout(corte);
+    }
+    if (!res.ok && res.status !== 200) {
+        // 401, 5xx, un 1102 de la plataforma… todo esto es transporte.
+        throw new Error(`code runner worker responded ${res.status}`);
+    }
+    const cuerpo = (await res.json());
+    const logs = Array.isArray(cuerpo.logs) ? cuerpo.logs.map(String) : [];
+    if (cuerpo.ok === true) {
+        return { output: cuerpo.output ?? null, logs };
+    }
+    // El worker contestó y dice que el código falló. Eso es un resultado, no una
+    // avería: se propaga tal cual y no se reintenta en el hijo.
+    throw new CodeNodeError(String(cuerpo.message ?? 'Code node failed'), logs, String(cuerpo.name ?? 'Error'));
+}
+/**
+ * Ejecutar el código, por el camino más seguro que esté disponible.
+ *
+ * Devuelve la misma forma corra donde corra — el llamante no se entera de
+ * cuál fue, que es la condición para que el respaldo sea un respaldo y no
+ * otro comportamiento.
+ */
+async function runTenantCode(code, ctx, timeoutMs) {
+    const url = urlDelWorker();
+    const secreto = secretoDelWorker();
+    if (!url || !secreto) {
+        // Desarrollo, o antes de desplegar el worker. El hijo es el camino normal
+        // aquí, no una degradación, así que no se avisa de nada.
+        return (0, pre_request_pool_1.runCodeNodeInChild)(code, ctx, timeoutMs);
+    }
+    try {
+        return await correrEnWorker(url, secreto, code, ctx, timeoutMs);
+    }
+    catch (err) {
+        // El código del inquilino falló y el worker lo dijo. No es una avería.
+        if (err instanceof CodeNodeError)
+            throw err;
+        const motivo = err instanceof Error ? err.message : String(err);
+        if (esEstricto()) {
+            logger.error(`[code-runner] el worker no respondió y CODE_RUNNER_STRICT está puesto — el nodo falla: ${motivo}`);
+            throw new Error(`Code runner unavailable: ${motivo}`);
+        }
+        // A nivel ERROR a propósito: esto devuelve la ejecución a la red privada,
+        // que es justo lo que el worker vino a evitar. Un fallo sostenido tiene
+        // que doler en el panel, no acumularse en silencio.
+        logger.error(`[code-runner] el worker no respondió (${motivo}) — se ejecuta en el proceso hijo local. ` +
+            'Eso devuelve el código de inquilino a la red privada; si se repite, míralo.');
+        return (0, pre_request_pool_1.runCodeNodeInChild)(code, ctx, timeoutMs);
+    }
+}

package/dist/contratos.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Los tipos que el SDK necesita del mundo de fuera, declarados AQUÍ.
+ *
+ * ## Por qué no se importan
+ *
+ * Porque el paquete no puede alcanzar `src/` de la api. Los siete vivían en
+ * entidades de Mongoose y servicios de Nest —`webhook.entity`,
+ * `telemetry.service`, `user.entity`…— y llegaban por `import type`, que se
+ * borra al compilar. Dentro del monolito eso funcionaba; en un paquete, no.
+ *
+ * ## Se declara la superficie USADA, no la entidad entera
+ *
+ * Está medido, no adivinado: de `TelemetryService` sólo se llaman dos métodos;
+ * de `UserDocument` sólo se leen cuatro campos. Copiar la entidad completa
+ * traería `@Prop`, el esquema, y con ellos media aplicación.
+ *
+ * ⚠️ **La dirección de la dependencia se invierte.** A partir de aquí el
+ * contrato lo define el SDK y la api lo cumple: sus entidades reexportan
+ * estos tipos en vez de definirlos. Si alguien añade un campo en la entidad y
+ * no aquí, el SDK sencillamente no lo ve — que es lo correcto: el SDK no
+ * conoce las entidades de nadie.
+ */
+/**
+ * Los operadores que el SDK sabe EVALUAR, sacados de `filter-utils`.
+ *
+ * ⚠️ No coinciden con los `enum` de las entidades de la api, y esa es la
+ * lista buena: aquí vive el evaluador. Los enum de allá van de 7 a 32 segun
+ * la entidad —`webhook` admite 7 de estos 30— asi que hay filtros
+ * que el motor sabe resolver y la base de datos rechaza al guardar. Es un
+ * fallo de la api, anterior a este paquete, y se arregla aparte.
+ */
+export type FilterOperator = 'array_contains' | 'array_empty' | 'array_length_eq' | 'array_length_gt' | 'array_length_lt' | 'array_not_contains' | 'array_not_empty' | 'contains' | 'date_after' | 'date_before' | 'date_eq' | 'ends_with' | 'eq' | 'exists' | 'gt' | 'gte' | 'has_key' | 'is_empty' | 'is_false' | 'is_not_empty' | 'is_true' | 'lt' | 'lte' | 'matches_regex' | 'neq' | 'not_contains' | 'not_ends_with' | 'not_exists' | 'not_starts_with' | 'starts_with';
+export interface PayloadFilter {
+    field: string;
+    operator: FilterOperator;
+    value?: string;
+    enabled?: boolean;
+}
+export interface SchemaFieldConstraints {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: 'email' | 'url' | 'uuid' | 'iso-date';
+    min?: number;
+    max?: number;
+    enum?: string[];
+    minItems?: number;
+    maxItems?: number;
+}
+export interface SchemaField {
+    path: string;
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'any';
+    required: boolean;
+    constraints?: SchemaFieldConstraints;
+}
+/**
+ * `skipped` es un estado de primera y no un `failed` descafeinado: un paso que
+ * no llegó a correr porque el anterior falló no es lo mismo que uno que sí
+ * corrió y salió mal, y la pantalla necesita distinguirlos para enseñar dónde
+ * se cortó el flujo.
+ */
+export type RunStepStatus = 'success' | 'failed' | 'skipped';
+export interface PasoEjecutado {
+    organizationId: string;
+    correlationId: string;
+    nodeId: string;
+    nodeName?: string;
+    nodeType?: string;
+    status: RunStepStatus;
+    startedAt: Date;
+    durationMs: number;
+    error?: string;
+    /** El origen de la corrida, para poder abrirla en la primera fila. */
+    sourceId?: string;
+    sourceName?: string;
+    workspaceId?: string;
+    entrada?: unknown;
+    salida?: unknown;
+    metadata?: Record<string, unknown>;
+    /** Cómo se disparó la corrida. Ausente = producción. */
+    modo?: 'pipeline';
+}
+/** Quien anota los pasos. El SDK sólo necesita saber que existe el método. */
+export interface RegistradorDeHistorial {
+    registrarPaso(paso: PasoEjecutado): unknown;
+}
+/**
+ * De dónde viene una línea de registro. Es `string` a propósito y no una
+ * unión cerrada: cada tipo de nodo aporta el suyo, y una unión obligaría a
+ * publicar el paquete cada vez que nace un nodo.
+ */
+export type LogSource = string;
+/**
+ * Lo único que el ciclo de vida le pide a la telemetría.
+ *
+ * Dos métodos, medidos sobre `node-lifecycle`: `emit` para lo que puede
+ * perderse y `emitAndWait` para lo que no. El servicio real de la api tiene
+ * muchos más; ninguno se usa desde aquí.
+ */
+export interface EmisorDeTelemetria {
+    emit(...args: unknown[]): unknown;
+    emitAndWait(...args: unknown[]): Promise<unknown>;
+}
+/**
+ * Lo que `request-context` lee de `req.user`, y nada más.
+ *
+ * ⚠️ `__isApiKey` y `__apiKeyScopes` llevan doble guion bajo porque no son
+ * campos del documento: los pone la estrategia de autenticación al vuelo para
+ * distinguir una sesión del panel —que actúa por la cuenta entera— de una
+ * llave, que sólo tiene lo que se le acuñó.
+ */
+export interface IdentidadDePeticion {
+    _id: {
+        toString(): string;
+    };
+    organizationId?: {
+        toString(): string;
+    };
+    __isApiKey?: boolean;
+    __apiKeyScopes?: string[];
+}

package/dist/contratos.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Los tipos que el SDK necesita del mundo de fuera, declarados AQUÍ.
+ *
+ * ## Por qué no se importan
+ *
+ * Porque el paquete no puede alcanzar `src/` de la api. Los siete vivían en
+ * entidades de Mongoose y servicios de Nest —`webhook.entity`,
+ * `telemetry.service`, `user.entity`…— y llegaban por `import type`, que se
+ * borra al compilar. Dentro del monolito eso funcionaba; en un paquete, no.
+ *
+ * ## Se declara la superficie USADA, no la entidad entera
+ *
+ * Está medido, no adivinado: de `TelemetryService` sólo se llaman dos métodos;
+ * de `UserDocument` sólo se leen cuatro campos. Copiar la entidad completa
+ * traería `@Prop`, el esquema, y con ellos media aplicación.
+ *
+ * ⚠️ **La dirección de la dependencia se invierte.** A partir de aquí el
+ * contrato lo define el SDK y la api lo cumple: sus entidades reexportan
+ * estos tipos en vez de definirlos. Si alguien añade un campo en la entidad y
+ * no aquí, el SDK sencillamente no lo ve — que es lo correcto: el SDK no
+ * conoce las entidades de nadie.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/dto/output-node.dto.d.ts

@@ -0,0 +1,19 @@
+/** Common aliases LLMs and clients may send → canonical nodeType */
+export declare const NODE_TYPE_ALIASES: Record<string, string>;
+export declare function normalizeNodeType(type: string): string;
+export declare class OutputNodeDto {
+    nodeType: string;
+    nodeId: string;
+    /**
+     * Which port the edge leaves through — see
+     * common/output-node-ref.schema.ts. Optional on the wire: absent means
+     * `main`, which is what every edge written before Phase 1 meant.
+     *
+     * Not validated against a fixed list on purpose. Container-owned ports
+     * are `<kind>:<container id>`, so the valid set is per-document and a
+     * whitelist here would either be wrong or duplicate the entity.
+     */
+    port?: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+}

package/dist/dto/output-node.dto.js

@@ -0,0 +1,96 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutputNodeDto = exports.NODE_TYPE_ALIASES = void 0;
+exports.normalizeNodeType = normalizeNodeType;
+const class_validator_1 = require("class-validator");
+const class_transformer_1 = require("class-transformer");
+const node_types_1 = require("@hostwebhook/node-types");
+/** Common aliases LLMs and clients may send → canonical nodeType */
+exports.NODE_TYPE_ALIASES = {
+    mergeNode: 'merge',
+    approvalNode: 'approval',
+    filterNode: 'filter',
+    transformNode: 'transform',
+    delayNode: 'delay',
+    conditionalNode: 'conditional',
+    rateLimiterNode: 'rateLimiter',
+    aggregatorNode: 'aggregator',
+    cacheNode: 'cache',
+    schemaValidatorNode: 'schemaValidator',
+    email: 'emailAction',
+    http: 'httpAction',
+    mongo: 'mongoAction',
+    notification: 'notificationAction',
+    sheets: 'sheetsAction',
+    'scheduled-workflow': 'scheduledWorkflow',
+    scheduledwebhook: 'scheduledWorkflow',
+    aiNode: 'ai',
+    loopNode: 'loop',
+    splitNode: 'split',
+    markdownNode: 'markdown',
+    fileTransformNode: 'fileTransform',
+    calendar: 'calendarAction',
+    docs: 'docsAction',
+    firecrawl: 'firecrawlAction',
+    // Legacy alias — pre-2026-04 the source node was `voiceCall` (one
+    // per tool). The fold-voice-call-triggers migration replaced it with
+    // `voiceAgent` (one per agent, N output handles by sourceHandle=toolName).
+    // Old payloads / saved flows still send the literal "voiceCall" until
+    // the dashboard rewrites them on next save — normalise here so the
+    // pipeline doesn't reject inflight data.
+    voiceCall: 'voiceAgent',
+};
+function normalizeNodeType(type) {
+    return exports.NODE_TYPE_ALIASES[type] ?? type;
+}
+class OutputNodeDto {
+    nodeType;
+    nodeId;
+    /**
+     * Which port the edge leaves through — see
+     * common/output-node-ref.schema.ts. Optional on the wire: absent means
+     * `main`, which is what every edge written before Phase 1 meant.
+     *
+     * Not validated against a fixed list on purpose. Container-owned ports
+     * are `<kind>:<container id>`, so the valid set is per-document and a
+     * whitelist here would either be wrong or duplicate the entity.
+     */
+    port;
+    sourceHandle;
+    targetHandle;
+}
+exports.OutputNodeDto = OutputNodeDto;
+__decorate([
+    (0, class_transformer_1.Transform)(({ value }) => exports.NODE_TYPE_ALIASES[value] ?? value),
+    (0, class_validator_1.IsIn)(node_types_1.ALL_NODE_TYPES),
+    __metadata("design:type", String)
+], OutputNodeDto.prototype, "nodeType", void 0);
+__decorate([
+    (0, class_validator_1.IsMongoId)(),
+    __metadata("design:type", String)
+], OutputNodeDto.prototype, "nodeId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.MaxLength)(80),
+    __metadata("design:type", String)
+], OutputNodeDto.prototype, "port", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], OutputNodeDto.prototype, "sourceHandle", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], OutputNodeDto.prototype, "targetHandle", void 0);

package/dist/ensure-meta.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Backstop for the standardised `_meta` contract documented in
+ * `@hostwebhook/node-types` (`PayloadMeta`):
+ *
+ *   { iterable: boolean; count: number; iterateField?: string }
+ *
+ * Most pipeline / transform / fetch nodes set `_meta` explicitly. Action
+ * nodes that proxy a third-party API (slack/discord/telegram/whatsapp/
+ * etc.) emit the raw API response as their output, and the contract
+ * was easy to forget when adding a new operation. Calling `ensureMeta`
+ * right before JSON-stringifying the result guarantees every downstream
+ * consumer (Limit / Loop / Filter / Aggregator / `$()` cross-node refs)
+ * sees a contract-compliant payload.
+ *
+ * Behavior:
+ *   - If `output` already has a `_meta` field, returned unchanged.
+ *   - If not, wraps with the safest default: a single, non-iterable
+ *     object. Operations that DO return arrays should set
+ *     `_meta: { iterable: true, iterateField, count }` themselves —
+ *     this helper is the safety net, not a heuristic guesser.
+ */
+export declare function ensureMeta<T extends Record<string, unknown> | null | undefined>(output: T): Record<string, unknown>;

package/dist/ensure-meta.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureMeta = ensureMeta;
+/**
+ * Backstop for the standardised `_meta` contract documented in
+ * `@hostwebhook/node-types` (`PayloadMeta`):
+ *
+ *   { iterable: boolean; count: number; iterateField?: string }
+ *
+ * Most pipeline / transform / fetch nodes set `_meta` explicitly. Action
+ * nodes that proxy a third-party API (slack/discord/telegram/whatsapp/
+ * etc.) emit the raw API response as their output, and the contract
+ * was easy to forget when adding a new operation. Calling `ensureMeta`
+ * right before JSON-stringifying the result guarantees every downstream
+ * consumer (Limit / Loop / Filter / Aggregator / `$()` cross-node refs)
+ * sees a contract-compliant payload.
+ *
+ * Behavior:
+ *   - If `output` already has a `_meta` field, returned unchanged.
+ *   - If not, wraps with the safest default: a single, non-iterable
+ *     object. Operations that DO return arrays should set
+ *     `_meta: { iterable: true, iterateField, count }` themselves —
+ *     this helper is the safety net, not a heuristic guesser.
+ */
+function ensureMeta(output) {
+    if (output &&
+        typeof output === 'object' &&
+        output._meta) {
+        return output;
+    }
+    return {
+        _meta: { iterable: false, count: 1 },
+        ...(output ?? {}),
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Infrastructure-level iteration wrapper.
+ *
+ * Nodes only implement single-item execution. This helper detects
+ * _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;
+}>;
+export {};

package/dist/execute-with-iteration.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Infrastructure-level iteration wrapper.
+ *
+ * Nodes only implement single-item execution. This helper detects
+ * _meta.iterable and automatically iterates, aggregating results.
+ * Nodes never see _meta — they receive clean individual payloads.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWithIteration = executeWithIteration;
+async function executeWithIteration(payload, executeSingle) {
+    const meta = payload._meta;
+    if (meta?.iterable && meta.iterateField) {
+        const items = payload[meta.iterateField] ?? [];
+        const results = [];
+        let totalLatency = 0;
+        let lastStatus = 200;
+        for (const item of items) {
+            const clean = typeof item === 'object' && item !== null
+                ? { ...item }
+                : { value: item };
+            delete clean._meta;
+            const res = await executeSingle(clean);
+            totalLatency += res.latencyMs;
+            lastStatus = res.statusCode;
+            try {
+                const parsed = JSON.parse(res.responseBody);
+                // If executor returns an array, spread its items instead of nesting [[...]]
+                if (Array.isArray(parsed)) {
+                    for (const entry of parsed)
+                        results.push(entry);
+                }
+                else {
+                    results.push(parsed);
+                }
+            }
+            catch {
+                results.push(res.responseBody);
+            }
+        }
+        // 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,
+                responseBody: JSON.stringify(single),
+                latencyMs: totalLatency,
+            };
+        }
+        const aggregated = {
+            _meta: { iterable: true, iterateField: 'results', count: results.length },
+            results,
+        };
+        return {
+            statusCode: lastStatus,
+            responseBody: JSON.stringify(aggregated),
+            latencyMs: totalLatency,
+        };
+    }
+    // Single item — strip _meta and execute
+    const clean = { ...payload };
+    delete clean._meta;
+    return executeSingle(clean);
+}

package/dist/filter-utils.d.ts

@@ -0,0 +1,22 @@
+import type { PayloadFilter } from './contratos';
+export declare function getNestedValue(obj: unknown, path: string): unknown;
+export interface FilterResolveOpts {
+    /**
+     * @deprecated Sin efecto: el motor de plantillas retiró el evaluador de JS.
+     * Se mantiene el campo para no obligar a tocar todos los llamantes a la vez.
+     */
+    allowJs?: boolean;
+    workspacePayloads?: Record<string, Record<string, unknown>>;
+}
+export declare function evaluateFilters(filters: PayloadFilter[], payload: unknown, mode?: 'and' | 'or', opts?: FilterResolveOpts): boolean;
+/**
+ * Evaluate filters against a payload that may be iterable.
+ * If iterable: filters each item, returns a new iterable payload with only passing items.
+ * If not iterable: returns { passed, payload } with the original payload.
+ */
+export declare function evaluateFiltersIterable(filters: PayloadFilter[], payload: Record<string, unknown>, mode?: 'and' | 'or', outputAsSingle?: boolean, opts?: FilterResolveOpts): {
+    passed: boolean;
+    resultPayload: Record<string, unknown>;
+    totalItems: number;
+    passedItems: number;
+};