@mobileai/react-native 0.9.0 → 0.9.2

package/src/support/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Support Mode — barrel export.
+ */
+
+// Types
+export type {
+  SupportModeConfig,
+  QuickReply,
+  EscalationConfig,
+  EscalationContext,
+  CSATConfig,
+  CSATRating,
+  BusinessHoursConfig,
+} from './types';
+
+// Prompt injection
+export { buildSupportPrompt } from './supportPrompt';
+
+// Escalation tool + WebSocket manager
+export { createEscalateTool } from './escalateTool';
+export { EscalationSocket } from './EscalationSocket';
+export type { SocketReplyHandler } from './EscalationSocket';
+
+// UI Components
+export { SupportGreeting } from './SupportGreeting';
+export { CSATSurvey } from './CSATSurvey';
+

package/src/support/supportPrompt.ts

@@ -0,0 +1,55 @@
+/**
+ * Support Mode prompt — injected into the system prompt when support mode is enabled.
+ *
+ * Uses POSITIVE framing (what TO DO) instead of negative rules (per user's prompt engineering rules).
+ */
+
+import type { SupportModeConfig } from './types';
+
+/**
+ * Build the support mode system prompt addition.
+ * This gets appended to the main system prompt when support mode is active.
+ */
+export function buildSupportPrompt(config: SupportModeConfig): string {
+  const parts: string[] = [];
+
+  // Core support persona
+  parts.push(`
+## Support Mode Active
+
+You are a helpful customer support assistant. Your primary goal is to resolve the user's issue quickly and empathetically.
+
+### Behavior Guidelines
+- Greet the user warmly and acknowledge their issue
+- Ask clarifying questions when the user's request is ambiguous
+- Provide step-by-step guidance when helping with app features
+- Use the app's UI tools to demonstrate solutions visually (tap, navigate, type)
+- After resolving, confirm with the user that their issue is fixed
+- Stay focused on the user's current issue — complete one task before moving to another
+`);
+
+  // Custom system context from the consumer
+  if (config.systemContext) {
+    parts.push(`### App Context\n${config.systemContext}\n`);
+  }
+
+  // Auto-escalate topics
+  if (config.autoEscalateTopics?.length) {
+    parts.push(
+      `### Auto-Escalation Topics\n` +
+      `When the user's query matches any of these topics, use the escalate_to_human tool immediately:\n` +
+      config.autoEscalateTopics.map((t) => `- ${t}`).join('\n') + '\n'
+    );
+  }
+
+  // Business hours context
+  if (config.businessHours) {
+    parts.push(
+      `### Business Hours\n` +
+      `The support team operates in timezone: ${config.businessHours.timezone}.\n` +
+      `If outside business hours, inform the user and offer to help with what you can.\n`
+    );
+  }
+
+  return parts.join('\n');
+}

package/src/support/types.ts

