tracebck-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # tracebck-sdk
 
-Lightweight session recording SDK based on [rrweb](https://github.com/rrweb-io/rrweb).
+Lightweight session recording SDK for [Tracebck](https://tracebck.dev). Captures user interactions, DOM changes, and network requests for replay.
 
 ## Installation
 
@@ -14,32 +14,20 @@ Or via CDN:
 <script src="https://unpkg.com/tracebck-sdk/dist/index.iife.js"></script>
 ```
 
-## Usage
+## Quick Start
 
 ### ES Modules
 
 ```javascript
 import { init, startSession, stopSession } from 'tracebck-sdk';
 
-// Initialize with your API key
-init({
-  apiKey: 'your-api-key',
-  // endpoint: 'https://your-api.com/v1', // optional, uses default
-  debug: false // optional
-});
+init({ apiKey: 'sk_your_api_key' });
 
-// Start recording
 startSession({
-  identifier: {
-    type: 'userId', // or 'email', 'anonymous', etc.
-    value: 'user-123'
-  },
-  metadata: {
-    plan: 'premium' // optional custom metadata
-  }
+  identifier: { type: 'userId', value: 'user-123' }
 });
 
-// Stop recording (call on logout or when done)
+// When done (e.g. on logout)
 stopSession();
 ```
 
@@ -48,9 +36,7 @@ stopSession();
 ```html
 <script src="https://unpkg.com/tracebck-sdk/dist/index.iife.js"></script>
 <script>
-  Tracebck.init({
-    apiKey: 'your-api-key'
-  });
+  Tracebck.init({ apiKey: 'sk_your_api_key' });
 
   Tracebck.startSession({
     identifier: { type: 'userId', value: 'user-123' }
@@ -58,14 +44,121 @@ stopSession();
 </script>
 ```
 
-## Configuration Options
+## API
+
+### `init(config)`
+
+Initializes the SDK. Must be called before `startSession()`.
+
+```javascript
+init({
+  apiKey: 'sk_your_api_key',
+  maskAllInputs: true,
+  captureNetwork: true,
+  flushInterval: 5000,
+  options: { /* rrweb options */ }
+});
+```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `apiKey` | string | required | Your API key |
-| `maskAllInputs` | boolean | `false` | Mask all input values for privacy |
-| `options` | object | `{}` | Additional rrweb options |
+| `apiKey` | `string` | **required** | Your project API key |
+| `maskAllInputs` | `boolean` | `false` | Replace all input values with `*` for privacy |
+| `captureNetwork` | `boolean` | `true` | Capture fetch and XHR requests |
+| `flushInterval` | `number` | `5000` | Interval in ms between event flushes |
+| `options` | `object` | `{}` | Additional [rrweb options](#rrweb-options) |
+
+### `startSession(config)`
+
+Creates a session and starts recording. If a session is already active, it will be stopped first.
+
+```javascript
+startSession({
+  identifier: {
+    type: 'email',
+    value: 'user@example.com'
+  },
+  metadata: {
+    plan: 'premium',
+    company: 'Acme'
+  }
+});
+```
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `identifier.type` | `string` | No | Identifier type (`'email'`, `'userId'`, etc.). Defaults to `'custom'` |
+| `identifier.value` | `string` | **Yes** | Unique user identifier |
+| `metadata` | `object` | No | Custom metadata attached to the session |
+
+Browser metadata (URL, referrer, userAgent, language, resolution) is captured automatically.
+
+### `stopSession()`
+
+Stops recording, flushes remaining events, and closes the session. Events are also flushed automatically when the user leaves or hides the page.
+
+## rrweb Options
+
+Pass rrweb `record()` options via the `options` field in `init()` to customize recording behavior.
+
+### Privacy
+
+Block elements entirely (rendered as grey placeholders in replay):
+
+```javascript
+options: {
+  blockClass: 'no-record',       // default: 'rr-block'
+  blockSelector: '.secret-panel'
+}
+```
+
+Mask text content (replaced with `*`):
+
+```javascript
+options: {
+  maskTextClass: 'rr-mask',
+  maskTextSelector: '.sensitive'
+}
+```
+
+Granular input masking:
+
+```javascript
+options: {
+  maskInputOptions: {
+    email: true,
+    tel: true,
+    password: true  // true by default
+  }
+}
+```
+
+### Performance
+
+```javascript
+options: {
+  sampling: {
+    mousemove: 100,     // throttle mouse tracking to every 100ms (default: true)
+    scroll: 200,        // throttle scroll events to 200ms (default: 150)
+    input: 'last'       // only record final input value (default: 'last')
+  },
+  slimDOMOptions: 'all' // strip scripts, comments, meta tags from snapshots
+}
+```
+
+## Network Capture
+
+When `captureNetwork` is enabled (default), the SDK intercepts `fetch` and `XMLHttpRequest` calls and records them as replay events. Requests to the Tracebck API are excluded automatically.
+
+Captured per request: method, URL, status code, headers, body (text content types only, max 100KB), and duration.
+
+## Distribution
 
+| Format | File | Usage |
+|--------|------|-------|
+| ESM | `dist/index.js` | `import` / bundlers |
+| CJS | `dist/index.cjs` | `require()` |
+| IIFE | `dist/index.iife.js` | `<script>` tag (exposes `window.Tracebck`) |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracebck-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lightweight session recording SDK based on rrweb",
   "author": "Miguel Hang",
   "license": "MIT",