@bufferlog/sdk-node 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BufferLog.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# @bufferlog/sdk-node
+
+> **Buffer logs in memory. Flush only on errors. Save 90%+ on APM costs.**
+
+`@bufferlog/sdk-node` is a lightweight SDK that wraps your existing logging library (Winston, Pino) and buffers all debug/info logs in memory per-request. If the request succeeds, the logs are safely discarded. If an error occurs (such as an HTTP 5xx or `logger.error`), the preceding log context is automatically flushed to your APM (Datadog, Splunk, etc.), giving you complete visibility without the cost of storing successful request logs.
+
+---
+
+## Installation
+
+```bash
+npm install @bufferlog/sdk-node
+```
+
+---
+
+## Quick Start
+
+### 1. Express + Winston Setup
+
+```typescript
+import express from 'express';
+import winston from 'winston';
+import { BufferLog, StdOutAdapter, DatadogAdapter } from '@bufferlog/sdk-node';
+
+// 1. Create a BufferLog instance
+const bufferlog = BufferLog.create({
+  bufferCapacity: 100,
+  adapters: [
+    new DatadogAdapter({ apiKey: process.env.DD_API_KEY! }),
+    new StdOutAdapter({ pretty: true })
+  ],
+});
+
+// 2. Create a Winston logger with the BufferLog transport
+const logger = winston.createLogger({
+  level: 'debug',
+  transports: [bufferlog.winstonTransport()],
+});
+
+// 3. Apply the Express middleware
+const app = express();
+app.use(bufferlog.expressMiddleware());
+
+// 4. Log normally - BufferLog handles context tracking and routing
+app.get('/api/data', (req, res) => {
+  logger.info('Querying database...');    // Buffered (discarded if HTTP 2xx)
+  logger.debug('SQL: SELECT * FROM ...'); // Buffered (discarded if HTTP 2xx)
+  res.json({ status: 'ok' });             // Success -> logs are discarded ($0 cost)
+});
+
+app.get('/api/fail', (req, res) => {
+  logger.info('Starting transaction...');  // Buffered
+  logger.error('Database connection lost'); // Triggers Flush! Context + error is sent to APM
+  res.status(500).json({ error: true });
+});
+```
+
+### 2. Fastify + Pino Setup
+
+```typescript
+import Fastify from 'fastify';
+import pino from 'pino';
+import { BufferLog, StdOutAdapter } from '@bufferlog/sdk-node';
+
+// 1. Create a BufferLog instance
+const bufferlog = BufferLog.create({
+  bufferCapacity: 100,
+  adapters: [new StdOutAdapter({ pretty: true })],
+});
+
+// 2. Wrap Pino logger with BufferLog destination
+const logger = pino(
+  { level: 'debug' },
+  bufferlog.pinoDestination()
+);
+
+const fastify = Fastify();
+
+// 3. Register Fastify plugin and pass the required options
+fastify.register(bufferlog.fastifyPlugin(), bufferlog.fastifyPluginOptions());
+
+fastify.get('/api/data', async (request, reply) => {
+  logger.info('Handling fastify request');
+  return { ok: true };
+});
+```
+
+---
+
+## Configuration Options
+
+Pass configuration options when calling `BufferLog.create(...)`:
+
+```typescript
+BufferLog.create({
+  // Max logs to retain in memory per request. Oldest are overwritten when full.
+  bufferCapacity: 100,
+
+  // Log levels that immediately trigger a flush to APM.
+  // Defaults to: ['error', 'fatal', 'crit', 'emerg']
+  flushOnLevels: ['error', 'fatal'],
+
+  // HTTP response status codes that trigger a flush.
+  // Defaults to: [500, 501, 502, 503, 504]
+  flushOnStatusCodes: [500, 502, 503, 504],
+
+  // Downstream targets where flushed logs are shipped.
+  adapters: [
+    new DatadogAdapter({ apiKey: process.env.DD_API_KEY! }),
+    new SplunkAdapter({ token: process.env.SPLUNK_TOKEN!, url: process.env.SPLUNK_URL! }),
+    new StdOutAdapter()
+  ],
+
+  // Globally enable or disable buffering behavior.
+  enabled: true,
+
+  // If true, logs are sent directly to stdout/stderr if downstream APM adapters fail.
+  failOpen: true,
+
+  // Scrub sensitive PII data before logs enter the memory buffer.
+  scrubber: (msg, metadata) => {
+    return {
+      message: msg.replace(/password=\S+/g, 'password=***'),
+      metadata,
+    };
+  }
+});
+```
+
+---
+
+## Local Metrics & ROI Tracking
+
+You can inspect the effectiveness and cost savings of BufferLog dynamically:
+
+```typescript
+const metrics = bufferlog.getMetrics();
+console.log(metrics);
+/*
+Output:
+{
+  buffers: {
+    created: 1000,     // Total requests processed
+    discarded: 995,    // Requests where logs were successfully discarded
+    active: 0          // Active requests currently in flight
+  },
+  flash: {
+    flushCount: 5,     // Total flushes triggered
+    eventsFlushed: 45, // Total log lines shipped to APMs
+    adapterErrors: 0   // Connection/adapter errors
+  }
+}
+*/
+```
+In this scenario, **99.5% of logs were safely discarded**, resulting in massive ingest savings!
+
+---
+
+## Control Plane Integration
+
+Connect the SDK to the BufferLog Control Plane for remote policy management and usage tracking. Policies can be changed from the dashboard without redeploying your application.
+
+```typescript
+const bufferlog = BufferLog.create({
+  adapters: [new DatadogAdapter({ apiKey: process.env.DD_API_KEY! })],
+  controlPlane: {
+    url: 'https://control.bufferlog.io',  // or http://localhost:3001 for local dev
+    apiKey: process.env.BUFFERLOG_API_KEY!,
+    pollIntervalMs: 60_000,      // How often to fetch policy updates (default: 60s)
+    telemetryIntervalMs: 60_000, // How often to push metrics (default: 60s)
+  },
+});
+```
+
+When connected, the SDK will:
+- **Poll for policy updates** — buffer capacity, sampling rate, flush triggers, and bypass rules can all be changed remotely.
+- **Push usage metrics** — counters (never log data) are sent to power the ROI dashboard.
+
+If the control plane is unreachable, the SDK continues operating with its last known configuration.
+
+---
+
+## Graceful Shutdown
+
+When your application is shutting down, call `shutdown()` to stop background timers and send a final telemetry report:
+
+```typescript
+process.on('SIGTERM', async () => {
+  await bufferlog.shutdown();
+  process.exit(0);
+});
+```
+

