@nexussdk/tracker

@nexussdk/tracker

Ultra-resilient, production-grade client crash ingestion and telemetry SDK with automated PII sanitization, Core Web Vitals, and pluggable transports (< 10KB gzipped).

Key Features

Core (all versions):

• Automated PII Scrubbing: Recursive sanitization of emails, JWT tokens, credit card numbers, passwords, and authorization headers before transmission.
• Deterministic Fingerprinting: Parses stack traces across V8, SpiderMonkey, and JSCore to generate consistent error group hashes.
• Client-Side Deduplication & Sampling: Sliding window deduplication prevents telemetry storms. Configurable sampling rate and session crash limits.
• Pluggable Transports: fetch (with keepalive and navigator.sendBeacon fallback), console, localStorage offline buffers, or custom callbacks.
• Zero-Dependency Web Vitals: LCP, CLS, FID, TTFB, INP, FCP, and long tasks via native PerformanceObserver.
• Framework-Agnostic Error Boundary: NexusGuardCore crash isolation for any JavaScript runtime.
• Built-in Local Dev Server: nexus-dev CLI for offline development with real-time SSE Web GUI.

Advanced Capabilities & Resilience (v0.0.8+ / v0.0.9):

• 🛡️ Error Storm Throttling: StormThrottler deduplicates mass identical error bursts using fingerprint-keyed rolling windows with LRU capacity bounding (MAX_BUCKETS = 200) to protect memory during traffic spikes.
• 🧹 Robust PII Masking: Automated recursive scrubbing of VN phone numbers (including . / - punctuation), emails, passwords, JWT tokens, and card numbers, plus data-nexus-mask element subtree redaction via Element.closest().
• 🔍 Cross-Engine Fingerprinting: Cross-platform stack trace parsing normalizing V8, SpiderMonkey, and Safari JSCore global code frames with djb2 hashing including column numbers.
• 👆 Rage Click & Dead Click Detection: InteractionSignalDetector catches user frustration (3+ clicks in 500ms) and broken UI (click with no DOM mutation in 750ms) using only MutationObserver.
• 🎬 LoAF Observer: LoafObserver uses Chrome 123+ Long Animation Frame API to automatically attribute jank to first-party vs third-party scripts (Facebook Pixel, GTM, etc.).
• 📦 Payload Compression: compressPayload uses native CompressionStream (gzip) to reduce large payloads by ~82% — adding zero bytes to your bundle.

Installation

pnpm add @nexussdk/tracker
# or
npm install @nexussdk/tracker

(If using React or Vue, install @nexussdk/sdk instead for built-in hooks and components).

Quickstart (Vanilla JS / TypeScript)

import { NexusTrackerClient, attachWebVitals, NexusGuardCore } from '@nexussdk/tracker';

// 1. Initialize client
const tracker = new NexusTrackerClient({
  apiKey: 'pk_live_your_api_key',
  environment: 'production',
  sampling: {
    rate: 1.0,           // 100% sampling
    dedupeWindow: 10000, // 10s deduplication window
    maxPerSession: 50,   // Crash-loop defense: cap at 50 errors per session
  },
  transport: 'fetch',
});

// 2. Attach Web Vitals observer
const detachVitals = attachWebVitals(tracker, {
  poorRatingOnly: true,
  captureAsEvents: false, // captured as breadcrumbs
});

// 3. Capture errors manually
try {
  executePayment();
} catch (err) {
  tracker.captureError(err, { orderId: 'ord_123' });
}

// 4. Capture informational/warning messages
tracker.captureMessage('High memory usage detected', 'warning', { heapMb: 420 });

// 5. Add custom breadcrumbs
tracker.addBreadcrumb({
  category: 'ui.click',
  message: 'User clicked checkout button',
  level: 'info',
});

Configuration Options (NexusTrackerOptions)

Sampling Configuration (SamplingConfig)

export interface SamplingConfig {
  /** Sampling rate: 0.0 (0%) to 1.0 (100%). Default: 1.0 */
  rate?: number;
  /** Deduplication sliding window in milliseconds. Default: 10000 */
  dedupeWindow?: number;
  /** Max unique error fingerprints captured per browser session. Default: 100 */
  maxPerSession?: number;
}

Universal Error Boundary (NexusGuardCore)

const guard = new NexusGuardCore({
  tracker,
  onError: (error, info) => {
    console.warn(`Protected crash [Ref: ${info.errorId}]:`, error);
  },
});

// Subscribe to state changes
const unsubscribe = guard.subscribe((info) => {
  if (info) {
    document.getElementById('root')!.innerHTML = `
      <div class="alert">
        <h2>App Crash Protected</h2>
        <p>Reference: ${info.errorId}</p>
        <button id="retry">Retry</button>
      </div>
    `;
    document.getElementById('retry')?.addEventListener('click', () => guard.recover());
  }
});

Local Dev Server (nexus-dev)

The tracker package includes an offline telemetry receiver and dashboard CLI:

# Start local ingestion server on port 4567
npx nexus-dev --port 4567
# or in monorepo
pnpm nexus-dev

• Web Dashboard: http://localhost:4567/
• Ingestion Endpoint: http://localhost:4567/api/v1/telemetry/errors
• SSE Stream: http://localhost:4567/sse

Framework Compatibility Matrix

@nexussdk/tracker has zero runtime dependencies and runs on any modern browser or Node.js backend:

License

MIT © Nexus Platform