@hostwebhook/platform-contracts 0.3.1 → 0.5.0

package/dist/servicios/motor-de-ejecucion.d.ts

@@ -75,11 +75,56 @@ export interface EventoDeCorrida {
     headers?: unknown;
     sourceIp?: unknown;
     webhookId?: unknown;
+    /** El cuerpo del evento. Lo leen diez sitios. */
+    payload?: unknown;
+    /**
+     * 🔥 El paso en una cadena de webhooks encadenados. Lo lee
+     * `onDeliveryResult` para decidir si sigue la cadena, y sin él la cadena se
+     * corta en el primer salto **sin error**.
+     */
+    chainStep?: unknown;
 }
 /** Y de un webhook: dos campos. */
+/**
+ * Lo que el motor lee de un webhook.
+ *
+ * 🔥 Esto declaraba DOS campos —`id` y `name`— y el motor lee dieciocho. El
+ * hueco no era cosmético: `onDeliveryResult` implementa el CORTACIRCUITOS
+ * leyendo `circuitState`, `healthStatus` y los contadores de medio abierto. Con
+ * el tipo estrecho, quien construyera el objeto mirando esta interfaz mandaría
+ * sólo `id` y `name`, los cinco campos llegarían `undefined`, y
+ * `circuitState === 'open'` sería SIEMPRE falso.
+ *
+ * O sea: el cortacircuitos dejaría de saltar y de recuperarse, en silencio y
+ * con todo en verde. Se vio al ir a poner `onDeliveryResult` en el contrato.
+ *
+ * ⚠️ Todo opcional salvo `id`: es un añadido, no un cambio de forma.
+ */
 export interface WebhookDeCorrida {
     id: unknown;
     name?: unknown;
+    _id?: unknown;
+    organizationId?: unknown;
+    workspaceId?: unknown;
+    userId?: unknown;
+    entity?: unknown;
+    targetUrl?: unknown;
+    retryStrategy?: unknown;
+    retryDelaySeconds?: unknown;
+    maxRetries?: unknown;
+    delaySeconds?: unknown;
+    priority?: unknown;
+    circuitState?: unknown;
+    healthStatus?: unknown;
+    halfOpenSuccesses?: unknown;
+    halfOpenSuccessThreshold?: unknown;
+    autoReplayOnRecovery?: unknown;
+}
+/** Lo que devolvió una entrega. */
+export interface ResultadoDeEntrega {
+    success: boolean;
+    statusCode: number;
+    responseBody: string;
 }
 /**
  * El contexto de la corrida.
@@ -99,7 +144,30 @@ export interface ContextoDeCorrida {
     orgId: string;
     backoffCapMs?: number;
     maxNodeCycles?: number;
+    /**
+     * ⚠️ `Record`, no `Map`, y es la única diferencia deliberada con el
+     * `PipelineContext` del motor: **un `Map` se serializa como `{}`**. Este
+     * contexto cruza un cable, así que el contrato pide la forma que sobrevive.
+     * Quien lo pase desde dentro tiene que aplanarlo (`Object.fromEntries`).
+     */
     nodeVisitCounts?: Record<string, number>;
+    /** Marca la corrida como prueba: no cuenta para el historial de producción. */
+    isTest?: boolean;
+    /** En una prueba, propagar por todos los nodos de aguas abajo. */
+    propagateNodes?: boolean;
+    /** 🔥 Tope contra la propagación infinita. Sin esto no hay red. */
+    propagationDepth?: number;
+    /** Saltarse la entrega primaria (despachos que sólo notifican). */
+    skipPrimaryDelivery?: boolean;
+    /** 🔥 Estado del bucle: con él, los nodos de dentro escriben checkpoints. */
+    loopStateId?: string;
+    /** Payloads de workspace que pisa el bucle en cada vuelta. */
+    wsPayloadOverrides?: Record<string, Record<string, unknown>>;
+    /**
+     * 🔥 Pila de llamadas entre workspaces (`"nodeType:nodeId"`). Es lo que
+     * detecta los ciclos de FlowLinks y aplica el `maxFlowCallDepth` del plan.
+     */
+    callStack?: string[];
 }
 /** Una espera pendiente, de lo que el motor le lee. */
 export interface EsperaPendiente {
@@ -169,6 +237,35 @@ export interface DespachoDelMotor {
         comment?: string;
         [k: string]: unknown;
     }): Promise<void>;
+    /**
+     * La vuelta siguiente de un bucle, cuando la trae un trabajo de la cola.
+     *
+     * ⚠️ No es lo mismo que `dispatchOutputNodes`: el bucle lleva su propio
+     * estado —`loopStateId` en el contexto— y esta llamada continúa una iteración
+     * concreta, no arranca un despacho.
+     */
+    handleLoopIteration(event: EventoDeCorrida, webhook: WebhookDeCorrida, loopNode: unknown, payload: Record<string, unknown>, ctx: ContextoDeCorrida, depth: number): Promise<void>;
+    /** Vacía el buffer de un agregador cuando le toca. */
+    handleAggregatorFlush(data: {
+        aggregatorNodeId: string;
+        groupKey: string;
+        webhookId: string;
+        orgId: string;
+        propagationDepth: number;
+        backoffCapMs?: number;
+        [k: string]: unknown;
+    }): Promise<void>;
+    /**
+     * Lo que pasa DESPUÉS de entregar: nodos de aguas abajo y cortacircuitos.
+     *
+     * 🔥 Es el que obligó a ensanchar `WebhookDeCorrida`. Lee `circuitState`,
+     * `healthStatus` y los contadores de medio abierto para decidir si el
+     * circuito se abre, se cierra o sigue igual — con el tipo estrecho de antes,
+     * esos campos llegaban `undefined` y el cortacircuitos no hacía nada.
+     */
+    onDeliveryResult(event: EventoDeCorrida, webhook: WebhookDeCorrida, result: ResultadoDeEntrega, ctx: ContextoDeCorrida & {
+        isRouter?: boolean;
+    }): Promise<void>;
     /** Reanuda cuando a un merge se le acaba el tiempo de espera. */
     resumeAfterMergeTimeout(mergeState: EstadoDeMerge, mergeNode: NodoDeMerge): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/platform-contracts",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Contratos compartidos entre los servicios de HostWebhook: addons del plan, identidad interna, y las formas que cruzan una frontera de red",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",