@growconnect/growtickets-nest 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -11,8 +11,9 @@ export type { GrowTicketsTrackOptions } from './nest/services';
 export { GrowTicketsLogin, GrowTicketsOnSuccess, GrowTicketsSecondFactor } from './nest/decorators';
 export type { GrowTicketsAccountOptions } from './nest/decorators';
 export { GrowTicketsRouteGuard } from './nest/route-tag.guard';
+export { GrowTicketsMaintenanceGuard } from './nest/maintenance.guard';
 export { DEFAULT_PORTAL_PATH, DEFAULT_THROTTLE, GROWTICKETS_OPTIONS } from './nest/options';
-export type { GrowTicketsGuard, GrowTicketsModuleAsyncOptions, GrowTicketsModuleOptions, GrowTicketsSecurityOptions } from './nest/options';
+export type { GrowTicketsGuard, GrowTicketsMaintenanceOptions, GrowTicketsModuleAsyncOptions, GrowTicketsModuleOptions, GrowTicketsSecurityOptions } from './nest/options';
 export type { PublicErrorBody, Reporter } from './contracts';
 export { TICKET_REFERENCE } from './contracts';
 export { SecretValue } from './secret-value';
@@ -30,3 +31,15 @@ export type { HandlePortalRequestOptions, PortalRequest, PortalResult } from './
 export { PORTAL_ROUTES, matchPortalRoute, REFERENCE } from './proxy/portal-routes';
 export type { PortalRoute, IdentityMode, MatchedPortalRoute } from './proxy/portal-routes';
 export { SDK_NAME, SDK_VERSION } from './security/sdk';
