@logtide/sdk-node 0.1.1 → 0.2.1

package/README.md

@@ -1,21 +1,36 @@
-# LogTide Node.js SDK
+<p align="center">
+  <img src="https://raw.githubusercontent.com/logtide-dev/logtide/main/docs/images/logo.png" alt="LogTide Logo" width="400">
+</p>
 
-Official Node.js SDK for LogTide with advanced features: retry logic, circuit breaker, query API, live streaming, and middleware support.
+<h1 align="center">LogTide Node.js SDK</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@logtide/sdk-node"><img src="https://img.shields.io/npm/v/@logtide/sdk-node?color=blue" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18+-green.svg" alt="Node.js"></a>
+  <a href="https://github.com/logtide-dev/logtide-sdk-node/releases"><img src="https://img.shields.io/github/v/release/logtide-dev/logtide-sdk-node" alt="Release"></a>
+</p>
+
+<p align="center">
+  Official Node.js SDK for <a href="https://logtide.dev">LogTide</a> with automatic batching, retry logic, circuit breaker, query API, live streaming, and middleware support.
+</p>
+
+---
 
 ## Features
 
-- ✅ **Automatic batching** with configurable size and interval
-- ✅ **Retry logic** with exponential backoff
-- ✅ **Circuit breaker** pattern for fault tolerance
-- ✅ **Max buffer size** with drop policy to prevent memory leaks
-- ✅ **Query API** for searching and filtering logs
-- ✅ **Live tail** with Server-Sent Events (SSE)
-- ✅ **Trace ID context** for distributed tracing
-- ✅ **Global metadata** added to all logs
-- ✅ **Structured error serialization**
-- ✅ **Internal metrics** (logs sent, errors, latency, etc.)
-- ✅ **Express & Fastify middleware** for auto-logging HTTP requests
-- ✅ **Full TypeScript support** with strict types
+- **Automatic batching** with configurable size and interval
+- **Retry logic** with exponential backoff
+- **Circuit breaker** pattern for fault tolerance
+- **Max buffer size** with drop policy to prevent memory leaks
+- **Query API** for searching and filtering logs
+- **Live tail** with Server-Sent Events (SSE)
+- **Trace ID context** for distributed tracing
+- **Global metadata** added to all logs
+- **Structured error serialization**
+- **Internal metrics** (logs sent, errors, latency, etc.)
+- **Express & Fastify middleware** for auto-logging HTTP requests
+- **Full TypeScript support** with strict types
 
 ## Installation
 
