vedatrace 0.2.1 → 0.3.1

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var transports_index = require('./transports/index.cjs');
+var transports_index = require('./index-osD28Hs0.cjs');
 
 class VedaTraceBatcher {
   constructor(transports, config, immediateFlush = false) {
@@ -10,55 +10,53 @@ class VedaTraceBatcher {
     this.config = config;
     this.immediateFlush = immediateFlush;
     this.context = config.executionContext;
+    this.waitUntilFn = config.waitUntil;
   }
   queue = [];
   flushTimer = null;
-  flushDebounceTimer = null;
+  flushQueued = false;
   isFlushing = false;
   pendingFlush = null;
   context;
-  /** Attach execution context after initialization */
+  waitUntilFn;
+  /**
+   * Set when the ingestion endpoint rejects our credentials. Every subsequent
+   * batch would fail identically, so we stop rather than spend a request (and a
+   * retry storm) per flush for the life of the process. start() clears it.
+   */
+  halted = false;
   setContext(ctx) {
     this.context = ctx;
   }
-  /** Get current context */
   getContext() {
     return this.context;
   }
-  /** Add log to queue with context-aware flush */
   add(log) {
+    if (this.halted) return;
     this.queue.push(log);
-    if (!this.flushTimer && !this.immediateFlush) {
+    if (this.context || this.waitUntilFn) {
+      this.debouncedFlush();
+      return;
+    }
+    if (this.immediateFlush) {
+      this.flush();
+      return;
+    }
+    if (!this.flushTimer) {
       this.startFlushTimer();
     }
-    if (this.immediateFlush || this.context) {
-      this.debouncedFlush();
-    } else if (this.queue.length >= this.config.batchSize) {
+    if (this.queue.length >= this.config.batchSize) {
       this.flush();
     }
   }
-  /** Debounced flush - prevents rapid-fire flushes */
   debouncedFlush() {
-    if (this.flushDebounceTimer) {
-      clearTimeout(this.flushDebounceTimer);
-    }
-    this.flushDebounceTimer = setTimeout(() => {
-      this.flushDebounceTimer = null;
-      this.flush().catch((error) => {
-        if (this.config.onError) {
-          this.config.onError(
-            error instanceof Error ? error : new Error(String(error))
-          );
-        } else {
-          console.error(
-            "[VedaTrace] Debounced flush error:",
-            error instanceof Error ? error.message : String(error)
-          );
-        }
-      });
-    }, 100);
+    if (this.flushQueued) return;
+    this.flushQueued = true;
+    queueMicrotask(() => {
+      this.flushQueued = false;
+      this.flush().catch((error) => this.reportError(error));
+    });
   }
-  /** Flush logs to all transports with waitUntil protection */
   async flush() {
     if (this.isFlushing) {
       return this.pendingFlush ?? Promise.resolve();
@@ -72,10 +70,16 @@ class VedaTraceBatcher {
     const flushPromise = this.sendWithRetry(logsToSend).finally(() => {
       this.isFlushing = false;
       this.pendingFlush = null;
+    }).then(() => {
+      if (this.queue.length > 0 && !this.halted) {
+        return this.flush();
+      }
     });
     this.pendingFlush = flushPromise;
-    if (this.context) {
+    if (this.context && typeof this.context.waitUntil === "function") {
       this.context.waitUntil(flushPromise);
+    } else if (typeof this.waitUntilFn === "function") {
+      this.waitUntilFn(flushPromise);
     }
     return flushPromise;
   }
@@ -85,26 +89,47 @@ class VedaTraceBatcher {
       try {
         await transport.send(logs);
       } catch (error) {
-        errors.push(error instanceof Error ? error : new Error(String(error)));
+        errors.push(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(", ")}`
-      );
-      if (this.config.onError) {
-        this.config.onError(combinedError);
-      } else {
-        console.error("[VedaTrace]", combinedError.message);
-      }
+    if (errors.length === 0 || errors.length < this.transports.length) {
+      this.config.onSuccess?.();
       return;
     }
-    if (this.config.onSuccess) {
-      this.config.onSuccess();
+    const fatalError = errors.find(transports_index.isFatal);
+    if (fatalError) {
+      this.halt(fatalError);
+      return;
+    }
+    if (errors.some(transports_index.isRetryable) && attempt < this.config.maxRetries) {
+      const backoff = this.config.retryDelay * (attempt + 1);
+      await this.delay(transports_index.retryAfterMs(errors) ?? backoff);
+      return this.sendWithRetry(logs, attempt + 1);
+    }
+    const detail = errors.map(describeError).join(", ");
+    this.reportError(
+      new Error(
+        errors.some(transports_index.isRetryable) ? `Failed to send ${logs.length} logs after ${this.config.maxRetries} retries: ${detail}` : `Failed to send ${logs.length} logs: ${detail}`
+      )
+    );
+  }
+  /** Stop accepting logs after an unrecoverable authentication failure. */
+  halt(error) {
+    this.halted = true;
+    this.queue = [];
+    this.stop();
+    this.reportError(
+      new Error(
+        `VedaTrace disabled: ${describeError(error)}. Check your API key and the key's allowed origins, then call logger.start() to resume.`
+      )
+    );
+  }
+  reportError(error) {
+    const normalized = error instanceof Error ? error : new Error(String(error));
+    if (this.config.onError) {
+      this.config.onError(normalized);
+    } else {
+      console.error("[VedaTrace]", normalized.message);
     }
   }
   startFlushTimer() {
@@ -113,22 +138,11 @@ class VedaTraceBatcher {
     }
     this.flushTimer = setInterval(() => {
       if (this.queue.length > 0) {
-        this.flush().catch((error) => {
-          if (this.config.onError) {
-            this.config.onError(
-              error instanceof Error ? error : new Error(String(error))
-            );
-          } else {
-            console.error(
-              "[VedaTrace] Flush error:",
-              error instanceof Error ? error.message : String(error)
-            );
-          }
-        });
+        this.flush().catch((error) => this.reportError(error));
       }
     }, this.config.flushInterval);
     if (this.config.unrefTimer === true) {
-      this.flushTimer.unref();
+      this.flushTimer.unref?.();
     }
   }
   stop() {
@@ -136,12 +150,10 @@ class VedaTraceBatcher {
       clearInterval(this.flushTimer);
       this.flushTimer = null;
     }
-    if (this.flushDebounceTimer) {
-      clearTimeout(this.flushDebounceTimer);
-      this.flushDebounceTimer = null;
-    }
+    this.flushQueued = false;
   }
   start() {
+    this.halted = false;
     if (!this.flushTimer && !this.immediateFlush) {
       this.startFlushTimer();
     }
@@ -152,10 +164,17 @@ class VedaTraceBatcher {
   getQueueSize() {
     return this.queue.length;
   }
+  /** True once an auth failure has shut the batcher down. */
+  isHalted() {
+    return this.halted;
+  }
   setExecutionContext(ctx) {
     this.context = ctx;
   }
 }
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 
 function detectRuntime() {
   if (typeof navigator !== "undefined" && navigator.userAgent === "Cloudflare-Workers") {
@@ -198,7 +217,8 @@ function isBrowser() {
   return detectRuntime() === "browser";
 }
 
-const SDK_VERSION = process.env.npm_package_version ?? "0.0.0";
+const SDK_VERSION = "0.3.1";
+
 class VedaTraceLogger {
   batcher = null;
   runtime;
@@ -351,24 +371,17 @@ class BrowserLifecycle {
     this.config = config;
     this.boundVisibilityHandler = this.handleVisibilityChange.bind(this);
     this.boundPageHideHandler = this.handlePageHide.bind(this);
-    this.boundBeforeUnloadHandler = this.handleBeforeUnload.bind(this);
-    this.boundUnloadHandler = this.handleUnload.bind(this);
   }
   boundVisibilityHandler;
   boundPageHideHandler;
-  boundBeforeUnloadHandler;
-  boundUnloadHandler;
   isAttached = false;
   pendingFlush = null;
   /** Start listening for browser lifecycle events */
   attach() {
     if (this.isAttached) return;
-    if (typeof document !== "undefined") {
-      document.addEventListener("visibilitychange", this.boundVisibilityHandler);
-      window.addEventListener("pagehide", this.boundPageHideHandler);
-      window.addEventListener("beforeunload", this.boundBeforeUnloadHandler);
-      window.addEventListener("unload", this.boundUnloadHandler);
-    }
+    if (typeof document === "undefined" || typeof window === "undefined") return;
+    document.addEventListener("visibilitychange", this.boundVisibilityHandler);
+    window.addEventListener("pagehide", this.boundPageHideHandler);
     this.isAttached = true;
     if (this.config.debug) {
       console.log("[VedaTrace] Browser lifecycle handlers attached");
@@ -377,21 +390,25 @@ class BrowserLifecycle {
   /** Stop listening for browser lifecycle events */
   detach() {
     if (!this.isAttached) return;
-    if (typeof document !== "undefined") {
+    if (typeof document !== "undefined" && typeof window !== "undefined") {
       document.removeEventListener(
         "visibilitychange",
         this.boundVisibilityHandler
       );
       window.removeEventListener("pagehide", this.boundPageHideHandler);
-      window.removeEventListener("beforeunload", this.boundBeforeUnloadHandler);
-      window.removeEventListener("unload", this.boundUnloadHandler);
     }
     this.isAttached = false;
     if (this.config.debug) {
       console.log("[VedaTrace] Browser lifecycle handlers detached");
     }
   }
-  /** Handle visibility change - flush when page becomes hidden */
+  /**
+   * Flush when the page becomes hidden.
+   *
+   * This is the one that actually matters: on mobile, a backgrounded tab is
+   * often discarded without ever firing pagehide, so "hidden" is the last
+   * reliable moment to ship what we have.
+   */
   handleVisibilityChange() {
     if (document.visibilityState === "hidden") {
       if (this.config.debug) {
@@ -400,7 +417,7 @@ class BrowserLifecycle {
       this.scheduleFlush();
     }
   }
-  /** Handle pagehide event - primary flush handler for Safari */
+  /** Final flush as the page is torn down or frozen into the bfcache. */
   handlePageHide(event) {
     if (this.config.debug) {
       console.log(
@@ -408,46 +425,16 @@ class BrowserLifecycle {
         event.persisted ? "(cached)" : "(navigation)"
       );
     }
-    if (event.persisted) {
-      this.scheduleFlush();
-    } else {
-      this.finalFlush();
-    }
-  }
-  /** Handle beforeunload - backup flush mechanism */
-  handleBeforeUnload(event) {
-    if (this.config.debug) {
-      console.log("[VedaTrace] Before unload event");
-    }
-    this.finalFlush();
-  }
-  /** Handle unload - fallback for older browsers */
-  handleUnload() {
-    if (this.config.debug) {
-      console.log("[VedaTrace] Unload event");
-    }
-    this.finalFlush();
+    this.scheduleFlush();
   }
-  /** Schedule a debounced flush (for visibility change) */
+  /** Flush at most once at a time; keepalive carries it past the document. */
   scheduleFlush() {
     if (this.pendingFlush) return;
-    this.pendingFlush = this.config.flush().finally(() => {
+    this.pendingFlush = this.config.flush().catch(() => {
+    }).finally(() => {
       this.pendingFlush = null;
     });
   }
-  /**
-   * Final flush using keepalive fetch
-   * For sending logs after the page context is destroyed
-   */
-  finalFlush() {
-    for (const transport of this.config.transports) {
-      if (transport.name === "http" && "flush" in transport) {
-        transport.flush?.();
-      }
-    }
-    this.config.flush().catch(() => {
-    });
-  }
   /** Check if handlers are attached */
   isActive() {
     return this.isAttached;
@@ -528,6 +515,16 @@ function redactPii(value, mask) {
   return result;
 }
 
+function resolveApiKey(config) {
+  if (config.apiKey) return config.apiKey;
+  try {
+    if (typeof process !== "undefined" && process.env) {
+      return process.env.VEDATRACE_API_KEY || void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
 const RUNTIME_FLUSH_INTERVALS = {
   node: 3e3,
   bun: 3e3,
@@ -538,15 +535,16 @@ const RUNTIME_FLUSH_INTERVALS = {
 };
 function vedatrace(config = {}) {
   const runtime = detectRuntime();
-  const logger = new VedaTraceLogger(config);
-  if (config.apiKey && (!config.transports || config.transports.length === 0)) {
+  const apiKey = resolveApiKey(config);
+  const logger = new VedaTraceLogger(apiKey ? { ...config, apiKey } : config);
+  if (apiKey && (!config.transports || config.transports.length === 0)) {
     const isBrowserEnv = isBrowser();
     const isServerlessEnv = isServerless();
     const isLongRunningEnv = isLongRunning();
     const HttpTransport = isBrowserEnv ? transports_index.VedaTraceHttpTransportBrowser : transports_index.VedaTraceHttpTransport;
     const httpConfig = {
-      apiKey: config.apiKey,
-      keepalive: isBrowserEnv
+      apiKey,
+      keepalive: isBrowserEnv || isServerlessEnv
     };
     if (config.endpoint) httpConfig.endpoint = config.endpoint;
     const httpTransport = new HttpTransport(httpConfig);
@@ -571,12 +569,15 @@ function vedatrace(config = {}) {
         unrefTimer: config.unrefTimer ?? shouldUnrefTimer,
         executionContext: config.executionContext,
         onError: config.onError,
-        onSuccess: config.onSuccess
+        onSuccess: config.onSuccess,
+        debug: config.debug,
+        waitUntil: config.waitUntil
       },
       immediateFlush
     );
     logger.setBatcher(batcher);
-    if (typeof process !== "undefined" && isLongRunningEnv) {
+    const isNodeRuntime = typeof process !== "undefined" && process.versions?.node;
+    if (typeof process !== "undefined" && (isLongRunningEnv || isNodeRuntime)) {
       const flushLogs = async () => {
         await batcher.flush();
       };
@@ -612,7 +613,9 @@ function devVedatrace(config = {}) {
 exports.VedaTraceConsoleTransport = transports_index.VedaTraceConsoleTransport;
 exports.VedaTraceHttpTransport = transports_index.VedaTraceHttpTransport;
 exports.VedaTraceHttpTransportBrowser = transports_index.VedaTraceHttpTransportBrowser;
+exports.VedaTraceTransportError = transports_index.VedaTraceTransportError;
 exports.BrowserLifecycle = BrowserLifecycle;
+exports.SDK_VERSION = SDK_VERSION;
 exports.VedaTraceBatcher = VedaTraceBatcher;
 exports.VedaTraceLogger = VedaTraceLogger;
 exports.default = vedatrace;

package/dist/index.d.cts

@@ -1,17 +1,14 @@
-import { b as VedaTraceTransport, B as BatcherConfig, c as VedaTraceEdgeContext, I as InternalLogEntry, V as VedaTraceLoggerInterface, R as RuntimeType$1, a as VedaTraceConfig, L as LogMetadata, d as RedactionConfig } from './types-BU0UESs9.cjs';
-export { e as VedaTraceLevel, f as VedaTraceLog } from './types-BU0UESs9.cjs';
+import { b as VedaTraceTransport, B as BatcherConfig, c as VedaTraceEdgeContext, I as InternalLogEntry, V as VedaTraceLoggerInterface, R as RuntimeType$1, a as VedaTraceConfig, L as LogMetadata, d as RedactionConfig } from './types-CSBzeGyK.cjs';
+export { e as VedaTraceLevel, f as VedaTraceLog } from './types-CSBzeGyK.cjs';
 export { ConsoleFormat, ConsoleTransportConfig, HttpTransportConfig, VedaTraceConsoleTransport, VedaTraceHttpTransport, VedaTraceHttpTransportBrowser } from './transports/index.cjs';
 
 /**
  * VedaTrace Batcher - Context-Aware for Cloudflare Workers
  *
- * Key features:
- * 1. Stores EdgeContext for waitUntil() integration
- * 2. setContext() method for post-initialization context attachment
- * 3. Fire-and-forget flush wrapped in ctx.waitUntil() when context is available
- * 4. Debounced flush to avoid excessive network calls
- * 5. Automatic flush on each log entry when context is present
- * 6. All callbacks moved into BatcherConfig for cleaner API
+ * Three flush modes:
+ * 1. Reliable mode (context or waitUntilFn): debounced flush + waitUntil for guaranteed delivery
+ * 2. Immediate mode: flush() called directly from add() during handler execution
+ * 3. Batch mode: periodic/batch-size flush for long-running environments
  */
 
 declare class VedaTraceBatcher {
@@ -20,30 +17,63 @@ declare class VedaTraceBatcher {
     private immediateFlush;
     private queue;
     private flushTimer;
-    private flushDebounceTimer;
+    private flushQueued;
     private isFlushing;
     private pendingFlush;
     private context;
+    private waitUntilFn;
+    /**
+     * Set when the ingestion endpoint rejects our credentials. Every subsequent
+     * batch would fail identically, so we stop rather than spend a request (and a
+     * retry storm) per flush for the life of the process. start() clears it.
+     */
+    private halted;
     constructor(transports: VedaTraceTransport[], config: BatcherConfig, immediateFlush?: boolean);
-    /** Attach execution context after initialization */
     setContext(ctx: VedaTraceEdgeContext): void;
-    /** Get current context */
     getContext(): VedaTraceEdgeContext | undefined;
-    /** Add log to queue with context-aware flush */
     add(log: InternalLogEntry): void;
-    /** Debounced flush - prevents rapid-fire flushes */
     private debouncedFlush;
-    /** Flush logs to all transports with waitUntil protection */
     flush(): Promise<void>;
     private sendWithRetry;
+    /** Stop accepting logs after an unrecoverable authentication failure. */
+    private halt;
+    private reportError;
     private startFlushTimer;
     stop(): void;
     start(): void;
     private delay;
     getQueueSize(): number;
+    /** True once an auth failure has shut the batcher down. */
+    isHalted(): boolean;
     setExecutionContext(ctx: VedaTraceEdgeContext): void;
 }
 
+/**
+ * Transport error types
+ *
+ * The batcher needs to tell three cases apart:
+ *   - retryable  (network blip, timeout, 429, 5xx) — back off and try again
+ *   - permanent  (400 malformed batch) — retrying wastes the caller's time
+ *   - fatal      (401/403 bad key or blocked origin) — every future batch will
+ *                fail the same way, so stop instead of burning a request per flush
+ */
+declare class VedaTraceTransportError extends Error {
+    readonly name = "VedaTraceTransportError";
+    readonly status: number | undefined;
+    readonly retryable: boolean;
+    readonly fatal: boolean;
+    /** Server-requested backoff from a `Retry-After` header, in milliseconds. */
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, options?: {
+        status?: number;
+        retryable?: boolean;
+        fatal?: boolean;
+        retryAfterMs?: number;
+    });
+    /** Build an error from an HTTP response status. */
+    static fromStatus(status: number, body: string, retryAfterMs?: number): VedaTraceTransportError;
+}
+
 /**
  * Core VedaTrace Logger implementation
  * Supports Cloudflare Workers / Pages via withContext() integration
@@ -80,12 +110,17 @@ declare class VedaTraceLogger implements VedaTraceLoggerInterface {
  * Browser lifecycle management for VedaTrace
  *
  * Handles:
- * - visibilitychange: flush when page becomes hidden
- * - pagehide: final flush when user leaves the page
- * - beforeunload: backup flush before page unload
+ * - visibilitychange: flush when the page becomes hidden
+ * - pagehide: final flush when the page goes away
  *
- * Uses fetch with keepalive: true for final flush to ensure
- * the request completes after the tab is closed.
+ * `beforeunload` and `unload` are deliberately not used. Registering either one
+ * makes Chrome and Safari ineligible for the back/forward cache, so a logging
+ * SDK that listens for them measurably slows down every back-navigation in the
+ * host app. `visibilitychange` + `pagehide` covers every case they did,
+ * including Safari, and is the pair the browsers themselves recommend.
+ *
+ * The final flush goes out through the batcher's normal HTTP transport, which
+ * sets `keepalive: true` in the browser so the request outlives the document.
  */
 
 interface BrowserLifecycleConfig {
@@ -101,8 +136,6 @@ declare class BrowserLifecycle {
     private config;
     private boundVisibilityHandler;
     private boundPageHideHandler;
-    private boundBeforeUnloadHandler;
-    private boundUnloadHandler;
     private isAttached;
     private pendingFlush;
     constructor(config: BrowserLifecycleConfig);
@@ -110,21 +143,18 @@ declare class BrowserLifecycle {
     attach(): void;
     /** Stop listening for browser lifecycle events */
     detach(): void;
-    /** Handle visibility change - flush when page becomes hidden */
+    /**
+     * Flush when the page becomes hidden.
+     *
+     * This is the one that actually matters: on mobile, a backgrounded tab is
+     * often discarded without ever firing pagehide, so "hidden" is the last
+     * reliable moment to ship what we have.
+     */
     private handleVisibilityChange;
-    /** Handle pagehide event - primary flush handler for Safari */
+    /** Final flush as the page is torn down or frozen into the bfcache. */
     private handlePageHide;
-    /** Handle beforeunload - backup flush mechanism */
-    private handleBeforeUnload;
-    /** Handle unload - fallback for older browsers */
-    private handleUnload;
-    /** Schedule a debounced flush (for visibility change) */
+    /** Flush at most once at a time; keepalive carries it past the document. */
     private scheduleFlush;
-    /**
-     * Final flush using keepalive fetch
-     * For sending logs after the page context is destroyed
-     */
-    private finalFlush;
     /** Check if handlers are attached */
     isActive(): boolean;
 }
@@ -149,6 +179,21 @@ declare function isServerless(): boolean;
 declare function isLongRunning(): boolean;
 declare function isBrowser(): boolean;
 
+/**
+ * SDK version, inlined at build time.
+ *
+ * This file is generated by `scripts/sync-version.mjs` from package.json and is
+ * checked in so type-checking and tests work without a build step. Do not edit
+ * it by hand — `bun run build` and `changeset version` both regenerate it, and
+ * a test asserts it matches package.json.
+ *
+ * It exists because the previous `process.env.npm_package_version` read was
+ * wrong twice over: npm only sets that variable for its own lifecycle scripts,
+ * so it was always undefined for consumers, and the bare `process` reference
+ * survived bundling and threw a ReferenceError in browsers.
+ */
+declare const SDK_VERSION = "0.3.1";
+
 /**
  * VedaTrace SDK - Universal JavaScript logging
  *
@@ -189,4 +234,4 @@ declare function vedatrace(config?: VedaTraceConfig): VedaTraceLoggerInterface;
  */
 declare function devVedatrace(config?: Omit<VedaTraceConfig, "apiKey" | "transports">): VedaTraceLoggerInterface;
 
-export { BatcherConfig, BrowserLifecycle, InternalLogEntry, LogMetadata, RedactionConfig, RuntimeType$1 as RuntimeType, VedaTraceBatcher, VedaTraceConfig, VedaTraceEdgeContext, VedaTraceLogger, VedaTraceLoggerInterface, VedaTraceTransport, vedatrace as default, detectRuntime, devVedatrace, isBrowser, isEdgeRuntime, isLongRunning, isServerless, redact, vedatrace };
+export { BatcherConfig, BrowserLifecycle, InternalLogEntry, LogMetadata, RedactionConfig, RuntimeType$1 as RuntimeType, SDK_VERSION, VedaTraceBatcher, VedaTraceConfig, VedaTraceEdgeContext, VedaTraceLogger, VedaTraceLoggerInterface, VedaTraceTransport, VedaTraceTransportError, vedatrace as default, detectRuntime, devVedatrace, isBrowser, isEdgeRuntime, isLongRunning, isServerless, redact, vedatrace };