@getecho-ai/react-native-sdk 1.0.0

package/README.md

@@ -0,0 +1,350 @@
+# Echo React Native SDK
+
+AI-powered chat and e-commerce SDK for React Native apps. Add an intelligent shopping assistant to your app in minutes.
+
+## Installation
+
+```bash
+npm install @getecho-ai/react-native-sdk react-native-webview @react-native-async-storage/async-storage
+```
+
+**Expo users:**
+
+```bash
+npx expo install @getecho-ai/react-native-sdk react-native-webview @react-native-async-storage/async-storage
+```
+
+## Quick Start (< 5 minutes)
+
+The fastest way to get started - uses the built-in `useSimpleCart` hook for automatic cart management:
+
+```tsx
+import { EchoProvider, EchoChat, useSimpleCart } from '@getecho-ai/react-native-sdk';
+
+function App() {
+  const { cart, callbacks } = useSimpleCart();
+
+  return (
+    <EchoProvider config={{ apiKey: 'your-api-key', callbacks }}>
+      <YourApp cart={cart} />
+      <EchoChat />
+    </EchoProvider>
+  );
+}
+```
+
+That's it! The AI assistant can now add products to cart and show cart contents.
+
+## Production Setup (Custom Cart)
+
+For production apps with existing cart logic:
+
+```tsx
+import { EchoProvider, EchoChat } from '@getecho-ai/react-native-sdk';
+
+function App() {
+  return (
+    <EchoProvider
+      config={{
+        apiKey: 'your-api-key',
+        callbacks: {
+          // Required: Handle add to cart
+          onAddToCart: async (product, quantity = 1) => {
+            await yourCartService.add(product.id, quantity);
+            return {
+              success: true,
+              cartItemCount: yourCartService.getItemCount()
+            };
+          },
+
+          // Required: Return current cart
+          onGetCart: async () => {
+            const cart = await yourCartService.getCart();
+            return {
+              success: true,
+              cart: {
+                items: cart.items.map(item => ({
+                  productId: item.id,
+                  quantity: item.qty,
+                  product: item.product,
+                })),
+                itemCount: cart.totalItems,
+                total: cart.totalPrice,
+                currency: 'TRY',
+              }
+            };
+          },
+
+          // Optional: Navigate to product detail
+          onNavigateToProduct: (productId) => {
+            navigation.navigate('ProductDetail', { id: productId });
+          },
+
+          // Optional: Navigate to checkout
+          onNavigateToCheckout: () => {
+            navigation.navigate('Checkout');
+          },
+        },
+      }}
+    >
+      <YourApp />
+      <EchoChat />
+    </EchoProvider>
+  );
+}
+```
+
+## Local Development
+
+When developing locally with the Echo backend:
+
+```tsx
+<EchoProvider
+  config={{
+    apiKey: 'your-api-key',
+    apiUrl: 'http://localhost:3000', // Auto-converts to 10.0.2.2 on Android emulator
+    callbacks,
+  }}
+>
+```
+
+The SDK automatically handles Android emulator's localhost quirk (converts `localhost` to `10.0.2.2`).
+
+For real devices, use your machine's local IP:
+
+```tsx
+apiUrl: 'http://192.168.1.100:3000'
+```
+
+## Components
+
+### `<EchoProvider>`
+
+Wrap your app with this provider. Required props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `config.apiKey` | `string` | Your Echo API key |
+| `config.callbacks` | `EchoCallbacks` | Cart and navigation callbacks |
+
+Optional props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `config.apiUrl` | `string` | Override API URL (default: production) |
+| `config.userId` | `string` | Pre-set user ID |
+| `config.userEmail` | `string` | User email for personalization |
+| `config.theme` | `EchoTheme` | UI customization |
+| `config.uiSettings` | `UISettings` | Control UI elements visibility |
+
+### `<EchoChat>`
+
+The main chat component with floating button and modal.
+
+```tsx
+<EchoChat
+  floating={true}           // Show floating button (default: true)
+  position="bottom-right"   // Button position (default: "bottom-right")
+/>
+```
+
+### `<EchoChatButton>`
+
+Standalone chat button for custom layouts:
+
+```tsx
+<EchoChatButton
+  onPress={() => setModalVisible(true)}
+  position="bottom-left"
+/>
+```
+
+### `<EchoChatModal>`
+
+Standalone chat modal:
+
+```tsx
+<EchoChatModal
+  visible={isVisible}
+  onClose={() => setIsVisible(false)}
+/>
+```
+
+## Hooks
+
+### `useSimpleCart(options?)`
+
+Built-in cart management for quick prototyping:
+
+```tsx
+const {
+  cart,           // Current cart state
+  setCart,        // Direct cart setter
+  clearCart,      // Clear all items
+  removeItem,     // Remove by productId
+  updateQuantity, // Update item quantity
+  callbacks,      // Ready-to-use EchoCallbacks
+} = useSimpleCart({
+  initialCart: { items: [], itemCount: 0 },
+  onCartChange: (cart) => console.log('Cart updated:', cart),
+  onNavigateToProduct: (id) => navigation.navigate('Product', { id }),
+  onNavigateToCheckout: () => navigation.navigate('Checkout'),
+});
+```
+
+### `useEcho()`
+
+Access Echo context anywhere in your app:
+
+```tsx
+const {
+  config,     // Current config
+  userId,     // Current user ID
+  chatId,     // Current chat ID
+  isReady,    // SDK initialized
+} = useEcho();
+```
+
+## Utilities
+
+### `resolveApiUrl(url?)`
+
+Platform-aware URL resolution for development:
+
+```tsx
+import { resolveApiUrl } from '@getecho-ai/react-native-sdk';
+
+const url = resolveApiUrl('http://localhost:3000');
+// Android emulator: 'http://10.0.2.2:3000'
+// iOS simulator: 'http://localhost:3000'
+// Production URL: unchanged
+```
+
+### `getLocalhostUrl(port?)`
+
+Get the correct localhost URL for current platform:
+
+```tsx
+import { getLocalhostUrl } from '@getecho-ai/react-native-sdk';
+
+const url = getLocalhostUrl(3000);
+// Android: 'http://10.0.2.2:3000'
+// iOS: 'http://localhost:3000'
+```
+
+## UI Settings
+
+Control visibility of UI elements:
+
+```tsx
+<EchoProvider
+  config={{
+    apiKey: 'your-key',
+    callbacks,
+    uiSettings: {
+      showSidebar: false,       // Hide conversation history sidebar
+      showExpandButton: false,  // Hide expand/collapse button
+      showCartButton: true,     // Show cart button in header
+      showHistoryButton: false, // Hide history/new chat button
+      showCloseButton: true,    // Show close button
+    },
+  }}
+>
+```
+
+## Troubleshooting
+
+### "Network request failed" on Android emulator
+
+The SDK should auto-convert localhost URLs. If issues persist:
+
+```tsx
+// Explicitly use 10.0.2.2
+apiUrl: 'http://10.0.2.2:3000'
+```
+
+### WebView not loading
+
+Ensure peer dependencies are installed:
+
+```bash
+npm ls react-native-webview @react-native-async-storage/async-storage
+```
+
+For Expo, run `npx expo install` to get compatible versions.
+
+### Cart not updating
+
+1. Verify `onAddToCart` returns `{ success: true, cartItemCount: N }`
+2. Check `onGetCart` returns valid cart structure
+3. Add console.log in callbacks to debug
+
+### TypeScript errors
+
+Import types explicitly:
+
+```tsx
+import type { Product, Cart, EchoCallbacks } from '@getecho-ai/react-native-sdk';
+```
+
+## API Reference
+
+### Types
+
+```tsx
+type Product = {
+  id: string;
+  title: string;
+  description?: string;
+  priceAmount?: number;
+  currency?: string;
+  primaryImage?: string;
+  images?: string[];
+  url?: string;
+  category?: string;
+  brand?: string;
+  inStock?: boolean;
+};
+
+type Cart = {
+  items: CartItem[];
+  total?: number;
+  currency?: string;
+  itemCount: number;
+};
+
+type CartItem = {
+  productId: string;
+  quantity: number;
+  product?: Product;
+};
+
+type AddToCartResult = {
+  success: boolean;
+  cartItemCount?: number;
+  error?: string;
+};
+
+type GetCartResult = {
+  success: boolean;
+  cart?: Cart;
+  error?: string;
+};
+
+type EchoCallbacks = {
+  onAddToCart: (product: Product, quantity?: number) => Promise<AddToCartResult>;
+  onGetCart: () => Promise<GetCartResult>;
+  onNavigateToProduct?: (productId: string) => void;
+  onNavigateToUrl?: (url: string) => void;
+  onNavigateToCheckout?: () => void;
+  onAuthRequired?: () => void;
+};
+```
+
+## Example App
+
+See the `/example` directory for a complete Expo demo app.
+
+## License
+
+MIT

