@koderlabs/tasks-sdk-web-reporter 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +109 -5
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,9 +1,113 @@
1
- # Proprietary Software
1
+ # @koderlabs/tasks-sdk-web-reporter
2
2
 
3
- KoderLabs proprietary. All rights reserved.
3
+ > Runtime: browser DOM only — requires `document`, `window`, shadow-DOM, `getDisplayMedia` (for native screenshots). For mobile bug-reporter use `@koderlabs/tasks-sdk-rn` (Phase 2b — not yet shipped).
4
4
 
5
- See the bundled `LICENSE` for terms. No grant of any rights, express or
6
- implied, is conferred by access to or possession of this package. A
7
- separate signed written licence from KoderLabs is required for any use.
5
+ In-app bug reporter for browser apps. Renders a Shadow-DOM modal with a screenshot capture + annotator (highlight / hide), a description field, and submits the result as a Ticket against the configured InstantTasks project.
6
+
7
+ This package replaces the v0 `@koderlabs/tasks-widget`. The factory function `widgetIntegration` is kept as a deprecated alias.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ npm install @koderlabs/tasks-sdk @koderlabs/tasks-sdk-web-reporter
13
+ # or
14
+ pnpm add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-web-reporter
15
+ # or
16
+ yarn add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-web-reporter
17
+ ```
18
+
19
+ ## Usage
20
+
21
+ ```ts
22
+ import { init } from '@koderlabs/tasks-sdk';
23
+ import { reporterIntegration } from '@koderlabs/tasks-sdk-web-reporter';
24
+
25
+ const reporter = reporterIntegration({
26
+ hotkey: 'mod+shift+b', // 'mod' = Cmd on macOS, Ctrl elsewhere
27
+ autoInject: true, // floating action button bottom-right
28
+ useNativeScreenshot: true, // getDisplayMedia (prompts once / session)
29
+ autoCapture: true, // snap immediately when modal opens
30
+ showBranding: true,
31
+ });
32
+
33
+ init({
34
+ projectId: 'FE',
35
+ accessKey: 'sk_live_…',
36
+ integrations: [reporter],
37
+ });
38
+
39
+ // Imperative API
40
+ reporter.show();
41
+ reporter.setReporter({ email: 'user@example.com', fullName: 'Jane Doe' });
42
+ reporter.on('feedbacksent', (e) => console.log('ticket', e.ticketKey, e.ticketUrl));
43
+ ```
44
+
45
+ ## `reporterIntegration(opts)`
46
+
47
+ | Option | Type | Default | Notes |
48
+ |---|---|---|---|
49
+ | `hotkey` | `string \| false` | `mod+shift+b` | E.g. `ctrl+shift+i`. `false` disables. Server config can override. |
50
+ | `autoInject` | `boolean` | `true` | Inject the floating bug button. Server-side `showFab` overrides when caller didn't pass it. |
51
+ | `useNativeScreenshot` | `boolean` | `true` | Prefer `getDisplayMedia` over `html2canvas`. Pixel-perfect; one-time browser permission. |
52
+ | `autoCapture` | `boolean` | `true` | Capture on modal open instead of requiring a button click. |
53
+ | `showBranding` | `boolean` | `true` | "Powered by InstantTasks" footer. |
54
+ | `reporter` | `{ email, fullName? }` | — | Pre-fill reporter identity. |
55
+ | `customData` | `Record<string, Serializable>` | — | Appended to every submission. |
56
+ | `collectEmail` | `boolean` | `false` | Show email input in the form. |
57
+ | `silent` | `boolean` | `false` | Suppress console diagnostics. |
58
+ | `exposeGlobal` | `boolean` | non-prod | Expose `window.InstantTasks.show()` for DevTools. **Off in production** by default — any 3rd-party script on the page could otherwise trigger the widget. |
59
+ | `networkRecording` | `{ enabled?, excludedKeys?, excludedDomains? }` | — | Reserved for upcoming integration with `web-network`. |
60
+
61
+ ## Remote config
62
+
63
+ On `setup()` the integration fetches `GET /api/v1/sdk/v1/config` using the caller's access key. Server-side `sdkConfig` (`hotkey`, `showFab`, `enabled`) overrides any field the integrator did **not** explicitly pass. Explicit options always win. If `enabled: false` is set server-side, the hotkey and FAB are both forced off.
64
+
65
+ If the fetch fails (offline, 401, etc.) the local defaults are kept — the widget never silently disappears.
66
+
67
+ ## `WidgetApi`
68
+
69
+ | Method | Purpose |
70
+ |---|---|
71
+ | `show()`, `hide()`, `isVisible()` | Modal control. |
72
+ | `capture(mode?)` | v1: alias for `show()`. Mode selector deferred. |
73
+ | `cancelCapture()` | Close without submitting. |
74
+ | `setReporter(info)`, `clearReporter()` | Reporter identity. |
75
+ | `setCustomData(data)` | Merge into custom-data envelope. |
76
+ | `setNetworkRecordingSettings(s)` | Set excludedKeys/excludedDomains. |
77
+ | `on(event, listener)`, `off(event, listener)` | Event bus. |
78
+ | `unload()` | Tear down (hotkey, FAB, modal). |
79
+
80
+ ## Events
81
+
82
+ `load`, `loaderror`, `show`, `hide`, `capture`, `feedbackbeforesend`, `feedbacksent`, `feedbackerror`, `feedbackdiscarded`.
83
+
84
+ `feedbackbeforesend` is mutable — set `assignee`, `labels`, `customFields`, `priority`, `issueType` via `setValue(field, value)`. Call `cancel()` to abort the submission. `description`, `title`, `email`, `screenshot` are **not** mutable here.
85
+
86
+ ## Other exports
87
+
88
+ - `reporterIntegration` (preferred factory)
89
+ - `widgetIntegration` — **deprecated alias** of `reporterIntegration`, kept for backwards compat with v0.
90
+ - `ReporterIntegration`, `WidgetIntegration` — class export for `new ReporterIntegration()` usage.
91
+ - `isNativeCaptureSupported()` — feature-detect `getDisplayMedia`.
92
+ - `parseHotkey`, `registerHotkey` — hotkey utilities.
93
+ - `collectMetadata`, `formatMetadataBlock`, `patchConsole` — metadata utilities.
94
+
95
+ ## Caveats
96
+
97
+ - DOM only — calling `reporterIntegration()` on Node will throw the first time it tries to read `document`. Guard with `typeof window !== 'undefined'` in SSR code or only register the integration in `useEffect`.
98
+ - `useNativeScreenshot: true` prompts the user to share their screen the first time per session. On WebGL / cross-origin-iframe pages this is the only way to get a faithful screenshot — `html2canvas` cannot render those.
99
+ - The FAB lives in its own shadow host on `document.body` so styles don't leak in either direction. Both the FAB and modal are hidden from screenshots during capture.
100
+ - `exposeGlobal` defaults to **on** in non-production, **off** in production. Override explicitly if you have a non-production env on `NODE_ENV=production`.
101
+ - The widget submits as a Ticket via the SDK ingest endpoint; the response payload `{ ticketKey, ticketUrl }` is fired on `feedbacksent`.
102
+
103
+ ---
104
+
105
+ ## Suite overview
106
+
107
+ Full SDK suite map + platform availability matrix: [docs/sdk/overview.md](https://github.com/jawaidgadiwala/instant-tasks/blob/main/docs/sdk/overview.md).
108
+
109
+ ## License
110
+
111
+ KoderLabs proprietary. See [`LICENSE`](./LICENSE) for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.
8
112
 
9
113
  Licensing inquiries: jawaidgadiwala@gmail.com
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@koderlabs/tasks-sdk-web-reporter",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Browser in-app bug-report modal + screenshot capture for the InstantTasks SDK.",
5
5
  "keywords": [
6
6
  "instanttasks",
@@ -41,7 +41,7 @@
41
41
  ],
42
42
  "sideEffects": true,
43
43
  "dependencies": {
44
- "@koderlabs/tasks-sdk": "0.1.0"
44
+ "@koderlabs/tasks-sdk": "0.1.2"
45
45
  },
46
46
  "peerDependencies": {
47
47
  "html2canvas": "^1.4.1"
@@ -61,7 +61,7 @@
61
61
  "node": ">=20"
62
62
  },
63
63
  "publishConfig": {
64
- "access": "restricted"
64
+ "access": "public"
65
65
  },
66
66
  "scripts": {
67
67
  "build": "tsup",