@hostwebhook/platform-contracts 0.1.0 → 0.3.0

package/dist/servicios/telemetria.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Lo que un nodo apunta en el registro. Una sola operación.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. Después del #459 quedaban 16 ficheros de `nodes/`
+ * importando `TelemetryService`, más tres del motor en `common/` —que viaja
+ * con ellos—. Los 19 lo usan para **lo mismo**: `emit`.
+ *
+ * `TelemetryService` arrastra la colección de logs, su conexión de Mongo
+ * propia y el gateway de sockets que empuja la fila al panel en vivo. Nada de
+ * eso puede vivir en `hw-nodes`: el registro es del gateway, y lo que el nodo
+ * necesita es poder DECIR lo que ha pasado.
+ *
+ * ## Tres métodos, y medidos
+ *
+ * En `nodes/` el inventario dio **uno solo** —`emit`— en 15 de los 16
+ * ficheros. El que sobraba (`ai-nodes.controller`) no lo llamaba: se lo
+ * pasaba al probador, y para eso ya existe la bandera `conTelemetria` desde
+ * el #458.
+ *
+ * ⚠️ Pero el inventario iba apuntado sólo a `nodes/`, y el motor vive en
+ * `common/`, que viaja con ellos. Al compilar salieron dos métodos más:
+ * `hasRecentSuccess` y `emitAndWait`. Los dos son de la recuperación de
+ * caídas, no del registro: sin ellos un nodo caro se re-ejecuta. Lo cazó tsc,
+ * no yo — la lección de siempre, con el barrido mal apuntado.
+ *
+ * ⚠️ Y ahí apareció una regresión MÍA. El #459 le quitó a
+ * `code-nodes.controller` el parámetro `telemetry` y su `super()`, pero dejó
+ * en pie un `this.telemetry` en la ruta `:id/test` escrita a mano. Desde
+ * entonces valía `undefined`, así que un paso de Run Pipeline sobre un Code
+ * node **no anotaba nada** — justo el comportamiento que el #459 decía haber
+ * conservado. No lo vio tsc porque la clase base del factory está tipada como
+ * `=> any`: dentro de una subclase, `this.loquesea` compila.
+ *
+ * ## Los campos son los que se usan
+ *
+ * El esquema `TelemetryLog` tiene ~20 campos. Se contaron los que aparecen de
+ * verdad en las 67 llamadas de `nodes/` y las 53 de `common/`: son quince.
+ * Fuera quedan `timestamp` —lo pone el gateway si falta—, `correlationId` y
+ * los dos de voz, que nadie de este lado escribe.
+ *
+ * ## Cómo viaja
+ *
+ * Bien: sólo datos planos. `TelemetryLog` es una clase con decoradores pero
+ * sin métodos, así que no hay documento vivo que aplanar; aun así el contrato
+ * lo declara aparte para no arrastrar `@nestjs/mongoose` a `hw-nodes`.
+ *
+ * ⚠️ `emit` devuelve `void` y no espera: por dentro hace `create(...).catch()`.
+ * Eso es deliberado y hay que conservarlo cuando esto sea una llamada de red —
+ * un nodo no puede quedarse esperando a que se escriba una fila de log, y
+ * menos aún fallar porque no se pudo escribir.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEMETRIA = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+exports.TELEMETRIA = 'TELEMETRIA';

