@trace-stack/node 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# @trace-stack/node
+
+Official Node.js SDK for [TraceStack](https://tracestack.dev) — a multi-tenant observability and log monitoring platform.
+
+**Zero dependencies** · Batching · Exponential backoff retry · Graceful shutdown · TypeScript-first
+
+---
+
+## Installation
+
+```bash
+npm install @trace-stack/node
+```
+
+> **Requires Node.js 18+** (uses native `fetch` API)
+
+## Quick Start
+
+```ts
+import { TraceStack } from "@trace-stack/node";
+
+const logger = new TraceStack({
+  apiKey: "ts_live_xxxx",
+  serviceName: "payment-service",
+});
+
+// Log at different severity levels
+logger.debug("Debugging payment flow", { step: "init" });
+logger.info("User logged in", { userId: "u_123" });
+logger.warn("High memory usage", { memoryMB: 450 });
+logger.error("Payment failed", { orderId: "ord_456", amount: 999 });
+logger.fatal("Database connection lost", { host: "db-primary" });
+
+// Graceful shutdown (flushes remaining logs)
+process.on("SIGTERM", async () => {
+  await logger.destroy();
+  process.exit(0);
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | **required** | Your TraceStack API key (must start with `ts_`) |
+| `serviceName` | `string` | `"default"` | Identifies the sending service |
+| `endpoint` | `string` | `"http://localhost:5000"` | Ingestion API URL |
+| `batchSize` | `number` | `50` | Logs to buffer before auto-flush |
+| `flushInterval` | `number` | `5000` | Auto-flush interval in ms |
+| `maxRetries` | `number` | `3` | Max retry attempts on failure |
+| `timeout` | `number` | `10000` | HTTP request timeout in ms |
+| `debug` | `boolean` | `false` | Log SDK internals to console |
+
+## Features
+
+### Batching
+
+Logs are buffered in memory and flushed in batches for efficiency. Flushes happen when:
+- The buffer reaches `batchSize` (default: 50 logs)
+- The `flushInterval` timer fires (default: every 5 seconds)
+- You call `logger.flush()` manually
+
+```ts
+// Manual flush before a critical operation
+await logger.flush();
+```
+
+### Retry with Exponential Backoff
+
+Failed HTTP requests are retried up to `maxRetries` times with exponential backoff:
+- Attempt 1: immediate
+- Retry 1: wait 1s
+- Retry 2: wait 2s
+- Retry 3: wait 4s
+
+Rate-limited requests (HTTP 429) respect the `Retry-After` header. Client errors (4xx) are **not** retried.
+
+### Auto-Metadata
+
+Every log entry automatically includes:
+- `hostname` — machine hostname
+- `pid` — Node.js process ID
+- `nodeVersion` — Node.js runtime version
+
+Custom metadata is merged with system metadata:
+
+```ts
+logger.info("Order placed", { orderId: "123", amount: 49.99 });
+// metadata = { hostname: "...", pid: 1234, nodeVersion: "v20.0.0", orderId: "123", amount: 49.99 }
+```
+
+### Graceful Shutdown
+
+The SDK registers `SIGTERM`, `SIGINT`, and `beforeExit` handlers to flush remaining logs before the process exits.
+
+You can also manually trigger shutdown:
+
+```ts
+await logger.destroy();
+```
+
+After `destroy()`, no new logs are accepted.
+
+## API Reference
+
+### `new TraceStack(config: TraceStackConfig)`
+
+Creates a new TraceStack logger instance.
+
+### `logger.debug(message, metadata?)`
+### `logger.info(message, metadata?)`
+### `logger.warn(message, metadata?)`
+### `logger.error(message, metadata?)`
+### `logger.fatal(message, metadata?)`
+
+Log a message at the specified severity level.
+
+- `message: string` — Log message (required)
+- `metadata?: Record<string, unknown>` — Optional structured data
+
+### `logger.flush(): Promise<void>`
+
+Manually flush all buffered logs to the ingestion API.
+
+### `logger.destroy(): Promise<void>`
+
+Gracefully shut down the SDK. Flushes remaining logs and stops all timers.
+
+## Log Levels
+
+| Level | When to use |
+|-------|-------------|
+| `debug` | Detailed diagnostic information |
+| `info` | General operational events |
+| `warn` | Potential issues that aren't errors |
+| `error` | Error events that might still allow the app to continue |
+| `fatal` | Critical errors that require immediate attention |
+
+## License
+
+MIT

package/dist/batcher.d.ts

@@ -0,0 +1,51 @@
+import type { LogEntry } from "./types";
+import { Transport } from "./transport";
+/**
+ * In-memory log buffer that accumulates entries and
+ * flushes them in batches via the Transport layer.
+ *
+ * Auto-flushes when:
+ * - Buffer reaches `batchSize` threshold
+ * - `flushInterval` timer fires
+ *
+ * Provides a mutex to prevent concurrent flushes.
+ */
+export declare class Batcher {
+    private buffer;
+    private flushTimer;
+    private flushing;
+    private destroyed;
+    private readonly batchSize;
+    private readonly flushInterval;
+    private readonly transport;
+    private readonly debug;
+    constructor(options: {
+        transport: Transport;
+        batchSize?: number;
+        flushInterval?: number;
+        debug?: boolean;
+    });
+    /**
+     * Add a log entry to the buffer.
+     * Triggers an immediate flush if the buffer reaches batchSize.
+     */
+    add(entry: LogEntry): void;
+    /**
+     * Flush all buffered logs to the transport.
+     * Thread-safe: only one flush can run at a time.
+     */
+    flush(): Promise<void>;
+    /**
+     * Destroy the batcher: stop the timer and flush remaining logs.
+     * After destroy(), no new logs can be added.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Returns the current number of buffered logs.
+     */
+    get size(): number;
+    private startTimer;
+    private stopTimer;
+    private log;
+}
+//# sourceMappingURL=batcher.d.ts.map

package/dist/batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batcher.d.ts","sourceRoot":"","sources":["../src/batcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AASxC;;;;;;;;;GASG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,OAAO,EAAE;QACnB,SAAS,EAAE,SAAS,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;IAUD;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAmB1B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+B5B;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,GAAG;CAKZ"}

package/dist/batcher.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Batcher = void 0;
+// ─── Constants ───────────────────────────────────────────────
+const DEFAULT_BATCH_SIZE = 50;
+const DEFAULT_FLUSH_INTERVAL = 5000; // 5 seconds
+// ─── Batcher ─────────────────────────────────────────────────
+/**
+ * In-memory log buffer that accumulates entries and
+ * flushes them in batches via the Transport layer.
+ *
+ * Auto-flushes when:
+ * - Buffer reaches `batchSize` threshold
+ * - `flushInterval` timer fires
+ *
+ * Provides a mutex to prevent concurrent flushes.
+ */
+class Batcher {
+    constructor(options) {
+        this.buffer = [];
+        this.flushTimer = null;
+        this.flushing = false;
+        this.destroyed = false;
+        this.transport = options.transport;
+        this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+        this.flushInterval = options.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
+        this.debug = options.debug ?? false;
+        // Start the periodic flush timer
+        this.startTimer();
+    }
+    /**
+     * Add a log entry to the buffer.
+     * Triggers an immediate flush if the buffer reaches batchSize.
+     */
+    add(entry) {
+        if (this.destroyed) {
+            this.log("SDK destroyed — dropping log entry");
+            return;
+        }
+        this.buffer.push(entry);
+        this.log(`Buffered log [${entry.level}]: ${entry.message.substring(0, 80)}`);
+        // Auto-flush when batch size reached
+        if (this.buffer.length >= this.batchSize) {
+            this.log(`Batch size ${this.batchSize} reached — flushing`);
+            // Fire-and-forget flush (don't block the caller)
+            this.flush().catch((err) => {
+                this.log(`Flush error: ${err}`);
+            });
+        }
+    }
+    /**
+     * Flush all buffered logs to the transport.
+     * Thread-safe: only one flush can run at a time.
+     */
+    async flush() {
+        // Mutex — prevent concurrent flushes
+        if (this.flushing) {
+            this.log("Flush already in progress — skipping");
+            return;
+        }
+        if (this.buffer.length === 0) {
+            return;
+        }
+        this.flushing = true;
+        try {
+            // Drain the buffer (take all current entries)
+            const batch = this.buffer.splice(0, this.buffer.length);
+            this.log(`Flushing ${batch.length} logs`);
+            const result = await this.transport.send({ logs: batch });
+            if (!result.success) {
+                this.log(`Flush failed: ${result.error}`);
+                // Note: we intentionally don't re-add failed logs to the buffer.
+                // This prevents unbounded memory growth if the server is persistently down.
+                // The transport layer already retried with backoff.
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /**
+     * Destroy the batcher: stop the timer and flush remaining logs.
+     * After destroy(), no new logs can be added.
+     */
+    async destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.stopTimer();
+        this.log("Destroying batcher — final flush");
+        await this.flush();
+    }
+    /**
+     * Returns the current number of buffered logs.
+     */
+    get size() {
+        return this.buffer.length;
+    }
+    // ─── Timer Management ──────────────────────────────────
+    startTimer() {
+        if (this.flushInterval > 0) {
+            this.flushTimer = setInterval(() => {
+                this.flush().catch((err) => {
+                    this.log(`Periodic flush error: ${err}`);
+                });
+            }, this.flushInterval);
+            // Allow the Node.js process to exit even if timer is running
+            if (this.flushTimer && typeof this.flushTimer === "object" && "unref" in this.flushTimer) {
+                this.flushTimer.unref();
+            }
+        }
+    }
+    stopTimer() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    // ─── Debug ─────────────────────────────────────────────
+    log(message) {
+        if (this.debug) {
+            console.log(`[TraceStack:Batcher] ${message}`);
+        }
+    }
+}
+exports.Batcher = Batcher;
+//# sourceMappingURL=batcher.js.map

package/dist/batcher.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,71 @@
+import type { TraceStackConfig } from "./types";
+/**
+ * TraceStack SDK client for Node.js.
+ *
+ * Captures logs and sends them to the TraceStack ingestion API
+ * with automatic batching, exponential backoff retry, and
+ * graceful shutdown support.
+ *
+ * @example
+ * ```ts
+ * import { TraceStack } from "@trace-stack/node";
+ *
+ * const logger = new TraceStack({
+ *   apiKey: "ts_live_xxxx",
+ *   serviceName: "payment-service",
+ * });
+ *
+ * logger.info("User logged in", { userId: "123" });
+ * logger.error("Payment failed", { orderId: "456", amount: 999 });
+ *
+ * // On shutdown
+ * await logger.destroy();
+ * ```
+ */
+export declare class TraceStack {
+    private readonly config;
+    private readonly batcher;
+    private readonly shutdownHandlers;
+    private destroyed;
+    private readonly systemMeta;
+    constructor(config: TraceStackConfig);
+    /**
+     * Log a debug-level message.
+     */
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log an info-level message.
+     */
+    info(message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log a warning-level message.
+     */
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log an error-level message.
+     */
+    error(message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log a fatal-level message.
+     */
+    fatal(message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Manually flush all buffered logs immediately.
+     * Useful before a critical operation or checkpoint.
+     */
+    flush(): Promise<void>;
+    /**
+     * Gracefully shut down the SDK.
+     * Flushes all remaining logs and stops background timers.
+     * After calling destroy(), no new logs will be accepted.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Capture a log entry and add it to the buffer.
+     */
+    private capture;
+    private registerShutdownHandlers;
+    private removeShutdownHandlers;
+    private log;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAsB,MAAM,SAAS,CAAC;AAYpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGJ;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA0B;IAC3D,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;gBAEzC,MAAM,EAAE,gBAAgB;IAwDpC;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhE;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI/D;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI/D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhE;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMhE;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9B;;OAEG;IACH,OAAO,CAAC,OAAO;IAyBf,OAAO,CAAC,wBAAwB;IAwBhC,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,GAAG;CAMZ"}

package/dist/client.js

@@ -0,0 +1,193 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceStack = void 0;
+const transport_1 = require("./transport");
+const batcher_1 = require("./batcher");
+const os_1 = __importDefault(require("os"));
+// ─── Constants ───────────────────────────────────────────────
+const API_KEY_PREFIX = "ts_";
+const DEFAULT_ENDPOINT = "http://localhost:5000";
+// ─── TraceStack Client ──────────────────────────────────────
+/**
+ * TraceStack SDK client for Node.js.
+ *
+ * Captures logs and sends them to the TraceStack ingestion API
+ * with automatic batching, exponential backoff retry, and
+ * graceful shutdown support.
+ *
+ * @example
+ * ```ts
+ * import { TraceStack } from "@trace-stack/node";
+ *
+ * const logger = new TraceStack({
+ *   apiKey: "ts_live_xxxx",
+ *   serviceName: "payment-service",
+ * });
+ *
+ * logger.info("User logged in", { userId: "123" });
+ * logger.error("Payment failed", { orderId: "456", amount: 999 });
+ *
+ * // On shutdown
+ * await logger.destroy();
+ * ```
+ */
+class TraceStack {
+    constructor(config) {
+        this.destroyed = false;
+        // ─── Validate API key ─────────────────────────────────
+        if (!config.apiKey) {
+            throw new Error("[TraceStack] apiKey is required");
+        }
+        if (!config.apiKey.startsWith(API_KEY_PREFIX)) {
+            throw new Error(`[TraceStack] apiKey must start with "${API_KEY_PREFIX}" — got "${config.apiKey.substring(0, 10)}..."`);
+        }
+        // ─── Merge defaults ──────────────────────────────────
+        this.config = {
+            ...config,
+            serviceName: config.serviceName ?? "default",
+            endpoint: config.endpoint ?? DEFAULT_ENDPOINT,
+            debug: config.debug ?? false,
+        };
+        // ─── System metadata (captured once) ─────────────────
+        this.systemMeta = {
+            hostname: os_1.default.hostname(),
+            pid: process.pid,
+            nodeVersion: process.version,
+        };
+        // ─── Initialize transport + batcher ──────────────────
+        const transport = new transport_1.Transport({
+            endpoint: this.config.endpoint,
+            apiKey: this.config.apiKey,
+            maxRetries: config.maxRetries,
+            timeout: config.timeout,
+            debug: this.config.debug,
+        });
+        this.batcher = new batcher_1.Batcher({
+            transport,
+            batchSize: config.batchSize,
+            flushInterval: config.flushInterval,
+            debug: this.config.debug,
+        });
+        // ─── Graceful shutdown handlers ──────────────────────
+        this.shutdownHandlers = [];
+        this.registerShutdownHandlers();
+        this.log("Initialized", {
+            endpoint: this.config.endpoint,
+            serviceName: this.config.serviceName,
+            batchSize: config.batchSize ?? 50,
+            flushInterval: config.flushInterval ?? 5000,
+        });
+    }
+    // ─── Public Logging Methods ────────────────────────────
+    /**
+     * Log a debug-level message.
+     */
+    debug(message, metadata) {
+        this.capture("debug", message, metadata);
+    }
+    /**
+     * Log an info-level message.
+     */
+    info(message, metadata) {
+        this.capture("info", message, metadata);
+    }
+    /**
+     * Log a warning-level message.
+     */
+    warn(message, metadata) {
+        this.capture("warn", message, metadata);
+    }
+    /**
+     * Log an error-level message.
+     */
+    error(message, metadata) {
+        this.capture("error", message, metadata);
+    }
+    /**
+     * Log a fatal-level message.
+     */
+    fatal(message, metadata) {
+        this.capture("fatal", message, metadata);
+    }
+    // ─── Buffer Control ────────────────────────────────────
+    /**
+     * Manually flush all buffered logs immediately.
+     * Useful before a critical operation or checkpoint.
+     */
+    async flush() {
+        await this.batcher.flush();
+    }
+    /**
+     * Gracefully shut down the SDK.
+     * Flushes all remaining logs and stops background timers.
+     * After calling destroy(), no new logs will be accepted.
+     */
+    async destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        this.log("Shutting down...");
+        this.removeShutdownHandlers();
+        await this.batcher.destroy();
+        this.log("Shutdown complete");
+    }
+    // ─── Internal ──────────────────────────────────────────
+    /**
+     * Capture a log entry and add it to the buffer.
+     */
+    capture(level, message, metadata) {
+        if (this.destroyed) {
+            this.log("SDK destroyed — dropping log");
+            return;
+        }
+        const entry = {
+            level,
+            message,
+            timestamp: new Date().toISOString(),
+            serviceName: this.config.serviceName,
+            metadata: metadata
+                ? { ...this.systemMeta, ...metadata }
+                : { ...this.systemMeta },
+        };
+        this.batcher.add(entry);
+    }
+    // ─── Shutdown Handlers ─────────────────────────────────
+    registerShutdownHandlers() {
+        const handler = async () => {
+            this.log("Received shutdown signal — flushing logs");
+            await this.destroy();
+        };
+        // Wrap in a sync function for process event listeners
+        const syncHandler = () => {
+            handler().catch((err) => {
+                console.error("[TraceStack] Error during shutdown flush:", err);
+            });
+        };
+        process.on("SIGTERM", syncHandler);
+        process.on("SIGINT", syncHandler);
+        process.on("beforeExit", syncHandler);
+        this.shutdownHandlers.push(async () => {
+            process.removeListener("SIGTERM", syncHandler);
+            process.removeListener("SIGINT", syncHandler);
+            process.removeListener("beforeExit", syncHandler);
+        });
+    }
+    removeShutdownHandlers() {
+        for (const remove of this.shutdownHandlers) {
+            remove().catch(() => { });
+        }
+        this.shutdownHandlers.length = 0;
+    }
+    // ─── Debug Logging ─────────────────────────────────────
+    log(message, data) {
+        if (this.config.debug) {
+            const suffix = data ? ` ${JSON.stringify(data)}` : "";
+            console.log(`[TraceStack] ${message}${suffix}`);
+        }
+    }
+}
+exports.TraceStack = TraceStack;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { TraceStack } from "./client";
+export type { TraceStackConfig, LogLevel, LogEntry, IngestPayload, IngestResponse, TransportResult, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,YAAY,EACV,gBAAgB,EAChB,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,cAAc,EACd,eAAe,GAChB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+// ─── @trace-stack/node ───────────────────────────────────────
+// Node.js SDK for TraceStack log ingestion.
+//
+// Usage:
+//   import { TraceStack } from "@trace-stack/node";
+//
+//   const logger = new TraceStack({ apiKey: "ts_live_xxx" });
+//   logger.info("Hello world");
+// ──────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceStack = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "TraceStack", { enumerable: true, get: function () { return client_1.TraceStack; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,gEAAgE;AAChE,4CAA4C;AAC5C,EAAE;AACF,SAAS;AACT,oDAAoD;AACpD,EAAE;AACF,8DAA8D;AAC9D,gCAAgC;AAChC,iEAAiE;;;AAEjE,mCAAsC;AAA7B,oGAAA,UAAU,OAAA"}

package/dist/transport.d.ts

@@ -0,0 +1,28 @@
+import type { IngestPayload, TransportResult } from "./types";
+/**
+ * HTTP transport layer for the TraceStack SDK.
+ * Handles sending log batches to the ingestion API with
+ * exponential backoff retry on failures.
+ */
+export declare class Transport {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly maxRetries;
+    private readonly timeout;
+    private readonly debug;
+    constructor(options: {
+        endpoint: string;
+        apiKey: string;
+        maxRetries?: number;
+        timeout?: number;
+        debug?: boolean;
+    });
+    /**
+     * Send a batch of logs to the ingestion API.
+     * Retries with exponential backoff on transient failures.
+     */
+    send(payload: IngestPayload): Promise<TransportResult>;
+    private sleep;
+    private log;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAU9D;;;;GAIG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,OAAO,EAAE;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;IAQD;;;OAGG;IACG,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC;IAmG5D,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,GAAG;CAKZ"}

package/dist/transport.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transport = void 0;
+// ─── Constants ───────────────────────────────────────────────
+const DEFAULT_TIMEOUT = 10000; // 10 seconds
+const DEFAULT_MAX_RETRIES = 3;
+const BASE_RETRY_DELAY = 1000; // 1 second
+// ─── Transport ───────────────────────────────────────────────
+/**
+ * HTTP transport layer for the TraceStack SDK.
+ * Handles sending log batches to the ingestion API with
+ * exponential backoff retry on failures.
+ */
+class Transport {
+    constructor(options) {
+        this.endpoint = options.endpoint;
+        this.apiKey = options.apiKey;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.debug = options.debug ?? false;
+    }
+    /**
+     * Send a batch of logs to the ingestion API.
+     * Retries with exponential backoff on transient failures.
+     */
+    async send(payload) {
+        const url = `${this.endpoint}/api/v1/logs/ingest`;
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                // Wait before retry (skip for first attempt)
+                if (attempt > 0) {
+                    const delay = BASE_RETRY_DELAY * Math.pow(2, attempt - 1);
+                    this.log(`Retry attempt ${attempt}/${this.maxRetries} after ${delay}ms`);
+                    await this.sleep(delay);
+                }
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                const response = await fetch(url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "x-api-key": this.apiKey,
+                    },
+                    body: JSON.stringify(payload),
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                // Parse response body
+                const body = await response.json().catch(() => ({}));
+                // Success
+                if (response.ok) {
+                    const data = body.data;
+                    this.log(`Successfully sent ${payload.logs.length} logs`);
+                    return {
+                        success: true,
+                        statusCode: response.status,
+                        ingested: data?.ingested ?? payload.logs.length,
+                        retries: attempt,
+                    };
+                }
+                // Rate limited — retry with Retry-After if available
+                if (response.status === 429) {
+                    const retryAfter = response.headers.get("Retry-After");
+                    if (retryAfter && attempt < this.maxRetries) {
+                        const waitMs = parseInt(retryAfter, 10) * 1000;
+                        if (!isNaN(waitMs) && waitMs > 0) {
+                            this.log(`Rate limited. Waiting ${waitMs}ms (Retry-After header)`);
+                            await this.sleep(waitMs);
+                            continue;
+                        }
+                    }
+                    lastError = `Rate limited (429)`;
+                    continue;
+                }
+                // Client errors (4xx except 429) — don't retry
+                if (response.status >= 400 && response.status < 500) {
+                    const errorMsg = body.error ?? `HTTP ${response.status}`;
+                    this.log(`Client error: ${errorMsg} — not retrying`);
+                    return {
+                        success: false,
+                        statusCode: response.status,
+                        error: errorMsg,
+                        retries: attempt,
+                    };
+                }
+                // Server errors (5xx) — retry
+                lastError = `Server error: HTTP ${response.status}`;
+                this.log(lastError);
+            }
+            catch (err) {
+                // Network error or timeout — retry
+                if (err instanceof Error) {
+                    if (err.name === "AbortError") {
+                        lastError = `Request timeout after ${this.timeout}ms`;
+                    }
+                    else {
+                        lastError = `Network error: ${err.message}`;
+                    }
+                }
+                else {
+                    lastError = "Unknown transport error";
+                }
+                this.log(lastError);
+            }
+        }
+        // All retries exhausted
+        this.log(`All ${this.maxRetries} retries exhausted. Dropping ${payload.logs.length} logs.`);
+        return {
+            success: false,
+            error: lastError ?? "Max retries exhausted",
+            retries: this.maxRetries,
+        };
+    }
+    // ─── Helpers ─────────────────────────────────────────────
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    log(message) {
+        if (this.debug) {
+            console.log(`[TraceStack] ${message}`);
+        }
+    }
+}
+exports.Transport = Transport;
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Configuration for the TraceStack SDK client.
+ */
+export interface TraceStackConfig {
+    /**
+     * Your TraceStack API key.
+     * Must start with "ts_" (e.g., "ts_live_abc123...").
+     */
+    apiKey: string;
+    /**
+     * Service name attached to every log entry.
+     * Identifies which service/app is sending logs.
+     * @example "payment-service", "api-gateway"
+     */
+    serviceName?: string;
+    /**
+     * TraceStack ingestion API endpoint.
+     * @default "http://localhost:5000"
+     */
+    endpoint?: string;
+    /**
+     * Number of logs to buffer before auto-flushing.
+     * @default 50
+     */
+    batchSize?: number;
+    /**
+     * Interval (ms) between automatic flushes of the buffer.
+     * @default 5000
+     */
+    flushInterval?: number;
+    /**
+     * Maximum number of retry attempts for failed HTTP requests.
+     * Uses exponential backoff: 1s, 2s, 4s, ...
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * HTTP request timeout in milliseconds.
+     * @default 10000
+     */
+    timeout?: number;
+    /**
+     * Enable debug logging to console.
+     * Useful during development to see SDK internals.
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Supported log severity levels, ordered by severity.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+/**
+ * A single log entry to be sent to TraceStack.
+ */
+export interface LogEntry {
+    /** Log severity level */
+    level: LogLevel;
+    /** Human-readable log message */
+    message: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Service name that generated the log */
+    serviceName: string;
+    /** Optional source identifier (file, module, function) */
+    source?: string;
+    /** Optional structured metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Payload sent to the ingestion API.
+ */
+export interface IngestPayload {
+    logs: LogEntry[];
+}
+/**
+ * Response from the ingestion API.
+ */
+export interface IngestResponse {
+    success: boolean;
+    data?: {
+        ingested: number;
+    };
+    error?: string;
+}
+/**
+ * Result of a transport send operation.
+ */
+export interface TransportResult {
+    success: boolean;
+    statusCode?: number;
+    ingested?: number;
+    error?: string;
+    retries: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,yBAAyB;IACzB,KAAK,EAAE,QAAQ,CAAC;IAEhB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAEhB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAElB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IAEpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAID;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// ─── SDK Configuration ───────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,gEAAgE"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@trace-stack/node",
+  "version": "1.0.0",
+  "description": "Node.js SDK for TraceStack — log ingestion with batching, retries, and graceful shutdown",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "tracestack",
+    "logging",
+    "observability",
+    "sdk",
+    "monitoring"
+  ],
+  "license": "MIT",
+  "devDependencies": {},
+  "dependencies": {
+    "typescript": "^5.9.3"
+  }
+}