@nexussdk/tracker 0.0.1

package/src/fingerprint.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Error fingerprinting and stack trace parsing utilities.
+ * Generates deterministic SHA-256-based fingerprints for error deduplication.
+ * @module @nexus/sdk-tracker/fingerprint
+ */
+
+import type { StackFrame } from '@nexussdk/contracts';
+
+/**
+ * Parses a JavaScript error stack string into structured StackFrame objects.
+ * Supports V8 (Chrome/Node), SpiderMonkey (Firefox), and JavaScriptCore (Safari) formats.
+ *
+ * @param stack - Raw stack trace string from an Error object.
+ * @returns Array of parsed {@link StackFrame} objects (innermost first).
+ *
+ * @example
+ * const frames = parseStackTrace(new TypeError('test').stack);
+ * // [{ functionName: 'processPayment', fileName: 'chunk.js', lineNumber: 1, columnNumber: 400 }]
+ */
+export function parseStackTrace(stack?: string): StackFrame[] {
+  if (!stack) return [];
+
+  const frames: StackFrame[] = [];
+  const lines = stack.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // V8 format: "    at FunctionName (file.js:line:col)"
+    // V8 anonymous: "    at file.js:line:col"
+    const v8Match =
+      trimmed.match(/^at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)$/) ||
+      trimmed.match(/^at\s+(.+?):(\d+):(\d+)$/) ||
+      trimmed.match(/^at\s+\((.+?):(\d+):(\d+)\)$/);
+
+    if (v8Match) {
+      if (v8Match.length === 5) {
+        // Named function
+        frames.push({
+          functionName: v8Match[1] ?? '<anonymous>',
+          fileName: v8Match[2] ?? '<unknown>',
+          lineNumber: parseInt(v8Match[3] ?? '0', 10),
+          columnNumber: parseInt(v8Match[4] ?? '0', 10),
+        });
+      } else if (v8Match.length === 4) {
+        // Anonymous or "at (file:line:col)"
+        frames.push({
+          functionName: '<anonymous>',
+          fileName: v8Match[1] ?? '<unknown>',
+          lineNumber: parseInt(v8Match[2] ?? '0', 10),
+          columnNumber: parseInt(v8Match[3] ?? '0', 10),
+        });
+      }
+      continue;
+    }
+
+    // Firefox/Safari format: "functionName@file.js:line:col"
+    const geckoMatch = trimmed.match(/^(.+?)@(.+?):(\d+):(\d+)$/);
+    if (geckoMatch) {
+      frames.push({
+        functionName: geckoMatch[1] ?? '<anonymous>',
+        fileName: geckoMatch[2] ?? '<unknown>',
+        lineNumber: parseInt(geckoMatch[3] ?? '0', 10),
+        columnNumber: parseInt(geckoMatch[4] ?? '0', 10),
+      });
+    }
+  }
+
+  return frames;
+}
+
+/**
+ * Computes a fast non-cryptographic fingerprint string for error deduplication.
+ * Uses a djb2-style hash over the signature components to avoid SubtleCrypto async API.
+ *
+ * Format: hash(errorType + ":" + errorMessage + ":" + topFileName + ":" + topLineNumber)
+ *
+ * @param errorType - JavaScript error type (e.g. "TypeError").
+ * @param errorMessage - Primary error message.
+ * @param topFrame - Innermost (first) stack frame, or undefined if stack is empty.
+ * @returns Hex-like fingerprint string for deduplication grouping.
+ *
+ * @example
+ * const fp = computeFingerprint(
+ *   'TypeError',
+ *   "Cannot read properties of undefined (reading 'map')",
+ *   { functionName: 'render', fileName: 'chunk.js', lineNumber: 1, columnNumber: 400 }
+ * );
+ * // 'fp_a3f9b2c1d4...'
+ */
+export function computeFingerprint(
+  errorType: string,
+  errorMessage: string,
+  topFrame?: StackFrame,
+): string {
+  const fileName = topFrame?.fileName ?? 'unknown';
+  const lineNumber = topFrame?.lineNumber ?? 0;
+  const signature = `${errorType}:${errorMessage}:${fileName}:${lineNumber}`;
+
+  // djb2 hash algorithm — fast, no async, no external deps
+  let hash = 5381;
+  for (let i = 0; i < signature.length; i++) {
+    hash = ((hash << 5) + hash + signature.charCodeAt(i)) >>> 0;
+  }
+
+  return `fp_${hash.toString(16).padStart(8, '0')}`;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Public export interface for @nexussdk/tracker.
+ * Re-exports the client, sanitizer, listeners, and all tracker contracts.
+ *
+ * @example
+ * import { NexusTrackerClient } from '@nexussdk/tracker';
+ * const tracker = new NexusTrackerClient({ apiKey: 'pk_live_...' });
+ */
+
+export { NexusTrackerClient } from './client.js';
+export type { NexusTrackerOptions, INexusTrackerClient } from './client.js';
+export { sanitizeObject, sanitizeUrl } from './sanitizer.js';
+export { computeFingerprint, parseStackTrace } from './fingerprint.js';
+export { BreadcrumbManager } from './breadcrumbs.js';
+export { Transport } from './transport.js';
+export type { TransportOptions } from './transport.js';

package/src/listeners.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Global error and unhandled rejection listeners.
+ * Attaches window-level hooks without interfering with native browser behavior.
+ * @module @nexus/sdk-tracker/listeners
+ */
+
+import type { NexusTrackerClient } from './client.js';
+
+/**
+ * Attaches global error event listeners to the browser window.
+ * Captures:
+ * - `window.onerror` — synchronous uncaught exceptions
+ * - `window.onunhandledrejection` — unhandled Promise rejections
+ *
+ * CRITICAL: Neither handler calls `event.preventDefault()`.
+ * Native browser behavior (console.error, DevTools display) is preserved.
+ *
+ * @param client - The NexusTrackerClient instance to forward errors to.
+ * @returns Cleanup function that removes all attached listeners.
+ *
+ * @example
+ * const cleanup = attachGlobalListeners(trackerClient);
+ * // On SDK destroy:
+ * cleanup();
+ */
+export function attachGlobalListeners(client: NexusTrackerClient): () => void {
+  if (typeof window === 'undefined') {
+    return () => void 0; // No-op in SSR contexts
+  }
+
+  const errorHandler = (event: ErrorEvent): void => {
+    // Do NOT call event.preventDefault() — preserve native browser behavior
+    const error = event.error instanceof Error ? event.error : new Error(event.message);
+    client.captureError(error);
+  };
+
+  const rejectionHandler = (event: PromiseRejectionEvent): void => {
+    // Do NOT call event.preventDefault()
+    client.captureError(event.reason);
+  };
+
+  window.addEventListener('error', errorHandler);
+  window.addEventListener('unhandledrejection', rejectionHandler);
+
+  return () => {
+    window.removeEventListener('error', errorHandler);
+    window.removeEventListener('unhandledrejection', rejectionHandler);
+  };
+}

package/src/sanitizer.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview PII sanitization engine for safe error payload transmission.
+ * Recursively redacts sensitive fields before any data leaves the client device.
+ * @module @nexus/sdk-tracker/sanitizer
+ */
+
+/** Maximum object recursion depth to prevent stack overflows on deep structures. */
+const MAX_DEPTH = 5;
+
+/**
+ * Regex matching sensitive key names that should be redacted.
+ * Matches exact key names (case-insensitive) for password, token, secret, etc.
+ */
+const SENSITIVE_KEY_PATTERN =
+  /^(password|passwd|token|secret|authorization|bearer|auth|credit_?card|cvv|cvc|ssn|api_?key|access_?token|refresh_?token)$/i;
+
+/**
+ * Regex matching credit card number patterns (13-16 digit sequences).
+ * Covers common formats with spaces or dashes between groups.
+ */
+const CREDIT_CARD_PATTERN = /\b(?:\d[ -]*?){13,16}\b/g;
+
+/**
+ * Regex matching email addresses in string values.
+ * Only the domain portion is retained for limited diagnostic context.
+ */
+const EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+
+/**
+ * Regex matching URL query parameters containing sensitive tokens.
+ * Strips values for: token, auth, key, secret, password, api_key.
+ */
+const SENSITIVE_QUERY_PARAM_PATTERN =
+  /([?&](token|auth|key|secret|password|api_key|access_token|refresh_token)=)[^&]*/gi;
+
+/**
+ * Sanitizes a string value by removing credit card numbers and email addresses.
+ *
+ * @param value - The string to sanitize.
+ * @returns Sanitized string with sensitive patterns replaced.
+ */
+function sanitizeString(value: string): string {
+  return value
+    .replace(CREDIT_CARD_PATTERN, '[CARD_REDACTED]')
+    .replace(EMAIL_PATTERN, '[EMAIL_REDACTED]')
+    .replace(SENSITIVE_QUERY_PARAM_PATTERN, '$1[REDACTED]');
+}
+
+/**
+ * Recursively sanitizes an object, redacting sensitive key-value pairs.
+ * Handles nested objects, arrays, and string values.
+ *
+ * @param value - The value to sanitize (any type).
+ * @param depth - Current recursion depth (internal, starts at 0).
+ * @returns A sanitized deep copy of the input.
+ *
+ * @example
+ * const payload = {
+ *   user: { email: 'john@example.com', password: 'secret123' },
+ *   token: 'Bearer abc123',
+ *   creditCard: '4111 1111 1111 1111',
+ * };
+ * const safe = sanitizeObject(payload);
+ * // { user: { email: '[EMAIL_REDACTED]', password: '[REDACTED]' },
+ * //   token: '[REDACTED]', creditCard: '[REDACTED]' }
+ */
+export function sanitizeObject(value: unknown, depth = 0): unknown {
+  if (depth > MAX_DEPTH) return '[MaxDepthExceeded]';
+
+  if (value === null || value === undefined) return value;
+
+  if (typeof value === 'string') {
+    return sanitizeString(value);
+  }
+
+  if (typeof value !== 'object') {
+    return value; // number, boolean, etc.
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeObject(item, depth + 1));
+  }
+
+  const sanitized: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+    if (SENSITIVE_KEY_PATTERN.test(key)) {
+      sanitized[key] = '[REDACTED]';
+    } else {
+      sanitized[key] = sanitizeObject(val, depth + 1);
+    }
+  }
+  return sanitized;
+}
+
+/**
+ * Sanitizes a URL by stripping sensitive query parameters.
+ *
+ * @param url - URL string to sanitize.
+ * @returns URL with sensitive query values replaced with [REDACTED].
+ *
+ * @example
+ * sanitizeUrl('https://app.com/auth?token=abc123&redirect=/home');
+ * // 'https://app.com/auth?token=[REDACTED]&redirect=/home'
+ */
+export function sanitizeUrl(url: string): string {
+  return url.replace(SENSITIVE_QUERY_PARAM_PATTERN, '$1[REDACTED]');
+}