package/dist/servicios/trazas-de-llm.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Lo que el AI Node apunta y consulta sobre sus llamadas al modelo.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `LlmTracesClientService` es
+ * un CLIENTE HTTP contra `hw-llm-traces`, que ya es un servicio aparte — el
+ * coste de los logs no vive en esta api. Aun así el nodo no debe conocer al
+ * cliente: arrastra su configuración, su reintento y su autenticación.
+ *
+ * ## Cómo viaja
+ *
+ * ⚠️ `emitTrace` devuelve `Promise<void>` y su llamante NO la espera: apuntar
+ * una traza no puede retrasar una respuesta del modelo ni tumbarla. Eso hay
+ * que conservarlo.
+ *
+ * Las dos consultas devuelven `unknown` a propósito — es lo que devuelve el
+ * cliente real, que reenvía lo que conteste el servicio de trazas sin darle
+ * forma. Tipar aquí una forma que allí no se garantiza sería inventarla.
+ */
+/** Lo que se apunta de una llamada al modelo. */
+export interface TrazaDeLlm {
+    traceId?: string;
+    spanId?: string;
+    startTime: string | Date;
+    endTime?: string | Date;
+    provider: 'openai' | 'anthropic' | 'google' | 'ollama' | 'mistral' | 'cohere' | 'custom';
+    model: string;
+    operation?: 'chat' | 'completion' | 'embedding' | 'image' | 'audio';
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadInputTokens?: number;
+    cacheCreationInputTokens?: number;
+    costUsd?: number;
+    status?: 'success' | 'error' | 'timeout';
+    error?: {
+        message?: string;
+        code?: string;
+        httpStatus?: number;
+    };
+    input?: {
+        messages?: unknown;
+        system?: unknown;
+        truncated?: boolean;
+    };
+    output?: {
+        content?: string;
+        toolCalls?: unknown[];
+        stopReason?: string;
+        truncated?: boolean;
+    };
+    metadata?: Record<string, unknown>;
+    aiNodeId?: string;
+    aiNodeName?: string;
+    eventId?: string;
+    workspaceId?: string;
+    invokedFrom?: string;
+    tags?: string[];
+}
+/** Los filtros con que la pantalla pide trazas. */
+export interface FiltrosDeTrazas {
+    limit?: number;
+    offset?: number;
+    aiNodeId?: string;
+    status?: 'success' | 'error' | 'timeout';
+    model?: string;
+    provider?: string;
+    startAfter?: string;
+    startBefore?: string;
+    search?: string;
+    sortBy?: 'startTime' | 'costUsd' | 'latencyMs';
+    sortOrder?: 'asc' | 'desc';
+}
+export interface TrazasDeLlm {
+    queryTraces(orgId: string, params: FiltrosDeTrazas): Promise<unknown>;
+    getTrace(orgId: string, traceId: string): Promise<unknown>;
+    /** ⚠️ No se espera. Ver la cabecera. */
+    emitTrace(orgId: string, traza: TrazaDeLlm): Promise<void>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const TRAZAS_DE_LLM = "TRAZAS_DE_LLM";

package/dist/servicios/trazas-de-llm.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Lo que el AI Node apunta y consulta sobre sus llamadas al modelo.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `LlmTracesClientService` es
+ * un CLIENTE HTTP contra `hw-llm-traces`, que ya es un servicio aparte — el
+ * coste de los logs no vive en esta api. Aun así el nodo no debe conocer al
+ * cliente: arrastra su configuración, su reintento y su autenticación.
+ *
+ * ## Cómo viaja
+ *
+ * ⚠️ `emitTrace` devuelve `Promise<void>` y su llamante NO la espera: apuntar
+ * una traza no puede retrasar una respuesta del modelo ni tumbarla. Eso hay
+ * que conservarlo.
+ *
+ * Las dos consultas devuelven `unknown` a propósito — es lo que devuelve el
+ * cliente real, que reenvía lo que conteste el servicio de trazas sin darle
+ * forma. Tipar aquí una forma que allí no se garantiza sería inventarla.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRAZAS_DE_LLM = void 0;
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.TRAZAS_DE_LLM = 'TRAZAS_DE_LLM';

package/dist/servicios/tuneles.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Lo que un nodo necesita de un túnel. Dos cosas, y por dos caminos distintos.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `nodes/` importaba `tunnels/` así:
+ *
+ *   5  `TcpTunnelPool`    el pool de reenviadores TCP
+ *   1  `TunnelsService`   para comprobar que un túnel es de la organización
+ *   1  `tunnels.module`   cableado
+ *
+ * ## ⚠️ Ésta NO es como las anteriores: el pool no puede mudarse
+ *
+ * Las once costuras anteriores acababan igual — el nodo pide por contrato y
+ * el día de la Fase 4 el contrato se convierte en una llamada HTTP. Aquí eso
+ * **no funciona**, y conviene decirlo antes de que alguien lo intente.
+ *
+ * `TcpTunnelPool.getOrCreate()` devuelve un reenviador que abre un **listener
+ * TCP en 127.0.0.1**, y lo que el nodo hace con él es apuntar ahí el driver de
+ * Mongo o de Postgres. Un `host:port` local sólo sirve dentro del proceso que
+ * lo abrió: pedirlo por red devolvería una dirección de otra máquina.
+ *
+ * Y el otro extremo tampoco se mueve: el pool se enchufa al servidor de
+ * sockets en el arranque —`webhook.gateway.ts` llama a `setGateway(this)`—
+ * porque los bytes del túnel viajan por la conexión que el cliente del
+ * usuario mantiene ABIERTA contra el gateway.
+ *
+ * O sea que el día de la mudanza hay dos salidas, y ninguna es «que el
+ * contrato hable HTTP»:
+ *
+ *   a) el pool se va con los nodos, y `hw-nodes` mantiene su propio enlace de
+ *      sockets con los clientes de túnel;
+ *   b) los nodos de base de datos por túnel se quedan en el gateway.
+ *
+ * Lo que este contrato SÍ consigue hoy es que `nodes/` deje de importar la
+ * clase —con su reenviador, sus sockets y su barrido— y que la decisión de
+ * arriba se pueda tomar cambiando un registro, no cinco ficheros.
+ *
+ * ## Por qué un registro y no un token
+ *
+ * ⚠️ Dos de los cuatro llamantes del pool no tienen DI: uno es un método
+ * `static` (`ExternalMongoBackend.resolveCollection`) y otro una función
+ * suelta (`resolvePool` en el backend de Postgres). Un token de Nest no llega
+ * ahí.
+ *
+ * El registro de módulo es el patrón que ya usa `probador-de-nodos.ts` desde
+ * el #458, por el mismo motivo. Lo enchufa un provider con `onModuleInit`
+ * —ver `tunnels/monta-el-tunel-local.ts`— para que se pueda PROBAR que el
+ * registro ocurrió: un registro no lo garantiza el compilador.
+ *
+ * El otro contrato, `TunelesDeLaOrganizacion`, sí va por token: su único
+ * llamante es un servicio con constructor.
+ */
+/** Una dirección a la que conectar un driver. Siempre en `127.0.0.1`. */
+export interface DireccionLocal {
+    host: string;
+    port: number;
+}
+/**
+ * Un túnel, visto desde el nodo: «dame una dirección local que salga ahí».
+ *
+ * Los cuatro llamantes hacían exactamente los mismos dos pasos —pedir el
+ * reenviador al pool y sacarle `getLocalAddress()`—, así que el contrato es
+ * uno solo.
+ */
+export interface TunelLocal {
+    /**
+     * ⚠️ Lanza si el túnel no está enchufado al gateway. Es lo que hace hoy
+     * `getOrCreate`, y hay que conservarlo: devolver una dirección que no
+     * escucha convertiría un error claro en un timeout del driver.
+     */
+    direccionLocalPara(tunnelId: string, host: string, port: number): Promise<DireccionLocal>;
+}
+/** Lo llama `tunnels/monta-el-tunel-local.ts` al arrancar. */
+export declare function registrarTunelLocal(t: TunelLocal): void;
+/** Para los tests, que montan el suyo. */
+export declare function olvidarTunelLocal(): void;
+export declare function hayTunelLocal(): boolean;
+/**
+ * ⚠️ Lanza con un mensaje que dice QUÉ falta. Si nadie registró, el nodo no
+ * puede abrir el túnel, y un `undefined` silencioso acabaría en un error del
+ * driver a diez fotogramas de distancia de la causa.
+ */
+export declare function obtenerTunelLocal(): TunelLocal;
+/** Lo que el nodo pregunta sobre a quién pertenece un túnel. */
+export interface TunelesDeLaOrganizacion {
+    /**
+     * ⚠️ Devuelve `unknown` y LANZA si el túnel no existe o no es de esa
+     * organización.
+     *
+     * `unknown` porque el servicio real devuelve el documento de Mongoose y su
+     * único llamante lo DESCARTA: sólo le importa si lanzó. Así el documento no
+     * cruza y el llamante no puede usarlo sin un cast.
+     *
+     * ⚠️ Y una nota para la Fase 4: ese llamante envuelve la llamada en un
+     * `catch` que lo convierte todo en «Tunnel not found». Hoy da igual —lo
+     * único que puede fallar es la consulta—, pero en cuanto esto sea una
+     * llamada de red, un corte de red se leerá como «el túnel no existe». Quien
+     * lo implemente por HTTP tiene que distinguir las dos cosas ahí.
+     */
+    asegurarQueEsDeLaOrganizacion(tunnelId: string, orgId: string): Promise<unknown>;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+export declare const TUNELES_DE_LA_ORGANIZACION = "TUNELES_DE_LA_ORGANIZACION";

package/dist/servicios/tuneles.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Lo que un nodo necesita de un túnel. Dos cosas, y por dos caminos distintos.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `nodes/` importaba `tunnels/` así:
+ *
+ *   5  `TcpTunnelPool`    el pool de reenviadores TCP
+ *   1  `TunnelsService`   para comprobar que un túnel es de la organización
+ *   1  `tunnels.module`   cableado
+ *
+ * ## ⚠️ Ésta NO es como las anteriores: el pool no puede mudarse
+ *
+ * Las once costuras anteriores acababan igual — el nodo pide por contrato y
+ * el día de la Fase 4 el contrato se convierte en una llamada HTTP. Aquí eso
+ * **no funciona**, y conviene decirlo antes de que alguien lo intente.
+ *
+ * `TcpTunnelPool.getOrCreate()` devuelve un reenviador que abre un **listener
+ * TCP en 127.0.0.1**, y lo que el nodo hace con él es apuntar ahí el driver de
+ * Mongo o de Postgres. Un `host:port` local sólo sirve dentro del proceso que
+ * lo abrió: pedirlo por red devolvería una dirección de otra máquina.
+ *
+ * Y el otro extremo tampoco se mueve: el pool se enchufa al servidor de
+ * sockets en el arranque —`webhook.gateway.ts` llama a `setGateway(this)`—
+ * porque los bytes del túnel viajan por la conexión que el cliente del
+ * usuario mantiene ABIERTA contra el gateway.
+ *
+ * O sea que el día de la mudanza hay dos salidas, y ninguna es «que el
+ * contrato hable HTTP»:
+ *
+ *   a) el pool se va con los nodos, y `hw-nodes` mantiene su propio enlace de
+ *      sockets con los clientes de túnel;
+ *   b) los nodos de base de datos por túnel se quedan en el gateway.
+ *
+ * Lo que este contrato SÍ consigue hoy es que `nodes/` deje de importar la
+ * clase —con su reenviador, sus sockets y su barrido— y que la decisión de
+ * arriba se pueda tomar cambiando un registro, no cinco ficheros.
+ *
+ * ## Por qué un registro y no un token
+ *
+ * ⚠️ Dos de los cuatro llamantes del pool no tienen DI: uno es un método
+ * `static` (`ExternalMongoBackend.resolveCollection`) y otro una función
+ * suelta (`resolvePool` en el backend de Postgres). Un token de Nest no llega
+ * ahí.
+ *
+ * El registro de módulo es el patrón que ya usa `probador-de-nodos.ts` desde
+ * el #458, por el mismo motivo. Lo enchufa un provider con `onModuleInit`
+ * —ver `tunnels/monta-el-tunel-local.ts`— para que se pueda PROBAR que el
+ * registro ocurrió: un registro no lo garantiza el compilador.
+ *
+ * El otro contrato, `TunelesDeLaOrganizacion`, sí va por token: su único
+ * llamante es un servicio con constructor.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TUNELES_DE_LA_ORGANIZACION = void 0;
+exports.registrarTunelLocal = registrarTunelLocal;
+exports.olvidarTunelLocal = olvidarTunelLocal;
+exports.hayTunelLocal = hayTunelLocal;
+exports.obtenerTunelLocal = obtenerTunelLocal;
+let tunelLocal = null;
+/** Lo llama `tunnels/monta-el-tunel-local.ts` al arrancar. */
+function registrarTunelLocal(t) {
+    tunelLocal = t;
+}
+/** Para los tests, que montan el suyo. */
+function olvidarTunelLocal() {
+    tunelLocal = null;
+}
+function hayTunelLocal() {
+    return tunelLocal !== null;
+}
+/**
+ * ⚠️ Lanza con un mensaje que dice QUÉ falta. Si nadie registró, el nodo no
+ * puede abrir el túnel, y un `undefined` silencioso acabaría en un error del
+ * driver a diez fotogramas de distancia de la causa.
+ */
+function obtenerTunelLocal() {
+    if (!tunelLocal) {
+        throw new Error('Nadie registró el túnel local — `MontaElTunelLocal` tiene que estar en los providers de `TunnelsModule`');
+    }
+    return tunelLocal;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+exports.TUNELES_DE_LA_ORGANIZACION = 'TUNELES_DE_LA_ORGANIZACION';

package/dist/servicios/workspace/acceso-al-recurso.d.ts

@@ -0,0 +1,39 @@
+/**
+ * La pregunta que hace el guardia de workspace: ¿puede este usuario tocar
+ * este recurso?
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. El guardia resolvía el
+ * workspace del recurso con la CONEXIÓN de Mongoose —`connection.model(...)`—
+ * y luego comprobaba el acceso con ella otra vez. Eso es la base de datos del
+ * gateway, y no puede viajar.
+ *
+ * Mismo reparto que el guardia de credenciales del #457: el guardia se muda,
+ * la consulta se queda y se pregunta por contrato.
+ *
+ * ## ⚠️ Lo que hay que conservar
+ *
+ * - **Si el recurso NO existe, se deja pasar.** El manejador contestará 404
+ *   como hasta ahora; un 403 aquí diría «existe pero no es tuyo» sobre algo
+ *   que no existe, que es filtrar información.
+ * - **Si el modelo no está registrado, LANZA.** Un nombre mal escrito tiene
+ *   que reventar la ruta la primera vez, no dejar pasar todo en silencio.
+ * - **Deniega lanzando**, no devolviendo `false`. Es lo que hace hoy
+ *   `asegurarAccesoAlWorkspace`, y el guardia cuenta con ello.
+ */
+export interface AccesoAlRecurso {
+    /**
+     * Lanza si el usuario no puede con ese recurso. Vuelve sin más si puede —
+     * o si el recurso no existe. Ver la cabecera.
+     */
+    asegurarAcceso(params: {
+        /** Nombre del MODELO de Mongoose, no de la colección. */
+        modelo: string;
+        /** Campo contra el que se compara el id. Casi siempre `_id`. */
+        campo: string;
+        id: string;
+        orgId: string;
+        userId: string;
+    }): Promise<void>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const ACCESO_AL_RECURSO = "ACCESO_AL_RECURSO";

package/dist/servicios/workspace/acceso-al-recurso.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACCESO_AL_RECURSO = void 0;
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.ACCESO_AL_RECURSO = 'ACCESO_AL_RECURSO';

package/dist/servicios/zona-horaria-del-usuario.d.ts

@@ -0,0 +1,40 @@
+/**
+ * En qué zona horaria vive un usuario. Una pregunta, un campo.
+ *
+ * ## Por qué
+ *
+ * Último trozo de la costura `nodes/` → `auth/`. `ScheduledWorkflowsService`
+ * inyectaba el modelo de `User` para leer **un campo**: la zona horaria con la
+ * que programar un cron cuando el DTO no la trae.
+ *
+ * Un servicio de nodo consultando la colección de usuarios es justo lo que no
+ * puede viajar a `hw-nodes`: allí no hay colección de usuarios, y no debe
+ * haberla — la identidad vive en el gateway.
+ *
+ * ## Lo que se conserva
+ *
+ * ⚠️ La caída a `'UTC'`, y en los DOS casos que ya tenía: si el usuario no
+ * existe, y si la consulta falla. Eso no es un detalle: sin zona horaria un
+ * cron no se puede programar, así que el original prefería una por defecto a
+ * reventar la creación del nodo. Quien implemente esto por HTTP tiene que
+ * seguir cayendo a `'UTC'` cuando el gateway no conteste — está escrito en el
+ * contrato para que no se pierda por el camino.
+ *
+ * ## Y esto viaja
+ *
+ * Una cadena. Como los topes del plan y a diferencia de la costura del motor,
+ * aquí no hay nada que aplanar.
+ */
+export interface ZonaHorariaDelUsuario {
+    /**
+     * ⚠️ Nunca lanza y nunca devuelve vacío: si no se sabe, `'UTC'`.
+     *
+     * Devolver `null` obligaría a cada llamante a decidir el respaldo, y ése es
+     * el tipo de decisión que se toma distinta en cada sitio.
+     */
+    zonaDe(userId: string): Promise<string>;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+export declare const ZONA_HORARIA_DEL_USUARIO = "ZONA_HORARIA_DEL_USUARIO";

package/dist/servicios/zona-horaria-del-usuario.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZONA_HORARIA_DEL_USUARIO = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+exports.ZONA_HORARIA_DEL_USUARIO = 'ZONA_HORARIA_DEL_USUARIO';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/platform-contracts",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -8,7 +8,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "npm --prefix ../node-types run build && tsc",
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
@@ -20,6 +20,12 @@
   "license": "MIT",
   "devDependencies": {
     "typescript": "^5.0.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@nestjs/common": "^11.0.0",
+    "@hostwebhook/node-types": "*"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=11.0.0 <12",
+    "@hostwebhook/node-types": ">=1.67.0 <2"
   }
 }