@bugspotter/sdk 0.1.0-alpha.1

package/docs/SESSION_REPLAY.md

@@ -0,0 +1,381 @@
+# Session Replay Feature
+
+## Overview
+
+The BugSpotter SDK now includes session replay functionality that captures DOM mutations, mouse movements, clicks, and scrolls using [rrweb](https://www.rrweb.io/). This feature maintains a circular buffer that keeps only the last 15-30 seconds of events (configurable), ensuring minimal memory footprint while providing valuable context for bug reports.
+
+## Key Features
+
+- **Circular Buffer**: Time-based buffer that automatically prunes events older than the configured duration
+- **Performance Optimized**: Configurable sampling rates for mousemove and scroll events
+- **Automatic Recording**: Starts recording when BugSpotter initializes
+- **Minimal Overhead**: Slim DOM recording options to reduce payload size
+- **Serializable Events**: All events are JSON-serializable for easy transmission
+
+## Configuration
+
+### Basic Setup
+
+By default, session replay is enabled with a 15-second buffer:
+
+```typescript
+import { BugSpotter } from '@bugspotter/sdk';
+
+BugSpotter.init({
+  apiKey: 'your-api-key',
+  endpoint: 'https://api.bugspotter.com',
+});
+```
+
+### Custom Configuration
+
+```typescript
+BugSpotter.init({
+  apiKey: 'your-api-key',
+  endpoint: 'https://api.bugspotter.com',
+  replay: {
+    enabled: true, // Enable/disable replay (default: true)
+    duration: 30, // Duration in seconds (default: 15, recommended max: 30)
+    sampling: {
+      mousemove: 50, // Throttle mousemove events to every 50ms (default: 50)
+      scroll: 100, // Throttle scroll events to every 100ms (default: 100)
+    },
+  },
+});
+```
+
+### Disabling Replay
+
+```typescript
+BugSpotter.init({
+  apiKey: 'your-api-key',
+  replay: {
+    enabled: false,
+  },
+});
+```
+
+## How It Works
+
+### 1. Automatic Recording
+
+When BugSpotter initializes, the DOM collector automatically starts recording if replay is enabled:
+
+```typescript
+const bugspotter = BugSpotter.init(config);
+// Recording starts automatically!
+```
+
+### 2. Circular Buffer
+
+The circular buffer maintains only recent events:
+
+- Events are timestamped as they're captured
+- When new events are added, old events are automatically pruned
+- Only events within the configured duration are kept
+
+### 3. Bug Report Inclusion
+
+When a bug is reported, the last N seconds of events are included:
+
+```typescript
+const report = await bugspotter.capture();
+console.log(report.replay); // Array of rrweb events
+```
+
+### 4. Event Transmission
+
+The replay events are included in the bug report payload:
+
+```typescript
+{
+  title: "Bug title",
+  description: "Bug description",
+  report: {
+    screenshot: "...",
+    console: [...],
+    network: [...],
+    metadata: {...},
+    replay: [...] // rrweb events
+  }
+}
+```
+
+## Event Types
+
+The DOM collector captures the following event types:
+
+- **DOM Mutations**: Element additions, removals, and attribute changes
+- **Mouse Movements**: Throttled mousemove events
+- **Mouse Interactions**: Clicks, double-clicks, context menu, etc.
+- **Scroll Events**: Throttled scroll events
+- **Viewport Resizes**: Window resize events
+- **Input Changes**: Form input changes
+
+## Performance Considerations
+
+### Memory Usage
+
+- The circular buffer automatically prunes old events
+- Recommended duration: 15-30 seconds
+- Longer durations = more memory usage
+
+### Sampling Rates
+
+Default sampling rates are optimized for performance:
+
+- **Mousemove**: 50ms (20 events/second)
+- **Scroll**: 100ms (10 events/second)
+
+Adjust these based on your needs:
+
+```typescript
+replay: {
+  sampling: {
+    mousemove: 100, // Reduce to 10 events/second for better performance
+    scroll: 200,    // Reduce to 5 events/second
+  }
+}
+```
+
+### Slim DOM Options
+
+The collector uses slim DOM options by default:
+
+- Doesn't record script tags
+- Doesn't record comments
+- Doesn't record certain meta tags
+- Doesn't inline images (reduces payload size)
+
+## Advanced Usage
+
+### Direct Access to DOM Collector
+
+You can access the DOM collector directly for advanced use cases:
+
+```typescript
+import { DOMCollector } from '@bugspotter/sdk';
+
+const collector = new DOMCollector({
+  duration: 20,
+  sampling: {
+    mousemove: 100,
+    scroll: 200,
+  },
+});
+
+// Start recording
+collector.startRecording();
+
+// Get events
+const events = collector.getEvents();
+
+// Clear buffer
+collector.clearBuffer();
+
+// Stop recording
+collector.stopRecording();
+
+// Clean up
+collector.destroy();
+```
+
+### Direct Access to Circular Buffer
+
+```typescript
+import { CircularBuffer } from '@bugspotter/sdk';
+
+const buffer = new CircularBuffer({
+  duration: 30, // 30 seconds
+});
+
+// Add events
+buffer.add(event);
+buffer.addBatch([event1, event2, event3]);
+
+// Get events
+const events = buffer.getEvents();
+
+// Change duration
+buffer.setDuration(60); // Change to 60 seconds
+
+// Clear buffer
+buffer.clear();
+```
+
+## Edge Cases
+
+### Iframes
+
+The collector handles iframes gracefully:
+
+- Cross-origin iframes are not recorded by default (security restriction)
+- Same-origin iframes can be recorded with `recordCrossOriginIframes: true`
+
+### Shadow DOM
+
+Shadow DOM is handled automatically by rrweb.
+
+### Single Page Applications
+
+The collector works seamlessly with SPAs - it captures all DOM changes regardless of routing.
+
+## Troubleshooting
+
+### High Memory Usage
+
+If you're experiencing high memory usage:
+
+1. Reduce the buffer duration: `duration: 10`
+2. Increase sampling rates: `mousemove: 200, scroll: 300`
+3. Check for memory leaks in your application
+
+### Missing Events
+
+If events seem to be missing:
+
+1. Verify replay is enabled: `replay.enabled: true`
+2. Check the buffer duration is sufficient
+3. Verify events are within the time window
+
+### Performance Issues
+
+If you're experiencing performance issues:
+
+1. Increase sampling rates to reduce event frequency
+2. Reduce buffer duration
+3. Consider disabling replay in development mode
+
+## Browser Compatibility
+
+Session replay works in all modern browsers that support:
+
+- MutationObserver API
+- ES6 features
+- Proxy API
+
+Tested on:
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+
+## Dependencies
+
+- `rrweb@^2.0.0-alpha.4`: Core recording library
+- `rrweb-snapshot@^2.0.0-alpha.4`: DOM snapshot library
+- `@rrweb/types@^2.0.0-alpha.18`: TypeScript types
+
+## API Reference
+
+### BugSpotterConfig.replay
+
+```typescript
+interface ReplayConfig {
+  enabled?: boolean; // Default: true
+  duration?: number; // Default: 15 seconds
+  sampling?: {
+    mousemove?: number; // Default: 50ms
+    scroll?: number; // Default: 100ms
+  };
+}
+```
+
+### DOMCollector
+
+```typescript
+class DOMCollector {
+  constructor(config?: DOMCollectorConfig);
+  startRecording(): void;
+  stopRecording(): void;
+  getEvents(): eventWithTime[];
+  getCompressedEvents(): eventWithTime[];
+  clearBuffer(): void;
+  isCurrentlyRecording(): boolean;
+  getBufferSize(): number;
+  setDuration(seconds: number): void;
+  getDuration(): number;
+  destroy(): void;
+}
+```
+
+### CircularBuffer
+
+```typescript
+class CircularBuffer {
+  constructor(config: CircularBufferConfig);
+  add(event: eventWithTime): void;
+  addBatch(events: eventWithTime[]): void;
+  getEvents(): eventWithTime[];
+  getCompressedEvents(): eventWithTime[];
+  clear(): void;
+  size(): number;
+  setDuration(seconds: number): void;
+  getDuration(): number;
+}
+```
+
+## Examples
+
+### Example 1: Capturing a Bug Report
+
+```typescript
+const bugspotter = BugSpotter.init({
+  apiKey: 'your-api-key',
+  replay: {
+    duration: 20,
+  },
+});
+
+// ... user interacts with the app ...
+
+// When user reports a bug
+const report = await bugspotter.capture();
+console.log(report.replay.length); // Number of events captured
+```
+
+### Example 2: Custom Sampling
+
+```typescript
+BugSpotter.init({
+  apiKey: 'your-api-key',
+  replay: {
+    duration: 15,
+    sampling: {
+      mousemove: 200, // Less frequent mousemove events
+      scroll: 300, // Less frequent scroll events
+    },
+  },
+});
+```
+
+### Example 3: Programmatic Control
+
+```typescript
+import { BugSpotter, DOMCollector } from '@bugspotter/sdk';
+
+// Initialize without auto-start
+const bugspotter = BugSpotter.init({
+  apiKey: 'your-api-key',
+  replay: {
+    enabled: false,
+  },
+});
+
+// Manually create and control collector
+const collector = new DOMCollector({ duration: 30 });
+
+// Start recording when needed
+document.getElementById('start-btn').addEventListener('click', () => {
+  collector.startRecording();
+});
+
+// Stop recording when needed
+document.getElementById('stop-btn').addEventListener('click', () => {
+  collector.stopRecording();
+});
+```
+
+## License
+
+See main package LICENSE file.

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@bugspotter/sdk",
+  "version": "0.1.0-alpha.1",
+  "description": "Professional bug reporting SDK with screenshots, session replay, and automatic error capture for web applications",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "browser": "dist/bugspotter.min.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.js",
+      "browser": "./dist/bugspotter.min.js"
+    }
+  },
+  "scripts": {
+    "dev": "webpack --watch --mode development",
+    "build": "npm run build:webpack && npm run build:esm && npm run build:cjs",
+    "build:webpack": "webpack --mode production",
+    "build:esm": "tsc --project tsconfig.build.json --module ES2020 --outDir dist/esm && shx mv dist/esm/index.js dist/index.esm.js && shx rm -rf dist/esm",
+    "build:cjs": "tsc --project tsconfig.build.json --module CommonJS --outDir dist",
+    "prepublishOnly": "npm run build && npm test",
+    "lint": "eslint \"src/**/*.{ts,js}\"",
+    "lint:fix": "eslint \"src/**/*.{ts,js}\" --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:watch": "vitest --config vitest.e2e.config.ts",
+    "test:playwright": "playwright test",
+    "test:playwright:ui": "playwright test --ui"
+  },
+  "keywords": [
+    "bug-reporting",
+    "error-tracking",
+    "session-replay",
+    "screenshot",
+    "error-capture",
+    "debugging",
+    "monitoring",
+    "frontend",
+    "react",
+    "vue",
+    "angular",
+    "typescript"
+  ],
+  "author": "Apex Bridge Technology",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apexbridge-tech/bugspotter.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/apexbridge-tech/bugspotter/issues"
+  },
+  "homepage": "https://github.com/apexbridge-tech/bugspotter#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@bugspotter/types": "workspace:*",
+    "@rrweb/types": "2.0.0-alpha.18",
+    "html-to-image": "^1.11.13",
+    "pako": "^2.1.0",
+    "rrweb": "2.0.0-alpha.4",
+    "rrweb-snapshot": "2.0.0-alpha.4"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.48.0",
+    "@types/node": "^20.11.0",
+    "@types/pako": "^2.0.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "happy-dom": "^19.0.2",
+    "jsdom": "^24.1.0",
+    "shx": "^0.4.0",
+    "ts-loader": "^9.5.1",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.4",
+    "webpack": "^5.90.0",
+    "webpack-cli": "^5.1.4"
+  }
+}