package/dist/bridge/CallbackManager.d.ts

@@ -0,0 +1,46 @@
+/**
+ * CallbackManager - Handles async actions between WebView and Native
+ *
+ * This implements the manual completion pattern where:
+ * 1. Action is initiated with a callbackId
+ * 2. Partner app completes the action (e.g., user logs in, adds to cart)
+ * 3. Partner calls completeAction(callbackId, result)
+ *
+ * Includes 30 second timeout to prevent indefinite hangs
+ */
+import type { CallbackResult } from "../types";
+declare class CallbackManager {
+    private readonly pendingCallbacks;
+    /**
+     * Initiate a new action and return a promise that resolves when
+     * the partner app completes the action via completeAction()
+     * Automatically times out after 30 seconds
+     */
+    initiateAction(callbackId: string): Promise<CallbackResult>;
+    /**
+     * Complete an action with the result from partner app
+     * This resolves the pending promise and clears the timeout
+     */
+    completeAction(callbackId: string, result: CallbackResult): boolean;
+    /**
+     * Cancel a pending action (e.g., user closes chat)
+     * Clears the timeout as well
+     */
+    cancelAction(callbackId: string, reason?: string): boolean;
+    /**
+     * Check if an action is still pending
+     */
+    isPending(callbackId: string): boolean;
+    /**
+     * Get all pending callback IDs (useful for debugging)
+     */
+    getPendingIds(): string[];
+    /**
+     * Cancel all pending actions (e.g., on unmount)
+     * Clears all timeouts as well
+     */
+    cancelAll(reason?: string): void;
+}
+export declare const callbackManager: CallbackManager;
+export { CallbackManager };
+export default callbackManager;

