@mushi-mushi/core 1.7.2 → 1.8.0

package/dist/index.d.cts

@@ -117,6 +117,27 @@ interface MushiWidgetConfig {
     featureRequestDescription?: string;
     /** Minimum description character count before the submit button enables. */
     minDescriptionLength?: number;
+    /**
+     * CSS selectors of host-app elements that the widget trigger and panel must
+     * never visually overlap. At render time the widget queries each selector,
+     * measures the union bounding rect, and nudges `--mushi-top` / `--mushi-bottom`
+     * so the panel clears every avoided element by at least 8px.
+     *
+     * Typical use: avoid a sticky mobile header or a fixed sign-in CTA.
+     *
+     * @example
+     * avoidSelectors: ['[data-mobile-header]', '#sign-in-cta']
+     */
+    avoidSelectors?: string[];
+}
+/** Optional flat link in the rich banner action row (admin-console BetaBanner style). */
+interface MushiBannerLink {
+    /** Link label shown in the action row. */
+    label: string;
+    /** External URL — opens in a new tab when set. */
+    href?: string;
+    /** When `href` is absent, opens the widget in feature-request mode. */
+    featureRequest?: boolean;
 }
 /**
  * Configuration for the `trigger: 'banner'` header-strip launcher.
@@ -136,12 +157,25 @@ interface MushiBannerConfig {
     variant?: 'neon' | 'brand' | 'subtle';
     /** 'top' pins the banner below any existing sticky headers; 'bottom' pins above bottom navs. Defaults to 'top'. */
     position?: 'top' | 'bottom';
-    /** Override the call-to-action text in the banner. Defaults to 'Report a bug'. */
+    /**
+     * Body copy on the strip — the lime "Beta" announcement line users see in
+     * the Mushi admin console. When set, the banner switches to the rich layout
+     * (pill + message + flat text actions) instead of button-only CTAs.
+     */
+    message?: string;
+    /**
+     * Pill label shown before `message` (e.g. "Beta"). Defaults to `"Beta"` when
+     * `message` is set. Pass `false` to hide the pill.
+     */
+    label?: string | false;
+    /** Override the call-to-action text in the banner. Defaults to '🐛 Report a bug'. */
     bugCta?: string;
     /** Show a "✨ Request a feature" button alongside the bug button. Defaults to true. */
     featureCta?: boolean;
     /** Override the feature-request button label. */
     featureCtaLabel?: string;
+    /** Extra flat links after the bug/feature CTAs (e.g. "My submissions"). */
+    links?: MushiBannerLink[];
     /** CSS z-index of the banner element. Defaults to the widget's configured zIndex. */
     zIndex?: number;
 }
