@jarve/bug-reporter 0.4.3 → 1.0.0

package/README.md

@@ -19,6 +19,7 @@ Go to your JARVE Agency dashboard at `/admin/bug-reports/sites` and:
 - Enter your site name and color
 - Click **Generate API Key**
 - Copy the API key (starts with `brk_`)
+- Copy the public Site ID for the same site
 
 ### 2. Install
 
@@ -57,6 +58,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
         <JarveBugReporter
           apiUrl="https://www.jarve.com.au/api/bug-reporter/external"
           apiKey="brk_your_api_key_here"
+          siteId="your_public_site_id"
           user={{ name: 'James', email: 'james@example.com' }}
         >
           {children}
@@ -77,6 +79,7 @@ Click the blue bug icon (bottom-right) to report bugs. They'll appear in your JA
 | ---------------- | --------------------------------- | -------- | -------------------------------------------------------------------------------------- |
 | `apiUrl`         | `string`                          | Yes      | Base URL for the external bug reporter API                                             |
 | `apiKey`         | `string`                          | Yes      | Your site's API key (starts with `brk_`)                                               |
+| `siteId`         | `string`                          | Yes      | Public site identifier used for widget state and labels. Do not derive it from apiKey. |
 | `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                                                                       |

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { JarveTheme } from '@jarve/widget-shared';
 
 type FloatingButtonPosition = 'left' | 'right';
 
@@ -6,35 +7,154 @@ interface BugReporterUser {
     name: string;
     email: string;
 }
+interface ClickedElement {
+    tagName: string;
+    textContent: string | null;
+    className: string;
+    id: string | null;
+    ariaLabel: string | null;
+    dataAttributes: Record<string, string>;
+    selectorPath: string;
+    clickX: number;
+    clickY: number;
+    relativeClickX: number;
+    relativeClickY: number;
+}
+interface CaptureMetadata {
+    pageUrl: string;
+    sectionId: string | null;
+    viewportWidth: number;
+    viewportHeight: number;
+    deviceType: 'desktop' | 'tablet' | 'mobile';
+    browser: string;
+    os: string;
+    timestamp: string;
+    timestampUtc: string;
+    reporterName: string;
+    reporterEmail: string;
+    /**
+     * Public site identifier supplied explicitly by the host app. This is used
+     * for prompt context and client-side draft scoping; it must never be
+     * derived from the secret API key.
+     */
+    siteId: string;
+    screenshotCaptureFailed?: boolean;
+    clickedElement?: ClickedElement;
+}
+interface ConversationMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+interface ConsoleError {
+    message: string;
+    source?: string;
+    lineno?: number;
+    colno?: number;
+    timestamp: string;
+}
+interface FailedNetworkRequest {
+    url: string;
+    hasQueryString: boolean;
+    method: string;
+    status: number;
+    statusText: string;
+    /**
+     * Response body text, truncated to `TRUNCATE_LEN`. Always `null` unless
+     * the consumer opted in via `captureResponseBodies`. See Issue B4 —
+     * bodies routinely contain JWTs, Supabase RLS errors, and Stripe IDs,
+     * so we capture only status metadata by default.
+     */
+    responseBody: string | null;
+    /**
+     * The response `Content-Type` header, captured for every failed request
+     * regardless of the body-capture opt-in. Useful for triage without the
+     * privacy cost of the full body.
+     */
+    contentType: string | null;
+    timestamp: string;
+}
+interface CaptureResult {
+    screenshot: Blob;
+    metadata: CaptureMetadata;
+    consoleErrors: ConsoleError[];
+    networkErrors: FailedNetworkRequest[];
+}
 interface BugReporterApiConfig {
     apiUrl: string;
     apiKey: string;
 }
 
-declare global {
-    interface Window {
-        __jarve_widgets?: Map<string, {
-            type: string;
-            label: string;
-            tooltip: string;
-            iconName: string;
-            accentColor: string;
-            isActive: boolean;
-            trigger: () => void;
-        }>;
-    }
+/**
+ * Payload handed to `onBeforeSubmit` immediately before the widget POSTs
+ * `/submit`. Consumers can mutate/redact in place and return either the
+ * same reference or a freshly built object — whatever is returned replaces
+ * the payload wholesale. See Issue B8.
+ */
+interface BugReportSubmitPayload {
+    metadata: CaptureResult['metadata'];
+    conversation: ConversationMessage[];
+    structuredReport: {
+        summary: string;
+        expected_behavior: string;
+        actual_behavior: string;
+        reproducibility: string;
+        specific_data: string;
+        severity: string;
+    } | undefined;
+    consoleErrors: CaptureResult['consoleErrors'];
+    networkErrors: CaptureResult['networkErrors'];
+    clickedElement: CaptureResult['metadata']['clickedElement'] | null;
 }
+
 interface JarveBugReporterProps {
     /** Base URL for the external bug reporter API (e.g. "https://www.jarve.com.au/api/bug-reporter/external") */
     apiUrl: string;
     /** API key for your site (starts with "brk_") */
     apiKey: string;
+    /**
+     * Public site identifier for this widget install. Used for client-side draft
+     * scoping and prompt context. Must be supplied explicitly by the host app
+     * and must never be derived from the secret API key.
+     */
+    siteId: string;
     /** Optional position for the floating button (default: 'right') */
     buttonPosition?: FloatingButtonPosition;
     /** Optional user info. If not provided, the AI will ask for name/email during the conversation. */
     user?: BugReporterUser;
+    /**
+     * Base z-index for every rendered widget layer (FAB, overlay, modal).
+     * Default `10000`. Raise this when the host application already uses high
+     * z-indexes for its own modals/toasts and the widget needs to sit above
+     * them. See Issue F2.
+     */
+    zIndexBase?: number;
+    /**
+     * When `true`, capture a truncated copy of each failed response body in
+     * addition to status metadata. Default `false`. Response bodies routinely
+     * contain JWTs, Supabase RLS errors exposing schema, and vendor IDs —
+     * only opt in when you have reviewed those privacy implications. See
+     * Issue B4.
+     */
+    captureResponseBodies?: boolean;
+    /**
+     * Color theme for the bug-report modal. Defaults to `'auto'` which
+     * follows `matchMedia('(prefers-color-scheme: dark)')`. Use `'light'` or
+     * `'dark'` to force a palette. The widget owns its own `.dark` class —
+     * consumer apps do not need `darkMode: 'class'` in their Tailwind config.
+     * See Issue E11.
+     */
+    theme?: JarveTheme;
+    /**
+     * Final chance to scrub the bug-report payload before it leaves the
+     * browser. The hook receives the full `/submit` payload and must return
+     * either a replacement object (mutated or rebuilt) or `null`/`false` /
+     * throw to cancel the submit. On cancel the modal stays open with the
+     * draft intact and shows an inline `role="alert"` error so the user can
+     * retry. Async hooks are awaited. See Issue B8.
+     */
+    onBeforeSubmit?: (payload: BugReportSubmitPayload) => BugReportSubmitPayload | null | false | Promise<BugReportSubmitPayload | null | false>;
     children: React.ReactNode;
 }
-declare function JarveBugReporter({ apiUrl, apiKey, user, buttonPosition, children, }: JarveBugReporterProps): react_jsx_runtime.JSX.Element;
+declare function JarveBugReporter({ apiUrl, apiKey, siteId, user, buttonPosition, zIndexBase, captureResponseBodies, theme, onBeforeSubmit, children, }: JarveBugReporterProps): react_jsx_runtime.JSX.Element;
 
-export { type BugReporterApiConfig, type BugReporterUser, type FloatingButtonPosition, JarveBugReporter };
+export { type BugReportSubmitPayload, type BugReporterApiConfig, type BugReporterUser, type FloatingButtonPosition, JarveBugReporter, type JarveBugReporterProps };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { JarveTheme } from '@jarve/widget-shared';
 
 type FloatingButtonPosition = 'left' | 'right';
 
@@ -6,35 +7,154 @@ interface BugReporterUser {
     name: string;
     email: string;
 }
+interface ClickedElement {
+    tagName: string;
+    textContent: string | null;
+    className: string;
+    id: string | null;
+    ariaLabel: string | null;
+    dataAttributes: Record<string, string>;
+    selectorPath: string;
+    clickX: number;
+    clickY: number;
+    relativeClickX: number;
+    relativeClickY: number;
+}
+interface CaptureMetadata {
+    pageUrl: string;
+    sectionId: string | null;
+    viewportWidth: number;
+    viewportHeight: number;
+    deviceType: 'desktop' | 'tablet' | 'mobile';
+    browser: string;
+    os: string;
+    timestamp: string;
+    timestampUtc: string;
+    reporterName: string;
+    reporterEmail: string;
+    /**
+     * Public site identifier supplied explicitly by the host app. This is used
+     * for prompt context and client-side draft scoping; it must never be
+     * derived from the secret API key.
+     */
+    siteId: string;
+    screenshotCaptureFailed?: boolean;
+    clickedElement?: ClickedElement;
+}
+interface ConversationMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+interface ConsoleError {
+    message: string;
+    source?: string;
+    lineno?: number;
+    colno?: number;
+    timestamp: string;
+}
+interface FailedNetworkRequest {
+    url: string;
+    hasQueryString: boolean;
+    method: string;
+    status: number;
+    statusText: string;
+    /**
+     * Response body text, truncated to `TRUNCATE_LEN`. Always `null` unless
+     * the consumer opted in via `captureResponseBodies`. See Issue B4 —
+     * bodies routinely contain JWTs, Supabase RLS errors, and Stripe IDs,
+     * so we capture only status metadata by default.
+     */
+    responseBody: string | null;
+    /**
+     * The response `Content-Type` header, captured for every failed request
+     * regardless of the body-capture opt-in. Useful for triage without the
+     * privacy cost of the full body.
+     */
+    contentType: string | null;
+    timestamp: string;
+}
+interface CaptureResult {
+    screenshot: Blob;
+    metadata: CaptureMetadata;
+    consoleErrors: ConsoleError[];
+    networkErrors: FailedNetworkRequest[];
+}
 interface BugReporterApiConfig {
     apiUrl: string;
     apiKey: string;
 }
 
-declare global {
-    interface Window {
-        __jarve_widgets?: Map<string, {
-            type: string;
-            label: string;
-            tooltip: string;
-            iconName: string;
-            accentColor: string;
-            isActive: boolean;
-            trigger: () => void;
-        }>;
-    }
+/**
+ * Payload handed to `onBeforeSubmit` immediately before the widget POSTs
+ * `/submit`. Consumers can mutate/redact in place and return either the
+ * same reference or a freshly built object — whatever is returned replaces
+ * the payload wholesale. See Issue B8.
+ */
+interface BugReportSubmitPayload {
+    metadata: CaptureResult['metadata'];
+    conversation: ConversationMessage[];
+    structuredReport: {
+        summary: string;
+        expected_behavior: string;
+        actual_behavior: string;
+        reproducibility: string;
+        specific_data: string;
+        severity: string;
+    } | undefined;
+    consoleErrors: CaptureResult['consoleErrors'];
+    networkErrors: CaptureResult['networkErrors'];
+    clickedElement: CaptureResult['metadata']['clickedElement'] | null;
 }
+
 interface JarveBugReporterProps {
     /** Base URL for the external bug reporter API (e.g. "https://www.jarve.com.au/api/bug-reporter/external") */
     apiUrl: string;
     /** API key for your site (starts with "brk_") */
     apiKey: string;
+    /**
+     * Public site identifier for this widget install. Used for client-side draft
+     * scoping and prompt context. Must be supplied explicitly by the host app
+     * and must never be derived from the secret API key.
+     */
+    siteId: string;
     /** Optional position for the floating button (default: 'right') */
     buttonPosition?: FloatingButtonPosition;
     /** Optional user info. If not provided, the AI will ask for name/email during the conversation. */
     user?: BugReporterUser;
+    /**
+     * Base z-index for every rendered widget layer (FAB, overlay, modal).
+     * Default `10000`. Raise this when the host application already uses high
+     * z-indexes for its own modals/toasts and the widget needs to sit above
+     * them. See Issue F2.
+     */
+    zIndexBase?: number;
+    /**
+     * When `true`, capture a truncated copy of each failed response body in
+     * addition to status metadata. Default `false`. Response bodies routinely
+     * contain JWTs, Supabase RLS errors exposing schema, and vendor IDs —
+     * only opt in when you have reviewed those privacy implications. See
+     * Issue B4.
+     */
+    captureResponseBodies?: boolean;
+    /**
+     * Color theme for the bug-report modal. Defaults to `'auto'` which
+     * follows `matchMedia('(prefers-color-scheme: dark)')`. Use `'light'` or
+     * `'dark'` to force a palette. The widget owns its own `.dark` class —
+     * consumer apps do not need `darkMode: 'class'` in their Tailwind config.
+     * See Issue E11.
+     */
+    theme?: JarveTheme;
+    /**
+     * Final chance to scrub the bug-report payload before it leaves the
+     * browser. The hook receives the full `/submit` payload and must return
+     * either a replacement object (mutated or rebuilt) or `null`/`false` /
+     * throw to cancel the submit. On cancel the modal stays open with the
+     * draft intact and shows an inline `role="alert"` error so the user can
+     * retry. Async hooks are awaited. See Issue B8.
+     */
+    onBeforeSubmit?: (payload: BugReportSubmitPayload) => BugReportSubmitPayload | null | false | Promise<BugReportSubmitPayload | null | false>;
     children: React.ReactNode;
 }
-declare function JarveBugReporter({ apiUrl, apiKey, user, buttonPosition, children, }: JarveBugReporterProps): react_jsx_runtime.JSX.Element;
+declare function JarveBugReporter({ apiUrl, apiKey, siteId, user, buttonPosition, zIndexBase, captureResponseBodies, theme, onBeforeSubmit, children, }: JarveBugReporterProps): react_jsx_runtime.JSX.Element;
 
-export { type BugReporterApiConfig, type BugReporterUser, type FloatingButtonPosition, JarveBugReporter };
+export { type BugReportSubmitPayload, type BugReporterApiConfig, type BugReporterUser, type FloatingButtonPosition, JarveBugReporter, type JarveBugReporterProps };