@arvoretech/bug-jar 0.3.1 → 0.4.0

package/README.md

@@ -1,12 +1,12 @@
 # 🪲 Bug Jar
 
-Capture everything for non-technical people to help debug. One script tag, zero config.
+Capture everything for non-technical people to help debug. One debug link, zero config.
 
-Bug Jar is a lightweight JavaScript library that silently records all browser activity (network requests, console logs, errors, user actions, performance metrics, and more) and lets anyone — even non-technical users — generate a complete debug report with a single click.
+Bug Jar is a lightweight JavaScript library that silently records all browser activity (network requests, console logs, errors, user actions, performance metrics, and more) and lets you capture a complete, encrypted debug session from a one-time debug link.
 
 ## Why?
 
-Because asking someone to "open DevTools and check the Network tab" doesn't scale. Bug Jar gives your support team, QA, and stakeholders a one-click way to capture everything developers need to reproduce and fix bugs.
+Because asking someone to "open DevTools and check the Network tab" doesn't scale. Bug Jar gives your support team and QA a link they can send to anyone to capture everything developers need to reproduce and fix bugs.
 
 ## What it captures
 
@@ -26,30 +26,19 @@ Because asking someone to "open DevTools and check the Network tab" doesn't scal
 
 ## Quick Start
 
-### Script tag (zero config)
+Bug Jar runs as a **debug session**: staff generates a one-time link, the user
+opens it in the real app, and the encrypted package is uploaded to S3. See
+[Debug Session Mode](#debug-session-mode-encrypted-upload-to-s3) below.
 
 ```html
 <script src="https://unpkg.com/@arvoretech/bug-jar"></script>
 <script>
-  BugJar.init();
+  BugJar.init({
+    debugSessionEndpoint: 'https://api.arvore.com.br/debug-sessions',
+  })
 </script>
 ```
 
-### NPM
-
-```bash
-npm install @arvoretech/bug-jar
-```
-
-```typescript
-import { init } from '@arvoretech/bug-jar'
-
-init({
-  endpoint: 'https://your-api.com/bug-reports',
-  uiPosition: 'bottom-right',
-})
-```
-
 ## Configuration
 
 ```typescript
@@ -74,16 +63,12 @@ init({
   // Privacy — fields containing these strings are redacted
   sensitiveFields: ['password', 'token', 'secret', 'authorization', 'cookie', 'session', 'credit_card', 'cvv', 'ssn', 'cpf'],
 
-  // Where to send reports (if not set, downloads as JSON file)
-  endpoint: 'https://your-api.com/bug-reports',
-
   // Callback when report is generated
   onCapture: (report) => console.log(report),
 
-  // UI widget
-  ui: true,
-  uiPosition: 'bottom-right', // bottom-right | bottom-left | top-right | top-left
-  uiLabel: 'Reportar Bug',
+  // Debug session
+  debugSessionEndpoint: 'https://api.arvore.com.br/debug-sessions',
+  // debugToken is read automatically from the ?debug=<token> query param
 })
 ```
 
@@ -92,7 +77,7 @@ init({
 ```typescript
 import { BugJar } from '@arvoretech/bug-jar'
 
-const jar = new BugJar({ ui: false })
+const jar = new BugJar()
 jar.start()
 
 // Later, capture a report programmatically
@@ -105,12 +90,46 @@ await fetch('/api/bugs', {
 })
 ```
 
+## Debug Session Mode (encrypted upload to S3)
+
+For non-technical users, staff can generate a one-time debug link. The user opens
+the link in the real app, reproduces the bug, and Bug Jar records the whole flow,
+encrypts the package end-to-end in the browser, and uploads it straight to a
+private S3 bucket via a presigned URL. No AWS credentials ever reach the browser.
+
+```html
+<script src="https://unpkg.com/@arvoretech/bug-jar"></script>
+<script>
+  BugJar.init({
+    debugSessionEndpoint: 'https://api.arvore.com.br/debug-sessions',
+    // debugToken is read automatically from the ?debug=<token> query param
+  })
+</script>
+```
+
+Flow:
+
+1. Staff (admin) calls `POST /debug-sessions` with the target app URL and gets back
+   a `debugLink` (`https://app.../?debug=<token>`), the presigned PUT URL, the
+   server public key, and an expiry.
+2. The user opens the link. Bug Jar detects `?debug=<token>`, fetches the session
+   from `debugSessionEndpoint`, starts screen recording, and shows a top banner.
+3. The user clicks **Finalizar e enviar**. Bug Jar builds the ZIP, encrypts it
+   (libsodium sealed box + secretbox hybrid), and uploads the encrypted blob to S3.
+4. Staff downloads the `.bin` via `GET /debug-sessions/:token/download` and
+   decrypts it offline with the private key.
+
+The package leaves the browser already unreadable; only the holder of the X25519
+private key can open it. `libsodium-wrappers` is loaded dynamically, so it only
+ships when debug mode is actually used.
+
+
 ## Privacy & Security
 
 - Sensitive fields are automatically redacted (passwords, tokens, secrets, etc.)
 - Password inputs are never captured
 - You control what gets captured via configuration
-- No data leaves the browser unless you configure an endpoint
+- No data leaves the browser unless a debug session is active
 - All processing happens client-side
 
 ## Browser Support

package/dist/index.d.mts

@@ -15,11 +15,8 @@ interface BugJarConfig {
     sensitiveFields: string[];
     endpoint?: string;
     onCapture?: (report: BugReport) => void;
-    ui: boolean;
-    uiPosition: "bottom-right" | "bottom-left" | "top-right" | "top-left";
-    uiLabel: string;
-    hideOnMobile?: boolean;
-    uiCompactOnMobile?: boolean;
+    debugToken?: string;
+    debugSessionEndpoint?: string;
 }
 interface NetworkEntry {
     id: string;
@@ -136,6 +133,14 @@ declare function generateSummary(report: BugReport): string;
 
 declare function exportAsZip(report: BugReport, videoBlob: Blob | null): Promise<Blob>;
 
+interface DebugSessionPayload {
+    token: string;
+    publicKey: string;
+    presignedPut: string;
+    reportId: string;
+    expiresAt: number;
+}
+
 declare class BugJar {
     private config;
     private network;
@@ -148,7 +153,8 @@ declare class BugJar {
     private screenshot;
     private featureFlags;
     private screenRecorder;
-    private ui;
+    private debugBanner;
+    private debugSession;
     private started;
     constructor(config?: Partial<BugJarConfig>);
     start(): void;
@@ -158,7 +164,9 @@ declare class BugJar {
     capture(userDescription?: string): Promise<BugReport>;
     captureAndExport(userDescription?: string): Promise<BugReport>;
     getReport(): Promise<BugReport>;
+    private startDebugSession;
+    private finishDebugSession;
 }
 declare function init(config?: Partial<BugJarConfig>): BugJar;
 
-export { BugJar, type BugJarConfig, type BugReport, BugJar as default, exportAsZip, generateSummary, init };
+export { BugJar, type BugJarConfig, type BugReport, type DebugSessionPayload, BugJar as default, exportAsZip, generateSummary, init };

package/dist/index.d.ts

@@ -15,11 +15,8 @@ interface BugJarConfig {
     sensitiveFields: string[];
     endpoint?: string;
     onCapture?: (report: BugReport) => void;
-    ui: boolean;
-    uiPosition: "bottom-right" | "bottom-left" | "top-right" | "top-left";
-    uiLabel: string;
-    hideOnMobile?: boolean;
-    uiCompactOnMobile?: boolean;
+    debugToken?: string;
+    debugSessionEndpoint?: string;
 }
 interface NetworkEntry {
     id: string;
@@ -136,6 +133,14 @@ declare function generateSummary(report: BugReport): string;
 
 declare function exportAsZip(report: BugReport, videoBlob: Blob | null): Promise<Blob>;
 
+interface DebugSessionPayload {
+    token: string;
+    publicKey: string;
+    presignedPut: string;
+    reportId: string;
+    expiresAt: number;
+}
+
 declare class BugJar {
     private config;
     private network;
@@ -148,7 +153,8 @@ declare class BugJar {
     private screenshot;
     private featureFlags;
     private screenRecorder;
-    private ui;
+    private debugBanner;
+    private debugSession;
     private started;
     constructor(config?: Partial<BugJarConfig>);
     start(): void;
@@ -158,7 +164,9 @@ declare class BugJar {
     capture(userDescription?: string): Promise<BugReport>;
     captureAndExport(userDescription?: string): Promise<BugReport>;
     getReport(): Promise<BugReport>;
+    private startDebugSession;
+    private finishDebugSession;
 }
 declare function init(config?: Partial<BugJarConfig>): BugJar;
 
-export { BugJar, type BugJarConfig, type BugReport, BugJar as default, exportAsZip, generateSummary, init };
+export { BugJar, type BugJarConfig, type BugReport, type DebugSessionPayload, BugJar as default, exportAsZip, generateSummary, init };