package/dist/bridge/CallbackManager.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * CallbackManager - Handles async actions between WebView and Native
+ *
+ * This implements the manual completion pattern where:
+ * 1. Action is initiated with a callbackId
+ * 2. Partner app completes the action (e.g., user logs in, adds to cart)
+ * 3. Partner calls completeAction(callbackId, result)
+ *
+ * Includes 30 second timeout to prevent indefinite hangs
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallbackManager = exports.callbackManager = void 0;
+const CALLBACK_TIMEOUT_MS = 30000; // 30 seconds
+class CallbackManager {
+    constructor() {
+        this.pendingCallbacks = new Map();
+    }
+    /**
+     * Initiate a new action and return a promise that resolves when
+     * the partner app completes the action via completeAction()
+     * Automatically times out after 30 seconds
+     */
+    initiateAction(callbackId) {
+        return new Promise((resolve) => {
+            const timeoutId = setTimeout(() => {
+                const pending = this.pendingCallbacks.get(callbackId);
+                if (pending) {
+                    console.warn(`[EchoSDK] Callback timeout: ${callbackId}`);
+                    resolve({ success: false, error: "CALLBACK_TIMEOUT" });
+                    this.pendingCallbacks.delete(callbackId);
+                }
+            }, CALLBACK_TIMEOUT_MS);
+            this.pendingCallbacks.set(callbackId, {
+                resolve,
+                createdAt: Date.now(),
+                timeoutId,
+            });
+            console.log(`[EchoSDK] Action initiated: ${callbackId}`);
+        });
+    }
+    /**
+     * Complete an action with the result from partner app
+     * This resolves the pending promise and clears the timeout
+     */
+    completeAction(callbackId, result) {
+        const pending = this.pendingCallbacks.get(callbackId);
+        if (!pending) {
+            console.warn(`[EchoSDK] No pending callback found for: ${callbackId}`);
+            return false;
+        }
+        // Clear timeout
+        if (pending.timeoutId) {
+            clearTimeout(pending.timeoutId);
+        }
+        console.log(`[EchoSDK] Action completed: ${callbackId}`, result);
+        pending.resolve(result);
+        this.pendingCallbacks.delete(callbackId);
+        return true;
+    }
+    /**
+     * Cancel a pending action (e.g., user closes chat)
+     * Clears the timeout as well
+     */
+    cancelAction(callbackId, reason) {
+        const pending = this.pendingCallbacks.get(callbackId);
+        if (!pending) {
+            return false;
+        }
+        // Clear timeout
+        if (pending.timeoutId) {
+            clearTimeout(pending.timeoutId);
+        }
+        console.log(`[EchoSDK] Action cancelled: ${callbackId}`, reason);
+        pending.resolve({
+            success: false,
+            error: reason || "ACTION_CANCELLED",
+        });
+        this.pendingCallbacks.delete(callbackId);
+        return true;
+    }
+    /**
+     * Check if an action is still pending
+     */
+    isPending(callbackId) {
+        return this.pendingCallbacks.has(callbackId);
+    }
+    /**
+     * Get all pending callback IDs (useful for debugging)
+     */
+    getPendingIds() {
+        return Array.from(this.pendingCallbacks.keys());
+    }
+    /**
+     * Cancel all pending actions (e.g., on unmount)
+     * Clears all timeouts as well
+     */
+    cancelAll(reason) {
+        const message = reason || "ALL_ACTIONS_CANCELLED";
+        this.pendingCallbacks.forEach((pending, callbackId) => {
+            // Clear timeout
+            if (pending.timeoutId) {
+                clearTimeout(pending.timeoutId);
+            }
+            pending.resolve({
+                success: false,
+                error: message,
+            });
+            console.log(`[EchoSDK] Action cancelled: ${callbackId}`);
+        });
+        this.pendingCallbacks.clear();
+    }
+}
+exports.CallbackManager = CallbackManager;
+// Export singleton instance
+exports.callbackManager = new CallbackManager();
+exports.default = exports.callbackManager;

