@mobileai/react-native 0.9.18 → 0.9.20

package/lib/typescript/src/index.d.ts

@@ -6,6 +6,7 @@
  */
 export { AIAgent } from './components/AIAgent';
 export { AIZone } from './components/AIZone';
+export { AIConsentDialog, useAIConsent } from './components/AIConsentDialog';
 export { InfoCard } from './components/cards/InfoCard';
 export { ReviewSummary } from './components/cards/ReviewSummary';
 export { GeminiProvider } from './providers/GeminiProvider';
@@ -16,11 +17,15 @@ export { VoiceService } from './services/VoiceService';
 export { AudioInputService } from './services/AudioInputService';
 export { AudioOutputService } from './services/AudioOutputService';
 export { KnowledgeBaseService } from './services/KnowledgeBaseService';
+export { createMobileAIKnowledgeRetriever } from './services/MobileAIKnowledgeRetriever';
 export { MobileAI } from './services/telemetry';
 export { logger } from './utils/logger';
-export type { AgentConfig, AgentMode, ExecutionResult, InteractiveElement, DehydratedScreen, ToolDefinition, ActionDefinition, TokenUsage, KnowledgeEntry, KnowledgeRetriever, KnowledgeBaseConfig, ChatBarTheme, AIMessage, AIProviderName, ScreenMap, ScreenMapEntry, InteractionMode, } from './core/types';
+export type { AgentConfig, AgentMode, ExecutionResult, InteractiveElement, DehydratedScreen, ToolDefinition, ActionDefinition, TokenUsage, KnowledgeEntry, KnowledgeRetriever, KnowledgeBaseConfig, ChatBarTheme, AIMessage, AIProviderName, ScreenMap, ScreenMapEntry, InteractionMode, ConversationSummary, } from './core/types';
+export type { MobileAIKnowledgeRetrieverOptions } from './services/MobileAIKnowledgeRetriever';
+export type { AIConsentConfig } from './components/AIConsentDialog';
 export type { VoiceServiceConfig, VoiceServiceCallbacks, VoiceStatus, } from './services/VoiceService';
-export type { TelemetryConfig, TelemetryEvent, } from './services/telemetry';
-export { SupportGreeting, CSATSurvey, buildSupportPrompt, createEscalateTool, EscalationSocket } from './support';
-export type { SupportModeConfig, QuickReply, EscalationConfig, EscalationContext, CSATConfig, CSATRating, BusinessHoursConfig, SupportTicket, } from './support';
+export type { TelemetryConfig, TelemetryEvent } from './services/telemetry';
+export { SupportGreeting, CSATSurvey, buildSupportPrompt, createEscalateTool, EscalationSocket, } from './support';
+export { createReportIssueTool } from './support';
+export type { SupportModeConfig, QuickReply, EscalationConfig, EscalationContext, CSATConfig, CSATRating, BusinessHoursConfig, SupportTicket, ReportedIssue, ReportedIssueCustomerStatus, ReportedIssueStatusUpdate, } from './support';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/providers/GeminiProvider.d.ts