@@ -0,0 +1,141 @@
+/**
+ * Support Mode — types and configuration.
+ *
+ * Transforms the AI agent into a customer support assistant with:
+ * - Custom greeting message
+ * - Quick reply suggestions
+ * - Human escalation capability
+ * - CSAT (Customer Satisfaction) collection after conversation
+ */
+
+// ─── Support Mode Config ──────────────────────────────────
+
+export interface SupportModeConfig {
+  /** Enable support mode. Default: false */
+  enabled: boolean;
+
+  /** Greeting message shown when the chat opens */
+  greeting?: {
+    /** Main greeting text (e.g., "Hi! 👋 How can I help you today?") */
+    message: string;
+    /** Agent name shown above the greeting (e.g., "MobileAI Support") */
+    agentName?: string;
+    /** Avatar URL for the support agent */
+    avatarUrl?: string;
+  };
+
+  /** Quick reply buttons shown below the greeting */
+  quickReplies?: QuickReply[];
+
+  /** Escalation configuration */
+  escalation?: EscalationConfig;
+
+  /** CSAT survey configuration */
+  csat?: CSATConfig;
+
+  /** Business hours (optional — shows offline message outside hours) */
+  businessHours?: BusinessHoursConfig;
+
+  /**
+   * Additional system prompt context for the support persona.
+   * Merged with the base system prompt.
+   * Example: "You are a friendly support agent for FeedYum food delivery app."
+   */
+  systemContext?: string;
+
+  /**
+   * Topics the AI should NOT attempt to resolve — escalate immediately.
+   * Example: ['billing dispute', 'account deletion', 'legal']
+   */
+  autoEscalateTopics?: string[];
+}
+
+// ─── Quick Replies ────────────────────────────────────────
+
+export interface QuickReply {
+  /** Display text on the button */
+  label: string;
+  /** Message sent when tapped (defaults to label if not set) */
+  message?: string;
+  /** Icon emoji (optional) */
+  icon?: string;
+}
+
+// ─── Escalation ───────────────────────────────────────────
+
+export interface EscalationConfig {
+  /**
+   * Where to route the escalation.
+   * - 'mobileai' (default when analyticsKey is set): ticket goes to MobileAI
+   *   dashboard inbox via POST /api/v1/escalations + WebSocket reply delivery.
+   * - 'custom': fires the onEscalate callback — wire to Intercom, Zendesk, etc.
+   */
+  provider?: 'mobileai' | 'custom';
+
+  /**
+   * Callback when user requests human support (required when provider='custom').
+   * Use this to open a live chat widget, send email, etc.
+   */
+  onEscalate?: (context: EscalationContext) => void;
+
+  /** Label for the escalate button. Default: "Talk to a human" */
+  buttonLabel?: string;
+
+  /** Message shown to user when escalated. Default: "Connecting you to a human agent..." */
+  escalationMessage?: string;
+}
+
+export interface EscalationContext {
+  /** Summary of the conversation so far */
+  conversationSummary: string;
+  /** Current screen the user is on */
+  currentScreen: string;
+  /** User's original question/issue */
+  originalQuery: string;
+  /** Number of AI steps taken before escalation */
+  stepsBeforeEscalation: number;
+}
+
+// ─── CSAT (Customer Satisfaction) ─────────────────────────
+
+export interface CSATConfig {
+  /** Enable CSAT survey after conversation. Default: true if support mode enabled */
+  enabled?: boolean;
+
+  /** Question text. Default: "How was your experience?" */
+  question?: string;
+
+  /** Rating type. Default: 'emoji' */
+  ratingType?: 'stars' | 'emoji' | 'thumbs';
+
+  /** Callback when user submits rating */
+  onSubmit: (rating: CSATRating) => void;
+
+  /** Show after N seconds of inactivity. Default: 10 */
+  showAfterIdleSeconds?: number;
+}
+
+export interface CSATRating {
+  /** Numeric score (1-5 for stars/emoji, 0-1 for thumbs) */
+  score: number;
+  /** Optional text feedback */
+  feedback?: string;
+  /** Conversation metadata */
+  metadata: {
+    conversationDuration: number;
+    stepsCount: number;
+    wasEscalated: boolean;
+    screen: string;
+  };
+}
+
+// ─── Business Hours ───────────────────────────────────────
+
+export interface BusinessHoursConfig {
+  /** Timezone (IANA format, e.g., 'Africa/Cairo') */
+  timezone: string;
+  /** Schedule per day of week (0=Sunday, 6=Saturday) */
+  schedule: Record<number, { start: string; end: string } | null>;
+  /** Message shown outside business hours */
+  offlineMessage?: string;
+}

package/src/tools/guideTool.ts

@@ -0,0 +1,67 @@
+import { DeviceEventEmitter } from 'react-native';
+import type { ToolDefinition } from '../core/types';
+import type { ToolContext } from './types';
+import { logger } from '../utils/logger';
+
+export function createGuideTool(context: ToolContext): ToolDefinition {
+  return {
+    name: 'guide_user',
+    description: 'Highlight a specific element to draw the user\'s attention. Use when you want to show the user where to tap next. Auto-dismisses after a few seconds.',
+    parameters: {
+      index: { 
+        type: 'number', 
+        description: 'Fiber element index from the screen layout',
+        required: true,
+      },
+      message: { 
+        type: 'string', 
+        description: 'Short instruction shown near the highlighted element (e.g. "Tap here to continue")',
+        required: true,
+      },
+      autoRemoveAfterMs: { 
+        type: 'number', 
+        description: 'Auto-dismiss after this many milliseconds. Default: 5000',
+        required: false,
+      }
+    },
+    execute: async (args: Record<string, any>) => {
+      const lastDehydratedRoot = context.getLastDehydratedRoot?.();
+      if (!lastDehydratedRoot) {
+        return '❌ Cannot guide user: No screen layout structure available.';
+      }
+
+      const index = Number(args.index);
+      const element = lastDehydratedRoot.elements[index];
+
+      if (!element) {
+        return `❌ Element at index ${index} not found on current screen.`;
+      }
+
+      const stateNode = element.fiberNode?.stateNode;
+      if (!stateNode || typeof stateNode.measure !== 'function') {
+        return `❌ Element at index ${index} (${element.label}) cannot be highlighted because its layout position cannot be measured.`;
+      }
+
+      return new Promise((resolve) => {
+        stateNode.measure((_x: number, _y: number, width: number, height: number, pageX: number, pageY: number) => {
+          if (width === 0 || height === 0) {
+            resolve(`❌ Element at index ${index} is not visible (0x0 size)`);
+            return;
+          }
+
+          DeviceEventEmitter.emit('MOBILE_AI_HIGHLIGHT', {
+            pageX,
+            pageY,
+            width,
+            height,
+            message: args.message,
+            autoRemoveAfterMs: args.autoRemoveAfterMs || 5000,
+          });
+
+          logger.info('GuideTool', `Highlighted element ${index} ("${element.label}") at ${pageX},${pageY}`);
+          resolve(`✅ Highlighted element ${index} ("${element.label}") with message: "${args.message}"`);
+        });
+      });
+    },
+  };
+}

