@bugport.ai/widget 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BugPort
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# `@bugport.ai/widget`
+
+Install the BugPort customer-facing bug reporting widget:
+
+```bash
+npm install @bugport.ai/widget
+```
+
+React usage:
+
+```tsx
+import { BugPortWidget } from '@bugport.ai/widget'
+
+export function App() {
+  return (
+    <BugPortWidget
+      projectKey='bp_pub_xxxxx'
+      environment='staging'
+      apiBaseUrl='http://localhost:8000/v1'
+      user={{
+        id: 'user_123',
+        email: 'qa@example.com',
+        name: 'QA Reviewer',
+      }}
+    />
+  )
+}
+```
+
+`publicKey` is also accepted as an alias for `projectKey` when you want the prop name to match the dashboard/widget-key terminology.
+
+Imperative mounting:
+
+```ts
+import { initBugPortWidget } from '@bugport.ai/widget'
+
+const widget = initBugPortWidget({
+  projectKey: 'bp_pub_xxxxx',
+  environment: 'staging',
+  apiBaseUrl: 'http://localhost:8000/v1',
+})
+
+// later
+widget.destroy()
+```
+
+`window.BugPort.init(...)` is also registered automatically when the package runs in a browser bundle.
+
+> A CDN/IIFE single-file build is not published yet — the package targets bundler (ESM/CJS) consumers.
+
+## Project key setup
+
+1. In the BugPort dashboard, open your project → **Widget keys**.
+2. Create a key for the environment you are embedding in (e.g. `staging`,
+   `production`).
+3. Copy the public key (`bp_pub_…`) and pass it as `projectKey`.
+
+## Allowed origins
+
+Widget keys are origin-restricted. Add every site origin that will load the
+widget (e.g. `https://app.yourcompany.com`) to the key's **allowed origins** in
+the dashboard, or submissions will be rejected.
+
+## Configuration
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `projectKey` / `publicKey` | `string` | — | Public widget key (`bp_pub_…`). Required. |
+| `environment` | `string` | key default | Matches the widget key environment. |
+| `apiBaseUrl` | `string` | `https://api.bugport.ai/v1` | Override for local/self-hosted API. |
+| `user` | `{ id?, email?, name?, role? }` | — | Optional reporter identity. `role` is a staff hint (see accessibility scan below). |
+| `projectId` | `string` | — | BugPort project id — required only for the staff accessibility scan. |
+| `diagnostics` | `BugPortDiagnosticsConfig` | disabled | Optional in-page console/network capture (see below). |
+
+## Events / callbacks
+
+| Callback | Fires when |
+|----------|-----------|
+| `onSubmitted(result)` | A bug was successfully submitted (`result` includes the dashboard URL). |
+| `onError(error)` | Submission or capture failed. |
+| `onSubmitPayload(payload)` | Before submit — inspect/augment the outgoing payload. |
+
+## Privacy / captured data
+
+The widget captures only what the reporter triggers: feedback text,
+annotations, an optional screenshot, and page context (URL, viewport, user
+agent). Screenshots are optional. Provide a `user` only if you want to
+attribute reports.
+
+## Diagnostics (console & network capture)
+
+Optionally attach in-page diagnostics — console logs, runtime errors, and
+fetch/XHR network activity — so a bug report carries the context an engineer
+needs. **Off by default**; nothing is instrumented until you opt in.
+
+```tsx
+<BugPortWidget
+  projectKey="bp_pub_xxxxx"
+  diagnostics={{
+    enabled: true,
+    console: true,
+    runtimeErrors: true,
+    network: true,        // fetch + XHR
+    requestBodies: false, // bodies are off by default (privacy)
+    responseBodies: false,
+    userControlled: true, // show end-user attach toggles in the report form
+    deniedUrls: [/\/auth\//, 'https://api.stripe.com'],
+  }}
+/>
+```
+
+Privacy safeguards: request/response bodies are **opt-in**; common secrets
+(auth headers, tokens, password-like values) are **redacted** by default
+(`redactHeaders` / `redactPatterns` extend this); `allowedUrls` / `deniedUrls`
+scope what network traffic is captured; and `userControlled` lets the reporter
+decide what to attach. Buffer sizes are bounded via the `max*Events` options.
+
+The collector lifecycle is managed for you — instrumentation installs on mount
+and is fully removed on unmount. Lower-level helpers (`DiagnosticsCollector`,
+`buildDiagnosticsPayload`, the `redact*` utilities) are also exported for
+advanced use.
+
+## Accessibility
+
+**WCAG picker.** The report form includes a collapsed, optional "Accessibility
+(WCAG)" section where reporters can tag a bug with a WCAG 2.2 success
+criterion and conformance level. Level A and AA criteria are listed (grouped
+by POUR principle); AAA or future criteria can be entered via the free-text
+"Other criterion" option. The picked values are submitted as
+`wcagCriterion` / `wcagLevel`.
+
+**Staff page scan.** When `user.role` is one of `qa`, `qa_tester`, `staff`,
+`admin`, `owner`, or `internal` (case-insensitive) and a `projectId` is
+configured, the panel shows a staff-only "Scan this page" action that runs an
+axe-core accessibility check of the live page and files the findings to
+BugPort. Notes:
+
+- The role hint is a **UX gate only** — it is spoofable by design and is never
+  sent to the server. The API authenticates with the widget key and enforces a
+  rate limit of 10 scans per hour per key regardless of role.
+- axe-core is **not** in the widget's base bundle. It is declared as a regular
+  dependency and loaded through a dynamic `import("axe-core")` only when a
+  staff user activates the scan, so your bundler emits it as a separate lazy
+  chunk that end users never download.
+
+## Troubleshooting
+
+- **Submissions rejected (403/origin)** → add your site origin to the widget
+  key's allowed origins.
+- **Requests 404** → check `apiBaseUrl`; it must resolve to a BugPort API base
+  ending in `/v1`.
+- **Nothing renders** → ensure React 18+ is installed (peer dependency) and the
+  component is mounted client-side.
+
+## License
+
+MIT © BugPort. See [LICENSE](./LICENSE).