@mushi-mushi/react-native 0.21.0 → 0.22.0

package/README.md

@@ -182,4 +182,4 @@ MIT
 <!-- mushi-readme-stats-footer -->
 ---
 
-<sub>Monorepo scale (July 2026): 51 edge functions · 323 SQL migrations · 13 outbound plugins · 11 inbound adapters · 19 pipeline agents. Canonical counts: <a href="https://github.com/kensaurus/mushi-mushi/blob/master/docs/stats.md">docs/stats.md</a> · <code>pnpm docs-stats</code></sub>
+<sub>Monorepo scale (July 2026): 59 edge functions · 374 SQL migrations · 13 outbound plugins · 11 inbound adapters · 19 pipeline agents. Canonical counts: <a href="https://github.com/kensaurus/mushi-mushi/blob/master/docs/stats.md">docs/stats.md</a> · <code>pnpm docs-stats</code></sub>

package/dist/index.cjs

@@ -49,7 +49,8 @@ module.exports = __toCommonJS(index_exports);
 
 // src/provider.tsx
 var import_react4 = require("react");
-var import_core6 = require("@mushi-mushi/core");
+var import_react_native5 = require("react-native");
+var import_core8 = require("@mushi-mushi/core");
 
 // src/capture/console-capture.ts
 var import_core = require("@mushi-mushi/core");
@@ -1479,13 +1480,336 @@ var s3 = import_react_native4.StyleSheet.create({
   }
 });
 
