@trustchex/react-native-sdk 1.481.1 → 1.483.4

package/src/Shared/Components/EIDScanner.tsx

@@ -9,6 +9,8 @@ import { MRZInfo } from '../EIDReader/lds/icao/mrzInfo';
 import { eidReader } from '../EIDReader/eidReader';
 import NativeProgressBar from './NativeProgressBar';
 import type { MRZFields } from '../Types/mrzFields';
+import { buildDocumentName } from '../Libs/mrzTransliteration';
+import { normalizeFromMRZInfo } from '../Libs/documentDataNormalizer';
 import { useTranslation } from 'react-i18next';
 import AppContext from '../Contexts/AppContext';
 import StyledButton from './StyledButton';
@@ -52,6 +54,7 @@ const EIDScanner = ({
   const [documentMRZInfo, setDocumentMRZInfo] = React.useState<MRZInfo>();
   const [documentFaceImageMimeType, setDocumentFaceImageMimeType] =
     React.useState<string>();
+  const [documentName, setDocumentName] = React.useState<import('../Types/documentReadResult').DocumentName>();
   const [progress, setProgress] = React.useState(0);
   const [progressStage, setProgressStage] = React.useState<string>('');
 
@@ -133,6 +136,21 @@ const EIDScanner = ({
   const [voiceGuidanceMessage, setVoiceGuidanceMessage] = useState<string>();
   const [attemptNumber, setAttemptNumber] = useState<number>(0);
 
+  const getFieldsFromMRZ = useCallback((mrz: MRZInfo) => {
+    return {
+      documentCode: mrz.getDocumentCode(),
+      personalNumber: mrz.getPersonalNumber() || mrz.getOptionalData1(),
+      documentNumber: mrz.getDocumentNumber(),
+      firstName: mrz.getSecondaryIdentifier(),
+      lastName: mrz.getPrimaryIdentifier(),
+      birthDate: mrz.getDateOfBirth(),
+      expirationDate: mrz.getDateOfExpiry(),
+      issuingState: mrz.getIssuingState(),
+      sex: mrz.getGender().getStrCode(),
+      nationality: mrz.getNationality(),
+    } satisfies MRZFields;
+  }, []);
+
   const readNFC = useCallback(async () => {
     const startTime = Date.now();
     const currentAttempt = attemptNumber + 1;
@@ -228,6 +246,32 @@ const EIDScanner = ({
           setDocumentMRZInfo(passportData.mrz);
           setDocumentFaceImageMimeType(passportData.mimeType);
           setIsScanned(true);
+
+          {
+            const documentData = normalizeFromMRZInfo(passportData.mrz);
+            const builtName = buildDocumentName(
+              documentData.firstName,
+              documentData.lastName,
+              documentData.issuingCountry,
+              passportData.dg11FirstName,
+              passportData.dg11LastName
+            );
+            setDocumentName(builtName);
+            const documentReadResult = {
+              document: {
+                ...documentData,
+                firstName: builtName.displayFirst,
+                lastName: builtName.displayLast,
+              },
+              name: builtName,
+              face: {
+                data: passportData.faceImage,
+                mimeType: passportData.mimeType,
+              },
+            };
+            appContext.setLastDocumentRead?.(documentReadResult);
+            appContext.onDocumentRead?.(documentReadResult);
+          }
           await trackEIDScanComplete(
             docType,
             scanDuration,
@@ -314,23 +358,10 @@ const EIDScanner = ({
     isEnabled,
     attemptNumber,
     t,
+    getFieldsFromMRZ,
+    appContext,
   ]);
 
-  const getFieldsFromMRZ = useCallback((mrz: MRZInfo) => {
-    return {
-      documentCode: mrz.getDocumentCode(),
-      personalNumber: mrz.getPersonalNumber() || mrz.getOptionalData1(),
-      documentNumber: mrz.getDocumentNumber(),
-      firstName: mrz.getSecondaryIdentifier(),
-      lastName: mrz.getPrimaryIdentifier(),
-      birthDate: mrz.getDateOfBirth(),
-      expirationDate: mrz.getDateOfExpiry(),
-      issuingState: mrz.getIssuingState(),
-      sex: mrz.getGender().getStrCode(),
-      nationality: mrz.getNationality(),
-    } satisfies MRZFields;
-  }, []);
-
   useEffect(() => {
     const checkIsSupported = async () => {
       const deviceIsSupported = await NFCManager.isSupported();
@@ -533,11 +564,13 @@ const EIDScanner = ({
                   <View style={styles.idCardFields}>
                     <IDCardField
                       label={t('eidScannerScreen.surname')}
-                      value={documentMRZInfo.getPrimaryIdentifier()}
+                      value={documentName?.displayLast ?? documentMRZInfo.getPrimaryIdentifier()}
+                      subValue={documentName?.source === 'dg11' ? documentMRZInfo.getPrimaryIdentifier() : undefined}
                     />
                     <IDCardField
                       label={t('eidScannerScreen.name')}
-                      value={documentMRZInfo.getSecondaryIdentifier()}
+                      value={documentName?.displayFirst ?? documentMRZInfo.getSecondaryIdentifier()}
+                      subValue={documentName?.source === 'dg11' ? documentMRZInfo.getSecondaryIdentifier() : undefined}
                     />
                     <IDCardField
                       label={t('eidScannerScreen.documentNumber')}
@@ -866,6 +899,11 @@ const styles = StyleSheet.create({
     flexShrink: 1,
     flexWrap: 'wrap',
   },
+  idCardFieldSubValue: {
+    fontSize: 9,
+    color: '#aaa',
+    marginTop: 1,
+  },
   guide: {
     flex: 1,
     display: 'flex',
@@ -896,12 +934,23 @@ const styles = StyleSheet.create({
   },
 });
 
-const IDCardField = ({ label, value }: { label: string; value: string }) => (
+const IDCardField = ({
+  label,
+  value,
+  subValue,
+}: {
+  label: string;
+  value: string;
+  subValue?: string;
+}) => (
   <View style={styles.idCardFieldItem}>
     <Text style={styles.idCardFieldLabel} numberOfLines={1}>
       {label}
     </Text>
     <Text style={styles.idCardFieldValue}>{value || '—'}</Text>
+    {subValue ? (
+      <Text style={styles.idCardFieldSubValue}>{subValue}</Text>
+    ) : null}
   </View>
 );
 

package/src/Shared/Contexts/AppContext.ts

@@ -3,6 +3,7 @@ import type {
   IdentificationInfo,
   WorkflowStep,
 } from '../Types/identificationInfo';
+import type { DocumentReadResult } from '../Types/documentReadResult';
 
 export type AppContextType = {
   isDemoSession: boolean;
@@ -19,8 +20,12 @@ export type AppContextType = {
   currentWorkflowStep?: WorkflowStep;
   isDebugNavigated?: boolean;
   isTestVideoSession?: boolean;
+  /** Last document read result — available to upload services for real-name fields. */
+  lastDocumentRead?: DocumentReadResult;
   onCompleted?: () => void;
   onError?: (error: string) => void;
+  onDocumentRead?: (result: DocumentReadResult) => void;
+  setLastDocumentRead?: (result: DocumentReadResult) => void;
   setSessionId?: (id: string) => void;
   setBaseUrl?: (url: string) => void;
   setIsDemoSession?: (isDemoSession: boolean) => void;
@@ -49,8 +54,11 @@ export default createContext<AppContextType>({
   currentWorkflowStep: undefined,
   isDebugNavigated: false,
   isTestVideoSession: false,
+  lastDocumentRead: undefined,
   onCompleted: undefined,
   onError: undefined,
+  onDocumentRead: undefined,
+  setLastDocumentRead: undefined,
   setSessionId: undefined,
   setBaseUrl: undefined,
 });

package/src/Shared/EIDReader/eidReader.ts

@@ -4,6 +4,7 @@ import { NFCManagerCardService } from './nfcManagerCardService';
 import { EIDService } from './eidService';
 import { DG1File } from './lds/icao/dg1File';
 import { DG2File } from './lds/icao/dg2File';
+import { DG11File } from './lds/icao/dg11File';
 import { FaceImageInfo } from './lds/iso19794/faceImageInfo';
 import { Buffer } from 'buffer';
 import { MRZInfo } from './lds/icao/mrzInfo';
@@ -322,7 +323,14 @@ const eidReader = async (
   dateOfExpiry: string,
   progressCallback?: (progress: number) => void
 ): Promise<
-  { mrz?: MRZInfo; faceImage: string; mimeType: string } | undefined
+  | {
+      mrz?: MRZInfo;
+      faceImage: string;
+      mimeType: string;
+      dg11FirstName: string | null;
+      dg11LastName: string | null;
+    }
+  | undefined
 > => {
   let progress = 0;
   const nfcManagerCardService = new NFCManagerCardService();
@@ -566,6 +574,22 @@ const eidReader = async (
       progressCallback(progress);
     }
 
+    // Read DG11 (Additional Personal Data — printed name in UTF-8, optional)
+    let dg11FirstName: string | null = null;
+    let dg11LastName: string | null = null;
+    try {
+      const dg11InputStream = passportService.getInputStream(
+        EIDService.EF_DG11
+      );
+      await dg11InputStream.init();
+      const dg11File = new DG11File(dg11InputStream);
+      await dg11File.read();
+      dg11FirstName = dg11File.getFirstName();
+      dg11LastName = dg11File.getLastName();
+    } catch {
+      // DG11 is optional — not all chips have it, and access may be denied
+    }
+
     // Read DG2 (Face Image)
     const dg2Done = stepTimer();
     const dg2InputStream = passportService.getInputStream(EIDService.EF_DG2);
@@ -615,6 +639,8 @@ const eidReader = async (
       mrz: mrzInfo,
       faceImage: imageAsBase64,
       mimeType: mimeType,
+      dg11FirstName,
+      dg11LastName,
     };
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);

package/src/Shared/EIDReader/lds/icao/dg11File.ts

@@ -0,0 +1,94 @@
+import { Buffer } from 'buffer';
+import { InputStream } from '../../java/inputStream';
+import { TLVInputStream } from '../../tlv/tlvInputStream';
+import { DataGroup } from '../dataGroup';
+
+/**
+ * DG11 — Additional Personal Data (ICAO 9303-10 §4.6.6).
+ *
+ * We only extract tag 0x5F0E (Name of Holder), which contains the full name
+ * exactly as printed on the document, in UTF-8, using the same `<<` primary/
+ * secondary delimiter as the MRZ (but with native Unicode characters).
+ *
+ * Example: "ÖZTÜRK<<GÖKHAN MEHMET" → lastName="ÖZTÜRK", firstName="GÖKHAN MEHMET"
+ *
+ * The file is optional on the chip — if absent or unreadable we return null
+ * so the caller can fall back to reverse transliteration.
+ */
+export class DG11File extends DataGroup {
+  private static readonly DG11_TAG = 0x6b;
+  private static readonly TAG_LIST_TAG = 0x5c;
+  private static readonly NAME_OF_HOLDER_TAG = 0x5f0e;
+
+  private firstName: string | null = null;
+  private lastName: string | null = null;
+
+  constructor(is?: InputStream) {
+    super(DG11File.DG11_TAG, is);
+  }
+
+  /** Returns the first name from DG11, or null if not present. */
+  getFirstName(): string | null {
+    return this.firstName;
+  }
+
+  /** Returns the last name from DG11, or null if not present. */
+  getLastName(): string | null {
+    return this.lastName;
+  }
+
+  async read(): Promise<void> {
+    await super.readObject();
+  }
+
+  protected async readContent(inputStream: InputStream): Promise<void> {
+    const tlvIn =
+      inputStream instanceof TLVInputStream
+        ? inputStream
+        : new TLVInputStream(inputStream);
+
+    // Skip the tag list (0x5C) — we only care about 0x5F0E
+    // The tag list tells us which optional tags are present; we probe directly.
+    try {
+      await tlvIn.skipToTag(DG11File.NAME_OF_HOLDER_TAG);
+    } catch {
+      // Tag not present in this chip's DG11
+      return;
+    }
+
+    const length = await tlvIn.readLength();
+    if (length <= 0) return;
+
+    const bytes = new Uint8Array(length);
+    await inputStream.readBytesWithOffset(bytes, 0, length);
+
+    const nameString = Buffer.from(bytes).toString('utf8').trim();
+    this.parseName(nameString);
+  }
+
+  protected writeContent(): void {
+    // Write not needed for reading
+  }
+
+  /**
+   * Split "PRIMARY<<SECONDARY" into last/first name components.
+   * Strips trailing filler `<` within each segment.
+   */
+  private parseName(nameString: string): void {
+    const delimIndex = nameString.indexOf('<<');
+    if (delimIndex < 0) {
+      this.lastName = nameString.replace(/<+$/, '').trim();
+      this.firstName = '';
+      return;
+    }
+    this.lastName = nameString
+      .substring(0, delimIndex)
+      .replace(/<+$/, '')
+      .trim();
+    this.firstName = nameString
+      .substring(delimIndex + 2)
+      .replace(/<$/, ' ')
+      .replace(/<+$/, '')
+      .trim();
+  }
+}

package/src/Shared/Libs/documentDataNormalizer.ts

@@ -0,0 +1,108 @@
+import type { MRZFields } from '../Types/mrzFields';
+import type { DocumentData } from '../Types/documentData';
+import type { MRZInfo } from '../EIDReader/lds/icao/mrzInfo';
+
+/**
+ * Expand a 2-digit MRZ year to a 4-digit calendar year.
+ * ICAO 9303: YY >= 30 → 19YY, YY < 30 → 20YY.
+ * (Threshold 30 keeps all current valid documents in range.)
+ */
+function expandYear(yy: string): string {
+  const n = parseInt(yy, 10);
+  return n >= 30 ? `19${yy}` : `20${yy}`;
+}
+
+/**
+ * Convert a YYMMDD MRZ date string to ISO 8601 YYYY-MM-DD.
+ * Returns null for empty, null, or malformed input.
+ */
+function mrzDateToISO(raw: string | null | undefined): string | null {
+  if (!raw || raw.length !== 6) return null;
+  const yy = raw.slice(0, 2);
+  const mm = raw.slice(2, 4);
+  const dd = raw.slice(4, 6);
+  if (!/^\d{6}$/.test(raw)) return null;
+  return `${expandYear(yy)}-${mm}-${dd}`;
+}
+
+/**
+ * Normalize the MRZ document-code field to a single-letter form.
+ * The `mrz` npm package returns "ID" for TD1, while the chip returns "I".
+ */
+function normalizeDocumentType(raw: string | null | undefined): string {
+  if (!raw) return 'I';
+  const upper = raw.trim().toUpperCase();
+  if (upper === 'ID') return 'I';
+  // TD2 can be "IR", "AC", etc — take only the first character
+  return upper.charAt(0);
+}
+
+/**
+ * Normalize the sex field to a single uppercase letter.
+ * NFC chip: "M" | "F" | "U" | "X"
+ * mrz package: "male" | "female" | "" | null
+ */
+function normalizeSex(raw: string | null | undefined): 'M' | 'F' | 'X' | 'U' {
+  if (!raw) return 'U';
+  switch (raw.trim().toLowerCase()) {
+    case 'm':
+    case 'male':
+      return 'M';
+    case 'f':
+    case 'female':
+      return 'F';
+    case 'x':
+    case 'unspecified':
+      return 'X';
+    default:
+      return 'U';
+  }
+}
+
+/**
+ * Trim a string and return null if empty or only filler chars.
+ */
+function clean(val: string | null | undefined): string | null {
+  if (!val) return null;
+  const t = val.replace(/</g, '').trim();
+  return t.length > 0 ? t : null;
+}
+
+/**
+ * Build a DocumentData from a chip-read MRZInfo object (NFC path).
+ */
+export function normalizeFromMRZInfo(mrz: MRZInfo): DocumentData {
+  const rawPersonal =
+    mrz.getPersonalNumber() ?? clean(mrz.getOptionalData1());
+
+  return {
+    documentType: normalizeDocumentType(mrz.getDocumentCode()),
+    issuingCountry: mrz.getIssuingState().replace(/<$/, '').trim(),
+    nationality: mrz.getNationality().replace(/<$/, '').trim(),
+    documentNumber: mrz.getDocumentNumber().trim(),
+    personalNumber: clean(rawPersonal),
+    lastName: mrz.getPrimaryIdentifier().trim(),
+    firstName: mrz.getSecondaryIdentifier().trim(),
+    sex: normalizeSex(mrz.getGender().getStrCode()),
+    dateOfBirth: mrzDateToISO(mrz.getDateOfBirth()),
+    dateOfExpiry: mrzDateToISO(mrz.getDateOfExpiry()),
+  };
+}
+
+/**
+ * Build a DocumentData from an MRZFields object (camera OCR path).
+ */
+export function normalizeFromMRZFields(fields: MRZFields): DocumentData {
+  return {
+    documentType: normalizeDocumentType(fields.documentCode),
+    issuingCountry: clean(fields.issuingState) ?? '',
+    nationality: clean(fields.nationality) ?? '',
+    documentNumber: clean(fields.documentNumber) ?? '',
+    personalNumber: clean(fields.personalNumber),
+    lastName: clean(fields.lastName) ?? '',
+    firstName: clean(fields.firstName) ?? '',
+    sex: normalizeSex(fields.sex),
+    dateOfBirth: mrzDateToISO(fields.birthDate),
+    dateOfExpiry: mrzDateToISO(fields.expirationDate),
+  };
+}

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

@@ -1244,18 +1244,13 @@ const validateMRZ = (
       documentCode: result.fields.documentCode || null,
       issuingState: result.fields.issuingState || null,
       documentNumber: result.fields.documentNumber || null,
-      documentNumberCheckDigit: result.fields.documentNumberCheckDigit || null,
       nationality: result.fields.nationality || null,
       lastName: result.fields.lastName || null,
       firstName: result.fields.firstName || null,
       sex: result.fields.sex || null,
       birthDate: result.fields.birthDate || null,
-      birthDateCheckDigit: result.fields.birthDateCheckDigit || null,
       expirationDate: result.fields.expirationDate || null,
-      expirationDateCheckDigit: result.fields.expirationDateCheckDigit || null,
       personalNumber: result.fields.personalNumber || null,
-      personalNumberCheckDigit: result.fields.personalNumberCheckDigit || null,
-      compositeCheckDigit: result.fields.compositeCheckDigit || null,
       optional1: result.fields.optional1 || null,
       optional2: result.fields.optional2 || null,
     };

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;
+}