@mushi-mushi/react-native 0.21.0 → 0.23.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, FC, ReactElement } from 'react';
-import { MushiRewardsConfig, MushiPageContext, MushiBreadcrumb, MushiReporterReport, MushiReporterComment, MushiHallOfFameEntry, MushiTierResult, MushiReputationResult, MushiAssistantReply } from '@mushi-mushi/core';
+import { MushiAnalyticsConfig, MushiRewardsConfig, MushiPageContext, MushiBreadcrumb, MushiReporterReport, MushiReporterComment, MushiHallOfFameEntry, MushiPropertyValue, MushiTierResult, MushiReputationResult, MushiAssistantReply } from '@mushi-mushi/core';
 export { MushiHallOfFameEntry, MushiReporterComment, MushiReporterReport } from '@mushi-mushi/core';
 
 interface ConsoleEntry {
@@ -42,6 +42,74 @@ interface DeviceInfo {
 }
 declare function getDeviceInfo(): DeviceInfo;
 
+/**
+ * FILE: packages/react-native/src/analytics/event-tracker.ts
+ * PURPOSE: Product-analytics batcher behind `useMushi().track()` on React Native.
+ *
+ * OVERVIEW:
+ * - The core tracker (`@mushi-mushi/core` event-tracker.ts) returns early
+ *   without `window`, so RN gets this minimal port: in-memory batch, interval
+ *   flush, explicit `flush()` for app-background, AsyncStorage spill for
+ *   unsent batches (cap 200 / 24 h) and persisted consent.
+ * - Validation and PII rules are the shared ones from core
+ *   (`isValidEventName`, `sanitizeEventProperties`, `propertiesWithinByteLimit`).
+ * - Transport is `MushiApiClient.postProductEvents()` — the same
+ *   POST /v1/sdk/events the web SDK uses; `surface` is `'mobile'`.
+ *
+ * DEPENDENCIES:
+ * - @mushi-mushi/core — validation helpers + wire types.
+ * - @react-native-async-storage/async-storage — optional peer; without it the
+ *   batch is memory-only and consent is per-launch.
+ *
+ * USAGE:
+ * - Created by MushiProvider; hosts call `useMushi().track(name, props)`.
+ * - No React import here so the module is unit-testable with fake timers.
+ *
+ * NOTES:
+ * - No DNT signal exists on native; `analytics.enabled:false` or
+ *   `analytics.consent:'required'` + `setConsent('denied')` are the off switches.
+ *   App Tracking Transparency prompts remain the host's responsibility.
+ */
+
+/** The subset of the web `analytics` block that applies on native. */
+type RNAnalyticsConfig = Pick<MushiAnalyticsConfig, 'enabled' | 'consent' | 'flushIntervalMs' | 'propertyAllowlist'>;
+
+/**
+ * FILE: theme.ts
+ * PURPOSE: Host-adaptive theme for the RN report sheet (`widget.theme`).
+ *
+ * OVERVIEW:
+ * - Defaults are neutral: the shared washi/sumi surfaces with an INK accent,
+ *   so the sheet reads as part of the host app rather than a neon Mushi
+ *   product. The neon palette is only used by `<MushiBanner variant="neon">`.
+ * - Hosts override any token. When a host sets `accent` but not `accentFg`,
+ *   the text colour on the accent is picked for contrast (black or white).
+ *
+ * Plan 018 (docs/execplans/reporter-loop-v2.md §1.4).
+ */
+interface MushiRNTheme {
+    /** Sheet background. */
+    bg: string;
+    /** Primary text. */
+    fg: string;
+    /** Secondary text. */
+    muted: string;
+    /** Cards, inputs, chips. */
+    surface: string;
+    /** Borders and separators. */
+    border: string;
+    /** Selected chip, primary button, links. */
+    accent: string;
+    /** Text on `accent`. */
+    accentFg: string;
+    success: string;
+    error: string;
+    /** Host font family; undefined keeps the platform font. */
+    fontFamily?: string;
+    /** Corner radius for cards, inputs and buttons. */
+    radius: number;
+}
+
 interface MushiRNConfig {
     projectId: string;
     apiKey: string;
@@ -83,6 +151,13 @@ interface MushiRNConfig {
         };
         /** Poll interval (ms) for My Reports while the inbox tab is open. 0 = off (default). */
         inboxPollIntervalMs?: number;
+        /**
+         * Theme tokens for the report sheet (bg, fg, muted, surface, border,
+         * accent, accentFg, success, error, fontFamily, radius). Unset tokens
+         * use neutral system-style defaults with an ink accent; when only
+         * `accent` is set, the text on it is chosen for contrast.
+         */
+        theme?: Partial<MushiRNTheme>;
     };
     assistant?: {
         enabled?: boolean;
@@ -115,6 +190,22 @@ interface MushiRNConfig {
         secureStorage?: boolean;
     };
     rewards?: MushiRewardsConfig;
+    /**
+     * Product analytics (`useMushi().track()`). Events batch to
+     * POST /v1/sdk/events every 5 s, on app background and at 20 queued events;
+     * unsent batches spill to AsyncStorage (optional peer) and replay on the
+     * next launch. `consent: 'required'` buffers until `setConsent('granted')`.
+     * There is no DNT signal on native — `enabled: false` is the off switch.
+     */
+    analytics?: RNAnalyticsConfig;
+    /**
+     * Session lifecycle tracking for the console's Activity and Users views:
+     * session start / end on foreground and background, a heartbeat every
+     * minute, and a page view per `setScreen()` change. Default true. Follows
+     * the `analytics` switch and consent: nothing is sent while analytics is
+     * disabled or consent is not granted.
+     */
+    trackSessions?: boolean;
 }
 
 interface MushiRNInstance {
@@ -178,8 +269,12 @@ interface MushiRNInstance {
     }): void;
     /** List this device's reports ordered by most recent. Returns [] on failure. */
     listMyReports(): Promise<MushiReporterReport[]>;
-    /** List admin + reporter comments on a specific report. */
+    /** List admin + reporter comments on a specific report. Returns [] on failure. */
     listMyComments(reportId: string): Promise<MushiReporterComment[]>;
+    /** Like `listMyComments`, but resolves `null` when the thread could not be loaded, so a UI can offer Retry. */
+    loadMyThread(reportId: string): Promise<MushiReporterComment[] | null>;
+    /** Mark this device's unread notifications for a report as read. Resolves the number marked (0 on failure). */
+    markReportRead(reportId: string): Promise<number>;
     /** Post a reporter reply on a report thread. Returns the new comment or null on failure. */
     replyToReport(reportId: string, body: string): Promise<MushiReporterComment | null>;
     /** Record a reporter feedback signal (e.g. `confirms`, `not_fixed`) on a report. Returns the outcome or null. */
@@ -190,6 +285,15 @@ interface MushiRNInstance {
     getHallOfFame(limit?: number): Promise<MushiHallOfFameEntry[]>;
     /** Manually record a host-defined activity event. */
     recordActivity(action: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Record a product-analytics event, e.g. `track('checkout_started', { plan: 'pro' })`.
+     * Names must match `^[a-z][a-z0-9_]{1,63}$`; properties are flat, PII-looking
+     * keys are dropped and string values are scrubbed. Batched to
+     * POST /v1/sdk/events with `$surface: 'mobile'`. Returns true when queued.
+     */
+    track(event: string, properties?: Record<string, MushiPropertyValue>): boolean;
+    /** Grant or deny analytics consent (persisted in AsyncStorage when available). */
+    setConsent(state: 'granted' | 'denied'): void;
     /** Returns the current user's tier. */
     getTier(): Promise<MushiTierResult | null>;
     /** Returns the current user's reputation + point totals. */
@@ -226,7 +330,9 @@ declare function useMushiWidget(): {
  * - Slide-up modal built entirely on RN built-ins (Modal, Animated, PanResponder)
  * - Conversational flow: category → description → submit → confirmation
  * - Drag-to-dismiss via PanResponder on the handle area
- * - Dark/light theme via useColorScheme
+ * - Host-adaptive theme (`widget.theme`, see ../theme.ts) over light/dark
+ * - "Your reports": statuses come from the shared core table
+ *   (`@mushi-mushi/core/reporter-ui`), so web and RN say the same thing
  *
  * DEPENDENCIES:
  * - React Native built-in APIs only (no third-party libs)
@@ -240,10 +346,14 @@ declare function useMushiWidget(): {
  * - PanResponder threshold: 80 px downward drag dismisses
  * - Animated.spring for slide-up, Animated.timing for backdrop
  * - Success confirmation auto-closes after 1.4 s
+ * - Thread loads show a skeleton, then Retry on failure; a failed reply keeps
+ *   its text and offers Retry. Opening a thread marks it read.
  *
  * NOTES:
  * - KeyboardAvoidingView wraps the sheet so the text input stays visible
  * - Categories match the web SDK: bug, slow, visual, confusing, other
+ * - accessibilityViewIsModal is iOS-only; RN's Modal is its own window on
+ *   Android, which keeps TalkBack focus inside the sheet there.
  */
 
 interface MushiBottomSheetProps {
@@ -267,6 +377,8 @@ interface MushiBottomSheetProps {
     assistantSuggestions?: string[];
     /** Poll My Reports while inbox tab is open. 0 disables polling. */
     inboxPollIntervalMs?: number;
+    /** Theme tokens (`widget.theme`); unset tokens use the neutral defaults. */
+    theme?: Partial<MushiRNTheme>;
 }
 declare const MushiBottomSheet: FC<MushiBottomSheetProps>;
 
@@ -390,4 +502,4 @@ declare class AsyncStorageQueue {
     private getAsyncStorage;
 }
 
-export { AsyncStorageQueue, type ConsoleEntry, type DeviceInfo, MUSHI_BANNER_DEFAULT_HEIGHT, MushiBanner, type MushiBannerProps, MushiBottomSheet, type MushiBottomSheetProps, MushiFloatingButton, type MushiFloatingButtonProps, MushiProvider, type MushiRNConfig, type MushiRNInstance, MushiTrigger, type MushiTriggerProps, type NavigationEntry, type NetworkEntry, getDeviceInfo, setupConsoleCapture, setupNetworkCapture, useMushi, useMushiReport, useMushiWidget, useNavigationCapture };
+export { AsyncStorageQueue, type ConsoleEntry, type DeviceInfo, MUSHI_BANNER_DEFAULT_HEIGHT, MushiBanner, type MushiBannerProps, MushiBottomSheet, type MushiBottomSheetProps, MushiFloatingButton, type MushiFloatingButtonProps, MushiProvider, type MushiRNConfig, type MushiRNInstance, MushiTrigger, type MushiTriggerProps, type NavigationEntry, type NetworkEntry, type RNAnalyticsConfig, getDeviceInfo, setupConsoleCapture, setupNetworkCapture, useMushi, useMushiReport, useMushiWidget, useNavigationCapture };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, FC, ReactElement } from 'react';
-import { MushiRewardsConfig, MushiPageContext, MushiBreadcrumb, MushiReporterReport, MushiReporterComment, MushiHallOfFameEntry, MushiTierResult, MushiReputationResult, MushiAssistantReply } from '@mushi-mushi/core';
+import { MushiAnalyticsConfig, MushiRewardsConfig, MushiPageContext, MushiBreadcrumb, MushiReporterReport, MushiReporterComment, MushiHallOfFameEntry, MushiPropertyValue, MushiTierResult, MushiReputationResult, MushiAssistantReply } from '@mushi-mushi/core';
 export { MushiHallOfFameEntry, MushiReporterComment, MushiReporterReport } from '@mushi-mushi/core';
 
 interface ConsoleEntry {
@@ -42,6 +42,74 @@ interface DeviceInfo {
 }
 declare function getDeviceInfo(): DeviceInfo;
 
+/**
+ * FILE: packages/react-native/src/analytics/event-tracker.ts
+ * PURPOSE: Product-analytics batcher behind `useMushi().track()` on React Native.
+ *
+ * OVERVIEW:
+ * - The core tracker (`@mushi-mushi/core` event-tracker.ts) returns early
+ *   without `window`, so RN gets this minimal port: in-memory batch, interval
+ *   flush, explicit `flush()` for app-background, AsyncStorage spill for
+ *   unsent batches (cap 200 / 24 h) and persisted consent.
+ * - Validation and PII rules are the shared ones from core
+ *   (`isValidEventName`, `sanitizeEventProperties`, `propertiesWithinByteLimit`).
+ * - Transport is `MushiApiClient.postProductEvents()` — the same
+ *   POST /v1/sdk/events the web SDK uses; `surface` is `'mobile'`.
+ *
+ * DEPENDENCIES:
+ * - @mushi-mushi/core — validation helpers + wire types.
+ * - @react-native-async-storage/async-storage — optional peer; without it the
+ *   batch is memory-only and consent is per-launch.
+ *
+ * USAGE:
+ * - Created by MushiProvider; hosts call `useMushi().track(name, props)`.
+ * - No React import here so the module is unit-testable with fake timers.
+ *
+ * NOTES:
+ * - No DNT signal exists on native; `analytics.enabled:false` or
+ *   `analytics.consent:'required'` + `setConsent('denied')` are the off switches.
+ *   App Tracking Transparency prompts remain the host's responsibility.
+ */
+
+/** The subset of the web `analytics` block that applies on native. */
+type RNAnalyticsConfig = Pick<MushiAnalyticsConfig, 'enabled' | 'consent' | 'flushIntervalMs' | 'propertyAllowlist'>;
+
+/**
+ * FILE: theme.ts
+ * PURPOSE: Host-adaptive theme for the RN report sheet (`widget.theme`).
+ *
+ * OVERVIEW:
+ * - Defaults are neutral: the shared washi/sumi surfaces with an INK accent,
+ *   so the sheet reads as part of the host app rather than a neon Mushi
+ *   product. The neon palette is only used by `<MushiBanner variant="neon">`.
+ * - Hosts override any token. When a host sets `accent` but not `accentFg`,
+ *   the text colour on the accent is picked for contrast (black or white).
+ *
+ * Plan 018 (docs/execplans/reporter-loop-v2.md §1.4).
+ */
+interface MushiRNTheme {
+    /** Sheet background. */
+    bg: string;
+    /** Primary text. */
+    fg: string;
+    /** Secondary text. */
+    muted: string;
+    /** Cards, inputs, chips. */
+    surface: string;
+    /** Borders and separators. */
+    border: string;
+    /** Selected chip, primary button, links. */
+    accent: string;
+    /** Text on `accent`. */
+    accentFg: string;
+    success: string;
+    error: string;
+    /** Host font family; undefined keeps the platform font. */
+    fontFamily?: string;
+    /** Corner radius for cards, inputs and buttons. */
+    radius: number;
+}
+
 interface MushiRNConfig {
     projectId: string;
     apiKey: string;
@@ -83,6 +151,13 @@ interface MushiRNConfig {
         };
         /** Poll interval (ms) for My Reports while the inbox tab is open. 0 = off (default). */
         inboxPollIntervalMs?: number;
+        /**
+         * Theme tokens for the report sheet (bg, fg, muted, surface, border,
+         * accent, accentFg, success, error, fontFamily, radius). Unset tokens
+         * use neutral system-style defaults with an ink accent; when only
+         * `accent` is set, the text on it is chosen for contrast.
+         */
+        theme?: Partial<MushiRNTheme>;
     };
     assistant?: {
         enabled?: boolean;
@@ -115,6 +190,22 @@ interface MushiRNConfig {
         secureStorage?: boolean;
     };
     rewards?: MushiRewardsConfig;
+    /**
+     * Product analytics (`useMushi().track()`). Events batch to
+     * POST /v1/sdk/events every 5 s, on app background and at 20 queued events;
+     * unsent batches spill to AsyncStorage (optional peer) and replay on the
+     * next launch. `consent: 'required'` buffers until `setConsent('granted')`.
+     * There is no DNT signal on native — `enabled: false` is the off switch.
+     */
+    analytics?: RNAnalyticsConfig;
+    /**
+     * Session lifecycle tracking for the console's Activity and Users views:
+     * session start / end on foreground and background, a heartbeat every
+     * minute, and a page view per `setScreen()` change. Default true. Follows
+     * the `analytics` switch and consent: nothing is sent while analytics is
+     * disabled or consent is not granted.
+     */
+    trackSessions?: boolean;
 }
 
 interface MushiRNInstance {
@@ -178,8 +269,12 @@ interface MushiRNInstance {
     }): void;
     /** List this device's reports ordered by most recent. Returns [] on failure. */
     listMyReports(): Promise<MushiReporterReport[]>;
-    /** List admin + reporter comments on a specific report. */
+    /** List admin + reporter comments on a specific report. Returns [] on failure. */
     listMyComments(reportId: string): Promise<MushiReporterComment[]>;
+    /** Like `listMyComments`, but resolves `null` when the thread could not be loaded, so a UI can offer Retry. */
+    loadMyThread(reportId: string): Promise<MushiReporterComment[] | null>;
+    /** Mark this device's unread notifications for a report as read. Resolves the number marked (0 on failure). */
+    markReportRead(reportId: string): Promise<number>;
     /** Post a reporter reply on a report thread. Returns the new comment or null on failure. */
     replyToReport(reportId: string, body: string): Promise<MushiReporterComment | null>;
     /** Record a reporter feedback signal (e.g. `confirms`, `not_fixed`) on a report. Returns the outcome or null. */
@@ -190,6 +285,15 @@ interface MushiRNInstance {
     getHallOfFame(limit?: number): Promise<MushiHallOfFameEntry[]>;
     /** Manually record a host-defined activity event. */
     recordActivity(action: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Record a product-analytics event, e.g. `track('checkout_started', { plan: 'pro' })`.
+     * Names must match `^[a-z][a-z0-9_]{1,63}$`; properties are flat, PII-looking
+     * keys are dropped and string values are scrubbed. Batched to
+     * POST /v1/sdk/events with `$surface: 'mobile'`. Returns true when queued.
+     */
+    track(event: string, properties?: Record<string, MushiPropertyValue>): boolean;
+    /** Grant or deny analytics consent (persisted in AsyncStorage when available). */
+    setConsent(state: 'granted' | 'denied'): void;
     /** Returns the current user's tier. */
     getTier(): Promise<MushiTierResult | null>;
     /** Returns the current user's reputation + point totals. */
@@ -226,7 +330,9 @@ declare function useMushiWidget(): {
  * - Slide-up modal built entirely on RN built-ins (Modal, Animated, PanResponder)
  * - Conversational flow: category → description → submit → confirmation
  * - Drag-to-dismiss via PanResponder on the handle area
- * - Dark/light theme via useColorScheme
+ * - Host-adaptive theme (`widget.theme`, see ../theme.ts) over light/dark
+ * - "Your reports": statuses come from the shared core table
+ *   (`@mushi-mushi/core/reporter-ui`), so web and RN say the same thing
  *
  * DEPENDENCIES:
  * - React Native built-in APIs only (no third-party libs)
@@ -240,10 +346,14 @@ declare function useMushiWidget(): {
  * - PanResponder threshold: 80 px downward drag dismisses
  * - Animated.spring for slide-up, Animated.timing for backdrop
  * - Success confirmation auto-closes after 1.4 s
+ * - Thread loads show a skeleton, then Retry on failure; a failed reply keeps
+ *   its text and offers Retry. Opening a thread marks it read.
  *
  * NOTES:
  * - KeyboardAvoidingView wraps the sheet so the text input stays visible
  * - Categories match the web SDK: bug, slow, visual, confusing, other
+ * - accessibilityViewIsModal is iOS-only; RN's Modal is its own window on
+ *   Android, which keeps TalkBack focus inside the sheet there.
  */
 
 interface MushiBottomSheetProps {
@@ -267,6 +377,8 @@ interface MushiBottomSheetProps {
     assistantSuggestions?: string[];
     /** Poll My Reports while inbox tab is open. 0 disables polling. */
     inboxPollIntervalMs?: number;
+    /** Theme tokens (`widget.theme`); unset tokens use the neutral defaults. */
+    theme?: Partial<MushiRNTheme>;
 }
 declare const MushiBottomSheet: FC<MushiBottomSheetProps>;
 
@@ -390,4 +502,4 @@ declare class AsyncStorageQueue {
     private getAsyncStorage;
 }
 
-export { AsyncStorageQueue, type ConsoleEntry, type DeviceInfo, MUSHI_BANNER_DEFAULT_HEIGHT, MushiBanner, type MushiBannerProps, MushiBottomSheet, type MushiBottomSheetProps, MushiFloatingButton, type MushiFloatingButtonProps, MushiProvider, type MushiRNConfig, type MushiRNInstance, MushiTrigger, type MushiTriggerProps, type NavigationEntry, type NetworkEntry, getDeviceInfo, setupConsoleCapture, setupNetworkCapture, useMushi, useMushiReport, useMushiWidget, useNavigationCapture };
+export { AsyncStorageQueue, type ConsoleEntry, type DeviceInfo, MUSHI_BANNER_DEFAULT_HEIGHT, MushiBanner, type MushiBannerProps, MushiBottomSheet, type MushiBottomSheetProps, MushiFloatingButton, type MushiFloatingButtonProps, MushiProvider, type MushiRNConfig, type MushiRNInstance, MushiTrigger, type MushiTriggerProps, type NavigationEntry, type NetworkEntry, type RNAnalyticsConfig, getDeviceInfo, setupConsoleCapture, setupNetworkCapture, useMushi, useMushiReport, useMushiWidget, useNavigationCapture };