@hostwebhook/platform-contracts 0.4.0 → 0.6.0

package/dist/servicios/historial-de-corridas.d.ts

@@ -68,6 +68,38 @@ export interface GrabadorDeHistorial {
      * tiene que garantizarlo también.
      */
     cerrar(correlationId: string): void;
+    /**
+     * Sella la versión del flujo y devuelve su huella, o `null` si no hay flujo
+     * que sellar.
+     *
+     * ## 🔥 Por qué está en el contrato y no se calcula donde se graba
+     *
+     * La huella ES la forma del flujo, y la forma se lee del LIENZO, que hoy
+     * vive en el gateway. Sin lienzo no hay huella, y no se puede inventar.
+     *
+     * Cuando hw-nodes empezó a grabar el historial por su cuenta, esta llamada
+     * se quedó fuera — y el efecto no era «esta corrida pierde su foto»:
+     * `asegurarVersion` no CONSULTA la versión, la **CREA**. El que graba el paso
+     * es el único que la llama, así que sin ella **deja de haber fotos** y el
+     * historial de versiones del flujo se congela en la última que selló el
+     * gateway.
+     *
+     * ## ⚠️ Es `Promise`, a diferencia de los otros dos
+     *
+     * `registrarPaso` y `cerrar` son `void` porque corren en el camino caliente
+     * de cada paso. Éste no: se llama **una vez por corrida** —quien lo
+     * implemente debe recordar el resultado por `correlationId`— y el que graba
+     * necesita la huella para escribirla en la fila. Un `void` aquí obligaría a
+     * escribir la corrida sin huella y volver a por ella después.
+     *
+     * ⚠️ Y devuelve `null` de verdad cuando no hay nada que sellar (sin
+     * `workspaceId`, o si el lienzo falla). `null` NO es «reusa la última»:
+     * escribir una huella que no es la de esa corrida se lee peor que no tener
+     * ninguna, porque nadie sospecha de ella.
+     */
+    sellarVersion(orgId: string, workspaceId?: string, 
+    /** De qué nodo salió la corrida. Decide QUÉ flujo se sella. */
+    sourceId?: string): Promise<string | null>;
 }
 /**
  * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.

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.
@@ -192,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.4.0",
+  "version": "0.6.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",