@trustchex/react-native-sdk 1.464.0 → 1.475.0

package/lib/module/Shared/Libs/PERMISSIONS_MANAGER.md

@@ -0,0 +1,268 @@
+# PermissionManager Documentation
+
+## Overview
+
+`PermissionManager` is a centralized utility for handling all platform-specific permission requests (camera, microphone, NFC, etc.) in the React Native SDK. It abstracts away platform differences (iOS vs Android) and provides a clean, consistent API.
+
+## Location
+
+- **File**: `src/Shared/Libs/permissions.utils.ts`
+- **Export**: Can be imported from `src/Shared/Libs/index.ts`
+
+## Supported Permissions
+
+```typescript
+type PermissionType = 'camera' | 'microphone' | 'nfc';
+```
+
+| Permission   | iOS | Android | Notes                                    |
+| ------------ | --- | ------- | ---------------------------------------- |
+| `camera`     | ✅  | ✅      | Camera access for video recording        |
+| `microphone` | ✅  | ✅      | Microphone access for audio recording    |
+| `nfc`        | ✅  | ✅      | NFC chip reading (document verification) |
+
+## API Reference
+
+### Request Methods
+
+#### `requestPermission(permission: PermissionType): Promise<boolean>`
+
+Request a single permission. Returns `true` if granted, `false` if denied.
+
+```typescript
+import PermissionManager from '../../Shared/Libs/permissions.utils';
+
+const hasCamera = await PermissionManager.requestPermission('camera');
+if (!hasCamera) {
+  console.log('Camera permission denied');
+}
+```
+
+#### `requestPermissions(permissions: PermissionType[]): Promise<Map<PermissionType, boolean>>`
+
+Request multiple permissions at once. Returns a Map with permission status for each.
+
+```typescript
+const results = await PermissionManager.requestPermissions([
+  'camera',
+  'microphone',
+]);
+const hasCamera = results.get('camera') ?? false;
+const hasMicrophone = results.get('microphone') ?? false;
+```
+
+#### `requestCameraAndMicrophone(): Promise<boolean>`
+
+**⭐ Convenience method** — Request camera and microphone together (common for video recording). Returns `true` only if BOTH are granted.
+
+```typescript
+const hasBothPermissions = await PermissionManager.requestCameraAndMicrophone();
+if (!hasBothPermissions) {
+  showError('Camera and microphone access required for video call');
+}
+```
+
+#### `requestCamera(): Promise<boolean>`
+
+Request camera permission only.
+
+```typescript
+const hasCamera = await PermissionManager.requestCamera();
+```
+
+#### `requestMicrophone(): Promise<boolean>`
+
+Request microphone permission only.
+
+```typescript
+const hasMicrophone = await PermissionManager.requestMicrophone();
+```
+
+#### `requestNFC(): Promise<boolean>`
+
+Request NFC permission for document verification.
+
+```typescript
+const hasNFC = await PermissionManager.requestNFC();
+```
+
+#### `requestWithFallback(permission: PermissionType, onDenied?: () => void): Promise<boolean>`
+
+Request permission with custom callback when denied.
+
+```typescript
+const granted = await PermissionManager.requestWithFallback('camera', () => {
+  showAlert('Camera access is required for verification');
+});
+```
+
+### Check Methods (Non-requesting)
+
+Check if a permission is already granted without requesting.
+
+#### `checkPermission(permission: PermissionType): Promise<boolean>`
+
+Check a single permission status.
+
+```typescript
+const hasCamera = await PermissionManager.checkPermission('camera');
+```
+
+#### `hasCameraAndMicrophone(): Promise<boolean>`
+
+Check if both camera and microphone are granted.
+
+```typescript
+const ready = await PermissionManager.hasCameraAndMicrophone();
+```
+
+#### `hasCamera(): Promise<boolean>`
+
+Check if camera is granted.
+
+```typescript
+const hasCamera = await PermissionManager.hasCamera();
+```
+
+#### `hasMicrophone(): Promise<boolean>`
+
+Check if microphone is granted.
+
+```typescript
+const hasMicrophone = await PermissionManager.hasMicrophone();
+```
+
+#### `hasNFC(): Promise<boolean>`
+
+Check if NFC is granted.
+
+```typescript
+const hasNFC = await PermissionManager.hasNFC();
+```
+
+## Common Patterns
+
+### Pattern 1: Video Call Setup (Camera + Microphone)
+
+```typescript
+import PermissionManager from '../../Shared/Libs/permissions.utils';
+
+async function initializeVideoCall() {
+  const hasBothPermissions =
+    await PermissionManager.requestCameraAndMicrophone();
+
+  if (!hasBothPermissions) {
+    setConnectionState('permissions_denied');
+    return;
+  }
+
+  // Proceed with video call initialization
+  const stream = await service.initialize();
+  setLocalStream(stream);
+}
+```
+
+### Pattern 2: Document Verification (NFC)
+
+```typescript
+const hasNFC = await PermissionManager.requestNFC();
+
+if (!hasNFC) {
+  showError('NFC access required to read document');
+  return;
+}
+
+const result = await readNFCChip();
+```
+
+### Pattern 3: Check Before Requesting
+
+```typescript
+// First check if permission is already granted
+const alreadyHasCamera = await PermissionManager.checkPermission('camera');
+
+if (alreadyHasCamera) {
+  // Skip request dialog
+  startCamera();
+} else {
+  // Request permission (shows OS dialog)
+  const granted = await PermissionManager.requestCamera();
+  if (granted) {
+    startCamera();
+  } else {
+    showErrorMessage('Camera access required');
+  }
+}
+```
+
+## Platform Implementation Details
+
+### iOS
+
+Uses the `react-native-permissions` library with `RNPermissions` module.
+
+**Permissions layout location**: `ios/App.xcodeproj/Info.plist`
+
+Required Info.plist keys:
+
+- `NSCameraUsageDescription` — Camera access explanation
+- `NSMicrophoneUsageDescription` — Microphone access explanation
+- `NFCReaderUsageDescription` — NFC access explanation
+
+### Android
+
+Uses built-in `PermissionsAndroid` from React Native core.
+
+**Permissions manifest location**: `android/app/src/main/AndroidManifest.xml`
+
+Required manifest permissions:
+
+- `android.permission.CAMERA` — Camera access
+- `android.permission.RECORD_AUDIO` — Microphone access
+- `android.permission.NFC` — NFC chip reading
+
+## Error Handling
+
+The PermissionManager handles errors internally and logs them using the debug utility. All methods return clear boolean or Map results so you can check status directly:
+
+```typescript
+const granted = await PermissionManager.requestCamera();
+
+// Simple check
+if (!granted) {
+  // Handle permission denied
+}
+```
+
+## Best Practices
+
+1. ✅ **Use convenience methods** — `requestCameraAndMicrophone()` instead of manually requesting both
+2. ✅ **Request at the right time** — Request permissions when the feature is about to be used
+3. ✅ **Check before requesting** — Use `checkPermission()` if you want to skip the OS dialog
+4. ✅ **Handle denial gracefully** — Always provide clear error messages when permissions are denied
+5. ✅ **Use the centralized manager** — Never import React Native permissions directly; always use PermissionManager
+
+## Troubleshooting
+
+### Permission request dialog not appearing
+
+- Check that you're using `request*` methods, not `check*` methods
+- Verify the permission is in the app's manifest (Android) or Info.plist (iOS)
+- Test on a device where the permission hasn't been granted yet
+
+### Camera/Microphone not working after permission granted
+
+- Check that you're handling successful permission grant and initializing the feature
+- Verify other features aren't holding exclusive access to the device
+
+### NFC not working on iOS
+
+- Ensure `NFCReaderUsageDescription` is set in Info.plist
+- The app must be signed with proper entitlements for NFC
+- NFC requires iPhone XS or later
+
+## Related Files
+
+- `src/Screens/Dynamic/VideoCallScreen.tsx` — Example usage with video calls
+- `src/Shared/Libs/index.ts` — Exported for easy importing
+- `src/Shared/Libs/debug.utils.ts` — Used internally for debug logging

