@bufferlog/sdk-node 1.0.0

package/dist/control-plane/policy-fetcher.js

@@ -0,0 +1,116 @@
+/**
+ * Policy Fetcher — Periodically polls the BufferLog Control Plane
+ * for dynamic configuration updates.
+ *
+ * The SDK calls GET /api/v1/policy every `intervalMs` (default 60s).
+ * If the server returns updated policies, the fetcher invokes the
+ * `onUpdate` callback so the BufferLog instance can apply changes
+ * without requiring a redeploy.
+ *
+ * Design notes:
+ * - Fail-safe: if the control plane is unreachable, the SDK continues
+ *   operating with its last known config. No logs are lost.
+ * - Uses AbortController for clean shutdown.
+ * - Sends SDK version and runtime info in headers for server-side analytics.
+ */
+export class PolicyFetcher {
+    url;
+    apiKey;
+    intervalMs;
+    onUpdate;
+    onError;
+    timer = null;
+    abortController = null;
+    _lastPolicy = null;
+    _fetchCount = 0;
+    _errorCount = 0;
+    constructor(options) {
+        const base = options.controlPlaneUrl.replace(/\/+$/, '');
+        this.url = `${base}/api/v1/policy`;
+        this.apiKey = options.apiKey;
+        this.intervalMs = options.intervalMs ?? 60_000;
+        this.onUpdate = options.onUpdate;
+        this.onError = options.onError;
+    }
+    /**
+     * Start polling. Fetches immediately, then every `intervalMs`.
+     */
+    start() {
+        if (this.timer)
+            return; // Already running
+        // Fetch immediately on start
+        this.fetch();
+        this.timer = setInterval(() => this.fetch(), this.intervalMs);
+        // Ensure the timer doesn't prevent process exit
+        if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+            this.timer.unref();
+        }
+    }
+    /**
+     * Stop polling and cancel any in-flight request.
+     */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+        }
+    }
+    /**
+     * Perform a single fetch. Can be called manually to force a refresh.
+     */
+    async fetch() {
+        this.abortController = new AbortController();
+        const timeout = setTimeout(() => this.abortController?.abort(), 10_000);
+        try {
+            const response = await fetch(this.url, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'User-Agent': `bufferlog-sdk-node/0.1.0 (node/${process.version})`,
+                },
+                signal: this.abortController.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Policy fetch returned ${response.status}`);
+            }
+            const policy = (await response.json());
+            this._fetchCount++;
+            this._lastPolicy = policy;
+            this.onUpdate?.(policy);
+            return policy;
+        }
+        catch (err) {
+            this._errorCount++;
+            const error = err instanceof Error ? err : new Error(String(err));
+            // Don't report abort errors (expected during shutdown)
+            if (error.name !== 'AbortError') {
+                this.onError?.(error);
+            }
+            return null;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /** Last successfully fetched policy */
+    get lastPolicy() {
+        return this._lastPolicy;
+    }
+    /** Total successful fetches */
+    get fetchCount() {
+        return this._fetchCount;
+    }
+    /** Total fetch errors */
+    get errorCount() {
+        return this._errorCount;
+    }
+    /** Whether the fetcher is currently running */
+    get isRunning() {
+        return this.timer !== null;
+    }
+}
+//# sourceMappingURL=policy-fetcher.js.map

package/dist/control-plane/policy-fetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-fetcher.js","sourceRoot":"","sources":["../../src/control-plane/policy-fetcher.ts"],"names":[],"mappings":"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"}

package/dist/control-plane/telemetry-reporter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Telemetry Reporter — Periodically pushes SDK metrics to the
+ * BufferLog Control Plane.
+ *
+ * The SDK calls POST /api/v1/telemetry every `intervalMs` (default 60s)
+ * with counters only — never actual log data.
+ *
+ * Metrics sent:
+ * - logs_discarded: total log lines discarded (success path)
+ * - logs_flushed: total log lines shipped to APMs (error path)
+ * - requests_success: successful requests processed
+ * - requests_error: error requests processed
+ * - buffers_active: currently in-flight request buffers
+ *
+ * Design notes:
+ * - Fire-and-forget: telemetry failures are silently ignored.
+ * - Uses AbortController for clean shutdown.
+ * - Timer is unref'd so it doesn't prevent process exit.
+ */
+import type { BufferManagerMetrics } from '../core/buffer-manager.js';
+export interface TelemetryReporterOptions {
+    /** Control plane base URL */
+    controlPlaneUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Reporting interval in milliseconds. @default 60000 */
+    intervalMs?: number;
+    /** Function that returns the current metrics snapshot */
+    metricsProvider: () => {
+        buffers: BufferManagerMetrics;
+        flash: {
+            flushCount: number;
+            eventsFlushed: number;
+            adapterErrors: number;
+        };
+    };
+    /** Callback invoked on send errors (optional, for debugging) */
+    onError?: (error: Error) => void;
+}
+export declare class TelemetryReporter {
+    private readonly url;
+    private readonly apiKey;
+    private readonly intervalMs;
+    private readonly metricsProvider;
+    private readonly onError?;
+    private timer;
+    private _sendCount;
+    private _errorCount;
+    private prevDiscarded;
+    private prevFlushed;
+    private prevSuccess;
+    private prevError;
+    constructor(options: TelemetryReporterOptions);
+    /**
+     * Start reporting. Sends the first report after one interval.
+     */
+    start(): void;
+    /**
+     * Stop reporting.
+     */
+    stop(): void;
+    /**
+     * Send a single telemetry snapshot. Can be called manually (e.g. on shutdown).
+     */
+    send(): Promise<boolean>;
+    /** Total successful sends */
+    get sendCount(): number;
+    /** Total send errors */
+    get errorCount(): number;
+    /** Whether the reporter is currently running */
+    get isRunning(): boolean;
+}
+//# sourceMappingURL=telemetry-reporter.d.ts.map

package/dist/control-plane/telemetry-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-reporter.d.ts","sourceRoot":"","sources":["../../src/control-plane/telemetry-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,MAAM,WAAW,wBAAwB;IACvC,6BAA6B;IAC7B,eAAe,EAAE,MAAM,CAAC;IAExB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IAEf,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,yDAAyD;IACzD,eAAe,EAAE,MAAM;QACrB,OAAO,EAAE,oBAAoB,CAAC;QAC9B,KAAK,EAAE;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,aAAa,EAAE,MAAM,CAAC;YAAC,aAAa,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7E,CAAC;IAEF,gEAAgE;IAChE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8C;IAC9E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAyB;IAElD,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,WAAW,CAAK;IAGxB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,SAAS,CAAK;gBAEV,OAAO,EAAE,wBAAwB;IAS7C;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;OAEG;IACH,IAAI,IAAI,IAAI;IAOZ;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IA6D9B,6BAA6B;IAC7B,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wBAAwB;IACxB,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,gDAAgD;IAChD,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF"}

package/dist/control-plane/telemetry-reporter.js

@@ -0,0 +1,133 @@
+/**
+ * Telemetry Reporter — Periodically pushes SDK metrics to the
+ * BufferLog Control Plane.
+ *
+ * The SDK calls POST /api/v1/telemetry every `intervalMs` (default 60s)
+ * with counters only — never actual log data.
+ *
+ * Metrics sent:
+ * - logs_discarded: total log lines discarded (success path)
+ * - logs_flushed: total log lines shipped to APMs (error path)
+ * - requests_success: successful requests processed
+ * - requests_error: error requests processed
+ * - buffers_active: currently in-flight request buffers
+ *
+ * Design notes:
+ * - Fire-and-forget: telemetry failures are silently ignored.
+ * - Uses AbortController for clean shutdown.
+ * - Timer is unref'd so it doesn't prevent process exit.
+ */
+export class TelemetryReporter {
+    url;
+    apiKey;
+    intervalMs;
+    metricsProvider;
+    onError;
+    timer = null;
+    _sendCount = 0;
+    _errorCount = 0;
+    // Track previous metrics to send deltas
+    prevDiscarded = 0;
+    prevFlushed = 0;
+    prevSuccess = 0;
+    prevError = 0;
+    constructor(options) {
+        const base = options.controlPlaneUrl.replace(/\/+$/, '');
+        this.url = `${base}/api/v1/telemetry`;
+        this.apiKey = options.apiKey;
+        this.intervalMs = options.intervalMs ?? 60_000;
+        this.metricsProvider = options.metricsProvider;
+        this.onError = options.onError;
+    }
+    /**
+     * Start reporting. Sends the first report after one interval.
+     */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.send(), this.intervalMs);
+        if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+            this.timer.unref();
+        }
+    }
+    /**
+     * Stop reporting.
+     */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Send a single telemetry snapshot. Can be called manually (e.g. on shutdown).
+     */
+    async send() {
+        try {
+            const metrics = this.metricsProvider();
+            // Calculate deltas since last send
+            const currentDiscarded = metrics.flash.eventsFlushed; // flushed events
+            const bufMetrics = metrics.buffers;
+            const payload = {
+                sdkVersion: '0.1.0',
+                runtime: 'node',
+                runtimeVersion: process.version.replace('v', ''),
+                metrics: {
+                    logs_discarded: bufMetrics.discarded - this.prevDiscarded + this.prevDiscarded,
+                    logs_flushed: metrics.flash.eventsFlushed,
+                    requests_success: bufMetrics.discarded,
+                    requests_error: bufMetrics.flushed,
+                    buffers_active: bufMetrics.active,
+                },
+            };
+            // Update prev counters
+            this.prevDiscarded = bufMetrics.discarded;
+            this.prevFlushed = metrics.flash.eventsFlushed;
+            this.prevSuccess = bufMetrics.discarded;
+            this.prevError = bufMetrics.flushed;
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 10_000);
+            try {
+                const response = await fetch(this.url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${this.apiKey}`,
+                        'User-Agent': `bufferlog-sdk-node/0.1.0 (node/${process.version})`,
+                    },
+                    body: JSON.stringify(payload),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    throw new Error(`Telemetry push returned ${response.status}`);
+                }
+                this._sendCount++;
+                return true;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch (err) {
+            this._errorCount++;
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (error.name !== 'AbortError') {
+                this.onError?.(error);
+            }
+            return false;
+        }
+    }
+    /** Total successful sends */
+    get sendCount() {
+        return this._sendCount;
+    }
+    /** Total send errors */
+    get errorCount() {
+        return this._errorCount;
+    }
+    /** Whether the reporter is currently running */
+    get isRunning() {
+        return this.timer !== null;
+    }
+}
+//# sourceMappingURL=telemetry-reporter.js.map