package/src/tools/index.ts

@@ -13,5 +13,8 @@ export { createSliderTool } from './sliderTool';
 export { createPickerTool } from './pickerTool';
 export { createDatePickerTool } from './datePickerTool';
 export { createKeyboardTool } from './keyboardTool';
+export { createGuideTool } from './guideTool';
+export { createSimplifyTool } from './simplifyTool';
+export { createRestoreTool } from './restoreTool';
 
 export type { AgentTool, ToolContext, ToolParameter } from './types';

package/src/tools/restoreTool.ts

@@ -0,0 +1,33 @@
+import type { ToolDefinition } from '../core/types';
+import { globalZoneRegistry } from '../core/ZoneRegistry';
+import { logger } from '../utils/logger';
+
+export function createRestoreTool(): ToolDefinition {
+  return {
+    name: 'restore_zone',
+    description: 'Restore a specific Zone to its default state, reversing any previous simplify_zone or inject_card operations.',
+    parameters: {
+      zoneId: { 
+        type: 'string', 
+        description: 'The ID of the AIZone to restore',
+        required: true,
+      }
+    },
+    execute: async (args) => {
+      const zoneId = String(args.zoneId);
+
+      const zone = globalZoneRegistry.get(zoneId) as any;
+      if (!zone) {
+        return `❌ Cannot restore zone "${zoneId}": Zone does not exist.`;
+      }
+
+      if (zone._controller) {
+        zone._controller.restore();
+        logger.info('RestoreTool', `Restored zone: ${zoneId}`);
+        return `✅ Successfully restored zone "${zoneId}" to its default state.`;
+      }
+
+      return `❌ Cannot restore zone "${zoneId}": Controller not attached.`;
+    },
+  };
+}

package/src/tools/simplifyTool.ts

@@ -0,0 +1,33 @@
+import type { ToolDefinition } from '../core/types';
+import { globalZoneRegistry } from '../core/ZoneRegistry';
+import { logger } from '../utils/logger';
+
+export function createSimplifyTool(): ToolDefinition {
+  return {
+    name: 'simplify_zone',
+    description: 'Simplify the UI in a specific Zone by telling it to hide elements marked as aiPriority="low". Use this when a screen zone looks cluttered and you want to reduce cognitive load for the user.',
+    parameters: {
+      zoneId: { 
+        type: 'string', 
+        description: 'The ID of the AIZone you want to simplify (e.g. from the screen layout context)',
+        required: true,
+      }
+    },
+    execute: async (args) => {
+      const zoneId = String(args.zoneId);
+
+      if (!globalZoneRegistry.isActionAllowed(zoneId, 'simplify')) {
+        return `❌ Cannot simplify zone "${zoneId}": Zone does not exist or allowSimplify is false.`;
+      }
+
+      const zone = globalZoneRegistry.get(zoneId) as any;
+      if (zone && zone._controller) {
+        zone._controller.simplify();
+        logger.info('SimplifyTool', `Simplified zone: ${zoneId}`);
+        return `✅ Successfully requested simplification for zone "${zoneId}".`;
+      }
+
+      return `❌ Cannot simplify zone "${zoneId}": Controller not attached. Is the zone currently rendered on screen?`;
+    },
+  };
+}

package/src/tools/types.ts

@@ -53,4 +53,6 @@ export interface ToolContext {
   buildNestedParams?: (path: string[], params?: any) => any;
   /** Capture screenshot (optional) */
   captureScreenshot?: () => Promise<string | null>;
+  /** Get the most recently dehydrated screen (with layout coords) */
+  getLastDehydratedRoot?: () => any;
 }

package/src/types/jsx.d.ts

@@ -0,0 +1,20 @@
+import 'react-native';
+
+declare module 'react-native' {
+  // Augment core component props to support declarative AI priorities
+  interface ViewProps {
+    aiPriority?: 'high' | 'low';
+  }
+  interface TextProps {
+    aiPriority?: 'high' | 'low';
+  }
+  interface PressableProps {
+    aiPriority?: 'high' | 'low';
+  }
+  interface TextInputProps {
+    aiPriority?: 'high' | 'low';
+  }
+  interface ImageProps {
+    aiPriority?: 'high' | 'low';
+  }
+}