quick-bug-reporter-react 1.2.0 → 1.3.0

package/README.md

@@ -8,6 +8,7 @@ Drop-in bug reporter for React apps — screenshot capture, video recording, ann
 - **Video recording** — Screen + microphone via `MediaRecorder` API
 - **Annotation** — Drag-to-highlight on captured screenshots
 - **Network logging** — Automatic fetch interception during capture
+- **Console capture** — Automatic console log and JS error capture
 - **Integrations** — Linear and Jira (direct API or backend proxy)
 - **Zero config UI** — Floating bug button + modal wizard, ships its own styles
 
@@ -56,18 +57,20 @@ import {
   BugReporterProvider,
   FloatingBugButton,
   BugReporterModal,
-  LinearIntegration,
+  JiraIntegration,
 } from "quick-bug-reporter-react";
 
-const linear = new LinearIntegration({
-  submitProxyEndpoint: "/api/bug-report",
+const jira = new JiraIntegration({
+  createIssueProxyEndpoint: "/api/jira/create-issue",
+  uploadAttachmentProxyEndpoint: "/api/jira/upload-attachment",
+  projectKey: "BUG",
 });
 
 export default function App({ children }) {
   return (
     <BugReporterProvider
-      integrations={{ linear }}
-      defaultProvider="linear"
+      integrations={{ jira }}
+      defaultProvider="jira"
     >
       {children}
       <FloatingBugButton />
@@ -81,32 +84,41 @@ That's it — a floating "Report Bug" button appears in the bottom-right corner.
 
 ## Integrations
 
-Both integrations support two modes:
+### Jira
+
+```ts
+import { JiraIntegration } from "quick-bug-reporter-react";
+
+// ✅ Recommended: split proxy endpoints (parallel uploads, fastest)
+const jira = new JiraIntegration({
+  createIssueProxyEndpoint: "/api/jira/create-issue",
+  uploadAttachmentProxyEndpoint: "/api/jira/upload-attachment",
+  projectKey: "BUG",
+  issueType: "Bug", // optional, defaults to "Bug"
+});
+```
 
-| Mode | When to use | How it works |
-|------|------------|--------------|
-| **Backend proxy** (recommended) | Production apps | Your server-side endpoint receives the report and calls Linear/Jira. API keys stay on the server. |
-| **Direct API** | Server-side only (Next.js API routes, etc.) | The library calls Linear/Jira APIs directly. **Does NOT work from browser-only SPAs due to CORS.** |
+| Option | Description |
+|--------|-------------|
+| `projectKey` | Jira project key (e.g. `"BUG"`) |
+| `issueType` | Issue type name, defaults to `"Bug"` |
+| `createIssueProxyEndpoint` | Proxy for issue creation (recommended) |
+| `uploadAttachmentProxyEndpoint` | Proxy for attachment uploads (recommended) |
+| `submitProxyEndpoint` | Single endpoint fallback (slower — see [below](#legacy-single-endpoint)) |
+| `baseUrl` | Jira instance URL (direct mode only — not for browser SPAs) |
+| `email` | Jira email (direct mode only) |
+| `apiToken` | Jira API token (direct mode only) |
+| `fetchImpl` | Custom fetch implementation |
 
 ### Linear
 
 ```ts
 import { LinearIntegration } from "quick-bug-reporter-react";
 
-// ✅ Recommended: Backend proxy (works everywhere)
-const linear = new LinearIntegration({
-  submitProxyEndpoint: "/api/bug-report",
-});
-
-// Or split proxy endpoints for finer control:
+// ✅ Recommended: split proxy endpoints (parallel uploads, fastest)
 const linear = new LinearIntegration({
   createIssueProxyEndpoint: "/api/linear/create-issue",
   uploadProxyEndpoint: "/api/linear/upload",
-});
-
-// ⚠️ Direct API — server-side / Next.js API routes only
-const linear = new LinearIntegration({
-  apiKey: "lin_api_...",
   teamId: "TEAM_ID",
   projectId: "PROJECT_ID", // optional — assigns issues to a Linear project
 });
@@ -114,101 +126,62 @@ const linear = new LinearIntegration({
 
 | Option | Description |
 |--------|-------------|
-| `apiKey` | Linear API key (direct mode only) |
 | `teamId` | Linear team ID |
 | `projectId` | Linear project ID — optional, assigns every issue to this project |
-| `submitProxyEndpoint` | Single endpoint that handles the entire submission |
-| `createIssueProxyEndpoint` | Proxy for issue creation only |
-| `uploadProxyEndpoint` | Proxy for file uploads only |
-| `fetchImpl` | Custom fetch implementation |
-
-### Jira
-
-```ts
-import { JiraIntegration } from "quick-bug-reporter-react";
-
-// ✅ Recommended: Backend proxy
-const jira = new JiraIntegration({
-  submitProxyEndpoint: "/api/bug-report",
-});
-
-// Or split proxy endpoints:
-const jira = new JiraIntegration({
-  createIssueProxyEndpoint: "/api/jira/create-issue",
-  uploadAttachmentProxyEndpoint: "/api/jira/upload-attachment",
-  projectKey: "BUG",
-});
-
-// ⚠️ Direct API — server-side only (CORS + exposes credentials)
-const jira = new JiraIntegration({
-  baseUrl: "https://your-domain.atlassian.net",
-  email: "you@example.com",
-  apiToken: "...",
-  projectKey: "BUG",
-  issueType: "Bug", // optional, defaults to "Bug"
-});
-```
-
-| Option | Description |
-|--------|-------------|
-| `baseUrl` | Jira instance URL (direct mode only) |
-| `email` | Jira email (direct mode only) |
-| `apiToken` | Jira API token (direct mode only) |
-| `projectKey` | Jira project key (e.g. `"BUG"`) |
-| `issueType` | Issue type name, defaults to `"Bug"` |
-| `submitProxyEndpoint` | Single endpoint that handles the entire submission |
-| `createIssueProxyEndpoint` | Proxy for issue creation only |
-| `uploadAttachmentProxyEndpoint` | Proxy for attachment uploads only |
+| `createIssueProxyEndpoint` | Proxy for issue creation (recommended) |
+| `uploadProxyEndpoint` | Proxy for file uploads (recommended) |
+| `submitProxyEndpoint` | Single endpoint fallback (slower — see [below](#legacy-single-endpoint)) |
+| `apiKey` | Linear API key (direct mode only — not for browser SPAs) |
 | `fetchImpl` | Custom fetch implementation |
 
 ---
 
-### Proxy endpoint contract
+### Proxy endpoint contract (split endpoints)
 
-When using `submitProxyEndpoint`, the library sends a single `FormData` POST with a **pre-formatted description** and all attachment files. Your proxy just needs to create the issue and upload the files — no custom formatting required.
+With split endpoints the library handles formatting and **uploads attachments in parallel** — your proxy only needs to forward auth. This is ~3× faster than a single endpoint.
 
-#### FormData fields
+#### `createIssueProxyEndpoint`
 
-| Field | Type | Always sent | Description |
-|-------|------|:-----------:|-------------|
-| `provider` | string | Yes | `"linear"` or `"jira"` |
-| `title` | string | Yes | Issue title |
-| `description` | string | Yes | **Pre-formatted** issue description (ready to use as-is) |
-| `issueType` | string | Jira only | Issue type (e.g. `"Bug"`) |
-| `projectKey` | string | Jira only | Jira project key (if configured) |
-| `teamId` | string | Linear only | Linear team ID (if configured) |
-| `projectId` | string | Linear only | Linear project ID (if configured) |
-| `screenshotFile` | File | If screenshot | `bug-screenshot.png` |
-| `screenRecordingFile` | File | If video | `bug-recording.webm` |
-| `networkLogsFile` | File | Yes | `network-logs.txt` |
-| `clientMetadataFile` | File | Yes | `client-metadata.json` |
-| `consoleLogsFile` | File | If present | `console-logs.txt` (JS errors + console output) |
+Receives a JSON POST:
 
-#### Expected response
-
-**Jira proxy:**
 ```json
 {
-  "jira": { "id": "10001", "key": "BUG-42", "url": "https://you.atlassian.net/browse/BUG-42" },
-  "warnings": []
+  "summary": "Bug title",                  // Jira
+  "title": "Bug title",                    // Linear
+  "description": "Pre-formatted description (ready to use as-is)",
+  "issueType": "Bug",                      // Jira only
+  "projectKey": "BUG",                     // Jira only
+  "teamId": "...",                          // Linear only
+  "projectId": "..."                        // Linear only (if configured)
 }
 ```
 
-**Linear proxy:**
+Must return:
+
 ```json
-{
-  "linear": { "id": "...", "identifier": "ENG-123", "url": "https://linear.app/..." },
-  "warnings": []
-}
+// Jira
+{ "id": "10001", "key": "BUG-42", "url": "https://you.atlassian.net/browse/BUG-42" }
+
+// Linear
+{ "id": "...", "identifier": "ENG-123", "url": "https://linear.app/..." }
 ```
 
-#### Example Jira proxy (Node.js / Express)
+#### `uploadAttachmentProxyEndpoint` (Jira)
+
+Receives `FormData` with `issueKey` (string) + `file` (File). Returns `{ "ok": true }`.
+
+#### `uploadProxyEndpoint` (Linear)
+
+Receives `FormData` with `file` (File) + `filename` (string) + `contentType` (string). Returns `{ "assetUrl": "https://..." }`.
+
+#### Example: Jira proxy (Node.js / Express)
 
 ```ts
-app.post("/api/bug-report", upload.any(), async (req, res) => {
-  const { title, description, issueType, projectKey } = req.body;
+// POST /api/jira/create-issue — forward issue creation with auth
+app.post("/api/jira/create-issue", express.json(), async (req, res) => {
+  const { summary, description, issueType, projectKey } = req.body;
 
-  // 1. Convert plain-text description to Jira ADF
+  // Convert plain-text description to Jira ADF
   const adf = {
     type: "doc", version: 1,
     content: description.split(/\n{2,}/).filter(Boolean).map(chunk => ({
@@ -217,8 +190,7 @@ app.post("/api/bug-report", upload.any(), async (req, res) => {
     })),
   };
 
-  // 2. Create the issue
-  const issue = await fetch(`${JIRA_BASE}/rest/api/3/issue`, {
+  const jiraRes = await fetch(`${JIRA_BASE}/rest/api/3/issue`, {
     method: "POST",
     headers: {
       Authorization: `Basic ${btoa(`${JIRA_EMAIL}:${JIRA_TOKEN}`)}`,
@@ -227,38 +199,173 @@ app.post("/api/bug-report", upload.any(), async (req, res) => {
     body: JSON.stringify({
       fields: {
         project: { key: projectKey },
-        summary: title,
+        summary,
         description: adf,
         issuetype: { name: issueType || "Bug" },
       },
     }),
-  }).then(r => r.json());
-
-  // 3. Upload all attachment files
-  for (const file of req.files) {
-    const form = new FormData();
-    form.append("file", file.buffer, file.originalname);
-    await fetch(`${JIRA_BASE}/rest/api/3/issue/${issue.key}/attachments`, {
-      method: "POST",
-      headers: {
-        Authorization: `Basic ${btoa(`${JIRA_EMAIL}:${JIRA_TOKEN}`)}`,
-        "X-Atlassian-Token": "no-check",
-      },
-      body: form,
+  });
+
+  const data = await jiraRes.json();
+  res.status(jiraRes.ok ? 201 : jiraRes.status).json(
+    jiraRes.ok
+      ? { id: data.id, key: data.key, url: `${JIRA_BASE}/browse/${data.key}` }
+      : { error: data.errorMessages?.join("; ") || "Jira issue creation failed" }
+  );
+});
+
+// POST /api/jira/upload-attachment — forward file upload with auth
+app.post("/api/jira/upload-attachment", upload.single("file"), async (req, res) => {
+  const issueKey = req.body.issueKey;
+  const form = new FormData();
+  form.append("file", req.file.buffer, req.file.originalname);
+
+  const jiraRes = await fetch(`${JIRA_BASE}/rest/api/3/issue/${issueKey}/attachments`, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${btoa(`${JIRA_EMAIL}:${JIRA_TOKEN}`)}`,
+      "X-Atlassian-Token": "no-check",
+    },
+    body: form,
+  });
+
+  res.status(jiraRes.ok ? 200 : jiraRes.status).json(
+    jiraRes.ok ? { ok: true } : { error: "Upload failed" }
+  );
+});
+```
+
+#### Example: Linear proxy (Node.js / Express)
+
+Linear uses a **GraphQL API**. Your proxy forwards mutations to `https://api.linear.app/graphql` with the API key server-side.
+
+```ts
+const LINEAR_API = "https://api.linear.app/graphql";
+const LINEAR_API_KEY = process.env.LINEAR_API_KEY; // e.g. "lin_api_..."
+
+// Helper: execute a Linear GraphQL mutation
+async function linearGql(query: string, variables: Record<string, unknown>) {
+  const res = await fetch(LINEAR_API, {
+    method: "POST",
+    headers: {
+      Authorization: LINEAR_API_KEY,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ query, variables }),
+  });
+  const body = await res.json();
+  if (!res.ok || body.errors?.length) {
+    throw new Error(body.errors?.[0]?.message || `Linear API error (${res.status})`);
+  }
+  return body.data;
+}
+
+// POST /api/linear/create-issue — create issue via GraphQL
+app.post("/api/linear/create-issue", express.json(), async (req, res) => {
+  const { title, description, teamId, projectId } = req.body;
+
+  try {
+    const data = await linearGql(
+      `mutation IssueCreate($input: IssueCreateInput!) {
+        issueCreate(input: $input) {
+          success
+          issue { id identifier url }
+        }
+      }`,
+      {
+        input: {
+          title,
+          description,
+          teamId,
+          ...(projectId ? { projectId } : {}),
+        },
+      }
+    );
+
+    const issue = data.issueCreate.issue;
+    res.status(201).json({
+      id: issue.id,
+      identifier: issue.identifier,
+      url: issue.url,
     });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
   }
+});
 
-  res.json({ jira: { id: issue.id, key: issue.key, url: `${JIRA_BASE}/browse/${issue.key}` } });
+// POST /api/linear/upload — upload file via GraphQL fileUpload + PUT
+app.post("/api/linear/upload", upload.single("file"), async (req, res) => {
+  const file = req.file;
+  const contentType = req.body.contentType || file.mimetype;
+  const filename = req.body.filename || file.originalname;
+
+  try {
+    // 1. Request an upload URL from Linear
+    const data = await linearGql(
+      `mutation FileUpload($contentType: String!, $filename: String!, $size: Int!) {
+        fileUpload(contentType: $contentType, filename: $filename, size: $size) {
+          success
+          uploadFile { uploadUrl assetUrl headers { key value } }
+        }
+      }`,
+      { contentType, filename, size: file.size }
+    );
+
+    const { uploadUrl, assetUrl, headers } = data.fileUpload.uploadFile;
+
+    // 2. PUT the file to the upload URL with Linear's signed headers
+    const uploadHeaders: Record<string, string> = {};
+    for (const h of headers) uploadHeaders[h.key] = h.value;
+
+    const uploadRes = await fetch(uploadUrl, {
+      method: "PUT",
+      headers: uploadHeaders,
+      body: file.buffer,
+    });
+
+    if (!uploadRes.ok) throw new Error(`Upload failed (${uploadRes.status})`);
+
+    res.json({ assetUrl });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
 });
 ```
 
-### Advanced: Split proxy endpoints
+> **Key points for Linear proxy implementers:**
+> - The `create-issue` endpoint receives `{ title, description, teamId, projectId }` — use these directly in the `IssueCreateInput` GraphQL mutation. The `description` is already pre-formatted by the library.
+> - The `upload` endpoint must: (1) call `fileUpload` mutation to get a signed upload URL, (2) `PUT` the file binary to that URL with the returned headers, (3) return the `assetUrl`.
+> - `projectId` is optional — only include it in the mutation input if it's present in the request body.
+
+---
+
+### Legacy: single endpoint
+
+`submitProxyEndpoint` bundles everything into one request. The proxy must create the issue **and** upload all attachments server-side, which means uploads happen sequentially and are **~3× slower**. Use split endpoints above instead when possible.
+
+<details>
+<summary>Single endpoint FormData fields (click to expand)</summary>
+
+| Field | Type | Always sent | Description |
+|-------|------|:-----------:|-------------|
+| `provider` | string | Yes | `"linear"` or `"jira"` |
+| `title` | string | Yes | Issue title |
+| `description` | string | Yes | **Pre-formatted** issue description (ready to use as-is) |
+| `issueType` | string | Jira only | Issue type (e.g. `"Bug"`) |
+| `projectKey` | string | Jira only | Jira project key (if configured) |
+| `teamId` | string | Linear only | Linear team ID (if configured) |
+| `projectId` | string | Linear only | Linear project ID (if configured) |
+| `screenshotFile` | File | If screenshot | `bug-screenshot.png` |
+| `screenRecordingFile` | File | If video | `bug-recording.webm` |
+| `networkLogsFile` | File | Yes | `network-logs.txt` |
+| `clientMetadataFile` | File | Yes | `client-metadata.json` |
+| `consoleLogsFile` | File | If present | `console-logs.txt` (JS errors + console output) |
+
+**Jira response:** `{ "jira": { "id": "...", "key": "BUG-42", "url": "..." }, "warnings": [] }`
 
-Instead of a single `submitProxyEndpoint`, you can use separate endpoints for issue creation and file uploads. This gives the **library** full control over formatting while your proxy only handles auth:
+**Linear response:** `{ "linear": { "id": "...", "identifier": "ENG-123", "url": "..." }, "warnings": [] }`
 
-- **`createIssueProxyEndpoint`** — receives `{ title, description, issueType, projectKey }` as JSON, returns `{ id, key, url }`
-- **`uploadAttachmentProxyEndpoint`** (Jira) — receives `FormData` with `issueKey` + `file`, returns `{ ok: true }`
-- **`uploadProxyEndpoint`** (Linear) — receives `FormData` with `file` + `filename` + `contentType`, returns `{ assetUrl }`
+</details>
 
 ### Advanced: Custom fetch
 
@@ -291,6 +398,7 @@ const linear = new LinearIntegration({
 - `ScreenshotCapturer` — HTML-to-canvas screenshot engine
 - `ScreenRecorder` — Screen + mic recording via MediaRecorder
 - `NetworkLogger` — Fetch interception logger
+- `ConsoleCapture` — Console log and JS error capture
 
 ### Integrations