package/dist/control-plane/telemetry-reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-reporter.js","sourceRoot":"","sources":["../../src/control-plane/telemetry-reporter.ts"],"names":[],"mappings":"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"}

package/dist/core/buffer-manager.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Buffer Manager — Lifecycle manager for per-request ring buffers.
+ *
+ * Responsibilities:
+ * - Create a new ring buffer when a request starts
+ * - Retrieve the buffer for a given context ID
+ * - Discard (GC) the buffer on success (HTTP 2xx)
+ * - Flush (drain) the buffer on error (HTTP 5xx or log.error())
+ *
+ * Design notes:
+ * - Uses a Map<string, RingBuffer<LogEvent>> for O(1) lookups
+ * - Fail-open: if contextId is missing, operations return gracefully
+ * - Tracks metrics (created, discarded, flushed) for the ROI dashboard
+ */
+import { RingBuffer } from './ring-buffer.js';
+import type { LogEvent } from './log-event.js';
+export interface BufferManagerMetrics {
+    /** Total buffers created */
+    created: number;
+    /** Total buffers discarded (success path) */
+    discarded: number;
+    /** Total buffers flushed (error path) */
+    flushed: number;
+    /** Currently active buffers */
+    active: number;
+}
+export declare class BufferManager {
+    private readonly defaultCapacity;
+    private readonly buffers;
+    private readonly metrics;
+    /**
+     * @param defaultCapacity Default ring buffer capacity for new buffers
+     */
+    constructor(defaultCapacity?: number);
+    /**
+     * Create a new ring buffer for a request context.
+     *
+     * @param contextId Unique identifier for the request
+     * @param capacity Optional override for buffer capacity
+     * @returns The newly created ring buffer
+     */
+    createBuffer(contextId: string, capacity?: number): RingBuffer<LogEvent>;
+    /**
+     * Retrieve the ring buffer for a given context ID.
+     * Returns undefined if no buffer exists (e.g., outside request scope).
+     */
+    getBuffer(contextId: string): RingBuffer<LogEvent> | undefined;
+    /**
+     * Check if a buffer exists for the given context ID.
+     */
+    hasBuffer(contextId: string): boolean;
+    /**
+     * Discard a buffer — the SUCCESS path.
+     * The buffer is removed from the map and becomes eligible for GC.
+     * No logs are emitted. This is the money-saving operation.
+     *
+     * @param contextId The request context to discard
+     * @returns true if a buffer was found and discarded, false if not found
+     */
+    discardBuffer(contextId: string): boolean;
+    /**
+     * Flush a buffer — the ERROR path.
+     * Drains all buffered log events and removes the buffer from the map.
+     *
+     * @param contextId The request context to flush
+     * @returns Array of log events in chronological order, or empty array if not found
+     */
+    flushBuffer(contextId: string): LogEvent[];
+    /**
+     * Get a snapshot of current metrics.
+     * Used by the ROI dashboard and telemetry.
+     */
+    getMetrics(): Readonly<BufferManagerMetrics>;
+    /**
+     * Reset all metrics counters. Useful for testing.
+     */
+    resetMetrics(): void;
+    /**
+     * Get the number of currently active buffers.
+     */
+    get activeCount(): number;
+}
+//# sourceMappingURL=buffer-manager.d.ts.map

