@koderlabs/tasks-sdk-web-reporter

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).

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.

This package replaces the v0 @koderlabs/tasks-widget. The factory function widgetIntegration is kept as a deprecated alias.

Install

npm install @koderlabs/tasks-sdk @koderlabs/tasks-sdk-web-reporter
# or
pnpm add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-web-reporter
# or
yarn add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-web-reporter

Usage

import { init } from '@koderlabs/tasks-sdk';
import { reporterIntegration } from '@koderlabs/tasks-sdk-web-reporter';

const reporter = reporterIntegration({
  hotkey: 'mod+shift+b',         // 'mod' = Cmd on macOS, Ctrl elsewhere
  autoInject: true,              // floating action button bottom-right
  useNativeScreenshot: true,     // getDisplayMedia (prompts once / session)
  autoCapture: true,             // snap immediately when modal opens
  showBranding: true,
});

init({
  projectId: 'FE',
  accessKey: 'sk_live_…',
  integrations: [reporter],
});

// Imperative API
reporter.show();
reporter.setReporter({ email: '[email protected]', fullName: 'Jane Doe' });
reporter.on('feedbacksent', (e) => console.log('ticket', e.ticketKey, e.ticketUrl));

reporterIntegration(opts)

| Option | Type | Default | Notes | |---|---|---|---| | hotkey | string \| false | mod+shift+b | E.g. ctrl+shift+i. false disables. Server config can override. | | autoInject | boolean | true | Inject the floating bug button. Server-side showFab overrides when caller didn't pass it. | | useNativeScreenshot | boolean | true | Prefer getDisplayMedia over html2canvas. Pixel-perfect; one-time browser permission. | | autoCapture | boolean | true | Capture on modal open instead of requiring a button click. | | showBranding | boolean | true | "Powered by InstantTasks" footer. | | reporter | { email, fullName? } | — | Pre-fill reporter identity. | | customData | Record<string, Serializable> | — | Appended to every submission. | | collectEmail | boolean | false | Show email input in the form. | | silent | boolean | false | Suppress console diagnostics. | | 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. | | networkRecording | { enabled?, excludedKeys?, excludedDomains? } | — | Reserved for upcoming integration with web-network. |

Remote config

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.

If the fetch fails (offline, 401, etc.) the local defaults are kept — the widget never silently disappears.

WidgetApi

| Method | Purpose | |---|---| | show(), hide(), isVisible() | Modal control. | | capture(mode?) | v1: alias for show(). Mode selector deferred. | | cancelCapture() | Close without submitting. | | setReporter(info), clearReporter() | Reporter identity. | | setCustomData(data) | Merge into custom-data envelope. | | setNetworkRecordingSettings(s) | Set excludedKeys/excludedDomains. | | on(event, listener), off(event, listener) | Event bus. | | unload() | Tear down (hotkey, FAB, modal). |

Events

load, loaderror, show, hide, capture, feedbackbeforesend, feedbacksent, feedbackerror, feedbackdiscarded.

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.

Other exports

• reporterIntegration (preferred factory)
• widgetIntegration — deprecated alias of reporterIntegration, kept for backwards compat with v0.
• ReporterIntegration, WidgetIntegration — class export for new ReporterIntegration() usage.
• isNativeCaptureSupported() — feature-detect getDisplayMedia.
• parseHotkey, registerHotkey — hotkey utilities.
• collectMetadata, formatMetadataBlock, patchConsole — metadata utilities.

Caveats

• 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.
• 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.
• 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.
• exposeGlobal defaults to on in non-production, off in production. Override explicitly if you have a non-production env on NODE_ENV=production.
• The widget submits as a Ticket via the SDK ingest endpoint; the response payload { ticketKey, ticketUrl } is fired on feedbacksent.

Suite overview

Full SDK suite map + platform availability matrix: docs/sdk/overview.md.

License

KoderLabs proprietary. See LICENSE for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.

Licensing inquiries: [email protected]