@bugspotter/sdk 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,639 @@
+# @bugspotter/sdk
+
+> Core SDK for capturing and reporting bugs
+
+The BugSpotter SDK provides a comprehensive solution for capturing bug reports in web applications, including screenshots, console logs, network requests, and browser metadata.
+
+## 📦 Installation
+
+### NPM Package
+
+```bash
+# npm
+npm install @bugspotter/sdk
+
+# yarn
+yarn add @bugspotter/sdk
+
+# pnpm
+pnpm add @bugspotter/sdk
+```
+
+### CDN
+
+```html
+<!-- BugSpotter CDN (versioned - recommended for production) -->
+<script src="https://cdn.bugspotter.io/sdk/bugspotter-0.1.0.min.js"></script>
+
+<!-- Latest version (for development only) -->
+<script src="https://cdn.bugspotter.io/sdk/bugspotter-latest.min.js"></script>
+
+<!-- Or unpkg -->
+<script src="https://unpkg.com/@bugspotter/sdk@latest/dist/bugspotter.min.js"></script>
+```
+
+📘 **See [CDN Usage Guide](./docs/CDN.md) for detailed CDN integration, SRI hashes, and troubleshooting.**
+
+### From Source
+
+```bash
+# Clone and build from source
+git clone https://github.com/apexbridge-tech/bugspotter.git
+cd bugspotter/packages/sdk
+pnpm install
+pnpm build
+```
+
+The built SDK will be available at `dist/bugspotter.min.js` (~99 KB minified with session replay).
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+**ES Modules (React, Vue, Angular, etc.)**
+
+```javascript
+import BugSpotter from '@bugspotter/sdk';
+
+// Initialize with auto-widget
+const bugSpotter = BugSpotter.init({
+  apiKey: 'bgs_your_api_key',
+  endpoint: 'https://api.bugspotter.com',
+  showWidget: true,
+});
+```
+
+**CommonJS (Node.js)**
+
+```javascript
+const BugSpotter = require('@bugspotter/sdk');
+
+const bugSpotter = BugSpotter.init({
+  apiKey: 'bgs_your_api_key',
+  endpoint: 'https://api.bugspotter.com',
+  showWidget: true,
+});
+```
+
+**UMD (Browser script tag)**
+
+```html
+<script src="https://cdn.bugspotter.io/sdk/bugspotter-latest.min.js"></script>
+<script>
+  // Initialize with auto-widget
+  const bugSpotter = BugSpotter.init({
+    apiKey: 'bgs_your_api_key',
+    endpoint: 'https://api.bugspotter.com',
+    showWidget: true,
+  });
+</script>
+```
+
+### Direct File Uploads (Presigned URLs)
+
+For better performance with large files, use `DirectUploader` to upload files directly to storage:
+
+```javascript
+import { DirectUploader, compressReplayEvents } from '@bugspotter/sdk';
+
+// 1. Create bug report (metadata only)
+const response = await fetch('https://api.example.com/api/v1/reports', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'x-api-key': 'bgs_your_api_key',
+  },
+  body: JSON.stringify({
+    project_id: 'project-uuid',
+    title: 'Bug title',
+    description: 'Bug description',
+  }),
+});
+const { id: bugId } = await response.json();
+
+// 2. Initialize DirectUploader
+const uploader = new DirectUploader({
+  apiEndpoint: 'https://api.example.com',
+  apiKey: 'bgs_your_api_key',
+  projectId: 'project-uuid',
+  bugId,
+});
+
+// 3. Upload screenshot with progress tracking
+const screenshotBlob = await fetch(screenshotDataUrl).then((r) => r.blob());
+await uploader.uploadScreenshot(screenshotBlob, (progress) => {
+  console.log(`Upload: ${progress.percentage}%`);
+});
+
+// 4. Compress and upload replay
+const compressedReplay = await compressReplayEvents(replayEvents);
+await uploader.uploadReplay(compressedReplay);
+
+console.log('All uploads complete!');
+```
+
+**Benefits:**
+
+- 97% memory reduction (3.33MB → 100KB API payload)
+- 3x faster uploads (direct to storage)
+- Progress tracking for large files
+- Automatic compression for replays
+
+### Manual Capture
+
+```javascript
+// Initialize without widget
+const bugSpotter = BugSpotter.init({
+  apiKey: 'your-api-key',
+  endpoint: 'https://api.example.com/bugs',
+  showWidget: false,
+});
+
+// Capture bug report manually
+async function reportBug() {
+  const report = await bugSpotter.capture();
+  console.log('Captured:', report);
+  // report contains: screenshot, console, network, metadata
+}
+```
+
+## 🎨 Using the Widget
+
+### Automatic Widget
+
+```javascript
+// Widget appears automatically with showWidget: true
+const bugSpotter = BugSpotter.init({
+  apiKey: 'demo-key',
+  endpoint: 'http://localhost:4000/api/bugs',
+  showWidget: true,
+  widgetOptions: {
+    position: 'bottom-right',
+    icon: '⚡',
+    backgroundColor: '#1a365d',
+    size: 48,
+  },
+});
+```
+
+### Custom Widget
+
+```javascript
+// Create custom floating button
+const button = new BugSpotter.FloatingButton({
+  position: 'bottom-right',
+  icon: '🐛',
+  backgroundColor: '#ff4444',
+  size: 56,
+  offset: { x: 24, y: 24 },
+  style: {
+    boxShadow: '0 2px 8px rgba(0,0,0,0.2)',
+    border: '2px solid white',
+  },
+});
+
+// Handle click
+button.onClick(async () => {
+  const report = await bugSpotter.capture();
+
+  const modal = new BugSpotter.BugReportModal({
+    onSubmit: async (data) => {
+      // data.title, data.description
+      const response = await fetch('https://api.example.com/bugs', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          ...data,
+          report,
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error('Submission failed');
+      }
+    },
+  });
+
+  modal.show(report.screenshot);
+});
+
+// Control button
+button.show();
+button.hide();
+button.setIcon('⚠️');
+button.setBackgroundColor('#00ff00');
+```
+
+## 🔒 PII Sanitization
+
+Automatic detection and masking of sensitive data before submission.
+
+**Built-in patterns:** Email, phone, credit card, SSN, Kazakhstan IIN, IP address
+
+```javascript
+BugSpotter.init({
+  sanitize: {
+    enabled: true, // Default
+    patterns: ['email', 'phone', 'creditcard'],
+    customPatterns: [{ name: 'api-key', regex: /API[-_]KEY:\s*[\w-]{20,}/gi }],
+    excludeSelectors: ['.public-email'],
+  },
+});
+```
+
+**Performance:** <10ms overhead, supports Cyrillic text
+
+## �📋 API Reference
+
+### BugSpotter Class
+
+#### `BugSpotter.init(config)`
+
+Initialize the SDK.
+
+**Parameters:**
+
+```typescript
+interface BugSpotterConfig {
+  apiKey?: string; // API key for authentication
+  endpoint?: string; // Backend API URL
+  showWidget?: boolean; // Auto-show widget (default: true)
+  widgetOptions?: FloatingButtonOptions;
+  replay?: {
+    // Session replay configuration
+    enabled?: boolean; // Enable replay (default: true)
+    duration?: number; // Buffer duration in seconds (default: 15)
+    sampling?: {
+      mousemove?: number; // Mousemove throttle in ms (default: 50)
+      scroll?: number; // Scroll throttle in ms (default: 100)
+    };
+  };
+  sanitize?: {
+    // PII sanitization configuration
+    enabled?: boolean; // Enable PII sanitization (default: true)
+    patterns?: Array<
+      // PII patterns to detect
+      'email' | 'phone' | 'creditcard' | 'ssn' | 'iin' | 'ip' | 'custom'
+    >;
+    customPatterns?: Array<{
+      // Custom regex patterns
+      name: string; // Pattern name for [REDACTED-NAME]
+      regex: RegExp; // Detection regex
+    }>;
+    excludeSelectors?: string[]; // CSS selectors to exclude from sanitization
+  };
+}
+```
+
+**Returns:** `BugSpotter` instance
+
+#### `bugSpotter.capture()`
+
+Capture current bug report data.
+
+**Returns:** `Promise<BugReport>`
+
+```typescript
+interface BugReport {
+  screenshot: string; // Base64 PNG data URL
+  console: ConsoleLog[]; // Array of console entries
+  network: NetworkRequest[]; // Array of network requests
+  metadata: BrowserMetadata; // Browser/system info
+  replay: eventWithTime[]; // Session replay events (rrweb format)
+}
+
+interface ConsoleLog {
+  level: string; // 'log', 'warn', 'error', 'info', 'debug'
+  message: string; // Formatted message
+  timestamp: number; // Unix timestamp
+  stack?: string; // Error stack trace (for errors)
+}
+
+interface NetworkRequest {
+  url: string; // Request URL
+  method: string; // HTTP method
+  status: number; // HTTP status code
+  duration: number; // Request duration in ms
+  timestamp: number; // Unix timestamp
+  error?: string; // Error message if failed
+}
+
+interface BrowserMetadata {
+  userAgent: string;
+  viewport: { width: number; height: number };
+  browser: string; // Detected browser name
+  os: string; // Detected OS
+  url: string; // Current page URL
+  timestamp: number; // Capture timestamp
+}
+```
+
+#### `bugSpotter.getConfig()`
+
+Get current configuration.
+
+**Returns:** `Readonly<BugSpotterConfig>`
+
+#### `bugSpotter.destroy()`
+
+Clean up and destroy the SDK instance.
+
+### FloatingButton Class
+
+#### Constructor
+
+```typescript
+new FloatingButton(options?: FloatingButtonOptions)
+
+interface FloatingButtonOptions {
+  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  icon?: string;            // Emoji or text
+  backgroundColor?: string; // CSS color
+  size?: number;           // Size in pixels
+  offset?: { x: number; y: number };
+  style?: Record<string, string>; // Additional CSS
+}
+```
+
+#### Methods
+
+- `button.onClick(handler: () => void | Promise<void>)` - Set click handler
+- `button.show()` - Show the button
+- `button.hide()` - Hide the button
+- `button.setIcon(icon: string)` - Change icon
+- `button.setBackgroundColor(color: string)` - Change color
+- `button.destroy()` - Remove button from DOM
+
+### BugReportModal Class
+
+#### Constructor
+
+```typescript
+new BugReportModal(options: BugReportModalOptions)
+
+interface BugReportModalOptions {
+  onSubmit: (data: BugReportData) => void | Promise<void>;
+  onClose?: () => void;
+}
+
+interface BugReportData {
+  title: string;
+  description: string;
+}
+```
+
+#### Methods
+
+- `modal.show(screenshot: string)` - Display modal with screenshot
+- `modal.close()` - Close the modal
+- `modal.destroy()` - Remove modal from DOM
+
+**Features:**
+
+- Form validation (title and description required)
+- Loading state during async submission
+- Error handling with user feedback
+- Escape key to close
+- Click X button to close
+- Cannot close by clicking outside (prevents data loss)
+
+### DirectUploader Class
+
+Direct client-to-storage uploads using presigned URLs (97% memory reduction, 3x faster).
+
+#### Constructor
+
+```typescript
+new DirectUploader(config: DirectUploadConfig)
+
+interface DirectUploadConfig {
+  apiEndpoint: string;    // Backend API URL
+  apiKey: string;         // bgs_... API key
+  projectId: string;      // Project UUID
+  bugId: string;         // Bug report UUID
+}
+```
+
+#### Methods
+
+**`uploadScreenshot(file, onProgress?)`**
+
+Upload screenshot directly to storage.
+
+```typescript
+const screenshotBlob = await fetch(dataUrl).then((r) => r.blob());
+
+const result = await uploader.uploadScreenshot(screenshotBlob, (progress) => {
+  console.log(`Screenshot: ${progress.loaded}/${progress.total} (${progress.percentage}%)`);
+});
+
+// result: { success: true, storageKey: "screenshots/..." }
+```
+
+**`uploadReplay(compressedBlob, onProgress?)`**
+
+Upload compressed replay data to storage.
+
+```typescript
+const compressed = await compressReplayEvents(events);
+const result = await uploader.uploadReplay(compressed);
+```
+
+**`uploadAttachment(file, onProgress?)`**
+
+Upload attachment file to storage.
+
+```typescript
+const file = document.querySelector('input[type="file"]').files[0];
+const result = await uploader.uploadAttachment(file);
+```
+
+#### Upload Progress
+
+```typescript
+interface UploadProgress {
+  loaded: number; // Bytes uploaded
+  total: number; // Total bytes
+  percentage: number; // 0-100
+}
+
+type UploadProgressCallback = (progress: UploadProgress) => void;
+```
+
+#### Upload Result
+
+```typescript
+interface UploadResult {
+  success: boolean;
+  storageKey?: string; // Storage location (if successful)
+  error?: string; // Error message (if failed)
+}
+```
+
+### Compression Utilities
+
+Compress replay events before uploading (2MB JSON → ~200KB gzip).
+
+**`compressReplayEvents(events)`**
+
+```typescript
+import { compressReplayEvents } from '@bugspotter/sdk';
+
+const events = [
+  /* rrweb events */
+];
+const compressed = await compressReplayEvents(events);
+console.log(`Compressed: ${(compressed.size / 1024).toFixed(2)} KB`);
+```
+
+Uses native `CompressionStream` API (Chrome 80+, Firefox 113+, Safari 16.4+).
+
+**`estimateCompressedReplaySize(events)`**
+
+Estimate compressed size without actually compressing.
+
+```typescript
+const estimatedSize = estimateCompressedReplaySize(events);
+console.log(`Estimated: ${(estimatedSize / 1024).toFixed(2)} KB`);
+```
+
+**`isWithinSizeLimit(blob, limitMB)`**
+
+Check if blob is within size limit.
+
+```typescript
+if (!isWithinSizeLimit(compressed, 10)) {
+  console.warn('File exceeds 10MB limit');
+}
+```
+
+## 📊 Capture Modules
+
+The SDK automatically captures:
+
+- **📸 Screenshots** - CSP-safe full page capture (~500ms)
+- **🎥 Session Replay** - Last 15-30s of user interactions (rrweb)
+- **📝 Console** - All log levels with stack traces
+- **🌐 Network** - fetch/XHR timing and responses
+- **💻 Metadata** - Browser, OS, viewport, URL
+
+See [Session Replay Documentation](docs/SESSION_REPLAY.md) for detailed configuration.
+
+### Screenshot Capture
+
+```typescript
+import { ScreenshotCapture } from '@bugspotter/sdk';
+
+const screenshotCapture = new ScreenshotCapture();
+const screenshot = await screenshotCapture.capture();
+// Returns: Base64 PNG data URL or 'SCREENSHOT_FAILED'
+```
+
+**Features:**
+
+- CSP-safe using `html-to-image`
+- Full page capture
+- Automatic error handling
+- ~500ms average capture time
+
+### Console Capture
+
+```typescript
+import { ConsoleCapture } from '@bugspotter/sdk';
+
+const consoleCapture = new ConsoleCapture();
+const logs = consoleCapture.getLogs();
+```
+
+**Features:**
+
+- Captures: log, warn, error, info, debug
+- Stack traces for errors
+- Timestamps for all entries
+- Object stringification
+- Circular reference handling
+- Configurable max logs (default: 100)
+
+### Network Capture
+
+```typescript
+import { NetworkCapture } from '@bugspotter/sdk';
+
+const networkCapture = new NetworkCapture();
+const requests = networkCapture.getRequests();
+```
+
+**Features:**
+
+- Captures fetch() and XMLHttpRequest
+- Request/response timing
+- HTTP status codes
+- Error tracking
+- Singleton pattern (one instance per page)
+
+### Metadata Capture
+
+```typescript
+import { MetadataCapture } from '@bugspotter/sdk';
+
+const metadataCapture = new MetadataCapture();
+const metadata = metadataCapture.capture();
+```
+
+**Features:**
+
+- Browser detection (Chrome, Firefox, Safari, Edge, etc.)
+- OS detection (Windows, macOS, Linux, iOS, Android)
+- Viewport dimensions
+- User agent string
+- Current URL
+- Timestamp
+
+## 🧪 Testing
+
+```bash
+pnpm test              # All tests
+pnpm test --watch      # Watch mode
+pnpm test --coverage   # Coverage report
+```
+
+**345 tests** passing (unit + E2E + Playwright)
+
+## �️ Building
+
+```bash
+pnpm run dev    # Development with watch
+pnpm run build  # Production build
+```
+
+Output: `dist/bugspotter.min.js` (~99 KB)
+
+## 📈 Performance
+
+- **Bundle**: ~99 KB minified
+- **Load**: < 100ms
+- **Memory**: < 15 MB (30s replay buffer)
+- **Screenshot**: ~500ms
+- **PII sanitization**: <10ms
+
+## 🔒 Security
+
+- CSP-safe (no eval, no inline scripts)
+- Automatic PII detection and masking
+- Input validation
+- HTTPS recommended
+
+## 🤝 Contributing
+
+See the main [CONTRIBUTING.md](../../CONTRIBUTING.md) guide.
+
+## 📄 License
+
+MIT License - see [LICENSE](../../LICENSE)
+
+---
+
+Part of the [BugSpotter](../../README.md) project