@bugport.dev/widget 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,576 @@
+import * as react from 'react';
+
+/** Intent the author attaches to a piece of feedback. */
+type AnnotationIntent = "fix" | "change" | "question" | "approve";
+/** How severe / blocking a piece of feedback is. */
+type AnnotationSeverity = "blocking" | "important" | "suggestion";
+/** Lifecycle position of an annotation. */
+type AnnotationStatus = "pending" | "acknowledged" | "resolved" | "dismissed";
+/**
+ * Axis-aligned rectangle expressed in CSS pixels. Reused for bounding boxes,
+ * placement geometry, and the original/current rects of a rearrange action.
+ */
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Structured payload carried by `kind: "placement"` annotations, describing a
+ * component the author wants dropped onto the page.
+ */
+type PlacementDetails = {
+    componentType: string;
+    width: number;
+    height: number;
+    scrollY: number;
+    text?: string;
+};
+/**
+ * Structured payload carried by `kind: "rearrange"` annotations, capturing
+ * where an existing element started and where it was moved to.
+ */
+type RearrangeDetails = {
+    selector: string;
+    label: string;
+    tagName: string;
+    originalRect: Rect;
+    currentRect: Rect;
+};
+/**
+ * The central feedback shape. Exactly seven fields are required — `id`, `x`,
+ * `y`, `comment`, `element`, `elementPath`, and `timestamp`. Everything else is
+ * optional and may be populated as the annotation gains DOM/React context, is
+ * specialised by `kind`, or is synced to the server.
+ */
+type Annotation = {
+    id: string;
+    /** Horizontal position as a percentage of the viewport width. */
+    x: number;
+    /**
+     * Vertical position in pixels — measured from the top of the document
+     * (absolute), or from the top of the viewport when `isFixed` is set.
+     */
+    y: number;
+    comment: string;
+    element: string;
+    elementPath: string;
+    timestamp: number;
+    selectedText?: string;
+    boundingBox?: Rect;
+    nearbyText?: string;
+    cssClasses?: string;
+    nearbyElements?: string;
+    computedStyles?: string;
+    fullPath?: string;
+    accessibility?: string;
+    /** True when the annotation was produced by a drag selection. */
+    isMultiSelect?: boolean;
+    /**
+     * True when the target element uses fixed/sticky positioning, in which case
+     * the marker is pinned to the viewport rather than the document.
+     */
+    isFixed?: boolean;
+    /** React component hierarchy string, e.g. "<App> <Dashboard> <Button>". */
+    reactComponents?: string;
+    /**
+     * Source path derived from React's `_debugSource` (dev mode only),
+     * e.g. "src/Button.tsx:42".
+     */
+    sourceFile?: string;
+    /** Index of a linked drawing stroke, when one exists. */
+    drawingIndex?: number;
+    /** Per-element boxes used to highlight a multi-select on hover. */
+    elementBoundingBoxes?: Rect[];
+    /** Annotation flavour. Consumers treat an absent value as "feedback". */
+    kind?: "feedback" | "placement" | "rearrange";
+    /** Present for placement-kind annotations. */
+    placement?: PlacementDetails;
+    /** Present for rearrange-kind annotations. */
+    rearrange?: RearrangeDetails;
+    sessionId?: string;
+    url?: string;
+    intent?: AnnotationIntent;
+    severity?: AnnotationSeverity;
+    status?: AnnotationStatus;
+    createdAt?: string;
+    updatedAt?: string;
+    resolvedAt?: string;
+    resolvedBy?: "human" | "agent";
+    authorId?: string;
+    /**
+     * Local-only bookkeeping: the Session ID this annotation has been synced to.
+     * Never transmitted to the server. The leading underscore is part of the
+     * contract.
+     */
+    _syncedTo?: string;
+};
+
+/** Console levels the collector can wrap. */
+type BugPortConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
+/** A captured `console.*` call. */
+type BugPortConsoleEvent = {
+    id: string;
+    type: "console";
+    level: BugPortConsoleLevel;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Safely-serialised arguments (circular-safe, size-capped). */
+    args: unknown[];
+    /** Human-readable, redacted single-line message derived from `args`. */
+    message: string;
+};
+/** A captured `window.onerror` or `unhandledrejection`. */
+type BugPortRuntimeErrorEvent = {
+    id: string;
+    type: "runtime_error" | "unhandled_rejection";
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    message: string;
+    stack?: string;
+    source?: string;
+    line?: number;
+    column?: number;
+};
+/** A captured `fetch` or `XMLHttpRequest`. */
+type BugPortNetworkEvent = {
+    id: string;
+    type: "network";
+    transport: "fetch" | "xhr";
+    /** ISO 8601 timestamp of when the request started. */
+    timestamp: string;
+    method: string;
+    url: string;
+    status?: number;
+    statusText?: string;
+    durationMs?: number;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBodyPreview?: string;
+    responseBodyPreview?: string;
+    responseBodyTruncated?: boolean;
+    error?: string;
+};
+/** Discriminated union of every diagnostic event the collector can emit. */
+type BugPortDiagnosticEvent = BugPortConsoleEvent | BugPortRuntimeErrorEvent | BugPortNetworkEvent;
+/**
+ * App-owner configuration for diagnostics capture. Every field is optional;
+ * sensible privacy-preserving defaults are applied by `normalizeDiagnosticsConfig`.
+ */
+type BugPortDiagnosticsConfig = {
+    /** Master switch. When false (the default), nothing is instrumented. */
+    enabled?: boolean;
+    console?: boolean;
+    runtimeErrors?: boolean;
+    /** Convenience switch enabling both fetch + xhr when their flags are unset. */
+    network?: boolean;
+    fetch?: boolean;
+    xhr?: boolean;
+    requestBodies?: boolean;
+    responseBodies?: boolean;
+    /** Show end-user toggles in the report form (default true when enabled). */
+    userControlled?: boolean;
+    defaultAttachConsole?: boolean;
+    defaultAttachNetwork?: boolean;
+    defaultAttachRuntimeErrors?: boolean;
+    maxEvents?: number;
+    maxConsoleEvents?: number;
+    maxNetworkEvents?: number;
+    maxRuntimeErrorEvents?: number;
+    maxBodySizeBytes?: number;
+    allowedUrls?: Array<string | RegExp>;
+    deniedUrls?: Array<string | RegExp>;
+    /** Extra header names (case-insensitive) to redact, merged with defaults. */
+    redactHeaders?: string[];
+    /** Extra value patterns to redact from strings, merged with defaults. */
+    redactPatterns?: RegExp[];
+    /**
+     * Final per-event hook. Return a (possibly mutated) event to keep it, or
+     * `null` to drop it entirely. Runs after redaction, before storage.
+     */
+    beforeSendDiagnostic?: (event: BugPortDiagnosticEvent) => BugPortDiagnosticEvent | null;
+};
+/** Fully-resolved config with all defaults applied. */
+type ResolvedDiagnosticsConfig = {
+    enabled: boolean;
+    console: boolean;
+    runtimeErrors: boolean;
+    fetch: boolean;
+    xhr: boolean;
+    requestBodies: boolean;
+    responseBodies: boolean;
+    userControlled: boolean;
+    defaultAttachConsole: boolean;
+    defaultAttachNetwork: boolean;
+    defaultAttachRuntimeErrors: boolean;
+    maxConsoleEvents: number;
+    maxNetworkEvents: number;
+    maxRuntimeErrorEvents: number;
+    maxBodySizeBytes: number;
+    allowedUrls: Array<string | RegExp>;
+    deniedUrls: Array<string | RegExp>;
+    redactHeaders: string[];
+    redactPatterns: RegExp[];
+    beforeSendDiagnostic?: (event: BugPortDiagnosticEvent) => BugPortDiagnosticEvent | null;
+};
+/** What the user has consented to attach for a given submission. */
+type DiagnosticsConsent = {
+    console: boolean;
+    network: boolean;
+    runtimeErrors: boolean;
+};
+/** Diagnostics block carried on the widget submission payload. */
+type BugPortDiagnosticsPayload = {
+    console?: BugPortConsoleEvent[];
+    runtimeErrors?: BugPortRuntimeErrorEvent[];
+    network?: BugPortNetworkEvent[];
+    /** ISO 8601 timestamp of when the snapshot was taken. */
+    capturedAt: string;
+    userConsent: DiagnosticsConsent;
+};
+
+declare class DiagnosticsCollector {
+    private readonly config;
+    private readonly redactor;
+    private readonly consoleBuffer;
+    private readonly runtimeBuffer;
+    private readonly networkBuffer;
+    private installed;
+    private originalConsole;
+    private originalFetch;
+    private originalXhrOpen;
+    private originalXhrSend;
+    private originalXhrSetHeader;
+    private errorHandler;
+    private rejectionHandler;
+    private readonly xhrState;
+    constructor(config: ResolvedDiagnosticsConfig);
+    /** Install configured instrumentation. Safe to call once; no-ops on SSR. */
+    install(): void;
+    /** Restore every patched global. Idempotent. */
+    uninstall(): void;
+    /** Push an event through the optional `beforeSendDiagnostic` hook + buffer. */
+    private emit;
+    private installConsole;
+    private captureConsole;
+    private installRuntimeErrors;
+    private shouldCaptureUrl;
+    /** Cap + flag a textual body to the configured byte budget. */
+    private capBody;
+    /** Extract a safe, redacted request body preview from a fetch/xhr body. */
+    private previewRequestBody;
+    private installFetch;
+    private captureFetchResponse;
+    private installXhr;
+    private attachXhrListeners;
+    getConsoleEvents(): BugPortConsoleEvent[];
+    getRuntimeErrorEvents(): BugPortRuntimeErrorEvent[];
+    getNetworkEvents(): BugPortNetworkEvent[];
+    clear(): void;
+}
+
+/** Scripted annotation used by demo mode. */
+type DemoAnnotation = {
+    selector: string;
+    comment: string;
+    selectedText?: string;
+};
+/** Captured screenshot attached to a submission. */
+type BugportSubmissionScreenshot = {
+    dataUrl: string;
+    mimeType: string;
+    width: number;
+    height: number;
+    capturedAt: number;
+};
+/** Payload handed to onSubmitPayload. */
+type BugportSubmissionPayload = {
+    title?: string;
+    description?: string;
+    output: string;
+    annotations: Annotation[];
+    screenshot?: BugportSubmissionScreenshot;
+    /**
+     * Optional in-page diagnostics, present only when the app owner enabled
+     * capture and the user consented to attach at least one source.
+     */
+    diagnostics?: BugPortDiagnosticsPayload;
+};
+/** Full prop surface of the feedback toolbar. */
+type PageFeedbackToolbarCSSProps = {
+    demoAnnotations?: DemoAnnotation[];
+    demoDelay?: number;
+    enableDemoMode?: boolean;
+    onAnnotationAdd?: (annotation: Annotation) => void;
+    onAnnotationDelete?: (annotation: Annotation) => void;
+    onAnnotationUpdate?: (annotation: Annotation) => void;
+    onAnnotationsClear?: (annotations: Annotation[]) => void;
+    onCopy?: (markdown: string) => void;
+    onSubmit?: (output: string, annotations: Annotation[]) => void | boolean | Promise<void | boolean>;
+    onSubmitPayload?: (payload: BugportSubmissionPayload) => void | boolean | Promise<void | boolean>;
+    projectKey?: string;
+    publicKey?: string;
+    copyToClipboard?: boolean;
+    className?: string;
+    /** Resolved diagnostics config (controls which user toggles are shown). */
+    diagnosticsConfig?: ResolvedDiagnosticsConfig;
+    /** Live diagnostics collector to snapshot from at submit time. */
+    diagnosticsCollector?: DiagnosticsCollector | null;
+};
+/** Public alias for {@link PageFeedbackToolbarCSSProps}. */
+type BugportWidgetProps = PageFeedbackToolbarCSSProps;
+/**
+ * Main feedback toolbar. Renders via a portal into document.body and returns
+ * null until mounted, or whenever the toolbar has been permanently hidden.
+ */
+declare function PageFeedbackToolbarCSS(props?: PageFeedbackToolbarCSSProps): React.ReactPortal | null;
+
+type WidgetReporter = {
+    id?: string;
+    email?: string;
+    name?: string;
+};
+type BugPortSubmissionResult = {
+    bugId: string;
+    dashboardUrl: string;
+};
+
+/** Public prop contract for the CSS annotation popup. */
+interface AnnotationPopupCSSProps {
+    /** Element name to display in header */
+    element: string;
+    /** Optional timestamp display (e.g., "@ 1.23s" for animation feedback) */
+    timestamp?: string;
+    /** Optional selected/highlighted text */
+    selectedText?: string;
+    /** Placeholder text for the textarea */
+    placeholder?: string;
+    /** Initial value for textarea (for edit mode) */
+    initialValue?: string;
+    /** Label for submit button (default: "Add") */
+    submitLabel?: string;
+    /** Called when annotation is submitted with text */
+    onSubmit: (text: string) => void;
+    /** Called when popup is cancelled/dismissed */
+    onCancel: () => void;
+    /** Called when delete button is clicked (only shown if provided) */
+    onDelete?: () => void;
+    /** Position styles (left, top) */
+    style?: React.CSSProperties;
+    /** Custom color for submit button and textarea focus (hex) */
+    accentColor?: string;
+    /** External exit state (parent controls exit animation) */
+    isExiting?: boolean;
+    /** Light mode styling */
+    lightMode?: boolean;
+    /** Computed styles for the selected element */
+    computedStyles?: Record<string, string>;
+}
+/** Imperative surface that parents can drive through a ref. */
+interface AnnotationPopupCSSHandle {
+    /** Shake the popup (e.g., when user clicks outside) */
+    shake: () => void;
+}
+declare const AnnotationPopupCSS: react.ForwardRefExoticComponent<AnnotationPopupCSSProps & react.RefAttributes<AnnotationPopupCSSHandle>>;
+
+declare const IconClose: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconPlus: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconCheck: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconCheckSmall: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconListSparkle: ({ size, style, }: {
+    size?: number;
+    style?: React.CSSProperties;
+}) => react.JSX.Element;
+declare const IconBugPortGlyph: ({ size, }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconHelp: ({ size, ...props }: {
+    size?: number;
+} & React.SVGProps<SVGSVGElement>) => react.JSX.Element;
+declare const IconCheckSmallAnimated: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconCopyAlt: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconCamera: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconCopyAnimated: ({ size, copied, tint, }: {
+    size?: number;
+    copied?: boolean;
+    tint?: string;
+}) => react.JSX.Element;
+declare const IconSendArrow: ({ size, state, }: {
+    size?: number;
+    state?: "idle" | "sending" | "sent" | "failed";
+}) => react.JSX.Element;
+declare const IconSendAnimated: ({ size, sent, }: {
+    size?: number;
+    sent?: boolean;
+}) => react.JSX.Element;
+declare const IconEye: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconEyeAlt: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconEyeClosed: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconEyeAnimated: ({ size, isOpen, }: {
+    size?: number;
+    isOpen?: boolean;
+}) => react.JSX.Element;
+declare const IconPausePlayAnimated: ({ size, isPaused, }: {
+    size?: number;
+    isPaused?: boolean;
+}) => react.JSX.Element;
+declare const IconEyeMinus: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconGear: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconPauseAlt: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconPause: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconPlayAlt: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconTrashAlt: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconChatEllipsis: ({ size, style, }: {
+    size?: number;
+    style?: React.CSSProperties;
+}) => react.JSX.Element;
+declare const IconCheckmark: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconCheckmarkLarge: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconCheckmarkCircle: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconXmark: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconXmarkLarge: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconSun: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconMoon: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconEdit: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconTrash: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconChevronLeft: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconChevronRight: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+declare const IconLayout: ({ size }: {
+    size?: number;
+}) => react.JSX.Element;
+
+declare function closestCrossingShadow(element: Element, selector: string): Element | null;
+declare function isInShadowDOM(element: Element): boolean;
+declare function getShadowHost(element: Element): Element | null;
+declare function getElementPath(target: HTMLElement, maxDepth?: number): string;
+declare function identifyElement(target: HTMLElement): {
+    name: string;
+    path: string;
+};
+declare function getNearbyText(element: HTMLElement): string;
+declare function identifyAnimationElement(target: HTMLElement): string;
+declare function getElementClasses(target: HTMLElement): string;
+
+declare function getStorageKey(pathname: string): string;
+declare function loadAnnotations<T = Annotation>(pathname: string): T[];
+declare function saveAnnotations<T = Annotation>(pathname: string, annotations: T[]): void;
+
+declare function normalizeDiagnosticsConfig(config: BugPortDiagnosticsConfig | undefined): ResolvedDiagnosticsConfig;
+
+/** Header names always stripped (case-insensitive). */
+declare const DEFAULT_REDACT_HEADERS: string[];
+/** Value patterns redacted from free-form strings (URLs, bodies, messages). */
+declare const DEFAULT_REDACT_PATTERNS: RegExp[];
+/** Apply value-pattern redaction to a free-form string. */
+declare function redactString(value: string, patterns?: RegExp[]): string;
+/** Redact sensitive entries from a header map. */
+declare function redactHeaders(headers: Record<string, string>, extraHeaderNames?: string[], patterns?: RegExp[]): Record<string, string>;
+/** Redact sensitive query parameters from a URL, preserving its structure. */
+declare function redactUrl(url: string, extraHeaderNames?: string[], patterns?: RegExp[]): string;
+/**
+ * Redact a request/response body preview. JSON bodies have sensitive keys
+ * stripped; everything else is treated as free text. Never throws.
+ */
+declare function redactBody(body: string, extraHeaderNames?: string[], patterns?: RegExp[]): string;
+/** Build a redactor bound to the resolved header/pattern config. */
+declare function createRedactor(extraHeaderNames: string[], extraPatterns: RegExp[]): {
+    headerNames: string[];
+    patterns: RegExp[];
+    string: (value: string) => string;
+    headers: (headers: Record<string, string>) => Record<string, string>;
+    url: (url: string) => string;
+    body: (body: string) => string;
+};
+
+/**
+ * Snapshot the collector buffers into a submission payload, including only the
+ * sources the user has consented to. Returns `undefined` when nothing is to be
+ * attached, keeping the submission byte-for-byte identical to a pre-diagnostics
+ * report.
+ */
+declare function buildDiagnosticsPayload(collector: DiagnosticsCollector | null | undefined, consent: DiagnosticsConsent): BugPortDiagnosticsPayload | undefined;
+
+type BugPortWidgetProps = Omit<PageFeedbackToolbarCSSProps, "onSubmitPayload" | "diagnosticsConfig" | "diagnosticsCollector"> & {
+    projectKey?: string;
+    publicKey?: string;
+    environment?: string;
+    apiBaseUrl?: string;
+    user?: WidgetReporter;
+    /** Optional in-page diagnostics capture configuration. */
+    diagnostics?: BugPortDiagnosticsConfig;
+    onSubmitted?: (result: BugPortSubmissionResult) => void;
+    onError?: (error: Error) => void;
+    onSubmitPayload?: (payload: BugportSubmissionPayload) => void | boolean | Promise<void | boolean>;
+};
+declare function BugPortWidget({ projectKey, publicKey, environment, apiBaseUrl, user, diagnostics, onSubmitted, onError, onSubmitPayload, ...props }: BugPortWidgetProps): react.JSX.Element;
+declare const BugportWidget: typeof BugPortWidget;
+type BugPortWidgetHandle = {
+    destroy: () => void;
+};
+declare function initBugPortWidget(props: BugPortWidgetProps & {
+    target?: HTMLElement;
+}): BugPortWidgetHandle;
+declare global {
+    interface Window {
+        BugPort?: {
+            init: typeof initBugPortWidget;
+        };
+    }
+}
+
+export { type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type BugPortConsoleEvent, type BugPortConsoleLevel, type BugPortDiagnosticEvent, type BugPortDiagnosticsConfig, type BugPortDiagnosticsPayload, type BugPortNetworkEvent, type BugPortRuntimeErrorEvent, type BugPortSubmissionResult, BugPortWidget, type BugPortWidgetHandle, type BugPortWidgetProps, type BugportSubmissionPayload, type BugportSubmissionScreenshot, BugportWidget, type BugportWidgetProps, DEFAULT_REDACT_HEADERS, DEFAULT_REDACT_PATTERNS, type DemoAnnotation, DiagnosticsCollector, type DiagnosticsConsent, IconBugPortGlyph, IconCamera, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconChevronLeft, IconChevronRight, IconClose, IconCopyAlt, IconCopyAnimated, IconEdit, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconLayout, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSendAnimated, IconSendArrow, IconSun, IconTrash, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, type PageFeedbackToolbarCSSProps, type ResolvedDiagnosticsConfig, type WidgetReporter, buildDiagnosticsPayload, closestCrossingShadow, createRedactor, getElementClasses, getElementPath, getNearbyText, getShadowHost, getStorageKey, identifyAnimationElement, identifyElement, initBugPortWidget, isInShadowDOM, loadAnnotations, normalizeDiagnosticsConfig, redactBody, redactHeaders, redactString, redactUrl, saveAnnotations };