@oobit/react-native-sdk 1.0.0

package/README.md

@@ -0,0 +1,568 @@
+# Widget SDK
+
+A React Native/Expo SDK that makes it easy to embed your card issuance widget into mobile apps. Just drop in the component and handle callbacks - no WebView complexity needed.
+
+## Installation
+
+```bash
+npm install @your-company/widget-sdk
+# or
+yarn add @your-company/widget-sdk
+```
+
+In this monorepo:
+```typescript
+import { WidgetSDK } from '@sdk';
+```
+
+## Quick Start
+
+```typescript
+import { WidgetSDK } from '@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"
+        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.
+        }}
+      />
+    </View>
+  );
+}
+```
+
+## Props
+
+### Required Props
+
+#### `apiKey: string`
+Your API key for authentication.
+
+```typescript
+<WidgetSDK apiKey="your-api-key" />
+```
+
+#### `environment: 'sandbox' | 'production'`
+The environment to use.
+
+```typescript
+<WidgetSDK environment="production" />
+```
+
+#### `widgetUrl: string`
+The URL of your widget (typically includes a JWT token for authentication).
+
+```typescript
+<WidgetSDK widgetUrl="https://widget.yourapp.com?token=jwt_token_here" />
+```
+
+### Optional Callback Props
+
+#### `onReady?: () => void`
+Called when the widget has finished loading and is ready for interaction.
+
+**Use this to:**
+- Hide loading indicators
+- Track analytics events
+- Initialize app state
+
+```typescript
+<WidgetSDK
+  onReady={() => {
+    console.log('Widget is ready!');
+    analytics.track('widget_loaded');
+  }}
+/>
+```
+
+#### `onCardCreated?: (cardId: string, cardType: string, last4: string) => void`
+Called when a card is successfully created in the widget.
+
+**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
+
+```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 });
+  }}
+/>
+```
+
+#### `onError?: (code: 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
+
+```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
+      refreshAuth();
+    }
+  }}
+/>
+```
+
+#### `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
+
+```typescript
+<WidgetSDK
+  onClose={() => {
+    console.log('User closed widget');
+
+    // Navigate back
+    navigation.goBack();
+
+    // Or hide widget
+    setShowWidget(false);
+
+    // Track analytics
+    analytics.track('widget_closed');
+  }}
+/>
+```
+
+## Complete Example
+
+```typescript
+import React, { useState } from 'react';
+import { View, Button, StyleSheet, Alert, ActivityIndicator } from 'react-native';
+import { WidgetSDK } from '@sdk';
+
+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);
+    }
+  };
+
+  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>
+    );
+  }
+
+  return (
+    <View style={styles.container}>
+      <Button
+        title={isLoading ? 'Loading...' : 'Create Card'}
+        onPress={launchWidget}
+        disabled={isLoading}
+      />
+      {isLoading && <ActivityIndicator style={{ marginTop: 20 }} />}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    padding: 20,
+  },
+});
+```
+
+## TypeScript Support
+
+The SDK is fully typed. Import types as needed:
+
+```typescript
+import type { WidgetSDKConfig } from '@sdk';
+
+const config: WidgetSDKConfig = {
+  apiKey: 'your-key',
+  environment: 'production',
+  widgetUrl: 'https://...',
+  onCardCreated: (cardId, cardType, last4) => {
+    // Fully typed parameters
+  },
+};
+```
+
+### Message Type Constants
+
+For advanced use cases where you need to handle messages directly:
+
+```typescript
+import { MessageTypes } from '@sdk';
+
+// Use constants instead of strings
+if (message.type === MessageTypes.CARD_CREATED) {
+  // Handle card creation
+}
+```
+
+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!
+
+You can also manually open the wallet from your React Native app:
+
+```typescript
+import { openNativeWallet, isWalletAvailable } from '@sdk';
+
+// Check if wallet is available
+const available = await isWalletAvailable();
+
+if (available) {
+  // Open native wallet
+  await openNativeWallet();
+}
+```
+
+## 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)
+
+### Programmatic Back Navigation
+
+You can programmatically trigger back navigation using a ref:
+
+```typescript
+import { useRef } from 'react';
+import { WidgetSDK, WidgetSDKRef } from '@sdk';
+
+function MyScreen() {
+  const widgetRef = useRef<WidgetSDKRef>(null);
+
+  const handleTimeout = () => {
+    // Programmatically navigate widget back
+    widgetRef.current?.navigateBack();
+  };
+
+  return (
+    <WidgetSDK
+      ref={widgetRef}
+      widgetUrl={widgetUrl}
+      accessToken={token}
+      onClose={() => setShowWidget(false)}
+    />
+  );
+}
+```
+
+### 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
+  }
+});
+```
+
+### 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
+
+```json
+{
+  "react": ">=18.0.0",
+  "react-native": ">=0.70.0",
+  "react-native-webview": ">=13.0.0"
+}
+```
+
+### Optional Dependencies
+
+For full wallet integration:
+- `expo-intent-launcher` - Android wallet integration
+- `expo-linking` - Deep link handling
+
+Install with:
+```bash
+expo install expo-intent-launcher expo-linking
+```
+
+## 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
+
+### 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
+
+### App Crashes on Wallet Integration
+
+**iOS:** Ensure Apple Wallet app is installed (may require real device)
+**Android:** Ensure Google Play Services is configured on the device/emulator
+
+## Support
+
+For integration help:
+- [Architecture Docs](../SDK_ARCHITECTURE.md)
+- [Quick Start Guide](../SDK_QUICKSTART.md)
+- [Web Widget Integration](../WIDGET_INTEGRATION.md)
+
+## License
+
+MIT

package/dist/WidgetSDK.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Widget SDK Component
+ * Embeds the web widget in a WebView and handles bidirectional communication
+ */
+import React from "react";
+import { WidgetSDKConfig } from "./types";
+export interface WidgetSDKRef {
+    navigateBack: () => void;
+}
+export declare const WidgetSDK: React.ForwardRefExoticComponent<WidgetSDKConfig & React.RefAttributes<WidgetSDKRef>>;
+//# sourceMappingURL=WidgetSDK.d.ts.map

package/dist/WidgetSDK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WidgetSDK.d.ts","sourceRoot":"","sources":["../src/WidgetSDK.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAON,MAAM,OAAO,CAAC;AAIf,OAAO,EAAiB,eAAe,EAAE,MAAM,SAAS,CAAC;AAGzD,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED,eAAO,MAAM,SAAS,sFA6PrB,CAAC"}