@mushi-mushi/core 1.15.0 → 1.16.0

package/dist/index.d.cts

@@ -19,6 +19,8 @@ interface MushiConfig {
     integrations?: MushiIntegrationsConfig;
     offline?: MushiOfflineConfig;
     rewards?: MushiRewardsConfig;
+    /** Page-aware, user-data-aware in-SDK assistant (P5). */
+    assistant?: MushiAssistantConfig;
     debug?: boolean;
     enabled?: boolean;
     /** Hook called before a report is sent. Return null to cancel, or return the (possibly modified) report. */
@@ -1024,6 +1026,56 @@ interface MushiDiagnosticsResult {
      */
     bannerRendered: boolean;
 }
+/**
+ * Page-aware assistant (P5). The host app publishes a structured snapshot of
+ * what the current screen is showing; the SDK forwards only this narrow,
+ * server-validated subset so a malicious page cannot inject arbitrary prompt
+ * fields. Ported from the admin console's page-context registry.
+ */
+interface MushiPageContext {
+    /** Current route/path (e.g. '/activity'). */
+    route: string;
+    /** Human title of the screen. */
+    title?: string;
+    /** One-line description of what is on screen. */
+    summary?: string;
+    /** Active filters as a flat key/value map. */
+    filters?: Record<string, string | number | boolean | null | undefined>;
+    /** The focused/selected entity, if any. */
+    selection?: {
+        kind: string;
+        id: string;
+        label?: string;
+    } | null;
+}
+interface MushiAssistantConfig {
+    /**
+     * Enable the in-SDK assistant tab. Defaults to false; the console can also
+     * enable it via runtime config so it can be turned on without a rebuild.
+     */
+    enabled?: boolean;
+    /** Tab label (default: "Ask"). */
+    label?: string;
+    /** Greeting shown on an empty assistant thread. */
+    greeting?: string;
+    /** Suggested starter questions shown on an empty thread. */
+    suggestions?: string[];
+}
+interface MushiAssistantStep {
+    label: string;
+    detail?: string;
+}
+interface MushiAssistantReply {
+    /** 'answer' resolves the turn; 'clarify' asks the user a follow-up. */
+    kind: 'answer' | 'clarify';
+    text?: string;
+    steps?: MushiAssistantStep[];
+    /** For 'clarify' replies. */
+    question?: string;
+    options?: string[];
+    /** Server-assigned thread id so the next turn continues the conversation. */
+    threadId?: string;
+}
 interface MushiSDKInstance {
     /**
      * Open the reporter widget. With no options, opens to the category
@@ -1100,6 +1152,26 @@ interface MushiSDKInstance {
         name?: string;
         [k: string]: unknown;
     }): void;
+    /**
+     * Identify the current end user with a signed Mushi identity JWT minted by
+     * the host app's server (see `@mushi-mushi/node`'s `mintMushiIdentityToken`).
+     * This is the trust anchor for secure "My Reports", rewards-to-membership
+     * grants, and the per-user assistant data index — the backend re-verifies
+     * the signature against the project's identity secret. Unlike `identify()`,
+     * which is spoofable, claims from this token are trusted server-side.
+     *
+     * Pass `null` (or call on logout) to clear the identity and fall back to the
+     * anonymous reporter token.
+     */
+    identifyWithToken(token: string | null): void;
+    /**
+     * Publish the current screen's context so the in-SDK assistant can answer
+     * page-aware questions. Call on every route/selection change. Pass `null`
+     * to clear (e.g. on unmount). Only a narrow subset is sent to the server.
+     */
+    publishPageContext(context: MushiPageContext | null): void;
+    /** Open the widget on the assistant ("Ask") tab. */
+    openAssistant(): void;
     /**
      * Sentry-grade observability surface (2026-05-07).
      *
@@ -1227,6 +1299,16 @@ interface MushiApiClient {
         status: MushiReportStatus;
     }>>;
     getSdkConfig(): Promise<MushiApiResponse<MushiRuntimeSdkConfig>>;
+    /**
+     * Send one assistant turn. Forwards the page context + thread id; the
+     * end-user identity token (when set) travels on the X-Mushi-User-Token
+     * header so the backend can scope retrieval to the verified user.
+     */
+    askAssistant(input: {
+        message: string;
+        threadId?: string | null;
+        context?: MushiPageContext | null;
+    }): Promise<MushiApiResponse<MushiAssistantReply>>;
     getLatestSdkVersion(packageName: string): Promise<MushiApiResponse<MushiSdkVersionInfo>>;
     /**
      * Mushi v2.1: ship a single passive-discovery observation (route +
@@ -1347,11 +1429,9 @@ interface MushiApiClient {
     /** Whether the caller has a mushi_testers row. */
     getTesterStatus(jwt: string): Promise<MushiApiResponse<{
         is_tester: boolean;
-        tester: {
-            id: string;
-            public_handle: string | null;
-            display_name: string | null;
-        } | null;
+        tester_id: string | null;
+        public_handle: string | null;
+        display_name: string | null;
     }>>;
 }
 /**
@@ -1471,6 +1551,12 @@ interface ApiClientOptions {
     apiEndpoint?: string;
     timeout?: number;
     maxRetries?: number;
+    /**
+     * Returns the current signed end-user identity JWT, or null when the user is
+     * anonymous. When present it is sent on the X-Mushi-User-Token header so the
+     * backend can verify it and scope identity-bound features to that user.
+     */
+    getUserToken?: () => string | null | undefined;
 }
 declare const DEFAULT_API_ENDPOINT = "https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api";
 declare const MUSHI_INTERNAL_HEADER = "X-Mushi-Internal";
