vedatrace 0.2.1 → 0.3.1

package/README.md

@@ -32,7 +32,7 @@ bun add vedatrace
 import { vedatrace } from 'vedatrace'
 
 const logger = vedatrace({
-  apiKey: 'your-api-key',
+  apiKey: 'your-api-key',   // or set VEDATRACE_API_KEY in the environment
   service: 'my-service'
 })
 
@@ -66,12 +66,6 @@ const logger = vedatrace({
   maxRetries: 3,
   retryDelay: 1000,
   
-  // Redaction
-  redaction: {
-    paths: ['password', 'token'],
-    mask: '[REDACTED]'
-  },
-  
   // Advanced
   immediateFlush: false,           // Flush on each log (dev mode, edge runtimes)
   runtime: 'auto',                 // Force runtime: 'node' | 'browser' | 'cloudflare' | 'deno' | 'bun'
@@ -250,6 +244,8 @@ The SDK timer uses `unref()` so the process will exit automatically when there's
 ### Error Handling
 
 ```typescript
+import { vedatrace, VedaTraceTransportError } from 'vedatrace'
+
 const logger = vedatrace({
   apiKey: '...',
   onError: (err) => {
@@ -262,6 +258,50 @@ const logger = vedatrace({
 logger.error('Critical error', { stack: err.stack })
 ```
 
+Transport failures arrive as `VedaTraceTransportError`, carrying `status`,
+`retryable`, `fatal` and `retryAfterMs` so you can tell a bad key from a blip:
+
+```typescript
+onError: (err) => {
+  if (err instanceof VedaTraceTransportError && err.fatal) {
+    // 401 / 403 - the key or its allowed origins are wrong
+  }
+}
+```
+
+### Retry behaviour
+
+Failed batches retry with backoff on `408`, `425`, `429` and `5xx`, and on
+network errors. A `Retry-After` header takes precedence over the local backoff.
+Other 4xx responses are reported once and not retried, since a retry cannot
+change the outcome.
+
+A `401` or `403` **halts the logger**: the credentials will fail identically on
+every future batch, so the SDK reports once through `onError` and stops instead
+of spending a doomed request per flush. Fix the key (or the key's allowed
+origins in your project settings) and call `logger.start()` to resume.
+
+## Environment variables
+
+| Variable             | Purpose                                              |
+| -------------------- | ---------------------------------------------------- |
+| `VEDATRACE_API_KEY`  | Used when `apiKey` is not passed to `vedatrace()`.    |
+
+Reading it is guarded, so it is safe in browsers and in Workers without
+`nodejs_compat` - those simply see no key and the logger stays inert.
+
+## Browser usage
+
+In the browser the SDK batches and flushes on `visibilitychange` and `pagehide`,
+using `keepalive` so the final request outlives the page. It deliberately does
+**not** register `beforeunload` or `unload`, either of which would make the host
+page ineligible for the back/forward cache.
+
+> **Your API key ships in the bundle.** Anyone can read it out of your JavaScript.
+> Restrict browser keys to your own origins under **Project settings -> API keys ->
+> Allowed origins**, and use a separate, unrestricted key for your backend. A key
+> with no origin list accepts logs from anywhere.
+
 ## Log Schema
 
 Logs sent to VedaTrace follow this schema:
@@ -328,6 +368,12 @@ Get the detected runtime environment. Returns: `'node' | 'browser' | 'cloudflare
 console.log(logger.runtime) // 'cloudflare' when running in Workers
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Note that commit messages drive the
+published version — `feat:` is a minor, `fix:` a patch, `refactor:` releases
+nothing.
+
 ## License
 
 MIT

package/dist/index-BcBZY8as.mjs

@@ -0,0 +1,231 @@
+const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 425, 429]);
+const FATAL_STATUSES = /* @__PURE__ */ new Set([401, 403]);
+class VedaTraceTransportError extends Error {
+  name = "VedaTraceTransportError";
+  status;
+  retryable;
+  fatal;
+  /** Server-requested backoff from a `Retry-After` header, in milliseconds. */
+  retryAfterMs;
+  constructor(message, options = {}) {
+    super(message);
+    this.status = options.status;
+    this.fatal = options.fatal ?? false;
+    this.retryable = options.retryable ?? true;
+    this.retryAfterMs = options.retryAfterMs;
+  }
+  /** Build an error from an HTTP response status. */
+  static fromStatus(status, body, retryAfterMs2) {
+    const fatal = FATAL_STATUSES.has(status);
+    const retryable = status >= 500 || RETRYABLE_STATUSES.has(status);
+    return new VedaTraceTransportError(`HTTP ${status}: ${body}`, {
+      status,
+      retryable,
+      fatal,
+      retryAfterMs: retryAfterMs2
+    });
+  }
+}
+function isRetryable(error) {
+  if (error instanceof VedaTraceTransportError) return error.retryable;
+  return true;
+}
+function isFatal(error) {
+  return error instanceof VedaTraceTransportError && error.fatal;
+}
+function retryAfterMs(errors) {
+  let longest;
+  for (const error of errors) {
+    if (error instanceof VedaTraceTransportError && error.retryAfterMs) {
+      longest = Math.max(longest ?? 0, error.retryAfterMs);
+    }
+  }
+  return longest;
+}
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return void 0;
+}
+
+const LEVEL_COLORS = {
+  debug: "\x1B[36m",
+  // cyan
+  info: "\x1B[32m",
+  // green
+  warn: "\x1B[33m",
+  // yellow
+  error: "\x1B[31m",
+  // red
+  fatal: "\x1B[35m"
+  // magenta
+};
+const RESET_COLOR = "\x1B[0m";
+const LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4
+};
+class VedaTraceConsoleTransport {
+  name = "console";
+  format;
+  colors;
+  minLevel;
+  constructor(config = {}) {
+    this.format = config.format ?? "pretty";
+    this.colors = config.colors ?? true;
+    this.minLevel = config.minLevel ?? "debug";
+  }
+  /** Send logs to console */
+  send(logs) {
+    for (const log of logs) {
+      if (LEVEL_PRIORITY[log.level] < LEVEL_PRIORITY[this.minLevel]) {
+        continue;
+      }
+      switch (this.format) {
+        case "json":
+          this.logJson(log);
+          break;
+        case "simple":
+          this.logSimple(log);
+          break;
+        default:
+          this.logPretty(log);
+          break;
+      }
+    }
+  }
+  /** Format as JSON */
+  logJson(log) {
+    console.log(JSON.stringify(log));
+  }
+  /** Format as simple text */
+  logSimple(log) {
+    const timestamp = new Date(log.timestamp ?? Date.now()).toISOString();
+    const service = log.service ? `[${log.service}] ` : "";
+    console.log(
+      `${timestamp} ${log.level.toUpperCase()} ${service}${log.message}`
+    );
+  }
+  /** Format as pretty colored output */
+  logPretty(log) {
+    const timestamp = new Date(log.timestamp ?? Date.now()).toISOString();
+    const color = this.colors ? LEVEL_COLORS[log.level] : "";
+    const reset = this.colors ? RESET_COLOR : "";
+    const service = log.service ? ` ${color}[${log.service}]${reset}` : "";
+    let output = `${timestamp} ${color}${log.level.toUpperCase()}${reset}${service} ${log.message}`;
+    if (log.metadata && Object.keys(log.metadata).length > 0) {
+      output += `
+  ${color}metadata:${reset} ${JSON.stringify(log.metadata, null, 2).replace(/\n/g, "\n  ")}`;
+    }
+    console.log(output);
+  }
+}
+
+const KEEPALIVE_MAX_BYTES = 56 * 1024;
+const encoder = new TextEncoder();
+class VedaTraceHttpTransport {
+  name = "http";
+  endpoint;
+  apiKey;
+  timeout;
+  headers;
+  keepalive;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.endpoint = config.endpoint ?? "https://ingest.vedatrace.dev/v1/logs";
+    this.timeout = config.timeout ?? 3e4;
+    this.headers = config.headers ?? {};
+    this.keepalive = config.keepalive ?? false;
+  }
+  /** Send logs via HTTP POST */
+  async send(logs) {
+    if (logs.length === 0) return;
+    const body = JSON.stringify(logs.map(toWirePayload));
+    if (this.keepalive && encoder.encode(body).length > KEEPALIVE_MAX_BYTES) {
+      if (logs.length > 1) {
+        const mid = Math.ceil(logs.length / 2);
+        await this.send(logs.slice(0, mid));
+        await this.send(logs.slice(mid));
+        return;
+      }
+      return this.post(body, false);
+    }
+    return this.post(body, this.keepalive);
+  }
+  async post(body, keepalive) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(this.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey,
+          ...this.headers
+        },
+        body,
+        signal: controller.signal,
+        keepalive
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw VedaTraceTransportError.fromStatus(
+          response.status,
+          text,
+          parseRetryAfter(response.headers.get("Retry-After"))
+        );
+      }
+    } catch (error) {
+      if (error instanceof VedaTraceTransportError) throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new VedaTraceTransportError(
+          `Request timeout after ${this.timeout}ms`,
+          { retryable: true }
+        );
+      }
+      throw new VedaTraceTransportError(
+        error instanceof Error ? error.message : String(error),
+        { retryable: true }
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * No-op: this transport holds no buffer of its own. The batcher owns the
+   * queue and calls send() directly, including on the browser's final flush.
+   */
+  async flush() {
+    return Promise.resolve();
+  }
+  /** Check if keepalive is enabled */
+  isKeepaliveEnabled() {
+    return this.keepalive;
+  }
+  /** Enable/disable keepalive */
+  setKeepalive(enabled) {
+    this.keepalive = enabled;
+  }
+}
+function toWirePayload(log) {
+  return {
+    level: log.level,
+    message: log.message,
+    service: log.service,
+    timestamp: log.timestamp ? new Date(log.timestamp).toISOString() : void 0,
+    metadata: log.metadata
+  };
+}
+class VedaTraceHttpTransportBrowser extends VedaTraceHttpTransport {
+  constructor(config) {
+    super({ ...config, keepalive: true });
+  }
+}
+
+export { VedaTraceHttpTransportBrowser as V, isRetryable as a, VedaTraceHttpTransport as b, VedaTraceConsoleTransport as c, VedaTraceTransportError as d, isFatal as i, retryAfterMs as r };

package/dist/index-osD28Hs0.cjs

@@ -0,0 +1,239 @@
+'use strict';
+
+const RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 425, 429]);
+const FATAL_STATUSES = /* @__PURE__ */ new Set([401, 403]);
+class VedaTraceTransportError extends Error {
+  name = "VedaTraceTransportError";
+  status;
+  retryable;
+  fatal;
+  /** Server-requested backoff from a `Retry-After` header, in milliseconds. */
+  retryAfterMs;
+  constructor(message, options = {}) {
+    super(message);
+    this.status = options.status;
+    this.fatal = options.fatal ?? false;
+    this.retryable = options.retryable ?? true;
+    this.retryAfterMs = options.retryAfterMs;
+  }
+  /** Build an error from an HTTP response status. */
+  static fromStatus(status, body, retryAfterMs2) {
+    const fatal = FATAL_STATUSES.has(status);
+    const retryable = status >= 500 || RETRYABLE_STATUSES.has(status);
+    return new VedaTraceTransportError(`HTTP ${status}: ${body}`, {
+      status,
+      retryable,
+      fatal,
+      retryAfterMs: retryAfterMs2
+    });
+  }
+}
+function isRetryable(error) {
+  if (error instanceof VedaTraceTransportError) return error.retryable;
+  return true;
+}
+function isFatal(error) {
+  return error instanceof VedaTraceTransportError && error.fatal;
+}
+function retryAfterMs(errors) {
+  let longest;
+  for (const error of errors) {
+    if (error instanceof VedaTraceTransportError && error.retryAfterMs) {
+      longest = Math.max(longest ?? 0, error.retryAfterMs);
+    }
+  }
+  return longest;
+}
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return void 0;
+}
+
+const LEVEL_COLORS = {
+  debug: "\x1B[36m",
+  // cyan
+  info: "\x1B[32m",
+  // green
+  warn: "\x1B[33m",
+  // yellow
+  error: "\x1B[31m",
+  // red
+  fatal: "\x1B[35m"
+  // magenta
+};
+const RESET_COLOR = "\x1B[0m";
+const LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4
+};
+class VedaTraceConsoleTransport {
+  name = "console";
+  format;
+  colors;
+  minLevel;
+  constructor(config = {}) {
+    this.format = config.format ?? "pretty";
+    this.colors = config.colors ?? true;
+    this.minLevel = config.minLevel ?? "debug";
+  }
+  /** Send logs to console */
+  send(logs) {
+    for (const log of logs) {
+      if (LEVEL_PRIORITY[log.level] < LEVEL_PRIORITY[this.minLevel]) {
+        continue;
+      }
+      switch (this.format) {
+        case "json":
+          this.logJson(log);
+          break;
+        case "simple":
+          this.logSimple(log);
+          break;
+        default:
+          this.logPretty(log);
+          break;
+      }
+    }
+  }
+  /** Format as JSON */
+  logJson(log) {
+    console.log(JSON.stringify(log));
+  }
+  /** Format as simple text */
+  logSimple(log) {
+    const timestamp = new Date(log.timestamp ?? Date.now()).toISOString();
+    const service = log.service ? `[${log.service}] ` : "";
+    console.log(
+      `${timestamp} ${log.level.toUpperCase()} ${service}${log.message}`
+    );
+  }
+  /** Format as pretty colored output */
+  logPretty(log) {
+    const timestamp = new Date(log.timestamp ?? Date.now()).toISOString();
+    const color = this.colors ? LEVEL_COLORS[log.level] : "";
+    const reset = this.colors ? RESET_COLOR : "";
+    const service = log.service ? ` ${color}[${log.service}]${reset}` : "";
+    let output = `${timestamp} ${color}${log.level.toUpperCase()}${reset}${service} ${log.message}`;
+    if (log.metadata && Object.keys(log.metadata).length > 0) {
+      output += `
+  ${color}metadata:${reset} ${JSON.stringify(log.metadata, null, 2).replace(/\n/g, "\n  ")}`;
+    }
+    console.log(output);
+  }
+}
+
+const KEEPALIVE_MAX_BYTES = 56 * 1024;
+const encoder = new TextEncoder();
+class VedaTraceHttpTransport {
+  name = "http";
+  endpoint;
+  apiKey;
+  timeout;
+  headers;
+  keepalive;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.endpoint = config.endpoint ?? "https://ingest.vedatrace.dev/v1/logs";
+    this.timeout = config.timeout ?? 3e4;
+    this.headers = config.headers ?? {};
+    this.keepalive = config.keepalive ?? false;
+  }
+  /** Send logs via HTTP POST */
+  async send(logs) {
+    if (logs.length === 0) return;
+    const body = JSON.stringify(logs.map(toWirePayload));
+    if (this.keepalive && encoder.encode(body).length > KEEPALIVE_MAX_BYTES) {
+      if (logs.length > 1) {
+        const mid = Math.ceil(logs.length / 2);
+        await this.send(logs.slice(0, mid));
+        await this.send(logs.slice(mid));
+        return;
+      }
+      return this.post(body, false);
+    }
+    return this.post(body, this.keepalive);
+  }
+  async post(body, keepalive) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(this.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-API-Key": this.apiKey,
+          ...this.headers
+        },
+        body,
+        signal: controller.signal,
+        keepalive
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw VedaTraceTransportError.fromStatus(
+          response.status,
+          text,
+          parseRetryAfter(response.headers.get("Retry-After"))
+        );
+      }
+    } catch (error) {
+      if (error instanceof VedaTraceTransportError) throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new VedaTraceTransportError(
+          `Request timeout after ${this.timeout}ms`,
+          { retryable: true }
+        );
+      }
+      throw new VedaTraceTransportError(
+        error instanceof Error ? error.message : String(error),
+        { retryable: true }
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * No-op: this transport holds no buffer of its own. The batcher owns the
+   * queue and calls send() directly, including on the browser's final flush.
+   */
+  async flush() {
+    return Promise.resolve();
+  }
+  /** Check if keepalive is enabled */
+  isKeepaliveEnabled() {
+    return this.keepalive;
+  }
+  /** Enable/disable keepalive */
+  setKeepalive(enabled) {
+    this.keepalive = enabled;
+  }
+}
+function toWirePayload(log) {
+  return {
+    level: log.level,
+    message: log.message,
+    service: log.service,
+    timestamp: log.timestamp ? new Date(log.timestamp).toISOString() : void 0,
+    metadata: log.metadata
+  };
+}
+class VedaTraceHttpTransportBrowser extends VedaTraceHttpTransport {
+  constructor(config) {
+    super({ ...config, keepalive: true });
+  }
+}
+
+exports.VedaTraceConsoleTransport = VedaTraceConsoleTransport;
+exports.VedaTraceHttpTransport = VedaTraceHttpTransport;
+exports.VedaTraceHttpTransportBrowser = VedaTraceHttpTransportBrowser;
+exports.VedaTraceTransportError = VedaTraceTransportError;
+exports.isFatal = isFatal;
+exports.isRetryable = isRetryable;
+exports.retryAfterMs = retryAfterMs;