@mushi-mushi/react-native 0.20.1 → 0.22.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,38 @@ 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'>;
+
 interface MushiRNConfig {
     projectId: string;
     apiKey: string;
@@ -115,6 +147,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 {
@@ -128,7 +176,11 @@ interface MushiRNInstance {
         description: string;
         category: string;
         screenshotDataUrl?: string;
-    }): Promise<void>;
+    }): Promise<{
+        ok: boolean;
+        queued?: boolean;
+        failureKind?: 'offline' | 'retrying' | 'rate_limited' | 'quota' | 'permanent' | 'credentials';
+    }>;
     getDeviceInfo(): ReturnType<typeof getDeviceInfo>;
     getConsoleEntries(): ReturnType<ReturnType<typeof setupConsoleCapture>['getEntries']>;
     getNetworkEntries(): ReturnType<ReturnType<typeof setupNetworkCapture>['getEntries']>;
@@ -186,6 +238,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. */
@@ -386,4 +447,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,38 @@ 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'>;
+
 interface MushiRNConfig {
     projectId: string;
     apiKey: string;
@@ -115,6 +147,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 {
@@ -128,7 +176,11 @@ interface MushiRNInstance {
         description: string;
         category: string;
         screenshotDataUrl?: string;
-    }): Promise<void>;
+    }): Promise<{
+        ok: boolean;
+        queued?: boolean;
+        failureKind?: 'offline' | 'retrying' | 'rate_limited' | 'quota' | 'permanent' | 'credentials';
+    }>;
     getDeviceInfo(): ReturnType<typeof getDeviceInfo>;
     getConsoleEntries(): ReturnType<ReturnType<typeof setupConsoleCapture>['getEntries']>;
     getNetworkEntries(): ReturnType<ReturnType<typeof setupNetworkCapture>['getEntries']>;
@@ -186,6 +238,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. */
@@ -386,4 +447,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 };