@@ -89,7 +104,7 @@ const client = new LogTideClient({
   // Buffer management
   maxBufferSize: 10000,
 
-  // Retry with exponential backoff (1s → 2s → 4s)
+  // Retry with exponential backoff (1s -> 2s -> 4s)
   maxRetries: 3,
   retryDelayMs: 1000,
 
@@ -158,9 +173,9 @@ client.log({
   service: 'custom-service',
   level: 'info',
   message: 'Custom log',
-  time: new Date().toISOString(), // Optional
+  time: new Date().toISOString(),
   metadata: { key: 'value' },
-  trace_id: 'custom-trace-id', // Optional
+  trace_id: 'custom-trace-id',
 });
 ```
 
@@ -201,16 +216,6 @@ client.withNewTraceId(() => {
 });
 ```
 
-### Auto Trace ID Mode
-
-```typescript
-const client = new LogTideClient({
-  apiUrl: 'http://localhost:8080',
-  apiKey: 'lp_your_api_key_here',
-  autoTraceId: true, // Every log gets a unique trace ID
-});
-```
-
 ---
 
 ## Query API
@@ -315,7 +320,9 @@ client.resetMetrics();
 
 ---
 
-## Middleware
+## Middleware Integration
+
+LogTide provides ready-to-use middleware for popular frameworks.
 
 ### Express Middleware
 
@@ -385,6 +392,17 @@ await fastify.listen({ port: 3000 });
 
 ---
 
+## Examples
+
+See the [examples/](./examples) directory for complete working examples:
+
+- **[basic.ts](./examples/basic.ts)** - Simple usage
+- **[advanced.ts](./examples/advanced.ts)** - All advanced features
+- **[express-middleware.ts](./examples/express-middleware.ts)** - Express integration
+- **[fastify-plugin.ts](./examples/fastify-plugin.ts)** - Fastify integration
+
+---
+
 ## Best Practices
 
 ### 1. Always Close on Shutdown
@@ -442,72 +460,6 @@ setInterval(() => {
 }, 60000);
 ```
 
-### 5. Use Trace IDs for Request Correlation
-
-```typescript
-app.use((req, res, next) => {
-  const traceId = req.headers['x-trace-id'] || randomUUID();
-  req.traceId = traceId;
-
-  client.withTraceId(traceId, () => {
-    next();
-  });
-});
-```
-
----
-
-## API Reference
-
-### LogTideClient
-
-#### Constructor
-```typescript
-new LogTideClient(options: LogTideClientOptions)
-```
-
-#### Logging Methods
-- `log(entry: LogEntry): void`
-- `debug(service: string, message: string, metadata?: object): void`
-- `info(service: string, message: string, metadata?: object): void`
-- `warn(service: string, message: string, metadata?: object): void`
-- `error(service: string, message: string, metadataOrError?: object | Error): void`
-- `critical(service: string, message: string, metadataOrError?: object | Error): void`
-
-#### Context Methods
-- `setTraceId(traceId: string | null): void`
-- `getTraceId(): string | null`
-- `withTraceId<T>(traceId: string, fn: () => T): T`
-- `withNewTraceId<T>(fn: () => T): T`
-
-#### Query Methods
-- `query(options: QueryOptions): Promise<LogsResponse>`
-- `getByTraceId(traceId: string): Promise<InternalLogEntry[]>`
-- `getAggregatedStats(options: AggregatedStatsOptions): Promise<AggregatedStatsResponse>`
-
-#### Streaming
-- `stream(options: StreamOptions): () => void` (returns cleanup function)
-
-#### Metrics
-- `getMetrics(): ClientMetrics`
-- `resetMetrics(): void`
-- `getCircuitBreakerState(): string`
-
-#### Lifecycle
-- `flush(): Promise<void>`
-- `close(): Promise<void>`
-
----
-
-## Examples
-
-See the [examples/](./examples) directory for complete working examples:
-
-- **[basic.ts](./examples/basic.ts)** - Simple usage
-- **[advanced.ts](./examples/advanced.ts)** - All advanced features
-- **[express-middleware.ts](./examples/express-middleware.ts)** - Express integration
-- **[fastify-plugin.ts](./examples/fastify-plugin.ts)** - Fastify integration
-
 ---
 
 ## TypeScript Support
@@ -526,36 +478,16 @@ import type {
 
 ---
 
-## Testing
-
-Run the test suite:
-
-```bash
-# Run tests
-pnpm test
-
-# Watch mode
-pnpm test:watch
-
-# Coverage
-pnpm test:coverage
-```
+## Contributing
 
----
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
-MIT
-
----
-
-## Contributing
-
-Contributions are welcome! Please open an issue or PR on [GitHub](https://github.com/logtide-dev/logtide-sdk-node).
-
----
+MIT License - see [LICENSE](LICENSE) for details.
 
-## Support
+## Links
 
-- **Documentation**: [https://logtide.dev/docs](https://logtide.dev/docs)
-- **Issues**: [GitHub Issues](https://github.com/logtide-dev/logtide-sdk-node/issues)
+- [LogTide Website](https://logtide.dev)
+- [Documentation](https://logtide.dev/docs/sdks/node/)
+- [GitHub Issues](https://github.com/logtide-dev/logtide-sdk-node/issues)

package/dist/index.cjs

@@ -42,25 +42,6 @@ var CircuitBreaker = class {
     return this.state;
   }
 };
-function isValidUUID(str) {
-  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-  return uuidRegex.test(str);
-}
-function normalizeTraceId(traceId, debug) {
-  if (!traceId) {
-    return void 0;
-  }
-  if (isValidUUID(traceId)) {
-    return traceId;
-  }
-  const newTraceId = crypto.randomUUID();
-  if (debug) {
-    console.warn(
-      `[LogTide] Invalid trace_id "${traceId}" (must be UUID v4). Generated new UUID: ${newTraceId}`
-    );
-  }
-  return newTraceId;
-}
 function serializeError(error) {
   if (error instanceof Error) {
     const result = {
@@ -108,6 +89,11 @@ var LogTideClient = class {
   latencies = [];
   // Context tracking
   currentTraceId = null;
+  // Console interception
+  consoleInterceptOptions = null;
+  originalConsole = null;
+  // Payload limits
+  payloadLimits;
   constructor(options) {
     this.apiUrl = options.apiUrl.replace(/\/$/, "");
     this.apiKey = options.apiKey;
@@ -124,15 +110,25 @@ var LogTideClient = class {
       options.circuitBreakerThreshold || 5,
       options.circuitBreakerResetMs || 3e4
     );
+    this.payloadLimits = {
+      maxFieldSize: options.payloadLimits?.maxFieldSize ?? 10 * 1024,
+      // 10KB
+      maxLogSize: options.payloadLimits?.maxLogSize ?? 100 * 1024,
+      // 100KB
+      excludeFields: options.payloadLimits?.excludeFields ?? [],
+      truncationMarker: options.payloadLimits?.truncationMarker ?? "...[TRUNCATED]"
+    };
     this.startFlushTimer();
+    if (options.interceptConsole?.enabled) {
+      this.startConsoleInterception(options.interceptConsole);
+    }
   }
   // ==================== Context Helpers ====================
   /**
    * Set trace ID for subsequent logs
-   * Automatically validates and normalizes to UUID v4
    */
   setTraceId(traceId) {
-    this.currentTraceId = normalizeTraceId(traceId, this.debugMode) || null;
+    this.currentTraceId = traceId;
   }
   /**
    * Get current trace ID
@@ -158,6 +154,207 @@ var LogTideClient = class {
   withNewTraceId(fn) {
     return this.withTraceId(crypto.randomUUID(), fn);
   }
+  // ==================== Console Interception ====================
+  /**
+   * Start intercepting console methods and forward them to LogTide
+   */
+  startConsoleInterception(options) {
+    if (this.originalConsole) {
+      return;
+    }
+    const config = {
+      enabled: true,
+      service: options?.service ?? "console",
+      preserveOriginal: options?.preserveOriginal ?? true,
+      includeStackTrace: options?.includeStackTrace ?? false,
+      levels: {
+        log: options?.levels?.log ?? true,
+        info: options?.levels?.info ?? true,
+        warn: options?.levels?.warn ?? true,
+        error: options?.levels?.error ?? true,
+        debug: options?.levels?.debug ?? true
+      }
+    };
+    this.consoleInterceptOptions = config;
+    this.originalConsole = {
+      log: console.log.bind(console),
+      info: console.info.bind(console),
+      warn: console.warn.bind(console),
+      error: console.error.bind(console),
+      debug: console.debug.bind(console)
+    };
+    const createInterceptor = (method, level) => {
+      const original = this.originalConsole[method];
+      return (...args) => {
+        if (config.preserveOriginal) {
+          original(...args);
+        }
+        if (!config.levels?.[method]) {
+          return;
+        }
+        const message = args.map((arg) => {
+          if (typeof arg === "string") return arg;
+          if (arg instanceof Error) return arg.message;
+          try {
+            return JSON.stringify(arg);
+          } catch {
+            return String(arg);
+          }
+        }).join(" ");
+        if (message.startsWith("[LogTide]")) {
+          return;
+        }
+        const metadata = {
+          source: "console",
+          originalMethod: method
+        };
+        if (config.includeStackTrace) {
+          const stack = new Error().stack;
+          if (stack) {
+            const stackLines = stack.split("\n").slice(2);
+            metadata.stackTrace = stackLines.join("\n");
+            const callerLine = stackLines[0];
+            if (callerLine) {
+              const match = callerLine.match(/at\s+(.+?)\s+\((.+):(\d+):(\d+)\)/);
+              if (match) {
+                metadata.caller = {
+                  function: match[1],
+                  file: match[2],
+                  line: parseInt(match[3], 10),
+                  column: parseInt(match[4], 10)
+                };
+              } else {
+                const altMatch = callerLine.match(/at\s+(.+):(\d+):(\d+)/);
+                if (altMatch) {
+                  metadata.caller = {
+                    file: altMatch[1],
+                    line: parseInt(altMatch[2], 10),
+                    column: parseInt(altMatch[3], 10)
+                  };
+                }
+              }
+            }
+          }
+        }
+        if (args.length > 1 || args.length === 1 && typeof args[0] !== "string") {
+          metadata.args = args.map((arg) => {
+            if (arg instanceof Error) {
+              return serializeError(arg);
+            }
+            return arg;
+          });
+        }
+        this.log({
+          service: config.service,
+          level,
+          message,
+          metadata
+        });
+      };
+    };
+    console.log = createInterceptor("log", "info");
+    console.info = createInterceptor("info", "info");
+    console.warn = createInterceptor("warn", "warn");
+    console.error = createInterceptor("error", "error");
+    console.debug = createInterceptor("debug", "debug");
+    if (this.debugMode) {
+      this.originalConsole.log("[LogTide] Console interception started");
+    }
+  }
+  /**
+   * Stop intercepting console methods and restore originals
+   */
+  stopConsoleInterception() {
+    if (!this.originalConsole) {
+      return;
+    }
+    console.log = this.originalConsole.log;
+    console.info = this.originalConsole.info;
+    console.warn = this.originalConsole.warn;
+    console.error = this.originalConsole.error;
+    console.debug = this.originalConsole.debug;
+    if (this.debugMode) {
+      console.log("[LogTide] Console interception stopped");
+    }
+    this.originalConsole = null;
+    this.consoleInterceptOptions = null;
+  }
+  /**
+   * Check if console interception is active
+   */
+  isConsoleInterceptionActive() {
+    return this.originalConsole !== null;
+  }
+  // ==================== Payload Processing ====================
+  /**
+   * Check if a string looks like base64 encoded data
+   */
+  looksLikeBase64(str) {
+    if (typeof str !== "string" || str.length < 100) return false;
+    if (str.startsWith("data:")) return true;
+    const base64Regex = /^[A-Za-z0-9+/=]{100,}$/;
+    return base64Regex.test(str.replace(/\s/g, ""));
+  }
+  /**
+   * Process a value for payload limits (truncation, base64 removal, etc.)
+   */
+  processValue(value, fieldPath) {
+    const fieldName = fieldPath.split(".").pop() || fieldPath;
+    if (this.payloadLimits.excludeFields.includes(fieldName)) {
+      return "[EXCLUDED]";
+    }
+    if (value === null || value === void 0) {
+      return value;
+    }
+    if (typeof value === "string") {
+      if (this.looksLikeBase64(value)) {
+        return "[BASE64 DATA REMOVED]";
+      }
+      if (value.length > this.payloadLimits.maxFieldSize) {
+        return value.substring(0, this.payloadLimits.maxFieldSize) + this.payloadLimits.truncationMarker;
+      }
+      return value;
+    }
+    if (Array.isArray(value)) {
+      return value.map((item, index) => this.processValue(item, `${fieldPath}[${index}]`));
+    }
+    if (typeof value === "object") {
+      const processed = {};
+      for (const [key, val] of Object.entries(value)) {
+        processed[key] = this.processValue(val, `${fieldPath}.${key}`);
+      }
+      return processed;
+    }
+    return value;
+  }
+  /**
+   * Process metadata to apply payload limits
+   */
+  processMetadata(metadata) {
+    if (!metadata) return metadata;
+    return this.processValue(metadata, "metadata");
+  }
+  /**
+   * Ensure log entry doesn't exceed max size
+   */
+  enforceMaxLogSize(entry) {
+    const serialized = JSON.stringify(entry);
+    if (serialized.length <= this.payloadLimits.maxLogSize) {
+      return entry;
+    }
+    if (this.debugMode) {
+      console.warn(`[LogTide] Log entry too large (${serialized.length} bytes), truncating metadata`);
+    }
+    const truncated = {
+      ...entry,
+      metadata: {
+        _truncated: true,
+        _originalSize: serialized.length,
+        message: entry.message
+      }
+    };
+    return truncated;
+  }
   // ==================== Logging Methods ====================
   startFlushTimer() {
     this.timer = setInterval(() => {
@@ -172,16 +369,19 @@ var LogTideClient = class {
       }
       return;
     }
-    const normalizedTraceId = normalizeTraceId(entry.trace_id, this.debugMode) || normalizeTraceId(this.currentTraceId, this.debugMode) || (this.autoTraceId ? crypto.randomUUID() : void 0);
-    const internalEntry = {
+    const traceId = entry.trace_id || this.currentTraceId || (this.autoTraceId ? crypto.randomUUID() : void 0);
+    const mergedMetadata = {
+      ...this.globalMetadata,
+      ...entry.metadata
+    };
+    const processedMetadata = this.processMetadata(mergedMetadata);
+    let internalEntry = {
       ...entry,
       time: entry.time || (/* @__PURE__ */ new Date()).toISOString(),
-      metadata: {
-        ...this.globalMetadata,
-        ...entry.metadata
-      },
-      trace_id: normalizedTraceId
+      metadata: processedMetadata,
+      trace_id: traceId
     };
+    internalEntry = this.enforceMaxLogSize(internalEntry);
     this.buffer.push(internalEntry);
     if (this.buffer.length >= this.batchSize) {
       this.flush();
@@ -396,6 +596,7 @@ var LogTideClient = class {
       clearInterval(this.timer);
       this.timer = null;
     }
+    this.stopConsoleInterception();
     await this.flush();
   }
 };