+// src/analytics/event-tracker.ts
+var import_core6 = require("@mushi-mushi/core");
+var CONSENT_BUFFER_MAX = 50;
+var SPILL_MAX = 200;
+var SPILL_TTL_MS = 24 * 60 * 60 * 1e3;
+var SURFACE = "mobile";
+async function defaultStorage() {
+  try {
+    const mod = await import("@react-native-async-storage/async-storage");
+    return mod.default;
+  } catch {
+    return null;
+  }
+}
+function createRNEventTracker(opts) {
+  const cfg = opts.config ?? {};
+  const enabled = cfg.enabled !== false;
+  const consentMode = cfg.consent ?? "implied";
+  const allowlist = cfg.propertyAllowlist ?? [];
+  const spillKey = `@mushi:events_spill_${opts.projectId}`;
+  const consentKey = `@mushi:analytics_consent_${opts.projectId}`;
+  let buffer = [];
+  let consentBuffer = [];
+  let consent = consentMode === "required" ? "pending" : "granted";
+  let userId = null;
+  let userTraits = null;
+  let pendingIdentify = false;
+  let flushing = false;
+  let destroyed = false;
+  let timer = null;
+  let storage = null;
+  const consentListeners = /* @__PURE__ */ new Set();
+  const loadStorage = opts.storage ?? defaultStorage;
+  const resolveClient = () => typeof opts.client === "function" ? opts.client() : opts.client;
+  async function readSpill() {
+    if (!storage) return [];
+    try {
+      const raw = await storage.getItem(spillKey);
+      if (!raw) return [];
+      const parsed = JSON.parse(raw);
+      if (!parsed || Date.now() - parsed.at > SPILL_TTL_MS) {
+        await storage.removeItem(spillKey);
+        return [];
+      }
+      return Array.isArray(parsed.events) ? parsed.events.slice(0, SPILL_MAX) : [];
+    } catch {
+      return [];
+    }
+  }
+  async function writeSpill(events) {
+    if (!storage) return;
+    try {
+      if (events.length === 0) await storage.removeItem(spillKey);
+      else await storage.setItem(spillKey, JSON.stringify({ at: Date.now(), events: events.slice(-SPILL_MAX) }));
+    } catch {
+    }
+  }
+  async function flushNow() {
+    if (destroyed && buffer.length === 0) return;
+    await ready;
+    if (flushing || consent !== "granted") return;
+    if (buffer.length === 0 && !pendingIdentify) return;
+    const client = resolveClient();
+    if (!client) return;
+    flushing = true;
+    const batch = buffer.splice(0, import_core6.EVENT_PROPERTY_LIMITS.maxServerBatch);
+    if (pendingIdentify) {
+      batch.unshift({ name: "identify", ts: (/* @__PURE__ */ new Date()).toISOString(), properties: {} });
+      pendingIdentify = false;
+    }
+    try {
+      const anonId = await Promise.resolve(opts.getAnonId());
+      const payload = {
+        anon_id: anonId,
+        user_id: userId ?? opts.getUserId?.() ?? null,
+        user_traits: userTraits ?? opts.getUserTraits?.() ?? null,
+        session_id: null,
+        sdk_version: opts.sdkVersion ?? null,
+        surface: SURFACE,
+        events: batch
+      };
+      const res = await client.postProductEvents(payload);
+      if (!res.ok) await writeSpill([...await readSpill(), ...batch.filter((e) => e.name !== "identify")]);
+      else await writeSpill([]);
+    } catch {
+      await writeSpill([...await readSpill(), ...batch.filter((e) => e.name !== "identify")]);
+    } finally {
+      flushing = false;
+    }
+    if (buffer.length >= import_core6.EVENT_PROPERTY_LIMITS.maxClientBatch) void flushNow();
+  }
+  function enqueue(ev) {
+    if (consent === "denied") return;
+    if (consent === "pending") {
+      if (consentBuffer.length < CONSENT_BUFFER_MAX) consentBuffer.push(ev);
+      return;
+    }
+    buffer.push(ev);
+    if (buffer.length >= import_core6.EVENT_PROPERTY_LIMITS.maxClientBatch) void flushNow();
+  }
+  const ready = enabled ? (async () => {
+    storage = await loadStorage();
+    if (destroyed) return;
+    let stored = null;
+    try {
+      stored = storage ? await storage.getItem(consentKey) : null;
+    } catch {
+      stored = null;
+    }
+    if (stored === "denied") {
+      consent = "denied";
+      buffer = [];
+      consentBuffer = [];
+      pendingIdentify = false;
+      await writeSpill([]);
+      return;
+    }
+    if (stored === "granted" && consent === "pending") {
+      consent = "granted";
+      buffer.push(...consentBuffer);
+      consentBuffer = [];
+    }
+    const spill = await readSpill();
+    if (spill.length > 0) {
+      buffer.unshift(...spill);
+      await writeSpill([]);
+    }
+  })().catch(() => void 0) : Promise.resolve();
+  if (enabled) {
+    const interval = Math.max(1e3, cfg.flushIntervalMs ?? 5e3);
+    timer = setInterval(() => {
+      void flushNow();
+    }, interval);
+  }
+  return {
+    ready,
+    track(name, properties, trackOpts) {
+      if (!enabled || destroyed) return false;
+      if (!(0, import_core6.isValidEventName)(name)) return false;
+      const { properties: props } = (0, import_core6.sanitizeEventProperties)(properties, { allowlist, scrub: opts.scrub });
+      let merged = props;
+      if (trackOpts?.reserved) {
+        const { properties: res } = (0, import_core6.sanitizeEventProperties)(trackOpts.reserved, { allowReserved: true, scrub: opts.scrub });
+        merged = { ...props, ...res };
+      }
+      merged.$surface = SURFACE;
+      const route = opts.getRoute?.();
+      if (route && merged.$route === void 0) merged.$route = route;
+      if (!(0, import_core6.propertiesWithinByteLimit)(merged)) return false;
+      enqueue({
+        name,
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        properties: merged,
+        ...trackOpts?.dedupKey ? { dedup_key: trackOpts.dedupKey } : {}
+      });
+      return true;
+    },
+    setConsent(state) {
+      void ready.then(() => storage?.setItem(consentKey, state)).catch(() => void 0);
+      if (state === "denied") {
+        consent = "denied";
+        buffer = [];
+        consentBuffer = [];
+        pendingIdentify = false;
+        void writeSpill([]);
+      } else {
+        const wasPending = consent === "pending";
+        consent = "granted";
+        if (wasPending && consentBuffer.length > 0) {
+          buffer.push(...consentBuffer);
+          consentBuffer = [];
+        }
+        if (buffer.length > 0 || pendingIdentify) void flushNow();
+      }
+      for (const listener of [...consentListeners]) {
+        try {
+          listener(state);
+        } catch {
+        }
+      }
+    },
+    setIdentity(id, traits) {
+      userId = id;
+      userTraits = traits ?? null;
+      if (id && enabled && consent !== "denied") {
+        pendingIdentify = true;
+        void flushNow();
+      }
+    },
+    consentState() {
+      return enabled ? consent : "denied";
+    },
+    onConsentChange(listener) {
+      consentListeners.add(listener);
+      return () => {
+        consentListeners.delete(listener);
+      };
+    },
+    async flush() {
+      await ready;
+      await flushNow();
+    },
+    async destroy() {
+      if (timer != null) {
+        clearInterval(timer);
+        timer = null;
+      }
+      await flushNow().catch(() => void 0);
+      destroyed = true;
+      buffer = [];
+      consentBuffer = [];
+      pendingIdentify = false;
+    }
+  };
+}
+
+// src/analytics/session-tracker.ts
+var import_core7 = require("@mushi-mushi/core");
+var HEARTBEAT_INTERVAL_MS = 6e4;
+var RESUME_WINDOW_MS = 30 * 6e4;
+function createRNSessionTracker(opts) {
+  const clock = opts.now ?? Date.now;
+  const resolveClient = () => typeof opts.client === "function" ? opts.client() : opts.client;
+  let sessionId = opts.sessionId ?? `sess_${(0, import_core7.newUuid)()}`;
+  let pageViewCount = 0;
+  let started = false;
+  let allowed = false;
+  let foreground = true;
+  let destroyed = false;
+  let backgroundedAt = null;
+  let heartbeat = null;
+  function route() {
+    return opts.getRoute?.() ?? null;
+  }
+  function send(kind, extra) {
+    const client = resolveClient();
+    if (!client || !allowed || destroyed) return;
+    const base = {
+      kind,
+      session_id: sessionId,
+      ts: new Date(clock()).toISOString(),
+      page_view_count: pageViewCount,
+      user_agent: opts.userAgent ?? null,
+      sdk_version: opts.sdkVersion
+    };
+    void Promise.resolve(opts.getReporterToken()).then((token) => client.postSessionEvent({ ...base, reporter_token_hash: token, ...extra })).catch(() => void 0);
+  }
+  function stopHeartbeat() {
+    if (heartbeat != null) {
+      clearInterval(heartbeat);
+      heartbeat = null;
+    }
+  }
+  function startHeartbeat() {
+    stopHeartbeat();
+    heartbeat = setInterval(() => send("session_heartbeat", { route: route() }), HEARTBEAT_INTERVAL_MS);
+  }
+  function startSession() {
+    started = true;
+    pageViewCount = 1;
+    send("session_start", { route: route() });
+    startHeartbeat();
+  }
+  function activate() {
+    if (allowed || destroyed) return;
+    allowed = true;
+    if (!foreground) return;
+    if (!started) startSession();
+    else startHeartbeat();
+  }
+  function deactivate() {
+    allowed = false;
+    stopHeartbeat();
+  }
+  const unsubscribe = opts.consent.onConsentChange(() => {
+    if (opts.consent.consentState() === "granted") activate();
+    else deactivate();
+  });
+  void opts.consent.ready.then(() => {
+    if (opts.consent.consentState() === "granted") activate();
+  }).catch(() => void 0);
+  return {
+    onAppStateChange(state) {
+      if (destroyed) return;
+      if (state === "active") {
+        if (foreground) return;
+        foreground = true;
+        const away = backgroundedAt == null ? 0 : clock() - backgroundedAt;
+        backgroundedAt = null;
+        if (!allowed) return;
+        if (!started || away >= RESUME_WINDOW_MS) {
+          sessionId = `sess_${(0, import_core7.newUuid)()}`;
+          startSession();
+        } else {
+          send("session_heartbeat", { route: route() });
+          startHeartbeat();
+        }
+        return;
+      }
+      if (state !== "background" || !foreground) return;
+      foreground = false;
+      backgroundedAt = clock();
+      stopHeartbeat();
+      if (started) send("session_end", { route: route() });
+    },
+    pageView(next) {
+      if (!allowed || !started || !foreground) return;
+      pageViewCount += 1;
+      send("page_view", { route: next });
+    },
+    destroy() {
+      destroyed = true;
+      deactivate();
+      unsubscribe();
+    }
+  };
+}
+
 // src/version.ts
 var MUSHI_SDK_PACKAGE = "@mushi-mushi/react-native";