+export type { AppCspOptions } from './security/csp';
+export { loadGrowTicketsEnv, onGrowTicketsEnvChange } from './env/load';
+export type { EnvChange } from './env/applier';
+export type { EnvChangeListener, LoadEnvOptions, LoadEnvResult, LoadEnvStatus } from './env/runtime';
+export { EnvError } from './env/errors';
+export { GrowTicketsLogService } from './logs-nest/service';
+export { GrowTicketsLogsLifecycle, GrowTicketsLogsModule } from './logs-nest/lifecycle';
+export { growTicketsLogStream } from './logs-nest/stream';
+export type { GrowTicketsLogStream, GrowTicketsLogStreamOptions } from './logs-nest/stream';
+export { flushGrowTicketsLogs, shutdownGrowTicketsLogs } from './logs-nest/api';
+export type { FlushResult } from './logs/flusher';
+export type { LogLevel, LogRecord } from './logs/types';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SDK_VERSION = exports.SDK_NAME = exports.REFERENCE = exports.matchPortalRoute = exports.PORTAL_ROUTES = exports.handleUnreadRequest = exports.handlePortalRequest = exports.createGrowTicketsClient = exports.countUnread = exports.createDefaultLogger = exports.redactByValue = exports.redactByKey = exports.statusForError = exports.toPublicError = exports.RateLimitError = exports.ExternalServiceError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.ConfigurationError = exports.GrowTicketsError = exports.getServerConfig = exports.SecretValue = exports.TICKET_REFERENCE = exports.GROWTICKETS_OPTIONS = exports.DEFAULT_THROTTLE = exports.DEFAULT_PORTAL_PATH = exports.GrowTicketsRouteGuard = exports.GrowTicketsSecondFactor = exports.GrowTicketsOnSuccess = exports.GrowTicketsLogin = exports.GrowTicketsSecurity = exports.GrowTicketsClient = exports.growTicketsMiddleware = exports.GrowTicketsModule = void 0;
+exports.shutdownGrowTicketsLogs = exports.flushGrowTicketsLogs = exports.growTicketsLogStream = exports.GrowTicketsLogsModule = exports.GrowTicketsLogsLifecycle = exports.GrowTicketsLogService = exports.EnvError = exports.onGrowTicketsEnvChange = exports.loadGrowTicketsEnv = exports.SDK_VERSION = exports.SDK_NAME = exports.REFERENCE = exports.matchPortalRoute = exports.PORTAL_ROUTES = exports.handleUnreadRequest = exports.handlePortalRequest = exports.createGrowTicketsClient = exports.countUnread = exports.createDefaultLogger = exports.redactByValue = exports.redactByKey = exports.statusForError = exports.toPublicError = exports.RateLimitError = exports.ExternalServiceError = exports.NotFoundError = exports.AuthorizationError = exports.AuthenticationError = exports.ConfigurationError = exports.GrowTicketsError = exports.getServerConfig = exports.SecretValue = exports.TICKET_REFERENCE = exports.GROWTICKETS_OPTIONS = exports.DEFAULT_THROTTLE = exports.DEFAULT_PORTAL_PATH = exports.GrowTicketsMaintenanceGuard = exports.GrowTicketsRouteGuard = exports.GrowTicketsSecondFactor = exports.GrowTicketsOnSuccess = exports.GrowTicketsLogin = exports.GrowTicketsSecurity = exports.GrowTicketsClient = exports.growTicketsMiddleware = exports.GrowTicketsModule = void 0;
 /**
  * `@growconnect/growtickets-nest`: el proxy del portal de GrowTickets y la seguridad del producto para NestJS
  * (Express o Fastify). Lo de Nest está en `./nest`; el resto es el núcleo agnóstico, el mismo de
@@ -19,6 +19,8 @@ Object.defineProperty(exports, "GrowTicketsOnSuccess", { enumerable: true, get:
 Object.defineProperty(exports, "GrowTicketsSecondFactor", { enumerable: true, get: function () { return decorators_1.GrowTicketsSecondFactor; } });
 var route_tag_guard_1 = require("./nest/route-tag.guard");
 Object.defineProperty(exports, "GrowTicketsRouteGuard", { enumerable: true, get: function () { return route_tag_guard_1.GrowTicketsRouteGuard; } });
+var maintenance_guard_1 = require("./nest/maintenance.guard");
+Object.defineProperty(exports, "GrowTicketsMaintenanceGuard", { enumerable: true, get: function () { return maintenance_guard_1.GrowTicketsMaintenanceGuard; } });
 var options_1 = require("./nest/options");
 Object.defineProperty(exports, "DEFAULT_PORTAL_PATH", { enumerable: true, get: function () { return options_1.DEFAULT_PORTAL_PATH; } });
 Object.defineProperty(exports, "DEFAULT_THROTTLE", { enumerable: true, get: function () { return options_1.DEFAULT_THROTTLE; } });
@@ -58,3 +60,18 @@ Object.defineProperty(exports, "REFERENCE", { enumerable: true, get: function ()
 var sdk_1 = require("./security/sdk");
 Object.defineProperty(exports, "SDK_NAME", { enumerable: true, get: function () { return sdk_1.SDK_NAME; } });
 Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return sdk_1.SDK_VERSION; } });
+var load_1 = require("./env/load");
+Object.defineProperty(exports, "loadGrowTicketsEnv", { enumerable: true, get: function () { return load_1.loadGrowTicketsEnv; } });
+Object.defineProperty(exports, "onGrowTicketsEnvChange", { enumerable: true, get: function () { return load_1.onGrowTicketsEnvChange; } });
+var errors_2 = require("./env/errors");
+Object.defineProperty(exports, "EnvError", { enumerable: true, get: function () { return errors_2.EnvError; } });
+var service_1 = require("./logs-nest/service");
+Object.defineProperty(exports, "GrowTicketsLogService", { enumerable: true, get: function () { return service_1.GrowTicketsLogService; } });
+var lifecycle_1 = require("./logs-nest/lifecycle");
+Object.defineProperty(exports, "GrowTicketsLogsLifecycle", { enumerable: true, get: function () { return lifecycle_1.GrowTicketsLogsLifecycle; } });
+Object.defineProperty(exports, "GrowTicketsLogsModule", { enumerable: true, get: function () { return lifecycle_1.GrowTicketsLogsModule; } });
+var stream_1 = require("./logs-nest/stream");
+Object.defineProperty(exports, "growTicketsLogStream", { enumerable: true, get: function () { return stream_1.growTicketsLogStream; } });
+var api_1 = require("./logs-nest/api");
+Object.defineProperty(exports, "flushGrowTicketsLogs", { enumerable: true, get: function () { return api_1.flushGrowTicketsLogs; } });
+Object.defineProperty(exports, "shutdownGrowTicketsLogs", { enumerable: true, get: function () { return api_1.shutdownGrowTicketsLogs; } });

package/dist/logs/buffer.d.ts

@@ -0,0 +1,25 @@
+import type { WireEntry } from './types';
+/**
+ * Las líneas capturadas que esperan al siguiente envío, en memoria y con tope.
+ *
+ * Lo que llena el tope no tumba nada: una línea leve que llega con la cola llena se descarta y se cuenta como perdida; una grave
+ * (`warning` o peor) hace sitio quitando la leve más vieja, o la más vieja si todas son graves. Lo perdido viaja en el campo
+ * `dropped` del siguiente lote, para que la central sepa cuánto NO vio.
+ */
+export declare class LogBuffer {
+    private readonly capacidad;
+    private readonly ahora;
+    private slots;
+    private perdidas;
+    constructor(capacidad?: number, ahora?: () => number);
+    add(entrada: WireEntry, grave: boolean): boolean;
+    /** Saca hasta `max` líneas, las más viejas primero. */
+    take(max: number): WireEntry[];
+    size(): number;
+    clear(): void;
+    /** Quita lo que lleva esperando desde antes de `limite` (época en ms) y lo cuenta como perdido. Devuelve cuántas. */
+    dropOlderThan(limite: number): number;
+    addLost(n: number): void;
+    /** Lo perdido desde la última vez, y a cero. */
+    takeLost(): number;
+}

