@hostwebhook/platform-contracts 0.2.0 → 0.3.0

package/dist/servicios/conversaciones-del-chat.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Las conversaciones de un chat trigger, por repositorio.
+ *
+ * ## Por qué costó más que las otras trece
+ *
+ * Las demás costuras invertían un servicio. Ésta y la de entregas invierten el
+ * acceso directo a una COLECCIÓN, y ésta además **mutaba el documento vivo**:
+ *
+ *     const existing = await this.conversationModel.findOne({...});
+ *     existing.messages.push(userMsg);
+ *     existing.expiresAt = expiresAt;
+ *     await existing.save();
+ *
+ * Eso no es una consulta que se pueda mover: es un documento de Mongoose
+ * cambiando en memoria y guardándose. Por eso quedó fuera del lote del #468 —
+ * cerrarla obliga a decidir de quién es la colección.
+ *
+ * La respuesta, mirando lo que se hace con ella: es del gateway. El panel
+ * lista conversaciones, la retención se administra desde `plans/` con
+ * `chatConversationRetentionDays`, y el índice TTL vive en su entidad. El nodo
+ * escribe turnos y los vuelve a leer.
+ *
+ * ## Y de paso arregla algo que ya estaba anotado
+ *
+ * El llamante de `upsert` tenía este comentario:
+ *
+ *   *«Plainify each entry so we don't leak Mongoose subdocument refs (parent,
+ *   `$__`, `_doc`, …) into the payload — those circular refs blow up recursive
+ *   walkers like extractAttachments / template renderers with "Maximum call
+ *   stack size exceeded"».*
+ *
+ * O sea que ya se estaba aplanando a mano, después de recibir el documento,
+ * porque no hacerlo reventaba. El repositorio devuelve datos planos y ese
+ * peligro desaparece en origen en vez de esquivarse en cada llamante.
+ *
+ * ## ⚠️ Lo que no se puede perder
+ *
+ * - **`expiresAt` se refresca en CADA turno de usuario.** La ventana de
+ *   retención rueda con la actividad; sin eso, una sesión larga caduca a mitad
+ *   de conversación. `null` significa «no caduca» (plan enterprise).
+ * - **El dedupe de voz.** Los SDK de voz repiten la transcripción final, así
+ *   que un turno idéntico al último —mismo rol y mismo contenido recortado— no
+ *   se añade. Sin eso el transcript sale duplicado.
+ * - **Los borradores pendientes son la memoria entre turnos.** Es lo que deja
+ *   al modelo entender un «confirma» que llega en el turno siguiente.
+ */
+/** Un turno del transcript. `mode` ausente significa texto. */
+export interface MensajeDeConversacion {
+    role: string;
+    content: string;
+    mode?: 'voice';
+}
+/** Un borrador que quedó a medias y espera confirmación. */
+export interface BorradorPendiente {
+    draftId: string;
+    operation: string;
+    subject?: string;
+    createdAt: Date;
+}
+/** Una conversación, plana. */
+export interface Conversacion {
+    id: string;
+    sessionId: string;
+    title?: string;
+    messages: MensajeDeConversacion[];
+    pendingDrafts: BorradorPendiente[];
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export interface RepositorioDeConversaciones {
+    /** La lista paginada del panel, con su total. */
+    listarPorTrigger(triggerId: string, opts: {
+        offset: number;
+        limit: number;
+    }): Promise<{
+        datos: Conversacion[];
+        total: number;
+    }>;
+    /** ⚠️ `null` si no existe o no es de ese trigger; el llamante decide el 404. */
+    buscarPorId(conversationId: string, triggerId: string): Promise<Conversacion | null>;
+    /**
+     * Un turno de usuario: lo añade a la sesión, o la crea.
+     *
+     * ⚠️ `expiresAt` se escribe SIEMPRE, exista ya la conversación o no: es lo
+     * que hace rodar la ventana de retención con la actividad.
+     */
+    guardarTurnoDeUsuario(params: {
+        orgId: string;
+        chatTriggerId: string;
+        sessionId: string;
+        title?: string;
+        mensaje: MensajeDeConversacion;
+        /** `null` = no caduca. */
+        expiresAt: Date | null;
+    }): Promise<Conversacion>;
+    /**
+     * Un turno de voz.
+     *
+     * ⚠️ Devuelve `anadido: false` cuando el turno es idéntico al último —mismo
+     * rol y mismo contenido recortado—. Los SDK de voz repiten la transcripción
+     * final y sin eso el transcript sale duplicado.
+     */
+    guardarTurnoDeVoz(params: {
+        orgId: string;
+        chatTriggerId: string;
+        sessionId: string;
+        title: string;
+        mensaje: MensajeDeConversacion;
+        expiresAt: Date | null;
+    }): Promise<{
+        conversationId: string;
+        anadido: boolean;
+    }>;
+    /** La respuesta del asistente, al final del transcript. */
+    anadirRespuesta(conversationId: string, content: string): Promise<void>;
+    /** Lo que el widget relee al recargar la página a mitad de sesión. */
+    historialDeSesion(chatTriggerId: string, sessionId: string): Promise<{
+        conversationId: string | null;
+        messages: MensajeDeConversacion[];
+    }>;
+    /**
+     * Aplica lo que pasó con los borradores en un turno y devuelve cómo quedó.
+     *
+     * ⚠️ Se quitan los enviados y se añaden los nuevos EN ESE ORDEN, y devuelve
+     * los ids resultantes porque el llamante los registra: sin ese log no había
+     * forma de averiguar por qué el modelo vio el borrador equivocado en el
+     * turno siguiente.
+     */
+    aplicarEventosDeBorrador(conversationId: string, cambios: {
+        quitar: string[];
+        anadir: Array<{
+            draftId: string;
+            operation: string;
+            subject?: string;
+        }>;
+    }): Promise<string[]>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const CONVERSACIONES_DEL_CHAT = "CONVERSACIONES_DEL_CHAT";

package/dist/servicios/conversaciones-del-chat.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Las conversaciones de un chat trigger, por repositorio.
+ *
+ * ## Por qué costó más que las otras trece
+ *
+ * Las demás costuras invertían un servicio. Ésta y la de entregas invierten el
+ * acceso directo a una COLECCIÓN, y ésta además **mutaba el documento vivo**:
+ *
+ *     const existing = await this.conversationModel.findOne({...});
+ *     existing.messages.push(userMsg);
+ *     existing.expiresAt = expiresAt;
+ *     await existing.save();
+ *
+ * Eso no es una consulta que se pueda mover: es un documento de Mongoose
+ * cambiando en memoria y guardándose. Por eso quedó fuera del lote del #468 —
+ * cerrarla obliga a decidir de quién es la colección.
+ *
+ * La respuesta, mirando lo que se hace con ella: es del gateway. El panel
+ * lista conversaciones, la retención se administra desde `plans/` con
+ * `chatConversationRetentionDays`, y el índice TTL vive en su entidad. El nodo
+ * escribe turnos y los vuelve a leer.
+ *
+ * ## Y de paso arregla algo que ya estaba anotado
+ *
+ * El llamante de `upsert` tenía este comentario:
+ *
+ *   *«Plainify each entry so we don't leak Mongoose subdocument refs (parent,
+ *   `$__`, `_doc`, …) into the payload — those circular refs blow up recursive
+ *   walkers like extractAttachments / template renderers with "Maximum call
+ *   stack size exceeded"».*
+ *
+ * O sea que ya se estaba aplanando a mano, después de recibir el documento,
+ * porque no hacerlo reventaba. El repositorio devuelve datos planos y ese
+ * peligro desaparece en origen en vez de esquivarse en cada llamante.
+ *
+ * ## ⚠️ Lo que no se puede perder
+ *
+ * - **`expiresAt` se refresca en CADA turno de usuario.** La ventana de
+ *   retención rueda con la actividad; sin eso, una sesión larga caduca a mitad
+ *   de conversación. `null` significa «no caduca» (plan enterprise).
+ * - **El dedupe de voz.** Los SDK de voz repiten la transcripción final, así
+ *   que un turno idéntico al último —mismo rol y mismo contenido recortado— no
+ *   se añade. Sin eso el transcript sale duplicado.
+ * - **Los borradores pendientes son la memoria entre turnos.** Es lo que deja
+ *   al modelo entender un «confirma» que llega en el turno siguiente.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONVERSACIONES_DEL_CHAT = void 0;
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.CONVERSACIONES_DEL_CHAT = 'CONVERSACIONES_DEL_CHAT';

package/dist/servicios/corridas-programadas.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lo que el motor necesita del flujo programado. UN método.
+ *
+ * ## Por qué
+ *
+ * `pipeline-run` llama a `ScheduledWorkflowsService.recordRun(swId, run)` al
+ * terminar una corrida que arrancó en un flujo programado. Es la única
+ * llamada: medido.
+ *
+ * ⚠️ Y NO es un `lastRunAt` que se pueda escribir a mano desde aquí. `recordRun`
+ * además archiva la fila en `scheduledworkflowruns` y poda a las últimas cien.
+ * Reimplementarlo del lado del motor sería una segunda copia de esa regla.
+ *
+ * ⚠️ Tiene que TERMINAR antes de que salga el marco `complete`: el panel
+ * relee el flujo cuando ese marco llega, así que apuntar después es una carrera
+ * que se pierde a veces. Por eso se espera, a diferencia de la salud del
+ * webhook.
+ */
+export interface CorridasProgramadas {
+    apuntarCorrida(swId: string, corrida: {
+        startedAt: Date;
+        completedAt: Date;
+        durationMs: number;
+        status: 'success' | 'partial' | 'failure';
+        errorMessage?: string | null;
+    }): Promise<void>;
+}
+/** ⚠️ Cadena y no `Symbol`. */
+export declare const CORRIDAS_PROGRAMADAS = "CORRIDAS_PROGRAMADAS";

package/dist/servicios/corridas-programadas.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORRIDAS_PROGRAMADAS = void 0;
+/** ⚠️ Cadena y no `Symbol`. */
+exports.CORRIDAS_PROGRAMADAS = 'CORRIDAS_PROGRAMADAS';

package/dist/servicios/credencial/permiso-sobre-credencial.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ¿Puede este usuario poner esta credencial? — la pregunta, sin la respuesta.
+ *
+ * ## Por qué existe
+ *
+ * Costura de la Fase 2. `node-controller.factory` aplicaba
+ * `@UseGuards(CredentialFolderGuard)` a los ~30 tipos de nodo, y ese guardia
+ * vive en `credentials/`: consulta la colección de credenciales y resuelve
+ * permisos de carpeta. Con eso, el factory —y con él todos los controladores
+ * de nodo— no se puede mudar a `hw-nodes` sin llevarse el dominio entero de
+ * credenciales, que es la Fase 4.
+ *
+ * ## Lo que NO se hace, y por qué
+ *
+ * Lo fácil era quitar el guardia y decir «ya autoriza el gateway al proxear».
+ * Y es defendible: la autenticación va EN el gateway por diseño.
+ *
+ * ⚠️ Pero este guardia existe **porque la comprobación se olvidó trece
+ * veces**. Su propio docblock cuenta el agujero: bastaba con leerle el id de
+ * credencial a un nodo que sí se pudiera ver, ponérselo a un nodo propio y
+ * ejecutarlo, y la credencial de la carpeta negada se descifraba igual. Y un
+ * id de Mongo no es un secreto: sale en el lienzo y en la barra del navegador.
+ *
+ * Dejar esa garantía viviendo SÓLO en el proxy es apostar a que nada alcance
+ * nunca `hw-nodes` por otro camino — una mala configuración, un servicio
+ * nuevo, una prueba. Cuando pase, el agujero vuelve, y vuelve callado.
+ *
+ * Así que la pregunta se queda y lo que se va es la RESPUESTA: `hw-nodes`
+ * preguntará por la red privada a quien tenga el dato. Una llamada por
+ * escritura de nodo que lleve credencial —crear o editar—, no por ejecución.
+ * Un salto interno es ~1 ms contra los 100-500 ms que el nodo gasta llamando
+ * a Slack o a Gmail.
+ */
+/** Los tres papeles sobre una carpeta, de menos a más. */
+export type RolDeCarpeta = 'viewer' | 'editor' | 'owner';
+export interface PreguntaDePermiso {
+    credentialId: string;
+    userId: string;
+    orgId: string;
+    rolMinimo: RolDeCarpeta;
+}
+export interface PermisoSobreCredencial {
+    /**
+     * ⚠️ Devuelve `true` cuando la credencial NO EXISTE, y eso no es un
+     * descuido: es la semántica que hay que conservar.
+     *
+     * Negar aquí daría un 403 sobre algo inexistente, y un 403 dice «existe
+     * pero no es tuya». Dejando pasar, el manejador contesta 404 como siempre y
+     * no se filtra qué ids existen — que es justo lo que este guardia protege,
+     * porque los ids circulan.
+     *
+     * O sea: `false` significa «existe y NO puedes», nunca «no la encuentro».
+     */
+    puedeUsar(pregunta: PreguntaDePermiso): Promise<boolean>;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`. Un `Symbol` no sobrevive a una frontera de módulo
+ * duplicada ni a una serialización, y esto está pensado para acabar cruzando
+ * una red.
+ */
+export declare const PERMISO_SOBRE_CREDENCIAL = "PERMISO_SOBRE_CREDENCIAL";

package/dist/servicios/credencial/permiso-sobre-credencial.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * ¿Puede este usuario poner esta credencial? — la pregunta, sin la respuesta.
+ *
+ * ## Por qué existe
+ *
+ * Costura de la Fase 2. `node-controller.factory` aplicaba
+ * `@UseGuards(CredentialFolderGuard)` a los ~30 tipos de nodo, y ese guardia
+ * vive en `credentials/`: consulta la colección de credenciales y resuelve
+ * permisos de carpeta. Con eso, el factory —y con él todos los controladores
+ * de nodo— no se puede mudar a `hw-nodes` sin llevarse el dominio entero de
+ * credenciales, que es la Fase 4.
+ *
+ * ## Lo que NO se hace, y por qué
+ *
+ * Lo fácil era quitar el guardia y decir «ya autoriza el gateway al proxear».
+ * Y es defendible: la autenticación va EN el gateway por diseño.
+ *
+ * ⚠️ Pero este guardia existe **porque la comprobación se olvidó trece
+ * veces**. Su propio docblock cuenta el agujero: bastaba con leerle el id de
+ * credencial a un nodo que sí se pudiera ver, ponérselo a un nodo propio y
+ * ejecutarlo, y la credencial de la carpeta negada se descifraba igual. Y un
+ * id de Mongo no es un secreto: sale en el lienzo y en la barra del navegador.
+ *
+ * Dejar esa garantía viviendo SÓLO en el proxy es apostar a que nada alcance
+ * nunca `hw-nodes` por otro camino — una mala configuración, un servicio
+ * nuevo, una prueba. Cuando pase, el agujero vuelve, y vuelve callado.
+ *
+ * Así que la pregunta se queda y lo que se va es la RESPUESTA: `hw-nodes`
+ * preguntará por la red privada a quien tenga el dato. Una llamada por
+ * escritura de nodo que lleve credencial —crear o editar—, no por ejecución.
+ * Un salto interno es ~1 ms contra los 100-500 ms que el nodo gasta llamando
+ * a Slack o a Gmail.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMISO_SOBRE_CREDENCIAL = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`. Un `Symbol` no sobrevive a una frontera de módulo
+ * duplicada ni a una serialización, y esto está pensado para acabar cruzando
+ * una red.
+ */
+exports.PERMISO_SOBRE_CREDENCIAL = 'PERMISO_SOBRE_CREDENCIAL';