package/dist/core/buffer-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-manager.d.ts","sourceRoot":"","sources":["../../src/core/buffer-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,aAAa;IAYZ,OAAO,CAAC,QAAQ,CAAC,eAAe;IAX5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAKtB;IAEF;;OAEG;gBAC0B,eAAe,GAAE,MAAY;IAE1D;;;;;;OAMG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC;IAQxE;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,SAAS;IAI9D;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;;;OAOG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAczC;;;;;;OAMG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE;IAa1C;;;OAGG;IACH,UAAU,IAAI,QAAQ,CAAC,oBAAoB,CAAC;IAI5C;;OAEG;IACH,YAAY,IAAI,IAAI;IAOpB;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}

package/dist/core/buffer-manager.js

@@ -0,0 +1,119 @@
+/**
+ * Buffer Manager — Lifecycle manager for per-request ring buffers.
+ *
+ * Responsibilities:
+ * - Create a new ring buffer when a request starts
+ * - Retrieve the buffer for a given context ID
+ * - Discard (GC) the buffer on success (HTTP 2xx)
+ * - Flush (drain) the buffer on error (HTTP 5xx or log.error())
+ *
+ * Design notes:
+ * - Uses a Map<string, RingBuffer<LogEvent>> for O(1) lookups
+ * - Fail-open: if contextId is missing, operations return gracefully
+ * - Tracks metrics (created, discarded, flushed) for the ROI dashboard
+ */
+import { RingBuffer } from './ring-buffer.js';
+export class BufferManager {
+    defaultCapacity;
+    buffers = new Map();
+    metrics = {
+        created: 0,
+        discarded: 0,
+        flushed: 0,
+        active: 0,
+    };
+    /**
+     * @param defaultCapacity Default ring buffer capacity for new buffers
+     */
+    constructor(defaultCapacity = 100) {
+        this.defaultCapacity = defaultCapacity;
+    }
+    /**
+     * Create a new ring buffer for a request context.
+     *
+     * @param contextId Unique identifier for the request
+     * @param capacity Optional override for buffer capacity
+     * @returns The newly created ring buffer
+     */
+    createBuffer(contextId, capacity) {
+        const buffer = new RingBuffer(capacity ?? this.defaultCapacity);
+        this.buffers.set(contextId, buffer);
+        this.metrics.created++;
+        this.metrics.active++;
+        return buffer;
+    }
+    /**
+     * Retrieve the ring buffer for a given context ID.
+     * Returns undefined if no buffer exists (e.g., outside request scope).
+     */
+    getBuffer(contextId) {
+        return this.buffers.get(contextId);
+    }
+    /**
+     * Check if a buffer exists for the given context ID.
+     */
+    hasBuffer(contextId) {
+        return this.buffers.has(contextId);
+    }
+    /**
+     * Discard a buffer — the SUCCESS path.
+     * The buffer is removed from the map and becomes eligible for GC.
+     * No logs are emitted. This is the money-saving operation.
+     *
+     * @param contextId The request context to discard
+     * @returns true if a buffer was found and discarded, false if not found
+     */
+    discardBuffer(contextId) {
+        const buffer = this.buffers.get(contextId);
+        if (!buffer) {
+            return false;
+        }
+        // Clear references to allow GC of log events
+        buffer.clearFull();
+        this.buffers.delete(contextId);
+        this.metrics.discarded++;
+        this.metrics.active--;
+        return true;
+    }
+    /**
+     * Flush a buffer — the ERROR path.
+     * Drains all buffered log events and removes the buffer from the map.
+     *
+     * @param contextId The request context to flush
+     * @returns Array of log events in chronological order, or empty array if not found
+     */
+    flushBuffer(contextId) {
+        const buffer = this.buffers.get(contextId);
+        if (!buffer) {
+            return [];
+        }
+        const events = buffer.drain();
+        this.buffers.delete(contextId);
+        this.metrics.flushed++;
+        this.metrics.active--;
+        return events;
+    }
+    /**
+     * Get a snapshot of current metrics.
+     * Used by the ROI dashboard and telemetry.
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Reset all metrics counters. Useful for testing.
+     */
+    resetMetrics() {
+        this.metrics.created = 0;
+        this.metrics.discarded = 0;
+        this.metrics.flushed = 0;
+        this.metrics.active = this.buffers.size;
+    }
+    /**
+     * Get the number of currently active buffers.
+     */
+    get activeCount() {
+        return this.buffers.size;
+    }
+}
+//# sourceMappingURL=buffer-manager.js.map