package/dist/logs/buffer.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogBuffer = void 0;
+/**
+ * Las líneas capturadas que esperan al siguiente envío, en memoria y con tope.
+ *
+ * Lo que llena el tope no tumba nada: una línea leve que llega con la cola llena se descarta y se cuenta como perdida; una grave
+ * (`warning` o peor) hace sitio quitando la leve más vieja, o la más vieja si todas son graves. Lo perdido viaja en el campo
+ * `dropped` del siguiente lote, para que la central sepa cuánto NO vio.
+ */
+class LogBuffer {
+    constructor(capacidad = 10_000, ahora = Date.now) {
+        this.capacidad = capacidad;
+        this.ahora = ahora;
+        this.slots = [];
+        this.perdidas = 0;
+    }
+    add(entrada, grave) {
+        if (this.slots.length >= this.capacidad) {
+            if (!grave) {
+                this.perdidas++;
+                return false;
+            }
+            const i = this.slots.findIndex((s) => !s.severe);
+            this.slots.splice(i === -1 ? 0 : i, 1);
+            this.perdidas++;
+        }
+        this.slots.push({ entry: entrada, severe: grave, addedAt: this.ahora() });
+        return true;
+    }
+    /** Saca hasta `max` líneas, las más viejas primero. */
+    take(max) {
+        return this.slots.splice(0, max).map((s) => s.entry);
+    }
+    size() {
+        return this.slots.length;
+    }
+    clear() {
+        this.slots = [];
+    }
+    /** Quita lo que lleva esperando desde antes de `limite` (época en ms) y lo cuenta como perdido. Devuelve cuántas. */
+    dropOlderThan(limite) {
+        const antes = this.slots.length;
+        this.slots = this.slots.filter((s) => s.addedAt >= limite);
+        this.perdidas += antes - this.slots.length;
+        return antes - this.slots.length;
+    }
+    addLost(n) {
+        this.perdidas += Math.max(0, n);
+    }
+    /** Lo perdido desde la última vez, y a cero. */
+    takeLost() {
+        const n = this.perdidas;
+        this.perdidas = 0;
+        return n;
+    }
+}
+exports.LogBuffer = LogBuffer;

package/dist/logs/doctor.d.ts

@@ -0,0 +1,17 @@
+import { type Transport } from './sender';
+import type { LogsHost } from './types';
+export interface DoctorResult {
+    exitCode: number;
+    lines: string[];
+}
+export interface DoctorOptions {
+    /** Manda de verdad una línea de prueba (`info`) y comprueba que la central la acepta. Escribe en los logs del proyecto. */
+    send?: boolean;
+    transport?: Transport;
+}
+/**
+ * Comprueba de punta a punta lo que, al fallar, NO da error: sin dirección o sin clave, con la clave sin el alcance «Logs» o con el módulo
+ * apagado en el proyecto la librería no manda nada y el explorador de la mesa de ayuda queda vacío sin decir por qué. Dice qué falta y cómo
+ * arreglarlo; sale con 1 si algo impide que las líneas lleguen.
+ */
+export declare function runLogsDoctor(host: LogsHost, opciones?: DoctorOptions): Promise<DoctorResult>;

