@arvoretech/bug-jar 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Árvore Educação
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# 🪲 Bug Jar
+
+Capture everything for non-technical people to help debug. One script tag, 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.
+
+## 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.
+
+## What it captures
+
+| Category | Details |
+|----------|---------|
+| **Network** | All fetch/XHR/beacon requests with headers, payload, response, status, timing |
+| **Console** | log, warn, error, info, debug — with stack traces |
+| **Errors** | Uncaught exceptions, unhandled promise rejections, resource load failures |
+| **User Actions** | Clicks, inputs, navigation, scroll, resize, visibility changes |
+| **Environment** | Browser, OS, viewport, DPR, timezone, language, connection type |
+| **Performance** | Navigation timing, Web Vitals (LCP, FID, CLS), resource count |
+| **Storage** | localStorage keys, sessionStorage keys, cookie names |
+| **Screenshot** | Visual snapshot of the current page state |
+| **HTML Snapshot** | Full DOM at the moment of report |
+| **Feature Flags** | PostHog, LaunchDarkly, Statsig, Unleash (auto-detected) |
+| **Memory** | JS heap usage (Chrome) |
+
+## Quick Start
+
+### Script tag (zero config)
+
+```html
+<script src="https://unpkg.com/@arvoretech/bug-jar"></script>
+<script>
+  BugJar.init();
+</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
+init({
+  // Buffer sizes
+  maxNetworkEntries: 100,
+  maxConsoleEntries: 200,
+  maxUserActions: 150,
+  maxErrors: 50,
+
+  // What to capture
+  captureScreenshot: true,
+  captureHtmlSnapshot: true,
+  captureCookies: true,
+  captureLocalStorage: true,
+  captureSessionStorage: true,
+  capturePerformance: true,
+  captureWebVitals: true,
+  captureMemory: true,
+  captureConnectivity: true,
+
+  // 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',
+})
+```
+
+## Programmatic Usage
+
+```typescript
+import { BugJar } from '@arvoretech/bug-jar'
+
+const jar = new BugJar({ ui: false })
+jar.start()
+
+// Later, capture a report programmatically
+const report = await jar.capture('User clicked X but nothing happened')
+
+// Send it wherever you want
+await fetch('/api/bugs', {
+  method: 'POST',
+  body: JSON.stringify(report),
+})
+```
+
+## 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
+- All processing happens client-side
+
+## Browser Support
+
+Works in all modern browsers (Chrome, Firefox, Safari, Edge). Some features (memory info, connection type) are Chrome-only but degrade gracefully.
+
+## Size
+
+~12kb gzipped, zero dependencies.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,162 @@
+interface BugJarConfig {
+    maxNetworkEntries: number;
+    maxConsoleEntries: number;
+    maxUserActions: number;
+    maxErrors: number;
+    captureScreenshot: boolean;
+    captureHtmlSnapshot: boolean;
+    captureCookies: boolean;
+    captureLocalStorage: boolean;
+    captureSessionStorage: boolean;
+    capturePerformance: boolean;
+    captureWebVitals: boolean;
+    captureMemory: boolean;
+    captureConnectivity: boolean;
+    sensitiveFields: string[];
+    endpoint?: string;
+    onCapture?: (report: BugReport) => void;
+    ui: boolean;
+    uiPosition: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+    uiLabel: string;
+}
+interface NetworkEntry {
+    id: string;
+    timestamp: number;
+    method: string;
+    url: string;
+    requestHeaders: Record<string, string>;
+    requestBody: unknown;
+    status: number | null;
+    statusText: string;
+    responseHeaders: Record<string, string>;
+    responseBody: unknown;
+    responseSize: number | null;
+    duration: number | null;
+    type: "fetch" | "xhr" | "beacon";
+    error: string | null;
+    initiator: string | null;
+}
+interface ConsoleEntry {
+    timestamp: number;
+    level: "log" | "warn" | "error" | "info" | "debug";
+    args: unknown[];
+    stack: string | null;
+}
+interface ErrorEntry {
+    timestamp: number;
+    message: string;
+    stack: string | null;
+    filename: string | null;
+    lineno: number | null;
+    colno: number | null;
+    type: "uncaught" | "unhandledrejection" | "resource";
+    context: string | null;
+}
+interface UserAction {
+    timestamp: number;
+    type: "click" | "input" | "navigation" | "scroll" | "resize" | "visibility" | "copy" | "paste";
+    target: string;
+    value?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EnvironmentInfo {
+    userAgent: string;
+    platform: string;
+    language: string;
+    languages: string[];
+    timezone: string;
+    timezoneOffset: number;
+    screenWidth: number;
+    screenHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    devicePixelRatio: number;
+    colorDepth: number;
+    cookiesEnabled: boolean;
+    doNotTrack: string | null;
+    online: boolean;
+    hardwareConcurrency: number;
+    maxTouchPoints: number;
+    vendor: string;
+    connection: ConnectionInfo | null;
+    memory: MemoryInfo | null;
+}
+interface ConnectionInfo {
+    effectiveType: string;
+    downlink: number;
+    rtt: number;
+    saveData: boolean;
+}
+interface MemoryInfo {
+    jsHeapSizeLimit: number;
+    totalJSHeapSize: number;
+    usedJSHeapSize: number;
+}
+interface PerformanceData {
+    navigationTiming: Record<string, number>;
+    resourceCount: number;
+    totalTransferSize: number;
+    domContentLoaded: number | null;
+    loadComplete: number | null;
+    firstPaint: number | null;
+    firstContentfulPaint: number | null;
+    largestContentfulPaint: number | null;
+    firstInputDelay: number | null;
+    cumulativeLayoutShift: number | null;
+    timeToInteractive: number | null;
+}
+interface StorageSnapshot {
+    localStorage: Record<string, string>;
+    sessionStorage: Record<string, string>;
+    cookies: string[];
+}
+interface BugReport {
+    id: string;
+    timestamp: number;
+    url: string;
+    title: string;
+    userDescription: string;
+    environment: EnvironmentInfo;
+    network: NetworkEntry[];
+    console: ConsoleEntry[];
+    errors: ErrorEntry[];
+    userActions: UserAction[];
+    performance: PerformanceData | null;
+    storage: StorageSnapshot | null;
+    screenshot: string | null;
+    htmlSnapshot: string | null;
+    featureFlags: Record<string, unknown> | null;
+    metadata: Record<string, unknown>;
+    version: string;
+}
+
+declare function generateSummary(report: BugReport): string;
+
+declare function exportAsZip(report: BugReport, videoBlob: Blob | null): Promise<Blob>;
+
+declare class BugJar {
+    private config;
+    private network;
+    private console;
+    private errors;
+    private userActions;
+    private environment;
+    private performance;
+    private storage;
+    private screenshot;
+    private featureFlags;
+    private screenRecorder;
+    private ui;
+    private started;
+    constructor(config?: Partial<BugJarConfig>);
+    start(): void;
+    stop(): void;
+    startRecording(): Promise<void>;
+    get isRecording(): boolean;
+    capture(userDescription?: string): Promise<BugReport>;
+    captureAndExport(userDescription?: string): Promise<BugReport>;
+    getReport(): Promise<BugReport>;
+}
+declare function init(config?: Partial<BugJarConfig>): BugJar;
+
+export { BugJar, type BugJarConfig, type BugReport, BugJar as default, exportAsZip, generateSummary, init };

package/dist/index.d.ts

@@ -0,0 +1,162 @@
+interface BugJarConfig {
+    maxNetworkEntries: number;
+    maxConsoleEntries: number;
+    maxUserActions: number;
+    maxErrors: number;
+    captureScreenshot: boolean;
+    captureHtmlSnapshot: boolean;
+    captureCookies: boolean;
+    captureLocalStorage: boolean;
+    captureSessionStorage: boolean;
+    capturePerformance: boolean;
+    captureWebVitals: boolean;
+    captureMemory: boolean;
+    captureConnectivity: boolean;
+    sensitiveFields: string[];
+    endpoint?: string;
+    onCapture?: (report: BugReport) => void;
+    ui: boolean;
+    uiPosition: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+    uiLabel: string;
+}
+interface NetworkEntry {
+    id: string;
+    timestamp: number;
+    method: string;
+    url: string;
+    requestHeaders: Record<string, string>;
+    requestBody: unknown;
+    status: number | null;
+    statusText: string;
+    responseHeaders: Record<string, string>;
+    responseBody: unknown;
+    responseSize: number | null;
+    duration: number | null;
+    type: "fetch" | "xhr" | "beacon";
+    error: string | null;
+    initiator: string | null;
+}
+interface ConsoleEntry {
+    timestamp: number;
+    level: "log" | "warn" | "error" | "info" | "debug";
+    args: unknown[];
+    stack: string | null;
+}
+interface ErrorEntry {
+    timestamp: number;
+    message: string;
+    stack: string | null;
+    filename: string | null;
+    lineno: number | null;
+    colno: number | null;
+    type: "uncaught" | "unhandledrejection" | "resource";
+    context: string | null;
+}
+interface UserAction {
+    timestamp: number;
+    type: "click" | "input" | "navigation" | "scroll" | "resize" | "visibility" | "copy" | "paste";
+    target: string;
+    value?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EnvironmentInfo {
+    userAgent: string;
+    platform: string;
+    language: string;
+    languages: string[];
+    timezone: string;
+    timezoneOffset: number;
+    screenWidth: number;
+    screenHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    devicePixelRatio: number;
+    colorDepth: number;
+    cookiesEnabled: boolean;
+    doNotTrack: string | null;
+    online: boolean;
+    hardwareConcurrency: number;
+    maxTouchPoints: number;
+    vendor: string;
+    connection: ConnectionInfo | null;
+    memory: MemoryInfo | null;
+}
+interface ConnectionInfo {
+    effectiveType: string;
+    downlink: number;
+    rtt: number;
+    saveData: boolean;
+}
+interface MemoryInfo {
+    jsHeapSizeLimit: number;
+    totalJSHeapSize: number;
+    usedJSHeapSize: number;
+}
+interface PerformanceData {
+    navigationTiming: Record<string, number>;
+    resourceCount: number;
+    totalTransferSize: number;
+    domContentLoaded: number | null;
+    loadComplete: number | null;
+    firstPaint: number | null;
+    firstContentfulPaint: number | null;
+    largestContentfulPaint: number | null;
+    firstInputDelay: number | null;
+    cumulativeLayoutShift: number | null;
+    timeToInteractive: number | null;
+}
+interface StorageSnapshot {
+    localStorage: Record<string, string>;
+    sessionStorage: Record<string, string>;
+    cookies: string[];
+}
+interface BugReport {
+    id: string;
+    timestamp: number;
+    url: string;
+    title: string;
+    userDescription: string;
+    environment: EnvironmentInfo;
+    network: NetworkEntry[];
+    console: ConsoleEntry[];
+    errors: ErrorEntry[];
+    userActions: UserAction[];
+    performance: PerformanceData | null;
+    storage: StorageSnapshot | null;
+    screenshot: string | null;
+    htmlSnapshot: string | null;
+    featureFlags: Record<string, unknown> | null;
+    metadata: Record<string, unknown>;
+    version: string;
+}
+
+declare function generateSummary(report: BugReport): string;
+
+declare function exportAsZip(report: BugReport, videoBlob: Blob | null): Promise<Blob>;
+
+declare class BugJar {
+    private config;
+    private network;
+    private console;
+    private errors;
+    private userActions;
+    private environment;
+    private performance;
+    private storage;
+    private screenshot;
+    private featureFlags;
+    private screenRecorder;
+    private ui;
+    private started;
+    constructor(config?: Partial<BugJarConfig>);
+    start(): void;
+    stop(): void;
+    startRecording(): Promise<void>;
+    get isRecording(): boolean;
+    capture(userDescription?: string): Promise<BugReport>;
+    captureAndExport(userDescription?: string): Promise<BugReport>;
+    getReport(): Promise<BugReport>;
+}
+declare function init(config?: Partial<BugJarConfig>): BugJar;
+
+export { BugJar, type BugJarConfig, type BugReport, BugJar as default, exportAsZip, generateSummary, init };