@passgage/sdk-react-native 1.0.4 → 1.0.6

package/README.md

@@ -10,6 +10,15 @@ npm install @passgage/sdk-react-native
 yarn add @passgage/sdk-react-native
 ```
 
+## Dependencies
+
+The package has the following dependencies:
+
+- **axios**: ^1.6.0 - HTTP client for API requests
+- **react-native-geolocation-service**: ^5.3.1 - Geolocation service
+- **react-native-permissions**: ^5.4.4 - Permissions management
+- **zustand**: ^5.0.9 - State management
+
 ### Peer Dependencies
 
 You also need to install these peer dependencies:
@@ -19,9 +28,10 @@ npm install react-native-vision-camera react-native-nfc-manager @react-native-co
 ```
 
 Follow the installation instructions for each native library:
+
 - [react-native-vision-camera](https://react-native-vision-camera.com/docs/guides)
 - [react-native-nfc-manager](https://github.com/revtel/react-native-nfc-manager)
-- [@react-native-community/geolocation](https://github.com/react-native-geolocation/react-native-geolocation)
+- [react-native-geolocation-service](https://github.com/Agontuk/react-native-geolocation-service)
 - [react-native-keychain](https://github.com/oblador/react-native-keychain)
 
 ## Usage
@@ -31,232 +41,484 @@ Follow the installation instructions for each native library:
 Wrap your app with `PassgageAccessProvider`:
 
 ```typescript
-import { PassgageAccessProvider } from '@passgage/sdk-react-native';
+import {PassgageAccessProvider} from '@passgage/sdk-react-native';
 
 function App() {
   return (
     <PassgageAccessProvider
       baseURL="https://your-api.passgage.com"
-      onUnauthorized={() => {
+      msalToken={'Your MSAL Token'}
+      apiVersion="v2" // Optional: API version (default: "v2")
+      timeout={30000} // Optional: Request timeout in ms (default: 30000)
+      rememberUser={true} // Optional: Persist authentication (default: true)
+      onUnauthorized={error => {
         // Handle session expiration
-        console.log('Session expired');
+        console.log('Unauthorized error:', error);
       }}
-    >
+      getLocationErrorCallback={error => {
+        // Handle location retrieval errors
+        console.log('Location error:', error);
+      }}
+      locationPermissionErrorCallback={error => {
+        // Handle location permission errors
+        console.log('Permission error:', error);
+      }}>
       <YourApp />
     </PassgageAccessProvider>
   );
 }
 ```
 
+#### Provider Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `baseURL` | `string` | ✓ | - | Base URL of your Passgage API |
+| `msalToken` | `string` | ✓ | - | Microsoft Azure AD token |
+| `apiVersion` | `string` | ✗ | `"v2"` | API version to use |
+| `timeout` | `number` | ✗ | `30000` | Request timeout in milliseconds |
+| `rememberUser` | `boolean` | ✗ | `true` | Persist authentication state |
+| `onUnauthorized` | `(error: Error) => void` | ✗ | - | Called when session expires |
+| `getLocationErrorCallback` | `(error: any) => void` | ✗ | - | Called on location retrieval errors |
+| `locationPermissionErrorCallback` | `(error: any) => void` | ✗ | - | Called on location permission errors |
+
 ### Authentication
 
 ```typescript
-import { usePassgageAuth } from '@passgage/sdk-react-native';
+const LoginScreen = () => {
+  const {loading, error, loginWithAzure} = useAuthStore();
+
+  const handleLogin = async idToken => {
+    if (result?.idToken) {
+      loginWithAzure({id_token: result.idToken});
+    } else {
+      Alert.alert('Login Failed', 'No ID token received');
+    }
+  };
 
-function LoginScreen() {
-  const { login, logout, user, isLoading, isAuthenticated } = usePassgageAuth({
-    onLoginSuccess: (user) => {
-      console.log('Logged in:', user?.fullName);
+  return (
+    <View style={styles.formContainer}>
+      {error && (
+        <View style={styles.errorContainer}>
+          <Text style={styles.errorText}>{error}</Text>
+        </View>
+      )}
+      <TouchableOpacity
+        style={[styles.button, loading && styles.buttonDisabled]}
+        onPress={() => handleLogin('Provide your msal token')}
+        disabled={loading}>
+        {loading ? (
+          <ActivityIndicator color="#fff" />
+        ) : (
+          <Text style={styles.buttonText}>Sign In</Text>
+        )}
+      </TouchableOpacity>
+    </View>
+  );
+};
+```
+
+### QR Scanner
+
+```typescript
+const QRScannerScreen = () => {
+  const [qrCode, setQrCode] = useState('c70fc3a2-fbfb-4ca6-adcb-71ac0b796836');
+
+  const {scan, isLoading} = usePassgageQRScanner({
+    options: {skipLocationCheck: false, skipRepetitiveCheck: false},
+    onSuccess: entrance => {
+      const message = `Access granted!\nEntrance ID: ${entrance?.id || 'N/A'}`;
+      Alert.alert('Success', message);
     },
-    onLoginError: (error) => {
-      console.error('Login failed:', error);
+    onError: error => {
+      const errorMessage = error.message || 'QR validation failed';
+      Alert.alert('Failed', errorMessage);
     },
   });
 
-  const handleLogin = async () => {
-    await login({
-      login: 'user@example.com',
-      password: 'password123',
-    });
+  const handleScan = async () => {
+    if (!qrCode.trim()) {
+      Alert.alert('Error', 'Please enter a QR code');
+      return;
+    }
+
+    try {
+      await scan(qrCode.trim());
+    } catch (error: any) {
+      // Error already handled by onError callback
+      console.error('QR scan error:', error);
+    }
+  };
+
+  const handleClear = () => {
+    setQrCode('');
   };
 
   return (
-    <View>
-      {isAuthenticated ? (
-        <Text>Welcome, {user?.fullName}!</Text>
-      ) : (
-        <Button title="Login" onPress={handleLogin} disabled={isLoading} />
-      )}
+    <View style={styles.container}>
+      <View style={styles.content}>
+        <Text style={styles.icon}>📱</Text>
+        <Text style={styles.title}>QR Code Scanner</Text>
+        <Text style={styles.description}>
+          Enter a QR code to validate access
+        </Text>
+
+        <View style={styles.inputContainer}>
+          <TextInput
+            style={styles.input}
+            placeholder="Enter QR code"
+            value={qrCode}
+            onChangeText={setQrCode}
+            autoCapitalize="none"
+            editable={!isLoading}
+            returnKeyType="done"
+            onSubmitEditing={handleScan}
+          />
+        </View>
+
+        <View style={styles.buttonContainer}>
+          <TouchableOpacity
+            style={[
+              styles.button,
+              styles.scanButton,
+              isLoading && styles.buttonDisabled,
+            ]}
+            onPress={handleScan}
+            disabled={isLoading || !qrCode.trim()}>
+            {isLoading ? (
+              <ActivityIndicator color="#fff" />
+            ) : (
+              <Text style={styles.buttonText}>Validate QR Code</Text>
+            )}
+          </TouchableOpacity>
+          {qrCode.trim() && !isLoading && (
+            <TouchableOpacity
+              style={[styles.button, styles.clearButton]}
+              onPress={handleClear}>
+              <Text style={styles.clearButtonText}>Clear</Text>
+            </TouchableOpacity>
+          )}
+        </View>
+        <View style={styles.info}>
+          <Text style={styles.infoText}>
+            💡 In a real app, you would use react-native-vision-camera to scan
+            QR codes with the camera
+          </Text>
+          <Text style={styles.infoText}>
+            {'\n'}For testing, you can enter any QR code value manually
+          </Text>
+        </View>
+      </View>
     </View>
   );
-}
+};
 ```
 
-### QR Scanner
+### NFC Scanner
 
 ```typescript
-import { usePassgageQRScanner } from '@passgage/sdk-react-native';
+export default function NFCScannerScreen() {
+  NfcManager.start();
+
+  const {nfcData, supportNFC, startScanning, stopScanning, isScanning, error} =
+    usePassgageNFCScanner({
+      options: {skipLocationCheck: false, skipRepetitiveCheck: false},
+      onSuccess: entrance => {
+        const message = `Access granted!\nEntrance ID: ${
+          entrance?.id || 'N/A'
+        }`;
+        Alert.alert('Success', message);
+      },
+      onError: error => {
+        const errorMessage = error.message || 'NFC validation failed';
+        Alert.alert('Failed', errorMessage);
+      },
+    });
 
-function QRScanScreen() {
-  const { scan, isLoading, error } = usePassgageQRScanner({
-    onSuccess: (entrance) => {
-      console.log('QR scan successful:', entrance);
-    },
-    onError: (error) => {
-      console.error('QR scan failed:', error);
-    },
-  });
+  const handleStartScan = async () => {
+    startScanning();
+  };
 
+  const handleStopScan = async () => {
+    try {
+      await stopScanning();
+    } catch (error: any) {
+      console.error('Stop NFC scan error:', error);
+    }
+  };
   return (
-    <View>
-      <Camera
-        onCodeScanned={(code) => scan(code)}
-        isActive={!isLoading}
-      />
+    <View style={styles.container}>
+      <View style={styles.content}>
+        <Text style={styles.icon}>💳</Text>
+        <Text style={styles.title}>NFC Card Scanner</Text>
+        <Text style={styles.description}>
+          {isScanning
+            ? 'Hold your device near an NFC card'
+            : 'Tap the button below to start scanning'}
+        </Text>
+
+        <View style={styles.scanStatus}>
+          {isScanning ? (
+            <>
+              <ActivityIndicator size="large" color="#FF9500" />
+              <Text style={styles.statusText}>Scanning for NFC cards...</Text>
+            </>
+          ) : (
+            <View style={styles.readyIndicator}>
+              <Text style={styles.readyText}>
+                {supportNFC
+                  ? 'Ready to scan'
+                  : supportNFC === false
+                  ? 'Device not support NFC'
+                  : 'LOADING...'}
+              </Text>
+            </View>
+          )}
+        </View>
+
+        <View style={styles.buttonContainer}>
+          {!isScanning ? (
+            <TouchableOpacity
+              style={[styles.button, styles.scanButton]}
+              onPress={async () => {
+                handleStartScan();
+              }}>
+              <Text style={styles.buttonText}>Start NFC Scan</Text>
+            </TouchableOpacity>
+          ) : (
+            <TouchableOpacity
+              style={[styles.button, styles.stopButton]}
+              onPress={handleStopScan}>
+              <Text style={styles.buttonText}>Stop Scanning</Text>
+            </TouchableOpacity>
+          )}
+        </View>
+
+        {error && (
+          <View style={styles.errorContainer}>
+            <Text style={styles.errorText}>{error.message}</Text>
+          </View>
+        )}
+
+        <View style={styles.info}>
+          <Text style={styles.infoTitle}>How it works:</Text>
+          <Text style={styles.infoText}>
+            1. Tap "Start NFC Scan" button{'\n'}
+            2. Hold your device near an NFC card{'\n'}
+            3. Wait for validation response{'\n'}
+            4. Access will be granted if authorized
+          </Text>
+          <Text style={styles.infoNote}>
+            {'\n'}💡 Make sure NFC is enabled in your device settings
+          </Text>
+        </View>
+      </View>
     </View>
   );
 }
 ```
 
-### NFC Scanner
+## API
+
+### Hooks
+
+All hooks use the `usePassgage*` prefix to avoid naming conflicts:
+
+#### `usePassgageQRScanner(options)`
+
+QR code scanning with validation and location checking.
 
 ```typescript
-import { usePassgageNFCScanner } from '@passgage/sdk-react-native';
+const {scan, isLoading} = usePassgageQRScanner({
+  options: {
+    skipLocationCheck: false,    // Skip location verification
+    skipRepetitiveCheck: false,  // Skip duplicate scan detection
+  },
+  onSuccess: (entrance) => {
+    console.log('Access granted:', entrance);
+  },
+  onError: (error) => {
+    console.error('Access denied:', error);
+  },
+});
+
+// Scan a QR code
+await scan(qrCode);
+```
+
+#### `usePassgageNFCScanner(options)`
 
-function NFCScanScreen() {
-  const { startScanning, stopScanning, isScanning } = usePassgageNFCScanner({
+NFC card scanning with validation and location checking.
+
+```typescript
+const {nfcData, supportNFC, startScanning, stopScanning, isScanning, error} =
+  usePassgageNFCScanner({
+    options: {
+      skipLocationCheck: false,
+      skipRepetitiveCheck: false,
+    },
     onSuccess: (entrance) => {
-      console.log('NFC scan successful:', entrance);
+      console.log('Access granted:', entrance);
     },
     onError: (error) => {
-      console.error('NFC scan failed:', error);
+      console.error('Access denied:', error);
     },
   });
 
-  useEffect(() => {
-    startScanning();
-    return () => stopScanning();
-  }, []);
+// Start NFC scanning
+await startScanning();
 
-  return (
-    <View>
-      <Text>{isScanning ? 'Scanning...' : 'Tap to scan'}</Text>
-    </View>
-  );
-}
+// Stop NFC scanning
+await stopScanning();
 ```
 
-### Check-In
+**Returns:**
+- `nfcData?: string` - Last scanned NFC card data
+- `supportNFC?: boolean` - Whether device supports NFC
+- `startScanning: () => Promise<void>` - Start NFC scanning
+- `stopScanning: () => Promise<void>` - Stop NFC scanning
+- `isScanning: boolean` - Whether currently scanning
+- `error: Error | null` - Last error if any
+
+#### `useLocation()`
+
+Access current user location and location utilities.
 
 ```typescript
-import { usePassgageCheckIn, usePassgageAuth } from '@passgage/sdk-react-native';
-
-function CheckInScreen() {
-  const { user } = usePassgageAuth();
-  const { getNearbyBranches, checkInEntry, checkInExit, isLoading } = usePassgageCheckIn();
-  const [branches, setBranches] = useState([]);
-
-  useEffect(() => {
-    const loadBranches = async () => {
-      const result = await getNearbyBranches({ radius: 5000 });
-      if (result.success) {
-        setBranches(result.data);
-      }
-    };
-    loadBranches();
-  }, []);
-
-  const handleCheckIn = async (branchId: string) => {
-    const result = await checkInEntry({
-      branchId,
-      userId: user.id,
-    });
+const {location, error, refreshLocation} = useLocation();
 
-    if (result.success) {
-      console.log('Checked in successfully');
-    }
-  };
+// Get current location
+console.log(location?.latitude, location?.longitude);
 
-  return (
-    <View>
-      {branches.map((branch) => (
-        <TouchableOpacity key={branch.id} onPress={() => handleCheckIn(branch.id)}>
-          <Text>{branch.title}</Text>
-        </TouchableOpacity>
-      ))}
-    </View>
-  );
-}
+// Manually refresh location
+await refreshLocation();
 ```
 
-### Remote Work
+**Returns:**
+- `location?: Location` - Current location coordinates
+- `error?: string` - Location error if any
+- `refreshLocation: () => Promise<void>` - Manually refresh location
+
+### State Management
+
+#### `useAuthStore()`
+
+Zustand store for authentication state management.
 
 ```typescript
-import { usePassgageRemoteWork, usePassgageAuth } from '@passgage/sdk-react-native';
+import {useAuthStore} from '@passgage/sdk-react-native';
+
+const {
+  user,
+  loading,
+  error,
+  authStatus,
+  login,
+  loginWithAzure,
+  logout,
+  restoreAuth,
+  refreshToken,
+  clearError,
+} = useAuthStore();
+
+// Login with Azure AD
+await loginWithAzure({id_token: 'your-azure-token'});
+
+// Check auth status
+if (authStatus === 'authenticated') {
+  console.log('User:', user);
+}
 
-function RemoteWorkScreen() {
-  const { user } = usePassgageAuth();
-  const { logEntry, logExit, isLoading } = usePassgageRemoteWork();
+// Logout
+await logout();
 
-  const handleStartWork = async () => {
-    const result = await logEntry({
-      userId: user.id,
-      description: 'Working from home',
-    });
+// Restore previous session
+await restoreAuth();
 
-    if (result.success) {
-      console.log('Work entry logged');
-    }
-  };
+// Manually refresh token
+await refreshToken();
 
-  const handleEndWork = async () => {
-    const result = await logExit({
-      userId: user.id,
-      description: 'Finished work',
-    });
+// Clear error state
+clearError();
+```
 
-    if (result.success) {
-      console.log('Work exit logged');
-    }
-  };
+**State:**
+- `user?: User` - Current authenticated user
+- `loading: boolean` - Loading state
+- `error: string | null` - Error message if any
+- `authStatus: 'idle' | 'loading' | 'authenticated' | 'unauthenticated'` - Authentication status
 
-  return (
-    <View>
-      <Button title="Start Work" onPress={handleStartWork} disabled={isLoading} />
-      <Button title="End Work" onPress={handleEndWork} disabled={isLoading} />
-    </View>
-  );
-}
+**Methods:**
+- `login(credentials)` - Login with email/password
+- `loginWithAzure(params)` - Login with Azure AD token
+- `logout()` - Logout and clear session
+- `restoreAuth()` - Restore session from secure storage
+- `refreshToken()` - Manually refresh access token
+- `clearError()` - Clear error state
+
+### Services
+
+Low-level services for advanced use cases. Most developers should use hooks instead.
+
+#### `AuthService`
+
+```typescript
+import {AuthService} from '@passgage/sdk-react-native';
+
+const authService = new AuthService(apiClient);
+await authService.loginWithAzure({id_token: 'token'});
+await authService.logout();
 ```
 
-## API
+#### `QRAccessService`
 
-### Hooks
+```typescript
+import {QRAccessService} from '@passgage/sdk-react-native';
 
-All hooks use the `usePassgage*` prefix to avoid naming conflicts:
+const qrService = new QRAccessService(apiClient);
+const entrance = await qrService.validateQRCode(qrCode, options);
+```
 
-- `usePassgageAuth()` - Authentication and user management
-- `usePassgageQRScanner()` - QR code scanning with validation
-- `usePassgageNFCScanner()` - NFC card scanning with validation
-- `usePassgageCheckIn()` - GPS-based check-in with nearby branches
-- `usePassgageRemoteWork()` - Remote work entry/exit logging
-- `useLocation()` - Location tracking and permissions
-- `usePassgageAccess()` - Access SDK context and services
+#### `NFCAccessService`
 
-### Components
+```typescript
+import {NFCAccessService} from '@passgage/sdk-react-native';
 
-- `<PassgageAccessProvider>` - SDK configuration provider
+const nfcService = new NFCAccessService(apiClient);
+const entrance = await nfcService.validateNFCCard(cardId, options);
+```
 
-### Services
+#### `DeviceAccessService`
 
-Low-level services are also available through `usePassgageAccess()`:
+```typescript
+import {DeviceAccessService} from '@passgage/sdk-react-native';
 
-- `authService` - Authentication operations
-- `qrAccessService` - QR code validation
-- `nfcAccessService` - NFC card validation
-- `checkInService` - Check-in operations
-- `remoteWorkService` - Remote work logging
-- `locationService` - Location management
-- `deviceAccessService` - Device operations
+const deviceService = new DeviceAccessService(apiClient);
+const device = await deviceService.getDeviceInfo(deviceId);
+```
+
+#### `LocationService`
+
+```typescript
+import {LocationService} from '@passgage/sdk-react-native';
+
+const locationService = new LocationService();
+const location = await locationService.getCurrentLocation();
+const isInRange = locationService.isWithinRange(location, targetLocation, range);
+```
+
+### Components
+
+- `<PassgageAccessProvider>` - SDK configuration provider
 
 ## Security Features
 
 - **JWT Authentication**: Secure token-based authentication
 - **Automatic Token Refresh**: Tokens are automatically refreshed when expired
-- **Secure Storage**: Tokens stored securely using platform-specific secure storage
+- **Secure Storage**: Tokens stored securely using platform-specific secure storage (Keychain/Keystore)
 - **TLS 1.2+**: All network communications encrypted
 - **Location Verification**: Automatic location validation with range checking
-- **Anti-Passback**: Support for anti-passback rules
+- **Backend Logging**: Access logs sent to backend for audit trail
 
 ## Token Flow
 
@@ -267,7 +529,7 @@ The SDK automatically handles authentication tokens:
 3. Tokens are automatically refreshed when they expire
 4. On logout, all tokens are cleared
 
-**You don't need to manually manage tokens!** Just use the hooks and the SDK handles everything.
+**You don't need to manually manage tokens!** Just provide msal tokens to provider and the SDK handles everything.
 
 ## Example Application