@mushi-mushi/web 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -36,12 +36,27 @@ interface WidgetRewardsState {
     /** Expected base points for a `report_submit` action (default 50). */
     pointsForReport: number;
 }
+interface WidgetSubmitOutcome {
+    /** Server-confirmed report id. When `null` the report was queued
+     *  offline / failed-and-queued for retry; the success step degrades
+     *  gracefully (no "track on console" link, just the receipt stamp). */
+    reportId: string | null;
+    /** Convenience flag for the widget to decide whether to render the
+     *  optimistic copy ("queued offline, we'll send it when you're back")
+     *  versus the confirmed copy ("received — track at #abc12345"). */
+    queuedOffline?: boolean;
+}
 interface WidgetCallbacks {
+    /**
+     * Returns the outcome of the submission so the widget can render a
+     * real receipt (report id, deep link). Older callers that return
+     * `void` still work — the widget falls back to the legacy stamp.
+     */
     onSubmit(data: {
         category: MushiReportCategory;
         description: string;
         intent?: string;
-    }): void;
+    }): void | Promise<WidgetSubmitOutcome | void>;
     onOpen(): void;
     onClose(): void;
     onScreenshotRequest(): void;
@@ -62,6 +77,13 @@ declare class MushiWidget {
     private step;
     private selectedCategory;
     private selectedIntent;
+    /**
+     * True when the user took the "Feature request" shortcut. We track this
+     * separately from `selectedCategory='other'` so the Back button on the
+     * details step jumps straight back to the category picker instead of
+     * landing on the intent picker the user explicitly skipped.
+     */
+    private viaFeatureRequest;
     private screenshotAttached;
     private screenshotCapturing;
     private screenshotError;
@@ -99,14 +121,36 @@ declare class MushiWidget {
     private successTimer;
     private autoCloseTimer;
     private rewardsState;
+    /** Server-confirmed id for the just-submitted report. Surfaces in
+     *  the success step as a copyable receipt + optional deep link to
+     *  the Mushi console (when `dashboardUrl` is configured). Cleared
+     *  on every new `open()` so a re-opened widget never reuses a
+     *  stale id from the previous session. */
+    private lastReportId;
+    /** True when the just-submitted report was queued offline (no
+     *  network, or the API errored and went into the retry queue).
+     *  Drives a different success copy so the user knows the report
+     *  hasn't actually reached the console yet. */
+    private lastSubmitQueuedOffline;
+    /** Whether the user has clicked ✕ on the header banner this session. */
+    private bannerDismissed;
     constructor(config: MushiWidgetConfig | undefined, callbacks: WidgetCallbacks, sdkVersion?: string);
     mount(): void;
     getIsMounted(): boolean;
     updateConfig(config?: MushiWidgetConfig): void;
     open(options?: {
         category?: MushiReportCategory;
+        featureRequest?: boolean;
     }): void;
     close(): void;
+    /**
+     * Briefly highlight the trigger button (a soft pulse + tooltip) without
+     * opening the full reporter panel. Use for first-session welcome nudges
+     * and other "by the way, this exists" prompts where forcing the panel
+     * open would feel aggressive. Honours `position: 'none'` (no-op when
+     * the trigger button is hidden).
+     */
+    pulseTrigger(): void;
     getIsOpen(): boolean;
     showTrigger(): void;
     hideTrigger(): void;
@@ -138,6 +182,13 @@ declare class MushiWidget {
     private syncAttachedLaunchers;
     private syncSmartHide;
     private shouldRenderTrigger;
+    /** Height of the banner in px — kept in sync with the CSS `.mushi-banner` height (36px). */
+    private static readonly BANNER_HEIGHT;
+    /** CSS property applied to document.body so host-app content doesn't slide under the banner. */
+    private static readonly BODY_NUDGE_PROP;
+    private applyBodyNudge;
+    private removeBodyNudge;
+    private renderBanner;
     private effectiveTrigger;
     private isMobileSmartHidden;
     private detectEnvironment;
@@ -166,6 +217,19 @@ declare class MushiWidget {
      */
     private renderStepIndicator;
     private renderCategoryStep;
+    /**
+     * First-class "Feature request" entry rendered at the top of the
+     * category step. Beta apps consistently get more useful signal when
+     * the user has a no-friction path to say "I wish this did X" — burying
+     * it as an intent under the "Other" category drops feature submissions
+     * by ~40% in industry studies (Userpilot, Usersnap 2025).
+     *
+     * Wire format: still routes through the standard `other` category with
+     * a `user_category = 'Feature request'` stamp, so we don't need a DB
+     * migration. The admin console filters on that string to surface the
+     * Feature-request swimlane.
+     */
+    private renderFeatureRequestEntry;
     /** Collapsible "What's new" changelog row. Closes the reporter feedback loop. */
     private renderBetaChangelog;
     /**
@@ -188,6 +252,19 @@ declare class MushiWidget {
      * frame instantly.
      */
     private renderSuccessStep;
+    /**
+     * Two-way receipt block. Until the host's `onSubmit` resolves with a
+     * server-confirmed report id, we show a discreet "delivering..." pill so
+     * the user knows their submission is still in flight. Once we have the
+     * id, we surface a short monospaced id + a copy button + an optional
+     * "Track on Mushi" deep link to `dashboardUrl/reports/<id>` so the user
+     * can watch the status walk through queued -> classified -> fixed in
+     * real time (Peak-End rule: the last impression sticks). If we never
+     * get an id (offline retry queue), we say so explicitly rather than
+     * pretending everything is fine.
+     */
+    private renderSuccessReceipt;
+    private renderSlaLine;
     /**
      * Reciprocity footer on the success step: closes the feedback loop by
      * attributing where the report goes, sets a response expectation, and
@@ -238,20 +315,12 @@ interface NetworkCaptureOptions {
 declare function createNetworkCapture(options?: NetworkCaptureOptions): NetworkCapture;
 
 interface ScreenshotCapture {
-    take(): Promise<ScreenshotResult>;
+    take(): Promise<string | null>;
     updateOptions(options: ScreenshotCaptureOptions): void;
 }
 interface ScreenshotCaptureOptions {
     privacy?: MushiPrivacyConfig;
 }
-type ScreenshotResult = {
-    ok: true;
-    dataUrl: string;
-} | {
-    ok: false;
-    reason: 'tainted' | 'load-error' | 'unsupported' | 'cancelled' | 'error';
-    message?: string;
-};
 declare function createScreenshotCapture(options?: ScreenshotCaptureOptions): ScreenshotCapture;
 
 interface PerformanceCapture {
@@ -343,6 +412,35 @@ interface ProactiveTriggerConfig {
     apiCascade?: boolean | MushiApiCascadeConfig;
     apiEndpoint?: string;
     errorBoundary?: boolean;
+    /**
+     * Beta-mode nudges. Fire when the user has been on the same route for
+     * `pageDwellMs` continuous milliseconds without filing any report. Default
+     * disabled because production apps usually don't want unsolicited prompts;
+     * recommended only when `betaMode.enabled` is true on the widget.
+     *
+     * Pass `true` to use the default 5-minute threshold, or a config object
+     * to override. Set to `false` (default) to disable entirely.
+     */
+    pageDwell?: boolean | {
+        thresholdMs?: number;
+        excludeRoutes?: string[];
+    };
+    /**
+     * First-session welcome. Fires exactly once per user (tracked via
+     * `localStorage`) `delayMs` milliseconds after `Mushi.init`. Use to
+     * gently surface the bug button to new beta users so they know feedback
+     * is welcome. Default disabled.
+     */
+    firstSession?: boolean | {
+        delayMs?: number;
+        storageKey?: string;
+    };
+    /**
+     * The project ID, used to namespace the `firstSession` localStorage key so
+     * multi-tenant single-page apps don't share first-session state across
+     * projects. Sourced from `MushiConfig.projectId` by the SDK.
+     */
+    projectId?: string;
 }
 interface ProactiveTriggerCallbacks {
     onTrigger: (type: string, context: Record<string, unknown>) => void;

package/dist/index.d.ts

@@ -36,12 +36,27 @@ interface WidgetRewardsState {
     /** Expected base points for a `report_submit` action (default 50). */
     pointsForReport: number;
 }
+interface WidgetSubmitOutcome {
+    /** Server-confirmed report id. When `null` the report was queued
+     *  offline / failed-and-queued for retry; the success step degrades
+     *  gracefully (no "track on console" link, just the receipt stamp). */
+    reportId: string | null;
+    /** Convenience flag for the widget to decide whether to render the
+     *  optimistic copy ("queued offline, we'll send it when you're back")
+     *  versus the confirmed copy ("received — track at #abc12345"). */
+    queuedOffline?: boolean;
+}
 interface WidgetCallbacks {
+    /**
+     * Returns the outcome of the submission so the widget can render a
+     * real receipt (report id, deep link). Older callers that return
+     * `void` still work — the widget falls back to the legacy stamp.
+     */
     onSubmit(data: {
         category: MushiReportCategory;
         description: string;
         intent?: string;
-    }): void;
+    }): void | Promise<WidgetSubmitOutcome | void>;
     onOpen(): void;
     onClose(): void;
     onScreenshotRequest(): void;
@@ -62,6 +77,13 @@ declare class MushiWidget {
     private step;
     private selectedCategory;
     private selectedIntent;
+    /**
+     * True when the user took the "Feature request" shortcut. We track this
+     * separately from `selectedCategory='other'` so the Back button on the
+     * details step jumps straight back to the category picker instead of
+     * landing on the intent picker the user explicitly skipped.
+     */
+    private viaFeatureRequest;
     private screenshotAttached;
     private screenshotCapturing;
     private screenshotError;
@@ -99,14 +121,36 @@ declare class MushiWidget {
     private successTimer;
     private autoCloseTimer;
     private rewardsState;
+    /** Server-confirmed id for the just-submitted report. Surfaces in
+     *  the success step as a copyable receipt + optional deep link to
+     *  the Mushi console (when `dashboardUrl` is configured). Cleared
+     *  on every new `open()` so a re-opened widget never reuses a
+     *  stale id from the previous session. */
+    private lastReportId;
+    /** True when the just-submitted report was queued offline (no
+     *  network, or the API errored and went into the retry queue).
+     *  Drives a different success copy so the user knows the report
+     *  hasn't actually reached the console yet. */
+    private lastSubmitQueuedOffline;
+    /** Whether the user has clicked ✕ on the header banner this session. */
+    private bannerDismissed;
     constructor(config: MushiWidgetConfig | undefined, callbacks: WidgetCallbacks, sdkVersion?: string);
     mount(): void;
     getIsMounted(): boolean;
     updateConfig(config?: MushiWidgetConfig): void;
     open(options?: {
         category?: MushiReportCategory;
+        featureRequest?: boolean;
     }): void;
     close(): void;
+    /**
+     * Briefly highlight the trigger button (a soft pulse + tooltip) without
+     * opening the full reporter panel. Use for first-session welcome nudges
+     * and other "by the way, this exists" prompts where forcing the panel
+     * open would feel aggressive. Honours `position: 'none'` (no-op when
+     * the trigger button is hidden).
+     */
+    pulseTrigger(): void;
     getIsOpen(): boolean;
     showTrigger(): void;
     hideTrigger(): void;
@@ -138,6 +182,13 @@ declare class MushiWidget {
     private syncAttachedLaunchers;
     private syncSmartHide;
     private shouldRenderTrigger;
+    /** Height of the banner in px — kept in sync with the CSS `.mushi-banner` height (36px). */
+    private static readonly BANNER_HEIGHT;
+    /** CSS property applied to document.body so host-app content doesn't slide under the banner. */
+    private static readonly BODY_NUDGE_PROP;
+    private applyBodyNudge;
+    private removeBodyNudge;
+    private renderBanner;
     private effectiveTrigger;
     private isMobileSmartHidden;
     private detectEnvironment;
@@ -166,6 +217,19 @@ declare class MushiWidget {
      */
     private renderStepIndicator;
     private renderCategoryStep;
+    /**
+     * First-class "Feature request" entry rendered at the top of the
+     * category step. Beta apps consistently get more useful signal when
+     * the user has a no-friction path to say "I wish this did X" — burying
+     * it as an intent under the "Other" category drops feature submissions
+     * by ~40% in industry studies (Userpilot, Usersnap 2025).
+     *
+     * Wire format: still routes through the standard `other` category with
+     * a `user_category = 'Feature request'` stamp, so we don't need a DB
+     * migration. The admin console filters on that string to surface the
+     * Feature-request swimlane.
+     */
+    private renderFeatureRequestEntry;
     /** Collapsible "What's new" changelog row. Closes the reporter feedback loop. */
     private renderBetaChangelog;
     /**
@@ -188,6 +252,19 @@ declare class MushiWidget {
      * frame instantly.
      */
     private renderSuccessStep;
+    /**
+     * Two-way receipt block. Until the host's `onSubmit` resolves with a
+     * server-confirmed report id, we show a discreet "delivering..." pill so
+     * the user knows their submission is still in flight. Once we have the
+     * id, we surface a short monospaced id + a copy button + an optional
+     * "Track on Mushi" deep link to `dashboardUrl/reports/<id>` so the user
+     * can watch the status walk through queued -> classified -> fixed in
+     * real time (Peak-End rule: the last impression sticks). If we never
+     * get an id (offline retry queue), we say so explicitly rather than
+     * pretending everything is fine.
+     */
+    private renderSuccessReceipt;
+    private renderSlaLine;
     /**
      * Reciprocity footer on the success step: closes the feedback loop by
      * attributing where the report goes, sets a response expectation, and
@@ -238,20 +315,12 @@ interface NetworkCaptureOptions {
 declare function createNetworkCapture(options?: NetworkCaptureOptions): NetworkCapture;
 
 interface ScreenshotCapture {
-    take(): Promise<ScreenshotResult>;
+    take(): Promise<string | null>;
     updateOptions(options: ScreenshotCaptureOptions): void;
 }
 interface ScreenshotCaptureOptions {
     privacy?: MushiPrivacyConfig;
 }
-type ScreenshotResult = {
-    ok: true;
-    dataUrl: string;
-} | {
-    ok: false;
-    reason: 'tainted' | 'load-error' | 'unsupported' | 'cancelled' | 'error';
-    message?: string;
-};
 declare function createScreenshotCapture(options?: ScreenshotCaptureOptions): ScreenshotCapture;
 
 interface PerformanceCapture {
@@ -343,6 +412,35 @@ interface ProactiveTriggerConfig {
     apiCascade?: boolean | MushiApiCascadeConfig;
     apiEndpoint?: string;
     errorBoundary?: boolean;
+    /**
+     * Beta-mode nudges. Fire when the user has been on the same route for
+     * `pageDwellMs` continuous milliseconds without filing any report. Default
+     * disabled because production apps usually don't want unsolicited prompts;
+     * recommended only when `betaMode.enabled` is true on the widget.
+     *
+     * Pass `true` to use the default 5-minute threshold, or a config object
+     * to override. Set to `false` (default) to disable entirely.
+     */
+    pageDwell?: boolean | {
+        thresholdMs?: number;
+        excludeRoutes?: string[];
+    };
+    /**
+     * First-session welcome. Fires exactly once per user (tracked via
+     * `localStorage`) `delayMs` milliseconds after `Mushi.init`. Use to
+     * gently surface the bug button to new beta users so they know feedback
+     * is welcome. Default disabled.
+     */
+    firstSession?: boolean | {
+        delayMs?: number;
+        storageKey?: string;
+    };
+    /**
+     * The project ID, used to namespace the `firstSession` localStorage key so
+     * multi-tenant single-page apps don't share first-session state across
+     * projects. Sourced from `MushiConfig.projectId` by the SDK.
+     */
+    projectId?: string;
 }
 interface ProactiveTriggerCallbacks {
     onTrigger: (type: string, context: Record<string, unknown>) => void;