@@ -16,15 +16,16 @@ export declare class GeminiProvider implements AIProvider {
     constructor(apiKey?: string, model?: string, proxyUrl?: string, proxyHeaders?: Record<string, string>);
     generateContent(systemPrompt: string, userMessage: string, tools: ToolDefinition[], history: AgentStep[], screenshot?: string): Promise<ProviderResult>;
     /**
-     * Builds a single `agent_step` function declaration that combines:
-     * - Structured reasoning fields (previous_goal_eval, memory, plan)
+     * Builds a single `agent_step` function declaration that keeps Gemini's
+     * served schema intentionally narrow:
+     * - Structured reasoning fields
      * - action_name (enum of all available tool names)
-     * - All tool parameter fields as flat top-level properties
+     * - action_input as a JSON object string
      *
-     * Flat schema avoids Gemini's "deeply nested schema" rejection in ANY mode.
+     * Flattening every tool parameter into top-level properties can trigger
+     * Gemini's "too much branching for serving" error once the toolset grows.
      */
     private buildAgentStepDeclaration;
-    private mapParamType;
     /**
      * Builds contents for the generateContent call.
      * Single-turn: user message + optional screenshot as inlineData.

package/lib/typescript/src/services/ConversationService.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ConversationService — backend-persisted AI conversation history.
+ *
+ * Saves and retrieves AI chat sessions from the MobileAI backend so users
+ * can browse and continue previous conversations across app launches.
+ *
+ * All methods are no-ops when analyticsKey is absent (graceful degradation).
+ * All network errors are silently swallowed — history is best-effort and must
+ * never break the core agent flow.
+ */
+import type { AIMessage, ConversationSummary } from '../core/types';
+interface StartConversationParams {
+    analyticsKey: string;
+    userId?: string;
+    deviceId?: string;
+    messages: AIMessage[];
+}
+interface AppendMessagesParams {
+    conversationId: string;
+    analyticsKey: string;
+    messages: AIMessage[];
+}
+interface FetchConversationsParams {
+    analyticsKey: string;
+    userId?: string;
+    deviceId?: string;
+    limit?: number;
+}
+interface FetchConversationParams {
+    conversationId: string;
+    analyticsKey: string;
+}
+/**
+ * Start a new conversation on the backend.
+ * Call this when the first AI response arrives in a new session.
+ * Returns the backend conversationId, or null on failure.
+ */
+export declare function startConversation({ analyticsKey, userId, deviceId, messages, }: StartConversationParams): Promise<string | null>;
+/**
+ * Append new messages to an existing conversation.
+ * Fire-and-forget — call after each exchange (debounce in caller).
+ */
+export declare function appendMessages({ conversationId, analyticsKey, messages, }: AppendMessagesParams): Promise<void>;
+/**
+ * Fetch the user's conversation list (most-recent-first).
+ * Returns empty array on failure — never throws.
+ */
+export declare function fetchConversations({ analyticsKey, userId, deviceId, limit, }: FetchConversationsParams): Promise<ConversationSummary[]>;
+/**
+ * Fetch the full message history of a single conversation.
+ * Returns null on failure.
+ */
+export declare function fetchConversation({ conversationId, analyticsKey, }: FetchConversationParams): Promise<AIMessage[] | null>;
+export {};
+//# sourceMappingURL=ConversationService.d.ts.map

package/lib/typescript/src/services/MobileAIKnowledgeRetriever.d.ts

@@ -0,0 +1,9 @@
+import type { KnowledgeRetriever } from '../core/types';
+export interface MobileAIKnowledgeRetrieverOptions {
+    publishableKey: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    limit?: number;
+}
+export declare function createMobileAIKnowledgeRetriever(options: MobileAIKnowledgeRetrieverOptions): KnowledgeRetriever;
+//# sourceMappingURL=MobileAIKnowledgeRetriever.d.ts.map

package/lib/typescript/src/services/telemetry/MobileAI.d.ts

@@ -29,6 +29,13 @@ export declare const MobileAI: {
      * @param defaultValue Fallback if not assigned
      */
     getFlag(key: string, defaultValue?: string): string;
+    /**
+     * Helper function to securely consume a global WOW action limit (like a discount)
+     * natively on the MobileAI Server to prevent prompt injection bypasses.
+     * @param actionName - The exact registered name of the WOW action
+     * @returns true if allowed, false if rejected or error
+     */
+    consumeWowAction(actionName: string): Promise<boolean>;
 };
 /**
  * Internal: Bind the TelemetryService instance (called by AIAgent on mount).

package/lib/typescript/src/services/telemetry/TelemetryService.d.ts

@@ -11,7 +11,7 @@ import type { TelemetryConfig } from './types';
 import { FlagService } from '../flags/FlagService';
 export declare class TelemetryService {
     private queue;
-    private config;
+    config: TelemetryConfig;
     private sessionId;
     private currentScreen;
     private screenFlow;

package/lib/typescript/src/services/telemetry/TouchAutoCapture.d.ts

@@ -13,16 +13,19 @@
  */
 import type { TelemetryService } from './TelemetryService';
 /**
- * Checks if the user is repeatedly tapping the same element in frustration.
- * If rage click detected, emits 'rage_click' event to telemetry.
+ * Checks if the user is rage-tapping an element.
+ *
+ * Industry best-practice criteria:
+ * 1. Same label tapped 3+ times within 1 second
+ * 2. Taps must be on the SAME screen (screen change = not rage, it's navigation)
+ * 3. Navigation labels ("Next", "Skip", etc.) are excluded
  */
 export declare function checkRageClick(label: string, telemetry: TelemetryService): void;
 /**
- * Extract a label from a GestureResponderEvent's native target.
+ * Extract a label from a GestureResponderEvent.
  *
- * @param nativeEvent - The nativeEvent from onStartShouldSetResponderCapture
- * @param rootRef - The root View ref (to resolve relative positions)
+ * @param event - The GestureResponderEvent from onStartShouldSetResponderCapture
  * @returns A descriptive label string for the tapped element
  */
-export declare function extractTouchLabel(nativeEvent: any): string;
+export declare function extractTouchLabel(event: any): string;
 //# sourceMappingURL=TouchAutoCapture.d.ts.map

package/lib/typescript/src/services/telemetry/types.d.ts

@@ -6,7 +6,7 @@
  * 2. Consumer-tracked: via MobileAI.track() API
  */
 /** Auto-captured event types */
-export type AutoEventType = 'screen_view' | 'user_action' | 'scroll_depth' | 'idle_detected' | 'session_start' | 'session_end' | 'agent_request' | 'agent_step' | 'agent_complete' | 'escalation' | 'knowledge_query' | 'knowledge_miss' | 'csat_response';
+export type AutoEventType = 'screen_view' | 'user_action' | 'scroll_depth' | 'idle_detected' | 'session_start' | 'session_end' | 'agent_request' | 'agent_step' | 'agent_trace' | 'agent_complete' | 'escalation' | 'knowledge_query' | 'knowledge_miss' | 'csat_response' | 'ces_response' | 'agent_first_response' | 'human_first_response' | 'fcr_achieved' | 'engagement_signal' | 'health_signal' | 'onboarding_step';
 /** All event types (auto + custom) */
 export type EventType = AutoEventType | string;
 export interface TelemetryEvent {
@@ -46,5 +46,7 @@ export interface TelemetryConfig {
     maxBatchSize?: number;
     /** Enable debug logging for telemetry (default: false) */
     debug?: boolean;
+    /** Callback fired locally whenever an event is tracked (useful for reacting to rage_tap) */
+    onEvent?: (event: import('./types').TelemetryEvent) => void;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/specs/FloatingOverlayNativeComponent.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Codegen spec for MobileAIFloatingOverlay native view.
+ *
+ * This file is required by React Native's Codegen (New Architecture / Fabric).
+ * It defines the TypeScript interface for the native view. During the build,
+ * Codegen uses this spec to generate C++ glue code that bridges JS and native.
+ *
+ * Consumers don't use this directly — use FloatingOverlayWrapper.tsx instead.
+ *
+ * Naming convention: file must end in NativeComponent.ts (Codegen convention).
+ */
+import type { ViewProps } from 'react-native';
+export interface NativeProps extends ViewProps {
+}
+declare const _default: import("react-native/Libraries/Utilities/codegenNativeComponent").NativeComponentType<NativeProps>;
+export default _default;
+//# sourceMappingURL=FloatingOverlayNativeComponent.d.ts.map

package/lib/typescript/src/support/EscalationSocket.d.ts

@@ -12,6 +12,7 @@
  * Handles:
  * - Server heartbeat pings (type: 'ping') — acknowledged silently
  * - Auto-reconnect on unexpected close (max 3 attempts, exponential backoff)
+ * - Message queue — buffers sendText calls while connecting, flushes on open
  */
 export type SocketReplyHandler = (reply: string, ticketId?: string) => void;
 interface EscalationSocketOptions {
@@ -27,6 +28,9 @@ export declare class EscalationSocket {
     private reconnectAttempts;
     private reconnectTimer;
     private intentionalClose;
+    private _hasErrored;
+    /** Messages buffered while the socket is connecting / reconnecting. */
+    private messageQueue;
     private readonly onReply;
     private readonly onError?;
     private readonly onTypingChange?;
@@ -34,9 +38,22 @@ export declare class EscalationSocket {
     private readonly maxReconnectAttempts;
     constructor(options: EscalationSocketOptions);
     connect(wsUrl: string): void;
+    /** True if the underlying WebSocket is open and ready to send. */
+    get isConnected(): boolean;
+    /** True if the socket encountered an error (and may not be reliable to reuse). */
+    get hasErrored(): boolean;
+    /**
+     * Send a text message to the live agent.
+     *
+     * If the socket is currently connecting or reconnecting, the message is
+     * buffered and sent automatically once the connection is established.
+     * Returns `true` in both cases (connected send + queued send).
+     * Returns `false` only if the socket has no URL (was never connected).
+     */
     sendText(text: string): boolean;
     sendTypingStatus(isTyping: boolean): boolean;
     disconnect(): void;
+    private flushQueue;
     private openConnection;
     private scheduleReconnect;
 }

package/lib/typescript/src/support/ReportedIssueEventSource.d.ts

@@ -0,0 +1,24 @@
+import type { ReportedIssue } from './types';
+export interface ReportedIssueEventSourceOptions {
+    url: string;
+    onIssueUpdate?: (issue: ReportedIssue) => void;
+    onConnected?: () => void;
+    onError?: (error: Error) => void;
+}
+export declare class ReportedIssueEventSource {
+    private abortController;
+    private intentionalClose;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private readonly maxReconnectAttempts;
+    private readonly options;
+    constructor(options: ReportedIssueEventSourceOptions);
+    connect(): void;
+    disconnect(): void;
+    private openConnection;
+    private readStream;
+    private readFullResponse;
+    private handleEvent;
+    private scheduleReconnect;
+}
+//# sourceMappingURL=ReportedIssueEventSource.d.ts.map

package/lib/typescript/src/support/escalateTool.d.ts

@@ -18,6 +18,11 @@ export interface EscalationToolDeps {
         role: string;
         content: string;
     }>;
+    getToolCalls?: () => Array<{
+        name: string;
+        input: Record<string, unknown>;
+        output: string;
+    }>;
     getScreenFlow?: () => string[];
     onHumanReply?: (reply: string, ticketId?: string) => void;
     onEscalationStarted?: (ticketId: string, socket: EscalationSocket) => void;

package/lib/typescript/src/support/index.d.ts

@@ -1,9 +1,10 @@
 /**
  * Support Mode — barrel export.
  */
-export type { SupportModeConfig, QuickReply, EscalationConfig, EscalationContext, CSATConfig, CSATRating, BusinessHoursConfig, SupportTicket, } from './types';
+export type { SupportModeConfig, QuickReply, EscalationConfig, EscalationContext, CSATConfig, CSATRating, BusinessHoursConfig, SupportTicket, ReportedIssue, ReportedIssueCustomerStatus, ReportedIssueStatusUpdate, } from './types';
 export { buildSupportPrompt } from './supportPrompt';
 export { createEscalateTool } from './escalateTool';
+export { createReportIssueTool } from './reportIssueTool';
 export { EscalationSocket } from './EscalationSocket';
 export type { SocketReplyHandler } from './EscalationSocket';
 export { EscalationEventSource } from './EscalationEventSource';

package/lib/typescript/src/support/reportIssueTool.d.ts

@@ -0,0 +1,20 @@
+import type { ToolDefinition } from '../core/types';
+export interface ReportIssueToolDeps {
+    analyticsKey?: string;
+    getCurrentScreen: () => string;
+    getHistory: () => Array<{
+        role: string;
+        content: string;
+    }>;
+    getScreenFlow?: () => string[];
+    userContext?: {
+        userId?: string;
+        name?: string;
+        email?: string;
+        phone?: string;
+        plan?: string;
+        custom?: Record<string, string | number | boolean>;
+    };
+}
+export declare function createReportIssueTool({ analyticsKey, getCurrentScreen, getHistory, getScreenFlow, userContext, }: ReportIssueToolDeps): ToolDefinition | null;
+//# sourceMappingURL=reportIssueTool.d.ts.map

package/lib/typescript/src/support/types.d.ts

@@ -38,6 +38,31 @@ export interface SupportModeConfig {
      * Example: ['billing dispute', 'account deletion', 'legal']
      */
     autoEscalateTopics?: string[];
+    /**
+     * Options for the AI's persona and tone.
+     */
+    persona?: {
+        /** The agent's name to use in conversation. */
+        agentName?: string;
+        /** The tone of the AI (e.g., 'professional', 'casual', 'empathetic'). Default: 'empathetic' */
+        tone?: string;
+        /** How the AI signs off at the end of a resolution (e.g., 'Best, Support Team') */
+        signOff?: string;
+    };
+    /**
+     * Consumer-defined "WOW actions" — special tools the AI can use to surprise/delight
+     * the user (e.g. apply discount, extend trial) when they've had a frustrating experience.
+     */
+    wowActions?: Array<{
+        /** Internal name for the tool (e.g., 'apply_discount') */
+        name: string;
+        /** What the action does */
+        description: string;
+        /** Instructions specifying exactly when the AI should trigger this action */
+        triggerHint: string;
+        /** Callback when the AI executes this action */
+        handler: (args: Record<string, any>) => Promise<string | void>;
+    }>;
 }
 export interface QuickReply {
     /** Display text on the button */
@@ -78,7 +103,9 @@ export interface EscalationContext {
 export interface CSATConfig {
     /** Enable CSAT survey after conversation. Default: true if support mode enabled */
     enabled?: boolean;
-    /** Question text. Default: "How was your experience?" */
+    /** Which survey to show. 'csat' = Customer Satisfaction, 'ces' = Customer Effort Score. Default: 'csat' */
+    surveyType?: 'csat' | 'ces';
+    /** Question text. Default varies by surveyType ("How was your experience?" or "How easy was it to resolve your issue?") */
     question?: string;
     /** Rating type. Default: 'emoji' */
     ratingType?: 'stars' | 'emoji' | 'thumbs';
@@ -98,6 +125,7 @@ export interface CSATRating {
         stepsCount: number;
         wasEscalated: boolean;
         screen: string;
+        ticketId?: string;
     };
 }
 export interface BusinessHoursConfig {
@@ -126,4 +154,31 @@ export interface SupportTicket {
     /** Number of unread messages (computed by backend = history.length - readMessageCount) */
     unreadCount?: number;
 }
+export type ReportedIssueCustomerStatus = 'acknowledged' | 'investigating' | 'answered' | 'resolved' | 'escalated';
+export interface ReportedIssueStatusUpdate {
+    id: string;
+    status: ReportedIssueCustomerStatus;
+    message: string;
+    source: 'ai' | 'operator' | 'system';
+    timestamp: string;
+}
+export interface ReportedIssue {
+    id: string;
+    issueType: string;
+    complaintSummary: string;
+    verificationStatus: string;
+    severity: string;
+    confidence?: number | null;
+    screen: string;
+    evidenceSummary?: string | null;
+    aiSummary?: string | null;
+    recommendedAction?: string | null;
+    sourceScreens?: string[] | null;
+    screenFlow?: string[] | null;
+    customerStatus: ReportedIssueCustomerStatus;
+    statusHistory: ReportedIssueStatusUpdate[];
+    createdAt: string;
+    updatedAt: string;
+    linkedEscalationTicketId?: string | null;
+}
 //# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/utils/logger.d.ts

@@ -1,8 +1,23 @@
+export interface LogEntry {
+    level: 'info' | 'warn' | 'error' | 'debug';
+    context: string;
+    args: any[];
+    timestamp: number;
+    message: string;
+}
 export declare const logger: {
     /** Enable or disable all SDK logging. */
     setEnabled: (value: boolean) => void;
     /** Check if logging is enabled. */
     isEnabled: () => boolean;
+    /** Return a snapshot of recent SDK log entries. */
+    getEntries: () => LogEntry[];
+    /** Return recent entries as plain text lines, newest last. */
+    getRecentLines: (limit?: number) => string[];
+    /** Extract unflushed entries as plain text and clear the unflushed buffer. */
+    extractUnflushedLines: () => string[];
+    /** Clear the in-memory SDK log history. */
+    clearEntries: () => void;
     info: (context: string, ...args: any[]) => void;
     warn: (context: string, ...args: any[]) => void;
     error: (context: string, ...args: any[]) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobileai/react-native",
-  "version": "0.9.18",
+  "version": "0.9.20",
   "description": "Build autonomous AI agents for React Native and Expo apps. Provides AI-native UI traversal, tool calling, and structured reasoning.",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -21,6 +21,7 @@
   },
   "files": [
     "lib",
+    "src/specs",
     "bin",
     "generate-map.js",
     "android",
@@ -84,7 +85,7 @@
     "url": "git+https://github.com/MobileAIAgent/react-native.git"
   },
   "author": "Mohamed Salah <mohamed2m2018@gmail.com> (https://example.com)",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "bugs": {
     "url": "https://github.com/MobileAIAgent/react-native/issues"
   },
@@ -117,27 +118,33 @@
     "react-native-builder-bob": "^0.40.18",
     "react-test-renderer": "^19.2.0",
     "turbo": "^2.5.6",
-    "typescript": "^5.9.2"
-  },
-  "dependencies": {
+    "typescript": "^5.9.2",
     "@google/genai": "^1.0.0",
     "react-native-audio-api": "*"
   },
   "peerDependencies": {
+    "@google/genai": "*",
     "@react-native-async-storage/async-storage": "*",
     "expo-speech-recognition": "*",
     "react": "*",
     "react-native": "*",
     "react-native-audio-api": "*",
+    "react-native-screens": "*",
     "react-native-view-shot": "*"
   },
   "peerDependenciesMeta": {
+    "@google/genai": {
+      "optional": true
+    },
     "@react-native-async-storage/async-storage": {
       "optional": true
     },
     "react-native-audio-api": {
       "optional": true
     },
+    "react-native-screens": {
+      "optional": true
+    },
     "react-native-view-shot": {
       "optional": true
     },
@@ -145,6 +152,14 @@
       "optional": true
     }
   },
+  "codegenConfig": {
+    "name": "RNMobileAIOverlaySpec",
+    "type": "components",
+    "jsSrcsDir": "src/specs",
+    "android": {
+      "javaPackageName": "com.mobileai.overlay"
+    }
+  },
   "workspaces": [
     "example-react-navigation"
   ],

package/react-native.config.js

@@ -0,0 +1,12 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: './android',
+        packageImportPath: 'import com.mobileai.overlay.MobileAIOverlayPackage;',
+        packageInstance: 'new MobileAIOverlayPackage()',
+      },
+      ios: {},
+    },
+  },
+};

package/src/specs/FloatingOverlayNativeComponent.ts

@@ -0,0 +1,19 @@
+/**
+ * Codegen spec for MobileAIFloatingOverlay native view.
+ *
+ * This file is required by React Native's Codegen (New Architecture / Fabric).
+ * It defines the TypeScript interface for the native view. During the build,
+ * Codegen uses this spec to generate C++ glue code that bridges JS and native.
+ *
+ * Consumers don't use this directly — use FloatingOverlayWrapper.tsx instead.
+ *
+ * Naming convention: file must end in NativeComponent.ts (Codegen convention).
+ */
+
+import type { ViewProps } from 'react-native';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+
+export interface NativeProps extends ViewProps {}
+
+// Codegen reads this export to generate the native component interfaces.
+export default codegenNativeComponent<NativeProps>('MobileAIFloatingOverlay');