@backtrack-js/browser 0.4.0

package/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2026 Matheus Moorete. All rights reserved.
+
+Permission is hereby granted to any person obtaining a copy of this software and associated documentation files (the "Software"), to inspect, run, and use the Software free of charge for evaluation and application integration, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+Redistribution, modification, sublicensing, or creating derivative works of the Software, in whole or in part, without the express written permission of the copyright holder is strictly prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# Backtrack (@backtrack-js/browser)
+
+[![npm version](https://img.shields.io/npm/v/@backtrack-js/browser.svg)](https://www.npmjs.com/package/@backtrack-js/browser)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Backtrack** is a privacy-first, client-side session recorder and time-travel engine for web applications. It captures pre-bug context (DOM mutations, console logs, network requests, navigation, and unhandled errors) in a rolling local ring-buffer, allowing developers to backtrack user sessions and reproduce bugs with exact fidelity.
+
+- 🔒 **Privacy-First:** Strict data masking (passwords, credit cards, inputs, authorization headers). No data leaves the browser unless explicitly exported.
+- ⚡ **Lightweight & Framework-Agnostic:** Pure TypeScript core. Zero framework dependencies (no React required in your client bundle).
+- 🔄 **Rolling Ring Buffer:** Continuously stores the last $N$ minutes of user activity in IndexedDB with automatic retention and storage limits.
+- 🎬 **Full Session Replay:** Powered by [rrweb](https://github.com/rrweb-io/rrweb) with synchronized timeline events.
+- 🛠 **Built-in Incident Viewer:** Includes an interactive web inspector and CLI to replay incidents offline.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @backtrack-js/browser
+
+# yarn
+yarn add @backtrack-js/browser
+
+# pnpm
+pnpm add @backtrack-js/browser
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { Backtrack } from '@backtrack-js/browser';
+
+// 1. Initialize Backtrack
+const recorder = new Backtrack({
+  bufferMinutes: 5,         // Keep last 5 minutes of activity in rolling buffer
+  afterErrorSeconds: 15,    // Keep recording for 15 seconds after an error occurs
+  maxStorageMb: 50,         // Retention target for rolling buffer (protected incidents are never auto-pruned)
+  captureHttpStatus: [500, 502, 503, 504], // Auto-trigger on server errors
+  network: {
+    capturePayloads: false, // Bodies are disabled by default for privacy
+    maxPayloadSize: 64 * 1024
+  },
+  privacy: {
+    maskAllInputs: true,    // Mask all form inputs by default
+    blockMedia: true        // Replace images/media with placeholders
+  }
+});
+
+// 2. Start recording
+await recorder.start();
+
+// 3. (Optional) Manually trigger an incident on user feedback or caught error
+const incidentId = await recorder.capture('User reported payment bug', 30);
+console.log('Incident captured:', incidentId);
+```
+
+---
+
+## Privacy & Data Masking
+
+Backtrack is designed with strict security defaults:
+
+- **Inputs & Forms:** All `<input>`, `<textarea>`, and `<select>` values are masked by default (`maskAllInputs: true`).
+- **Network Headers:** Authorization, Cookies, API keys, and Bearer tokens are automatically redacted.
+- **Sensitive Selectors:** Use standard selectors or CSS classes to protect proprietary or personal data:
+
+```typescript
+const recorder = new Backtrack({
+  privacy: {
+    maskAllInputs: true,
+    blockMedia: true,
+    blockSelector: '.backtrack-block, [data-private]',      // Completely hides elements in replay
+    maskTextSelector: '.backtrack-mask, .customer-pII',     // Scrambles text content
+    sanitizeUrl: (url) => {
+      // Remove sensitive query parameters
+      url.searchParams.delete('token');
+      return url.toString();
+    }
+  }
+});
+```
+
+---
+
+## Network & Payload Capture
+
+Network requests and responses can be configured using `network` options:
+
+```typescript
+const recorder = new Backtrack({
+  network: {
+    capturePayloads: false,
+    maxPayloadSize: 64 * 1024
+  }
+});
+```
+
+- **Bodies are not captured by default (`capturePayloads: false`):** Request and response bodies are disabled by default to prevent unintentional data leakage. HTTP method, URL, status, timing, and sanitized headers continue to be captured.
+- **Enabling bodies increases the risk of PII:** Enabling `capturePayloads: true` should be done mindfully according to your compliance and privacy requirements.
+- **Sanitization remains active:** Even when payload capture is explicitly enabled, Backtrack continues to sanitize and redact known sensitive keys (passwords, tokens, credentials, etc.) and patterns (Bearer tokens, emails, CPFs, cards).
+- **`maxPayloadSize` is a limit per payload, not per incident:** It bounds each individual request or response body (default is `64 * 1024` bytes). Payloads exceeding this limit are truncated safely with a truncation marker.
+
+---
+
+## Capturing Incidents
+
+### Automatic Triggers
+Backtrack automatically triggers and freezes an incident when:
+1. An unhandled window exception occurs (`window.onerror`).
+2. An unhandled promise rejection occurs (`unhandledrejection`).
+3. An HTTP request returns a matching error status (`captureHttpStatus`).
+
+### Manual Capture
+You can trigger incident recording manually anywhere in your code (e.g. from an error boundary or user feedback modal):
+
+```typescript
+// Capture the last 60 seconds of context
+const incidentId = await recorder.capture('Checkout error', 60);
+
+// Export the complete incident artifact as a JSON object
+const artifact = await recorder.exportIncident(incidentId);
+
+// Download or send artifact to your support/logging service
+const jsonBlob = new Blob([JSON.stringify(artifact, null, 2)], { type: 'application/json' });
+```
+
+### Exception Capture
+In React Error Boundaries or try/catch blocks:
+
+```typescript
+recorder.captureException(error, {
+  source: 'react',
+  componentStack: errorInfo.componentStack
+});
+```
+
+---
+
+## Remote Transport & beforeSend
+
+Backtrack allows applications to automatically dispatch finalized incidents to any remote endpoint or telemetry backend using `transport` and `beforeSend`:
+
+```typescript
+const recorder = new Backtrack({
+  transport: {
+    async send(artifact) {
+      const response = await fetch('/api/backtrack/incidents', {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json'
+        },
+        body: JSON.stringify(artifact)
+      });
+
+      if (!response.ok) {
+        throw new Error(`Upload failed: ${response.status}`);
+      }
+    }
+  },
+
+  beforeSend(artifact) {
+    if (artifact.environment.url.includes('/healthcheck')) {
+      return null;
+    }
+
+    return artifact;
+  }
+});
+```
+
+### Dispatch Flow & Semantics
+
+- **Sent Only When Finalized:** Incidents are dispatched only after they have been completely finalized and safely written to IndexedDB.
+  ```text
+  incidente finalizado
+          ↓
+    montar artefato
+          ↓
+      beforeSend
+          ↓
+  null? cancela envio
+          ↓
+    transport.send
+  ```
+- **Role of `beforeSend`:**
+  - Affects **only** the automated transmission via `transport.send`.
+  - Does **not** mutate the artifact stored in local IndexedDB.
+  - Does **not** affect `getArtifact()` or explicit file downloads via `exportIncident()`.
+  - Returning `null` cancels the upload.
+  - If `beforeSend` throws an error, the upload is aborted cleanly without affecting the application or the recorded incident.
+- **Fault Isolation:** Network or transport errors will never break the host application, reject user captures, delete local incidents, prevent finalization, or trigger unhandled promise rejections.
+- **Concurrency & Delivery Guarantees:**
+  - Each finalized incident triggers at most one upload attempt.
+  - Multiple incidents can upload concurrently.
+  - `stop()` does not wait for pending network uploads.
+  - There is currently no delivery guarantee (persistent retry queue, offline backoff, etc.); if transport fails, the incident remains saved in local IndexedDB and can be accessed or resent by the application.
+
+---
+
+## Release and trace correlation
+
+Backtrack artifacts (`formatVersion: 2`) provide an observability `context` to correlate client-side replays with backend traces, application releases, and environments.
+
+### Static Context
+
+Configure static metadata when initializing Backtrack:
+
+```typescript
+const recorder = new Backtrack({
+  context: {
+    release: 'checkout-web@2.14.0',
+    environment: 'production',
+    traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+    spanId: '00f067aa0ba902b7'
+  }
+});
+```
+
+### Dynamic Context (`getContext`)
+
+When trace IDs or active environments change dynamically during user navigation (e.g. from OpenTelemetry, Datadog, Sentry, or custom APM SDKs), use `getContext` to evaluate the latest context at incident export time:
+
+```typescript
+const recorder = new Backtrack({
+  context: {
+    release: 'checkout-web@2.14.0',
+    environment: 'production'
+  },
+  getContext: async () => {
+    const activeSpan = tracer.getActiveSpan();
+    const spanContext = activeSpan?.spanContext();
+
+    return {
+      release: 'checkout-web@2.14.0',
+      environment: 'production',
+      traceId: spanContext?.traceId,
+      spanId: spanContext?.spanId
+    };
+  }
+});
+```
+
+### Correlation Semantics
+
+- **Precedence:** `getContext() > context (static) > environment metadata`.
+- **Trace correlation scope:** Backtrack **only correlates** external trace and span identifiers supplied by your application. It does **not** generate backend traces, start trace spans, or perform distributed instrumentation on its own.
+- **Normalization:** `traceId` (32 hex characters) and `spanId` (16 hex characters) are validated and normalized to lowercase. A `spanId` cannot be supplied without an accompanying `traceId`.
+- **Fault Resilience:** If `getContext()` throws an error or rejects, incident export continues safely using available static context without failing the export or losing incident data.
+
+---
+
+## Inspecting Incidents (Viewer)
+
+Backtrack includes an offline visualizer with video replay, console logs, network inspection, and breadcrumbs.
+
+### Launch the Viewer CLI
+Run the embedded CLI to launch the local visualizer:
+
+```bash
+npx backtrack
+```
+
+This starts a local server at `http://localhost:5173/` and opens your default browser. Drag and drop any exported incident `.json` file to replay it!
+
+---
+
+## API Reference
+
+### `Backtrack` (`FlightRecorder`)
+
+| Method | Return Type | Description |
+| --- | --- | --- |
+| `start()` | `Promise<void>` | Initializes storage and begins recording. |
+| `stop()` | `Promise<void>` | Stops recording, flushes pending batches to storage, and detaches listeners. |
+| `capture(reason?, windowSeconds?)` | `Promise<string>` | Manually captures and finalizes an incident. Returns incident ID. |
+| `captureException(error, context?)` | `Promise<string \| undefined> \| void` | Records a caught exception and triggers an incident. |
+| `listIncidents()` | `Promise<IncidentSummary[]>` | Lists all stored incidents. |
+| `getArtifact(incidentId)` | `Promise<FlightRecorderArtifact>` | Retrieves the full artifact for an incident (v1 or v2). |
+| `exportIncident(incidentId)` | `Promise<FlightRecorderArtifact>` | Exports the artifact and marks it finalized. |
+| `deleteIncident(incidentId)` | `Promise<void>` | Deletes an incident from local storage. |
+| `clear()` | `Promise<void>` | Clears all stored chunks, sessions, and incidents. |
+| `getHealth()` | `RecorderHealth` | Returns current buffer status, storage usage, and state. |
+
+---
+
+## License
+
+[MIT](LICENSE)

package/bin/cli.cjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+function printHelp() {
+  console.log(`
+Uso: backtrack [comando] [opções]
+
+Comandos:
+  viewer                        Inicia o servidor local do Backtrack Viewer (padrão)
+  symbolize <incidente> [opções] Resolve stack traces usando source maps
+
+Opções globais:
+  -h, --help                    Mostra esta mensagem de ajuda
+
+Execute "backtrack symbolize --help" para ver as opções do comando symbolize.
+`.trim());
+}
+
+const command = process.argv[2];
+
+if (command === '--help' || command === '-h') {
+  printHelp();
+  return;
+}
+
+if (command === 'symbolize') {
+  const result = require('./symbolize.cjs').run(process.argv.slice(3));
+  if (result instanceof Promise) {
+    result.then((code) => {
+      if (typeof code === 'number') {
+        process.exitCode = code;
+      }
+    }).catch((err) => {
+      console.error(err);
+      process.exitCode = 1;
+    });
+  }
+  return;
+}
+
+if (
+  !command ||
+  command === 'viewer' ||
+  command === '--port' ||
+  command === '-p'
+) {
+  require('./viewer.cjs');
+  return;
+}
+
+console.error(`Comando desconhecido: ${command}`);
+process.exitCode = 1;

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './cli.cjs';