package/dist/config.d.ts

@@ -0,0 +1,97 @@
+/**
+ * SDK Configuration — Defines all tunable parameters for BufferLog.
+ *
+ * Design notes:
+ * - All fields are optional with sensible defaults
+ * - Configuration is frozen after initialization to prevent mutation
+ */
+import type { DownstreamAdapter } from './flash/adapters/types.js';
+/**
+ * User-facing configuration options for the BufferLog SDK.
+ */
+export interface BufferLogConfig {
+    /**
+     * Maximum number of log events per request buffer.
+     * When full, the oldest log is overwritten (ring buffer behavior).
+     * @default 100
+     */
+    bufferCapacity?: number;
+    /**
+     * Log levels that trigger a buffer flush.
+     * By default, ERROR and FATAL trigger a flush.
+     * @default ['error', 'fatal']
+     */
+    flushOnLevels?: string[];
+    /**
+     * HTTP status codes that trigger a buffer flush on response.
+     * @default [500, 501, 502, 503, 504]
+     */
+    flushOnStatusCodes?: number[];
+    /**
+     * Downstream adapters to send flushed logs to.
+     * At least one adapter should be configured; falls back to stdout if empty.
+     */
+    adapters?: DownstreamAdapter[];
+    /**
+     * Enable/disable BufferLog entirely.
+     * When disabled, all logs pass through to the original logger unmodified.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Enable fail-open behavior: if BufferLog encounters an internal error,
+     * forward logs directly to stderr/stdout instead of dropping them.
+     * @default true
+     */
+    failOpen?: boolean;
+    /**
+     * Optional PII scrubbing function applied to each log event before buffering.
+     * Receives the log message and metadata; should return sanitized versions.
+     */
+    scrubber?: (message: string, metadata?: Record<string, unknown>) => {
+        message: string;
+        metadata?: Record<string, unknown>;
+    };
+    /**
+     * Connect to the BufferLog Control Plane for dynamic policy
+     * updates and telemetry reporting.
+     * If not set, the SDK operates in standalone mode with static config.
+     */
+    controlPlane?: {
+        /** Control plane base URL, e.g. "https://control.bufferlog.io" */
+        url: string;
+        /** API key for authentication */
+        apiKey: string;
+        /** Policy polling interval in ms. @default 60000 */
+        pollIntervalMs?: number;
+        /** Telemetry reporting interval in ms. @default 60000 */
+        telemetryIntervalMs?: number;
+    };
+}
+/**
+ * Resolved configuration with all defaults applied.
+ * Immutable after construction.
+ */
+export interface ResolvedConfig {
+    readonly bufferCapacity: number;
+    readonly flushOnLevels: ReadonlySet<string>;
+    readonly flushOnStatusCodes: ReadonlySet<number>;
+    readonly adapters: readonly DownstreamAdapter[];
+    readonly enabled: boolean;
+    readonly failOpen: boolean;
+    readonly scrubber?: (message: string, metadata?: Record<string, unknown>) => {
+        message: string;
+        metadata?: Record<string, unknown>;
+    };
+    readonly controlPlane?: {
+        readonly url: string;
+        readonly apiKey: string;
+        readonly pollIntervalMs: number;
+        readonly telemetryIntervalMs: number;
+    };
+}
+/**
+ * Merge user config with defaults and freeze the result.
+ */
+export declare function resolveConfig(userConfig?: BufferLogConfig): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAE/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;QAClE,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC;IAEF;;;;OAIG;IACH,YAAY,CAAC,EAAE;QACb,kEAAkE;QAClE,GAAG,EAAE,MAAM,CAAC;QACZ,iCAAiC;QACjC,MAAM,EAAE,MAAM,CAAC;QACf,oDAAoD;QACpD,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,yDAAyD;QACzD,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;QAC3E,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC;IACF,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;KACtC,CAAC;CACH;AAWD;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,GAAE,eAAoB,GAAG,cAAc,CAsB9E"}

