@koderlabs/tasks-sdk-web-reporter 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,362 @@
+import { Integration, ClientInterface } from '@koderlabs/tasks-sdk';
+import { Serializable } from '@koderlabs/tasks-sdk-types';
+
+interface DrawCommand {
+    /** 'highlight' = red cutout rect with dim overlay; 'hide' = opaque black box */
+    type: 'highlight' | 'hide';
+    /** Normalized 0..1 against captured-image width */
+    x: number;
+    /** Normalized 0..1 against captured-image height */
+    y: number;
+    /** Normalized 0..1 width */
+    w: number;
+    /** Normalized 0..1 height */
+    h: number;
+}
+type WidgetApi = {
+    show(): void;
+    hide(): void;
+    isVisible(): boolean;
+    capture(mode?: 'fullscreen' | 'advanced'): Promise<void>;
+    cancelCapture(): void;
+    setReporter(info: {
+        email: string;
+        fullName?: string;
+    }): void;
+    clearReporter(): void;
+    setCustomData(data?: Record<string, Serializable>): void;
+    setNetworkRecordingSettings(s: {
+        excludedKeys?: string[];
+        excludedDomains?: string[];
+    }): void;
+    on(event: WidgetEventName, listener: (e: WidgetEvent) => void): void;
+    off(event: WidgetEventName, listener: (e: WidgetEvent) => void): void;
+    unload(): void;
+};
+type WidgetEventName = 'load' | 'loaderror' | 'show' | 'hide' | 'capture' | 'feedbackbeforesend' | 'feedbacksent' | 'feedbackerror' | 'feedbackdiscarded';
+/** Mutable fields in feedbackbeforesend — cannot mutate description/screenshot */
+type MutableFeedbackField = 'assignee' | 'labels' | 'customFields' | 'priority' | 'issueType';
+interface BeforeSendPayload {
+    values: {
+        description: string;
+        title?: string;
+        email?: string;
+        assignee?: string;
+        labels?: string[];
+        customFields?: Record<string, unknown>;
+        priority?: string;
+        issueType?: string;
+    };
+    setValue(field: MutableFeedbackField, value: unknown): void;
+    cancel(): void;
+}
+type WidgetEvent = {
+    name: 'load';
+} | {
+    name: 'loaderror';
+    error: Error;
+} | {
+    name: 'show';
+} | {
+    name: 'hide';
+} | {
+    name: 'capture';
+    canvas: HTMLCanvasElement;
+} | (BeforeSendPayload & {
+    name: 'feedbackbeforesend';
+}) | {
+    name: 'feedbacksent';
+    ticketKey: string;
+    ticketUrl: string;
+} | {
+    name: 'feedbackerror';
+    error: Error;
+} | {
+    name: 'feedbackdiscarded';
+};
+interface NetworkRecordingSettings {
+    enabled?: boolean;
+    excludedKeys?: string[];
+    excludedDomains?: string[];
+}
+interface WidgetOptions {
+    /**
+     * Hotkey string, e.g. 'ctrl+shift+i'. Set to false to disable.
+     * Mac users should use 'meta+shift+i' or keep ctrl for cross-platform.
+     */
+    hotkey?: string | false;
+    /** Auto-inject a floating trigger button into the host page. Default: true. */
+    autoInject?: boolean;
+    /** Prefer getDisplayMedia (asks browser permission, pixel-perfect) over
+     *  html2canvas (no prompt, DOM-rendered). Default: false — seamless UX.
+     *  Flip to true when the page has WebGL / cross-origin iframes / canvas
+     *  content html2canvas can't render. */
+    useNativeScreenshot?: boolean;
+    /** Capture screenshot automatically when the widget opens, instead of
+     *  requiring an explicit click. Default: true. Set false to keep the
+     *  "Add Screenshot" button as the trigger. */
+    autoCapture?: boolean;
+    /** Show "Powered by InstantTasks" branding. Default: true. */
+    showBranding?: boolean;
+    /** Default reporter info. Can be overridden via setReporter(). */
+    reporter?: {
+        email: string;
+        fullName?: string;
+    };
+    /** Arbitrary key/value appended to every submission. */
+    customData?: Record<string, Serializable>;
+    /** Whether to ask the user for their email. Default: false. */
+    collectEmail?: boolean;
+    /** Suppress console diagnostics. Default: false. */
+    silent?: boolean;
+    /**
+     * Expose `window.InstantTasks.show()` for manual triggering from DevTools.
+     * Default: true in non-production, false in production. In production this
+     * defaults off because any third-party script (analytics, A/B testing,
+     * vendor injects) can read `window.InstantTasks` and trigger the widget.
+     */
+    exposeGlobal?: boolean;
+    /** Network recording settings. */
+    networkRecording?: NetworkRecordingSettings;
+}
+
+/**
+ * Capability detection for native screenshot capture.
+ * Ported from: sentry-javascript/packages/feedback/src/util/isScreenshotSupported.ts
+ *
+ * Returns false on:
+ * - Mobile UA (Android, iPhone, iPad via UA, etc.)
+ * - iPad-as-Mac (Macintosh UA with maxTouchPoints > 1)
+ * - Insecure context (non-HTTPS except localhost)
+ * - Missing getDisplayMedia API
+ */
+declare function isNativeCaptureSupported(): boolean;
+
+/**
+ * Hotkey parser and listener factory.
+ *
+ * Parses strings like 'ctrl+shift+i', 'meta+shift+i'.
+ * Modifiers: ctrl, meta, alt, shift (order-insensitive).
+ * Ignores keypresses when the focused element is an input, textarea,
+ * or any contenteditable element (to avoid interfering with user typing).
+ */
+interface ParsedHotkey {
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+    key: string;
+}
+/**
+ * Parse a hotkey string into a structured predicate.
+ * Returns null for invalid or falsy input.
+ */
+declare function parseHotkey(raw: string | false | undefined): ParsedHotkey | null;
+/**
+ * Register a keydown listener for the given hotkey string.
+ * Returns a cleanup function to remove the listener.
+ *
+ * @param hotkeyStr - e.g. 'ctrl+shift+i' or false to disable.
+ * @param handler - Called when the hotkey fires outside typing targets.
+ * @param target - Element to attach to (defaults to window).
+ */
+declare function registerHotkey(hotkeyStr: string | false | undefined, handler: () => void, target?: EventTarget): () => void;
+
+/**
+ * Metadata collector.
+ *
+ * Collects:
+ *   - url: current window.location.href
+ *   - userAgent: navigator.userAgent
+ *   - viewport: { width, height }
+ *   - appVersion: from <meta name="app-version" content="…"> if present
+ *   - consoleTail: last N console messages (ring buffer, opt-in via captureConsole)
+ *   - customData: lazy callback result (Jam-style pattern)
+ */
+
+interface ConsoleEntry {
+    level: 'log' | 'warn' | 'error' | 'info' | 'debug';
+    args: string[];
+    ts: number;
+}
+interface BrowserInfo {
+    name?: string;
+    version?: string;
+    major?: string;
+    mobile?: boolean;
+}
+interface OsInfo {
+    name?: string;
+    version?: string;
+}
+interface DeviceInfo {
+    deviceMemoryGB?: number;
+    hardwareConcurrency?: number;
+    jsHeapUsedMB?: number;
+    jsHeapTotalMB?: number;
+}
+interface NetworkInfo {
+    online?: boolean;
+    effectiveType?: string;
+    downlinkMbps?: number;
+    rttMs?: number;
+    saveData?: boolean;
+}
+interface CollectedMetadata {
+    url: string;
+    userAgent: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    appVersion?: string;
+    consoleTail?: ConsoleEntry[];
+    customData?: Record<string, Serializable>;
+    /** Physical screen resolution (independent of window size). */
+    screen?: {
+        width: number;
+        height: number;
+        dpr: number;
+    };
+    /** Parsed from userAgentData (Chromium) or UA regex. */
+    browser?: BrowserInfo;
+    /** Parsed OS name + version. */
+    os?: OsInfo;
+    /** Hardware capabilities. */
+    device?: DeviceInfo;
+    /** Network conditions at submit time. */
+    network?: NetworkInfo;
+    /** BCP-47 language tags from `navigator.languages`. */
+    languages?: string[];
+    /** IANA timezone name (e.g. `America/New_York`). */
+    timezone?: string;
+    /** UTC offset in minutes at submit time. */
+    timezoneOffsetMin?: number;
+    /** User-agent preference signals. */
+    preferences?: {
+        colorScheme?: 'light' | 'dark';
+        reducedMotion?: boolean;
+        contrast?: 'no-preference' | 'more' | 'less';
+    };
+    /** Document referrer at the moment of the report. */
+    referrer?: string;
+    /** Navigation timing snapshot — useful for "was the page slow?" reports. */
+    pageLoad?: {
+        domContentLoadedMs?: number;
+        loadCompleteMs?: number;
+        ttfbMs?: number;
+    };
+    /** Wall-clock at submit time (server already has receive time; this is the user's). */
+    clientTime?: string;
+}
+/** Patch global console to capture a ring buffer of log calls. */
+declare function patchConsole(): () => void;
+/**
+ * Collect current-page metadata snapshot.
+ *
+ * @param captureConsole - Include console ring buffer. Default: false.
+ * @param customDataFn   - Lazy callback that returns extra key/value data.
+ */
+declare function collectMetadata(captureConsole?: boolean, customDataFn?: () => Record<string, Serializable> | Promise<Record<string, Serializable>>): Promise<CollectedMetadata>;
+/**
+ * Format collected metadata as a collapsible markdown block.
+ * Appended to the ticket description body.
+ */
+/**
+ * Format collected metadata as an HTML block.
+ *
+ * Output is HTML — not markdown — because ticket descriptions in
+ * InstantTasks are stored as TipTap-compatible HTML and the renderer
+ * does NOT post-process markdown. Returning `**bold**` and bare `\n`
+ * would render as literal asterisks on one collapsed line.
+ */
+declare function formatMetadataBlock(meta: CollectedMetadata): string;
+
+/**
+ * @koderlabs/tasks-sdk-web-reporter
+ *
+ * Browser in-app bug-reporter integration for the InstantTasks SDK.
+ * `reporterIntegration(opts)` (alias: `widgetIntegration` for back-compat).
+ *
+ * Usage:
+ *   import { init } from '@koderlabs/tasks-sdk';
+ *   import { reporterIntegration } from '@koderlabs/tasks-sdk-web-reporter';
+ *
+ *   const client = init({
+ *     projectId: 'FE',
+ *     accessKey: 'sk_live_…',
+ *     integrations: [reporterIntegration({ hotkey: 'ctrl+shift+i' })],
+ *   });
+ */
+
+type Listener = (e: WidgetEvent) => void;
+declare class WidgetIntegration implements Integration {
+    readonly name = "widget";
+    private opts;
+    /** Caller-supplied options, before defaults were applied. Used to decide
+     *  which fields can be overwritten by server-side project config. */
+    private _initialOpts;
+    private client;
+    private shell;
+    private fabBtn;
+    /** Outer shadow-host element for the FAB. Tracked separately from the
+     *  button so capture flows can hide the *entire* widget chrome (not just
+     *  the modal) from screenshots. */
+    private fabHost;
+    private _visible;
+    private _reporter;
+    private _customData;
+    /** Reserved for upcoming network capture filters (Phase I).
+     *  Public so the field stays type-checked and isn't tree-shaken; safe to
+     *  read but currently has no effect. */
+    networkSettings: {
+        excludedKeys?: string[];
+        excludedDomains?: string[];
+    };
+    private listeners;
+    private cleanupHotkey;
+    private cleanupConsole;
+    constructor(opts: WidgetOptions);
+    setup(client: ClientInterface): void;
+    /**
+     * GET /sdk/v1/config — uses the SDK's own configured endpoint + access
+     * key (the client already has both). Merges into this.opts only for
+     * fields the caller didn't explicitly set.
+     */
+    private _applyRemoteConfig;
+    /** Wires hotkey + FAB + debug surface. Called after _applyRemoteConfig. */
+    private _wireRuntime;
+    teardown(): void;
+    show(): void;
+    hide(): void;
+    isVisible(): boolean;
+    capture(mode?: 'fullscreen' | 'advanced'): Promise<void>;
+    cancelCapture(): void;
+    setReporter(info: {
+        email: string;
+        fullName?: string;
+    }): void;
+    clearReporter(): void;
+    setCustomData(data?: Record<string, unknown>): void;
+    setNetworkRecordingSettings(s: {
+        excludedKeys?: string[];
+        excludedDomains?: string[];
+    }): void;
+    on(event: WidgetEventName, listener: Listener): void;
+    off(event: WidgetEventName, listener: Listener): void;
+    unload(): void;
+    private _openModal;
+    private _injectFab;
+    private _emit;
+}
+/**
+ * Create an in-app reporter integration for the InstantTasks SDK client.
+ *
+ * @param opts - Reporter configuration options.
+ * @returns An Integration that can be passed to `init({ integrations: [...] })`.
+ */
+declare function reporterIntegration(opts?: WidgetOptions): Integration & WidgetApi;
+/** @deprecated Renamed to `reporterIntegration`. Will be removed in v1. */
+declare const widgetIntegration: typeof reporterIntegration;
+
+export { type DrawCommand, WidgetIntegration as ReporterIntegration, type WidgetApi, type WidgetEvent, type WidgetEventName, WidgetIntegration, type WidgetOptions, collectMetadata, reporterIntegration as default, formatMetadataBlock, isNativeCaptureSupported, parseHotkey, patchConsole, registerHotkey, reporterIntegration, widgetIntegration };