@nexussdk/tracker 0.0.1 → 0.0.4

package/README.md

@@ -0,0 +1,170 @@
+# @nexussdk/tracker
+
+> Ultra-resilient, production-grade client crash ingestion and telemetry SDK with automated PII sanitization, Core Web Vitals, and pluggable transports (< 5KB gzipped).
+
+[![npm version](https://img.shields.io/npm/v/@nexussdk/tracker.svg)](https://www.npmjs.com/package/@nexussdk/tracker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Bundle Size](https://img.shields.io/badge/bundle_size-<5KB_gzipped-success.svg)](https://bundlephobia.com)
+
+---
+
+## Key Features
+
+- **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, deterministic error group hashes without async crypto overhead.
+- **Client-Side Deduplication & Sampling**: Sliding window deduplication prevents telemetry storms during rapid loops. Configurable sampling rate and session crash limits.
+- **Pluggable Transports**: Supports `fetch` (with keepalive and `navigator.sendBeacon` fallback during page unloads), `console` logging, `localStorage` offline buffers, or custom callback functions.
+- **Zero-Dependency Web Vitals**: Observes LCP, CLS, FID, TTFB, INP, FCP, and long tasks (>50ms) using the browser's native `PerformanceObserver` API.
+- **Framework-Agnostic Error Boundary Core**: `NexusGuardCore` provides crash isolation and recovery logic for any JavaScript runtime.
+- **Built-in Local Ingestion Server**: `nexus-dev` CLI offers an instant local HTTP ingestion server with real-time SSE Web GUI for offline development.
+
+---
+
+## Installation
+
+```bash
+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)
+
+```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`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `apiKey` | `string` | Env | Public API key (`pk_live_...`) |
+| `baseUrl` | `string` | Env | Ingestion endpoint URL (e.g. `https://telemetry.example.com`) |
+| `environment` | `string` | `'production'` | Target environment name |
+| `autoCapture` | `boolean` | `true` | Binds global `window.onerror` and `unhandledrejection` handlers |
+| `tags` | `Record<string, string>` | `{}` | Global static tags attached to every captured event |
+| `extra` | `Record<string, unknown>` | `{}` | Additional structured context attached to all events |
+| `sampling` | `SamplingConfig` | Default | Rate limiting and deduplication parameters |
+| `transport` | `TransportPlugin` | `'fetch'` | Delivery dispatcher: `'fetch'`, `'console'`, `'localStorage'`, or custom fn |
+| `maxBreadcrumbs` | `number` | `50` | In-memory ring buffer capacity for breadcrumbs |
+| `beforeSend` | `Function` | `undefined` | Hook to inspect, modify, or discard events prior to transmission |
+
+---
+
+## Sampling Configuration (`SamplingConfig`)
+
+```typescript
+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`)
+
+```typescript
+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:
+
+```bash
+# 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:
+
+| Framework / Runtime | Supported Versions | Mechanism | Documentation |
+| :--- | :--- | :--- | :--- |
+| **React / Next.js** | React 16.8 – 19 / Next.js 13 – 16 | `<NexusGuard>`, `useNexus`, Error Boundary | [React Error Boundary Guide](https://nexus.dev/sdk-tracker/react-error-boundary/) |
+| **Vue / Nuxt** | Vue 2.7 & 3.x / Nuxt 3 & 4 | `app.config.errorHandler`, `error.vue` | [Vue Error Tracking Guide](https://nexus.dev/sdk-tracker/frameworks/vue/) |
+| **Angular** | Angular 14 – 19+ / AngularJS | `ErrorHandler` provider, HTTP interceptors | [Angular Error Tracking Guide](https://nexus.dev/sdk-tracker/frameworks/angular/) |
+| **Svelte / SvelteKit** | Svelte 3 – 5 / SvelteKit 1 & 2 | `handleError` hooks, `+error.svelte` | [Svelte Error Tracking Guide](https://nexus.dev/sdk-tracker/frameworks/svelte/) |
+| **Node.js Backend** | Node.js 18, 20, 22 LTS | Express / Fastify error middleware | [Node.js Backend Guide](https://nexus.dev/sdk-tracker/frameworks/vanilla/) |
+
+---
+
+## License
+
+MIT © [Nexus Platform](https://github.com/Huynhdung295/NexusSDK)