package/dist/core/buffer-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-manager.js","sourceRoot":"","sources":["../../src/core/buffer-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAc9C,MAAM,OAAO,aAAa;IAYK;IAXZ,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IAClD,OAAO,GAAyB;QAC/C,OAAO,EAAE,CAAC;QACV,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,CAAC;KACV,CAAC;IAEF;;OAEG;IACH,YAA6B,kBAA0B,GAAG;QAA7B,oBAAe,GAAf,eAAe,CAAc;IAAG,CAAC;IAE9D;;;;;;OAMG;IACH,YAAY,CAAC,SAAiB,EAAE,QAAiB;QAC/C,MAAM,MAAM,GAAG,IAAI,UAAU,CAAW,QAAQ,IAAI,IAAI,CAAC,eAAe,CAAC,CAAC;QAC1E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,SAAiB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,SAAiB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IAED;;;;;;;OAOG;IACH,aAAa,CAAC,SAAiB;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,KAAK,CAAC;QACf,CAAC;QAED,6CAA6C;QAC7C,MAAM,CAAC,SAAS,EAAE,CAAC;QACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAC,SAAiB;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;QAC9B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC/B,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,YAAY;QACV,IAAI,CAAC,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/dist/core/log-event.d.ts

@@ -0,0 +1,72 @@
+/**
+ * BufferLog Log Event Schema
+ *
+ * Lightweight internal representation of a log event.
+ * Designed for minimal allocation in the hot path:
+ * - Numeric timestamp (not ISO string)
+ * - Numeric enum for level (fast comparison)
+ * - Optional metadata to avoid empty object allocation
+ */
+/**
+ * Log severity levels as numeric enum for fast comparison.
+ * Usage: `if (event.level >= LogLevel.ERROR)` triggers a flush.
+ */
+export declare enum LogLevel {
+    TRACE = 0,
+    DEBUG = 10,
+    INFO = 20,
+    WARN = 30,
+    ERROR = 40,
+    FATAL = 50
+}
+/**
+ * Human-readable label map for serialization.
+ */
+export declare const LOG_LEVEL_LABELS: Record<LogLevel, string>;
+/**
+ * Reverse lookup: string label → LogLevel.
+ * Used when parsing levels from external logging libraries (e.g., Winston's 'info' → LogLevel.INFO).
+ */
+export declare const LOG_LEVEL_FROM_STRING: Record<string, LogLevel>;
+/**
+ * Internal log event — the unit stored in ring buffers.
+ *
+ * Design notes:
+ * - `timestamp` is `Date.now()` (ms since epoch) to avoid string allocation
+ * - `metadata` is optional; only allocate when the caller provides extra fields
+ * - `contextId` links this event to its owning request buffer
+ */
+export interface LogEvent {
+    /** Milliseconds since Unix epoch (Date.now()) */
+    readonly timestamp: number;
+    /** Severity level */
+    readonly level: LogLevel;
+    /** Log message — already formatted by the caller */
+    readonly message: string;
+    /** Optional structured metadata (e.g., userId, traceId, query params) */
+    readonly metadata?: Record<string, unknown>;
+    /** ID of the request context that owns this event */
+    readonly contextId: string;
+}
+/**
+ * Serialized form for downstream adapters (Datadog, Splunk, stdout).
+ */
+export interface SerializedLogEvent {
+    timestamp: string;
+    level: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+    contextId: string;
+    source: 'bufferlog';
+}
+/**
+ * Convert an internal LogEvent to its serialized downstream format.
+ * Called only on the flush path (not hot path), so string allocation is acceptable.
+ */
+export declare function serializeLogEvent(event: LogEvent): SerializedLogEvent;
+/**
+ * Factory for creating LogEvents with minimal ceremony.
+ * Captures timestamp at call time.
+ */
+export declare function createLogEvent(level: LogLevel, message: string, contextId: string, metadata?: Record<string, unknown>): LogEvent;
+//# sourceMappingURL=log-event.d.ts.map

package/dist/core/log-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-event.d.ts","sourceRoot":"","sources":["../../src/core/log-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,oBAAY,QAAQ;IAClB,KAAK,IAAI;IACT,KAAK,KAAK;IACV,IAAI,KAAK;IACT,IAAI,KAAK;IACT,KAAK,KAAK;IACV,KAAK,KAAK;CACX;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAOrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAY1D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,qBAAqB;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAEzB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5C,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,kBAAkB,CASrE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,QAAQ,CAQV"}