@mks2508/better-logger 0.14.0-alpha.2 → 0.18.2-alpha.2

package/dist/transports/HttpTransport.d.ts

@@ -0,0 +1,180 @@
+import type { TransportRecord, TransportOptions, IBufferedTransport, HookLogEntry } from '../types/index.js';
+/**
+ * Configuración para {@link HttpTransport}. Extiende {@link TransportOptions}
+ * con parámetros HTTP: URL destino, headers custom, buffer acotado,
+ * retry con backoff para fallos transitorios, timeout de fetch por intento, y
+ * un hook `onError` que reporta drops (overflow / 4xx / retry exhausto)
+ * sin escalar excepciones al caller.
+ *
+ * @example
+ * // Mínimo: solo URL
+ * new HttpTransport({ url: 'https://logs.example.com/ingest' });
+ *
+ * @example
+ * // Con retry/backoff ajustado y hook de errores
+ * new HttpTransport({
+ *   url: 'https://logs.example.com/ingest',
+ *   headers: { Authorization: 'Bearer <REDACTED>' },
+ *   maxRetries: 5,
+ *   initialBackoffMs: 500,
+ *   maxBackoffMs: 30_000,
+ *   fetchTimeoutMs: 5_000,
+ *   onError: (entry) => metrics.increment('log_drop', { reason: entry.message })
+ * });
+ */
+export interface HttpTransportOptions extends TransportOptions {
+    /** URL destino. Se usa POST con body JSON. */
+    url?: string;
+    /** Headers extra de la request (ej. `Authorization: Bearer ...`). */
+    headers?: Record<string, string>;
+    /** Tope máximo de records en buffer. En overflow se dropea el más viejo. */
+    maxBufferSize?: number;
+    /** Reintentos consecutivos por batch antes de dropear los records. */
+    maxRetries?: number;
+    /** Backoff inicial en ms. Duplica por intento hasta `maxBackoffMs`. */
+    initialBackoffMs?: number;
+    /** Techo de backoff en ms. */
+    maxBackoffMs?: number;
+    /** Timeout del fetch en ms (por intento). Default 10_000. */
+    fetchTimeoutMs?: number;
+    /**
+     * Hook opcional que se dispara cuando el buffer hace overflow o un batch
+     * se dropea tras `maxRetries`. Recibe una entrada {@link HookLogEntry}
+     * sintética.
+     */
+    onError?: (entry: HookLogEntry) => void | Promise<void>;
+}
+/**
+ * Transport basado en HTTP. Bufferea records, los batcha por tamaño o
+ * intervalo, POSTea el batch como JSON, y reporta fallos vía retry, buffer
+ * acotado y un hook `onError` — nunca un `.catch(() => {})` silencioso.
+ *
+ * Lifecycle de cada batch (driveado internamente por `sendWithRetry`):
+ *  1. `fetch(url, { method: 'POST', body, signal })` con un `AbortController`
+ *     que aborta tras `fetchTimeoutMs`.
+ *  2. Si `response.ok` → batch considerado entregado.
+ *  3. Si `4xx` → dropeado sin reintento: el cliente nunca se recupera de un
+ *     error de URL/auth/payload mal formado. Se dispara `onError`.
+ *  4. Si `5xx` o `fetch` lanza (red caída / abort por timeout) → reintento con
+ *     backoff exponencial: arranca en `initialBackoffMs`, duplica por intento,
+ *     techo `maxBackoffMs`, hasta `maxRetries` intentos. Tras el agotamiento
+ *     el batch se re-bufferiza (o se trimea contra `maxBufferSize`) y se
+ *     dispara `onError` con `droppedCount`.
+ *
+ * El body por defecto es el envelope JSON `{ logs: TransportRecord[] }`.
+ * Para cambiar el wire format, sobrescribe los hooks `protected`
+ * {@link HttpTransport.serializeBody} y {@link HttpTransport.buildHeaders}
+ * (referencia: {@link OtlpTransport}).
+ *
+ * Extender esta clase es la vía recomendada para shippear un transport
+ * nuevo orientado a HTTP.
+ *
+ * @example
+ * // Registro en un logger
+ * import logger from '@mks2508/better-logger';
+ * import { HttpTransport } from '@mks2508/better-logger/transports';
+ *
+ * logger.addTransport({
+ *   target: new HttpTransport({
+ *     url: 'https://logs.example.com/ingest',
+ *     flushInterval: 5_000,
+ *     batchSize: 100,
+ *     onError: (entry) => console.error('[log-drop]', entry.message)
+ *   })
+ * });
+ *
+ * @see {@link HttpTransportOptions}
+ * @see {@link OtlpTransport}
+ */
+export declare class HttpTransport implements IBufferedTransport {
+    /** Identificador del transport. Los loggers lo usan para lookup, dedup y logs de diagnóstico. */
+    readonly name: string;
+    private buffer;
+    private flushTimer?;
+    private closed;
+    /** Bag de options — `protected` para que subclasses (ej. {@link OtlpTransport}) puedan leerlo o extenderlo. */
+    protected options: HttpTransportOptions;
+    /**
+     * Crea una instancia de {@link HttpTransport}.
+     *
+     * Los campos omitidos en `options` se rellenan con defaults sensatos
+     * (`batchSize=50`, `maxBufferSize=10_000`, `maxRetries=3`,
+     * `initialBackoffMs=250`, `maxBackoffMs=5_000`, `fetchTimeoutMs=10_000`).
+     * Si se pasa `flushInterval`, arranca un `setInterval` que flushea cada
+     * N ms; si se omite, el flush solo dispara por llenado de `batchSize`.
+     *
+     * @param {HttpTransportOptions} [options] - Configuración opcional. Si se omite por completo, el transport queda inactivo hasta que se setee `options.url` por otra vía (subclasses).
+     *
+     * @example
+     * const t = new HttpTransport({
+     *   url: 'https://logs.example.com/ingest',
+     *   flushInterval: 5_000
+     * });
+     */
+    constructor(options?: HttpTransportOptions);
+    /** Records actualmente encolados esperando el próximo flush. */
+    get bufferSize(): number;
+    /** Capacidad máxima del buffer. Al superarla, el registro más viejo se dropea y se notifica vía `onError`. */
+    get maxBufferSize(): number;
+    /**
+     * Indica si el transport está listo para aceptar y entregar records.
+     * Devuelve `false` tras {@link close} o si no se configuró `url`.
+     *
+     * @returns {boolean} `true` si el transport puede enviar.
+     */
+    isReady(): boolean;
+    /**
+     * Encola un record en el buffer. Si el buffer está lleno, aplica la
+     * política de overflow (dropea el más viejo + dispara `onError`). Si tras
+     * el push se alcanza `batchSize`, dispara un flush asíncrono (sin await).
+     *
+     * No-op si el transport ya fue cerrado ({@link close}).
+     *
+     * @param {TransportRecord} record - Registro a encolar.
+     */
+    write(record: TransportRecord): void;
+    /**
+     * Serializa un batch al body de la request. Las subclasses sobrescriben
+     * para cambiar la codificación (ej. {@link OtlpTransport} produce OTLP/HTTP
+     * JSON en vez del envelope default `{ logs: [...] }`).
+     *
+     */
+    protected serializeBody(records: TransportRecord[]): string;
+    /**
+     * Construye los headers de la request. Las subclasses pueden prependear
+     * headers transport-specific (ej. `signoz-ingestion-key`).
+     *
+     */
+    protected buildHeaders(): Record<string, string>;
+    private applyOverflowPolicy;
+    /**
+     * Flushea el buffer actual: toma un snapshot de los records pendientes,
+     * los envía con retry/backoff vía `sendWithRetry`, y ante fallo los
+     * re-bufferiza preservando el orden. Si la re-bufferización excede
+     * `maxBufferSize`, trimea los más viejos y dispara `onError` con
+     * `droppedCount`.
+     *
+     * No-op si el transport está cerrado, el buffer está vacío o no hay
+     * `url` configurada.
+     *
+     * @returns {Promise<void>} Resuelve cuando el intento de entrega del batch actual terminó (success, drop definitivo o no-op).
+     *
+     * @see {@link HttpTransportOptions.onError}
+     */
+    flush(): Promise<void>;
+    private sendWithRetry;
+    /**
+     * Cierra el transport: marca el flag `closed`, detiene el timer de
+     * `flushInterval` si estaba corriendo, y ejecuta un flush final para
+     * entregar lo pendiente.
+     *
+     * Tras `close()`, todo {@link write} posterior es no-op y
+     * {@link isReady} devuelve `false`.
+     *
+     * @returns {Promise<void>} Resuelve cuando el flush final termina.
+     *
+     * @see {@link flush}
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=HttpTransport.d.ts.map

package/dist/transports/HttpTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpTransport.d.ts","sourceRoot":"","sources":["../../src/transports/HttpTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,eAAe,EACf,gBAAgB,EAEhB,kBAAkB,EAElB,YAAY,EACf,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC1D,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,aAAc,YAAW,kBAAkB;IACpD,iGAAiG;IACjG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAU;IAE/B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,UAAU,CAAC,CAAiC;IACpD,OAAO,CAAC,MAAM,CAAS;IAEvB,+GAA+G;IAC/G,SAAS,CAAC,OAAO,EAAE,oBAAoB,CAAC;IAExC;;;;;;;;;;;;;;;;OAgBG;gBACS,OAAO,CAAC,EAAE,oBAAoB;IAkB1C,gEAAgE;IAChE,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,8GAA8G;IAC9G,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;;;;OAKG;IACH,OAAO,IAAI,OAAO;IAIlB;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAepC;;;;;OAKG;IACH,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM;IAI3D;;;;OAIG;IACH,SAAS,CAAC,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAOhD,OAAO,CAAC,mBAAmB;IAgB3B;;;;;;;;;;;;;OAaG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAiCd,aAAa;IA4E3B;;;;;;;;;;;OAWG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ/B"}

package/dist/transports/OtlpTransport.d.ts

@@ -0,0 +1,165 @@
+import type { TransportRecord, HookLogEntry } from '../types/index.js';
+import { HttpTransport } from './HttpTransport.js';
+/**
+ * Opciones de configuración para {@link OtlpTransport}.
+ */
+export interface OtlpTransportOptions {
+    /**
+     * URL base del collector OTLP/HTTP, p.ej. `https://collector.example.com:4318`.
+     * El transport hace POST a `<endpoint>/v1/logs`.
+     */
+    endpoint: string;
+    /** Atributo de resource `service.name`. Requerido por la spec OTel. */
+    serviceName: string;
+    /** Atributo de resource `service.version`. Recomendado. */
+    serviceVersion?: string;
+    /** Atributo de resource `deployment.environment` (production/staging/dev). */
+    environment?: string;
+    /** Atributos de resource adicionales que se merguean en el bloque `resource`. */
+    resourceAttributes?: Record<string, string>;
+    /**
+     * Nombre de la env var cuyo valor se envía como header
+     * `signoz-ingestion-key`. El transport lee `process.env[ingestKeyEnvVar]`
+     * al construirse — nunca desde un string literal. Si la env var no está
+     * seteada, el header se omite silenciosamente (el collector OTLP usa el
+     * path default sin auth).
+     */
+    ingestKeyEnvVar?: string;
+    /** Headers extra que se merguean (Authorization, X-* custom). */
+    headers?: Record<string, string>;
+    /** Tamaño del batch (records por POST). Default 50. */
+    batchSize?: number;
+    /** Intervalo de flush en ms. */
+    flushInterval?: number;
+    /** Tope duro de records bufferizados. Default 10_000. */
+    maxBufferSize?: number;
+    /** Reintentos máximos por batch. Default 3. */
+    maxRetries?: number;
+    /** Backoff inicial en ms. Default 250. */
+    initialBackoffMs?: number;
+    /** Techo de backoff en ms. Default 5_000. */
+    maxBackoffMs?: number;
+    /** Timeout por fetch en ms. Default 10_000. */
+    fetchTimeoutMs?: number;
+    /** Hook que se dispara ante falla del transport (drop, agotamiento de reintentos, ...). */
+    onError?: (entry: HookLogEntry) => void | Promise<void>;
+}
+/**
+ * Shape del body JSON de un request OTLP/HTTP. Coincide con el JSON mapping
+ * del proto `LogsData` para `/v1/logs`. Ver
+ * https://opentelemetry.io/docs/specs/otlp/#json-protobuf-encoding
+ */
+interface OtlpLogsPayload {
+    resourceLogs: Array<{
+        resource: {
+            attributes: Array<{
+                key: string;
+                value: {
+                    stringValue: string;
+                };
+            }>;
+        };
+        scopeLogs: Array<{
+            scope: {
+                name: string;
+                version: string;
+            };
+            logRecords: Array<OtlpLogRecord>;
+        }>;
+    }>;
+}
+/**
+ * Registro individual de log dentro del payload OTLP. Mappea mensaje,
+ * severidad, timestamp (en nanosegundos), atributos y contexto de trace al
+ * formato `LogRecord` definido por la spec OTel Logs.
+ * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/
+ */
+interface OtlpLogRecord {
+    timeUnixNano: string;
+    observedTimeUnixNano: string;
+    severityNumber: number;
+    severityText: string;
+    body: {
+        stringValue: string;
+    };
+    attributes?: Array<{
+        key: string;
+        value: OtlpAttributeValue;
+    }>;
+    traceId?: string;
+    spanId?: string;
+}
+/**
+ * Unión discriminada que representa un `AnyValue` de OTel para atributos de
+ * log. Soporta string, int, double, bool y arrays anidados (homogéneos o
+ * mixtos).
+ * @see https://opentelemetry.io/docs/specs/otel/common/
+ */
+type OtlpAttributeValue = {
+    stringValue: string;
+} | {
+    intValue: number;
+} | {
+    doubleValue: number;
+} | {
+    boolValue: boolean;
+} | {
+    arrayValue: {
+        values: OtlpAttributeValue[];
+    };
+};
+/**
+ * Transport OTLP/HTTP para SigNoz (o cualquier backend compatible con OTLP).
+ *
+ * Extiende {@link HttpTransport} — hereda retry, buffer acotado, status check,
+ * close asincrónico y el hook on-error. Overridea únicamente la shape del
+ * payload y los headers del request.
+ *
+ * @example
+ * ```ts
+ * logger.addTransport({
+ *   target: new OtlpTransport({
+ *     endpoint: 'https://otelcollector.example.com:4318',
+ *     serviceName: 'my-app',
+ *     serviceVersion: '1.2.3',
+ *     environment: 'production',
+ *     ingestKeyEnvVar: 'SIGNOZ_KEY'
+ *   })
+ * });
+ * ```
+ */
+export declare class OtlpTransport extends HttpTransport {
+    readonly name = "otlp";
+    private readonly resource;
+    /** Resuelto al construir. Nunca se loguea, nunca se escribe a source. */
+    private readonly ingestKeyValue;
+    constructor(options: OtlpTransportOptions);
+    /**
+     * Construye el payload JSON OTLP/HTTP a partir de los records bufferizados.
+     * Un bloque `resourceLogs` por batch (sigue la guía de batching del
+     * collector OTel). Expuesto para tests y para subclasses custom de transport.
+     *
+     * @param records - Records de log a serializar dentro del payload.
+     * @returns Objeto `LogsData` listo para `JSON.stringify`.
+     * @see {@link OtlpLogsPayload}
+     */
+    buildPayload(records: TransportRecord[]): OtlpLogsPayload;
+    /**
+     * Serializa un batch al body JSON del request OTLP/HTTP. Override de
+     * {@link HttpTransport.serializeBody}.
+     *
+     * @param records - Records del batch a serializar.
+     * @returns String JSON listo para usar como `body` del fetch POST.
+     */
+    protected serializeBody(records: TransportRecord[]): string;
+    /**
+     * Construye los headers del request. Agrega `signoz-ingestion-key` con el
+     * valor resuelto al construir (nunca se loguea, nunca se escribe a source).
+     *
+     * @returns Record de headers a merguear en el fetch.
+     */
+    protected buildHeaders(): Record<string, string>;
+    private toLogRecord;
+}
+export {};
+//# sourceMappingURL=OtlpTransport.d.ts.map

package/dist/transports/OtlpTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OtlpTransport.d.ts","sourceRoot":"","sources":["../../src/transports/OtlpTransport.ts"],"names":[],"mappings":"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"}

package/dist/transports/TransportBridge.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview TransportBridge — facade de TransportManager.
+ * Encapsula el lifecycle de transports: add, remove, flush, close.
+ *
+ * @internal
+ */
+import type { TransportTarget } from '../types/index.js';
+import { TransportManager } from '../transports/index.js';
+/**
+ * Resultado de añadir un transport.
+ */
+export interface AddTransportResult {
+    /** ID único del transport. */
+    id: string;
+    /** La instancia de TransportManager (creada al primer add). */
+    manager: TransportManager;
+}
+/**
+ * Bridge para la gestión del lifecycle de transports.
+ *
+ * @internal
+ */
+export interface TransportBridge {
+    /** Añade un transport y devuelve su ID. */
+    addTransport(target: TransportTarget): string;
+    /** Elimina un transport por ID. Devuelve `true` si se eliminó. */
+    removeTransport(id: string): boolean;
+    /** Fuerza el flush de todos los buffers de transports. */
+    flushTransports(): Promise<void>;
+    /** Cierra todos los transports de forma graceful. */
+    closeTransports(): Promise<void>;
+    /** Devuelve el manager subyacente (o `undefined` si nunca se usó). */
+    getTransportManager(): TransportManager | undefined;
+    /** Escribe un transport record (fire-and-forget). No-op si el manager no está inicializado. */
+    writeRecord(record: Parameters<TransportManager['write']>[0]): void;
+}
+/**
+ * Crea una instancia de {@link TransportBridge}.
+ *
+ * @internal
+ */
+export declare function createTransportBridge(): TransportBridge;
+//# sourceMappingURL=TransportBridge.d.ts.map

package/dist/transports/TransportBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransportBridge.d.ts","sourceRoot":"","sources":["../../src/transports/TransportBridge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,OAAO,EAAE,gBAAgB,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,2CAA2C;IAC3C,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAAC;IAC9C,kEAAkE;IAClE,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,0DAA0D;IAC1D,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,qDAAqD;IACrD,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,sEAAsE;IACtE,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAAC;IACpD,+FAA+F;IAC/F,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CACvE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CAiCvD"}

package/dist/transports/TransportManager.d.ts

@@ -0,0 +1,251 @@
+import type { TransportRecord, TransportTarget, TransportOptions, ITransport, ITransportManager, LogLevel } from '../types/index.js';
+/**
+ * Firma del constructor de los transports registrados en el registry
+ * built-in. Acepta el tipo propio de options del transport; el pass-through
+ * se enforcea en registro vía TypeScript pero se borra en runtime.
+ */
+export type TransportConstructor = new (options?: TransportOptions) => ITransport;
+/**
+ * Registry y dispatcher de transports. Mantiene el set activo de destinos
+ * de log (console, file, http, otlp, o transports custom registrados vía
+ * {@link TransportManager.register}) y les dispatcha cada
+ * {@link TransportRecord} producido por el Logger.
+ *
+ * Cada transport added se identifica por un `id` opaco (generado por la
+ * propia instancia) que devuelven {@link add} y {@link list}, y que acepta
+ * {@link remove}. El registry arranca con los cuatro built-ins
+ * (`console` / `file` / `http` / `otlp`) ya cargados; {@link register}
+ * añade customs sin poder sobreescribir los built-ins (lanza).
+ *
+ * El dispatch ({@link write}) aplica el filtro de `level` por transport y
+ * el `transform` opcional de {@link TransportOptions}, y captura toda
+ * excepción / rechazo de cada transport para que un transport roto nunca
+ * rompa el log call del caller. El propio Logger habla con el manager a
+ * través del facade {@link TransportBridge} (ver
+ * `Logger.addTransport` / `Logger.getTransportManager`).
+ *
+ * Implementa {@link ITransportManager}.
+ *
+ * @example
+ * // Manager con nivel default y transports añadidos por nombre
+ * const tm = new TransportManager('info');
+ * tm.add({ target: 'console' });
+ * tm.add({ target: 'file', options: { path: './app.log' } });
+ *
+ * @example
+ * // Registrar un transport custom y usarlo por nombre
+ * tm.register('datadog', DatadogTransport);
+ * tm.add({ target: 'datadog', options: { apiKey: env('DD_KEY') } });
+ *
+ * @example
+ * // Pasar una instancia de ITransport directamente (sin pasar por registry)
+ * tm.add({ target: new MyTransport(), level: 'warn' });
+ *
+ * @example
+ * // Dispatch + ciclo de vida
+ * await tm.write(record);
+ * await tm.flush();   // flusha todos los buffered
+ * await tm.close();   // flush + close + clear
+ *
+ * @see {@link ITransportManager}
+ * @see {@link TransportTarget}
+ * @see {@link TransportBridge}
+ */
+export declare class TransportManager implements ITransportManager {
+    private transports;
+    private defaultLevel;
+    private readonly registry;
+    /**
+     * Crea un nuevo manager.
+     *
+     * @param {LogLevel} [defaultLevel='info'] - Nivel mínimo por defecto
+     *   para transports añadidos sin `level` explícito en su
+     *   {@link TransportTarget}. Records con `levelValue` inferior al del
+     *   transport se descartan en {@link write}.
+     *
+     * @example
+     * const tm = new TransportManager('debug'); // todo pasa salvo filter propio
+     */
+    constructor(defaultLevel?: LogLevel);
+    /**
+     * Registra un constructor de transport bajo un nombre string. Tras el
+     * registro, `add({ target: name, options })` instancia ese transport con
+     * las options pasadas.
+     *
+     * No se puede sobreescribir un built-in (`console` / `file` / `http` /
+     * `otlp`): lanza para evitar silenciar un transport crítico por un
+     * accidente de naming. El registro es por-instancia (no comparte entre
+     * managers).
+     *
+     * @param {string} name - Nombre bajo el que registrar (usado luego como
+     *   `target` en {@link TransportTarget}).
+     * @param {TransportConstructor} ctor - Constructor que acepta
+     *   {@link TransportOptions} y devuelve un {@link ITransport}.
+     * @throws {Error} Si `name` colisiona con un built-in del registry.
+     *
+     * @example
+     * tm.register('datadog', DatadogTransport);
+     * tm.add({ target: 'datadog', options: { apiKey: env('DD_KEY') } });
+     *
+     * @see {@link listRegistered}
+     */
+    register(name: string, ctor: TransportConstructor): void;
+    /**
+     * Lista los nombres de transports registrados en esta instancia
+     * (built-ins + customs añadidos vía {@link register}).
+     *
+     * @returns {string[]} Nombres registrados. Incluye siempre los cuatro
+     *   built-ins.
+     *
+     * @example
+     * tm.register('loki', LokiTransport);
+     * tm.listRegistered(); // ['console', 'file', 'http', 'otlp', 'loki']
+     */
+    listRegistered(): string[];
+    /**
+     * Añade un transport al set activo y devuelve su id opaco.
+     *
+     * Acepta dos formas de `target`:
+     *   - **string**: se resuelve contra el registry (built-ins + customs
+     *     vía {@link register}). Lanza si el nombre no existe, listando los
+     *     registrados para facilitar el debug.
+     *   - **ITransport instancia**: se registra tal cual, sin pasar por el
+     *     registry. Útil para transports one-off o cuya configuración no
+     *     encaja en un constructor reutilizable.
+     *
+     * El `level` (explícito en el target o `defaultLevel` del manager) fija
+     * el filtro por transport — los records con `levelValue` inferior se
+     * descartan en {@link write}. El `transform` opcional de
+     * {@link TransportOptions} se aplica por transport antes de delegar al
+     * `write` concreto.
+     *
+     * @param {TransportTarget} target - Especificación del transport a añadir.
+     * @returns {string} Id opaco del transport añadido. Úsalo con
+     *   {@link remove}; aparece en {@link list}.
+     * @throws {Error} Si `target.target` es un string no presente en el
+     *   registry.
+     *
+     * @example
+     * // Por nombre (built-in o custom registrado)
+     * const id = tm.add({ target: 'console' });
+     *
+     * @example
+     * // Instancia directa con nivel y transform propios
+     * const id = tm.add({
+     *   target: new MyTransport(),
+     *   level: 'warn',
+     *   options: { transform: r => r.level === 'debug' ? null : r }
+     * });
+     *
+     * @see {@link TransportTarget}
+     */
+    add(target: TransportTarget): string;
+    /**
+     * Elimina un transport del set por su id. Si el transport expone
+     * `close()`, lo invoca para liberar recursos (timers, sockets, file
+     * handles). Si `close()` devuelve una Promise, su eventual rechazo se
+     * ignora de forma best-effort — los errores de close durante la
+     * remoción no se propagan al caller.
+     *
+     * @param {string} id - Id devuelto por {@link add}.
+     * @returns {boolean} `true` si había un transport con ese id (y se
+     *   eliminó), `false` si el id no existía.
+     *
+     * @example
+     * const id = tm.add({ target: 'file', options: { path: './app.log' } });
+     * tm.remove(id); // true — FileTransport.close() se invoca
+     */
+    remove(id: string): boolean;
+    /**
+     * Dispatcha un {@link TransportRecord} a todos los transports activos
+     * que pasen el filtro de nivel.
+     *
+     * Por cada transport, en orden:
+     *   1. **Filtro de nivel**: si `record.levelValue < entry.levelValue`,
+     *      se skipa (ese transport no recibe este record).
+     *   2. **Transform**: si `entry.options.transform` está seteado, se
+     *      aplica al record. Si devuelve `null`, el record se droppea para
+     *      este transport (no para los demás).
+     *   3. **Write**: se llama a `transport.write(transformedRecord)`. Si
+     *      devuelve una Promise, se añade al batch await. Toda excepción
+     *      sincrónica o rechazo de Promise se captura y se loguea por
+     *      consola — el log call original del caller nunca rompe por un
+     *      transport roto.
+     *
+     * El método es async: retorna después de que todos los transports hayan
+     * resuelto (o fallado) su write. Para fire-and-forget desde el Logger,
+     * el caller puede ignorar la Promise.
+     *
+     * @param {TransportRecord} record - Record a dispatchar.
+     * @returns {Promise<void>} Resuelve cuando todos los writes terminaron
+     *   (exitosos o fallidos). Nunca rechaza.
+     *
+     * @example
+     * await tm.write({
+     *   level: 'info', levelValue: 1, severityNumber: 9, severityText: 'INFO',
+     *   time: Date.now(), msg: 'boot ok'
+     * });
+     *
+     * @see {@link TransportRecord}
+     */
+    write(record: TransportRecord): Promise<void>;
+    /**
+     * Flushea todos los transports que expongan `flush()` (buffered transports
+     * como {@link HttpTransport}, {@link FileTransport}, {@link OtlpTransport}).
+     * Los transports sin `flush()` (p.ej. {@link ConsoleTransport}) se
+     * skipan sin error.
+     *
+     * Errores de flush (sync throw o Promise rejection) se capturan y
+     * loguean por consola — nunca propagan al caller. Útil para forzar el
+     * envío del batch pendiente antes de un graceful shutdown.
+     *
+     * @returns {Promise<void>} Resuelve cuando todos los flushes terminaron.
+     *
+     * @example
+     * await tm.flush();
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown ordenado: flushea todos los transports buffered, luego
+     * invoca `close()` en cada uno, y finalmente limpia el set interno.
+     * Tras esto la instancia queda sin transports — reusarla requiere
+     * `add()` de nuevo.
+     *
+     * Los errores de close (sync throw o Promise rejection) se capturan y
+     * loguean — nunca propagan al caller.
+     *
+     * @returns {Promise<void>} Resuelve cuando flush + close de todos los
+     *   transports terminaron.
+     *
+     * @example
+     * // Shutdown limpio del proceso
+     * process.on('SIGTERM', async () => {
+     *   await logger.getTransportManager()?.close();
+     *   process.exit(0);
+     * });
+     */
+    close(): Promise<void>;
+    /**
+     * Número de transports actualmente en el set activo.
+     *
+     * @returns {number}
+     *
+     * @example
+     * if (tm.count === 0) console.warn('no transports configured');
+     */
+    get count(): number;
+    /**
+     * Lista los ids opacos de los transports actualmente activos.
+     *
+     * @returns {string[]} Array de ids (mismo formato opaco que devolvió
+     *   {@link add}).
+     *
+     * @example
+     * for (const id of tm.list()) {
+     *   console.log('removing transport', id);
+     *   tm.remove(id);
+     * }
+     */
+    list(): string[];
+}
+//# sourceMappingURL=TransportManager.d.ts.map

package/dist/transports/TransportManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransportManager.d.ts","sourceRoot":"","sources":["../../src/transports/TransportManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACX,MAAM,mBAAmB,CAAC;AAmB3B;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,OAAO,CAAC,EAAE,gBAAgB,KAAK,UAAU,CAAC;AAuClF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACtD,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgE;IAEzF;;;;;;;;;;OAUG;gBACS,YAAY,CAAC,EAAE,QAAQ;IAMnC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAOxD;;;;;;;;;;OAUG;IACH,cAAc,IAAI,MAAM,EAAE;IAI1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM;IA+BpC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAc3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCnD;;;;;;;;;;;;;;OAcG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB5B;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B5B;;;;;;;OAOG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,MAAM,EAAE;CAGnB"}

package/dist/transports/index.d.ts

@@ -0,0 +1,6 @@
+export { TransportManager } from './TransportManager.js';
+export { ConsoleTransport } from './ConsoleTransport.js';
+export { FileTransport, type FileTransportOptions } from './FileTransport.js';
+export { HttpTransport, type HttpTransportOptions } from './HttpTransport.js';
+export { OtlpTransport, type OtlpTransportOptions } from './OtlpTransport.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/transports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transports/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}