vedatrace 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aaron Will Djaba
+
+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,293 @@
+# VedaTrace SDK
+
+Universal JavaScript logging SDK for VedaTrace. Type-safe, lightweight, and developer-friendly.
+
+[![npm version](https://badge.fury.io/js/vedatrace.svg)](https://www.npmjs.com/package/vedatrace)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/vedatrace)](https://bundlephobia.com/package/vedatrace)
+
+## Features
+
+- 🎯 **Type-safe** - Full TypeScript support with autocomplete
+- 🚀 **Universal** - Works in Node.js, Cloudflare Workers, and browsers
+- 📦 **Lightweight** - ~3KB core, tree-shakeable
+- ⚡ **Fast** - Background batching, non-blocking
+- 🔒 **Safe** - Never breaks your app, graceful failures
+- 🎨 **Flexible** - Console + HTTP transports, child loggers
+
+## Installation
+
+```bash
+npm install vedatrace
+# or
+yarn add vedatrace
+# or
+bun add vedatrace
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { vedatrace } from 'vedatrace'
+
+const logger = vedatrace({
+  apiKey: 'your-api-key',
+  service: 'my-service'
+})
+
+logger.info('Hello world')
+logger.error('Something went wrong', { error: err.message })
+```
+
+### Development Mode
+
+```typescript
+import { devVedatrace } from 'vedatrace'
+
+// Console-only logging for development
+const logger = devVedatrace({ service: 'my-service' })
+```
+
+## Configuration
+
+```typescript
+const logger = vedatrace({
+  apiKey: 'your-api-key',           // Required for HTTP transport
+  service: 'my-service',            // Default service name
+  endpoint: 'https://ingest.vedatrace.dev/v1/logs',
+  environment: 'production',
+  
+  // Batching
+  batchSize: 100,                   // Flush after N logs
+  flushInterval: 5000,              // Flush after N ms
+  
+  // Retry
+  maxRetries: 3,
+  retryDelay: 1000,
+  
+  // Redaction
+  redaction: {
+    paths: ['password', 'token'],
+    mask: '[REDACTED]'
+  },
+  
+  // Callbacks
+  onError: (err) => console.error('VedaTrace error:', err),
+  onSuccess: () => console.log('Logs sent')
+})
+```
+
+## Logging
+
+### All Log Levels
+
+```typescript
+logger.debug('Debug info', { query: 'SELECT *' })
+logger.info('User action', { userId: '123' })
+logger.warn('Performance warning', { duration: 500 })
+logger.error('Error occurred', { error: err })
+logger.fatal('Critical failure', { stack: err.stack })
+```
+
+### Service Override
+
+Override the default service for individual logs:
+
+```typescript
+logger.info('Payment processed', { 
+  service: 'billing-service',  // Override default
+  amount: 99.99 
+})
+```
+
+## Child Loggers
+
+Create context-aware loggers:
+
+```typescript
+const requestLogger = logger.child({ 
+  requestId: 'req_123',
+  userId: 'user_456' 
+})
+
+requestLogger.info('Processing request') 
+// Includes requestId, userId, and default service
+```
+
+## Framework Integrations
+
+### Express.js
+
+```typescript
+import express from 'express'
+import { vedaTraceMiddleware } from 'vedatrace/express'
+
+const app = express()
+app.use(vedaTraceMiddleware({ 
+  apiKey: process.env.VEDATRACE_API_KEY 
+}))
+
+app.get('/', (req, res) => {
+  req.vedatrace.info('Home page visited')
+  res.json({ ok: true })
+})
+```
+
+### Next.js (App Router)
+
+```typescript
+import { withVedaTrace } from 'vedatrace/next'
+
+export const GET = withVedaTrace(async (req, { logger }) => {
+  logger.info('API called')
+  return Response.json({ success: true })
+}, { apiKey: '...' })
+```
+
+### React
+
+```tsx
+import { VedaTraceProvider, useVedaTrace } from 'vedatrace/react'
+
+function App() {
+  return (
+    <VedaTraceProvider apiKey="..." service="frontend">
+      <MyComponent />
+    </VedaTraceProvider>
+  )
+}
+
+function MyComponent() {
+  const logger = useVedaTrace()
+  
+  useEffect(() => {
+    logger.info('Component mounted')
+  }, [])
+  
+  return <div>Hello</div>
+}
+```
+
+## Cloudflare Workers
+
+```typescript
+import { vedatrace } from 'vedatrace'
+
+export default {
+  async fetch(req, env, ctx) {
+    const logger = vedatrace({ 
+      apiKey: env.VEDATRACE_API_KEY,
+      service: 'worker'
+    })
+    
+    logger.info('Request received', { 
+      method: req.method,
+      url: req.url 
+    })
+    
+    // Ensure logs are sent before response
+    ctx.waitUntil(logger.flush())
+    
+    return new Response('OK')
+  }
+}
+```
+
+## Advanced Usage
+
+### Custom Transports
+
+```typescript
+import { VedaTraceHttpTransport, VedaTraceConsoleTransport } from 'vedatrace/transports'
+
+const logger = vedatrace({
+  transports: [
+    new VedaTraceHttpTransport({ apiKey: '...' }),
+    new VedaTraceConsoleTransport({ format: 'pretty' })
+  ]
+})
+```
+
+### Manual Flush
+
+```typescript
+// Flush all pending logs
+await logger.flush()
+
+// Use in request handlers
+app.post('/webhook', async (req, res) => {
+  logger.info('Webhook received')
+  await logger.flush() // Ensure sent before responding
+  res.json({ ok: true })
+})
+```
+
+### Error Handling
+
+```typescript
+const logger = vedatrace({
+  apiKey: '...',
+  onError: (err) => {
+    // Handle transport errors
+    metrics.increment('vedatrace.errors')
+  }
+})
+
+// SDK never throws - errors are logged to onError
+logger.error('Critical error', { stack: err.stack })
+```
+
+## Log Schema
+
+Logs sent to VedaTrace follow this schema:
+
+```typescript
+{
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+  message: string
+  service?: string
+  timestamp?: number  // Auto-generated if not provided
+  metadata?: {
+    // Any arbitrary metadata
+  }
+}
+```
+
+## API Reference
+
+### `vedatrace(config)`
+
+Creates a new logger instance.
+
+### `logger.debug(message, metadata?)`
+
+Log at debug level.
+
+### `logger.info(message, metadata?)`
+
+Log at info level.
+
+### `logger.warn(message, metadata?)`
+
+Log at warn level.
+
+### `logger.error(message | Error, metadata?)`
+
+Log at error level. Accepts string or Error object.
+
+### `logger.fatal(message | Error, metadata?)`
+
+Log at fatal level. Accepts string or Error object.
+
+### `logger.child(defaults)`
+
+Create a child logger with default metadata.
+
+### `logger.flush()`
+
+Manually flush pending logs. Returns a Promise.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,338 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var transports_index = require('./transports/index.cjs');
+
+class VedaTraceBatcher {
+  constructor(transports, config, onError, onSuccess) {
+    this.transports = transports;
+    this.config = config;
+    this.onError = onError;
+    this.onSuccess = onSuccess;
+    this.startFlushTimer();
+  }
+  queue = [];
+  flushTimer = null;
+  isFlushing = false;
+  pendingFlush = null;
+  /** Add log to queue */
+  add(log) {
+    this.queue.push(log);
+    if (this.queue.length >= this.config.batchSize) {
+      this.flush();
+    }
+  }
+  /** Flush logs to all transports */
+  async flush() {
+    if (this.isFlushing) {
+      return this.pendingFlush ?? Promise.resolve();
+    }
+    if (this.queue.length === 0) {
+      return Promise.resolve();
+    }
+    this.isFlushing = true;
+    const logsToSend = [...this.queue];
+    this.queue = [];
+    this.pendingFlush = this.sendWithRetry(logsToSend).finally(() => {
+      this.isFlushing = false;
+      this.pendingFlush = null;
+    });
+    return this.pendingFlush;
+  }
+  /** Send logs with retry logic */
+  async sendWithRetry(logs, attempt = 0) {
+    const errors = [];
+    for (const transport of this.transports) {
+      try {
+        await transport.send(logs);
+      } catch (error) {
+        errors.push(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+    if (errors.length > 0 && errors.length === this.transports.length) {
+      if (attempt < this.config.maxRetries) {
+        await this.delay(this.config.retryDelay * (attempt + 1));
+        return this.sendWithRetry(logs, attempt + 1);
+      }
+      const combinedError = new Error(
+        `Failed to send logs after ${this.config.maxRetries} retries: ${errors.map((e) => e.message).join(", ")}`
+      );
+      this.onError?.(combinedError);
+      return;
+    }
+    this.onSuccess?.();
+  }
+  /** Start the flush interval timer */
+  startFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+    }
+    this.flushTimer = setInterval(() => {
+      if (this.queue.length > 0) {
+        this.flush();
+      }
+    }, this.config.flushInterval);
+  }
+  /** Stop the flush timer */
+  stop() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  /** Delay helper */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /** Get current queue size */
+  getQueueSize() {
+    return this.queue.length;
+  }
+}
+
+const SDK_VERSION = "1.0.0";
+class VedaTraceLogger {
+  batcher = null;
+  config;
+  childDefaults;
+  constructor(config = {}, childDefaults = {}) {
+    this.childDefaults = childDefaults;
+    this.config = {
+      service: config.service,
+      apiKey: config.apiKey,
+      endpoint: config.endpoint ?? "https://api.vedatrace.io/v1/logs",
+      environment: config.environment,
+      batchSize: config.batchSize ?? 100,
+      flushInterval: config.flushInterval ?? 5e3,
+      maxRetries: config.maxRetries ?? 3,
+      retryDelay: config.retryDelay ?? 1e3,
+      onError: config.onError,
+      onSuccess: config.onSuccess,
+      debug: config.debug ?? false
+    };
+    if (!config.disabled) {
+      this.initializeBatcher(config);
+    }
+  }
+  /** Initialize the batcher with transports */
+  initializeBatcher(config) {
+    const transports = config.transports ?? [];
+    if (config.apiKey && transports.length === 0) ;
+    if (transports.length > 0) {
+      this.batcher = new VedaTraceBatcher(
+        transports,
+        {
+          batchSize: this.config.batchSize,
+          flushInterval: this.config.flushInterval,
+          maxRetries: this.config.maxRetries,
+          retryDelay: this.config.retryDelay
+        },
+        this.config.onError,
+        this.config.onSuccess
+      );
+    }
+  }
+  /** Set batcher (called from factory function) */
+  setBatcher(batcher) {
+    this.batcher = batcher;
+  }
+  /** Log at debug level */
+  debug(message, metadata) {
+    this.log("debug", message, metadata);
+  }
+  /** Log at info level */
+  info(message, metadata) {
+    this.log("info", message, metadata);
+  }
+  /** Log at warn level */
+  warn(message, metadata) {
+    this.log("warn", message, metadata);
+  }
+  /** Log at error level */
+  error(message, metadata) {
+    this.log("error", message, metadata);
+  }
+  /** Log at fatal level */
+  fatal(message, metadata) {
+    this.log("fatal", message, metadata);
+  }
+  /** Internal log method */
+  log(level, message, metadata) {
+    if (!this.batcher) {
+      return;
+    }
+    const mergedMetadata = { ...this.childDefaults, ...metadata };
+    const { service: metaService, ...cleanMetadata } = mergedMetadata;
+    const service = metaService ?? this.config.service;
+    const logEntry = {
+      level,
+      message: message instanceof Error ? message.message : message,
+      service,
+      timestamp: Date.now(),
+      metadata: cleanMetadata,
+      _sdk: {
+        source: this.detectEnvironment(),
+        version: SDK_VERSION
+      }
+    };
+    if (message instanceof Error) {
+      logEntry._sdk ??= {};
+      logEntry._sdk.stackTrace = message.stack;
+    }
+    if (this.config.debug) {
+      console.log(`[VedaTrace:${level}]`, logEntry);
+    }
+    this.batcher.add(logEntry);
+  }
+  /** Create a child logger with default metadata */
+  child(defaults) {
+    const mergedDefaults = { ...this.childDefaults, ...defaults };
+    const childLogger = new VedaTraceLogger(
+      {
+        service: this.config.service,
+        apiKey: this.config.apiKey,
+        endpoint: this.config.endpoint,
+        environment: this.config.environment,
+        disabled: !this.batcher
+      },
+      mergedDefaults
+    );
+    if (this.batcher) {
+      childLogger.setBatcher(this.batcher);
+    }
+    return childLogger;
+  }
+  /** Flush pending logs */
+  async flush() {
+    if (this.batcher) {
+      await this.batcher.flush();
+    }
+  }
+  /** Detect runtime environment */
+  detectEnvironment() {
+    if (typeof globalThis !== "undefined" && "navigator" in globalThis) {
+      return "browser";
+    }
+    if (typeof process !== "undefined" && process.versions?.node) {
+      return "node";
+    }
+    return "edge";
+  }
+}
+
+const PII_PATTERNS = {
+  // Email addresses
+  email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+  // Phone numbers (various formats)
+  phone: /(\+?1[-.\s]?)?\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}/g,
+  // Social Security Numbers
+  ssn: /\b\d{3}-?\d{2}-?\d{4}\b/g,
+  // Credit card numbers (simplified)
+  creditCard: /\b(?:\d{4}[-\s]?){3}\d{4}\b/g
+};
+const SENSITIVE_KEYS = [
+  "password",
+  "token",
+  "secret",
+  "key",
+  "apiKey",
+  "api_key",
+  "auth",
+  "authorization",
+  "cookie",
+  "session",
+  "credit_card",
+  "creditCard",
+  "cvv",
+  "ssn",
+  "social_security",
+  "dob",
+  "birthdate"
+];
+function redact(obj, config = {}) {
+  if (!obj || typeof obj !== "object") {
+    return obj;
+  }
+  const { paths = [], mask = "[REDACTED]", autoDetectPii = true } = config;
+  if (Array.isArray(obj)) {
+    return obj.map((item) => redact(item, config));
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (isSensitiveKey(key, paths)) {
+      result[key] = mask;
+      continue;
+    }
+    if (value && typeof value === "object") {
+      result[key] = redact(value, config);
+      continue;
+    }
+    if (autoDetectPii && typeof value === "string") {
+      result[key] = redactPii(value, mask);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function isSensitiveKey(key, customPaths) {
+  const lowerKey = key.toLowerCase();
+  if (SENSITIVE_KEYS.some((sensitive) => lowerKey.includes(sensitive))) {
+    return true;
+  }
+  return customPaths.some((path) => {
+    const parts = path.split(".");
+    const lastPart = parts[parts.length - 1];
+    return lastPart ? lastPart.toLowerCase() === lowerKey : false;
+  });
+}
+function redactPii(value, mask) {
+  let result = value;
+  for (const [type, pattern] of Object.entries(PII_PATTERNS)) {
+    result = result.replace(pattern, `[${type.toUpperCase()}:${mask}]`);
+  }
+  return result;
+}
+
+function vedatrace(config = {}) {
+  const logger = new VedaTraceLogger(config);
+  if (config.apiKey && (!config.transports || config.transports.length === 0)) {
+    const httpConfig = { apiKey: config.apiKey };
+    if (config.endpoint) httpConfig.endpoint = config.endpoint;
+    const httpTransport = new transports_index.VedaTraceHttpTransport(httpConfig);
+    const batcher = new VedaTraceBatcher(
+      [httpTransport],
+      {
+        batchSize: config.batchSize ?? 100,
+        flushInterval: config.flushInterval ?? 5e3,
+        maxRetries: config.maxRetries ?? 3,
+        retryDelay: config.retryDelay ?? 1e3
+      },
+      config.onError,
+      config.onSuccess
+    );
+    logger.setBatcher(batcher);
+  }
+  return logger;
+}
+function devVedatrace(config = {}) {
+  return vedatrace({
+    ...config,
+    transports: [
+      new transports_index.VedaTraceConsoleTransport({
+        format: "pretty",
+        colors: true
+      })
+    ]
+  });
+}
+
+exports.VedaTraceConsoleTransport = transports_index.VedaTraceConsoleTransport;
+exports.VedaTraceHttpTransport = transports_index.VedaTraceHttpTransport;
+exports.VedaTraceBatcher = VedaTraceBatcher;
+exports.VedaTraceLogger = VedaTraceLogger;
+exports.default = vedatrace;
+exports.devVedatrace = devVedatrace;
+exports.redact = redact;
+exports.vedatrace = vedatrace;