@@ -336,6 +370,18 @@ interface MushiCooldownConfig {
     maxProactivePerSession?: number;
     dismissCooldownHours?: number;
     suppressAfterDismissals?: number;
+    /**
+     * Cross-reload re-show cooldown, in minutes (default 30; `0` disables).
+     *
+     * The `dismissCooldownHours` window only starts after a clean dismissal is
+     * recorded (widget `onClose`). A page reload or crash tears down the JS
+     * context before that, so on a broken/reloading page the proactive panel
+     * would otherwise re-open on every load. When a prompt is shown the SDK
+     * persists a timestamp; a fresh session (new JS context) suppresses prompts
+     * shown within this window. Within a live session the per-session limit
+     * governs instead, so this never blocks a legitimate second trigger.
+     */
+    reshowCooldownMinutes?: number;
 }
 interface MushiPreFilterConfig {
     enabled?: boolean;
@@ -833,6 +879,34 @@ interface MushiDiagnosticsResult {
     captureScreenshotAvailable: boolean;
     captureNetworkIntercepting: boolean;
     sdkVersion: string;
+    /**
+     * True when the widget host element has `pointer-events: none` and
+     * zero width/height — i.e. it cannot act as a touch blocker over host UI.
+     * False when the SDK has not yet mounted, or when a consumer has overridden
+     * the host styles without restoring the pass-through contract.
+     */
+    widgetHostPointerSafe: boolean;
+    /**
+     * Bounding rect of the widget host element (`offsetWidth × offsetHeight`).
+     * Should be `{ width: 0, height: 0 }` for a healthy SDK — the host is
+     * zero-sized with `overflow: visible` so the shadow internals extend
+     * outward without creating a hit-test surface.  `null` when not mounted.
+     */
+    widgetHostBounds: {
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * True when the widget is currently suppressed: `hideOnSelector` matched an
+     * element, `hideOnRoutes` matched the current pathname, or `hide()` was
+     * called.  A suppressed widget renders nothing and removes the body nudge.
+     */
+    widgetSuppressed: boolean;
+    /**
+     * True when `trigger: 'banner'` is active and the banner is currently
+     * rendered in the shadow DOM (not dismissed, not suppressed).
+     */
+    bannerRendered: boolean;
 }
 interface MushiSDKInstance {
     /**
@@ -1204,6 +1278,27 @@ declare function captureEnvironment(): MushiEnvironment;
 
 declare function getReporterToken(): string;
 
+/**
+ * RFC-4122 v4 UUID generator with a capability ladder so it works in every
+ * runtime a Mushi SDK ships to:
+ *
+ *   1. `crypto.randomUUID()`      — browsers (secure context), Node 19+, Deno
+ *   2. `crypto.getRandomValues()` — older browsers, RN with a crypto polyfill
+ *   3. `Math.random()`            — Hermes / JSC without a crypto polyfill
+ *
+ * Why this exists: report ids are written to the `reports.id uuid` column on
+ * the backend. SDKs that minted ad-hoc ids (`rn-<ts>-<rand>`, `mushi_<hex>`)
+ * failed the Postgres uuid cast (22P02) and the report was silently dropped
+ * (Sentry MUSHI-MUSHI-SERVER-D). Emitting a well-formed UUID at the source
+ * keeps the value valid end-to-end.
+ *
+ * A report id is an identifier, not a secret. The `Math.random` fallback only
+ * affects collision odds — negligible at our volume, and the backend dedupes
+ * on the `reports` primary key regardless — so we never throw just because a
+ * runtime lacks a CSPRNG.
+ */
+declare function newUuid(): string;
+
 /**
  * §3c — stable device fingerprint hash.
  *
@@ -1402,4 +1497,4 @@ declare function createLogger(options: LoggerOptions): Logger;
  */
 declare const noopLogger: Logger;
 
-export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiBannerConfig, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, 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 MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PiiScrubberConfig, type PreFilterResult, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, captureEnvironment, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, getDeviceFingerprintHash, getReporterToken, getSessionId, noopLogger, normaliseThrown, resolveRegionEndpoint, scrubPii };
+export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiBannerConfig, type MushiBannerLink, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, 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 MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PiiScrubberConfig, type PreFilterResult, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, captureEnvironment, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, getDeviceFingerprintHash, getReporterToken, getSessionId, newUuid, noopLogger, normaliseThrown, resolveRegionEndpoint, scrubPii };

package/dist/index.d.ts

@@ -117,6 +117,27 @@ interface MushiWidgetConfig {
     featureRequestDescription?: string;
     /** Minimum description character count before the submit button enables. */
     minDescriptionLength?: number;
+    /**
+     * CSS selectors of host-app elements that the widget trigger and panel must
+     * never visually overlap. At render time the widget queries each selector,
+     * measures the union bounding rect, and nudges `--mushi-top` / `--mushi-bottom`
+     * so the panel clears every avoided element by at least 8px.
+     *
+     * Typical use: avoid a sticky mobile header or a fixed sign-in CTA.
+     *
+     * @example
+     * avoidSelectors: ['[data-mobile-header]', '#sign-in-cta']
+     */
+    avoidSelectors?: string[];
+}
+/** Optional flat link in the rich banner action row (admin-console BetaBanner style). */
+interface MushiBannerLink {
+    /** Link label shown in the action row. */
+    label: string;
+    /** External URL — opens in a new tab when set. */
+    href?: string;
+    /** When `href` is absent, opens the widget in feature-request mode. */
+    featureRequest?: boolean;
 }
 /**
  * Configuration for the `trigger: 'banner'` header-strip launcher.
@@ -136,12 +157,25 @@ interface MushiBannerConfig {
     variant?: 'neon' | 'brand' | 'subtle';
     /** 'top' pins the banner below any existing sticky headers; 'bottom' pins above bottom navs. Defaults to 'top'. */
     position?: 'top' | 'bottom';
-    /** Override the call-to-action text in the banner. Defaults to 'Report a bug'. */
+    /**
+     * Body copy on the strip — the lime "Beta" announcement line users see in
+     * the Mushi admin console. When set, the banner switches to the rich layout
+     * (pill + message + flat text actions) instead of button-only CTAs.
+     */
+    message?: string;
+    /**
+     * Pill label shown before `message` (e.g. "Beta"). Defaults to `"Beta"` when
+     * `message` is set. Pass `false` to hide the pill.
+     */
+    label?: string | false;
+    /** Override the call-to-action text in the banner. Defaults to '🐛 Report a bug'. */
     bugCta?: string;
     /** Show a "✨ Request a feature" button alongside the bug button. Defaults to true. */
     featureCta?: boolean;
     /** Override the feature-request button label. */
     featureCtaLabel?: string;
+    /** Extra flat links after the bug/feature CTAs (e.g. "My submissions"). */
+    links?: MushiBannerLink[];
     /** CSS z-index of the banner element. Defaults to the widget's configured zIndex. */
     zIndex?: number;
 }