package/dist/config.js

@@ -0,0 +1,38 @@
+/**
+ * SDK Configuration — Defines all tunable parameters for BufferLog.
+ *
+ * Design notes:
+ * - All fields are optional with sensible defaults
+ * - Configuration is frozen after initialization to prevent mutation
+ */
+/** Default configuration values. */
+const DEFAULTS = {
+    bufferCapacity: 100,
+    flushOnLevels: ['error', 'fatal', 'crit', 'emerg'],
+    flushOnStatusCodes: [500, 501, 502, 503, 504],
+    enabled: true,
+    failOpen: true,
+};
+/**
+ * Merge user config with defaults and freeze the result.
+ */
+export function resolveConfig(userConfig = {}) {
+    return Object.freeze({
+        bufferCapacity: userConfig.bufferCapacity ?? DEFAULTS.bufferCapacity,
+        flushOnLevels: new Set((userConfig.flushOnLevels ?? DEFAULTS.flushOnLevels).map((l) => l.toLowerCase())),
+        flushOnStatusCodes: new Set(userConfig.flushOnStatusCodes ?? DEFAULTS.flushOnStatusCodes),
+        adapters: Object.freeze(userConfig.adapters ?? []),
+        enabled: userConfig.enabled ?? DEFAULTS.enabled,
+        failOpen: userConfig.failOpen ?? DEFAULTS.failOpen,
+        scrubber: userConfig.scrubber,
+        controlPlane: userConfig.controlPlane
+            ? Object.freeze({
+                url: userConfig.controlPlane.url,
+                apiKey: userConfig.controlPlane.apiKey,
+                pollIntervalMs: userConfig.controlPlane.pollIntervalMs ?? 60_000,
+                telemetryIntervalMs: userConfig.controlPlane.telemetryIntervalMs ?? 60_000,
+            })
+            : undefined,
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiGH,oCAAoC;AACpC,MAAM,QAAQ,GAAG;IACf,cAAc,EAAE,GAAG;IACnB,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC;IAClD,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IAC7C,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE,IAAI;CACN,CAAC;AAEX;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,aAA8B,EAAE;IAC5D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,cAAc,EAAE,UAAU,CAAC,cAAc,IAAI,QAAQ,CAAC,cAAc;QACpE,aAAa,EAAE,IAAI,GAAG,CACpB,CAAC,UAAU,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CACjF;QACD,kBAAkB,EAAE,IAAI,GAAG,CACzB,UAAU,CAAC,kBAAkB,IAAI,QAAQ,CAAC,kBAAkB,CAC7D;QACD,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAC;QAClD,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;QAC/C,QAAQ,EAAE,UAAU,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ;QAClD,QAAQ,EAAE,UAAU,CAAC,QAAQ;QAC7B,YAAY,EAAE,UAAU,CAAC,YAAY;YACnC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;gBACZ,GAAG,EAAE,UAAU,CAAC,YAAY,CAAC,GAAG;gBAChC,MAAM,EAAE,UAAU,CAAC,YAAY,CAAC,MAAM;gBACtC,cAAc,EAAE,UAAU,CAAC,YAAY,CAAC,cAAc,IAAI,MAAM;gBAChE,mBAAmB,EAAE,UAAU,CAAC,YAAY,CAAC,mBAAmB,IAAI,MAAM;aAC3E,CAAC;YACJ,CAAC,CAAC,SAAS;KACd,CAAC,CAAC;AACL,CAAC"}

package/dist/context/async-context.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Async Context Propagation — AsyncLocalStorage wrapper for request-scoped buffers.
+ *
+ * This is the "technical moat" of BufferLog for Node.js.
+ * Uses AsyncLocalStorage (stable since Node 16) to transparently propagate
+ * the request's log buffer through:
+ * - async/await chains
+ * - Promise.then() callbacks
+ * - setTimeout / setImmediate
+ * - EventEmitter handlers
+ * - Stream callbacks
+ *
+ * Design notes:
+ * - Stores the entire RequestContext (not just contextId) to avoid map lookups on the hot path
+ * - Returns `undefined` when accessed outside a request scope → signals fail-open
+ * - The `run()` method is the only way to create a scope, ensuring cleanup is deterministic
+ */
+import type { RingBuffer } from '../core/ring-buffer.js';
+import type { LogEvent } from '../core/log-event.js';
+/**
+ * Per-request context stored in AsyncLocalStorage.
+ */
+export interface RequestContext {
+    /** Unique identifier for this request */
+    readonly contextId: string;
+    /** The ring buffer holding this request's log events */
+    readonly buffer: RingBuffer<LogEvent>;
+    /** Timestamp when the request scope was created (for latency tracking) */
+    readonly startTime: number;
+    /** Optional: arbitrary key-value pairs to include with flushed logs */
+    readonly tags?: Record<string, string>;
+}
+/**
+ * Singleton async context manager for BufferLog.
+ *
+ * Usage:
+ * ```ts
+ * BufferLogContext.run(contextId, buffer, () => {
+ *   // All async operations in this callback (and their children)
+ *   // can access the buffer via BufferLogContext.current()
+ * });
+ * ```
+ */
+export declare class BufferLogContext {
+    private static readonly storage;
+    /**
+     * Execute a function within a request-scoped context.
+     * All async operations spawned within `fn` will inherit this context.
+     *
+     * @param contextId Unique request identifier
+     * @param buffer The ring buffer for this request
+     * @param fn The function to execute within the context
+     * @param tags Optional tags to attach to the context
+     * @returns The return value of `fn`
+     */
+    static run<T>(contextId: string, buffer: RingBuffer<LogEvent>, fn: () => T, tags?: Record<string, string>): T;
+    /**
+     * Get the current request context, if one exists.
+     * Returns `undefined` if called outside a `run()` scope.
+     *
+     * This is the hot-path accessor — called on every log statement.
+     * AsyncLocalStorage.getStore() is O(1) and highly optimized in V8.
+     */
+    static current(): RequestContext | undefined;
+    /**
+     * Get the current request's buffer directly.
+     * Convenience method to avoid `BufferLogContext.current()?.buffer`.
+     */
+    static currentBuffer(): RingBuffer<LogEvent> | undefined;
+    /**
+     * Get the current context ID.
+     * Convenience method for log correlation.
+     */
+    static currentContextId(): string | undefined;
+    /**
+     * Check if we're currently inside a BufferLog request scope.
+     */
+    static isActive(): boolean;
+    /**
+     * Disable the async local storage instance.
+     * Calling this will cause all subsequent `current()` calls to return `undefined`.
+     * Used in shutdown/cleanup scenarios.
+     */
+    static disable(): void;
+}
+//# sourceMappingURL=async-context.d.ts.map

package/dist/context/async-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-context.d.ts","sourceRoot":"","sources":["../../src/context/async-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAEtC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAA2C;IAE1E;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,CAAC,CAAC,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,EAC5B,EAAE,EAAE,MAAM,CAAC,EACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,CAAC;IAWJ;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,IAAI,cAAc,GAAG,SAAS;IAI5C;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,SAAS;IAIxD;;;OAGG;IACH,MAAM,CAAC,gBAAgB,IAAI,MAAM,GAAG,SAAS;IAI7C;;OAEG;IACH,MAAM,CAAC,QAAQ,IAAI,OAAO;IAI1B;;;;OAIG;IACH,MAAM,CAAC,OAAO,IAAI,IAAI;CAGvB"}

package/dist/context/async-context.js

@@ -0,0 +1,90 @@
+/**
+ * Async Context Propagation — AsyncLocalStorage wrapper for request-scoped buffers.
+ *
+ * This is the "technical moat" of BufferLog for Node.js.
+ * Uses AsyncLocalStorage (stable since Node 16) to transparently propagate
+ * the request's log buffer through:
+ * - async/await chains
+ * - Promise.then() callbacks
+ * - setTimeout / setImmediate
+ * - EventEmitter handlers
+ * - Stream callbacks
+ *
+ * Design notes:
+ * - Stores the entire RequestContext (not just contextId) to avoid map lookups on the hot path
+ * - Returns `undefined` when accessed outside a request scope → signals fail-open
+ * - The `run()` method is the only way to create a scope, ensuring cleanup is deterministic
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Singleton async context manager for BufferLog.
+ *
+ * Usage:
+ * ```ts
+ * BufferLogContext.run(contextId, buffer, () => {
+ *   // All async operations in this callback (and their children)
+ *   // can access the buffer via BufferLogContext.current()
+ * });
+ * ```
+ */
+export class BufferLogContext {
+    static storage = new AsyncLocalStorage();
+    /**
+     * Execute a function within a request-scoped context.
+     * All async operations spawned within `fn` will inherit this context.
+     *
+     * @param contextId Unique request identifier
+     * @param buffer The ring buffer for this request
+     * @param fn The function to execute within the context
+     * @param tags Optional tags to attach to the context
+     * @returns The return value of `fn`
+     */
+    static run(contextId, buffer, fn, tags) {
+        const ctx = {
+            contextId,
+            buffer,
+            startTime: Date.now(),
+            ...(tags && { tags }),
+        };
+        return this.storage.run(ctx, fn);
+    }
+    /**
+     * Get the current request context, if one exists.
+     * Returns `undefined` if called outside a `run()` scope.
+     *
+     * This is the hot-path accessor — called on every log statement.
+     * AsyncLocalStorage.getStore() is O(1) and highly optimized in V8.
+     */
+    static current() {
+        return this.storage.getStore();
+    }
+    /**
+     * Get the current request's buffer directly.
+     * Convenience method to avoid `BufferLogContext.current()?.buffer`.
+     */
+    static currentBuffer() {
+        return this.storage.getStore()?.buffer;
+    }
+    /**
+     * Get the current context ID.
+     * Convenience method for log correlation.
+     */
+    static currentContextId() {
+        return this.storage.getStore()?.contextId;
+    }
+    /**
+     * Check if we're currently inside a BufferLog request scope.
+     */
+    static isActive() {
+        return this.storage.getStore() !== undefined;
+    }
+    /**
+     * Disable the async local storage instance.
+     * Calling this will cause all subsequent `current()` calls to return `undefined`.
+     * Used in shutdown/cleanup scenarios.
+     */
+    static disable() {
+        this.storage.disable();
+    }
+}
+//# sourceMappingURL=async-context.js.map

package/dist/context/async-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-context.js","sourceRoot":"","sources":["../../src/context/async-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAqBrD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAU,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;IAE1E;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,CACR,SAAiB,EACjB,MAA4B,EAC5B,EAAW,EACX,IAA6B;QAE7B,MAAM,GAAG,GAAmB;YAC1B,SAAS;YACT,MAAM;YACN,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,GAAG,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;SACtB,CAAC;QAEF,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,OAAO;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,aAAa;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,gBAAgB;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAQ;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,SAAS,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAO;QACZ,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC"}

package/dist/control-plane/policy-fetcher.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 interface PolicyFetcherOptions {
+    /** Control plane base URL, e.g. "https://control.bufferlog.io" */
+    controlPlaneUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Polling interval in milliseconds. @default 60000 */
+    intervalMs?: number;
+    /** Callback invoked when a new policy is received */
+    onUpdate?: (policy: RemotePolicy) => void;
+    /** Callback invoked when a fetch fails */
+    onError?: (error: Error) => void;
+}
+export interface RemotePolicy {
+    bufferCapacity: number;
+    flushOnLevels: string[];
+    flushOnStatusCodes: number[];
+    enabled: boolean;
+    samplingRate: number;
+    bypassRules: Array<{
+        field: string;
+        value: string;
+        action: string;
+    }>;
+}
+export declare class PolicyFetcher {
+    private readonly url;
+    private readonly apiKey;
+    private readonly intervalMs;
+    private readonly onUpdate?;
+    private readonly onError?;
+    private timer;
+    private abortController;
+    private _lastPolicy;
+    private _fetchCount;
+    private _errorCount;
+    constructor(options: PolicyFetcherOptions);
+    /**
+     * Start polling. Fetches immediately, then every `intervalMs`.
+     */
+    start(): void;
+    /**
+     * Stop polling and cancel any in-flight request.
+     */
+    stop(): void;
+    /**
+     * Perform a single fetch. Can be called manually to force a refresh.
+     */
+    fetch(): Promise<RemotePolicy | null>;
+    /** Last successfully fetched policy */
+    get lastPolicy(): RemotePolicy | null;
+    /** Total successful fetches */
+    get fetchCount(): number;
+    /** Total fetch errors */
+    get errorCount(): number;
+    /** Whether the fetcher is currently running */
+    get isRunning(): boolean;
+}
+//# sourceMappingURL=policy-fetcher.d.ts.map

package/dist/control-plane/policy-fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-fetcher.d.ts","sourceRoot":"","sources":["../../src/control-plane/policy-fetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC;IAExB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IAEf,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAE1C,0CAA0C;IAC1C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AAED,qBAAa,aAAa;IACxB,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,QAAQ,CAAC,CAAiC;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAyB;IAElD,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,WAAW,CAAK;gBAEZ,OAAO,EAAE,oBAAoB;IASzC;;OAEG;IACH,KAAK,IAAI,IAAI;IAcb;;OAEG;IACH,IAAI,IAAI,IAAI;IAWZ;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAsC3C,uCAAuC;IACvC,IAAI,UAAU,IAAI,YAAY,GAAG,IAAI,CAEpC;IAED,+BAA+B;IAC/B,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,yBAAyB;IACzB,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,+CAA+C;IAC/C,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF"}