@hostwebhook/platform-contracts 0.1.0 → 0.3.0

package/dist/servicios/credenciales-del-gateway.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CREDENCIALES_DEL_GATEWAY = exports.CredencialDeTipoEquivocado = exports.MOTIVO_TIPO_EQUIVOCADO = void 0;
+exports.comoAtribuir = comoAtribuir;
+exports.tunelDe = tunelDe;
+const common_1 = require("@nestjs/common");
+/**
+ * Traduce `QuienPide` a lo que el registro de accesos entiende hoy.
+ *
+ * ⚠️ Y comprueba el id vacío, que es el agujero que el tipo no puede cerrar.
+ * Devuelve también si la atribución es utilizable, para que el adaptador lo
+ * apunte en vez de dejarlo pasar callando.
+ */
+function comoAtribuir(quien) {
+    if (quien.modo === 'usuario') {
+        return {
+            userId: quien.userId,
+            sourceIp: quien.sourceIp,
+            sirve: Boolean(quien.userId),
+        };
+    }
+    const sirve = Boolean(quien.type) && Boolean(quien.id);
+    return {
+        relatedEntity: { type: quien.type, id: quien.id },
+        /* ⚠️ En modo `nodo` el `userId` va TAMBIÉN si lo hay: quien disparó y sobre
+           qué son dos columnas distintas del registro, y quedarse con una era
+           perder la otra en silencio. */
+        userId: quien.userId,
+        sourceIp: quien.sourceIp,
+        motivo: quien.motivo,
+        sirve,
+    };
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+/**
+ * La credencial existe, pero no es del tipo que el llamante pide.
+ *
+ * ⚠️ Extiende `BadRequestException` A PROPÓSITO: mismo estado y mismo texto que
+ * lanzaba el adaptador, así que las familias que YA pasan `tipoEsperado` —mongo,
+ * postgres, las memorias del AI Node— no cambian ni una letra. Lo que añade es
+ * un `instanceof` con el que un llamante puede volver a poner SU mensaje.
+ *
+ * ## Por qué hacía falta
+ *
+ * `tipoEsperado` no es una comodidad: es dónde se comprueba, y comprobar en el
+ * gateway es lo que evita descifrar una credencial que se va a rechazar. Pero
+ * los helpers de Mailchimp y Shopify lanzaban un `ForbiddenException` con un
+ * mensaje accionable en inglés —«Connect a Shopify store from Settings →
+ * Credentials»— que SALE POR LA API al usuario. Pasar `tipoEsperado` cambiaba
+ * el mensaje y el código HTTP; no pasarlo obligaba a descifrar primero, que es
+ * peor que hoy. Con el `instanceof`, el llamante recupera su mensaje sin
+ * renunciar a la comprobación temprana.
+ *
+ * ⚠️ Lo que NUNCA hay que hacer es olfatear la prosa del mensaje con un regex:
+ * el texto del adaptador no es contrato, y el día que se reescriba, el `catch`
+ * deja de reconocerlo EN SILENCIO.
+ *
+ * ⚠️ Y `instanceof` no cruza HTTP. El día que esta costura sea red, la clase
+ * hay que rehidratarla desde el código de estado en el cliente del transporte.
+ * Es UN sitio y está a la vista; olfatear la prosa serían N escondidos.
+ */
+/**
+ * 🔥 El discriminador que hace que la clase sobreviva al cable.
+ *
+ * `instanceof` no cruza HTTP, y el código de estado tampoco basta: esta
+ * excepción es un **400**, igual que la validación de entrada y media docena
+ * de errores más de hw-credentials. Rehidratar «por el 400» convertiría
+ * cualquier petición mal formada en «la credencial es de otro tipo».
+ *
+ * ⚠️ Y lo que NUNCA hay que hacer es olfatear la prosa del mensaje: el texto
+ * no es contrato, y el día que se reescriba el `catch` deja de reconocerlo EN
+ * SILENCIO. Por eso va un campo propio en el CUERPO.
+ */
+exports.MOTIVO_TIPO_EQUIVOCADO = 'credencial-de-tipo-equivocado';
+class CredencialDeTipoEquivocado extends common_1.BadRequestException {
+    constructor(credentialId, tipoReal, tiposEsperados) {
+        /* Cuerpo estructurado y no una cadena: los tres campos de abajo son
+           propiedades de INSTANCIA, y una instancia no viaja por una red. Sin
+           ponerlos en el cuerpo, el otro lado no puede reconstruir la excepción
+           aunque sepa que es ésta. */
+        super({
+            statusCode: 400,
+            error: 'Bad Request',
+            message: `La credencial ${credentialId} es de tipo "${tipoReal}" y aquí se esperaba ` +
+                `${tiposEsperados.map((t) => `"${t}"`).join(' o ')}.`,
+            motivo: exports.MOTIVO_TIPO_EQUIVOCADO,
+            credentialId,
+            tipoReal,
+            tiposEsperados,
+        });
+        this.credentialId = credentialId;
+        this.tipoReal = tipoReal;
+        this.tiposEsperados = tiposEsperados;
+    }
+}
+exports.CredencialDeTipoEquivocado = CredencialDeTipoEquivocado;
+exports.CREDENCIALES_DEL_GATEWAY = 'CREDENCIALES_DEL_GATEWAY';
+/**
+ * El túnel por el que hay que salir para esta credencial, si lo hay.
+ *
+ * ⚠️ Deliberadamente NO es un método del contrato. `getTunnelIdForCredential`
+ * lo era en el gateway, y al medirlo resultó ser `metadata.tunnelId` y nada
+ * más — y `describir()` ya trae `metadata`. Añadir un método habría sido una
+ * llamada de red por cada consulta para leer un campo que ya venía en la
+ * anterior.
+ *
+ * Vive aquí y no repetido en los cinco sitios que lo derivan porque «leer un
+ * campo de un mapa» es exactamente donde una copia se queda con el nombre
+ * viejo el día que el campo cambie.
+ */
+function tunelDe(cred) {
+    const t = cred.metadata?.tunnelId;
+    return typeof t === 'string' && t.length > 0 ? t : null;
+}

package/dist/servicios/cuentas-de-atlassian.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Lo que un trigger de Atlassian le pide al gateway. Un método.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `triggers.service` llamaba a
+ * `AtlassianAccountsService` para una sola cosa: apuntar las cuentas que
+ * aparecen en un payload entrante.
+ *
+ * ⚠️ Y no es un detalle administrativo. Esa lista es lo que sostiene la
+ * Personal Data Reporting API que Atlassian OBLIGA a exponer: si deja de
+ * escribirse, la app deja de poder responder a quién tiene datos de quién.
+ * Ver `project_datos_personales_atlassian`.
+ *
+ * ## Cómo viaja
+ *
+ * Bien: `unknown` entra y un número sale. Nada que aplanar.
+ */
+export interface CuentasDeAtlassian {
+    /** Devuelve cuántas cuentas nuevas se apuntaron. */
+    registrarDesdePayload(payload: unknown, organizationId: string): Promise<number>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const CUENTAS_DE_ATLASSIAN = "CUENTAS_DE_ATLASSIAN";

package/dist/servicios/cuentas-de-atlassian.js

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

package/dist/servicios/descarga-de-drive.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Bajar un fichero de Drive y guardarlo — la petición, sin el guardado.
+ *
+ * ## Por qué
+ *
+ * `DriveDownloadHelper` lo usan dos servicios de nodo —`drive-actions` y
+ * `triggers`— y arrastra 23 ficheros del gateway: `FilesService` (24 por su
+ * cuenta), `PlansService` (13) y el adaptador de almacenamiento. Con eso,
+ * esos dos servicios no se pueden mudar a `hw-nodes` sin llevarse el
+ * almacenamiento y los planes.
+ *
+ * Medido antes de escribir esto: de todo el helper se llama **un método**,
+ * `downloadToR2`, desde dos sitios. Nada más.
+ *
+ * ⚠️ Y hubo que medirlo dos veces. El primer barrido —`this.driveDownload.` en
+ * una línea— no encontró NINGUNA llamada, porque están partidas en varias
+ * líneas. Un contrato basado en ese cero habría salido vacío.
+ *
+ * ## ⚠️ Lo que este contrato NO resuelve, y hay que saberlo
+ *
+ * `auth` es un cliente de OAuth de googleapis: un OBJETO CON MÉTODOS. Cruza
+ * bien mientras esto siga en el mismo proceso, y **no cruza una red**.
+ *
+ * Cuando `hw-nodes` sea un servicio de verdad, esta costura no se resuelve
+ * pasando el mismo argumento por HTTP: hay que decidir DÓNDE ocurre la
+ * descarga. Bajar de Drive puede hacerlo el nodo —tiene la credencial
+ * resuelta, según el plan— pero guardar en R2 es del gateway. O sea que este
+ * método se parte en dos, o el nodo sube el resultado.
+ *
+ * No es trabajo de hoy, pero está escrito aquí para que no se descubra en
+ * mitad de la mudanza. Hoy lo que se gana es que los dos servicios de nodo
+ * dejen de conocer `FilesService` y `PlansService`.
+ */
+/** Lo que sale. Unión discriminada, datos puros: esto sí viaja. */
+export type ResultadoDeDescarga = {
+    ok: true;
+    fileRef: {
+        id: string;
+        key: string;
+        originalName: string;
+        mimeType: string;
+        size: number;
+        downloadUrl: string;
+    };
+} | {
+    ok: false;
+    skipReason: 'file_too_large' | 'storage_quota_reached' | 'unsupported_workspace_type' | 'download_failed';
+    message: string;
+    sizeBytes?: number;
+};
+export interface PeticionDeDescarga {
+    /**
+     * ⚠️ Opaco, y es el que no viaja. Un `OAuth2Client` de googleapis es un
+     * objeto con métodos; sobrevive a una llamada en proceso y no a un
+     * `JSON.stringify`. Ver la nota de arriba.
+     */
+    auth: unknown;
+    fileId: string;
+    orgId: string;
+    userId: string;
+    workspaceId?: string;
+    /** Metadatos que el llamante ya tenía: ahorra una llamada a Drive. */
+    knownName?: string;
+    knownMimeType?: string;
+    knownSize?: number;
+}
+export interface DescargaDeDrive {
+    downloadToR2(peticion: PeticionDeDescarga): Promise<ResultadoDeDescarga>;
+}
+/**
+ * ⚠️ Cadena y no `Symbol`, por lo mismo que los otros tokens de la Fase 2: un
+ * `Symbol` no sobrevive a una frontera de módulo duplicada.
+ */
+export declare const DESCARGA_DE_DRIVE = "DESCARGA_DE_DRIVE";

package/dist/servicios/descarga-de-drive.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Bajar un fichero de Drive y guardarlo — la petición, sin el guardado.
+ *
+ * ## Por qué
+ *
+ * `DriveDownloadHelper` lo usan dos servicios de nodo —`drive-actions` y
+ * `triggers`— y arrastra 23 ficheros del gateway: `FilesService` (24 por su
+ * cuenta), `PlansService` (13) y el adaptador de almacenamiento. Con eso,
+ * esos dos servicios no se pueden mudar a `hw-nodes` sin llevarse el
+ * almacenamiento y los planes.
+ *
+ * Medido antes de escribir esto: de todo el helper se llama **un método**,
+ * `downloadToR2`, desde dos sitios. Nada más.
+ *
+ * ⚠️ Y hubo que medirlo dos veces. El primer barrido —`this.driveDownload.` en
+ * una línea— no encontró NINGUNA llamada, porque están partidas en varias
+ * líneas. Un contrato basado en ese cero habría salido vacío.
+ *
+ * ## ⚠️ Lo que este contrato NO resuelve, y hay que saberlo
+ *
+ * `auth` es un cliente de OAuth de googleapis: un OBJETO CON MÉTODOS. Cruza
+ * bien mientras esto siga en el mismo proceso, y **no cruza una red**.
+ *
+ * Cuando `hw-nodes` sea un servicio de verdad, esta costura no se resuelve
+ * pasando el mismo argumento por HTTP: hay que decidir DÓNDE ocurre la
+ * descarga. Bajar de Drive puede hacerlo el nodo —tiene la credencial
+ * resuelta, según el plan— pero guardar en R2 es del gateway. O sea que este
+ * método se parte en dos, o el nodo sube el resultado.
+ *
+ * No es trabajo de hoy, pero está escrito aquí para que no se descubra en
+ * mitad de la mudanza. Hoy lo que se gana es que los dos servicios de nodo
+ * dejen de conocer `FilesService` y `PlansService`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESCARGA_DE_DRIVE = void 0;
+/**
+ * ⚠️ Cadena y no `Symbol`, por lo mismo que los otros tokens de la Fase 2: un
+ * `Symbol` no sobrevive a una frontera de módulo duplicada.
+ */
+exports.DESCARGA_DE_DRIVE = 'DESCARGA_DE_DRIVE';

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

@@ -0,0 +1,81 @@
+/**
+ * Lo que el Chat Trigger necesita del nodo de IA.
+ *
+ * ## Por qué existe
+ *
+ * `chat-triggers` vive en el gateway —es uno de los cinco nodos de ORIGEN— y
+ * `ai-nodes` se muda a hw-nodes. Era el último cruce de la puerta hacia el
+ * ejecutor, y el más difícil de los tres: los otros dos eran filas de base de
+ * datos; éste lleva STREAMING.
+ *
+ * ⚠️ Y no se resolvía con el traspaso del motor. El chat NO pasa por el motor,
+ * y está escrito en tres sitios de su propio fichero: «chatTrigger is an
+ * ingress, not dispatched in-pipeline».
+ *
+ * ## 🔥 Lo que NO puede cruzar: el documento mutado
+ *
+ * El código de antes hacía esto:
+ *
+ *     const aiNode = await this.aiNodeModel.findOne({…});
+ *     if (trigger.systemPromptOverride) an.systemPrompt = trigger.systemPromptOverride;
+ *     if (an.memoryEnabled) an.memoryUserId = sessionId;
+ *     await this.aiNodesService.executeForEvent(aiNode, payload, {…});
+ *
+ * O sea: la puerta cargaba el documento del nodo, le PARCHEABA dos campos en
+ * memoria y se lo pasaba al ejecutor. Un documento de Mongoose parcheado no
+ * cruza una red.
+ *
+ * Así que la puerta deja de cargar el nodo. Manda el id y los dos ajustes, y
+ * quien tiene el nodo los aplica.
+ *
+ * ⚠️ El `sessionId` viaja SIEMPRE y se aplica sólo si el nodo tiene memoria.
+ * Antes la puerta leía `memoryEnabled` del documento para decidir; esa decisión
+ * se va con el dato, que es donde puede comprobarse.
+ */
+/** El nodo conectado, en lo que la puerta lee de él. Cuatro campos, medidos. */
+export interface NodoDeIaConectado {
+    id: string;
+    /** Para el paso del historial y para decirle al widget con quién habla. */
+    name: string;
+    workspaceId: string | null;
+    /** Si el widget enseña las llamadas a herramientas mientras ocurren. */
+    muestraLasHerramientas: boolean;
+}
+export interface EjecucionDeIa {
+    /** El nodo conectado a ese chat, o `null` si ya no existe. */
+    nodoConectado(aiNodeId: string, orgId: string): Promise<NodoDeIaConectado | null>;
+    /**
+     * Ejecuta el nodo y va emitiendo por `CANAL_DE_STREAM`.
+     *
+     * ⚠️ El emisor NO viaja como argumento: un callback no cruza una red. Lo que
+     * viaja es el `streamId`, y el ejecutor emite contra el canal — que del otro
+     * lado es el gateway sosteniendo el SSE. Ver `canal-de-stream.ts`.
+     */
+    ejecutarParaEvento(params: {
+        aiNodeId: string;
+        orgId: string;
+        payload: Record<string, unknown>;
+        /** Contra qué stream se emiten los trozos. */
+        streamId: string;
+        /** El prompt del trigger, si trae uno, en vez del del nodo. */
+        systemPromptOverride?: string;
+        /** ⚠️ Se aplica SÓLO si el nodo tiene la memoria puesta. Lo decide quien
+         *  tiene el nodo. */
+        sessionId?: string;
+        /** Para que lo que el agente ejecute como tool caiga DENTRO de la corrida
+         *  de este turno, y con el Chat Trigger de origen. */
+        correlationId?: string;
+        eventId?: string;
+        origen?: {
+            id: string;
+            name: string;
+        };
+    }): Promise<{
+        statusCode: number;
+        responseBody: string;
+        /** Lo que tardó. El paso del historial lo necesita. */
+        latencyMs: number;
+    }>;
+}
+/** ⚠️ Cadena y no `Symbol`. */
+export declare const EJECUCION_DE_IA = "EJECUCION_DE_IA";

package/dist/servicios/ejecucion-de-ia.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Lo que el Chat Trigger necesita del nodo de IA.
+ *
+ * ## Por qué existe
+ *
+ * `chat-triggers` vive en el gateway —es uno de los cinco nodos de ORIGEN— y
+ * `ai-nodes` se muda a hw-nodes. Era el último cruce de la puerta hacia el
+ * ejecutor, y el más difícil de los tres: los otros dos eran filas de base de
+ * datos; éste lleva STREAMING.
+ *
+ * ⚠️ Y no se resolvía con el traspaso del motor. El chat NO pasa por el motor,
+ * y está escrito en tres sitios de su propio fichero: «chatTrigger is an
+ * ingress, not dispatched in-pipeline».
+ *
+ * ## 🔥 Lo que NO puede cruzar: el documento mutado
+ *
+ * El código de antes hacía esto:
+ *
+ *     const aiNode = await this.aiNodeModel.findOne({…});
+ *     if (trigger.systemPromptOverride) an.systemPrompt = trigger.systemPromptOverride;
+ *     if (an.memoryEnabled) an.memoryUserId = sessionId;
+ *     await this.aiNodesService.executeForEvent(aiNode, payload, {…});
+ *
+ * O sea: la puerta cargaba el documento del nodo, le PARCHEABA dos campos en
+ * memoria y se lo pasaba al ejecutor. Un documento de Mongoose parcheado no
+ * cruza una red.
+ *
+ * Así que la puerta deja de cargar el nodo. Manda el id y los dos ajustes, y
+ * quien tiene el nodo los aplica.
+ *
+ * ⚠️ El `sessionId` viaja SIEMPRE y se aplica sólo si el nodo tiene memoria.
+ * Antes la puerta leía `memoryEnabled` del documento para decidir; esa decisión
+ * se va con el dato, que es donde puede comprobarse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EJECUCION_DE_IA = void 0;
+/** ⚠️ Cadena y no `Symbol`. */
+exports.EJECUCION_DE_IA = 'EJECUCION_DE_IA';

package/dist/servicios/enlaces-de-flujo.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Lo que un nodo usa para saltar a otro workspace.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `FlowLinksService` hace dos
+ * cosas —el CRUD de los enlaces y ejecutarlos— y los nodos sólo usan la
+ * segunda. El CRUD, con su colección y su cuota, se queda en el gateway.
+ *
+ * ## ⚠️ Lo que NO se puede perder
+ *
+ * Los dos métodos llevan `callStack` y `correlationId`, y ninguno es
+ * decorativo:
+ *
+ *   `callStack`       es la DETECCIÓN DE CICLOS. El despachador va añadiendo
+ *                     cada destino; si uno ya está, aborta. Perderlo por el
+ *                     camino convierte un enlace circular en un bucle
+ *                     infinito entre workspaces.
+ *   `correlationId`   es lo que hace que lo de al otro lado sea la MISMA
+ *                     corrida y no una suelta. Sin él el historial se parte
+ *                     en dos justo donde más se mira.
+ *
+ * Quien implemente esto por red tiene que propagar los dos.
+ */
+export interface DespachoDeEnlace {
+    sourceWorkspaceId: string;
+    sourceNodeType: string;
+    sourceNodeId: string;
+    payload: Record<string, unknown>;
+    /** ⚠️ La detección de ciclos. Ver la cabecera. */
+    callStack?: string[];
+    /** ⚠️ La corrida de la que sale. Ver la cabecera. */
+    correlationId?: string;
+}
+export interface ResumenDeDespacho {
+    invoked: number;
+    skipped: number;
+    errors: number;
+}
+export interface EnlacesDeFlujo {
+    dispatchOutgoing(orgId: string, opts: DespachoDeEnlace): Promise<ResumenDeDespacho>;
+    invokeWebhookAsTool(params: {
+        orgId: string;
+        webhookId: string;
+        payload: Record<string, unknown>;
+        callStack?: string[];
+        timeoutMs?: number;
+        source?: {
+            nodeType: string;
+            nodeId: string;
+        };
+        correlationId?: string;
+    }): Promise<{
+        ok: boolean;
+        statusCode: number;
+        body: string;
+        reason?: string;
+    }>;
+}
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+export declare const ENLACES_DE_FLUJO = "ENLACES_DE_FLUJO";

package/dist/servicios/enlaces-de-flujo.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Lo que un nodo usa para saltar a otro workspace.
+ *
+ * Costura de la Fase 2, del lote de las pequeñas. `FlowLinksService` hace dos
+ * cosas —el CRUD de los enlaces y ejecutarlos— y los nodos sólo usan la
+ * segunda. El CRUD, con su colección y su cuota, se queda en el gateway.
+ *
+ * ## ⚠️ Lo que NO se puede perder
+ *
+ * Los dos métodos llevan `callStack` y `correlationId`, y ninguno es
+ * decorativo:
+ *
+ *   `callStack`       es la DETECCIÓN DE CICLOS. El despachador va añadiendo
+ *                     cada destino; si uno ya está, aborta. Perderlo por el
+ *                     camino convierte un enlace circular en un bucle
+ *                     infinito entre workspaces.
+ *   `correlationId`   es lo que hace que lo de al otro lado sea la MISMA
+ *                     corrida y no una suelta. Sin él el historial se parte
+ *                     en dos justo donde más se mira.
+ *
+ * Quien implemente esto por red tiene que propagar los dos.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENLACES_DE_FLUJO = void 0;
+/** ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2. */
+exports.ENLACES_DE_FLUJO = 'ENLACES_DE_FLUJO';

package/dist/servicios/ficheros-del-gateway.d.ts

@@ -0,0 +1,210 @@
+import type { Readable } from 'node:stream';
+import type { FileRef } from './formas-compartidas';
+/**
+ * Lo que un nodo le pide al gateway sobre ficheros. Nada más.
+ *
+ * ## Por qué
+ *
+ * Costura de la Fase 2. `src/nodes/` importaba `files/` 28 veces:
+ *
+ *   11  `FilesModule`      cableado de DI, desaparece con la mudanza
+ *   11  `FilesService`     el registro de ficheros
+ *    6  `StorageAdapter`   el almacén crudo
+ *
+ * `FilesService` arrastra el cliente de S3 y la colección de ficheros. El
+ * plan lo dice claro: *«la primitiva de ficheros se queda en el gateway:
+ * sirve a Gmail, Drive y al chat»*. Así que el nodo no la lleva — la pide.
+ *
+ * ## Dos contratos y no uno, a propósito
+ *
+ * Son dos abstracciones distintas y hoy se inyectan por separado: el REGISTRO
+ * sabe de refs, permisos y URLs firmadas; el ALMACÉN sólo mueve bytes.
+ * Juntarlas obligaría a un adaptador que no aporta nada, y en la Fase 4 puede
+ * que no acaben en el mismo sitio.
+ *
+ * ## ⚠️ La superficie es la MEDIDA, no la que yo supuse
+ *
+ * Mi primera versión de este fichero declaraba 7 métodos y 2. Los de verdad
+ * son 16 y 4. La diferencia no la vio ninguna revisión: la vio un inventario
+ * que buscaba las llamadas por el NOMBRE de la propiedad inyectada, y que
+ * antes de dar un número tuvo que aprender a saltarse los literales de
+ * expresión regular —un `.replace(/"/g, ...)` en `email-actions` hacía
+ * desaparecer el fichero entero del recuento, sin error—. Si esta lista
+ * cambia, se vuelve a medir; no se estima.
+ *
+ * ## Lo que cruza bien, y lo que no va a cruzar
+ *
+ * Casi todo son datos planos o **URLs firmadas**, que es el patrón bueno para
+ * una frontera de red: el nodo recibe una URL y habla con R2 directamente,
+ * sin que los bytes pasen por el gateway.
+ *
+ * ⚠️ Tres no encajan en eso, y conviene tenerlas escritas antes de que la
+ * costura sea HTTP y se descubran midiendo latencia:
+ *
+ *   `getObjectBuffer`         devuelve el fichero ENTERO en memoria
+ *   `registerDirectFile`      lo recibe entero, en un `Buffer`
+ *   `ingestStreamToLibrary`   recibe un `Readable`, que ni siquiera se puede
+ *                             serializar
+ *
+ * Las tres tienen la misma salida el día que esto sea una llamada de red:
+ * pedir una URL firmada y que el nodo suba o baje por su cuenta, como ya hace
+ * el resto. No es trabajo de hoy.
+ */
+/**
+ * Lo que un nodo lee de un fichero recién registrado.
+ *
+ * ⚠️ Plano y con `id: string`, no el documento de Mongoose. Los cuatro
+ * métodos que devolvían `FileDocument` se usaban SÓLO para estos cinco
+ * campos —se comprobó llamante por llamante, no de memoria—, y un documento
+ * vivo no sobrevive a un `JSON.stringify`: pierde los métodos y `_id` se
+ * convierte en otra cosa. Aplanarlo aquí cuesta cuatro `_id.toString()`
+ * menos en los nodos; no aplanarlo cuesta un fallo en la Fase 4.
+ */
+export interface FicheroRegistrado {
+    id: string;
+    key: string;
+    originalName: string;
+    mimeType: string;
+    size: number;
+}
+/** El registro: qué ficheros hay, quién puede verlos, y por dónde bajarlos. */
+export interface RegistroDeFicheros {
+    /** URL firmada para bajar por clave, acotada a la organización. */
+    /**
+     * Que el payload no lleve un fichero que el antivirus marcó.
+     *
+     * ⚠️ Es lo ÚNICO que el motor le pide a ficheros —un método de dieciséis—,
+     * y por eso vale un token: inyectar `FilesService` entero para esto ataba el
+     * motor a un módulo que no se muda con él.
+     */
+    assertPayloadClean(payload: unknown): Promise<{
+        blocked: false;
+    } | {
+        blocked: true;
+        reason: string;
+        fileId: string;
+        fileName?: string;
+    }>;
+    getDownloadUrlByKey(key: string, orgId: string, expiresIn?: number): Promise<string>;
+    /**
+     * URL firmada para bajar por id.
+     *
+     * ⚠️ El servicio real devuelve además el documento; aquí no. Ninguno de sus
+     * dos llamantes lo mira: los dos desestructuran `downloadUrl` y ya.
+     */
+    getDownloadUrl(fileId: string, orgId: string): Promise<{
+        downloadUrl: string;
+    }>;
+    /**
+     * URL firmada para subir, más el id y la clave con que confirmarlo.
+     *
+     * ⚠️ Cinco parámetros, no los ocho del servicio. Los tres que faltan
+     * —`social`, `folderId`, `paraOrganizacion`— son cosas del gateway: la
+     * biblioteca de media y la foto de la organización. Ningún nodo los pasa, y
+     * se comprobaron las llamadas una a una. Un contrato es lo que hace falta,
+     * no lo que el servicio ofrece.
+     */
+    getUploadUrl(orgId: string, userId: string, fileName: string, mimeType: string, workspaceId?: string): Promise<{
+        fileId: string;
+        uploadUrl: string;
+        key: string;
+    }>;
+    /** Cierra una subida. Sólo se lee `size` del resultado. */
+    confirmUpload(fileId: string, orgId: string, medidas?: {
+        width?: number;
+        height?: number;
+        durationSec?: number;
+    }): Promise<FicheroRegistrado>;
+    /**
+     * Registra bytes que el nodo ya tiene: audio de un TTS, la respuesta de un
+     * HTTP, un adjunto de Gmail o de Telegram.
+     *
+     * ⚠️ Recibe el fichero ENTERO en memoria. Ver la nota de arriba.
+     */
+    registerDirectFile(params: {
+        orgId: string;
+        workspaceId?: string;
+        ownerUserId: string;
+        buffer: Buffer;
+        mimeType: string;
+        originalName: string;
+        source: string;
+        sourceMetadata?: Record<string, unknown>;
+        skipScan?: boolean;
+        keyPrefix?: string;
+    }): Promise<FicheroRegistrado>;
+    /**
+     * Mete un flujo en la biblioteca sin pasarlo entero por memoria. Lo usa la
+     * importación de Drive.
+     *
+     * ⚠️ Un `Readable` NO se serializa. Éste es el método que obliga a rehacer
+     * el camino cuando la costura sea HTTP, no a adaptarlo.
+     */
+    ingestStreamToLibrary(params: {
+        orgId: string;
+        userId: string;
+        originalName: string;
+        mimeType: string;
+        body: Readable;
+        folderId?: string | null;
+        source: string;
+        sourceMetadata?: Record<string, unknown>;
+    }): Promise<FicheroRegistrado>;
+    /** Un fichero por id, dentro de la organización. Lanza si no existe. */
+    findOne(fileId: string, orgId: string): Promise<FicheroRegistrado>;
+    /** Marca que se ha vuelto a usar, para que la limpieza no se lo lleve. */
+    touchFile(fileId: string, orgId: string): Promise<void>;
+    deleteFile(fileId: string, orgId: string): Promise<void>;
+    deleteByKey(key: string): Promise<void>;
+    /** Cuánto ocupa la organización. Lo mira el trigger antes de ingerir. */
+    getOrgStorageUsageBytes(orgId: string): Promise<number>;
+    /** Rellena las referencias de fichero que trae un payload. */
+    resolvePayloadFileRefs(refs: FileRef[], orgId: string): Promise<FileRef[]>;
+    getChatUploadUrl(params: {
+        chatTriggerId: string;
+        orgId: string;
+        ownerUserId: string;
+        workspaceId?: string;
+        sessionId: string;
+        fileName: string;
+        mimeType: string;
+    }): Promise<{
+        fileId: string;
+        uploadUrl: string;
+        key: string;
+    }>;
+    confirmChatUpload(fileId: string, chatTriggerId: string, sessionId: string): Promise<{
+        fileId: string;
+        mimeType: string;
+        size: number;
+        originalName: string;
+        scanStatus: string;
+    }>;
+    getChatFileStatus(fileId: string, chatTriggerId: string, sessionId: string): Promise<{
+        fileId: string;
+        scanStatus: string;
+        scanMessage?: string;
+        originalName: string;
+        mimeType: string;
+    }>;
+    /** Un adjunto de chat, comprobando que es de esa sesión y está limpio. */
+    resolveChatFileRef(fileId: string, chatTriggerId: string, sessionId: string): Promise<FileRef>;
+}
+/** El almacén crudo. Sólo mueve bytes. */
+export interface AlmacenDeObjetos {
+    getDownloadUrl(key: string, expiresIn?: number): Promise<string>;
+    deleteObject(key: string): Promise<void>;
+    /**
+     * ⚠️ Opcionales las dos, igual que en el adaptador real — y no por copiar:
+     * los cinco llamantes comprueban `if (!storage.getObjectBuffer) throw`
+     * antes de usarlas. Declararlas obligatorias convertiría esas cinco
+     * guardas en código muerto y taparía el día que un almacén no las traiga.
+     */
+    getObjectBuffer?(key: string): Promise<Buffer>;
+    uploadStream?(key: string, mimeType: string, body: Readable): Promise<void>;
+}
+/**
+ * ⚠️ Cadenas y no `Symbol`, igual que el resto de tokens de la Fase 2.
+ */
+export declare const REGISTRO_DE_FICHEROS = "REGISTRO_DE_FICHEROS";
+export declare const ALMACEN_DE_OBJETOS = "ALMACEN_DE_OBJETOS";