vantmetry 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vantmetry
+
+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

@@ -1,3 +1,25 @@
-# Vantmetry
+# vantmetry
 
-High-performance, self-hosted frontend error logger.
+Lightweight browser error tracking. Captures JavaScript errors, console errors, and unhandled promise rejections with zero blocking of the main thread.
+
+## Install
+
+```bash
+npm i vantmetry
+```
+
+Or use the CDN script tag — see [vantmetry.com/docs](https://vantmetry.com/docs).
+
+## Quick start
+
+```ts
+import { init } from 'vantmetry';
+
+init({ publicKey: 'vpk_your_key' });
+```
+
+That's it. Errors are auto-captured from that point on. See [vantmetry.com/docs](https://vantmetry.com/docs) for full configuration, React/Next.js integrations, manual logging, and PII masking details.
+
+## Source
+
+The full TypeScript source is in the `src/` directory of this package and on [GitHub](https://github.com/vantmetry/tracker).

package/core/init.d.ts

@@ -0,0 +1,2 @@
+import { VantmetryConfig } from './types';
+export declare function init(config: VantmetryConfig): void;

package/core/listeners.d.ts

@@ -0,0 +1,2 @@
+import { VantmetryTracker } from './tracker';
+export declare function initGlobalListeners(tracker: VantmetryTracker): void;

package/core/privacy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Masks sensitive patterns in a string.
+ */
+export declare function maskPII(input: string): string;
+/**
+ * Deeply masks PII in an object or array.
+ * Handles sensitive keys by fully redacting their values.
+ */
+export declare function maskObjectPII<T>(obj: T, seen?: WeakSet<object>): T;

package/core/singleton.d.ts

@@ -0,0 +1,4 @@
+import { VantmetryTracker } from './tracker';
+export declare function setInstance(tracker: VantmetryTracker): void;
+export declare function getInstance(): VantmetryTracker;
+export declare function isInitialized(): boolean;

package/core/tracker.d.ts

@@ -0,0 +1,21 @@
+import { LogPayload, VantmetryInstance, LogDetails, VantmetryConfig } from './types';
+export declare class VantmetryTracker implements VantmetryInstance {
+    private buffer;
+    private flushTimer;
+    private transport;
+    isReady: boolean;
+    private sentErrors;
+    private eventsThisSecond;
+    private lastResetTime;
+    private readonly TTL_MS;
+    private readonly MAX_EVENTS_PER_SEC;
+    constructor(config: VantmetryConfig);
+    error(message: string | unknown, details?: LogDetails): void;
+    warn(message: string, details?: LogDetails): void;
+    info(message: string, details?: LogDetails): void;
+    debug(message: string, details?: LogDetails): void;
+    flush(): Promise<void>;
+    private addToBuffer;
+    captureAutoError(payload: LogPayload): void;
+    private getSignature;
+}

package/core/transport.d.ts

@@ -0,0 +1,10 @@
+import { VantmetryConfig } from './types';
+export declare class TransportManager {
+    private wtSession;
+    private readonly endpoint;
+    private readonly wtEndpoint;
+    private readonly debug;
+    constructor(config: VantmetryConfig);
+    private initWT;
+    send(payload: string): Promise<void>;
+}

package/core/types.d.ts

@@ -0,0 +1,41 @@
+export declare const LogLevel: {
+    readonly ERROR: "ERROR";
+    readonly INFO: "INFO";
+    readonly WARN: "WARN";
+    readonly DEBUG: "DEBUG";
+};
+export type VantmetryLogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+export type LogDetails = Record<string, unknown>;
+export interface VantmetryInstance {
+    isReady: boolean;
+    error: (message: string | unknown, details?: LogDetails) => void;
+    warn: (message: string, details?: LogDetails) => void;
+    info: (message: string, details?: LogDetails) => void;
+    debug: (message: string, details?: LogDetails) => void;
+    flush: () => Promise<void>;
+}
+declare global {
+    interface Window {
+        Vantmetry?: VantmetryInstance;
+        onVantmetryReady?: (instance: VantmetryInstance) => void;
+    }
+}
+export interface LogPayload {
+    message: string | Event | unknown;
+    severity: VantmetryLogLevel;
+    type?: string;
+    stack?: string;
+    loc?: string;
+    trace_id?: string;
+    details?: LogDetails;
+}
+export interface LogItem extends LogPayload {
+    count: number;
+    ts: number;
+    url: string;
+    ua: string;
+}
+export interface VantmetryConfig {
+    publicKey: string;
+    ingestorUrl?: string;
+}

package/index.d.ts

@@ -0,0 +1,6 @@
+import { VantmetryInstance } from './core/types';
+export { init } from './core/init';
+export { VantmetryTracker } from './core/tracker';
+export { initGlobalListeners } from './core/listeners';
+export type { VantmetryConfig, LogDetails, VantmetryInstance, VantmetryLogLevel } from './core/types';
+export declare const logger: VantmetryInstance;

package/index.js

@@ -1 +1,28 @@
-module.exports = {};
+import { g as t } from "./init-DdlNmKDT.js";
+import { V as i, i as g, a as f } from "./init-DdlNmKDT.js";
+const n = {
+  get isReady() {
+    return t().isReady;
+  },
+  error(r, e) {
+    t().error(r, e);
+  },
+  warn(r, e) {
+    t().warn(r, e);
+  },
+  info(r, e) {
+    t().info(r, e);
+  },
+  debug(r, e) {
+    t().debug(r, e);
+  },
+  flush() {
+    return t().flush();
+  }
+};
+export {
+  i as VantmetryTracker,
+  g as init,
+  f as initGlobalListeners,
+  n as logger
+};

package/init-DdlNmKDT.js

@@ -0,0 +1,270 @@
+let f = null;
+function E(n) {
+  f = n;
+}
+function A() {
+  if (!f)
+    throw new Error("[Vantmetry] Not initialized. Call init() before using logger.");
+  return f;
+}
+function T() {
+  return f !== null;
+}
+const c = {
+  ERROR: "ERROR",
+  INFO: "INFO",
+  WARN: "WARN",
+  DEBUG: "DEBUG"
+}, b = "https://ingestor.vantmetry.com:4433";
+class S {
+  wtSession = null;
+  endpoint;
+  wtEndpoint;
+  debug;
+  constructor(e) {
+    const t = (e.ingestorUrl ?? b).replace(/\/$/, "");
+    this.endpoint = `${t}/api/ingestor/push/tcp?public_key=${e.publicKey}`, this.wtEndpoint = `${t}/api/ingestor/push/udp?public_key=${e.publicKey}`;
+    try {
+      this.debug = typeof window < "u" && !!window.localStorage?.getItem("vantmetry_debug");
+    } catch {
+      this.debug = !1;
+    }
+    this.initWT();
+  }
+  async initWT() {
+    if ("WebTransport" in window) {
+      await new Promise((e) => setTimeout(e, 200));
+      try {
+        this.wtSession = new WebTransport(this.wtEndpoint), await this.wtSession.ready, this.debug && console.log("WT: Connected");
+      } catch (e) {
+        this.debug && console.warn("WT: Failed, falling back to beacon", e), this.wtSession = null;
+      }
+    }
+  }
+  async send(e) {
+    if (this.wtSession)
+      try {
+        const s = (await this.wtSession.createUnidirectionalStream()).getWriter();
+        await s.write(new TextEncoder().encode(e)), await s.close();
+        return;
+      } catch (t) {
+        this.debug && console.warn("WT: Failed, falling back to beacon", t), this.wtSession = null;
+      }
+    if (typeof navigator < "u" && navigator.sendBeacon) {
+      const t = new Blob([e], { type: "application/json" });
+      if (navigator.sendBeacon(this.endpoint, t))
+        return;
+    }
+    fetch(this.endpoint, {
+      method: "POST",
+      body: e,
+      keepalive: !0,
+      headers: { "Content-Type": "application/json" }
+    }).catch((t) => {
+      this.debug && console.error("Vantmetry send failed", t);
+    });
+  }
+}
+const l = {
+  // Matches standard email formats
+  email: /\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\b/g,
+  // Matches standard CC groupings: 4-4-4-[3-4] with required separators, or Amex 4-6-5 format.
+  creditCard: /\b(?:\d{4}[-\s]){3}\d{3,4}\b|\b\d{4}[-\s]\d{6}[-\s]\d{5}\b/g,
+  // US Social Security Numbers (SSN): 3-2-4 format
+  ssn: /\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b/g,
+  // JWT Tokens (Header.Payload.Signature format starts with 'ey')
+  jwt: /\bey[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
+  // Generic secret detection (Bearer tokens, Basic auth, API keys)
+  authHeader: /\b(Bearer|Basic|Token)\s+[A-Za-z0-9\-._~+/=]+/gi
+}, p = /* @__PURE__ */ new Set([
+  "password",
+  "passwd",
+  "pwd",
+  "secret",
+  "token",
+  "authorization",
+  "api_key",
+  "apikey",
+  "access_token",
+  "refresh_token",
+  "session",
+  "cookie",
+  "credentials",
+  "client_secret",
+  "auth"
+]);
+function d(n) {
+  let e = n;
+  return e = e.replace(l.email, (t) => {
+    const s = t.split("@");
+    if (s.length !== 2)
+      return t;
+    const [r, a] = s;
+    return `${r.charAt(0)}***@${a}`;
+  }), e = e.replace(l.creditCard, (t) => {
+    const s = t.replace(/[-\s]/g, ""), r = s.slice(-4);
+    return "*".repeat(s.length - 4) + r;
+  }), e = e.replace(l.ssn, (t) => `***-**-${t.slice(-4)}`), e = e.replace(l.jwt, "[JWT REDACTED]"), e = e.replace(l.authHeader, "$1 [TOKEN REDACTED]"), e;
+}
+function h(n, e = /* @__PURE__ */ new WeakSet()) {
+  if (typeof n == "string")
+    return d(n);
+  if (!n || typeof n != "object")
+    return n;
+  if (e.has(n))
+    return "[Circular]";
+  if (e.add(n), Array.isArray(n))
+    return n.map((s) => h(s, e));
+  const t = {};
+  for (const [s, r] of Object.entries(n)) {
+    const a = s.toLowerCase();
+    if (p.has(a) || Array.from(p).some((i) => a.includes(i))) {
+      t[s] = "[REDACTED]";
+      continue;
+    }
+    typeof r == "string" ? t[s] = d(r) : typeof r == "object" && r !== null ? t[s] = h(r, e) : t[s] = r;
+  }
+  return t;
+}
+const R = 50, k = 2e3;
+class v {
+  buffer = [];
+  flushTimer = null;
+  transport;
+  isReady = !0;
+  // Deduplication & Circuit Breaker
+  sentErrors = /* @__PURE__ */ new Map();
+  eventsThisSecond = 0;
+  lastResetTime = Date.now();
+  TTL_MS = 6e4;
+  MAX_EVENTS_PER_SEC = 100;
+  constructor(e) {
+    this.transport = new S(e);
+  }
+  // --- Public API ---
+  error(e, t) {
+    this.addToBuffer({ severity: c.ERROR, type: "manual", message: e, details: t });
+  }
+  warn(e, t) {
+    this.addToBuffer({ severity: c.WARN, type: "manual", message: e, details: t });
+  }
+  info(e, t) {
+    this.addToBuffer({ severity: c.INFO, type: "manual", message: e, details: t });
+  }
+  debug(e, t) {
+    this.addToBuffer({ severity: c.DEBUG, type: "manual", message: e, details: t });
+  }
+  async flush() {
+    if (this.buffer.length === 0)
+      return;
+    const e = Date.now();
+    for (const s of this.buffer)
+      this.sentErrors.set(this.getSignature(s), e);
+    for (const [s, r] of this.sentErrors.entries())
+      e - r >= this.TTL_MS && this.sentErrors.delete(s);
+    const t = JSON.stringify(this.buffer);
+    this.buffer = [], this.flushTimer && (clearTimeout(this.flushTimer), this.flushTimer = null), await this.transport.send(t);
+  }
+  // --- Internal Logic ---
+  addToBuffer(e) {
+    if (!this.isReady)
+      return;
+    const t = Date.now();
+    if (t - this.lastResetTime > 1e3 && (this.eventsThisSecond = 0, this.lastResetTime = t), this.eventsThisSecond++, this.eventsThisSecond > this.MAX_EVENTS_PER_SEC) {
+      this.isReady = !1, console.error("[Vantmetry] Logging disabled to save browser CPU due to infinite loop detection.");
+      return;
+    }
+    const s = this.getSignature(e), r = this.sentErrors.get(s);
+    if (r && t - r < this.TTL_MS)
+      return;
+    const a = this.buffer.find((m) => this.getSignature(m) === s);
+    if (a) {
+      a.count = (a.count || 1) + 1;
+      return;
+    }
+    let { message: i, stack: o } = e;
+    const { details: u } = e;
+    i instanceof Error && (o = o ?? i.stack, i = i.message || String(i));
+    const g = typeof i == "string" ? d(i) : i, y = typeof u == "object" ? h(u) : u, w = typeof o == "string" ? d(o) : o;
+    this.buffer.push({
+      ...e,
+      message: g,
+      details: y,
+      stack: w,
+      count: 1,
+      ts: Date.now(),
+      url: window.location.href,
+      ua: navigator.userAgent
+    }), this.buffer.length >= R ? this.flush() : this.flushTimer || (this.flushTimer = setTimeout(() => {
+      this.flush();
+    }, k));
+  }
+  captureAutoError(e) {
+    this.addToBuffer(e);
+  }
+  getSignature(e) {
+    return `${e.type}:${e.severity}:${e.message}`;
+  }
+}
+function _(n) {
+  const e = console.error;
+  console.error = function(...t) {
+    if (e.apply(console, t), !n._isCapturingConsoleError) {
+      n._isCapturingConsoleError = !0;
+      try {
+        let s, r;
+        const a = t.findIndex((o) => o instanceof Error), i = t[a];
+        if (i) {
+          const o = t.slice(0, a).filter((u) => typeof u == "string").join(" ");
+          s = o ? `${o}: ${i.message || String(i)}` : i.message || String(i), r = i.stack;
+        } else
+          s = t.map((o) => {
+            if (typeof o == "string") return o;
+            try {
+              return JSON.stringify(o);
+            } catch {
+              return String(o);
+            }
+          }).join(" ");
+        n.captureAutoError({
+          type: "console.error",
+          message: s || "Unknown console.error",
+          stack: r,
+          severity: c.ERROR
+        });
+      } finally {
+        n._isCapturingConsoleError = !1;
+      }
+    }
+  }, window.addEventListener("error", function(t) {
+    n.captureAutoError({
+      type: "crash",
+      message: t.message || "Script error.",
+      stack: t.error?.stack,
+      loc: `${t.filename}:${t.lineno}:${t.colno}`,
+      severity: c.ERROR
+    });
+  }, { capture: !0 }), window.addEventListener("unhandledrejection", function(t) {
+    const s = t.reason, r = s instanceof Error;
+    n.captureAutoError({
+      type: "promise",
+      message: r ? s.message : String(s),
+      stack: r ? s.stack : new Error(`Unhandled rejection: ${String(s)}`).stack,
+      severity: c.ERROR
+    });
+  }, { capture: !0 }), document.addEventListener("visibilitychange", function() {
+    document.visibilityState === "hidden" && n.flush();
+  });
+}
+function C(n) {
+  if (T())
+    return;
+  const e = new v(n);
+  E(e), _(e);
+}
+export {
+  v as V,
+  _ as a,
+  A as g,
+  C as i
+};

package/next/index.d.ts

@@ -0,0 +1,11 @@
+import { VantmetryConfig } from '../index';
+/**
+ * Drop this into your Next.js layout or _document to load the tracker via CDN.
+ * Uses next/script so Next.js controls placement and loading strategy.
+ */
+export declare function VantmetryScript({ publicKey, ingestorUrl }: VantmetryConfig): import("react/jsx-runtime").JSX.Element;
+/**
+ * SSR-safe wrapper around init(). Use this in _app.tsx, app/layout.tsx client
+ * components, or anywhere module-level code may run on the server.
+ */
+export declare function initVantmetry(config: VantmetryConfig): void;

package/next/index.js

@@ -0,0 +1,21 @@
+import { jsx as i } from "react/jsx-runtime";
+import n from "next/script";
+import { i as e } from "../init-DdlNmKDT.js";
+function m({ publicKey: t, ingestorUrl: r }) {
+  return /* @__PURE__ */ i(
+    n,
+    {
+      strategy: "afterInteractive",
+      "data-public-key": t,
+      "data-ingestor-url": r,
+      src: "https://cdn.vantmetry.com/tracker.js"
+    }
+  );
+}
+function f(t) {
+  typeof window > "u" || e(t);
+}
+export {
+  m as VantmetryScript,
+  f as initVantmetry
+};

package/package.json

@@ -1,11 +1,64 @@
 {
   "name": "vantmetry",
-  "version": "0.0.1",
-  "description": "High-performance, self-hosted frontend error logger. Coming soon.",
-  "main": "index.js",
+  "version": "0.0.3",
+  "description": "Lightweight frontend error tracking with minimal browser impact.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    },
+    "./react": {
+      "import": "./react/index.js",
+      "types": "./react/index.d.ts"
+    },
+    "./next": {
+      "import": "./next/index.js",
+      "types": "./next/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "core",
+    "react",
+    "next",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
-    "error-logging"
+    "error-tracking",
+    "observability",
+    "frontend",
+    "browser",
+    "privacy"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vantmetry/tracker.git"
+  },
+  "homepage": "https://vantmetry.com",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "author": "Vantmetry Team",
-  "license": "MIT"
-}
+  "license": "MIT",
+  "dependencies": {},
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "next": ">=13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  }
+}

package/react/index.d.ts

@@ -0,0 +1,32 @@
+import { default as React, Component, ReactNode } from 'react';
+import { VantmetryConfig, VantmetryInstance } from '../index';
+interface VantmetryProviderProps extends VantmetryConfig {
+    children: ReactNode;
+}
+/**
+ * Initializes Vantmetry and makes the logger available via {@link useLogger}.
+ */
+export declare function VantmetryProvider({ publicKey, ingestorUrl, children }: VantmetryProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Returns the Vantmetry logger. Must be called inside a {@link VantmetryProvider}.
+ */
+export declare function useLogger(): VantmetryInstance;
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    /** Rendered when a render error is caught. Defaults to null (renders nothing). */
+    fallback?: ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+}
+/**
+ * Catches React render errors, logs them via Vantmetry, and renders the fallback.
+ * Place around any subtree you want to protect.
+ */
+export declare class VantmetryErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(_error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};

package/react/index.js

@@ -0,0 +1,37 @@
+import { jsx as s } from "react/jsx-runtime";
+import { createContext as i, Component as a, useEffect as u, useContext as c } from "react";
+import { logger as o } from "../index.js";
+import { i as m } from "../init-DdlNmKDT.js";
+const n = i(null);
+function h({ publicKey: t, ingestorUrl: r, children: e }) {
+  return u(() => {
+    m({ publicKey: t, ingestorUrl: r });
+  }, []), /* @__PURE__ */ s(n.Provider, { value: o, children: e });
+}
+function y() {
+  const t = c(n);
+  if (t === null)
+    throw new Error(
+      'useLogger() was called outside of VantmetryProvider. Wrap your app with <VantmetryProvider publicKey="..." /> to use this hook.'
+    );
+  return t;
+}
+class g extends a {
+  constructor(r) {
+    super(r), this.state = { hasError: !1 };
+  }
+  static getDerivedStateFromError(r) {
+    return { hasError: !0 };
+  }
+  componentDidCatch(r, e) {
+    o.error(r, { componentStack: e.componentStack ?? void 0 });
+  }
+  render() {
+    return this.state.hasError ? this.props.fallback ?? null : this.props.children;
+  }
+}
+export {
+  g as VantmetryErrorBoundary,
+  h as VantmetryProvider,
+  y as useLogger
+};

package/src/core/init.ts

@@ -0,0 +1,13 @@
+import { VantmetryTracker } from './tracker';
+import { initGlobalListeners } from './listeners';
+import { setInstance, isInitialized } from './singleton';
+import type { VantmetryConfig } from './types';
+
+export function init(config: VantmetryConfig): void {
+  if (isInitialized()) {
+    return;
+  }
+  const tracker = new VantmetryTracker(config);
+  setInstance(tracker);
+  initGlobalListeners(tracker);
+}

package/src/core/listeners.ts

@@ -0,0 +1,76 @@
+import { VantmetryTracker } from './tracker';
+import { LogLevel } from './types';
+
+export function initGlobalListeners(tracker: VantmetryTracker) {
+  const originalConsoleError = console.error;
+  console.error = function (...args: unknown[]) {
+    originalConsoleError.apply(console, args);
+
+    if ((tracker as unknown as Record<string, unknown>)['_isCapturingConsoleError']) return;
+    (tracker as unknown as Record<string, unknown>)['_isCapturingConsoleError'] = true;
+
+    try {
+      let message: string;
+      let stack: string | undefined;
+
+      const errorIndex = args.findIndex((arg) => arg instanceof Error);
+      const errorObj = args[errorIndex] as Error | undefined;
+      if (errorObj) {
+        const prefix = args
+          .slice(0, errorIndex)
+          .filter((a) => typeof a === 'string')
+          .join(' ');
+        message = prefix ? `${prefix}: ${errorObj.message || String(errorObj)}` : errorObj.message || String(errorObj);
+        stack = errorObj.stack;
+      } else {
+        message = args
+          .map((arg) => {
+            if (typeof arg === 'string') return arg;
+            try {
+              return JSON.stringify(arg);
+            } catch {
+              return String(arg);
+            }
+          })
+          .join(' ');
+      }
+
+      tracker.captureAutoError({
+        type: 'console.error',
+        message: message || 'Unknown console.error',
+        stack: stack,
+        severity: LogLevel.ERROR,
+      });
+    } finally {
+      (tracker as unknown as Record<string, unknown>)['_isCapturingConsoleError'] = false;
+    }
+  };
+
+  window.addEventListener('error', function (event: ErrorEvent) {
+    tracker.captureAutoError({
+      type: 'crash',
+      message: event.message || 'Script error.',
+      stack: event.error?.stack,
+      loc: `${event.filename}:${event.lineno}:${event.colno}`,
+      severity: LogLevel.ERROR,
+    });
+  }, { capture: true });
+
+  window.addEventListener('unhandledrejection', function (event: PromiseRejectionEvent) {
+    const reason = event.reason;
+    const isError = reason instanceof Error;
+    tracker.captureAutoError({
+      type: 'promise',
+      message: isError ? reason.message : String(reason),
+      stack: isError ? reason.stack : new Error(`Unhandled rejection: ${String(reason)}`).stack,
+      severity: LogLevel.ERROR,
+    });
+  }, { capture: true });
+
+  // Flush on page unload
+  document.addEventListener('visibilitychange', function () {
+    if (document.visibilityState === 'hidden') {
+      void tracker.flush();
+    }
+  });
+}

package/src/core/privacy.ts

@@ -0,0 +1,123 @@
+/**
+ * Regex collection for PII and credential masking.
+ */
+const PATTERNS = {
+  // Matches standard email formats
+  email: /\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\b/g,
+
+  // Matches standard CC groupings: 4-4-4-[3-4] with required separators, or Amex 4-6-5 format.
+  creditCard: /\b(?:\d{4}[-\s]){3}\d{3,4}\b|\b\d{4}[-\s]\d{6}[-\s]\d{5}\b/g,
+
+  // US Social Security Numbers (SSN): 3-2-4 format
+  ssn: /\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b/g,
+
+  // JWT Tokens (Header.Payload.Signature format starts with 'ey')
+  jwt: /\bey[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
+
+  // Generic secret detection (Bearer tokens, Basic auth, API keys)
+  authHeader: /\b(Bearer|Basic|Token)\s+[A-Za-z0-9\-._~+/=]+/gi,
+};
+
+// Keys that suggest the value is highly sensitive and should be completely redacted
+const SENSITIVE_KEYS = new Set([
+  'password',
+  'passwd',
+  'pwd',
+  'secret',
+  'token',
+  'authorization',
+  'api_key',
+  'apikey',
+  'access_token',
+  'refresh_token',
+  'session',
+  'cookie',
+  'credentials',
+  'client_secret',
+  'auth',
+]);
+
+/**
+ * Masks sensitive patterns in a string.
+ */
+export function maskPII(input: string): string {
+  let masked = input;
+
+  // Mask emails: user@example.com -> u***@example.com
+  masked = masked.replace(PATTERNS.email, (match) => {
+    const parts = match.split('@');
+    if (parts.length !== 2) {
+      return match;
+    }
+    const [user, domain] = parts;
+    const visibleUser = user.charAt(0);
+    return `${visibleUser}***@${domain}`;
+  });
+
+  // Mask credit cards: replaces all but the last 4 digits.
+  masked = masked.replace(PATTERNS.creditCard, (match) => {
+    const cleaned = match.replace(/[-\s]/g, '');
+    const last4 = cleaned.slice(-4);
+    return '*'.repeat(cleaned.length - 4) + last4;
+  });
+
+  // Mask SSNs: replaces first 5 digits -> ***-**-1234
+  masked = masked.replace(PATTERNS.ssn, (match) => {
+    const last4 = match.slice(-4);
+    return `***-**-${last4}`;
+  });
+
+  // Mask JWTs: eyJhb... -> [JWT REDACTED]
+  masked = masked.replace(PATTERNS.jwt, '[JWT REDACTED]');
+
+  // Mask Auth Headers
+  masked = masked.replace(PATTERNS.authHeader, '$1 [TOKEN REDACTED]');
+
+  return masked;
+}
+
+/**
+ * Deeply masks PII in an object or array.
+ * Handles sensitive keys by fully redacting their values.
+ */
+export function maskObjectPII<T>(obj: T, seen = new WeakSet()): T {
+  // Handle primitives and nulls
+  if (typeof obj === 'string') {
+    return maskPII(obj) as unknown as T;
+  }
+
+  if (!obj || typeof obj !== 'object') {
+    return obj;
+  }
+
+  // Prevent circular reference infinite loops
+  if (seen.has(obj as object)) {
+    return '[Circular]' as unknown as T;
+  }
+  seen.add(obj as object);
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => maskObjectPII(item, seen)) as unknown as T;
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const lowerKey = key.toLowerCase();
+
+    // Completely redact known sensitive keys
+    if (SENSITIVE_KEYS.has(lowerKey) || Array.from(SENSITIVE_KEYS).some((k) => lowerKey.includes(k))) {
+      result[key] = '[REDACTED]';
+      continue;
+    }
+
+    if (typeof value === 'string') {
+      result[key] = maskPII(value);
+    } else if (typeof value === 'object' && value !== null) {
+      result[key] = maskObjectPII(value, seen);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result as T;
+}

package/src/core/singleton.ts

@@ -0,0 +1,18 @@
+import type { VantmetryTracker } from './tracker';
+
+let instance: VantmetryTracker | null = null;
+
+export function setInstance(tracker: VantmetryTracker): void {
+  instance = tracker;
+}
+
+export function getInstance(): VantmetryTracker {
+  if (!instance) {
+    throw new Error('[Vantmetry] Not initialized. Call init() before using logger.');
+  }
+  return instance;
+}
+
+export function isInitialized(): boolean {
+  return instance !== null;
+}

package/src/core/tracker.ts

@@ -0,0 +1,146 @@
+import type { LogItem, LogPayload, VantmetryInstance, LogDetails, VantmetryConfig } from './types';
+import { LogLevel } from './types';
+import { TransportManager } from './transport';
+import { maskPII, maskObjectPII } from './privacy';
+
+const BATCH_LIMIT = 50;
+const FLUSH_INTERVAL = 2000;
+
+export class VantmetryTracker implements VantmetryInstance {
+  private buffer: Array<LogItem> = [];
+  private flushTimer: number | null = null;
+  private transport: TransportManager;
+  public isReady = true;
+
+  // Deduplication & Circuit Breaker
+  private sentErrors = new Map<string, number>();
+  private eventsThisSecond = 0;
+  private lastResetTime = Date.now();
+  private readonly TTL_MS = 60000;
+  private readonly MAX_EVENTS_PER_SEC = 100;
+
+  constructor(config: VantmetryConfig) {
+    this.transport = new TransportManager(config);
+  }
+
+  // --- Public API ---
+
+  public error(message: string | unknown, details?: LogDetails) {
+    this.addToBuffer({ severity: LogLevel.ERROR, type: 'manual', message, details });
+  }
+
+  public warn(message: string, details?: LogDetails) {
+    this.addToBuffer({ severity: LogLevel.WARN, type: 'manual', message, details });
+  }
+
+  public info(message: string, details?: LogDetails) {
+    this.addToBuffer({ severity: LogLevel.INFO, type: 'manual', message, details });
+  }
+
+  public debug(message: string, details?: LogDetails) {
+    this.addToBuffer({ severity: LogLevel.DEBUG, type: 'manual', message, details });
+  }
+
+  public async flush() {
+    if (this.buffer.length === 0) {
+      return;
+    }
+
+    const now = Date.now();
+    for (const item of this.buffer) {
+      this.sentErrors.set(this.getSignature(item), now);
+    }
+
+    // Clean up expired TTLs
+    for (const [key, timestamp] of this.sentErrors.entries()) {
+      if (now - timestamp >= this.TTL_MS) {
+        this.sentErrors.delete(key);
+      }
+    }
+
+    const dataPayload = JSON.stringify(this.buffer);
+    this.buffer = []; // Clear immediately
+
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    await this.transport.send(dataPayload);
+  }
+
+  // --- Internal Logic ---
+
+  private addToBuffer(payload: LogPayload) {
+    if (!this.isReady) {
+      return;
+    }
+
+    const now = Date.now();
+
+    // Emergency Circuit Breaker (Infinite Loop Protection)
+    if (now - this.lastResetTime > 1000) {
+      this.eventsThisSecond = 0;
+      this.lastResetTime = now;
+    }
+    this.eventsThisSecond++;
+
+    if (this.eventsThisSecond > this.MAX_EVENTS_PER_SEC) {
+      this.isReady = false;
+      console.error('[Vantmetry] Logging disabled to save browser CPU due to infinite loop detection.');
+      return;
+    }
+
+    const signature = this.getSignature(payload);
+
+    // Cross-flush Suppression
+    const lastSent = this.sentErrors.get(signature);
+    if (lastSent && now - lastSent < this.TTL_MS) {
+      return; // Silently drop exact duplicates within TTL
+    }
+
+    // Intra-buffer Deduplication
+    const existing = this.buffer.find((item) => this.getSignature(item) === signature);
+    if (existing) {
+      existing.count = (existing.count || 1) + 1;
+      return;
+    }
+
+    let { message, stack } = payload;
+    const { details } = payload;
+
+    if (message instanceof Error) {
+      stack = stack ?? message.stack;
+      message = message.message || String(message);
+    }
+
+    const maskedMessage = typeof message === 'string' ? maskPII(message) : message;
+    const maskedDetails = typeof details === 'object' ? maskObjectPII(details) : details;
+    const maskedStack = typeof stack === 'string' ? maskPII(stack) : stack;
+
+    this.buffer.push({
+      ...payload,
+      message: maskedMessage,
+      details: maskedDetails,
+      stack: maskedStack,
+      count: 1,
+      ts: Date.now(),
+      url: window.location.href,
+      ua: navigator.userAgent,
+    });
+
+    if (this.buffer.length >= BATCH_LIMIT) {
+      void this.flush();
+    } else if (!this.flushTimer) {
+      this.flushTimer = setTimeout(() => void this.flush(), FLUSH_INTERVAL) as unknown as number;
+    }
+  }
+
+  public captureAutoError(payload: LogPayload) {
+    this.addToBuffer(payload);
+  }
+
+  private getSignature(item: { type?: string; severity: string; message: unknown }): string {
+    return `${item.type}:${item.severity}:${item.message}`;
+  }
+}

package/src/core/transport.ts

@@ -0,0 +1,82 @@
+import type { VantmetryConfig } from './types';
+
+const DEFAULT_INGESTOR_URL = 'https://ingestor.vantmetry.com:4433';
+
+export class TransportManager {
+  private wtSession: WebTransport | null = null;
+  private readonly endpoint: string;
+  private readonly wtEndpoint: string;
+  private readonly debug: boolean;
+
+  constructor(config: VantmetryConfig) {
+    const base = (config.ingestorUrl ?? DEFAULT_INGESTOR_URL).replace(/\/$/, '');
+    this.endpoint = `${base}/api/ingestor/push/tcp?public_key=${config.publicKey}`;
+    this.wtEndpoint = `${base}/api/ingestor/push/udp?public_key=${config.publicKey}`;
+
+    try {
+      this.debug = typeof window !== 'undefined' && !!window.localStorage?.getItem('vantmetry_debug');
+    } catch {
+      this.debug = false;
+    }
+
+    void this.initWT();
+  }
+
+  private async initWT() {
+    if (!('WebTransport' in window)) {
+      return;
+    }
+
+    // Give browser a short moment to process Alt-Svc from previous visits
+    await new Promise((r) => setTimeout(r, 200));
+
+    // Now attempt WebTransport - browser should know to use HTTP/3
+    try {
+      this.wtSession = new WebTransport(this.wtEndpoint);
+      await this.wtSession.ready;
+      if (this.debug) {
+        console.log('WT: Connected');
+      }
+    } catch (err) {
+      if (this.debug) {
+        console.warn('WT: Failed, falling back to beacon', err);
+      }
+      this.wtSession = null;
+    }
+  }
+
+  public async send(payload: string): Promise<void> {
+    if (this.wtSession) {
+      try {
+        const stream = await this.wtSession.createUnidirectionalStream();
+        const writer = stream.getWriter();
+        await writer.write(new TextEncoder().encode(payload));
+        await writer.close();
+        return;
+      } catch (err) {
+        if (this.debug) {
+          console.warn('WT: Failed, falling back to beacon', err);
+        }
+        this.wtSession = null;
+      }
+    }
+
+    if (typeof navigator !== 'undefined' && navigator.sendBeacon) {
+      const blob = new Blob([payload], { type: 'application/json' });
+      if (navigator.sendBeacon(this.endpoint, blob)) {
+        return;
+      }
+    }
+
+    fetch(this.endpoint, {
+      method: 'POST',
+      body: payload,
+      keepalive: true,
+      headers: { 'Content-Type': 'application/json' },
+    }).catch((error) => {
+      if (this.debug) {
+        console.error('Vantmetry send failed', error);
+      }
+    });
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,47 @@
+export const LogLevel = {
+  ERROR: 'ERROR',
+  INFO: 'INFO',
+  WARN: 'WARN',
+  DEBUG: 'DEBUG',
+} as const;
+
+export type VantmetryLogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+export type LogDetails = Record<string, unknown>;
+
+export interface VantmetryInstance {
+  isReady: boolean;
+  error: (message: string | unknown, details?: LogDetails) => void;
+  warn: (message: string, details?: LogDetails) => void;
+  info: (message: string, details?: LogDetails) => void;
+  debug: (message: string, details?: LogDetails) => void;
+  flush: () => Promise<void>;
+}
+
+declare global {
+  interface Window {
+    Vantmetry?: VantmetryInstance;
+    onVantmetryReady?: (instance: VantmetryInstance) => void;
+  }
+}
+
+export interface LogPayload {
+  message: string | Event | unknown;
+  severity: VantmetryLogLevel;
+  type?: string;
+  stack?: string;
+  loc?: string;
+  trace_id?: string;
+  details?: LogDetails;
+}
+
+export interface LogItem extends LogPayload {
+  count: number;
+  ts: number;
+  url: string;
+  ua: string;
+}
+
+export interface VantmetryConfig {
+  publicKey: string;
+  ingestorUrl?: string;
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import { getInstance } from './core/singleton';
+import type { VantmetryInstance } from './core/types';
+
+export { init } from './core/init';
+export { VantmetryTracker } from './core/tracker';
+export { initGlobalListeners } from './core/listeners';
+export type { VantmetryConfig, LogDetails, VantmetryInstance, VantmetryLogLevel } from './core/types';
+
+export const logger: VantmetryInstance = {
+  get isReady() {
+    return getInstance().isReady;
+  },
+  error(message, details) {
+    getInstance().error(message, details);
+  },
+  warn(message, details) {
+    getInstance().warn(message, details);
+  },
+  info(message, details) {
+    getInstance().info(message, details);
+  },
+  debug(message, details) {
+    getInstance().debug(message, details);
+  },
+  flush() {
+    return getInstance().flush();
+  },
+};

package/src/next/index.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import Script from 'next/script';
+import { init, type VantmetryConfig } from '../index';
+
+/**
+ * Drop this into your Next.js layout or _document to load the tracker via CDN.
+ * Uses next/script so Next.js controls placement and loading strategy.
+ */
+export function VantmetryScript({ publicKey, ingestorUrl }: VantmetryConfig) {
+  return (
+    <Script
+      strategy="afterInteractive"
+      data-public-key={publicKey}
+      data-ingestor-url={ingestorUrl}
+      src="https://cdn.vantmetry.com/tracker.js"
+    />
+  );
+}
+
+/**
+ * SSR-safe wrapper around init(). Use this in _app.tsx, app/layout.tsx client
+ * components, or anywhere module-level code may run on the server.
+ */
+export function initVantmetry(config: VantmetryConfig): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+  init(config);
+}

package/src/next/next-script.d.ts

@@ -0,0 +1,16 @@
+declare module 'next/script' {
+  import type { FC } from 'react';
+
+  interface ScriptProps {
+    id?: string;
+    src?: string;
+    strategy?: 'beforeInteractive' | 'afterInteractive' | 'lazyOnload' | 'worker';
+    onLoad?: () => void;
+    onReady?: () => void;
+    onError?: (error: Error) => void;
+    [key: string]: unknown;
+  }
+
+  const Script: FC<ScriptProps>;
+  export default Script;
+}

package/src/react/index.tsx

@@ -0,0 +1,68 @@
+import React, { createContext, useContext, useEffect, Component, type ReactNode } from 'react';
+import { init, logger, type VantmetryConfig, type VantmetryInstance } from '../index';
+
+const VantmetryContext = createContext<VantmetryInstance | null>(null);
+
+interface VantmetryProviderProps extends VantmetryConfig {
+  children: ReactNode;
+}
+
+/**
+ * Initializes Vantmetry and makes the logger available via {@link useLogger}.
+ */
+export function VantmetryProvider({ publicKey, ingestorUrl, children }: VantmetryProviderProps) {
+  useEffect(() => {
+    init({ publicKey, ingestorUrl });
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return <VantmetryContext.Provider value={logger}>{children}</VantmetryContext.Provider>;
+}
+
+/**
+ * Returns the Vantmetry logger. Must be called inside a {@link VantmetryProvider}.
+ */
+export function useLogger(): VantmetryInstance {
+  const context = useContext(VantmetryContext);
+  if (context === null) {
+    throw new Error(
+      'useLogger() was called outside of VantmetryProvider. Wrap your app with <VantmetryProvider publicKey="..." /> to use this hook.',
+    );
+  }
+  return context;
+}
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  /** Rendered when a render error is caught. Defaults to null (renders nothing). */
+  fallback?: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+}
+
+/**
+ * Catches React render errors, logs them via Vantmetry, and renders the fallback.
+ * Place around any subtree you want to protect.
+ */
+export class VantmetryErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(_error: Error): ErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  override componentDidCatch(error: Error, info: React.ErrorInfo): void {
+    logger.error(error, { componentStack: info.componentStack ?? undefined });
+  }
+
+  override render(): ReactNode {
+    if (this.state.hasError) {
+      return this.props.fallback ?? null;
+    }
+    return this.props.children;
+  }
+}