package/dist/bridge/WebViewBridge.d.ts

@@ -0,0 +1,67 @@
+/**
+ * WebViewBridge - Handles communication between WebView and React Native
+ *
+ * Uses postMessage API for bidirectional communication:
+ * - WebView → Native: window.ReactNativeWebView.postMessage()
+ * - Native → WebView: webViewRef.injectJavaScript()
+ */
+import type { BridgeMessage, BridgeMessageType } from "../types";
+export type MessageHandler = (message: BridgeMessage) => void;
+declare class WebViewBridge {
+    private readonly messageHandlers;
+    private webViewRef;
+    /**
+     * Set the WebView reference for sending messages to WebView
+     */
+    setWebViewRef(ref: any): void;
+    /**
+     * Register a message handler
+     */
+    onMessage(handler: MessageHandler): () => void;
+    /**
+     * Handle incoming message from WebView
+     * This is called by the WebView's onMessage prop
+     */
+    handleMessage(event: {
+        nativeEvent: {
+            data: string;
+        };
+    }): void;
+    /**
+     * Send message to WebView
+     */
+    sendToWebView(type: BridgeMessageType, payload?: any, callbackId?: string): void;
+    /**
+     * Send a raw message to WebView without wrapping payload
+     * Used when the web embed expects root-level fields.
+     */
+    sendRawToWebView(message: any): void;
+    /**
+     * Initialize WebView with config
+     */
+    initWebView(config: {
+        apiKey: string;
+        userId?: string;
+        userEmail?: string;
+        theme?: any;
+    }): void;
+    /**
+     * Complete an action in WebView
+     */
+    completeActionInWebView(callbackId: string, result: {
+        success: boolean;
+        data?: any;
+        error?: string;
+    }): void;
+    /**
+     * Handle internal messages (action completion, etc.)
+     */
+    private handleInternalMessage;
+    /**
+     * Clear all handlers (useful on unmount)
+     */
+    clearHandlers(): void;
+}
+export declare const webViewBridge: WebViewBridge;
+export { WebViewBridge };
+export default webViewBridge;