@trustchex/react-native-sdk 1.478.7 → 1.483.4

package/src/Shared/Libs/native-device-info.utils.ts

@@ -1,6 +1,122 @@
 import { Platform } from 'react-native';
 import DeviceInfo from 'react-native-device-info';
 
+/**
+ * Full, non-PII device details for the support diagnostic report. Device-
+ * specific scanning/NFC issues correlate with hardware, OS level, memory and
+ * NFC capability, so we capture a broad-but-safe set. Excludes anything that
+ * identifies a person (uniqueId is a per-install vendor id, not PII, and is kept
+ * only for correlating repeat reports from the same device).
+ */
+export interface DeviceDetails {
+  platform: string; // 'ios' | 'android'
+  systemName: string; // 'iOS' | 'Android'
+  systemVersion: string;
+  apiLevel?: number; // Android API level
+  brand: string;
+  manufacturer: string;
+  model: string;
+  deviceId: string; // hardware model code, e.g. "iPhone16,1" / "tegu"
+  deviceType: string; // Handset / Tablet / …
+  isTablet: boolean;
+  isEmulator: boolean;
+  hasNotch: boolean;
+  totalMemoryMB?: number;
+  usedMemoryMB?: number;
+  totalDiskMB?: number;
+  freeDiskMB?: number;
+  batteryLevel?: number; // 0..1
+  appVersion: string;
+  buildNumber: string;
+  bundleId: string;
+  fontScale?: number;
+  installerPackage?: string;
+}
+
+/** Resolve an async getter to a number, tolerating failure. */
+const num = async (p: Promise<number>): Promise<number | undefined> => {
+  try {
+    const v = await p;
+    return typeof v === 'number' && isFinite(v) ? v : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Resolve an async getter, falling back on failure. */
+const safe = async <T>(p: Promise<T>, fallback: T): Promise<T> => {
+  try {
+    return await p;
+  } catch {
+    return fallback;
+  }
+};
+
+/** Read a synchronous getter, tolerating failure. */
+const sync = <T>(fn: () => T, fallback: T): T => {
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+};
+
+/** Gather the full non-PII device profile for a diagnostic report. */
+export const gatherDeviceDetails = async (): Promise<DeviceDetails> => {
+  const bytesToMB = (b?: number) =>
+    b === undefined ? undefined : Math.round(b / (1024 * 1024));
+  const isAndroid = Platform.OS === 'android';
+
+  const [
+    manufacturer,
+    isEmulator,
+    apiLevel,
+    installerPackage,
+    totalMemory,
+    usedMemory,
+    totalDisk,
+    freeDisk,
+    batteryLevel,
+    fontScale,
+  ] = await Promise.all([
+    safe(DeviceInfo.getManufacturer(), 'unknown'),
+    safe(DeviceInfo.isEmulator(), false),
+    isAndroid ? num(DeviceInfo.getApiLevel()) : Promise.resolve(undefined),
+    safe(DeviceInfo.getInstallerPackageName(), 'unknown'),
+    num(DeviceInfo.getTotalMemory()),
+    num(DeviceInfo.getUsedMemory()),
+    num(DeviceInfo.getTotalDiskCapacity()),
+    num(DeviceInfo.getFreeDiskStorage()),
+    num(DeviceInfo.getBatteryLevel()),
+    num(DeviceInfo.getFontScale()),
+  ]);
+
+  return {
+    platform: Platform.OS,
+    systemName: isAndroid ? 'Android' : 'iOS',
+    systemVersion: sync(() => DeviceInfo.getSystemVersion(), 'unknown'),
+    apiLevel,
+    brand: sync(() => DeviceInfo.getBrand(), 'unknown'),
+    manufacturer,
+    model: sync(() => DeviceInfo.getModel(), 'unknown'),
+    deviceId: sync(() => DeviceInfo.getDeviceId(), 'unknown'),
+    deviceType: sync(() => DeviceInfo.getDeviceType(), 'unknown'),
+    isTablet: sync(() => DeviceInfo.isTablet(), false),
+    isEmulator,
+    hasNotch: sync(() => DeviceInfo.hasNotch(), false),
+    totalMemoryMB: bytesToMB(totalMemory),
+    usedMemoryMB: bytesToMB(usedMemory),
+    totalDiskMB: bytesToMB(totalDisk),
+    freeDiskMB: bytesToMB(freeDisk),
+    batteryLevel,
+    appVersion: sync(() => DeviceInfo.getVersion(), 'unknown'),
+    buildNumber: sync(() => DeviceInfo.getBuildNumber(), 'unknown'),
+    bundleId: sync(() => DeviceInfo.getBundleId(), 'unknown'),
+    fontScale,
+    installerPackage,
+  };
+};
+
 export const NativeDeviceInfo = {
   generateHumanReadableIdentifier: async (): Promise<string> => {
     try {

package/src/Shared/Libs/sendDiagnosticReport.ts

@@ -0,0 +1,165 @@
+/**
+ * Assembles and shares the support diagnostic report.
+ *
+ * `react-native-share` is an OPTIONAL dependency: the host app opts into the
+ * diagnostic feature by installing it. When it's present we open the OS share
+ * sheet with the full report (the user picks email / WhatsApp / Drive / etc. and
+ * reviews before sending); when it's absent the feature is silently unavailable
+ * — `isDiagnosticSharingAvailable()` returns false and the result-screen button
+ * renders nothing, so apps that don't want it incur no dependency.
+ *
+ * Attached files (staged to a temp dir via react-native-fs, already an SDK dep):
+ *  - `diagnostics.json` — technical signals (device, camera, MRZ, NFC steps),
+ *  - `scan-data.json`   — the scanned identity data (PII; user reviews it),
+ *  - the captured document/face images.
+ *
+ * The readable summary rides as the share `message` so it's visible in the
+ * draft regardless of the chosen app.
+ */
+import RNFS from 'react-native-fs';
+import { diagnostics } from './diagnostics';
+import { gatherDeviceDetails } from './native-device-info.utils';
+import {
+  buildDiagnosticReport,
+  type ScanDataForReport,
+} from './diagnosticReport';
+import { logError } from './debug.utils';
+
+// `react-native-share` is OPTIONAL. Load it softly so the SDK bundles and runs
+// without it; only host apps that installed it get the diagnostic feature. A
+// static `import` would make Metro fail to resolve the module when it's absent,
+// so we use a guarded require and keep the reference typed loosely.
+type ShareModule = {
+  open: (options: Record<string, unknown>) => Promise<unknown>;
+};
+
+let shareModule: ShareModule | null | undefined;
+
+const loadShare = (): ShareModule | null => {
+  if (shareModule !== undefined) return shareModule;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const mod = require('react-native-share');
+    shareModule = (mod?.default ?? mod) as ShareModule;
+  } catch {
+    shareModule = null; // not installed — feature unavailable
+  }
+  return shareModule;
+};
+
+/**
+ * Whether diagnostic sharing is available (i.e. `react-native-share` is
+ * installed in the host app). The result-screen button hides itself when false.
+ */
+export const isDiagnosticSharingAvailable = (): boolean => loadShare() != null;
+
+export interface DiagnosticImage {
+  /** Stable file name without extension, e.g. "mrz-side". */
+  name: string;
+  base64: string;
+  mime: 'jpg' | 'png';
+}
+
+export interface SendDiagnosticParams {
+  scan: ScanDataForReport;
+  sdkVersion: string;
+  sessionId?: string;
+  /** base64 images to attach (MRZ side / front / face / NFC chip face). */
+  images?: DiagnosticImage[];
+}
+
+
+const writeTemp = async (
+  dir: string,
+  name: string,
+  data: string,
+  encoding: 'utf8' | 'base64'
+): Promise<string> => {
+  const path = `${dir}/${name}`;
+  await RNFS.writeFile(path, data, encoding);
+  return path.startsWith('file://') ? path : `file://${path}`;
+};
+
+export interface SendResult {
+  shared: boolean;
+  /** True when the user dismissed the share sheet (not an error). */
+  dismissed?: boolean;
+}
+
+/**
+ * Build the report, stage attachments, and present the share sheet. Returns
+ * { shared } — false on error, with `dismissed` set when the user cancelled.
+ */
+export const sendDiagnosticReport = async (
+  params: SendDiagnosticParams
+): Promise<SendResult> => {
+  const share = loadShare();
+  if (!share) {
+    // Optional dependency not installed — nothing to do.
+    return { shared: false };
+  }
+  const { scan, sdkVersion, sessionId, images = [] } = params;
+  const now = Date.now();
+  const iso = new Date(now).toISOString();
+
+  const device = await gatherDeviceDetails();
+  const report = buildDiagnosticReport({
+    diag: diagnostics.snapshot(now, iso),
+    device,
+    scan,
+    sdkVersion,
+    sessionId,
+  });
+
+  const dir = `${RNFS.TemporaryDirectoryPath}/trustchex-diagnostics-${now}`;
+  try {
+    await RNFS.mkdir(dir);
+    const urls: string[] = [];
+    urls.push(
+      await writeTemp(dir, 'diagnostics.json', report.diagnosticsJson, 'utf8')
+    );
+    urls.push(
+      await writeTemp(dir, 'scan-data.json', report.scanDataJson, 'utf8')
+    );
+    for (const img of images) {
+      if (!img.base64) continue;
+      urls.push(
+        await writeTemp(dir, `${img.name}.${img.mime}`, img.base64, 'base64')
+      );
+    }
+
+    try {
+      await share.open({
+        title: report.subject,
+        subject: report.subject, // used by email targets
+        message: report.body,
+        urls,
+        // Per-file MIME types so targets render attachments correctly.
+        filenames: urls.map((u) => u.split('/').pop() ?? 'attachment'),
+        failOnCancel: false,
+      });
+      return { shared: true };
+    } catch (shareErr) {
+      // react-native-share throws on user cancel unless failOnCancel:false; treat
+      // a cancel as a non-error dismissal.
+      const msg =
+        shareErr instanceof Error ? shareErr.message : String(shareErr);
+      if (/cancel|dismiss|user did not share/i.test(msg)) {
+        return { shared: false, dismissed: true };
+      }
+      throw shareErr;
+    }
+  } catch (e) {
+    logError(
+      'Diagnostics',
+      'Failed to share diagnostic report',
+      e instanceof Error ? e.message : String(e)
+    );
+    return { shared: false };
+  } finally {
+    // Best-effort cleanup — temp files are short-lived.
+    setTimeout(() => {
+      RNFS.unlink(dir).catch(() => {});
+    }, 60_000);
+  }
+};

package/src/Shared/Services/DataUploadService.ts

@@ -5,6 +5,7 @@ import type {
   ScannedIdentityDocument,
   LivenessDetection,
 } from '../Types/identificationInfo';
+import type { DocumentName } from '../Types/documentReadResult';
 import { getSessionKey, encryptWithAes } from '../Libs/crypto.utils';
 import mrzUtils from '../Libs/mrz.utils';
 import httpClient, { getSessionToken } from '../Libs/http-client';
@@ -46,7 +47,8 @@ export class DataUploadService {
   async submitDocumentData(
     identificationId: string,
     scannedDocument: ScannedIdentityDocument,
-    sessionKey: string
+    sessionKey: string,
+    documentName?: DocumentName
   ): Promise<void> {
     if (!scannedDocument || scannedDocument.documentType === 'UNKNOWN') {
       debugLog('DataUploadService', 'No document data to submit');
@@ -63,6 +65,9 @@ export class DataUploadService {
       type: mrzFields.documentCode,
       name: mrzFields.firstName,
       surname: mrzFields.lastName,
+      displayName: documentName?.source === 'dg11' ? documentName.displayFirst : undefined,
+      displaySurname: documentName?.source === 'dg11' ? documentName.displayLast : undefined,
+      nameSource: documentName?.source === 'dg11' ? documentName.source : undefined,
       gender: this.getGenderEnumType(mrzFields.sex),
       number: mrzFields.documentNumber,
       country: mrzFields.issuingState,
@@ -270,7 +275,8 @@ export class DataUploadService {
    */
   async uploadCollectedData(
     identificationInfo: IdentificationInfo,
-    onProgress?: (progress: number) => void
+    onProgress?: (progress: number) => void,
+    documentName?: DocumentName
   ): Promise<boolean> {
     const { identificationId, sessionId, scannedDocument, livenessDetection } =
       identificationInfo;
@@ -329,7 +335,7 @@ export class DataUploadService {
       if (scannedDocument) {
         onProgress?.(0.1);
         await runWithRetry(() =>
-          this.submitDocumentData(identificationId, scannedDocument, authToken)
+          this.submitDocumentData(identificationId, scannedDocument, authToken, documentName)
         );
         onProgress?.(0.3);
       }

package/src/Shared/Types/documentData.ts

@@ -0,0 +1,52 @@
+/**
+ * Unified, source-independent document data produced after a scan — whether
+ * the data came from an NFC chip read or camera OCR. All fields are normalized
+ * to consistent formats regardless of which path produced them.
+ */
+export interface DocumentData {
+  /**
+   * Document type.
+   * - `"P"`  — passport (TD3)
+   * - `"I"`  — ID card (TD1 / TD2)
+   */
+  documentType: 'P' | 'I' | string;
+
+  /** 3-letter ICAO issuing country code, e.g. `"TUR"`, `"DEU"`. */
+  issuingCountry: string;
+
+  /** 3-letter ICAO nationality code, e.g. `"TUR"`. */
+  nationality: string;
+
+  /** Document serial / number exactly as encoded on the document. */
+  documentNumber: string;
+
+  /** National identity number where applicable (e.g. Turkish TC kimlik no). Null if not present. */
+  personalNumber: string | null;
+
+  /** Last name — raw MRZ ASCII (OCR-B), e.g. `"OEZTUERK"`. */
+  lastName: string;
+
+  /** First name(s) — raw MRZ ASCII (OCR-B), e.g. `"GOEKHAN MEHMET"`. */
+  firstName: string;
+
+  /**
+   * Sex / gender.
+   * - `"M"` — male
+   * - `"F"` — female
+   * - `"X"` — unspecified / non-binary
+   * - `"U"` — unknown (not encoded on document)
+   */
+  sex: 'M' | 'F' | 'X' | 'U';
+
+  /**
+   * Date of birth in `YYYY-MM-DD` format, e.g. `"1985-01-15"`.
+   * Null if the document does not encode it.
+   */
+  dateOfBirth: string | null;
+
+  /**
+   * Document expiry date in `YYYY-MM-DD` format, e.g. `"2030-12-31"`.
+   * Null if the document does not encode it.
+   */
+  dateOfExpiry: string | null;
+}

package/src/Shared/Types/documentReadResult.ts

@@ -0,0 +1,47 @@
+import type { DocumentData } from './documentData';
+
+/**
+ * How the display name was derived from the raw MRZ ASCII name.
+ *
+ * - `dg11`          — read from the chip's DG11 supplemental data file (exact printed name)
+ * - `reverse_table` — reconstructed via country-aware ICAO 9303 reverse transliteration table
+ * - `raw`           — no conversion applied; display equals the raw MRZ value
+ */
+export type DocumentNameSource = 'dg11' | 'reverse_table' | 'raw';
+
+export interface DocumentName {
+  /** First name exactly as stored in the MRZ (ASCII, OCR-B, e.g. "GOEKHAN"). */
+  rawFirst: string;
+  /** Last name exactly as stored in the MRZ (ASCII, OCR-B, e.g. "OEZTUERK"). */
+  rawLast: string;
+  /** First name in best available Unicode form (e.g. "GÖKHAN"). */
+  displayFirst: string;
+  /** Last name in best available Unicode form (e.g. "ÖZTÜRK"). */
+  displayLast: string;
+  /** How displayFirst / displayLast were derived. */
+  source: DocumentNameSource;
+}
+
+export interface DocumentFaceImage {
+  /** Base64-encoded image data (no data-URI prefix). */
+  data: string;
+  /** MIME type, e.g. "image/jpeg" or "image/png". */
+  mimeType: string;
+}
+
+export interface DocumentReadResult {
+  /** Normalized document data — consistent shape regardless of NFC or OCR source. */
+  document: DocumentData;
+  /**
+   * Name in both raw MRZ ASCII form and best-available Unicode display form.
+   * rawFirst / rawLast mirror document.firstName / document.lastName.
+   * displayFirst / displayLast are the Unicode-converted equivalents.
+   */
+  name: DocumentName;
+  /**
+   * Face image — from the chip's DG2 file on the NFC path, or extracted from
+   * the document photo on the camera OCR path. Optional: only present when a
+   * face image was successfully obtained.
+   */
+  face?: DocumentFaceImage;
+}

package/src/Shared/Types/mrzFields.ts

@@ -7,18 +7,13 @@ export type MRZFieldName =
   | 'documentCode'
   | 'issuingState'
   | 'documentNumber'
-  | 'documentNumberCheckDigit'
   | 'nationality'
   | 'lastName'
   | 'firstName'
   | 'sex'
   | 'birthDate'
-  | 'birthDateCheckDigit'
   | 'expirationDate'
-  | 'expirationDateCheckDigit'
   | 'personalNumber'
-  | 'personalNumberCheckDigit'
-  | 'compositeCheckDigit'
   | 'optional1'
   | 'optional2';
 

package/src/Translation/Resources/en.ts

@@ -53,6 +53,12 @@ export default {
   'resultScreen.demoVerbalConsentTitle': 'Title',
   'resultScreen.demoVerbalConsentText': 'Text',
   'resultScreen.demoStartOver': 'Start Over',
+  'diagnosticReport.button': 'Report a scanning issue',
+  'diagnosticReport.noticeTitle': 'Share diagnostic report',
+  'diagnosticReport.noticeBody':
+    'This opens a draft with your scan data, document images and technical details so support can help resolve a scanning issue. Review it before sending.',
+  'diagnosticReport.continue': 'Continue',
+  'diagnosticReport.cancel': 'Cancel',
   'livenessDetectionScreen.guideHeader': 'Face Verification',
   'livenessDetectionScreen.guideText':
     'Please ensure the following for best results:',

package/src/Translation/Resources/tr.ts

@@ -53,6 +53,12 @@ export default {
   'resultScreen.demoVerbalConsentTitle': 'Başlık',
   'resultScreen.demoVerbalConsentText': 'Metin',
   'resultScreen.demoStartOver': 'Baştan Başla',
+  'diagnosticReport.button': 'Tarama sorununu bildir',
+  'diagnosticReport.noticeTitle': 'Tanılama raporu paylaş',
+  'diagnosticReport.noticeBody':
+    'Bu işlem; tarama verilerinizi, belge görüntülerinizi ve teknik ayrıntıları içeren bir taslak açar; böylece destek ekibi tarama sorununu çözebilir. Göndermeden önce gözden geçirin.',
+  'diagnosticReport.continue': 'Devam et',
+  'diagnosticReport.cancel': 'İptal',
   'livenessDetectionScreen.guideHeader': 'Yüz Doğrulaması',
   'livenessDetectionScreen.guideText':
     'En iyi sonuç için lütfen şunları sağlayın:',

package/src/Trustchex.tsx

@@ -1,4 +1,10 @@
-import React, { useEffect, useState, useMemo, useRef } from 'react';
+import React, {
+  useEffect,
+  useState,
+  useMemo,
+  useRef,
+  useCallback,
+} from 'react';
 import { NavigationContainer } from '@react-navigation/native';
 import { createNativeStackNavigator } from '@react-navigation/native-stack';
 import { View, ActivityIndicator, StyleSheet } from 'react-native';
@@ -22,6 +28,7 @@ import MRZTestScreen from './Screens/Debug/MRZTestScreen';
 import BarcodeTestScreen from './Screens/Debug/BarcodeTestScreen';
 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 i18n from './Translation';
 import { initializeTTS } from './Shared/Libs/tts.utils';
@@ -49,6 +56,14 @@ interface TrustchexProps {
   locale?: 'en' | 'tr';
   onCompleted?: () => void;
   onError?: (error: string) => void;
+  /**
+   * Called as soon as document data is available — immediately after a
+   * successful NFC chip read (before the user taps "Approve and Continue")
+   * or after a successful camera OCR scan. Receives MRZ fields (raw,
+   * untouched ASCII), a name object with both raw and best-available Unicode
+   * display form, and optionally the face image.
+   */
+  onDocumentRead?: (result: DocumentReadResult) => void;
   enableAnalytics?: boolean;
   debug?: boolean;
   logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
@@ -68,6 +83,7 @@ const Trustchex: React.FC<TrustchexProps> = ({
   locale: propLocale,
   onCompleted,
   onError,
+  onDocumentRead,
   enableAnalytics = true,
   debug = false,
   logLevel = 'trace',
@@ -80,6 +96,7 @@ 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 branding = useMemo(
     () => ({
@@ -96,11 +113,34 @@ const Trustchex: React.FC<TrustchexProps> = ({
   // discarding those mutations and causing screens to see undefined values.
   const contextRef = useRef<AppContextType | null>(null);
 
+  // Wrap the demo-session setter so it ALSO mutates the persistent context
+  // object synchronously. The React state update is async, but the verification
+  // flow navigates to the next step in the same tick and advances thereafter by
+  // direct mutation (never re-rendering Trustchex). If isDemoSession lived only
+  // as a state-derived memo field, downstream screens (e.g. ResultScreen, which
+  // gates the diagnostics button on it) could read a stale `false`. Mutating the
+  // ref makes the flag travel with the object every screen holds.
+  const setIsDemoSessionAndPersist = useCallback((value: boolean) => {
+    if (contextRef.current) {
+      contextRef.current.isDemoSession = value;
+    }
+    setIsDemoSession(value);
+  }, []);
+
+  const setLastDocumentRead = useCallback((result: DocumentReadResult) => {
+    if (contextRef.current) {
+      contextRef.current.lastDocumentRead = result;
+    }
+    setLastDocumentReadState(result);
+  }, []);
+
   const contextValue = useMemo(() => {
     const prev = contextRef.current;
 
     const value: AppContextType = {
-      isDemoSession,
+      // Prefer a direct mutation carried on the persistent object over the
+      // (possibly not-yet-flushed) state, so the demo flag can't desync.
+      isDemoSession: prev?.isDemoSession || isDemoSession,
       baseUrl: baseUrl || '',
       locale,
       branding,
@@ -120,11 +160,14 @@ const Trustchex: React.FC<TrustchexProps> = ({
       currentWorkflowStep: prev?.currentWorkflowStep,
       isDebugNavigated: prev?.isDebugNavigated,
       isTestVideoSession: prev?.isTestVideoSession,
+      lastDocumentRead,
       onCompleted,
       onError,
+      onDocumentRead,
+      setLastDocumentRead,
       setSessionId,
       setBaseUrl,
-      setIsDemoSession,
+      setIsDemoSession: setIsDemoSessionAndPersist,
     };
 
     // Update state-derived identificationInfo fields without replacing
@@ -146,6 +189,8 @@ const Trustchex: React.FC<TrustchexProps> = ({
     onCompleted,
     onError,
     isDemoSession,
+    lastDocumentRead,
+    setIsDemoSessionAndPersist,
   ]);
 
   // Initialize analytics when SDK mounts with valid session

package/src/index.tsx

@@ -51,5 +51,12 @@ export type {
 export { default as mrzUtils } from './Shared/Libs/mrz.utils';
 export type { MRZFormat, MRZValidationResult } from './Shared/Libs/mrz.utils';
 export type { MRZFields, MRZFieldName } from './Shared/Types/mrzFields';
+export type { DocumentData } from './Shared/Types/documentData';
+export type {
+  DocumentReadResult,
+  DocumentName,
+  DocumentNameSource,
+  DocumentFaceImage,
+} from './Shared/Types/documentReadResult';
 
 export default Trustchex;

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.478.7';
+export const SDK_VERSION = '1.483.4';