package/dist/logs/doctor.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLogsDoctor = runLogsDoctor;
+const monitor_1 = require("./monitor");
+const runtime_1 = require("./runtime");
+const sender_1 = require("./sender");
+const settings_1 = require("./settings");
+/**
+ * Comprueba de punta a punta lo que, al fallar, NO da error: sin dirección o sin clave, con la clave sin el alcance «Logs» o con el módulo
+ * apagado en el proyecto la librería no manda nada y el explorador de la mesa de ayuda queda vacío sin decir por qué. Dice qué falta y cómo
+ * arreglarlo; sale con 1 si algo impide que las líneas lleguen.
+ */
+async function runLogsDoctor(host, opciones = {}) {
+    const lineas = [];
+    let fallos = 0;
+    const ok = (texto) => void lineas.push(`✓ ${texto}`);
+    const aviso = (texto) => void lineas.push(`⚠ ${texto}`);
+    const mal = (texto) => {
+        fallos++;
+        lineas.push(`✗ ${texto}`);
+    };
+    const env = host.env ? host.env() : ((0, runtime_1.proc)()?.env ?? {});
+    const ajustes = (0, settings_1.readLogSettings)(env);
+    const necesitaNode18 = typeof (host.fetchImpl ?? globalThis.fetch) !== 'function' || typeof CompressionStream !== 'function';
+    if (necesitaNode18) {
+        mal('Los logs necesitan Node 18.18 o superior: este no tiene `fetch` o `CompressionStream`.');
+        return { exitCode: 1, lines: lineas };
+    }
+    if (ajustes.enabled)
+        ok('Los logs están encendidos en este producto (GROWTICKETS_LOGS).');
+    else
+        aviso('GROWTICKETS_LOGS está apagado: la librería no manda ninguna línea.');
+    const destino = host.target();
+    if (!destino) {
+        mal(host.problem?.() ?? 'Faltan GROWTICKETS_URL y GROWTICKETS_API_KEY en el entorno.');
+        return { exitCode: 1, lines: lineas };
+    }
+    ok(`Hablará con ${destino.baseUrl}.`);
+    const transporte = opciones.transport ?? (0, sender_1.createTransport)(host);
+    const respuesta = await transporte.get('config');
+    const datos = respuesta?.json?.data;
+    if (respuesta === null)
+        mal('La mesa de ayuda no contestó: comprueba la dirección, la red y que el cortafuegos deje salir esta conexión.');
+    else if (respuesta.status === 401)
+        mal('La mesa de ayuda no reconoce la clave de API (401): revisa GROWTICKETS_API_KEY.');
+    else if (respuesta.status === 403)
+        mal('Esta clave no tiene acceso a Logs (403): márcalo en «Claves de API» del proyecto.');
+    else if (respuesta.status === 404)
+        mal('Esa dirección no tiene la ingesta de logs (404): ¿es la de GrowTickets, y una versión con logs?');
+    else if (respuesta.status < 200 || respuesta.status >= 300)
+        mal(`La mesa de ayuda contestó con un error (HTTP ${respuesta.status}).`);
+    else if (datos?.enabled === false)
+        mal('El módulo «Logs» está apagado en este proyecto: enciéndelo en su pestaña «General».');
+    else
+        ok('La mesa de ayuda acepta los logs de este proyecto.');
+    if (opciones.send && fallos === 0) {
+        const monitor = new monitor_1.LogMonitor(host, { transport: transporte });
+        monitor.capture({ level: 'info', message: 'growtickets doctor: línea de prueba', channel: 'doctor' });
+        const envio = await monitor.flush(true);
+        if (envio.status === 'sent')
+            ok('Una línea de prueba llegó: búscala en el explorador de logs del proyecto.');
+        else
+            mal(`La línea de prueba no llegó (${envio.status}).`);
+    }
+    return { exitCode: fallos > 0 ? 1 : 0, lines: lineas };
+}

package/dist/logs/entry-builder.d.ts

@@ -0,0 +1,20 @@
+import type { Redactor } from './redactor';
+import type { LogLimits, LogRecord, WireEntry } from './types';
+export declare const DEFAULT_LIMITS: LogLimits;
+export interface BuildOptions {
+    limits: LogLimits;
+    redactor: Redactor;
+    /** La carpeta del producto: las rutas de la traza van relativas a ella (más cortas, estables entre despliegues). */
+    root: string;
+}
+/**
+ * Convierte lo que entrega un adaptador en la línea del protocolo: con los secretos tapados, el contexto sin objetos vivos y todo
+ * acotado a lo que la central dijo admitir (`logs/config`). Nunca lanza hacia fuera: si una parte no se puede convertir, esa parte
+ * se omite y la línea sale igual.
+ *
+ * ## La traza no lleva argumentos ni valores
+ *
+ * Se arma de las líneas `at …` del `stack`, que sólo traen función, archivo y línea; el mensaje del error va aparte y también pasa por el
+ * tapado. Las rutas son relativas a la carpeta del producto.
+ */
+export declare function buildEntry(registro: LogRecord, opciones: BuildOptions): WireEntry;

