@trustchex/react-native-sdk 1.497.0 → 1.500.2

package/src/Shared/Components/IdentityDocumentCamera.tsx

@@ -11,6 +11,7 @@ import {
   ActivityIndicator,
   PermissionsAndroid,
   Animated,
+  TouchableOpacity,
   type NativeSyntheticEvent,
   type ViewStyle,
 } from 'react-native';
@@ -31,6 +32,7 @@ import { debugLog, logError, isDebugEnabled } from '../Libs/debug.utils';
 import { diagnostics } from '../Libs/diagnostics';
 import LottieView from 'lottie-react-native';
 import StyledButton from './StyledButton';
+import DiagnosticReportButton from './DiagnosticReportButton';
 import { SafeAreaView } from 'react-native-safe-area-context';
 import { speak, resetLastMessage } from '../Libs/tts.utils';
 import AppContext from '../Contexts/AppContext';
@@ -67,6 +69,7 @@ import {
   MAX_CONSECUTIVE_QUALITY_FAILURES,
   REQUIRED_CONSISTENT_MRZ_READS,
   REQUIRED_CONSISTENT_DOCTYPE_DETECTIONS,
+  HELP_PROMPT_DELAY_MS,
   SIGNATURE_TEXT_REGEX,
   MRZ_BLOCK_PATTERN,
   MIN_CARD_FACE_SIZE_PERCENT,
@@ -143,6 +146,13 @@ const IdentityDocumentCamera = ({
   // cleared when a frame passes the brightness check (a fresh, glare-free frame).
   const [isGlareDetected, setIsGlareDetected] = useState(false);
   const [hasGuideShown, setHasGuideShown] = useState(false);
+  // "Having trouble?" escape: if a scan step doesn't complete within
+  // HELP_PROMPT_DELAY_MS the user is otherwise stuck on a live camera forever
+  // (no timeout/retry/help). We surface an unobtrusive prompt, then an opt-in
+  // help sheet with tips / retry / torch.
+  const [showHelpPrompt, setShowHelpPrompt] = useState(false);
+  const [helpSheetVisible, setHelpSheetVisible] = useState(false);
+  const stepStartedAt = useRef<number>(Date.now());
   const [status, setStatus] = useState<
     'SEARCHING' | 'SCANNING' | 'SCANNED' | 'INCORRECT'
   >('SEARCHING');
@@ -444,6 +454,25 @@ const IdentityDocumentCamera = ({
     }
   }, [status]);
 
+  // "Having trouble?" stuck-detection. The scan is frame-driven with no
+  // wall-clock timeout, so a document that never reads leaves the user stranded.
+  // Re-arm per step (keyed on nextStep) and per scan-start (hasGuideShown); show
+  // the prompt once the current step has been open longer than the threshold.
+  // Never arm on the terminal COMPLETED step.
+  useEffect(() => {
+    setShowHelpPrompt(false);
+    stepStartedAt.current = Date.now();
+    if (!hasGuideShown || nextStep === 'COMPLETED') {
+      return;
+    }
+    const interval = setInterval(() => {
+      if (Date.now() - stepStartedAt.current >= HELP_PROMPT_DELAY_MS) {
+        setShowHelpPrompt(true);
+      }
+    }, 1000);
+    return () => clearInterval(interval);
+  }, [nextStep, hasGuideShown]);
+
   // Disable face detection when scanning back side (no face expected, avoids false positives)
   useEffect(() => {
     if (nextStep === 'SCAN_ID_BACK') {
@@ -2643,37 +2672,53 @@ const IdentityDocumentCamera = ({
           onCameraError={handleCameraError}
         />
         <View style={[styles.topZone, { paddingTop: insets.top }]}>
-          {nextStep !== 'COMPLETED' &&
-            status !== 'SCANNED' &&
-            detectedDocumentType !== 'UNKNOWN' && (
-              <TextView style={styles.stepIndicator}>
-                {nextStep === 'SCAN_ID_FRONT_OR_PASSPORT'
-                  ? `${t('identityDocumentCamera.frontSide')} • ${t(
+          {nextStep !== 'COMPLETED' && status !== 'SCANNED' && (
+            <TextView style={styles.stepIndicator}>
+              {nextStep === 'SCAN_ID_FRONT_OR_PASSPORT'
+                ? // Show "Front side • 1/N" from the START — even before the
+                  // document type is recognized — so the user immediately knows
+                  // to present the photo side and how many steps remain. Until
+                  // the type is known we assume the ID-card path (the common
+                  // case); the total corrects to the passport count once a
+                  // passport is detected.
+                  `${t('identityDocumentCamera.frontSide')} • ${t(
+                    'identityDocumentCamera.stepProgress',
+                    {
+                      current: 1,
+                      total: onlyMRZScan
+                        ? detectedDocumentType === 'PASSPORT'
+                          ? 1
+                          : 2
+                        : detectedDocumentType === 'PASSPORT'
+                          ? 2
+                          : 3,
+                    }
+                  )}`
+                : nextStep === 'SCAN_HOLOGRAM'
+                  ? `${t('identityDocumentCamera.hologramCheck')} • ${t(
                       'identityDocumentCamera.stepProgress',
                       {
-                        current: 1,
-                        total: onlyMRZScan
-                          ? detectedDocumentType === 'PASSPORT'
-                            ? 1
-                            : 2
-                          : detectedDocumentType === 'PASSPORT'
-                            ? 2
-                            : 3,
+                        current: 2,
+                        total: detectedDocumentType === 'PASSPORT' ? 2 : 3,
                       }
                     )}`
-                  : nextStep === 'SCAN_HOLOGRAM'
-                    ? `${t('identityDocumentCamera.hologramCheck')} • ${t(
-                        'identityDocumentCamera.stepProgress',
-                        {
-                          current: 2,
-                          total: detectedDocumentType === 'PASSPORT' ? 2 : 3,
-                        }
-                      )}`
-                    : nextStep === 'SCAN_ID_BACK'
-                      ? `${t('identityDocumentCamera.backSide')} • ${t('identityDocumentCamera.stepProgress', { current: 3, total: 3 })}`
-                      : ''}
-              </TextView>
-            )}
+                  : nextStep === 'SCAN_ID_BACK'
+                    ? `${t('identityDocumentCamera.backSide')} • ${t('identityDocumentCamera.stepProgress', { current: 3, total: 3 })}`
+                    : ''}
+            </TextView>
+          )}
+
+          {/* Hologram capture progress — 16 frames are collected while the user
+              tilts the document; show N/16 so "tilt slowly" feels responsive
+              instead of a silent wait. */}
+          {nextStep === 'SCAN_HOLOGRAM' && status !== 'SCANNED' && (
+            <TextView style={styles.hologramProgress}>
+              {t('identityDocumentCamera.hologramProgress', {
+                current: hologramImageCount,
+                total: HOLOGRAM_IMAGE_COUNT,
+              })}
+            </TextView>
+          )}
 
           <AnimatedText
             style={[
@@ -2788,6 +2833,97 @@ const IdentityDocumentCamera = ({
         {testMode && testModeData && (
           <TestModePanel mrzText={testModeData.mrzText} />
         )}
+
+        {/* "Having trouble?" prompt — shows after the step has been stuck a
+            while; tapping it opens the help sheet. */}
+        {showHelpPrompt && !helpSheetVisible && nextStep !== 'COMPLETED' && (
+          <TouchableOpacity
+            style={styles.helpPrompt}
+            accessibilityRole="button"
+            onPress={() => setHelpSheetVisible(true)}
+          >
+            <TextView style={styles.helpPromptText}>
+              {t('identityDocumentCamera.havingTrouble')}
+            </TextView>
+          </TouchableOpacity>
+        )}
+
+        {/* Plain absolute overlay (NOT a <Modal>): the help sheet hosts a
+            DiagnosticReportButton which renders its OWN <Modal> for the sending
+            overlay, and nesting Modals is unreliable on iOS (the inner sending/
+            cancel UI can fail to present). An absolute View avoids the nesting. */}
+        {helpSheetVisible && (
+          <View style={styles.helpBackdrop}>
+            <View style={styles.helpCard}>
+              <TextView style={styles.helpTitle}>
+                {t('identityDocumentCamera.troubleTitle')}
+              </TextView>
+              <TextView style={styles.helpTip}>
+                {`• ${t('identityDocumentCamera.guidePoint1')}`}
+              </TextView>
+              <TextView style={styles.helpTip}>
+                {`• ${t('identityDocumentCamera.guidePoint2')}`}
+              </TextView>
+              <TextView style={styles.helpTip}>
+                {`• ${t('identityDocumentCamera.guidePoint3')}`}
+              </TextView>
+
+              {/* Torch is most useful in low light — only offer it then, and
+                  not during the hologram step (which manages the torch itself). */}
+              {isBrightnessLow && nextStep !== 'SCAN_HOLOGRAM' && (
+                <StyledButton
+                  mode="outlined"
+                  onPress={() => {
+                    setIsTorchOn(!isTorchOnRef.current);
+                  }}
+                  style={styles.helpButton}
+                >
+                  {isTorchOn
+                    ? t('identityDocumentCamera.turnOffTorch')
+                    : t('identityDocumentCamera.turnOnTorch')}
+                </StyledButton>
+              )}
+
+              <StyledButton
+                mode="contained"
+                onPress={() => {
+                  // Full restart: send the flow back to the first step (so a
+                  // stuck back/hologram step truly restarts, matching the label)
+                  // and re-show the guide, which deactivates + resets scan state
+                  // via the focus effect.
+                  setHelpSheetVisible(false);
+                  setShowHelpPrompt(false);
+                  setNextStep('SCAN_ID_FRONT_OR_PASSPORT');
+                  setDetectedDocumentType('UNKNOWN');
+                  setHasGuideShown(false);
+                }}
+                style={styles.helpButton}
+              >
+                {t('identityDocumentCamera.troubleRetry')}
+              </StyledButton>
+
+              {/* Support channel for a stuck scan. The diagnostics singleton
+                  has captured this scan's camera signals (brightness, blur,
+                  glare, frame stats); the report is PoW-authenticated and opt-in
+                  (asks before sending), and auto-hides without baseUrl/session. */}
+              <View style={styles.helpButton}>
+                <DiagnosticReportButton
+                  baseUrl={appContext.baseUrl}
+                  sessionId={appContext.identificationInfo?.sessionId}
+                  scan={{ documentType: detectedDocumentType }}
+                />
+              </View>
+
+              <StyledButton
+                mode="text"
+                onPress={() => setHelpSheetVisible(false)}
+                style={styles.helpButton}
+              >
+                {t('identityDocumentCamera.troubleDismiss')}
+              </StyledButton>
+            </View>
+          </View>
+        )}
       </>
     </View>
   );
@@ -2842,6 +2978,13 @@ const styles = StyleSheet.create({
     fontWeight: '500',
     marginBottom: 4,
   },
+  hologramProgress: {
+    color: '#4CAF50',
+    fontSize: 14,
+    textAlign: 'center',
+    fontWeight: '600',
+    marginBottom: 4,
+  },
   topZoneText: {
     color: 'white',
     fontSize: 20,
@@ -2877,6 +3020,56 @@ const styles = StyleSheet.create({
     bottom: '36%',
     backgroundColor: '#00000099',
   },
+  helpPrompt: {
+    position: 'absolute',
+    bottom: 40,
+    alignSelf: 'center',
+    backgroundColor: 'rgba(0,0,0,0.65)',
+    paddingVertical: 10,
+    paddingHorizontal: 20,
+    borderRadius: 22,
+  },
+  helpPromptText: {
+    color: 'white',
+    fontSize: 15,
+    fontWeight: '600',
+  },
+  helpBackdrop: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: 'rgba(0,0,0,0.55)',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 24,
+    zIndex: 10,
+  },
+  helpCard: {
+    width: '100%',
+    maxWidth: 340,
+    backgroundColor: 'white',
+    borderRadius: 16,
+    paddingVertical: 24,
+    paddingHorizontal: 20,
+  },
+  helpTitle: {
+    fontSize: 18,
+    fontWeight: 'bold',
+    color: '#111827',
+    textAlign: 'center',
+    marginBottom: 16,
+  },
+  helpTip: {
+    fontSize: 15,
+    color: '#374151',
+    lineHeight: 22,
+    marginBottom: 8,
+  },
+  helpButton: {
+    marginTop: 12,
+  },
   bottomZone: {
     position: 'absolute',
     top: '64%',

package/src/Shared/Libs/mrz.utils.ts

@@ -428,7 +428,33 @@ const reconstructMRZCandidates = (rawText: string): string[][] => {
             head = fixed + head.slice(9);
           }
         }
-        const optional = '<'.repeat(14);
+
+        // Recover the REAL optional/personal-number field (line-2 positions
+        // 29–42, i.e. 0-indexed 28–41) instead of blanking it. Many passports
+        // (and most residence permits) carry a personal number here; blanking it
+        // silently drops that data. Stitch any split fragment lines onto this
+        // line so the optional window is present, then accept the OCR'd optional
+        // ONLY if its own check digit (position 43, 0-indexed 42) validates —
+        // that proves the 14 chars were read correctly. If it doesn't validate
+        // (garbled/split-filler), fall back to the canonical blank, preserving
+        // the previous robustness for the empty-optional case.
+        let stitched = ocrLines[i];
+        let sj = i + 1;
+        while (stitched.length < 44 && sj < ocrLines.length) {
+          stitched += ocrLines[sj];
+          sj++;
+        }
+        let optional = '<'.repeat(14);
+        if (stitched.length >= 43) {
+          const candidateOptional = stitched.slice(28, 42);
+          const optionalCheck = stitched[42];
+          if (
+            /^[A-Z0-9<]{14}$/.test(candidateOptional) &&
+            cd731(candidateOptional) === optionalCheck
+          ) {
+            optional = candidateOptional;
+          }
+        }
         const l2NoComposite = head + optional + cd731(optional);
         const composite =
           l2NoComposite.slice(0, 10) +

package/src/Translation/Resources/en.ts

@@ -33,6 +33,14 @@ export default {
   'termsOfUseAndDataPrivacyScreen.acceptAndContinue': 'Accept and Continue',
   'resultScreen.submitting': 'Submitting your information...',
   'resultScreen.submissionFailed': 'An error occurred. Please try again later.',
+  'resultScreen.submissionFailedTitle': 'Submission failed',
+  'resultScreen.submissionFailedRetryHint':
+    'We could not submit your verification. Your information is saved — you can try again without re-scanning.',
+  'resultScreen.retrySubmission': 'Retry',
+  'errorBoundary.title': 'Something went wrong',
+  'errorBoundary.message':
+    'An unexpected error occurred. You can try again to continue.',
+  'errorBoundary.tryAgain': 'Try Again',
   'resultScreen.submissionSuccessful':
     'Your information has been securely submitted. You will be notified of the verification result shortly.',
   'resultScreen.thankYou': 'Thank You!',
@@ -160,6 +168,12 @@ export default {
     'Place document on a flat, dark surface',
   'identityDocumentCamera.guidePoint2': 'Use adequate lighting without glare',
   'identityDocumentCamera.guidePoint3': 'Keep the document within the frame',
+  'identityDocumentCamera.havingTrouble': 'Having trouble?',
+  'identityDocumentCamera.troubleTitle': 'Tips for scanning',
+  'identityDocumentCamera.troubleRetry': 'Restart scan',
+  'identityDocumentCamera.troubleDismiss': 'Keep trying',
+  'identityDocumentCamera.turnOnTorch': 'Turn on flashlight',
+  'identityDocumentCamera.turnOffTorch': 'Turn off flashlight',
   'identityDocumentCamera.lowBrightness':
     'Insufficient lighting. Move to a brighter location.',
   'identityDocumentCamera.alignPhotoSide': 'Show the side with your photo',
@@ -179,6 +193,8 @@ export default {
   'identityDocumentCamera.frontSide': 'Front',
   'identityDocumentCamera.backSide': 'Back',
   'identityDocumentCamera.hologramCheck': 'Hologram',
+  'identityDocumentCamera.hologramProgress':
+    'Capturing hologram… {{current}}/{{total}}',
   'identityDocumentCamera.keepSteady': 'Keep device steady',
   'identityDocumentCamera.avoidBlur': 'Keep device steady',
   'identityDocumentCamera.reduceGlare':

package/src/Translation/Resources/tr.ts

@@ -33,6 +33,14 @@ export default {
   'resultScreen.submitting': 'Bilgileriniz gönderiliyor...',
   'resultScreen.submissionFailed':
     'Bir hata oluştu. Lütfen daha sonra tekrar deneyin.',
+  'resultScreen.submissionFailedTitle': 'Gönderim başarısız',
+  'resultScreen.submissionFailedRetryHint':
+    'Doğrulamanız gönderilemedi. Bilgileriniz kaydedildi — yeniden taramadan tekrar deneyebilirsiniz.',
+  'resultScreen.retrySubmission': 'Tekrar Dene',
+  'errorBoundary.title': 'Bir şeyler ters gitti',
+  'errorBoundary.message':
+    'Beklenmeyen bir hata oluştu. Devam etmek için tekrar deneyebilirsiniz.',
+  'errorBoundary.tryAgain': 'Tekrar Dene',
   'resultScreen.submissionSuccessful':
     'Bilgileriniz güvenle gönderilmiştir. Doğrulama sonucu kısa süre içinde size bildirilecektir.',
   'resultScreen.thankYou': 'Teşekkürler!',
@@ -161,6 +169,12 @@ export default {
     'Belgeyi düz, koyu bir zemin üzerine yerleştirin',
   'identityDocumentCamera.guidePoint2': 'Yansıma olmadan yeterli ışık kullanın',
   'identityDocumentCamera.guidePoint3': 'Belgeyi çerçeve içinde tutun',
+  'identityDocumentCamera.havingTrouble': 'Sorun mu yaşıyorsunuz?',
+  'identityDocumentCamera.troubleTitle': 'Tarama ipuçları',
+  'identityDocumentCamera.troubleRetry': 'Taramayı yeniden başlat',
+  'identityDocumentCamera.troubleDismiss': 'Denemeye devam et',
+  'identityDocumentCamera.turnOnTorch': 'Feneri aç',
+  'identityDocumentCamera.turnOffTorch': 'Feneri kapat',
   'identityDocumentCamera.lowBrightness':
     'Aydınlatma yetersiz. Lütfen daha aydınlık bir yere gidin.',
   'identityDocumentCamera.alignPhotoSide': 'Fotoğraflı yüzü gösterin',
@@ -180,6 +194,8 @@ export default {
   'identityDocumentCamera.frontSide': 'Ön',
   'identityDocumentCamera.backSide': 'Arka',
   'identityDocumentCamera.hologramCheck': 'Hologram',
+  'identityDocumentCamera.hologramProgress':
+    'Hologram yakalanıyor… {{current}}/{{total}}',
   'identityDocumentCamera.keepSteady': 'Cihazı sabit tutun',
   'identityDocumentCamera.avoidBlur': 'Cihazı sabit tutun',
   'identityDocumentCamera.reduceGlare':

package/src/Trustchex.tsx

@@ -30,6 +30,7 @@ import NFCScanTestScreen from './Screens/Debug/NFCScanTestScreen';
 import AppContext, { type AppContextType } from './Shared/Contexts/AppContext';
 import type { DocumentReadResult } from './Shared/Types/documentReadResult';
 import DebugNavigationPanel from './Shared/Components/DebugNavigationPanel';
+import ErrorBoundary from './Shared/Components/ErrorBoundary';
 import i18n from './Translation';
 import { initializeTTS } from './Shared/Libs/tts.utils';
 import { analyticsService } from './Shared/Services/AnalyticsService';
@@ -102,7 +103,9 @@ const Trustchex: React.FC<TrustchexProps> = ({
   const [isInitialized, setIsInitialized] = useState(false);
   const [analyticsInitialized, setAnalyticsInitialized] = useState(false);
   const [isDemoSession, setIsDemoSession] = useState(false);
-  const [lastDocumentRead, setLastDocumentReadState] = useState<DocumentReadResult | undefined>(undefined);
+  const [lastDocumentRead, setLastDocumentReadState] = useState<
+    DocumentReadResult | undefined
+  >(undefined);
 
   const branding = useMemo(
     () => ({
@@ -278,64 +281,66 @@ const Trustchex: React.FC<TrustchexProps> = ({
         tertiaryColor={branding.tertiaryColor}
       >
         <AppContext.Provider value={contextValue}>
-          <NavigationContainer>
-            <Stack.Navigator
-              id={undefined}
-              initialRouteName="VerificationSessionCheckScreen"
-              screenOptions={{
-                headerShown: false,
-                headerBackButtonMenuEnabled: false,
-              }}
-            >
-              <Stack.Screen
-                name="VerificationSessionCheckScreen"
-                component={VerificationSessionCheckScreen}
-              />
-              <Stack.Screen
-                name="OTPVerificationScreen"
-                component={OTPVerificationScreen}
-              />
-              <Stack.Screen
-                name="ContractAcceptanceScreen"
-                component={ContractAcceptanceScreen}
-              />
-              <Stack.Screen
-                name="IdentityDocumentScanningScreen"
-                component={IdentityDocumentScanningScreen}
-              />
-              <Stack.Screen
-                name="IdentityDocumentEIDScanningScreen"
-                component={IdentityDocumentEIDScanningScreen}
-              />
-              <Stack.Screen
-                name="LivenessDetectionScreen"
-                component={LivenessDetectionScreen}
-              />
-              <Stack.Screen name="ResultScreen" component={ResultScreen} />
-              <Stack.Screen
-                name="QrCodeScanningScreen"
-                component={QrCodeScanningScreen}
-              />
-              <Stack.Screen
-                name="VideoCallScreen"
-                component={VideoCallScreen}
-              />
-              <Stack.Screen
-                name="VerbalConsentScreen"
-                component={VerbalConsentScreen}
-              />
-              <Stack.Screen name="MRZTestScreen" component={MRZTestScreen} />
-              <Stack.Screen
-                name="BarcodeTestScreen"
-                component={BarcodeTestScreen}
-              />
-              <Stack.Screen
-                name="NFCScanTestScreen"
-                component={NFCScanTestScreen}
-              />
-            </Stack.Navigator>
-            <DebugNavigationPanel />
-          </NavigationContainer>
+          <ErrorBoundary>
+            <NavigationContainer>
+              <Stack.Navigator
+                id={undefined}
+                initialRouteName="VerificationSessionCheckScreen"
+                screenOptions={{
+                  headerShown: false,
+                  headerBackButtonMenuEnabled: false,
+                }}
+              >
+                <Stack.Screen
+                  name="VerificationSessionCheckScreen"
+                  component={VerificationSessionCheckScreen}
+                />
+                <Stack.Screen
+                  name="OTPVerificationScreen"
+                  component={OTPVerificationScreen}
+                />
+                <Stack.Screen
+                  name="ContractAcceptanceScreen"
+                  component={ContractAcceptanceScreen}
+                />
+                <Stack.Screen
+                  name="IdentityDocumentScanningScreen"
+                  component={IdentityDocumentScanningScreen}
+                />
+                <Stack.Screen
+                  name="IdentityDocumentEIDScanningScreen"
+                  component={IdentityDocumentEIDScanningScreen}
+                />
+                <Stack.Screen
+                  name="LivenessDetectionScreen"
+                  component={LivenessDetectionScreen}
+                />
+                <Stack.Screen name="ResultScreen" component={ResultScreen} />
+                <Stack.Screen
+                  name="QrCodeScanningScreen"
+                  component={QrCodeScanningScreen}
+                />
+                <Stack.Screen
+                  name="VideoCallScreen"
+                  component={VideoCallScreen}
+                />
+                <Stack.Screen
+                  name="VerbalConsentScreen"
+                  component={VerbalConsentScreen}
+                />
+                <Stack.Screen name="MRZTestScreen" component={MRZTestScreen} />
+                <Stack.Screen
+                  name="BarcodeTestScreen"
+                  component={BarcodeTestScreen}
+                />
+                <Stack.Screen
+                  name="NFCScanTestScreen"
+                  component={NFCScanTestScreen}
+                />
+              </Stack.Navigator>
+              <DebugNavigationPanel />
+            </NavigationContainer>
+          </ErrorBoundary>
         </AppContext.Provider>
       </ThemeProvider>
     </SafeAreaProvider>

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated. Do not edit manually.
 // Version is synced from package.json during build.
-export const SDK_VERSION = '1.497.0';
+export const SDK_VERSION = '1.500.2';