@trustchex/react-native-sdk 1.464.0 → 1.475.0

package/src/Shared/Libs/MRZ_KNOWN_ISSUES.md

@@ -0,0 +1,112 @@
+# MRZ Reading & Correction — Known Issues & Limitations
+
+This documents the **inherent limitations** and **deliberate trade-offs** of the
+MRZ camera scanner (`mrz.utils.ts`, `mrzFrameAggregator.ts`, and the native
+`TrustchexCameraView` scan-frame OCR). These are not bugs — they are constraints
+of the ICAO 9303 standard and OCR, and the design decisions made around them.
+
+For the camera/OCR pipeline overview, see the doc comments in
+`mrzFrameAggregator.ts` and `mrz.utils.ts`.
+
+---
+
+## 1. Check-digit MOD-10 collisions: `1↔L` and `6↔G` are indistinguishable
+
+**Issue.** ICAO's 7-3-1 check digit weights letters by value (`A`=10 … `Z`=35),
+then takes the result mod 10. Some OCR look-alikes are **mod-10 equal** to the
+digit they resemble:
+
+| Look-alike | Letter value | Digit | mod 10 |
+| --- | --- | --- | --- |
+| `L` ↔ `1` | 21 | 1 | both ≡ **1** |
+| `G` ↔ `6` | 16 | 6 | both ≡ **6** |
+
+So a document number read as `SPECL2345` produces the **exact same check digit**
+as the correct `SPEC12345`. The MRZ **validates either way** — the check digit
+cannot tell them apart.
+
+**Impact.** If OCR reads a `1` as `L` (or `6` as `G`) in a *numeric* position of a
+field that also accepts letters (e.g. an alphanumeric document number), the MRZ
+will validate but may carry the letter form.
+
+**Mitigation.**
+
+- **Multi-frame voting** (`mrzFrameAggregator`) usually resolves it: across frames
+  the correct glyph wins the per-character vote.
+- **NFC chip read (eID)** is authoritative — when available it overrides the
+  camera reading.
+- Other digit↔letter confusions (`0↔O/Q/D`, `2↔Z`, `5↔S`, `8↔B`, `4↔A`, `1↔I`) are
+  **not** mod-10 collisions and *are* recovered to the correct digit.
+
+Covered by `mrz.ambiguous.test.ts` ("documents the … MOD-10 collision").
+
+---
+
+## 2. Unprotected fields (TD1 optional / national-ID) can't be self-corrected
+
+**Issue.** TD1's optional-data field (which on Turkish IDs holds the 11-digit
+national ID / TC number) has **no per-field check digit** — it is only covered by
+the composite check digit. If OCR corrupts the optional field **and** the
+composite digit is also dropped/misread (common on glossy cards), there is no
+independent anchor to detect the error.
+
+**Mitigation.** High-confidence numeric normalisation (`B→8`, `S→5`, `O→0`, …) is
+applied to the all-digit optional field, and **multi-frame voting** is the
+primary safeguard. A single noisy frame is not trusted; the consensus is.
+
+---
+
+## 3. Filler-letter normalisation is conservative in name fields (by design)
+
+**Issue.** The `<` filler is frequently OCR'd as a letter (`K`, and under glare
+`C`/`E`/`G`). We normalise these back to `<` **only** in structurally
+unambiguous positions — the trailing filler run, the TD1 issuing-state field, and
+the document-code filler.
+
+**Deliberate trade-off.** A `K`/`C`/`E`/`G` **inside the name field** is *not*
+normalised, because it cannot be distinguished from a real name letter (surnames
+like `AKTAS`, `KAYA`, `CETIN`, or a 2-letter `AK` start with these). Corrupting a
+real name is worse than a cosmetic filler glyph, so:
+
+- Names are **preserved verbatim** — `AKTAS` stays `AKTAS`.
+- A genuine filler misread *in the middle of a name region* may remain as a
+  letter (cosmetic only; the name field has no check digit, so validity is
+  unaffected, and the document number / dates — the identity-critical fields —
+  are always cleaned).
+
+Covered by the "real letters in names are not eaten" tests in `mrz.utils.test.ts`.
+
+---
+
+## 4. OCR throughput / image-quality dependence
+
+- **Resolution.** ML Kit needs ~16 px per character. A full-frame capture leaves a
+  30–44-char MRZ line below that floor, so the native pipeline **crops to the
+  on-screen scan frame and upscales + grayscale/contrast-enhances** before OCR.
+  The MRZ band must be reasonably filled within the on-screen guide.
+- **Glare / lamination.** Heavy glare on a glossy laminated card still degrades
+  OCR; the enhancement helps but does not eliminate it. Steadying the card and
+  reducing direct glare improves convergence.
+- **Throughput.** OCR runs at a few frames/sec; the JS handler is throttled
+  (~400 ms) and the recovery search is time-bounded so the UI stays responsive.
+  A pathological/garbage frame fails fast (recovery budget) rather than blocking.
+
+---
+
+## 5. Structurally broken frames are (correctly) rejected
+
+Truncated or wrong-length line-sets that cannot be repaired by ambiguous-char
+swaps or ±1 indel are reported **invalid** — the flow will not advance on a
+guess. This is intentional: a wrong-but-plausible reconstruction must never leak
+through. Multi-frame scanning accumulates until a check-digit-valid consensus is
+reached.
+
+---
+
+## 6. Platform parity
+
+The scan-frame ROI crop + grayscale/contrast enhancement exists on **both Android
+(Kotlin) and iOS (Swift / Core Image)**. The JS recovery, voting, and field
+mapping are shared, so behaviour is consistent across platforms. Debug builds
+require Metro to be reachable; build a **Release** variant for untethered device
+testing.

package/src/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/src/Shared/Libs/index.ts

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