package/src/transport.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Hybrid transport dispatcher for error payload delivery.
+ * Prefers fetch with keepalive; falls back to navigator.sendBeacon during page unload.
+ * @module @nexus/sdk-tracker/transport
+ */
+
+import type { ErrorEventPayload } from '@nexussdk/contracts';
+import { safeStringify, computeBackoffMs } from '@nexussdk/core';
+
+/**
+ * Options for configuring the transport dispatcher.
+ */
+export interface TransportOptions {
+  /** Go-Gin ingestion endpoint URL. */
+  endpoint: string;
+  /** Public API key for Authorization header. */
+  apiKey: string;
+  /** Maximum retry attempts on network failures. Defaults to 2. */
+  maxRetries?: number;
+}
+
+/**
+ * Hybrid transport dispatcher that intelligently selects the delivery mechanism:
+ * - **Normal execution**: `fetch(url, { keepalive: true })` with retry
+ * - **Page teardown** (`visibilityState === 'hidden'` or `pagehide`): `navigator.sendBeacon`
+ *
+ * @example
+ * const transport = new Transport({
+ *   endpoint: 'http://localhost:8080/api/v1/telemetry/errors',
+ *   apiKey: 'pk_live_...',
+ * });
+ * transport.send(errorPayload);
+ */
+export class Transport {
+  private readonly options: TransportOptions;
+  private readonly maxRetries: number;
+  private isPageHiding = false;
+
+  constructor(options: TransportOptions) {
+    this.options = options;
+    this.maxRetries = options.maxRetries ?? 2;
+
+    // Detect page teardown events to switch to sendBeacon
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+          this.isPageHiding = true;
+        }
+      });
+    }
+    if (typeof window !== 'undefined') {
+      window.addEventListener('pagehide', () => {
+        this.isPageHiding = true;
+      });
+    }
+  }
+
+  /**
+   * Dispatches an error payload to the Go-Gin ingestion endpoint.
+   * Automatically selects fetch or sendBeacon based on page lifecycle state.
+   *
+   * @param payload - The sanitized {@link ErrorEventPayload} to transmit.
+   *
+   * @example
+   * transport.send({
+   *   fingerprint: 'fp_abc123',
+   *   errorType: 'TypeError',
+   *   errorMessage: "Cannot read property 'map' of undefined",
+   *   // ...
+   * });
+   */
+  send(payload: ErrorEventPayload): void {
+    const body = safeStringify(payload);
+
+    // Use sendBeacon during page teardown — prevents cancelled fetch requests
+    if (
+      this.isPageHiding &&
+      typeof navigator !== 'undefined' &&
+      typeof navigator.sendBeacon === 'function'
+    ) {
+      const blob = new Blob([body], { type: 'application/json' });
+      navigator.sendBeacon(this.options.endpoint, blob);
+      return;
+    }
+
+    // Normal execution: fetch with keepalive and exponential backoff retry
+    void this.sendWithRetry(body, 0);
+  }
+
+  /**
+   * Forces immediate flush of all pending events using sendBeacon.
+   * Called during manual flush or SDK destroy lifecycle.
+   *
+   * @param payload - The error payload to flush.
+   * @returns Promise that resolves when the beacon is dispatched.
+   */
+  async flush(payload: ErrorEventPayload): Promise<void> {
+    const body = safeStringify(payload);
+    if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+      const blob = new Blob([body], { type: 'application/json' });
+      navigator.sendBeacon(this.options.endpoint, blob);
+      return;
+    }
+    await this.sendWithRetry(body, 0);
+  }
+
+  private async sendWithRetry(body: string, attempt: number): Promise<void> {
+    try {
+      const response = await fetch(this.options.endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.options.apiKey}`,
+        },
+        body,
+        keepalive: true,
+      });
+
+      if (response.ok) return;
+
+      // Retry on 5xx
+      if (response.status >= 500 && attempt < this.maxRetries) {
+        const delay = computeBackoffMs(attempt, 1000, 30_000);
+        await new Promise((r) => setTimeout(r, delay));
+        await this.sendWithRetry(body, attempt + 1);
+      }
+    } catch {
+      // Network failure — retry with backoff
+      if (attempt < this.maxRetries) {
+        const delay = computeBackoffMs(attempt, 1000, 30_000);
+        await new Promise((r) => setTimeout(r, delay));
+        await this.sendWithRetry(body, attempt + 1);
+      }
+      // All retries exhausted — silently drop to prevent host app instability
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs', 'iife'],
+  globalName: 'NexusTracker',
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  minify: true,
+  treeshake: true,
+  target: 'es2022',
+  outExtension({ format }) {
+    return {
+      js: format === 'esm' ? '.mjs' : format === 'cjs' ? '.cjs' : '.global.js',
+    };
+  },
+});