@@ -336,6 +370,18 @@ interface MushiCooldownConfig {
     maxProactivePerSession?: number;
     dismissCooldownHours?: number;
     suppressAfterDismissals?: number;
+    /**
+     * Cross-reload re-show cooldown, in minutes (default 30; `0` disables).
+     *
+     * The `dismissCooldownHours` window only starts after a clean dismissal is
+     * recorded (widget `onClose`). A page reload or crash tears down the JS
+     * context before that, so on a broken/reloading page the proactive panel
+     * would otherwise re-open on every load. When a prompt is shown the SDK
+     * persists a timestamp; a fresh session (new JS context) suppresses prompts
+     * shown within this window. Within a live session the per-session limit
+     * governs instead, so this never blocks a legitimate second trigger.
+     */
+    reshowCooldownMinutes?: number;
 }
 interface MushiPreFilterConfig {
     enabled?: boolean;
@@ -833,6 +879,34 @@ interface MushiDiagnosticsResult {
     captureScreenshotAvailable: boolean;
     captureNetworkIntercepting: boolean;
     sdkVersion: string;
+    /**
+     * True when the widget host element has `pointer-events: none` and
+     * zero width/height — i.e. it cannot act as a touch blocker over host UI.
+     * False when the SDK has not yet mounted, or when a consumer has overridden
+     * the host styles without restoring the pass-through contract.
+     */
+    widgetHostPointerSafe: boolean;
+    /**
+     * Bounding rect of the widget host element (`offsetWidth × offsetHeight`).
+     * Should be `{ width: 0, height: 0 }` for a healthy SDK — the host is
+     * zero-sized with `overflow: visible` so the shadow internals extend
+     * outward without creating a hit-test surface.  `null` when not mounted.
+     */
+    widgetHostBounds: {
+        width: number;
+        height: number;
+    } | null;
+    /**
+     * True when the widget is currently suppressed: `hideOnSelector` matched an
+     * element, `hideOnRoutes` matched the current pathname, or `hide()` was
+     * called.  A suppressed widget renders nothing and removes the body nudge.
+     */
+    widgetSuppressed: boolean;
+    /**
+     * True when `trigger: 'banner'` is active and the banner is currently
+     * rendered in the shadow DOM (not dismissed, not suppressed).
+     */
+    bannerRendered: boolean;
 }
 interface MushiSDKInstance {
     /**
@@ -1204,6 +1278,27 @@ declare function captureEnvironment(): MushiEnvironment;
 
 declare function getReporterToken(): string;
 
+/**
+ * RFC-4122 v4 UUID generator with a capability ladder so it works in every
+ * runtime a Mushi SDK ships to:
+ *
+ *   1. `crypto.randomUUID()`      — browsers (secure context), Node 19+, Deno
+ *   2. `crypto.getRandomValues()` — older browsers, RN with a crypto polyfill
+ *   3. `Math.random()`            — Hermes / JSC without a crypto polyfill
+ *
+ * Why this exists: report ids are written to the `reports.id uuid` column on
+ * the backend. SDKs that minted ad-hoc ids (`rn-<ts>-<rand>`, `mushi_<hex>`)
+ * failed the Postgres uuid cast (22P02) and the report was silently dropped
+ * (Sentry MUSHI-MUSHI-SERVER-D). Emitting a well-formed UUID at the source
+ * keeps the value valid end-to-end.
+ *
+ * A report id is an identifier, not a secret. The `Math.random` fallback only
+ * affects collision odds — negligible at our volume, and the backend dedupes
+ * on the `reports` primary key regardless — so we never throw just because a
+ * runtime lacks a CSPRNG.
+ */
+declare function newUuid(): string;
+
 /**
  * §3c — stable device fingerprint hash.
  *
@@ -1402,4 +1497,4 @@ declare function createLogger(options: LoggerOptions): Logger;
  */
 declare const noopLogger: Logger;
 
-export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiBannerConfig, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, 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 MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PiiScrubberConfig, type PreFilterResult, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, captureEnvironment, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, getDeviceFingerprintHash, getReporterToken, getSessionId, noopLogger, normaliseThrown, resolveRegionEndpoint, scrubPii };
+export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiBannerConfig, type MushiBannerLink, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, 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 MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PiiScrubberConfig, type PreFilterResult, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, captureEnvironment, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, getDeviceFingerprintHash, getReporterToken, getSessionId, newUuid, noopLogger, normaliseThrown, resolveRegionEndpoint, scrubPii };

package/dist/index.js

@@ -1035,6 +1035,26 @@ function generateToken() {
   return `mushi_${hex}`;
 }
 
+// src/uuid.ts
+function newUuid() {
+  const c = typeof crypto !== "undefined" ? crypto : void 0;
+  if (c?.randomUUID) {
+    return c.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (c?.getRandomValues) {
+    c.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
 // src/fingerprint.ts
 var CACHE_KEY = "mushi_fingerprint_hash";
 function collectInputs() {
@@ -1278,6 +1298,6 @@ function normaliseThrown(thrown) {
   return { name: "Error", message: String(thrown) };
 }
 
-export { DEFAULT_API_ENDPOINT, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, REGION_ENDPOINTS, captureEnvironment, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, getDeviceFingerprintHash, getReporterToken, getSessionId, noopLogger, normaliseThrown, resolveRegionEndpoint, scrubPii };
+export { DEFAULT_API_ENDPOINT, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, REGION_ENDPOINTS, captureEnvironment, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, getDeviceFingerprintHash, getReporterToken, getSessionId, newUuid, noopLogger, normaliseThrown, resolveRegionEndpoint, scrubPii };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map