package/lib/module/Shared/Libs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+
+// Export utility modules with validated symbols only.
+export { default as PermissionManager } from "./permissions.utils.js";
+export { SignalingClient } from "./SignalingClient.js";
+export { setDebugMode, setLogLevel, isDebugEnabled, getLogLevel, traceLog, debugLog, infoLog, debugWarn, debugError, logError, logWarn } from "./debug.utils.js";
+export { default as HTTPClient, HttpClientError, UnauthorizedError, ForbiddenError, NotFoundError, BadRequestError, TooManyRequestsError, InternalServerError } from "./http-client.js";
+export * from "./analytics.utils.js";
+export { getLocalizedCountryName } from "./country-display.utils.js";
+export { getSessionKey, encryptWithAes, decryptWithAes } from "./crypto.utils.js";
+export { default as debounce } from "./debounce.utils.js";
+export { handleDeepLink } from "./deeplink.utils.js";
+export { getSimulatedDemoData, isDemoSession } from "./demo.utils.js";
+export { default as MRZUtils } from "./mrz.utils.js";
+export { NativeDeviceInfo } from "./native-device-info.utils.js";
+export { default as getDeviceInfo } from "./native-device-info.utils.js";
+export { useKeepAwake, enableKeepAwake, disableKeepAwake, isKeepAwakeCurrentlyActive, getKeepAwakeStats } from "./native-keep-awake.utils.js";
+export { runWithRetry } from "./promise.utils.js";
+export { configureStatusBarForWhiteBackground, useStatusBarWhiteBackground } from "./status-bar.utils.js";
+export { speak, speakWithDebounce, stopSpeaking, resetLastMessage, initializeTTS } from "./tts.utils.js";