npm package: @jarve/bug-reporter
Description: Bug reporter widget for Next.js apps. Reports flow to JARVE Agency dashboard.
Latest version: 0.4.2

# @jarve/bug-reporter

Bug reporter widget for Next.js apps. Reports flow to your JARVE Agency dashboard.

## How it works

1. A floating bug icon appears in the bottom-right corner of your app (sibling-aware — auto-stacks with other @jarve widgets)
2. Click it to enter capture mode - hover over a section and click to screenshot it
3. An AI assistant interviews the user to build a structured bug report
4. The report (with screenshot, console errors, network errors, and AI conversation) is submitted to your JARVE Agency dashboard

## Setup

### 1. Register your site

Go to your JARVE Agency dashboard at `/admin/bug-reports/sites` and:

- Click **Add Site**
- Enter your site name and color
- Click **Generate API Key**
- Copy the API key (starts with `brk_`)

### 2. Install

```bash
pnpm add @jarve/bug-reporter
# or
npm install @jarve/bug-reporter
```

### 3. Add Tailwind content path

The widget uses Tailwind CSS classes. Add the package to your Tailwind content configuration so the classes aren't purged.

**Tailwind v4** (add `@source` in your CSS file):

```css
@source '../node_modules/@jarve/bug-reporter/dist';
```

**Tailwind v3** (add to `content` in `tailwind.config.ts`):

```js
content: ['./node_modules/@jarve/bug-reporter/dist/**/*.{js,mjs}']
```

### 4. Wrap your layout

```tsx
// app/layout.tsx
import { JarveBugReporter } from '@jarve/bug-reporter'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <JarveBugReporter
          apiUrl="https://www.jarve.com.au/api/bug-reporter/external"
          apiKey="brk_your_api_key_here"
          user={{ name: 'James', email: 'james@example.com' }}
        >
          {children}
        </JarveBugReporter>
      </body>
    </html>
  )
}
```

### 5. Done!

Click the blue bug icon (bottom-right) to report bugs. They'll appear in your JARVE Agency dashboard.

## Props

| Prop             | Type                              | Required | Description                                                                            |
| ---------------- | --------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `apiUrl`         | `string`                          | Yes      | Base URL for the external bug reporter API                                             |
| `apiKey`         | `string`                          | Yes      | Your site's API key (starts with `brk_`)                                               |
| `buttonPosition` | `'left' \| 'right'`               | No       | Floating button position. Default: `'right'`. Sibling-aware with other @jarve widgets. |
| `user`           | `{ name: string, email: string }` | No       | User info. If omitted, the AI will ask during conversation                             |
| `children`       | `ReactNode`                       | Yes      | Your app content                                                                       |

## What gets captured

- Screenshot of the clicked section
- Page URL and section identifier
- Device type, browser, OS, viewport size
- Console errors (last 50)
- Failed network requests (last 30)
- Clicked element details (tag, text, selector path)
- AI conversation transcript
- Structured report (summary, expected/actual behavior, severity)

## Requirements

- React 18+
- Tailwind CSS (v3 or v4)
- Next.js recommended but not required