@nexussdk/tracker 0.0.1 → 0.0.4

package/src/client.ts

@@ -1,289 +0,0 @@
-/**
- * @fileoverview NexusTrackerClient — Full-featured crash ingestion and telemetry SDK.
- * Automated global error capture, PII sanitization, deduplication, and hybrid transport.
- * @module @nexus/sdk-tracker/client
- */
-
-import type { Breadcrumb, DeviceContext, ErrorEventPayload, UserContext } from '@nexussdk/contracts';
-import { resolveApiKey, resolveBaseUrl } from '@nexussdk/core';
-import { sanitizeObject } from './sanitizer.js';
-import { computeFingerprint, parseStackTrace } from './fingerprint.js';
-import { BreadcrumbManager } from './breadcrumbs.js';
-import { Transport } from './transport.js';
-import { attachGlobalListeners } from './listeners.js';
-
-/**
- * Options for initializing the NexusTrackerClient.
- *
- * @example
- * const tracker = new NexusTrackerClient({
- *   apiKey: 'pk_live_...',
- *   environment: 'production',
- *   autoCapture: true,
- *   maxBreadcrumbs: 20,
- * });
- */
-export interface NexusTrackerOptions {
-  /**
-   * Public API Key ('pk_live_...' or 'pk_test_...').
-   * If omitted, resolved automatically via env variables.
-   */
-  apiKey?: string;
-  /**
-   * Centralized Go-Gin Ingestion URL. Defaults to 'https://api.nexus.dev'.
-   */
-  baseUrl?: string;
-  /**
-   * Target deployment environment ('production' | 'staging' | 'development').
-   */
-  environment?: string;
-  /**
-   * Max breadcrumbs retained in ring buffer. Defaults to 20 (max 50).
-   */
-  maxBreadcrumbs?: number;
-  /**
-   * Global tags attached to every captured telemetry event.
-   */
-  tags?: Record<string, string>;
-  /**
-   * Toggle automated capturing of uncaught exceptions. Defaults to true.
-   */
-  autoCapture?: boolean;
-  /**
-   * Callback hook to inspect, mutate, or drop an event before dispatch.
-   * Return null to drop the event completely.
-   */
-  beforeSend?: (event: ErrorEventPayload) => ErrorEventPayload | null;
-}
-
-/** Internal deduplication entry. */
-interface DedupeEntry {
-  timer: ReturnType<typeof setTimeout>;
-  count: number;
-  lastPayload: ErrorEventPayload;
-}
-
-/**
- * Public interface contract for NexusTrackerClient.
- */
-export interface INexusTrackerClient {
-  /**
-   * Manually captures an exception or custom error instance.
-   *
-   * @param error - Error object, string message, or unknown rejection value.
-   * @param extra - Optional custom metadata tags.
-   *
-   * @example
-   * tracker.captureError(new TypeError('Payment failed'), { checkoutStep: 'payment' });
-   */
-  captureError(error: unknown, extra?: Record<string, unknown>): void;
-
-  /**
-   * Records a user activity step into the chronological breadcrumb ring buffer.
-   *
-   * @param breadcrumb - Breadcrumb data without timestamp (auto-injected).
-   *
-   * @example
-   * tracker.addBreadcrumb({ category: 'navigation', message: 'Navigated to /checkout', level: 'info' });
-   */
-  addBreadcrumb(breadcrumb: Omit<Breadcrumb, 'timestamp'>): void;
-
-  /**
-   * Attaches end-user context to subsequent error payloads.
-   *
-   * @param user - User context or null to clear.
-   *
-   * @example
-   * tracker.setUser({ id: 'usr_12345', email: 'john@example.com' });
-   */
-  setUser(user: UserContext | null): void;
-
-  /**
-   * Dynamically sets or updates a persistent search tag.
-   *
-   * @param key - Tag key name.
-   * @param value - Tag value string.
-   *
-   * @example
-   * tracker.setTag('app_version', '2.4.1');
-   */
-  setTag(key: string, value: string): void;
-
-  /**
-   * Flushes any buffered events immediately via navigator.sendBeacon or fetch.
-   *
-   * @returns Promise that resolves when all events are dispatched.
-   *
-   * @example
-   * await tracker.flush();
-   */
-  flush(): Promise<void>;
-
-  /**
-   * Detaches global window listeners and clears in-memory ring buffers.
-   *
-   * @example
-   * tracker.destroy();
-   */
-  destroy(): void;
-}
-
-/**
- * NexusTrackerClient — resilient browser crash ingestion agent.
- *
- * @implements {INexusTrackerClient}
- *
- * @example
- * const tracker = new NexusTrackerClient({ apiKey: 'pk_live_...' });
- * tracker.captureError(new Error('Checkout failed'));
- */
-export class NexusTrackerClient implements INexusTrackerClient {
-  private readonly apiKey: string;
-  private readonly environment: string;
-  private readonly tags: Record<string, string>;
-  private readonly beforeSend?: (event: ErrorEventPayload) => ErrorEventPayload | null;
-  private readonly breadcrumbManager: BreadcrumbManager;
-  private readonly transport: Transport;
-  private userContext?: UserContext;
-  private readonly dedupeMap = new Map<string, DedupeEntry>();
-  private cleanupListeners?: () => void;
-
-  constructor(options: NexusTrackerOptions = {}) {
-    this.apiKey = resolveApiKey(options.apiKey);
-    const baseUrl = resolveBaseUrl(options.baseUrl);
-    this.environment = options.environment ?? 'production';
-    this.tags = { ...options.tags };
-    this.beforeSend = options.beforeSend;
-
-    this.breadcrumbManager = new BreadcrumbManager(Math.min(options.maxBreadcrumbs ?? 20, 50));
-    this.transport = new Transport({
-      endpoint: `${baseUrl}/api/v1/telemetry/errors`,
-      apiKey: this.apiKey,
-    });
-
-    if (options.autoCapture !== false && typeof window !== 'undefined') {
-      this.breadcrumbManager.attachListeners();
-      this.cleanupListeners = attachGlobalListeners(this);
-    }
-  }
-
-  /**
-   * Captures an error exception, generates fingerprint, scrubs PII, and enqueues transmission.
-   */
-  public captureError(error: unknown, extra?: Record<string, unknown>): void {
-    const normalized = this.normalizeError(error);
-    const stackFrames = parseStackTrace(normalized.stack);
-    const fingerprint = computeFingerprint(normalized.type, normalized.message, stackFrames[0]);
-
-    // Client-side 10-second sliding window deduplication
-    const existing = this.dedupeMap.get(fingerprint);
-    if (existing) {
-      existing.count += 1;
-      return;
-    }
-
-    const payload: ErrorEventPayload = {
-      fingerprint,
-      errorType: normalized.type,
-      errorMessage: normalized.message,
-      stackTrace: stackFrames,
-      breadcrumbs: this.breadcrumbManager.getAll(),
-      userContext: this.userContext,
-      deviceContext: this.getDeviceContext(),
-      tags: { environment: this.environment, ...this.tags, ...(extra as Record<string, string> | undefined) },
-      occurrenceCount: 1,
-      clientTimestamp: Date.now(),
-    };
-
-    // Apply PII sanitization before transmission
-    const sanitized = sanitizeObject(payload) as ErrorEventPayload;
-    const finalPayload = this.beforeSend ? this.beforeSend(sanitized) : sanitized;
-    if (!finalPayload) return;
-
-    this.transport.send(finalPayload);
-
-    // Track duplicate window — send aggregated event after 10 seconds
-    const timer = setTimeout(() => {
-      const entry = this.dedupeMap.get(fingerprint);
-      if (entry && entry.count > 1) {
-        const aggregated = { ...entry.lastPayload, occurrenceCount: entry.count, clientTimestamp: Date.now() };
-        this.transport.send(aggregated);
-      }
-      this.dedupeMap.delete(fingerprint);
-    }, 10_000);
-
-    this.dedupeMap.set(fingerprint, { timer, count: 1, lastPayload: finalPayload });
-  }
-
-  /**
-   * Records a contextual breadcrumb in the ring buffer.
-   */
-  public addBreadcrumb(breadcrumb: Omit<Breadcrumb, 'timestamp'>): void {
-    this.breadcrumbManager.push(breadcrumb);
-  }
-
-  /**
-   * Sets or clears the active user context for error telemetry.
-   */
-  public setUser(user: UserContext | null): void {
-    this.userContext = user ?? undefined;
-  }
-
-  /**
-   * Sets a custom tag associated with error events.
-   */
-  public setTag(key: string, value: string): void {
-    this.tags[key] = value;
-  }
-
-  /**
-   * Flushes all pending deduplication queues and dispatches queued payloads immediately.
-   */
-  public async flush(): Promise<void> {
-    // Flush all pending deduplication timers immediately
-    for (const [fingerprint, entry] of this.dedupeMap.entries()) {
-      clearTimeout(entry.timer);
-      if (entry.count > 0) {
-        const aggregated = { ...entry.lastPayload, occurrenceCount: entry.count, clientTimestamp: Date.now() };
-        await this.transport.flush(aggregated);
-      }
-      this.dedupeMap.delete(fingerprint);
-    }
-  }
-
-  /**
-   * Tears down global event listeners, flushes queues, and releases resources.
-   */
-  public destroy(): void {
-    this.cleanupListeners?.();
-    this.breadcrumbManager.detachListeners();
-    this.breadcrumbManager.clear();
-    this.dedupeMap.forEach((entry) => clearTimeout(entry.timer));
-    this.dedupeMap.clear();
-  }
-
-  private normalizeError(err: unknown): { type: string; message: string; stack?: string } {
-    if (err instanceof Error) {
-      return { type: err.name || 'Error', message: err.message, stack: err.stack };
-    }
-    if (typeof err === 'string') {
-      return { type: 'UnhandledException', message: err };
-    }
-    // Unknown rejection value (non-Error thrown)
-    return { type: 'NonErrorRejection', message: String(err) };
-  }
-
-  private getDeviceContext(): DeviceContext {
-    const isBrowser = typeof window !== 'undefined' && typeof navigator !== 'undefined';
-    return {
-      userAgent: isBrowser ? navigator.userAgent : 'Node/SSR',
-      currentUrl: isBrowser ? window.location.href : '',
-      viewport: isBrowser ? `${window.innerWidth}x${window.innerHeight}` : undefined,
-      timezone: Intl?.DateTimeFormat()?.resolvedOptions()?.timeZone,
-      networkStatus:
-        isBrowser && 'connection' in navigator
-          ? ((navigator as { connection?: { effectiveType?: string } }).connection?.effectiveType ?? 'unknown')
-          : undefined,
-    };
-  }
-}

package/src/fingerprint.ts

@@ -1,107 +0,0 @@
-/**
- * @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

@@ -1,16 +0,0 @@
-/**
- * @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

@@ -1,49 +0,0 @@
-/**
- * @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

@@ -1,107 +0,0 @@
-/**
- * @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]');
-}