@nexussdk/tracker 0.0.1 → 0.0.3

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]');
-}

package/src/transport.ts

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

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

package/tsup.config.ts

@@ -1,19 +0,0 @@
-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',
-    };
-  },
-});