@trustchex/react-native-sdk 1.481.1 → 1.484.0

package/src/Shared/Libs/mrzTransliteration.ts

@@ -0,0 +1,131 @@
+import type { DocumentName } from '../Types/documentReadResult';
+
+type DigraphMap = [string, string][];
+
+// ICAO 9303 digraphs safe to apply universally — these appear across many
+// national variants and are unlikely to collide with real letter sequences.
+// SS→ß, TH→Þ etc. are excluded: too ambiguous (HASSAN, THOMAS).
+const UNIVERSAL: DigraphMap = [
+  ['OE', 'Ö'],
+  ['UE', 'Ü'],
+];
+
+const GERMAN: DigraphMap = [
+  ['AE', 'Ä'],
+  ['OE', 'Ö'],
+  ['UE', 'Ü'],
+  ['SS', 'ß'],
+];
+
+const SWEDISH: DigraphMap = [
+  ['AA', 'Å'],
+  ['AE', 'Æ'],
+  ['OE', 'Ø'],
+];
+
+const DANISH: DigraphMap = [
+  ['AA', 'Å'],
+  ['AE', 'Æ'],
+  ['OE', 'Ø'],
+];
+
+const NORWEGIAN: DigraphMap = [
+  ['AA', 'Å'],
+  ['AE', 'Æ'],
+  ['OE', 'Ø'],
+];
+
+const FRENCH: DigraphMap = [
+  ['OE', 'Œ'],
+  ['AE', 'Æ'],
+];
+
+const ICELANDIC: DigraphMap = [
+  ['AE', 'Æ'],
+  ['OE', 'Ö'],
+  ['TH', 'Þ'],
+  ['D', 'Ð'],
+];
+
+const COUNTRY_MAP: Record<string, DigraphMap> = {
+  DEU: GERMAN,
+  AUT: GERMAN,
+  CHE: GERMAN,
+  SWE: SWEDISH,
+  DNK: DANISH,
+  NOR: NORWEGIAN,
+  FRA: FRENCH,
+  LUX: FRENCH,
+  ISL: ICELANDIC,
+};
+
+function applyDigraphMap(token: string, map: DigraphMap): string {
+  let result = '';
+  let i = 0;
+  while (i < token.length) {
+    let matched = false;
+    for (const [digraph, unicode] of map) {
+      if (token.startsWith(digraph, i)) {
+        result += unicode;
+        i += digraph.length;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      result += token[i];
+      i++;
+    }
+  }
+  return result;
+}
+
+function convertName(rawName: string, map: DigraphMap): string {
+  return rawName
+    .split(' ')
+    .map((word) => applyDigraphMap(word, map))
+    .join(' ');
+}
+
+export function buildDocumentName(
+  rawFirst: string,
+  rawLast: string,
+  issuingState: string | null | undefined,
+  dg11First?: string | null,
+  dg11Last?: string | null
+): DocumentName {
+  if (dg11First != null && dg11Last != null && (dg11First || dg11Last)) {
+    return {
+      rawFirst,
+      rawLast,
+      displayFirst: dg11First,
+      displayLast: dg11Last,
+      source: 'dg11',
+    };
+  }
+
+  const country = (issuingState ?? '').toUpperCase().trim();
+  const map = COUNTRY_MAP[country];
+
+  if (map) {
+    return {
+      rawFirst,
+      rawLast,
+      displayFirst: convertName(rawFirst, map),
+      displayLast: convertName(rawLast, map),
+      source: 'reverse_table',
+    };
+  }
+
+  // No country-specific table: apply OE→Ö and UE→Ü universally.
+  const displayFirst = convertName(rawFirst, UNIVERSAL);
+  const displayLast = convertName(rawLast, UNIVERSAL);
+  const changed = displayFirst !== rawFirst || displayLast !== rawLast;
+  return {
+    rawFirst,
+    rawLast,
+    displayFirst,
+    displayLast,
+    source: changed ? 'reverse_table' : 'raw',
+  };
+}

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/Trustchex.tsx

@@ -28,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';
@@ -55,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';
@@ -74,6 +83,7 @@ const Trustchex: React.FC<TrustchexProps> = ({
   locale: propLocale,
   onCompleted,
   onError,
+  onDocumentRead,
   enableAnalytics = true,
   debug = false,
   logLevel = 'trace',
@@ -86,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(
     () => ({
@@ -116,6 +127,13 @@ const Trustchex: React.FC<TrustchexProps> = ({
     setIsDemoSession(value);
   }, []);
 
+  const setLastDocumentRead = useCallback((result: DocumentReadResult) => {
+    if (contextRef.current) {
+      contextRef.current.lastDocumentRead = result;
+    }
+    setLastDocumentReadState(result);
+  }, []);
+
   const contextValue = useMemo(() => {
     const prev = contextRef.current;
 
@@ -142,8 +160,11 @@ const Trustchex: React.FC<TrustchexProps> = ({
       currentWorkflowStep: prev?.currentWorkflowStep,
       isDebugNavigated: prev?.isDebugNavigated,
       isTestVideoSession: prev?.isTestVideoSession,
+      lastDocumentRead,
       onCompleted,
       onError,
+      onDocumentRead,
+      setLastDocumentRead,
       setSessionId,
       setBaseUrl,
       setIsDemoSession: setIsDemoSessionAndPersist,
@@ -168,6 +189,7 @@ const Trustchex: React.FC<TrustchexProps> = ({
     onCompleted,
     onError,
     isDemoSession,
+    lastDocumentRead,
     setIsDemoSessionAndPersist,
   ]);
 

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