package/dist/logs/entry-builder.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LIMITS = void 0;
+exports.buildEntry = buildEntry;
+const normalize_1 = require("./normalize");
+const runtime_1 = require("./runtime");
+/** Lo más que ocupa la traza de una línea, en bytes: la central corta en 12.288. */
+const TRACE_BYTES = 12_288;
+const MAX_CAUSES = 3;
+const CAUSE_FRAMES = 5;
+exports.DEFAULT_LIMITS = { messageBytes: 8192, contextBytes: 16_384, traceFrames: 50 };
+/**
+ * Convierte lo que entrega un adaptador en la línea del protocolo: con los secretos tapados, el contexto sin objetos vivos y todo
+ * acotado a lo que la central dijo admitir (`logs/config`). Nunca lanza hacia fuera: si una parte no se puede convertir, esa parte
+ * se omite y la línea sale igual.
+ *
+ * ## La traza no lleva argumentos ni valores
+ *
+ * Se arma de las líneas `at …` del `stack`, que sólo traen función, archivo y línea; el mensaje del error va aparte y también pasa por el
+ * tapado. Las rutas son relativas a la carpeta del producto.
+ */
+function buildEntry(registro, opciones) {
+    const { limits, redactor } = opciones;
+    const entrada = {
+        at: toIso(registro.time),
+        level: registro.level,
+        message: redactAndCut(redactor, String(registro.message ?? '').trim(), limits.messageBytes),
+    };
+    const canal = typeof registro.channel === 'string' ? registro.channel.trim().slice(0, 60) : '';
+    if (canal !== '')
+        entrada.channel = canal;
+    const contexto = contextOf(registro.context, limits.contextBytes, redactor);
+    if (contexto)
+        entrada.context = contexto;
+    const excepcion = registro.error ? exceptionOf(registro.error, limits.traceFrames, opciones) : null;
+    if (excepcion)
+        entrada.exception = excepcion;
+    return entrada;
+}
+function toIso(tiempo) {
+    let fecha;
+    if (typeof tiempo === 'number')
+        fecha = new Date(tiempo > 1e11 ? tiempo : tiempo * 1000);
+    else if (tiempo instanceof Date)
+        fecha = tiempo;
+    else if (typeof tiempo === 'string' && tiempo !== '')
+        fecha = new Date(tiempo);
+    else
+        fecha = new Date();
+    return (Number.isNaN(fecha.getTime()) ? new Date() : fecha).toISOString();
+}
+/**
+ * El contexto, ya convertido, tapado y acotado en bytes. Si no cabe se queda con las primeras claves que quepan y lo dice con
+ * `_truncated`: mejor un contexto incompleto que perder la línea.
+ */
+function contextOf(contexto, bytes, redactor) {
+    const seguro = (0, normalize_1.safeContext)(contexto);
+    if (!seguro)
+        return null;
+    const limpio = redactor.context(seguro);
+    if ((0, runtime_1.byteLength)(JSON.stringify(limpio)) <= bytes)
+        return limpio;
+    const cabe = {};
+    for (const [clave, valor] of Object.entries(limpio)) {
+        if ((0, runtime_1.byteLength)(JSON.stringify({ ...cabe, [clave]: valor, _truncated: true })) > bytes)
+            break;
+        cabe[clave] = valor;
+    }
+    return { ...cabe, _truncated: true };
+}
+function exceptionOf(error, marcos, opciones) {
+    const clase = text(error.type) ?? text(error.name) ?? 'Error';
+    const mensaje = text(error.message) ?? '';
+    const pila = text(error.stack);
+    const primero = pila ? firstFrame(pila) : null;
+    let traza = pila ? traceOf(pila, marcos, opciones.root) : `${clase}${mensaje ? `: ${mensaje}` : ''}`;
+    for (let causa = error.cause, i = 0; causa && typeof causa === 'object' && i < MAX_CAUSES; causa = causa.cause, i++) {
+        const c = causa;
+        const nombre = text(c.type) ?? text(c.name) ?? 'Error';
+        const cuerpo = text(c.stack) ? traceOf(text(c.stack), CAUSE_FRAMES, opciones.root) : `${nombre}: ${text(c.message) ?? ''}`;
+        traza += `\n\nCaused by: ${cuerpo}`;
+    }
+    return {
+        class: (0, normalize_1.cutString)(clase, 191),
+        file: primero ? (0, normalize_1.cutString)(relative(primero.file, opciones.root), 255) : null,
+        line: primero ? primero.line : null,
+        trace: redactAndCut(opciones.redactor, traza, TRACE_BYTES),
+    };
+}
+function text(valor) {
+    return typeof valor === 'string' && valor !== '' ? valor : null;
+}
+/** El encabezado del `stack` (clase y mensaje, que puede ocupar varias líneas) y sus primeras `marcos` líneas `at …`, con rutas relativas. */
+function traceOf(pila, marcos, root) {
+    const lineas = pila.split('\n');
+    const inicio = lineas.findIndex((linea) => /^\s+at /.test(linea));
+    const encabezado = inicio === -1 ? lineas : lineas.slice(0, inicio);
+    const frames = inicio === -1 ? [] : lineas.slice(inicio).filter((linea) => /^\s+at /.test(linea));
+    return [...encabezado, ...frames.slice(0, Math.max(1, marcos))].map((linea) => relative(linea, root)).join('\n');
+}
+const FRAME = /^\s+at (?:.+? \()?(.+?):(\d+):\d+\)?$/;
+/** El primer marco que no es interno de Node: de ahí salen el archivo y la línea, como los de la excepción de Laravel. */
+function firstFrame(pila) {
+    for (const linea of pila.split('\n')) {
+        const marco = FRAME.exec(linea);
+        if (!marco || !marco[1] || !marco[2])
+            continue;
+        const archivo = marco[1].replace(/^file:\/\//, '');
+        if (archivo.startsWith('node:') || archivo === '<anonymous>')
+            continue;
+        return { file: archivo, line: Number(marco[2]) };
+    }
+    return null;
+}
+function relative(ruta, root) {
+    if (root.length < 2)
+        return ruta;
+    const base = root.endsWith('/') ? root : `${root}/`;
+    return ruta.split(`file://${base}`).join('').split(base).join('');
+}
+/**
+ * Tapar ANTES de cortar: cortando primero, un secreto partido justo en el borde ya no casaba ni como literal ni con su patrón y salía
+ * la mitad. Se tapa una ventana del doble (no el texto entero, que puede ser enorme) y después se corta.
+ */
+function redactAndCut(redactor, texto, bytes) {
+    return (0, runtime_1.cutBytes)(redactor.text((0, runtime_1.cutBytes)(texto, bytes * 2)), bytes);
+}

package/dist/logs/flusher.d.ts

@@ -0,0 +1,72 @@
+import type { LogBuffer } from './buffer';
+import type { RemoteConfig } from './remote-config';
+import { type Transport } from './sender';
+import type { LogSettings } from './settings';
+import type { LogsHost } from './types';
+/** Lo que lleva más de esto sin enviarse (por una caída de la mesa de ayuda) se descarta y se cuenta. */
+export declare const MAX_AGE_MS = 3600000;
+export type FlushStatus = 'idle' | 'disabled' | 'backoff' | 'sent' | 'failed' | 'busy' | 'unconfigured';
+export interface FlushResult {
+    status: FlushStatus;
+    entries: number;
+    chunks: number;
+    dropped: number;
+    rejected: number;
+}
+export interface FlusherDeps {
+    host: LogsHost;
+    transport: Transport;
+    remote: RemoteConfig;
+    buffer: LogBuffer;
+    settings: () => LogSettings;
+    warn: (clave: string, mensaje: string) => void;
+    now?: () => number;
+    uuid?: () => string;
+}
+/**
+ * Saca lo capturado de la cola y lo manda a la mesa de ayuda en lotes comprimidos.
+ *
+ * ## Un lote se REINTENTA con el mismo identificador
+ *
+ * Si el envío expira no se sabe si la central lo procesó. Reenviar el MISMO lote con el mismo `batch_id` es seguro (la central reconoce
+ * el duplicado); reenviar otro conjunto duplicaría las líneas. Por eso un lote en vuelo se guarda (`pending`) y es lo primero que se
+ * reintenta.
+ *
+ * ## Qué pasa cuando falla
+ *
+ * Sin respuesta, 401, 403, 408, 429 o 5xx: se conserva y se reintenta; tras tres fallos seguidos hay un corte de cinco minutos. Otro 4xx
+ * (el lote es inválido) no lo arregla ningún reintento: se descarta y se cuenta como perdido. Lo que lleva más de una hora sin enviarse
+ * se descarta también. Todo lo perdido viaja en `dropped` del siguiente lote: la central sabe cuánto NO vio. Si responde que los logs
+ * están apagados, se descarta todo y se deja de capturar hasta que vuelva a decir que sí.
+ *
+ * Sólo hay UN envío en vuelo a la vez, y nada de esto lanza hacia fuera.
+ */
+export declare class Flusher {
+    private readonly deps;
+    private pendientes;
+    private fallos;
+    private reintentoEn;
+    private enVuelo;
+    private readonly ahora;
+    private readonly uuid;
+    constructor(deps: FlusherDeps);
+    flush(opciones?: {
+        force?: boolean;
+        final?: boolean;
+    }): Promise<FlushResult>;
+    /** Lo que hay sin confirmar y cómo van los reintentos. Lo usan las pruebas y `doctor`. */
+    state(): {
+        pendientes: number;
+        fallos: number;
+        reintentoEn: number;
+    };
+    private enviarTodo;
+    private descartarTodo;
+    private descartarViejo;
+    /** Parte lo que hay en la cola en lotes de `max_entries` líneas y de poco más de tres megas, el primero con lo perdido hasta ahora. */
+    private formarLotes;
+    /** Un lote que comprimido no cabe se parte por la mitad: cada mitad con su identificador, y lo perdido en la primera. */
+    private partir;
+    private cuerpo;
+    private fallar;
+}

package/dist/logs/flusher.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Flusher = exports.MAX_AGE_MS = void 0;
+const runtime_1 = require("./runtime");
+const sender_1 = require("./sender");
+const FAILURES_BEFORE_BREAK = 3;
+const BREAK_MS = 300_000;
+const MAX_CHUNKS = 10;
+const FINAL_CHUNKS = 20;
+/** Lo más que pesa un lote sin comprimir (la central corta en 4 MiB) y lo más que pesa comprimido (corta en 1 MiB). */
+const MAX_BODY_CHARS = 3_000_000;
+const MAX_GZIP_BYTES = 1_000_000;
+/** Lo que lleva más de esto sin enviarse (por una caída de la mesa de ayuda) se descarta y se cuenta. */
+exports.MAX_AGE_MS = 3_600_000;
+/**
+ * Saca lo capturado de la cola y lo manda a la mesa de ayuda en lotes comprimidos.
+ *
+ * ## Un lote se REINTENTA con el mismo identificador
+ *
+ * Si el envío expira no se sabe si la central lo procesó. Reenviar el MISMO lote con el mismo `batch_id` es seguro (la central reconoce
+ * el duplicado); reenviar otro conjunto duplicaría las líneas. Por eso un lote en vuelo se guarda (`pending`) y es lo primero que se
+ * reintenta.
+ *
+ * ## Qué pasa cuando falla
+ *
+ * Sin respuesta, 401, 403, 408, 429 o 5xx: se conserva y se reintenta; tras tres fallos seguidos hay un corte de cinco minutos. Otro 4xx
+ * (el lote es inválido) no lo arregla ningún reintento: se descarta y se cuenta como perdido. Lo que lleva más de una hora sin enviarse
+ * se descarta también. Todo lo perdido viaja en `dropped` del siguiente lote: la central sabe cuánto NO vio. Si responde que los logs
+ * están apagados, se descarta todo y se deja de capturar hasta que vuelva a decir que sí.
+ *
+ * Sólo hay UN envío en vuelo a la vez, y nada de esto lanza hacia fuera.
+ */
+class Flusher {
+    constructor(deps) {
+        this.deps = deps;
+        this.pendientes = [];
+        this.fallos = 0;
+        this.reintentoEn = 0;
+        this.enVuelo = false;
+        this.ahora = deps.now ?? Date.now;
+        this.uuid = deps.uuid ?? runtime_1.uuid;
+    }
+    async flush(opciones = {}) {
+        if (this.enVuelo)
+            return resultado('busy');
+        this.enVuelo = true;
+        try {
+            return await this.enviarTodo(opciones.force === true, opciones.final === true);
+        }
+        catch {
+            return resultado('failed');
+        }
+        finally {
+            this.enVuelo = false;
+        }
+    }
+    /** Lo que hay sin confirmar y cómo van los reintentos. Lo usan las pruebas y `doctor`. */
+    state() {
+        return { pendientes: this.pendientes.reduce((n, c) => n + c.entries.length, 0), fallos: this.fallos, reintentoEn: this.reintentoEn };
+    }
+    async enviarTodo(forzar, final) {
+        const { host, remote, buffer, transport } = this.deps;
+        const salida = resultado('idle');
+        if (!this.deps.settings().enabled) {
+            this.descartarTodo();
+            return salida;
+        }
+        if (!host.target())
+            return { ...salida, status: 'unconfigured' };
+        await remote.refreshIfStale();
+        if (remote.enabled() === false) {
+            this.descartarTodo();
+            return { ...salida, status: 'disabled' };
+        }
+        const ahora = this.ahora();
+        if (!forzar && ahora < this.reintentoEn)
+            return { ...salida, status: 'backoff' };
+        this.descartarViejo(ahora);
+        if (this.pendientes.length === 0)
+            this.formarLotes(final ? FINAL_CHUNKS : MAX_CHUNKS, ahora);
+        if (this.pendientes.length === 0)
+            return salida;
+        while (this.pendientes.length > 0) {
+            const lote = this.pendientes[0];
+            const comprimido = await (0, sender_1.gzipJson)(this.cuerpo(lote, ahora));
+            if (comprimido.length > MAX_GZIP_BYTES && lote.entries.length > 1) {
+                this.partir(lote);
+                continue;
+            }
+            const respuesta = await transport.post('batches', comprimido);
+            if (respuesta === null || reintentable(respuesta.status)) {
+                this.fallar(respuesta?.status ?? null, ahora);
+                return { ...salida, status: 'failed' };
+            }
+            this.pendientes.shift();
+            if (respuesta.status < 200 || respuesta.status >= 300) {
+                buffer.addLost(lote.entries.length + lote.dropped);
+                this.deps.warn('rechazado', `La mesa de ayuda rechazó un lote de logs (HTTP ${respuesta.status}) y se descarta.`);
+                continue;
+            }
+            const datos = respuesta.json?.data;
+            if (datos?.enabled === false) {
+                remote.markDisabled();
+                this.descartarTodo();
+                return { ...salida, status: 'disabled' };
+            }
+            salida.entries += lote.entries.length;
+            salida.chunks++;
+            salida.dropped += lote.dropped;
+            salida.rejected += Array.isArray(datos?.rejected) ? datos.rejected.length : 0;
+        }
+        this.fallos = 0;
+        this.reintentoEn = 0;
+        return { ...salida, status: salida.chunks > 0 ? 'sent' : 'idle' };
+    }
+    descartarTodo() {
+        this.deps.buffer.clear();
+        this.deps.buffer.takeLost();
+        this.pendientes = [];
+    }
+    descartarViejo(ahora) {
+        const limite = ahora - exports.MAX_AGE_MS;
+        this.deps.buffer.dropOlderThan(limite);
+        const vigentes = this.pendientes.filter((c) => c.formedAt >= limite);
+        for (const caduco of this.pendientes.filter((c) => c.formedAt < limite))
+            this.deps.buffer.addLost(caduco.entries.length + caduco.dropped);
+        this.pendientes = vigentes;
+    }
+    /** Parte lo que hay en la cola en lotes de `max_entries` líneas y de poco más de tres megas, el primero con lo perdido hasta ahora. */
+    formarLotes(max, ahora) {
+        const { buffer, remote } = this.deps;
+        const entradas = buffer.take(remote.maxEntries() * max);
+        if (entradas.length === 0)
+            return;
+        const lotes = [];
+        let actual = [];
+        let peso = 0;
+        const cerrar = () => {
+            if (actual.length > 0)
+                lotes.push({ id: this.uuid(), entries: actual, dropped: 0, formedAt: ahora });
+            actual = [];
+            peso = 0;
+        };
+        for (const entrada of entradas) {
+            const largo = JSON.stringify(entrada).length;
+            if (actual.length >= remote.maxEntries() || (peso + largo > MAX_BODY_CHARS && actual.length > 0))
+                cerrar();
+            actual.push(entrada);
+            peso += largo;
+        }
+        cerrar();
+        lotes[0].dropped = buffer.takeLost();
+        this.pendientes = lotes;
+    }
+    /** Un lote que comprimido no cabe se parte por la mitad: cada mitad con su identificador, y lo perdido en la primera. */
+    partir(lote) {
+        const mitad = Math.ceil(lote.entries.length / 2);
+        this.pendientes.splice(0, 1, { id: this.uuid(), entries: lote.entries.slice(0, mitad), dropped: lote.dropped, formedAt: lote.formedAt }, { id: this.uuid(), entries: lote.entries.slice(mitad), dropped: 0, formedAt: lote.formedAt });
+    }
+    cuerpo(lote, ahora) {
+        const origen = this.deps.settings().origin;
+        return {
+            protocol: 1,
+            batch_id: lote.id,
+            sent_at: new Date(ahora).toISOString(),
+            dropped: lote.dropped,
+            sdk: this.deps.host.sdk,
+            instance: this.deps.host.instance,
+            remote: 'off',
+            entries: lote.entries,
+            ...(origen ? { origin: origen } : {}),
+        };
+    }
+    fallar(estado, ahora) {
+        this.fallos++;
+        if (estado === 401 || estado === 403) {
+            this.deps.warn('clave', `La mesa de ayuda rechazó la clave de API (HTTP ${estado}): comprueba GROWTICKETS_API_KEY y que lleve el alcance «Logs».`);
+        }
+        if (this.fallos >= FAILURES_BEFORE_BREAK)
+            this.reintentoEn = ahora + BREAK_MS;
+    }
+}
+exports.Flusher = Flusher;
+function reintentable(estado) {
+    return estado === 401 || estado === 403 || estado === 408 || estado === 429 || estado >= 500;
+}
+function resultado(status) {
+    return { status, entries: 0, chunks: 0, dropped: 0, rejected: 0 };
+}

package/dist/logs/format.d.ts

@@ -0,0 +1,4 @@
+/** Lo que `console.log` haría con los argumentos: la sustitución estilo printf del primero (`%s`, `%d`, `%j`…) y el resto unido con espacios. */
+export declare function formatArgs(args: readonly unknown[]): string;
+/** Un valor como texto, sin ejecutar nada suyo: un `Error` como `Clase: mensaje`, un objeto como JSON (acotado y sin ciclos). */
+export declare function stringify(valor: unknown): string;