@mushi-mushi/core 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -2,15 +2,18 @@ interface MushiConfig {
     projectId: string;
     apiKey: string;
     apiEndpoint?: string;
+    /** Opinionated defaults for common environments. Explicit config wins. */
+    preset?: MushiPreset;
     /**
      * Fetch non-secret widget/capture settings from the Mushi project at
      * startup. Defaults to true so console changes apply without rebuilding
      * host apps. Set false for fully static/offline deployments.
      */
-    runtimeConfig?: boolean;
+    runtimeConfig?: boolean | 'auto';
     sentry?: MushiSentryConfig;
     widget?: MushiWidgetConfig;
     capture?: MushiCaptureConfig;
+    privacy?: MushiPrivacyConfig;
     proactive?: MushiProactiveConfig;
     preFilter?: MushiPreFilterConfig;
     integrations?: MushiIntegrationsConfig;
@@ -27,6 +30,11 @@ interface MushiSentryConfig {
 }
 interface MushiWidgetConfig {
     position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /**
+     * Raw CSS anchors for app shells with bottom navs/chat composers/cookie
+     * banners. When set, these values win over `position` + numeric `inset`.
+     */
+    anchor?: MushiWidgetAnchor;
     theme?: 'auto' | 'light' | 'dark';
     triggerText?: string;
     expandedTitle?: string;
@@ -54,6 +62,10 @@ interface MushiWidgetConfig {
     /** Opt-in smart trigger behavior; planned to become the default in a later minor. */
     smartHide?: boolean | MushiWidgetSmartHideConfig;
     draggable?: boolean;
+    /** Show the tiny "Powered by Mushi vX" footer inside the widget panel. */
+    brandFooter?: boolean;
+    /** How the widget should surface SDK freshness warnings. Defaults to auto. */
+    outdatedBanner?: 'auto' | 'banner' | 'console-only' | 'off';
 }
 interface MushiWidgetInset {
     top?: number | 'auto';
@@ -61,6 +73,13 @@ interface MushiWidgetInset {
     bottom?: number | 'auto';
     left?: number | 'auto';
 }
+interface MushiWidgetAnchor {
+    top?: string;
+    right?: string;
+    bottom?: string;
+    left?: string;
+}
+type MushiPreset = 'production-calm' | 'beta-loud' | 'internal-debug' | 'manual-only';
 interface MushiWidgetSmartHideConfig {
     onMobile?: 'edge-tab' | 'hide' | false;
     onScroll?: 'shrink' | 'hide' | false;
@@ -69,18 +88,104 @@ interface MushiWidgetSmartHideConfig {
 interface MushiCaptureConfig {
     console?: boolean;
     network?: boolean;
+    /**
+     * URLs that should never be captured as host-app traffic. Strings are
+     * substring matches; RegExp values are tested against the fully resolved URL.
+     */
+    ignoreUrls?: MushiUrlMatcher[];
     performance?: boolean;
     screenshot?: 'on-report' | 'auto' | 'off';
     elementSelector?: boolean;
     replay?: 'sentry' | 'rrweb' | 'lite' | 'off';
+    /**
+     * Mushi Mushi v2.1 (whitepaper §6 hybrid mode): passive inventory
+     * discovery. When enabled the SDK observes navigations and emits a
+     * tiny payload — `(route, title, testids[], outbound api paths[],
+     * dom_summary[≤200 chars])` — back to `/v1/sdk/discovery`. The
+     * server aggregates this over a 30-day rolling window and the
+     * admin can ask Claude to propose an `inventory.yaml` from it.
+     *
+     * Default: off. Recommended: enable in dev/preview/staging from the
+     * day you install the SDK so the proposer has data when you go to
+     * generate your first inventory.
+     *
+     * What is sent (per navigation, throttled to ≤1/route/min):
+     *   - `location.pathname` template-normalized (`/practice/abc-123`
+     *     → `/practice/[id]` via uuid/numeric/hex heuristics + an
+     *     optional framework hint if the host app sets
+     *     `discoverInventory.routeTemplates`)
+     *   - `document.title`
+     *   - All `[data-testid]` values currently in the DOM
+     *   - Recent fetch/XHR paths the existing network capturer saw
+     *   - The first text run of `<h1>` / `<title>` / `<main>` truncated
+     *     to 200 chars (helps Claude name stories well)
+     *   - Sanitized query-param keys (key names only, never values)
+     *   - A SHA-256 of `userId || sessionId` so the server can dedupe
+     *     distinct users without ever seeing identity
+     *
+     * Nothing else. No DOM beyond the summary, no query values, no PII.
+     */
+    discoverInventory?: boolean | MushiDiscoverInventoryConfig;
+}
+/**
+ * Fine-grained controls for `discoverInventory`. Defaults are tuned
+ * to be quiet enough for production but dense enough for the proposer
+ * to produce useful drafts.
+ */
+interface MushiDiscoverInventoryConfig {
+    enabled?: boolean;
+    /**
+     * Minimum gap between two emissions for the same route (ms). Defaults
+     * to 60_000. Set to a larger value for high-traffic SPAs to keep the
+     * ingest volume manageable.
+     */
+    throttleMs?: number;
+    /**
+     * Static route templates the host framework knows about. When set,
+     * a visit to `/practice/abc-123` matches `/practice/[id]` and gets
+     * normalized to that template. Without this we fall back to a
+     * heuristic (uuid / numeric / 24-char-hex segments collapse to
+     * `[id]`). Provide this when you have a static manifest — Next.js'
+     * `next.config` route export, React Router's route config, etc.
+     */
+    routeTemplates?: string[];
+    /**
+     * Override the SHA-256 user-id-hash input. Defaults to
+     * `mushi.userId || sessionId`. Set to `null` to opt out of distinct-
+     * user counting entirely.
+     */
+    userIdSource?: 'auto' | 'session-only' | 'none';
+    /**
+     * If false, the DOM summary (≤200 chars from h1/title/main) is not
+     * captured. Default true.
+     */
+    captureDomSummary?: boolean;
+}
+interface MushiPrivacyConfig {
+    /** DOM nodes to visually mask in screenshots before upload. */
+    maskSelectors?: string[];
+    /** DOM subtrees to remove from screenshots before upload. */
+    blockSelectors?: string[];
+    /** Let reporters remove an attached screenshot before submitting. Defaults to true. */
+    allowUserRemoveScreenshot?: boolean;
 }
 interface MushiProactiveConfig {
     rageClick?: boolean;
     errorBoundary?: boolean;
     longTask?: boolean;
-    apiCascade?: boolean;
+    apiCascade?: boolean | MushiApiCascadeConfig;
     cooldown?: MushiCooldownConfig;
 }
+type MushiUrlMatcher = string | RegExp;
+interface MushiApiCascadeConfig {
+    enabled?: boolean;
+    /**
+     * URLs ignored by the API cascade detector. The SDK always ignores its own
+     * gateway endpoints as well; this hook lets host apps exclude analytics,
+     * health probes, or third-party scripts that are noisy by design.
+     */
+    ignoreUrls?: MushiUrlMatcher[];
+}
 interface MushiCooldownConfig {
     maxProactivePerSession?: number;
     dismissCooldownHours?: number;
@@ -167,6 +272,7 @@ interface MushiReport {
     consoleLogs?: MushiConsoleEntry[];
     networkLogs?: MushiNetworkEntry[];
     performanceMetrics?: MushiPerformanceMetrics;
+    timeline?: MushiTimelineEntry[];
     screenshotDataUrl?: string;
     selectedElement?: MushiSelectedElement;
     metadata?: Record<string, unknown>;
@@ -179,6 +285,10 @@ interface MushiReport {
      */
     fingerprintHash?: string;
     appVersion?: string;
+    /** SDK package that submitted the report, e.g. `@mushi-mushi/web`. */
+    sdkPackage?: string;
+    /** npm package version that submitted the report, e.g. `0.8.0`. */
+    sdkVersion?: string;
     proactiveTrigger?: string;
     sentryEventId?: string;
     sentryReplayId?: string;
@@ -209,6 +319,23 @@ interface MushiEnvironment {
     };
     deviceMemory?: number;
     hardwareConcurrency?: number;
+    /**
+     * v2 inventory hints (whitepaper §4.7).
+     *
+     * `route` — the bare pathname (no query / hash). Pinned to the
+     * inventory's `Page.path` so the Triage LLM can shortcut from a
+     * freeform "the streak counter is broken" report to the right page.
+     *
+     * `nearestTestid` — the closest ancestor of the active element with
+     * a `data-testid`, captured at widget-open time. This pins the
+     * report to one Action node when more than one page has the same
+     * page path (e.g. a shared "Buy Pro" CTA on landing + dashboard).
+     *
+     * Both are best-effort; freeform reports with no active element will
+     * have `route` only.
+     */
+    route?: string;
+    nearestTestid?: string;
 }
 interface MushiConsoleEntry {
     level: 'log' | 'warn' | 'error' | 'info' | 'debug';
@@ -247,12 +374,41 @@ interface MushiSelectedElement {
         width: number;
         height: number;
     };
+    /**
+     * `data-testid` of the closest ancestor that has one. Mushi v2 uses this
+     * to map a report → Action node in the bidirectional graph (whitepaper §4.7).
+     * Falls back to `undefined` when no ancestor declares a testid — the v2
+     * Triage LLM still classifies these reports, just without the inventory
+     * grounding shortcut.
+     */
+    nearestTestid?: string;
+    /** Path of the page the user reported from (`window.location.pathname`).
+     *  Combined with `nearestTestid` it pins a report to one Action even when
+     *  the same testid exists on multiple pages. */
+    route?: string;
+}
+type MushiTimelineKind = 'route' | 'click' | 'request' | 'log' | 'screen';
+interface MushiTimelineEntry {
+    ts: number;
+    kind: MushiTimelineKind;
+    payload: Record<string, unknown>;
 }
 type MushiEventType = 'report:submitted' | 'report:queued' | 'report:sent' | 'report:failed' | 'widget:opened' | 'widget:closed' | 'proactive:triggered' | 'proactive:dismissed';
 type MushiEventHandler = (event: {
     type: MushiEventType;
     data?: unknown;
 }) => void;
+interface MushiDiagnosticsResult {
+    apiEndpointReachable: boolean;
+    cspAllowsEndpoint: boolean;
+    widgetMounted: boolean;
+    shadowDomAvailable: boolean;
+    dialogSupported: boolean;
+    runtimeConfigLoaded: boolean;
+    captureScreenshotAvailable: boolean;
+    captureNetworkIntercepting: boolean;
+    sdkVersion: string;
+}
 interface MushiSDKInstance {
     report(options?: {
         category?: MushiReportCategory;
@@ -264,6 +420,11 @@ interface MushiSDKInstance {
         name?: string;
     }): void;
     setMetadata(key: string, value: unknown): void;
+    setScreen(screen: {
+        name: string;
+        route?: string;
+        feature?: string;
+    }): void;
     isOpen(): boolean;
     open(): void;
     openWith(category: MushiReportCategory): void;
@@ -274,6 +435,7 @@ interface MushiSDKInstance {
     close(): void;
     destroy(): void;
     updateConfig(config: MushiRuntimeSdkConfig): void;
+    diagnose(): Promise<MushiDiagnosticsResult>;
     /**
      * Wave G4 — unified `captureEvent` API. Submits a bug report
      * programmatically without opening the widget. Useful for adapters
@@ -320,6 +482,42 @@ interface MushiApiClient {
         status: MushiReportStatus;
     }>>;
     getSdkConfig(): Promise<MushiApiResponse<MushiRuntimeSdkConfig>>;
+    getLatestSdkVersion(packageName: string): Promise<MushiApiResponse<MushiSdkVersionInfo>>;
+    /**
+     * Mushi v2.1: ship a single passive-discovery observation (route +
+     * testids + outbound APIs + DOM summary). Best-effort fire-and-forget;
+     * the caller should not block on the response. The server rate-limits
+     * per (project, route) to keep ingest cheap, so it's fine for clients
+     * to over-emit on the throttle window — the server picks the freshest.
+     */
+    postDiscoveryEvent(event: MushiDiscoveryEventPayload): Promise<MushiApiResponse<{
+        accepted: boolean;
+    }>>;
+    listReporterReports(reporterToken: string): Promise<MushiApiResponse<{
+        reports: MushiReporterReport[];
+    }>>;
+    listReporterComments(reportId: string, reporterToken: string): Promise<MushiApiResponse<{
+        comments: MushiReporterComment[];
+    }>>;
+    replyToReporterReport(reportId: string, reporterToken: string, body: string): Promise<MushiApiResponse<{
+        comment: MushiReporterComment;
+    }>>;
+}
+/**
+ * Wire shape of a single discovery event sent by the SDK to
+ * `POST /v1/sdk/discovery`. Mirrored server-side in
+ * `_shared/schemas.ts::discoveryEventSchema`.
+ */
+interface MushiDiscoveryEventPayload {
+    route: string;
+    page_title?: string | null;
+    dom_summary?: string | null;
+    testids: string[];
+    network_paths: string[];
+    query_param_keys: string[];
+    user_id_hash?: string | null;
+    sdk_version?: string;
+    observed_at: string;
 }
 interface MushiApiResponse<T> {
     ok: boolean;
@@ -339,6 +537,34 @@ interface MushiRuntimeSdkConfig {
         minDescriptionLength?: number;
     };
 }
+interface MushiSdkVersionInfo {
+    package: string;
+    latest: string | null;
+    current?: string;
+    deprecated: boolean;
+    deprecationMessage?: string | null;
+    releasedAt?: string | null;
+}
+interface MushiReporterReport {
+    id: string;
+    status: string;
+    category: string;
+    severity?: string | null;
+    summary?: string | null;
+    description?: string | null;
+    created_at: string;
+    last_admin_reply_at?: string | null;
+    last_reporter_reply_at?: string | null;
+    unread_count?: number;
+}
+interface MushiReporterComment {
+    id: number;
+    author_kind: 'admin' | 'reporter';
+    author_name?: string | null;
+    body: string;
+    visible_to_reporter?: boolean;
+    created_at: string;
+}
 
 interface ApiClientOptions {
     projectId: string;
@@ -352,6 +578,9 @@ interface ApiClientOptions {
     maxRetries?: number;
 }
 declare const DEFAULT_API_ENDPOINT = "https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api";
+declare const MUSHI_INTERNAL_HEADER = "X-Mushi-Internal";
+declare const MUSHI_INTERNAL_INIT_MARKER = "__mushiInternal";
+type MushiInternalRequestKind = 'sdk-config' | 'report-submit' | 'report-status' | 'reporter-poll' | 'diagnose' | 'discovery';
 declare function createApiClient(options: ApiClientOptions): MushiApiClient;
 
 /**
@@ -543,4 +772,4 @@ declare function createLogger(options: LoggerOptions): Logger;
  */
 declare const noopLogger: Logger;
 
-export { type ApiClientOptions, DEFAULT_API_ENDPOINT, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, type MushiApiClient, type MushiApiResponse, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiIntegrationsConfig, type MushiNetworkEntry, type MushiOfflineConfig, type MushiOnDeviceClassifier, type MushiOnDeviceClassifierInput, type MushiOnDeviceClassifierResult, type MushiPerformanceMetrics, type MushiPreFilterConfig, type MushiProactiveConfig, type MushiRegion, type MushiReport, type MushiReportBuilder, type MushiReportCategory, type MushiReportStatus, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSelectedElement, type MushiSentryConfig, type MushiWidgetConfig, type OfflineQueue, type PiiScrubberConfig, type PreFilterResult, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, captureEnvironment, createApiClient, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, getDeviceFingerprintHash, getReporterToken, getSessionId, noopLogger, resolveRegionEndpoint, scrubPii };
+export { type ApiClientOptions, DEFAULT_API_ENDPOINT, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiDiagnosticsResult, type MushiDiscoverInventoryConfig, type MushiDiscoveryEventPayload, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiIntegrationsConfig, type MushiInternalRequestKind, type MushiNetworkEntry, type MushiOfflineConfig, type MushiOnDeviceClassifier, type MushiOnDeviceClassifierInput, type MushiOnDeviceClassifierResult, type MushiPerformanceMetrics, type MushiPreFilterConfig, type MushiPreset, type MushiPrivacyConfig, type MushiProactiveConfig, type MushiRegion, type MushiReport, type MushiReportBuilder, type MushiReportCategory, type MushiReportStatus, type MushiReporterComment, type MushiReporterReport, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiTimelineEntry, type MushiTimelineKind, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type OfflineQueue, type PiiScrubberConfig, type PreFilterResult, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, captureEnvironment, createApiClient, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, getDeviceFingerprintHash, getReporterToken, getSessionId, noopLogger, resolveRegionEndpoint, scrubPii };