bugstash 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,324 @@
+# BugStash
+
+**Pre-production bug reporting SDK for React apps.** Drop a floating debug panel into your dev/staging environment. Capture bugs with screenshots, console logs, network requests, and full browser context — then manage everything from the [BugStash Dashboard](https://bugstash.vercel.app).
+
+[![npm version](https://img.shields.io/npm/v/bugstash.svg)](https://www.npmjs.com/package/bugstash)
+[![license](https://img.shields.io/npm/l/bugstash.svg)](https://www.npmjs.com/package/bugstash)
+
+---
+
+## Why BugStash?
+
+- **No more "it works on my machine"** — Every bug report includes console logs, network requests, browser info, and an optional screenshot
+- **Zero config** — One line to initialize, automatically disabled in production
+- **Live Pins** — Click anywhere on your page to leave contextual feedback pinned to specific elements
+- **Built for teams** — Multi-tenant dashboard with roles, projects, and real-time updates
+- **Privacy first** — Built-in PII redaction for sensitive data
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install bugstash
+```
+
+### 2. Get your Project ID
+
+Sign up at [bugstash.vercel.app](https://bugstash.vercel.app), create an organization and project, then copy your **Project ID** from the settings page.
+
+### 3. Initialize
+
+```tsx
+// app/layout.tsx or _app.tsx
+import BugStash from 'bugstash';
+
+BugStash.init({
+  projectId: 'your-project-id',
+  endpoint: 'https://bugstash-backend.azurewebsites.net',
+  environment: 'development', // auto-disabled in 'production'
+});
+```
+
+That's it. A floating bug button appears in the corner of your app.
+
+---
+
+## Configuration
+
+```tsx
+BugStash.init({
+  // Required
+  projectId: 'your-project-id',
+
+  // Optional
+  endpoint: 'https://bugstash-backend.azurewebsites.net',
+  environment: 'development',   // 'development' | 'staging' | 'production'
+  panelPosition: 'bottom-right', // 'bottom-right' | 'bottom-left'
+
+  // Features
+  enableScreenshot: true,       // Screenshot capture (default: true)
+  enableAnnotation: true,       // Annotate screenshots (default: true)
+  enablePerformance: true,      // Collect Web Vitals (default: true)
+  enableLivePins: true,         // Pin comments on page elements (default: true)
+
+  // Limits
+  maxLogs: 100,                 // Console log buffer size
+  maxNetworkCaptures: 50,       // Network request buffer size
+  maxBreadcrumbs: 50,           // User action breadcrumbs
+
+  // User context (optional)
+  user: {
+    id: 'user-123',
+    email: 'dev@example.com',
+    name: 'Jane Developer',
+  },
+
+  // Git commit hash (optional, shown in reports)
+  commitHash: process.env.NEXT_PUBLIC_COMMIT_SHA,
+});
+```
+
+---
+
+## What Gets Captured
+
+Every bug report automatically includes:
+
+| Category | Details |
+|----------|---------|
+| **Console Logs** | `log`, `warn`, `error`, `info`, `debug` with timestamps |
+| **Network Requests** | URL, method, status, duration, request/response size |
+| **Errors** | Uncaught exceptions and unhandled promise rejections with stack traces |
+| **Breadcrumbs** | Clicks, navigation, form submissions, custom events |
+| **Performance** | FCP, LCP, CLS, TTFB, FID (Web Vitals) |
+| **Browser Context** | User agent, viewport, URL, timestamp, OS, device |
+| **Screenshot** | Full-page capture with optional annotations |
+
+---
+
+## Features
+
+### Bug Report Panel
+
+Click the floating bug button to open the report panel. Write a description, set priority/category, attach a screenshot, and submit. All captured context is bundled automatically.
+
+### Live Pins
+
+Pin comments directly on UI elements. Team members see pins in real-time. Great for design reviews and QA feedback.
+
+```tsx
+// Toggle pin mode programmatically
+BugStash.togglePinMode();
+BugStash.isPinModeActive(); // boolean
+```
+
+### Themes
+
+Choose from built-in themes or match your app's aesthetic:
+
+```tsx
+BugStash.getThemes();           // List all available themes
+BugStash.setTheme('midnight');  // Switch theme
+BugStash.getCurrentThemeId();   // Get current theme
+```
+
+### Layouts
+
+Switch between different panel layouts:
+
+```tsx
+BugStash.getLayouts();          // List available layouts
+BugStash.setLayout('minimal');  // Switch layout
+```
+
+### PII Redaction
+
+Automatically redact sensitive data before it leaves the browser:
+
+```tsx
+BugStash.redactString('my email is test@email.com');
+// → "my email is [EMAIL REDACTED]"
+
+BugStash.redactObject({ password: 'secret', name: 'John' });
+// → { password: '[REDACTED]', name: 'John' }
+```
+
+---
+
+## Programmatic API
+
+Access captured data directly:
+
+```tsx
+// Console logs
+BugStash.getLogs();
+BugStash.clearLogs();
+
+// Network requests
+BugStash.getNetworkCaptures();
+BugStash.getFailedNetworkCaptures();
+BugStash.clearNetworkCaptures();
+
+// Errors
+BugStash.getErrors();
+BugStash.clearErrors();
+
+// Breadcrumbs
+BugStash.getBreadcrumbs();
+BugStash.addBreadcrumb({ type: 'custom', message: 'User completed onboarding' });
+BugStash.clearBreadcrumbs();
+
+// Performance metrics
+BugStash.getPerformanceMetrics();
+
+// Cleanup
+BugStash.destroy();
+```
+
+---
+
+## Framework Examples
+
+### Next.js (App Router)
+
+```tsx
+// app/providers.tsx
+'use client';
+
+import { useEffect } from 'react';
+import BugStash from 'bugstash';
+
+export function BugStashProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    BugStash.init({
+      projectId: process.env.NEXT_PUBLIC_BUGSTASH_PROJECT_ID!,
+      endpoint: 'https://bugstash-backend.azurewebsites.net',
+      environment: process.env.NODE_ENV as any,
+    });
+    return () => BugStash.destroy();
+  }, []);
+
+  return <>{children}</>;
+}
+```
+
+```tsx
+// app/layout.tsx
+import { BugStashProvider } from './providers';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <BugStashProvider>{children}</BugStashProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Vite + React
+
+```tsx
+// main.tsx
+import BugStash from 'bugstash';
+
+BugStash.init({
+  projectId: import.meta.env.VITE_BUGSTASH_PROJECT_ID,
+  endpoint: 'https://bugstash-backend.azurewebsites.net',
+  environment: import.meta.env.MODE,
+});
+```
+
+### Create React App
+
+```tsx
+// src/index.tsx
+import BugStash from 'bugstash';
+
+BugStash.init({
+  projectId: process.env.REACT_APP_BUGSTASH_PROJECT_ID!,
+  endpoint: 'https://bugstash-backend.azurewebsites.net',
+  environment: process.env.NODE_ENV,
+});
+```
+
+---
+
+## Dashboard
+
+Manage all reports from the [BugStash Dashboard](https://bugstash.vercel.app):
+
+- **View & filter** bug reports by status, priority, category, and assignee
+- **Assign** reports to team members
+- **Track** resolution status
+- **Inspect** full context: logs, network, errors, screenshots
+- **Live Pins** — see pinned comments in real-time
+- **Multi-tenant** — multiple organizations and projects
+- **Team roles** — owner, admin, member permissions
+
+Sign up free at **[bugstash.vercel.app](https://bugstash.vercel.app)**
+
+---
+
+## How It Works
+
+```
+Your App (dev/staging)          BugStash Cloud
+┌─────────────────────┐        ┌──────────────────┐
+│                     │        │                  │
+│  bugstash SDK       │───────>│  Backend API     │
+│  - captures logs    │  HTTPS │  - stores reports│
+│  - records network  │        │  - manages pins  │
+│  - takes screenshots│        │  - real-time WS  │
+│  - tracks errors    │        │                  │
+│                     │        └────────┬─────────┘
+└─────────────────────┘                 │
+                                        v
+                               ┌──────────────────┐
+                               │                  │
+                               │  Dashboard       │
+                               │  - view reports  │
+                               │  - assign bugs   │
+                               │  - team collab   │
+                               │                  │
+                               └──────────────────┘
+```
+
+---
+
+## Production Safety
+
+BugStash automatically disables itself when `environment` is set to `'production'`. No data is captured, no UI is rendered, and no network requests are made. Zero overhead in production.
+
+```tsx
+BugStash.init({
+  projectId: 'your-project-id',
+  environment: process.env.NODE_ENV, // 'production' = fully disabled
+});
+```
+
+---
+
+## Requirements
+
+- React >= 17.0.0
+- Modern browser (Chrome, Firefox, Safari, Edge)
+- Optional: `html2canvas` for screenshot capture (`npm install html2canvas`)
+
+---
+
+## Links
+
+- [Dashboard & Sign Up](https://bugstash.vercel.app)
+- [Documentation](https://bugstash.vercel.app/docs)
+- [GitHub](https://github.com/anastanvir/bugstash)
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bugstash",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Lightweight browser SDK for pre-production bug reporting",
   "main": "./dist/index.cjs",
@@ -14,19 +14,31 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anastanvir/bugstash"
+  },
+  "homepage": "https://bugstash.vercel.app",
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch"
   },
   "keywords": [
-    "browser",
-    "sdk",
+    "bug-reporting",
     "debug",
-    "bug-report",
-    "development",
-    "staging"
+    "sdk",
+    "react",
+    "developer-tools",
+    "feedback",
+    "screenshot",
+    "error-tracking",
+    "staging",
+    "qa",
+    "testing",
+    "devtools"
   ],
   "author": "",
   "license": "MIT",