Documentation

Installation

Install the BugStash SDK with your preferred package manager.

npm install bugstash

Or with yarn / pnpm:

yarn add bugstash
pnpm add bugstash

Quick Start

Import and initialize BugStash at the root of your application. The SDK injects a lightweight overlay for live pins, bug reports, and screenshot capture.

import BugStash from 'bugstash'

BugStash.init({
  projectId: 'your-project-id',
  enableLivePins: true,
  enableScreenshot: true,
  enableAnnotation: true,
  enablePerformance: true,
})

Configuration

The init() method accepts a configuration object with these properties:

Live Pins

Live Pins let your team drop contextual markers directly on the page. Each pin records the viewport position, DOM selector, page URL, and a comment thread — making it simple to reference an exact element during review.

Bug Reports

The built-in bug report widget captures browser metadata, console logs, network waterfall, breadcrumbs, and a screenshot automatically. Users fill in a title and description, then the report is sent to your dashboard with all context attached.

Screenshots & Annotations

BugStash uses html2canvas to capture a pixel-perfect screenshot of the current viewport. When enableAnnotation is true, users can draw rectangles, arrows, circles, and freehand highlights on a frozen screenshot before submitting a report.

Console & Network Capture

The SDK intercepts console.log, console.warn, console.error, console.debug, and console.info calls. It also tracks all fetch and XMLHttpRequest calls including method, URL, status code, response time, headers, and whether the request failed.

Error Tracking

Uncaught errors and unhandled promise rejections are automatically captured with full stack traces. These are attached to bug reports and pins for context.

Performance Metrics

When enablePerformance is true (default), the SDK collects Core Web Vitals, page load times, memory usage, and resource counts. This data is included in bug reports.

PII Redaction

Built-in redaction for sensitive data. The SDK automatically masks credit card numbers, SSNs, JWT tokens, Bearer tokens, AWS access keys, and password fields in captured logs and network data. Sensitive headers like Authorization and Cookie are also redacted.

BugStash.init(config)

Initialize the SDK and mount the overlay. Must be called once before any other method.

import BugStash from 'bugstash'

BugStash.init({
  projectId: 'proj_abc123',
  enableLivePins: true,
  enableScreenshot: true,
  user: { id: 'usr_42', name: 'Jane', email: 'jane@co.com' },
})

BugStash.destroy()

Remove all SDK elements from the DOM, close WebSocket connections, restore original console/fetch/XHR functions, and clean up event listeners.

BugStash.destroy()

BugStash.togglePinMode()

Toggle pin creation mode on or off. When active, clicking on the page creates a new pin at that location. Check status with BugStash.isPinModeActive().

BugStash.togglePinMode()

// Check if pin mode is currently active
const active = BugStash.isPinModeActive()

User Identity & Auth

Set the current user context so all pins and reports are attributed correctly.

// Get the currently logged-in user
const user = BugStash.getCurrentUser()

// Login a user
await BugStash.login('jane@co.com', 'password', 'proj_abc123')

// Logout
BugStash.logout()

Logs & Network

Access captured console logs and network requests programmatically.

// Console logs
const logs = BugStash.getLogs()
BugStash.clearLogs()

// Network captures
const requests = BugStash.getNetworkCaptures()
const failed = BugStash.getFailedNetworkCaptures()
BugStash.clearNetworkCaptures()

Errors & Breadcrumbs

Retrieve tracked errors and user interaction breadcrumbs.

// Errors
const errors = BugStash.getErrors()
BugStash.clearErrors()

// Breadcrumbs (clicks, navigation, inputs, etc.)
const crumbs = BugStash.getBreadcrumbs()
BugStash.addBreadcrumb({ type: 'custom', message: 'User completed checkout' })
BugStash.clearBreadcrumbs()

Themes & Layouts

The SDK supports multiple UI themes and layout configurations.

// Themes
const themes = BugStash.getThemes()
BugStash.setTheme('dark')
const currentTheme = BugStash.getCurrentThemeId()

// Layouts
const layouts = BugStash.getLayouts()
BugStash.setLayout('compact')
const currentLayout = BugStash.getCurrentLayoutId()

Authentication

All API requests require a Bearer token. Include it as Authorization: Bearer <token>.

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "password": "securepassword",
  "orgName": "Acme Corp"
}

{
  "success": true,
  "data": {
    "tokens": { "accessToken": "eyJhbG...", "refreshToken": "..." },
    "user": { "id": "usr_42", "name": "Jane Doe", "role": "owner" }
  }
}

{
  "email": "jane@example.com",
  "password": "securepassword"
}

Pins

{
  "projectId": "proj_abc123",
  "title": "Padding issue on hero section",
  "x": 200, "y": 150,
  "pageUrl": "https://app.example.com",
  "selector": "#hero > .cta-btn",
  "priority": "high"
}

Reports

{
  "projectId": "...",
  "title": "Dropdown clips on mobile",
  "description": "The navigation dropdown is clipped...",
  "category": "ui",
  "severity": "high",
  "context": { "url": "...", "browser": "...", "os": "..." },
  "consoleLogs": [...],
  "errors": [...],
  "networkCaptures": [...],
  "breadcrumbs": [...],
  "performance": { ... },
  "screenshot": "data:image/png;base64,...",
  "annotation": "data:image/png;base64,..."
}

Webhooks

Register webhook URLs to receive real-time notifications when events occur. All payloads are signed with HMAC-SHA256.

{
  "url": "https://yourserver.com/webhooks/bugstash",
  "events": ["pin:created", "pin:resolved", "report:submitted"]
}

import { createHmac } from 'crypto'

function verifySignature(body: string, signature: string, secret: string) {
  const digest = createHmac('sha256', secret)
    .update(body)
    .digest('hex')
  return digest === signature
}

Data Export

Export your pins and reports as JSON or CSV.

Slack Integration

Connect BugStash to Slack for instant notifications. Go to Settings → Integrations → Slack and paste your Incoming Webhook URL. Every new pin and report posts a formatted message with the title, severity, reporter name, and a direct link to the dashboard.

GitHub Integration

Link your GitHub repository to auto-create issues from bug reports. Authorize the BugStash GitHub App and select your target repository. Each report opens a GitHub issue with title, description, browser metadata, and screenshot link.