-var MUSHI_SDK_VERSION = "0.21.0" ? "0.21.0" : "0.17.0";
+var MUSHI_SDK_VERSION = "0.22.0" ? "0.22.0" : "0.17.0";
 
 // src/provider.tsx
 var import_jsx_runtime4 = require("react/jsx-runtime");
 var MushiContext = (0, import_react4.createContext)(null);
+function nativeUserAgent() {
+  const os = import_react_native5.Platform?.OS ?? "native";
+  const version = import_react_native5.Platform?.Version;
+  return `${MUSHI_SDK_PACKAGE}/${MUSHI_SDK_VERSION} (${version != null ? `${os} ${String(version)}` : os})`;
+}
 var DEFAULT_SCREENSHOT_HINT = "Check the preview \u2014 remove it if any private info (balances, personal details) is visible.";
 function resolveScreenshotHint(v) {
   if (v === false) return null;
@@ -1528,9 +1852,9 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
   const networkRef = (0, import_react4.useRef)(null);
   const queueRef = (0, import_react4.useRef)(null);
   const apiClientRef = (0, import_react4.useRef)(null);
-  const sessionIdRef = (0, import_react4.useRef)(`sess_${(0, import_core6.newUuid)()}`);
+  const sessionIdRef = (0, import_react4.useRef)(`sess_${(0, import_core8.newUuid)()}`);
   const breadcrumbsRef = (0, import_react4.useRef)(
-    (0, import_core6.createBreadcrumbBuffer)({ max: config.capture?.maxBreadcrumbs ?? 50 })
+    (0, import_core8.createBreadcrumbBuffer)({ max: config.capture?.maxBreadcrumbs ?? 50 })
   );
   const [sheetVisible, setSheetVisible] = (0, import_react4.useState)(false);
   const [sheetPreferredTab, setSheetPreferredTab] = (0, import_react4.useState)("report");
@@ -1555,7 +1879,7 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
   if (config.endpoint && !config.apiEndpoint && __DEV__) {
     console.warn("[MushiProvider] `endpoint` is deprecated \u2014 use `apiEndpoint` instead.");
   }
-  const apiEndpoint = rawEndpoint ?? import_core6.DEFAULT_API_ENDPOINT;
+  const apiEndpoint = rawEndpoint ?? import_core8.DEFAULT_API_ENDPOINT;
   (0, import_react4.useEffect)(() => {
     if (config.capture?.console !== false) {
       consoleRef.current = setupConsoleCapture(config.capture?.maxConsoleEntries);
@@ -1563,7 +1887,7 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
     if (config.capture?.network !== false) {
       networkRef.current = setupNetworkCapture(config.capture?.maxNetworkEntries, apiEndpoint);
     }
-    apiClientRef.current = (0, import_core6.createApiClient)({
+    apiClientRef.current = (0, import_core8.createApiClient)({
       projectId: config.projectId,
       apiKey: config.apiKey,
       apiEndpoint,
@@ -1600,14 +1924,14 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
         if (existing && existing.startsWith("mushi_")) {
           reporterTokenRef.current = existing;
         } else {
-          const fresh = `mushi_${(0, import_core6.newUuid)()}`;
+          const fresh = `mushi_${(0, import_core8.newUuid)()}`;
           reporterTokenRef.current = fresh;
           await saveReporterToken(fresh, secureStorage);
         }
         resolveReporterTokenReady();
       } catch {
         if (reporterTokenRef.current === `rn-${config.projectId}-anon`) {
-          reporterTokenRef.current = `mushi_${(0, import_core6.newUuid)()}`;
+          reporterTokenRef.current = `mushi_${(0, import_core8.newUuid)()}`;
         }
         resolveReporterTokenReady();
       }
@@ -1727,7 +2051,7 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
       const merged = Object.keys(metadataRef.current).length > 0 ? { ...contextMeta, ...metadataRef.current } : Object.keys(contextMeta).length > 0 ? contextMeta : void 0;
       const breadcrumbs = breadcrumbsRef.current.getAll().map((c) => ({
         ...c,
-        message: (0, import_core6.scrubPii)(c.message)
+        message: (0, import_core8.scrubPii)(c.message)
       }));
       const timeline = breadcrumbs.map((c) => ({
         ts: c.timestamp,
@@ -1736,10 +2060,10 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
       }));
       const fingerprintHash = getDeviceFingerprintHash(deviceInfo);
       const report = {
-        id: (0, import_core6.newUuid)(),
+        id: (0, import_core8.newUuid)(),
         projectId: config.projectId,
         category: data.category,
-        description: (0, import_core6.scrubPii)(data.description),
+        description: (0, import_core8.scrubPii)(data.description),
         environment: {
           userAgent: deviceInfo.systemName ?? "ReactNative",
           platform: deviceInfo.platform ?? "mobile",
@@ -1752,7 +2076,7 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
         },
         consoleLogs: (consoleRef.current?.getEntries() ?? []).map((entry) => ({
           ...entry,
-          message: (0, import_core6.scrubPii)(entry.message)
+          message: (0, import_core8.scrubPii)(entry.message)
         })),
         networkLogs: networkRef.current?.getEntries().map((entry) => ({
           ...entry,
@@ -1782,7 +2106,7 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
         const code = result.error?.code ?? "";
         const isCredentialError = code === "HTTP_401" || code === "HTTP_403" || code.includes("UNAUTHORIZED") || code.includes("FORBIDDEN") || code.includes("INVALID_API_KEY");
         if (isCredentialError) {
-          const where = apiEndpoint.replace(/\/$/, "") === import_core6.DEFAULT_API_ENDPOINT ? "Get the correct values at: https://kensaur.us/mushi-mushi/admin/projects" : "Get the correct values from your Mushi console's Projects page.";
+          const where = apiEndpoint.replace(/\/$/, "") === import_core8.DEFAULT_API_ENDPOINT ? "Get the correct values at: https://kensaur.us/mushi-mushi/admin/projects" : "Get the correct values from your Mushi console's Projects page.";
           console.error(
             '[Mushi] Credentials rejected. Check your projectId and apiKey (must have "report:write" scope). ' + where
           );
@@ -1828,6 +2152,63 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
       if (rewardsFlushRef.current) clearInterval(rewardsFlushRef.current);
     };
   }, [config.rewards?.enabled, config.rewards?.trackActivity, config.rewards?.flushIntervalMs]);
+  const eventTrackerRef = (0, import_react4.useRef)(null);
+  const sessionTrackerRef = (0, import_react4.useRef)(null);
+  (0, import_react4.useEffect)(() => {
+    const getRoute = () => screenRef.current?.route ?? screenRef.current?.name ?? null;
+    const tracker = createRNEventTracker({
+      projectId: config.projectId,
+      client: () => apiClientRef.current,
+      getAnonId: async () => {
+        await reporterTokenReadyRef.current;
+        return reporterTokenRef.current;
+      },
+      getUserId: () => userRef.current?.id ?? null,
+      getRoute,
+      sdkVersion: MUSHI_SDK_VERSION,
+      config: config.analytics,
+      scrub: import_core8.scrubPii
+    });
+    eventTrackerRef.current = tracker;
+    const sessions = config.trackSessions === false ? null : createRNSessionTracker({
+      client: () => apiClientRef.current,
+      getReporterToken: async () => {
+        await reporterTokenReadyRef.current;
+        return reporterTokenRef.current;
+      },
+      getRoute,
+      consent: tracker,
+      sessionId: sessionIdRef.current,
+      sdkVersion: MUSHI_SDK_VERSION,
+      userAgent: nativeUserAgent()
+    });
+    sessionTrackerRef.current = sessions;
+    let sub;
+    try {
+      if (typeof import_react_native5.AppState?.addEventListener === "function") {
+        sub = import_react_native5.AppState.addEventListener("change", (state) => {
+          sessions?.onAppStateChange(state);
+          if (state !== "active") tracker.flush().catch(() => {
+          });
+        });
+      }
+    } catch {
+    }
+    return () => {
+      sub?.remove();
+      sessions?.destroy();
+      sessionTrackerRef.current = null;
+      eventTrackerRef.current = null;
+      tracker.destroy().catch(() => {
+      });
+    };
+  }, [
+    config.projectId,
+    config.analytics?.enabled,
+    config.analytics?.consent,
+    config.analytics?.flushIntervalMs,
+    config.trackSessions
+  ]);
   const instance = (0, import_react4.useMemo)(
     () => ({
       open,
@@ -1845,6 +2226,7 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
           name: traits?.name,
           provider: traits?.provider
         };
+        eventTrackerRef.current?.setIdentity(userId, traits ?? null);
       },
       setUser(user) {
         userRef.current = {
@@ -1853,18 +2235,22 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
           name: user.name,
           provider: user.provider
         };
+        eventTrackerRef.current?.setIdentity(user.id, { email: user.email, name: user.name, provider: user.provider });
       },
       identifyWithToken(token) {
         userTokenRef.current = token && typeof token === "string" ? token : null;
         if (userTokenRef.current) {
-          const claims = (0, import_core6.parseIdentityToken)(userTokenRef.current);
+          const claims = (0, import_core8.parseIdentityToken)(userTokenRef.current);
           if (claims?.sub) {
             userRef.current = {
               id: claims.sub,
               ...claims.email ? { email: claims.email } : {},
               ...claims.name ? { name: claims.name } : {}
             };
+            eventTrackerRef.current?.setIdentity(claims.sub, null);
           }
+        } else {
+          eventTrackerRef.current?.setIdentity(null, null);
         }
       },
       publishPageContext(context) {
@@ -1877,6 +2263,7 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
         const prev = screenRef.current?.name;
         screenRef.current = screen;
         if (screen.name && screen.name !== prev) {
+          sessionTrackerRef.current?.pageView(screen.route ?? screen.name);
           breadcrumbsRef.current.add({
             category: "navigation",
             level: "info",
@@ -1938,6 +2325,13 @@ function MushiProvider({ children, config: configProp, ...barePropConfig }) {
         if (!config.rewards?.enabled) return;
         activityQueueRef.current.push({ action, metadata });
       },
+      // Product analytics (Users & Funnels)
+      track(event, properties) {
+        return eventTrackerRef.current?.track(event, properties) ?? false;
+      },
+      setConsent(state) {
+        eventTrackerRef.current?.setConsent(state);
+      },
       async getTier() {
         const userId = userRef.current?.id;
         const client = apiClientRef.current;

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 {
@@ -190,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. */
@@ -390,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 };