@oobit/react-native-sdk 1.0.7 → 2.0.0

package/README.md

@@ -18,9 +18,9 @@ yarn add @oobit/react-native-sdk
 Make sure you have these installed:
 
 ```bash
-npm install react-native-webview expo-linking
+npm install react-native-webview expo-linking expo-clipboard expo-intent-launcher expo-local-authentication
 # or
-yarn add react-native-webview expo-linking
+yarn add react-native-webview expo-linking expo-clipboard expo-intent-launcher expo-local-authentication
 ```
 
 ## Quick Start
@@ -30,28 +30,23 @@ import { WidgetSDK } from '@oobit/react-native-sdk';
 import { View, Alert } from 'react-native';
 
 function MyApp() {
-  const widgetUrl = 'https://your-widget.com?token=xyz'; // Your authenticated widget URL
-
   return (
     <View style={{ flex: 1 }}>
       <WidgetSDK
-        apiKey="your-api-key"
+        accessToken="your-jwt-token-from-backend"
+        userWalletAddress="0x1234...abcd"
         environment="production"
-        widgetUrl={widgetUrl}
         onReady={() => {
           console.log('Widget loaded successfully');
         }}
-        onCardCreated={(cardId, cardType, last4) => {
-          Alert.alert('Success', `Card ${last4} created!`);
-          // Save card info, navigate to card details, etc.
-        }}
         onError={(code, message) => {
           Alert.alert('Error', message);
-          // Log to error tracking, show user-friendly message, etc.
         }}
         onClose={() => {
           console.log('User closed the widget');
-          // Navigate back, clean up state, etc.
+        }}
+        onTransactionRequested={(token, amount, address, tag) => {
+          console.log(`Send ${amount} ${token.symbol} to ${address}`);
         }}
       />
     </View>
@@ -63,105 +58,72 @@ function MyApp() {
 
 ### Required Props
 
-#### `apiKey: string`
-Your API key for authentication.
+#### `accessToken: string`
+JWT access token from your backend for authentication.
 
 ```typescript
-<WidgetSDK apiKey="your-api-key" />
+<WidgetSDK accessToken="eyJhbGciOiJIUzI1NiIs..." />
 ```
 
-#### `environment: 'sandbox' | 'production'`
-The environment to use.
+#### `userWalletAddress: string`
+The user's external wallet address for crypto deposits.
 
 ```typescript
-<WidgetSDK environment="production" />
+<WidgetSDK userWalletAddress="0x1234567890abcdef..." />
 ```
 
-#### `widgetUrl: string`
-The URL of your widget (typically includes a JWT token for authentication).
+### Optional Props
+
+#### `environment?: 'development' | 'production'`
+The environment to use. Defaults to `'production'`.
 
 ```typescript
-<WidgetSDK widgetUrl="https://widget.yourapp.com?token=jwt_token_here" />
+<WidgetSDK environment="development" />
 ```
 
-### Optional Callback Props
+#### `debug?: boolean`
+Enable debug logging to console. Defaults to `false`.
 
-#### `onReady?: () => void`
-Called when the widget has finished loading and is ready for interaction.
+```typescript
+<WidgetSDK debug={true} />
+```
 
-**Use this to:**
-- Hide loading indicators
-- Track analytics events
-- Initialize app state
+#### `loadingIndicatorColor?: string`
+Custom color for the loading indicator. Defaults to `'#007AFF'`.
 
 ```typescript
-<WidgetSDK
-  onReady={() => {
-    console.log('Widget is ready!');
-    analytics.track('widget_loaded');
-  }}
-/>
+<WidgetSDK loadingIndicatorColor="#6200EE" />
 ```
 
-#### `onCardCreated?: (cardId: string, cardType: string, last4: string) => void`
-Called when a card is successfully created in the widget.
+### Callback Props
 
-**Parameters:**
-- `cardId` - Unique identifier for the created card
-- `cardType` - Type of card: `'virtual'` or `'physical'`
-- `last4` - Last 4 digits of the card number
-
-**Use this to:**
-- Save card info to your app's state
-- Navigate to card details screen
-- Show success message to user
-- Trigger analytics events
-- Close the widget
+#### `onReady?: () => void`
+Called when the widget has finished loading and is ready for interaction.
 
 ```typescript
 <WidgetSDK
-  onCardCreated={(cardId, cardType, last4) => {
-    console.log(`Card created: ${cardId}, type: ${cardType}, ending in ${last4}`);
-
-    // Save to state
-    setUserCard({ id: cardId, type: cardType, last4 });
-
-    // Navigate to card details
-    navigation.navigate('CardDetails', { cardId });
-
-    // Track analytics
-    analytics.track('card_created', { cardType });
+  onReady={() => {
+    console.log('Widget is ready!');
+    setIsLoading(false);
   }}
 />
 ```
 
-#### `onError?: (code: string, message: string) => void`
+#### `onError?: (code: SDKErrorCode | string, message: string) => void`
 Called when an error occurs in the widget.
 
-**Parameters:**
-- `code` - Error code (e.g., `'INVALID_CARD'`, `'NETWORK_ERROR'`)
-- `message` - Human-readable error message
-
-**Use this to:**
-- Show error alerts to user
-- Log errors to monitoring service
-- Handle specific error cases
-- Retry operations
+**Error Codes:**
+- `TOKEN_EXPIRED` - The access token has expired
+- `PARSE_ERROR` - Failed to parse a message from the widget
+- `WEBVIEW_ERROR` - The WebView failed to load
 
 ```typescript
 <WidgetSDK
   onError={(code, message) => {
     console.error(`Widget error [${code}]: ${message}`);
 
-    // Show user-friendly error
-    Alert.alert('Error', message);
-
-    // Log to error tracking
-    Sentry.captureException(new Error(`Widget error: ${code} - ${message}`));
-
-    // Handle specific errors
-    if (code === 'SESSION_EXPIRED') {
-      // Refresh authentication and reload widget
+    if (code === 'TOKEN_EXPIRED') {
+      // Refresh token and reload
       refreshAuth();
     }
   }}
@@ -169,135 +131,92 @@ Called when an error occurs in the widget.
 ```
 
 #### `onClose?: () => void`
-Called when the user requests to close the widget (via a close button in the widget).
-
-**Use this to:**
-- Navigate back to previous screen
-- Clean up state
-- Track analytics events
-- Hide the widget
+Called when the user requests to close the widget.
 
 ```typescript
 <WidgetSDK
   onClose={() => {
-    console.log('User closed widget');
-
-    // Navigate back
     navigation.goBack();
+  }}
+/>
+```
 
-    // Or hide widget
-    setShowWidget(false);
+#### `onTransactionRequested?: (token, cryptoAmount, depositAddress, depositAddressTag) => void`
+Called when a crypto transaction is requested.
 
-    // Track analytics
-    analytics.track('widget_closed');
+```typescript
+<WidgetSDK
+  onTransactionRequested={(token, cryptoAmount, depositAddress, depositAddressTag) => {
+    console.log(`Send ${cryptoAmount} ${token.symbol} to ${depositAddress}`);
+    // Navigate to your send crypto screen
+    navigation.navigate('SendCrypto', {
+      token,
+      amount: cryptoAmount,
+      address: depositAddress,
+      tag: depositAddressTag,
+    });
   }}
 />
 ```
 
-## Complete Example
+#### `onLoadingChange?: (isLoading: boolean) => void`
+Called when the loading state changes.
 
 ```typescript
-import React, { useState } from 'react';
-import { View, Button, StyleSheet, Alert, ActivityIndicator } from 'react-native';
-import { WidgetSDK } from '@oobit/react-native-sdk';
+<WidgetSDK
+  onLoadingChange={(isLoading) => {
+    setShowCustomLoader(isLoading);
+  }}
+/>
+```
 
-export default function CardIssuanceScreen() {
-  const [showWidget, setShowWidget] = useState(false);
-  const [widgetUrl, setWidgetUrl] = useState('');
-  const [isLoading, setIsLoading] = useState(false);
-
-  const launchWidget = async () => {
-    try {
-      setIsLoading(true);
-
-      // Get authenticated widget URL from your backend
-      const response = await fetch('https://your-api.com/widget/token', {
-        method: 'POST',
-        headers: { 'Authorization': 'Bearer your-token' }
-      });
-      const { url } = await response.json();
-
-      setWidgetUrl(url);
-      setShowWidget(true);
-    } catch (error) {
-      Alert.alert('Error', 'Failed to load widget');
-    } finally {
-      setIsLoading(false);
-    }
+## Ref Methods
+
+You can control the widget programmatically using a ref:
+
+```typescript
+import { useRef } from 'react';
+import { WidgetSDK, WidgetSDKRef } from '@oobit/react-native-sdk';
+
+function MyScreen() {
+  const widgetRef = useRef<WidgetSDKRef>(null);
+
+  const handleBackPress = () => {
+    widgetRef.current?.navigateBack();
   };
 
-  if (showWidget && widgetUrl) {
-    return (
-      <View style={styles.container}>
-        <WidgetSDK
-          apiKey="your-api-key"
-          environment="production"
-          widgetUrl={widgetUrl}
-          onReady={() => {
-            console.log('Widget ready');
-          }}
-          onCardCreated={(cardId, cardType, last4) => {
-            Alert.alert(
-              'Card Created!',
-              `Your ${cardType} card ending in ${last4} is ready.`,
-              [
-                {
-                  text: 'View Card',
-                  onPress: () => {
-                    setShowWidget(false);
-                    // Navigate to card details
-                  }
-                }
-              ]
-            );
-          }}
-          onError={(code, message) => {
-            Alert.alert('Error', message);
-          }}
-          onClose={() => {
-            setShowWidget(false);
-          }}
-        />
-      </View>
-    );
-  }
+  const handleRetry = () => {
+    widgetRef.current?.reload();
+  };
 
   return (
-    <View style={styles.container}>
-      <Button
-        title={isLoading ? 'Loading...' : 'Create Card'}
-        onPress={launchWidget}
-        disabled={isLoading}
-      />
-      {isLoading && <ActivityIndicator style={{ marginTop: 20 }} />}
-    </View>
+    <WidgetSDK
+      ref={widgetRef}
+      accessToken={token}
+      userWalletAddress={address}
+    />
   );
 }
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    justifyContent: 'center',
-    padding: 20,
-  },
-});
 ```
 
+### Available Methods
+
+| Method | Description |
+|--------|-------------|
+| `navigateBack()` | Navigate back within the widget |
+| `reload()` | Reload the widget |
+
 ## TypeScript Support
 
 The SDK is fully typed. Import types as needed:
 
 ```typescript
-import type { WidgetSDKConfig } from '@oobit/react-native-sdk';
-
-const config: WidgetSDKConfig = {
-  apiKey: 'your-key',
-  environment: 'production',
-  widgetUrl: 'https://...',
-  onCardCreated: (cardId, cardType, last4) => {
-    // Fully typed parameters
-  },
-};
+import type {
+  WidgetSDKConfig,
+  WidgetSDKRef,
+  SDKErrorCode,
+  DepositToken,
+} from '@oobit/react-native-sdk';
 ```
 
 ### Message Type Constants
@@ -308,49 +227,14 @@ For advanced use cases where you need to handle messages directly:
 import { MessageTypes } from '@oobit/react-native-sdk';
 
 // Use constants instead of strings
-if (message.type === MessageTypes.CARD_CREATED) {
-  // Handle card creation
+if (message.type === MessageTypes.ERROR) {
+  // Handle error
 }
 ```
 
-Available constants:
-
-**Widget → Native:**
-- `MessageTypes.READY` - Widget is ready
-- `MessageTypes.CARD_CREATED` - Card was created
-- `MessageTypes.ERROR` - An error occurred
-- `MessageTypes.CLOSE` - User closed widget
-- `MessageTypes.OPEN_WALLET` - User wants to add card to wallet
-
-**Native → Widget:**
-- `MessageTypes.PLATFORM_INFO` - Platform info sent to widget
-- `MessageTypes.WALLET_OPENED` - Wallet open result
-- `MessageTypes.BACK_PRESSED` - User pressed back button/gesture
-- `MessageTypes.NAVIGATE_BACK` - Programmatic back navigation
-
-## Platform Support
-
-| Platform | Supported | Notes |
-|----------|-----------|-------|
-| iOS | ✅ | Includes Apple Wallet integration |
-| Android | ✅ | Includes Google Pay integration |
-| Web | ❌ | React Native only |
-
 ## Native Wallet Integration
 
-The SDK automatically handles adding cards to Apple Wallet (iOS) and Google Pay (Android) when requested by your widget.
-
-**Your widget can trigger wallet addition:**
-```javascript
-// In your web widget
-window.ReactNativeWebView.postMessage(JSON.stringify({
-  type: 'widget:open-wallet',
-  timestamp: Date.now(),
-  payload: { platform: 'ios' } // or 'android'
-}));
-```
-
-**The SDK handles it automatically** - no callback needed from your app!
+The SDK automatically handles adding cards to Apple Wallet (iOS) and Google Pay (Android).
 
 You can also manually open the wallet from your React Native app:
 
@@ -366,84 +250,81 @@ if (available) {
 }
 ```
 
-## Back Navigation
-
-The SDK handles back navigation gestures and forwards them to your web widget, allowing the widget to control its own internal navigation.
-
-### How It Works
-
-1. **Android**: Hardware back button press is intercepted and forwarded to the widget
-2. **iOS**: Swipe-back gestures are enabled via `allowsBackForwardNavigationGestures`
-
-The widget receives a `native:back-pressed` message and decides whether to:
-- Navigate back internally (if there's navigation history)
-- Close the widget (if on the first screen)
+## Platform Support
 
-### Programmatic Back Navigation
+| Platform | Supported | Notes |
+|----------|-----------|-------|
+| iOS | ✅ | Includes Apple Wallet integration |
+| Android | ✅ | Includes Google Pay integration |
+| Web | ❌ | React Native only |
 
-You can programmatically trigger back navigation using a ref:
+## Complete Example
 
 ```typescript
-import { useRef } from 'react';
+import React, { useState, useRef } from 'react';
+import { View, Button, StyleSheet, Alert } from 'react-native';
 import { WidgetSDK, WidgetSDKRef } from '@oobit/react-native-sdk';
 
-function MyScreen() {
+export default function PaymentScreen() {
+  const [showWidget, setShowWidget] = useState(false);
   const widgetRef = useRef<WidgetSDKRef>(null);
 
-  const handleTimeout = () => {
-    // Programmatically navigate widget back
-    widgetRef.current?.navigateBack();
-  };
+  if (showWidget) {
+    return (
+      <View style={styles.container}>
+        <WidgetSDK
+          ref={widgetRef}
+          accessToken="your-jwt-token"
+          userWalletAddress="0x1234..."
+          environment="production"
+          debug={__DEV__}
+          onReady={() => {
+            console.log('Widget ready');
+          }}
+          onError={(code, message) => {
+            Alert.alert('Error', `${code}: ${message}`);
+            if (code === 'WEBVIEW_ERROR') {
+              // Offer retry option
+              Alert.alert('Error', 'Failed to load. Retry?', [
+                { text: 'Cancel', onPress: () => setShowWidget(false) },
+                { text: 'Retry', onPress: () => widgetRef.current?.reload() },
+              ]);
+            }
+          }}
+          onClose={() => {
+            setShowWidget(false);
+          }}
+          onTransactionRequested={(token, amount, address, tag) => {
+            Alert.alert(
+              'Transaction Requested',
+              `Send ${amount} ${token.symbol} to ${address}`,
+            );
+          }}
+          onLoadingChange={(isLoading) => {
+            console.log('Loading:', isLoading);
+          }}
+        />
+      </View>
+    );
+  }
 
   return (
-    <WidgetSDK
-      ref={widgetRef}
-      widgetUrl={widgetUrl}
-      accessToken={token}
-      onClose={() => setShowWidget(false)}
-    />
+    <View style={styles.container}>
+      <Button
+        title="Open Payment Widget"
+        onPress={() => setShowWidget(true)}
+      />
+    </View>
   );
 }
-```
 
-### Web Widget Implementation
-
-Your web widget must handle these messages from the native app:
-
-```javascript
-// In your web widget
-window.addEventListener('message', (event) => {
-  try {
-    const message = JSON.parse(event.data);
-
-    if (message.type === 'native:back-pressed' || message.type === 'native:navigate-back') {
-      // Check if on first screen (login, etc.)
-      if (isOnFirstScreen()) {
-        // Close widget - return to native app
-        window.ReactNativeWebView.postMessage(JSON.stringify({
-          type: 'widget:close',
-          timestamp: Date.now()
-        }));
-      } else {
-        // Navigate back internally
-        window.history.back();
-        // OR: router.back() if using React Router
-      }
-    }
-  } catch (e) {
-    // Ignore non-JSON messages
-  }
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
 });
 ```
 
-### Message Types
-
-| Message | Direction | Description |
-|---------|-----------|-------------|
-| `native:back-pressed` | Native → Widget | User pressed back button/gesture |
-| `native:navigate-back` | Native → Widget | Programmatic back navigation request |
-| `widget:close` | Widget → Native | Widget requests to close |
-
 ## Dependencies
 
 ### Required Peer Dependencies
@@ -453,116 +334,35 @@ window.addEventListener('message', (event) => {
   "react": ">=18.0.0",
   "react-native": ">=0.70.0",
   "react-native-webview": ">=13.0.0",
-  "expo-linking": ">=6.0.0"
+  "expo-linking": ">=6.0.0",
+  "expo-clipboard": ">=5.0.0",
+  "expo-intent-launcher": ">=6.0.0",
+  "expo-local-authentication": ">=14.0.0"
 }
 ```
 
-### Optional Dependencies
-
-For full wallet integration on Android:
-- `expo-intent-launcher` - Android wallet integration
-
-Install with:
-```bash
-expo install expo-intent-launcher
-```
-
-## Common Use Cases
-
-### Show Widget After Authentication
-
-```typescript
-const [isAuthenticated, setIsAuthenticated] = useState(false);
-const [widgetUrl, setWidgetUrl] = useState('');
-
-useEffect(() => {
-  if (isAuthenticated) {
-    fetchWidgetUrl().then(setWidgetUrl);
-  }
-}, [isAuthenticated]);
-
-if (!isAuthenticated) {
-  return <LoginScreen onLogin={() => setIsAuthenticated(true)} />;
-}
-
-return <WidgetSDK widgetUrl={widgetUrl} {...props} />;
-```
-
-### Close Widget and Navigate
-
-```typescript
-<WidgetSDK
-  onCardCreated={(cardId) => {
-    // Navigate to card details immediately
-    navigation.replace('CardDetails', { cardId });
-  }}
-  onClose={() => {
-    // Go back to previous screen
-    navigation.goBack();
-  }}
-/>
-```
-
-### Track Analytics
-
-```typescript
-<WidgetSDK
-  onReady={() => {
-    analytics.track('widget_viewed');
-  }}
-  onCardCreated={(cardId, cardType) => {
-    analytics.track('card_created', {
-      cardId,
-      cardType,
-      source: 'mobile_app'
-    });
-  }}
-  onError={(code, message) => {
-    analytics.track('widget_error', { code, message });
-  }}
-/>
-```
-
-### Show Loading State
-
-```typescript
-const [isWidgetReady, setIsWidgetReady] = useState(false);
-
-<View style={{ flex: 1 }}>
-  {!isWidgetReady && (
-    <View style={styles.loadingOverlay}>
-      <ActivityIndicator size="large" />
-      <Text>Loading widget...</Text>
-    </View>
-  )}
-  <WidgetSDK
-    {...props}
-    onReady={() => setIsWidgetReady(true)}
-  />
-</View>
-```
-
 ## Troubleshooting
 
 ### Widget Not Loading
 
-**Check these:**
-1. Is `widgetUrl` accessible?
-2. Is the JWT token valid?
-3. Check React Native debugger for errors
-4. Verify `react-native-webview` is installed
+1. Verify `accessToken` is valid and not expired
+2. Check that `userWalletAddress` is a valid address
+3. Enable `debug={true}` to see console logs
+4. Verify all peer dependencies are installed
 
 ### Callbacks Not Firing
 
-**Make sure:**
-1. Your widget is sending proper postMessage events
-2. Message format matches expected structure (see web widget integration docs)
-3. Check console for `[WidgetSDK]` logs
+1. Enable debug mode to see message logs
+2. Check that your widget is sending proper postMessage events
+3. Verify message format matches expected structure
+
+### Error: TOKEN_EXPIRED
+
+The access token has expired. Fetch a new token from your backend and re-render the widget with the new token.
 
-### App Crashes on Wallet Integration
+### Error: WEBVIEW_ERROR
 
-**iOS:** Ensure Apple Wallet app is installed (may require real device)
-**Android:** Ensure Google Play Services is configured on the device/emulator
+The WebView failed to load. This could be a network issue. Use `widgetRef.current?.reload()` to retry.
 
 ## License