@@ -1510,6 +1596,43 @@ declare function resolveRegionEndpoint(opts: {
     fetcher?: typeof fetch;
 }): Promise<string>;
 
+/**
+ * FILE: packages/core/src/env-config.ts
+ * PURPOSE: Reads Mushi credentials from the environment when they are not
+ *          supplied explicitly. This lets every framework init work with
+ *          zero-config — just run `npx mushi-mushi` once, add the .env.local
+ *          line, and the provider/plugin/init works without props.
+ *
+ * Resolution order per field:
+ *   1. Vite / SvelteKit / Angular (VITE_MUSHI_*)
+ *   2. Next.js (NEXT_PUBLIC_MUSHI_*)
+ *   3. Nuxt (NUXT_PUBLIC_MUSHI_*)
+ *   4. Expo managed workflow (EXPO_PUBLIC_MUSHI_*)
+ *   5. Node / React Native / server (bare MUSHI_*)
+ *
+ * Vite statically replaces `import.meta.env.VITE_*` at build time, so the
+ * literal key references here are intentional — they make bundlers replace
+ * the values even when accessed indirectly.
+ *
+ * Next.js and Expo, by contrast, do STATIC string replacement that only
+ * inlines literal `process.env.NEXT_PUBLIC_*` / `process.env.EXPO_PUBLIC_*`
+ * dot-notation references. A dynamic `process.env[key]` lookup is explicitly
+ * unsupported and silently resolves to `undefined` in production client
+ * bundles (Expo even ships an ESLint rule against it). Every `process.env`
+ * read below is therefore a literal, statically-analyzable reference.
+ */
+interface ResolvedEnvConfig {
+    projectId?: string;
+    apiKey?: string;
+    apiEndpoint?: string;
+}
+/**
+ * Reads Mushi projectId, apiKey, and (optionally) apiEndpoint from
+ * the environment. Returns only the fields that are present so callers
+ * can cleanly spread: `{ ...resolveEnvConfig(), ...explicitConfig }`.
+ */
+declare function resolveEnvConfig(): ResolvedEnvConfig;
+
 interface PreFilterResult {
     passed: boolean;
     reason?: string;
@@ -1802,4 +1925,208 @@ 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, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, 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 MushiCrossAppReport, type MushiCustomCategory, type MushiDiagnosticsResult, type MushiDiscoverInventoryConfig, type MushiDiscoveryEventPayload, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiHallOfFameEntry, type MushiIntegrationsConfig, type MushiInternalRequestKind, type MushiLeaderboardEntry, 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 MushiTesterReputation, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiTracePropagationConfig, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PayloadGuardResult, type PiiScrubberConfig, type PreFilterResult, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, estimateJsonBytes, formatBytes, getDeviceFingerprintHash, getReporterToken, getSessionId, newUuid, noopLogger, normaliseThrown, resolveRegionEndpoint, scrubPii };
+/**
+ * FILE: packages/core/src/design-tokens.ts
+ * PURPOSE: The single cross-platform source of truth for Mushi widget design.
+ *
+ * Every platform SDK (web Shadow-DOM CSS, React Native components, Capacitor
+ * native sheet) reads its colours, spacing, radii, typography, z-index scale,
+ * motion, launcher geometry, and default copy from this module so the widget
+ * renders coherently everywhere. `@mushi-mushi/core` is already a dependency
+ * of every platform package, which is why the tokens live here rather than in
+ * a separate published package — one import path, no extra build wiring.
+ *
+ * Colour values mirror the historical washi/vermillion palette previously
+ * inlined in `@mushi-mushi/web`'s styles.ts so the visual identity is
+ * unchanged; the difference is that RN and Capacitor now share the exact
+ * same constants instead of re-deriving their own.
+ */
+type MushiThemeMode = 'light' | 'dark';
+interface MushiColorPalette {
+    /** washi cream / dark wash — primary surface */
+    paper: string;
+    /** elevated surface (panels, sheets) */
+    paperRaised: string;
+    /** sumi black / cream type — primary text */
+    ink: string;
+    /** captions, descriptions */
+    inkMuted: string;
+    /** disabled, separators */
+    inkFaint: string;
+    /** dim text */
+    inkDim: string;
+    /** hairline rules */
+    rule: string;
+    /** stronger rules / borders */
+    ruleStrong: string;
+    /** 朱 hanko red — signature accent */
+    accent: string;
+    /** ~8–12% accent wash */
+    accentWash: string;
+    /** accessible text on the accent wash */
+    accentInk: string;
+    /** success */
+    ok: string;
+    /** danger / destructive */
+    danger: string;
+}
+/** Light-mode palette. */
+declare const MUSHI_COLORS_LIGHT: MushiColorPalette;
+/** Dark-mode palette. */
+declare const MUSHI_COLORS_DARK: MushiColorPalette;
+/** Resolve the palette for a theme mode. */
+declare function mushiPalette(mode: MushiThemeMode): MushiColorPalette;
+/**
+ * Spacing scale (px). Named by feel, matching the editorial design system so
+ * the same rhythm reads across web and native.
+ */
+declare const MUSHI_SPACING: {
+    readonly hairline: 2;
+    readonly tight: 4;
+    readonly snug: 8;
+    readonly comfy: 12;
+    readonly roomy: 16;
+    readonly lounge: 20;
+    readonly open: 24;
+    readonly wide: 32;
+};
+/** Corner radii (px). Tables/strips stay sharp; controls get soft corners. */
+declare const MUSHI_RADIUS: {
+    readonly none: 0;
+    readonly control: 4;
+    readonly card: 10;
+    readonly sheet: 16;
+    readonly pill: 999;
+};
+/** Typography stacks shared by every platform (system-first, no web-font fetch). */
+declare const MUSHI_TYPE: {
+    readonly fontDisplay: "'Iowan Old Style', 'Palatino Linotype', 'Palatino', 'Book Antiqua', 'Cambria', Georgia, 'Times New Roman', serif";
+    readonly fontBody: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI Variable Display', 'Segoe UI', sans-serif";
+    readonly fontMono: "ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, Consolas, 'Liberation Mono', monospace";
+    readonly sizeBody: 14;
+    readonly sizeLabel: 12;
+    readonly sizeTitle: 16;
+    readonly lineBody: 1.55;
+};
+/**
+ * z-index scale. The host element is pass-through; only interactive surfaces
+ * opt back into pointer events. Banner sits just under the FAB; panel above.
+ */
+declare const MUSHI_Z: {
+    readonly base: 99999;
+    /** banner sits one below the trigger so an open FAB overlaps it */
+    readonly banner: 99998;
+    /** report/assistant panel sits one above the trigger */
+    readonly panel: 100000;
+    /** element-selector overlay — always on top */
+    readonly overlay: 2147483647;
+};
+/** Motion signature — a soft back-out "stamp press". */
+declare const MUSHI_MOTION: {
+    readonly easeStamp: "cubic-bezier(0.22, 1, 0.36, 1)";
+    readonly durationFast: 200;
+    readonly durationPanel: 300;
+};
+/**
+ * Launcher geometry — the numbers that previously diverged between platforms
+ * (banner height, FAB size, default gutter, panel width). Centralising them
+ * is what fixes the "different on every app" + safe-area bleed problems.
+ */
+declare const MUSHI_GEOMETRY: {
+    readonly bannerHeight: 36;
+    readonly fabSize: 52;
+    readonly edgeTabWidth: 28;
+    /** default gutter from the screen edge (added on top of safe-area insets) */
+    readonly gutter: 24;
+    readonly panelWidth: 384;
+    /** below this viewport width the panel becomes a full-width bottom sheet */
+    readonly panelSheetBreakpoint: 480;
+};
+/**
+ * Default user-facing copy. Centralised so apps stop drifting on the banner
+ * label / CTA wording (seen as inconsistent across the four host apps).
+ */
+declare const MUSHI_COPY: {
+    readonly bannerLabel: "Beta";
+    readonly bannerMessage: "Help us improve — your feedback shapes what we ship.";
+    readonly bugCta: "Report a bug";
+    readonly featureCta: "Feature request";
+    readonly triggerText: "🐛";
+    readonly panelTitle: "Send feedback";
+    readonly myReportsTab: "My reports";
+    readonly assistantTab: "Ask";
+};
+/** A flat, serialisable snapshot of every token for a given theme mode. */
+interface MushiTokenSnapshot {
+    mode: MushiThemeMode;
+    colors: MushiColorPalette;
+    spacing: typeof MUSHI_SPACING;
+    radius: typeof MUSHI_RADIUS;
+    type: typeof MUSHI_TYPE;
+    z: typeof MUSHI_Z;
+    motion: typeof MUSHI_MOTION;
+    geometry: typeof MUSHI_GEOMETRY;
+    copy: typeof MUSHI_COPY;
+}
+/** Build a full token snapshot for a theme mode (used by RN/Capacitor). */
+declare function mushiTokens(mode: MushiThemeMode): MushiTokenSnapshot;
+
+/**
+ * FILE: packages/core/src/identity.ts
+ * PURPOSE: The signed-JWT end-user identity contract shared between the SDK
+ *          and the Mushi backend.
+ *
+ * The host app's server mints a short-lived JWT (HS256, signed with the
+ * project's identity secret obtained from the console) describing the
+ * currently-logged-in end user, and hands it to the SDK via
+ * `Mushi.identifyWithToken(jwt)`. The SDK never verifies the signature — it
+ * only base64url-decodes the payload to show the user's name locally and
+ * forwards the raw token to the backend, which verifies it against the
+ * per-project secret before trusting any claim. This mirrors the Featurebase
+ * `featurebaseJwt` model and is the trust anchor for "My Reports", rewards,
+ * and the per-user assistant data index.
+ *
+ * Anonymous reporters (logged-out) keep using the random reporter token; the
+ * signed JWT is purely additive.
+ */
+/** Claims carried by a Mushi end-user identity token. */
+interface MushiIdentityClaims {
+    /** Mushi external project id this token is scoped to. */
+    projectId: string;
+    /** The host app's stable id for this end user (becomes `external_user_id`). */
+    sub: string;
+    /** Optional display email (never stored raw server-side — hashed). */
+    email?: string;
+    /** Optional display name. */
+    name?: string;
+    /** Issued-at (seconds since epoch). */
+    iat?: number;
+    /** Expiry (seconds since epoch). Tokens should be short-lived (<= 1h). */
+    exp?: number;
+}
+/**
+ * Sentinel so callers can distinguish a Mushi identity token from the random
+ * anonymous reporter token (`mushi_<uuid>`). Identity tokens are standard JWTs
+ * (three dot-separated base64url segments), so this prefix is informational
+ * only and not embedded in the wire format.
+ */
+declare const MUSHI_IDENTITY_TOKEN_PREFIX = "mushi.identity";
+/**
+ * Build the canonical claims object a host server should sign. Exposed so the
+ * `@mushi-mushi/node` SDK and docs share one definition of the payload shape.
+ */
+declare function buildIdentityClaims(input: {
+    projectId: string;
+    userId: string;
+    email?: string;
+    name?: string;
+    ttlSeconds?: number;
+}): Required<Pick<MushiIdentityClaims, 'projectId' | 'sub' | 'iat' | 'exp'>> & Pick<MushiIdentityClaims, 'email' | 'name'>;
+/**
+ * Decode (WITHOUT verifying) the claims of an identity JWT. Returns null if the
+ * token is malformed. CLIENT-SIDE DISPLAY ONLY — never trust these claims for
+ * authorisation; the server re-verifies the signature.
+ */
+declare function parseIdentityToken(token: string): MushiIdentityClaims | null;
+
+export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, MUSHI_COLORS_DARK, MUSHI_COLORS_LIGHT, MUSHI_COPY, MUSHI_GEOMETRY, MUSHI_IDENTITY_TOKEN_PREFIX, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, MUSHI_MOTION, MUSHI_RADIUS, MUSHI_SPACING, MUSHI_TYPE, MUSHI_Z, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiAssistantConfig, type MushiAssistantReply, type MushiAssistantStep, type MushiBannerConfig, type MushiBannerLink, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, type MushiColorPalette, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiCrossAppReport, type MushiCustomCategory, type MushiDiagnosticsResult, type MushiDiscoverInventoryConfig, type MushiDiscoveryEventPayload, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiHallOfFameEntry, type MushiIdentityClaims, type MushiIntegrationsConfig, type MushiInternalRequestKind, type MushiLeaderboardEntry, type MushiNetworkEntry, type MushiOfflineConfig, type MushiOnDeviceClassifier, type MushiOnDeviceClassifierInput, type MushiOnDeviceClassifierResult, type MushiPageContext, 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 MushiTesterReputation, type MushiThemeMode, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiTokenSnapshot, type MushiTracePropagationConfig, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PayloadGuardResult, type PiiScrubberConfig, type PreFilterResult, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, type ResolvedEnvConfig, buildIdentityClaims, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, estimateJsonBytes, formatBytes, getDeviceFingerprintHash, getReporterToken, getSessionId, mushiPalette, mushiTokens, newUuid, noopLogger, normaliseThrown, parseIdentityToken, resolveEnvConfig, resolveRegionEndpoint, scrubPii };