@bugspotter/sdk 0.1.0-alpha.2 → 0.1.2-alpha.5

package/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to the BugSpotter SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.1.1-alpha.5...sdk-v0.1.2-alpha.5) (2025-11-12)
+
+### Bug Fixes
+
+- **ci:** update SDK publish workflow to support prerelease tags ([#221](https://github.com/apexbridge-tech/bugspotter/issues/221)) ([dc4d7f2](https://github.com/apexbridge-tech/bugspotter/commit/dc4d7f2ef519afcf232704f05295729c6402008c))
+
+## [0.1.1-alpha.5](https://github.com/apexbridge-tech/bugspotter/compare/sdk-v0.1.0-alpha.5...sdk-v0.1.1-alpha.5) (2025-11-12)
+
+### Features
+
+- add exponential backoff retry and offline queue support ([c3c2106](https://github.com/apexbridge-tech/bugspotter/commit/c3c21063b777da37011449b89431a63f987ea777))
+- add FloatingButton widget and fix UMD exports ([b7e170e](https://github.com/apexbridge-tech/bugspotter/commit/b7e170eea47c7883722e59038a0d16b911c59588))
+- add FloatingButton widget with refactored architecture ([87a3d0e](https://github.com/apexbridge-tech/bugspotter/commit/87a3d0e69cea86db01e2847323440f296f045b16))
+- add gzip compression reducing payloads by 70-90% ([489e182](https://github.com/apexbridge-tech/bugspotter/commit/489e182ea072e3ffc43b58700b60288f6a255c22))
+- add gzip compression reducing payloads by 70-90% ([c545acf](https://github.com/apexbridge-tech/bugspotter/commit/c545acf6fe9a973c74a54f63a560b4fd96465e83))
+- add screenshot capture with html-to-image ([fae3eb7](https://github.com/apexbridge-tech/bugspotter/commit/fae3eb70fbf52d5b7c217f4d6d001735b661159d))
+- add session replay with rrweb ([175bd74](https://github.com/apexbridge-tech/bugspotter/commit/175bd74765d7f49b4be681c02eae0d7bbe8b1bc4))
+- add type safety system with shared types, Zod validation, and contract tests ([a3e436a](https://github.com/apexbridge-tech/bugspotter/commit/a3e436a931abda2cf30c85b32e5af2e011b7b3d9))
+- complete BugSpotter v0.1.0 with full documentation ([651153b](https://github.com/apexbridge-tech/bugspotter/commit/651153b2d4c86b9653df6164539991ea92c41942))
+- complete core SDK with all capture modules ([54fe97a](https://github.com/apexbridge-tech/bugspotter/commit/54fe97af32b2ee1aa09f5657b28b89e40454cb0a))
+- fixed bug in NetworkCapture + eslint + prettier ([75e2d92](https://github.com/apexbridge-tech/bugspotter/commit/75e2d9290d82ea3f9b377e3b189ce933f7e3e336))
+- initial project structure ([7109dc2](https://github.com/apexbridge-tech/bugspotter/commit/7109dc2e284ea8692081965e4b5a9cce4dc1b1e0))
+- **sdk:** bump to 0.1.0-alpha.5 with improved release workflow ([#219](https://github.com/apexbridge-tech/bugspotter/issues/219)) ([a191b7b](https://github.com/apexbridge-tech/bugspotter/commit/a191b7b998863f00df4bd24f529057e4c4160a73))
+- vitest configured + unit tests for capture ([381d11e](https://github.com/apexbridge-tech/bugspotter/commit/381d11e8ea45376c56ded0d62c2c37a726002acf))
+
+### Bug Fixes
+
+- increase browser test timeout and add GitHub release permissions ([#142](https://github.com/apexbridge-tech/bugspotter/issues/142)) ([301600e](https://github.com/apexbridge-tech/bugspotter/commit/301600e5fa6c01e0a6ef0e3281a0c27206cc00e2))
+- remove await from background queue processing ([174889d](https://github.com/apexbridge-tech/bugspotter/commit/174889d9df5541d0494b736d9b8c44bbcbdfbb7e))
+- **sdk:** remove unused @bugspotter/types workspace dependency ([#146](https://github.com/apexbridge-tech/bugspotter/issues/146)) ([7fed00b](https://github.com/apexbridge-tech/bugspotter/commit/7fed00bafab22f1854b78f861a90069b96a665c1))
+
+### Code Refactoring
+
+- Addressed comments on PR; ([fcb4888](https://github.com/apexbridge-tech/bugspotter/commit/fcb488813cd36147f6292c36f4540b23b7759e20))
+- improve capture classes with options, types, and performance ([616bd35](https://github.com/apexbridge-tech/bugspotter/commit/616bd3502c7620f65494ae813ea39e87781b5a2f))
+- improve transport and offline queue architecture ([01a27f3](https://github.com/apexbridge-tech/bugspotter/commit/01a27f3cc24d1211c65e4f0992fc969f40294e70))
+- optimize demo & documentation structure ([22c2171](https://github.com/apexbridge-tech/bugspotter/commit/22c21712229f19b1280d1406c2fac60655d41c4a))
+- Phase 2 - Extract shared capture architecture ([48d007c](https://github.com/apexbridge-tech/bugspotter/commit/48d007cecfc4651ded10a8c7fd4651fcec499fbd))
+- Phase 2 - Extract shared capture architecture ([ea88dda](https://github.com/apexbridge-tech/bugspotter/commit/ea88dda3cdbb07d72f96d707a3ebb97edf93379c))
+- Phase 2 - Extract shared capture architecture ([72f2425](https://github.com/apexbridge-tech/bugspotter/commit/72f242575c46c3c813bf15234ca95d5624b7d7d4))
+- remove deprecated code and unused variables ([392bbb9](https://github.com/apexbridge-tech/bugspotter/commit/392bbb9c91e3d57a49b9650782b778aea9607d50))
+
+### Tests
+
+- Add comprehensive edge case tests for DOM collector ([24b56b3](https://github.com/apexbridge-tech/bugspotter/commit/24b56b3317edd6df656f551c7d22db3cc03df7ac))
+
 ## [0.1.0] - 2025-11-01
 
 ### Added

package/README.md

@@ -57,8 +57,12 @@ import BugSpotter from '@bugspotter/sdk';
 
 // Initialize with auto-widget
 const bugSpotter = BugSpotter.init({
-  apiKey: 'bgs_your_api_key',
-  endpoint: 'https://api.bugspotter.com',
+  endpoint: 'https://api.bugspotter.com/api/v1/reports',
+  auth: {
+    type: 'api-key',
+    apiKey: 'bgs_your_api_key',
+    projectId: 'your-project-uuid',
+  },
   showWidget: true,
 });
 ```
@@ -69,8 +73,12 @@ const bugSpotter = BugSpotter.init({
 const BugSpotter = require('@bugspotter/sdk');
 
 const bugSpotter = BugSpotter.init({
-  apiKey: 'bgs_your_api_key',
-  endpoint: 'https://api.bugspotter.com',
+  endpoint: 'https://api.bugspotter.com/api/v1/reports',
+  auth: {
+    type: 'api-key',
+    apiKey: 'bgs_your_api_key',
+    projectId: 'your-project-uuid',
+  },
   showWidget: true,
 });
 ```
@@ -82,79 +90,82 @@ const bugSpotter = BugSpotter.init({
 <script>
   // Initialize with auto-widget
   const bugSpotter = BugSpotter.init({
-    apiKey: 'bgs_your_api_key',
-    endpoint: 'https://api.bugspotter.com',
+    endpoint: 'https://api.bugspotter.com/api/v1/reports',
+    auth: {
+      type: 'api-key',
+      apiKey: 'bgs_your_api_key',
+      projectId: 'your-project-uuid',
+    },
     showWidget: true,
   });
 </script>
 ```
 
-### Direct File Uploads (Presigned URLs)
+### How It Works
 
-For better performance with large files, use `DirectUploader` to upload files directly to storage:
+The SDK automatically uses an **optimized presigned URL upload flow** (40% fewer HTTP requests):
 
 ```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,
-});
+import BugSpotter from '@bugspotter/sdk';
 
-// 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}%`);
+// 1. Initialize SDK with required auth
+const bugSpotter = BugSpotter.init({
+  endpoint: 'https://api.bugspotter.com/api/v1/reports',
+  auth: {
+    type: 'api-key',
+    apiKey: 'bgs_your_api_key',
+    projectId: 'your-project-uuid', // Required for file uploads
+  },
+  showWidget: true,
 });
 
-// 4. Compress and upload replay
-const compressedReplay = await compressReplayEvents(replayEvents);
-await uploader.uploadReplay(compressedReplay);
-
-console.log('All uploads complete!');
+// 2. Submit a bug report (SDK handles everything automatically)
+// Optimized flow (3 HTTP requests instead of 5):
+// - Step 1: POST /api/v1/reports with hasScreenshot/hasReplay flags
+//           → Returns bug ID + presigned URLs for screenshot & replay
+// - Step 2: PUT to S3 presigned URLs (parallel uploads)
+// - Step 3: POST /api/v1/reports/{id}/confirm-upload (confirm each file)
 ```
 
 **Benefits:**
 
-- 97% memory reduction (3.33MB → 100KB API payload)
-- 3x faster uploads (direct to storage)
-- Progress tracking for large files
-- Automatic compression for replays
+- **40% fewer HTTP requests** - 3 requests vs 5 in legacy flow
+- Files upload directly to S3 (faster, no API bottleneck)
+- Automatic compression for replay events
+- Concurrent uploads (screenshot + replay in parallel)
+- Reduced server load
 
-### Manual Capture
+### Manual Capture & Programmatic Submission
 
 ```javascript
 // Initialize without widget
 const bugSpotter = BugSpotter.init({
-  apiKey: 'your-api-key',
-  endpoint: 'https://api.example.com/bugs',
+  endpoint: 'https://api.bugspotter.com/api/v1/reports',
+  auth: {
+    type: 'api-key',
+    apiKey: 'bgs_your_api_key',
+    projectId: 'your-project-uuid',
+  },
   showWidget: false,
 });
 
-// Capture bug report manually
-async function reportBug() {
-  const report = await bugSpotter.capture();
-  console.log('Captured:', report);
-  // report contains: screenshot, console, network, metadata
-}
+// Capture bug report data
+const report = await bugSpotter.capture();
+console.log('Captured:', report);
+// report contains: screenshot, console, network, metadata, replay
+
+// Submit programmatically (SDK handles presigned URL uploads)
+await bugSpotter.submit({
+  title: 'Application crashed',
+  description: 'Error occurred during form submission',
+  priority: 'high',
+  report,
+});
+// ✅ SDK automatically:
+// 1. Detects hasScreenshot/hasReplay from report data
+// 2. Gets presigned URLs from backend
+// 3. Uploads screenshot + replay to S3 (parallel)
+// 4. Confirms uploads with backend
 ```
 
 ## 🎨 Using the Widget
@@ -164,8 +175,12 @@ async function reportBug() {
 ```javascript
 // Widget appears automatically with showWidget: true
 const bugSpotter = BugSpotter.init({
-  apiKey: 'demo-key',
-  endpoint: 'http://localhost:4000/api/bugs',
+  endpoint: 'https://api.bugspotter.com/api/v1/reports',
+  auth: {
+    type: 'api-key',
+    apiKey: 'bgs_your_api_key',
+    projectId: 'your-project-uuid',
+  },
   showWidget: true,
   widgetOptions: {
     position: 'bottom-right',
@@ -179,17 +194,35 @@ const bugSpotter = BugSpotter.init({
 ### Custom Widget
 
 ```javascript
-// Create custom floating button
+// Default professional SVG icon (recommended)
 const button = new BugSpotter.FloatingButton({
+  position: 'bottom-right',
+  // icon: 'svg' is default - professional bug icon
+  backgroundColor: '#2563eb', // Professional blue (default)
+  tooltip: 'Report an Issue',
+});
+
+// Custom emoji/text icon
+const button2 = 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',
-  },
+});
+
+// Custom SVG icon
+const button3 = new BugSpotter.FloatingButton({
+  position: 'bottom-left',
+  customSvg: `
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
+      <path d="M12 2L2 7l10 5 10-5-10-5z"/>
+      <path d="M2 17l10 5 10-5M2 12l10 5 10-5"/>
+    </svg>
+  `,
+  tooltip: 'Custom Report Button',
+  backgroundColor: '#1a365d',
+  size: 48,
 });
 
 // Handle click
@@ -198,26 +231,16 @@ button.onClick(async () => {
 
   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,
-        }),
+      // Use SDK's submit() method for automatic presigned URL uploads
+      await bugSpotter.submit({
+        ...data, // title, description, priority
+        report,
       });
-
-      if (!response.ok) {
-        throw new Error('Submission failed');
-      }
+      // ✅ SDK handles presigned URLs and S3 uploads automatically
     },
   });
 
-  modal.show(report.screenshot);
+  modal.show(report._screenshotPreview || '');
 });
 
 // Control button
@@ -258,8 +281,13 @@ Initialize the SDK.
 
 ```typescript
 interface BugSpotterConfig {
-  apiKey?: string; // API key for authentication
-  endpoint?: string; // Backend API URL
+  endpoint: string; // Required: Backend API URL
+  auth: {
+    // Required: Authentication configuration
+    type: 'api-key';
+    apiKey: string; // API key (bgs_...)
+    projectId: string; // Project UUID (required for file uploads)
+  };
   showWidget?: boolean; // Auto-show widget (default: true)
   widgetOptions?: FloatingButtonOptions;
   replay?: {
@@ -290,6 +318,46 @@ interface BugSpotterConfig {
 
 **Returns:** `BugSpotter` instance
 
+#### `bugSpotter.submit(payload)`
+
+Submit a bug report with automatic file uploads via presigned URLs.
+
+**Parameters:**
+
+```typescript
+interface BugReportPayload {
+  title: string; // Bug title (required)
+  description?: string; // Bug description (optional)
+  priority?: 'low' | 'medium' | 'high' | 'critical';
+  report: BugReport; // Report data from capture()
+}
+```
+
+**Returns:** `Promise<void>`
+
+**Throws:** Error if submission fails
+
+**Example:**
+
+```typescript
+const report = await bugSpotter.capture();
+
+await bugSpotter.submit({
+  title: 'Button not responding',
+  description: 'Submit button does not work on checkout page',
+  priority: 'high',
+  report,
+});
+```
+
+**What it does:**
+
+1. Detects screenshot and replay from report data
+2. Requests presigned URLs from backend
+3. Uploads files directly to S3 (parallel)
+4. Confirms uploads with backend
+5. Handles errors and retries automatically
+
 #### `bugSpotter.capture()`
 
 Capture current bug report data.
@@ -298,11 +366,13 @@ Capture current bug report data.
 
 ```typescript
 interface BugReport {
-  screenshot: string; // Base64 PNG data URL
+  screenshotKey?: string; // Storage key after presigned URL upload
   console: ConsoleLog[]; // Array of console entries
   network: NetworkRequest[]; // Array of network requests
   metadata: BrowserMetadata; // Browser/system info
-  replay: eventWithTime[]; // Session replay events (rrweb format)
+  replay?: eventWithTime[]; // Session replay events (rrweb format)
+  replayKey?: string; // Storage key after presigned URL upload
+  _screenshotPreview?: string; // Internal: screenshot preview for modal (not sent to API)
 }
 
 interface ConsoleLog {
@@ -350,10 +420,12 @@ 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
+  icon?: string;            // 'svg' for default bug icon, or custom emoji/text
+  customSvg?: string;       // Custom SVG icon (overrides icon if provided)
+  backgroundColor?: string; // CSS color (default: '#2563eb' professional blue)
+  size?: number;            // Size in pixels (default: 56)
   offset?: { x: number; y: number };
+  tooltip?: string;         // Custom tooltip text (default: 'Report an Issue')
   style?: Record<string, string>; // Additional CSS
 }
 ```