@mushi-mushi/core 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -97,6 +97,69 @@ interface MushiCaptureConfig {
     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. */
@@ -256,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';
@@ -294,6 +374,18 @@ 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 {
@@ -391,6 +483,16 @@ interface MushiApiClient {
     }>>;
     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[];
     }>>;
@@ -401,6 +503,22 @@ interface MushiApiClient {
         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;
     data?: T;
@@ -462,7 +580,7 @@ interface ApiClientOptions {
 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';
+type MushiInternalRequestKind = 'sdk-config' | 'report-submit' | 'report-status' | 'reporter-poll' | 'diagnose' | 'discovery';
 declare function createApiClient(options: ApiClientOptions): MushiApiClient;
 
 /**
@@ -654,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, 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 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 };
+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 };

package/dist/index.d.ts

@@ -97,6 +97,69 @@ interface MushiCaptureConfig {
     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. */
@@ -256,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';
@@ -294,6 +374,18 @@ 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 {
@@ -391,6 +483,16 @@ interface MushiApiClient {
     }>>;
     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[];
     }>>;
@@ -401,6 +503,22 @@ interface MushiApiClient {
         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;
     data?: T;
@@ -462,7 +580,7 @@ interface ApiClientOptions {
 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';
+type MushiInternalRequestKind = 'sdk-config' | 'report-submit' | 'report-status' | 'reporter-poll' | 'diagnose' | 'discovery';
 declare function createApiClient(options: ApiClientOptions): MushiApiClient;
 
 /**
@@ -654,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, 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 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 };
+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 };

package/dist/index.js

@@ -119,6 +119,15 @@ function createApiClient(options) {
       const query = new URLSearchParams({ package: packageName }).toString();
       return request("GET", `/v1/sdk/latest-version?${query}`, void 0, maxRetries, "sdk-config");
     },
+    async postDiscoveryEvent(event) {
+      return request(
+        "POST",
+        "/v1/sdk/discovery",
+        event,
+        1,
+        "discovery"
+      );
+    },
     async listReporterReports(reporterToken) {
       return requestForReporter("GET", "/v1/reporter/reports", reporterToken);
     },
@@ -793,9 +802,23 @@ function captureEnvironment() {
       rtt: connection.rtt
     } : void 0,
     deviceMemory: nav?.deviceMemory,
-    hardwareConcurrency: nav?.hardwareConcurrency
+    hardwareConcurrency: nav?.hardwareConcurrency,
+    route: win?.location?.pathname,
+    nearestTestid: findNearestTestidFromActive(doc)
   };
 }
+function findNearestTestidFromActive(doc) {
+  if (!doc) return void 0;
+  let cur = doc.activeElement ?? null;
+  let hops = 0;
+  while (cur && hops < 20) {
+    const tid = cur.getAttribute?.("data-testid");
+    if (tid) return tid;
+    cur = cur.parentElement;
+    hops++;
+  }
+  return void 0;
+}
 
 // src/reporter-token.ts
 var STORAGE_KEY = "mushi_reporter_token";