@test-web/react-native-sdk 2.3.0 → 2.4.0

package/src/utils/mrzExamples.ts

@@ -0,0 +1,127 @@
+/**
+ * MRZ Examples and Utilities
+ * Generic utilities for testing MRZ parsing (works with any country)
+ */
+
+import { parseMRZ, formatMRZData } from './mrzParser';
+
+/**
+ * Extract just the MRZ portion from full card text
+ * This helps separate the MRZ lines from other card text
+ */
+export function extractMRZFromFullText(fullText: string): string | null {
+  const normalized = fullText.toUpperCase().replace(/\s/g, '');
+  
+  // Try to find TD1 pattern (90 chars)
+  const td1Match = normalized.match(/([A-Z0-9<]{30})([A-Z0-9<]{30})([A-Z0-9<]{30})/);
+  if (td1Match) {
+    const potential = td1Match[1] + td1Match[2] + td1Match[3];
+    const parsed = parseMRZ(potential);
+    if (parsed && parsed.documentType === 'TD1') {
+      return potential;
+    }
+  }
+  
+  // Try to find TD3 pattern (88 chars)
+  const td3Match = normalized.match(/([A-Z0-9<]{44})([A-Z0-9<]{44})/);
+  if (td3Match) {
+    const potential = td3Match[1] + td3Match[2];
+    const parsed = parseMRZ(potential);
+    if (parsed && parsed.documentType === 'TD3') {
+      return potential;
+    }
+  }
+  
+  // Try to find TD2 pattern (72 chars)
+  const td2Match = normalized.match(/([A-Z0-9<]{36})([A-Z0-9<]{36})/);
+  if (td2Match) {
+    const potential = td2Match[1] + td2Match[2];
+    const parsed = parseMRZ(potential);
+    if (parsed && parsed.documentType === 'TD2') {
+      return potential;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Test a single MRZ string
+ */
+export function testMRZ(mrzString: string) {
+  console.log('\n========== MRZ TEST ==========');
+  console.log('Input:', mrzString);
+  console.log('Length:', mrzString.length);
+
+  const parsed = parseMRZ(mrzString);
+
+  if (parsed) {
+    console.log('\n✓ Successfully parsed!');
+    console.log(formatMRZData(parsed));
+  } else {
+    console.log('\n✗ Failed to parse MRZ');
+    console.log('Expected lengths: 90 (TD1), 72 (TD2), or 88 (TD3)');
+  }
+
+  console.log('==============================\n');
+
+  return parsed;
+}
+
+/**
+ * Common OCR errors and corrections
+ */
+export const OCR_CORRECTIONS = {
+  'O': '0',  // Letter O to zero
+  'I': '1',  // Letter I to one
+  'S': '5',  // Letter S to five
+  'Z': '2',  // Letter Z to two
+  'B': '8',  // Letter B to eight
+  'G': '6',  // Letter G to six
+  '«': '<',  // Double angle quote to less than
+  '»': '<',  // Double angle quote to less than
+};
+
+/**
+ * Tips for scanning MRZ codes
+ */
+export const SCANNING_TIPS = [
+  'Ensure good lighting - avoid shadows and glare',
+  'Hold the document flat and steady',
+  'Align the MRZ zone within the camera frame',
+  'Keep the camera parallel to the document',
+  'Clean the camera lens if text is blurry',
+  'For passports, scan the bottom 2 lines',
+  'For ID cards, scan the bottom 3 lines',
+  'Avoid reflections from laminated surfaces',
+];
+
+/**
+ * Document type detection guide
+ */
+export const DOCUMENT_TYPES = {
+  TD1: {
+    name: 'TD1 - ID Card Size',
+    lines: 3,
+    charsPerLine: 30,
+    totalChars: 90,
+    examples: ['National ID Cards', 'Residence Permits', 'Some Driver Licenses'],
+    description: 'Used by most countries for national ID cards',
+  },
+  TD2: {
+    name: 'TD2 - Intermediate Size',
+    lines: 2,
+    charsPerLine: 36,
+    totalChars: 72,
+    examples: ['Some Passports', 'Travel Documents'],
+    description: 'Less common format for travel documents',
+  },
+  TD3: {
+    name: 'TD3 - Passport Size',
+    lines: 2,
+    charsPerLine: 44,
+    totalChars: 88,
+    examples: ['Passports', 'Passport Cards'],
+    description: 'Standard passport format used worldwide',
+  },
+};

package/src/utils/mrzParser.ts

@@ -0,0 +1,303 @@
+/**
+ * MRZ (Machine Readable Zone) Parser
+ * Supports TD1 (ID Cards), TD2, and TD3 (Passports) formats
+ * 
+ * Based on ICAO Document 9303 standards
+ */
+
+export interface MRZData {
+  documentType: 'TD1' | 'TD2' | 'TD3';
+  documentCode: string;
+  issuingCountry: string;
+  documentNumber: string;
+  dateOfBirth: string;
+  sex: string;
+  expirationDate: string;
+  nationality: string;
+  surname: string;
+  givenNames: string;
+  optionalData?: string;
+  rawMRZ: string;
+  isValid: boolean;
+}
+
+/**
+ * Normalize MRZ text by replacing common OCR errors
+ */
+export function normalizeMRZ(text: string): string {
+  return text
+    .toUpperCase()
+    .replace(/\s/g, '')
+    .replace(/[«»]/g, '<')
+    .replace(/O/g, '0')
+    .replace(/[^A-Z0-9<]/g, '');
+}
+
+/**
+ * Calculate check digit for MRZ validation
+ */
+function calculateCheckDigit(input: string): number {
+  const weights = [7, 3, 1];
+  let sum = 0;
+
+  for (let i = 0; i < input.length; i++) {
+    const char = input[i];
+    let value: number;
+
+    if (char === '<') {
+      value = 0;
+    } else if (char >= '0' && char <= '9') {
+      value = parseInt(char, 10);
+    } else if (char >= 'A' && char <= 'Z') {
+      value = char.charCodeAt(0) - 'A'.charCodeAt(0) + 10;
+    } else {
+      value = 0;
+    }
+
+    sum += value * weights[i % 3];
+  }
+
+  return sum % 10;
+}
+
+/**
+ * Validate check digit
+ */
+function validateCheckDigit(data: string, checkDigit: string): boolean {
+  if (checkDigit === '<') return true; // Optional field
+  const expected = calculateCheckDigit(data);
+  return expected === parseInt(checkDigit, 10);
+}
+
+/**
+ * Parse date from MRZ format (YYMMDD)
+ */
+function parseDate(dateStr: string): string {
+  if (dateStr.length !== 6) return '';
+  
+  const year = parseInt(dateStr.substring(0, 2), 10);
+  const month = dateStr.substring(2, 4);
+  const day = dateStr.substring(4, 6);
+  
+  // Assume dates > 50 are 19xx, otherwise 20xx
+  const fullYear = year > 50 ? 1900 + year : 2000 + year;
+  
+  return `${fullYear}-${month}-${day}`;
+}
+
+/**
+ * Parse names from MRZ format
+ */
+function parseNames(nameField: string): { surname: string; givenNames: string } {
+  const parts = nameField.split('<<');
+  const surname = parts[0].replace(/</g, ' ').trim();
+  const givenNames = parts.length > 1 ? parts[1].replace(/</g, ' ').trim() : '';
+  
+  return { surname, givenNames };
+}
+
+/**
+ * Parse TD1 format (ID Cards - 3 lines of 30 characters)
+ * Example from Argentina ID:
+ * IDARG323352335<0<<<<<<<<<<<<<<<<<
+ * 8612179M3504037ARG<<<<<<<<<<<<8
+ * SALVADOR<<HECTOR<MAURICIO<<<<<<
+ */
+export function parseTD1(mrz: string): MRZData | null {
+  if (mrz.length !== 90) {
+    return null;
+  }
+
+  const line1 = mrz.substring(0, 30);
+  const line2 = mrz.substring(30, 60);
+  const line3 = mrz.substring(60, 90);
+
+  // Line 1: Document code (2), Country (3), Document number (9), Check digit (1), Optional (15)
+  const documentCode = line1.substring(0, 2);
+  const issuingCountry = line1.substring(2, 5);
+  const documentNumber = line1.substring(5, 14).replace(/</g, '');
+  const docNumCheck = line1.substring(14, 15);
+  const optionalData1 = line1.substring(15, 30).replace(/</g, '');
+
+  // Line 2: DOB (6), DOB check (1), Sex (1), Expiry (6), Expiry check (1), Nationality (3), Optional (11), Composite check (1)
+  const dateOfBirth = parseDate(line2.substring(0, 6));
+  const dobCheck = line2.substring(6, 7);
+  const sex = line2.substring(7, 8);
+  const expirationDate = parseDate(line2.substring(8, 14));
+  const expCheck = line2.substring(14, 15);
+  const nationality = line2.substring(15, 18);
+  const optionalData2 = line2.substring(18, 29).replace(/</g, '');
+
+  // Line 3: Names
+  const { surname, givenNames } = parseNames(line3);
+
+  // Validate check digits
+  const isDocNumValid = validateCheckDigit(line1.substring(5, 14), docNumCheck);
+  const isDobValid = validateCheckDigit(line2.substring(0, 6), dobCheck);
+  const isExpValid = validateCheckDigit(line2.substring(8, 14), expCheck);
+
+  const isValid = isDocNumValid && isDobValid && isExpValid;
+
+  return {
+    documentType: 'TD1',
+    documentCode,
+    issuingCountry,
+    documentNumber,
+    dateOfBirth,
+    sex: sex === 'M' ? 'Male' : sex === 'F' ? 'Female' : 'Unknown',
+    expirationDate,
+    nationality,
+    surname,
+    givenNames,
+    optionalData: optionalData1 + optionalData2,
+    rawMRZ: mrz,
+    isValid,
+  };
+}
+
+/**
+ * Parse TD2 format (2 lines of 36 characters)
+ */
+export function parseTD2(mrz: string): MRZData | null {
+  if (mrz.length !== 72) {
+    return null;
+  }
+
+  const line1 = mrz.substring(0, 36);
+  const line2 = mrz.substring(36, 72);
+
+  // Line 1: Document code (2), Country (3), Names (31)
+  const documentCode = line1.substring(0, 2);
+  const issuingCountry = line1.substring(2, 5);
+  const { surname, givenNames } = parseNames(line1.substring(5, 36));
+
+  // Line 2: Document number (9), Check (1), Nationality (3), DOB (6), Check (1), Sex (1), Expiry (6), Check (1), Optional (7), Check (1)
+  const documentNumber = line2.substring(0, 9).replace(/</g, '');
+  const docNumCheck = line2.substring(9, 10);
+  const nationality = line2.substring(10, 13);
+  const dateOfBirth = parseDate(line2.substring(13, 19));
+  const dobCheck = line2.substring(19, 20);
+  const sex = line2.substring(20, 21);
+  const expirationDate = parseDate(line2.substring(21, 27));
+  const expCheck = line2.substring(27, 28);
+  const optionalData = line2.substring(28, 35).replace(/</g, '');
+
+  const isDocNumValid = validateCheckDigit(line2.substring(0, 9), docNumCheck);
+  const isDobValid = validateCheckDigit(line2.substring(13, 19), dobCheck);
+  const isExpValid = validateCheckDigit(line2.substring(21, 27), expCheck);
+
+  const isValid = isDocNumValid && isDobValid && isExpValid;
+
+  return {
+    documentType: 'TD2',
+    documentCode,
+    issuingCountry,
+    documentNumber,
+    dateOfBirth,
+    sex: sex === 'M' ? 'Male' : sex === 'F' ? 'Female' : 'Unknown',
+    expirationDate,
+    nationality,
+    surname,
+    givenNames,
+    optionalData,
+    rawMRZ: mrz,
+    isValid,
+  };
+}
+
+/**
+ * Parse TD3 format (Passports - 2 lines of 44 characters)
+ * Example from US Passport:
+ * P<USAGATCHALIAN<<NICOLE<ANGELINE<LUCIENNE<JA
+ * 5778700136USA8904160F28012456149724051<605856
+ */
+export function parseTD3(mrz: string): MRZData | null {
+  if (mrz.length !== 88) {
+    return null;
+  }
+
+  const line1 = mrz.substring(0, 44);
+  const line2 = mrz.substring(44, 88);
+
+  // Line 1: Document code (2), Country (3), Names (39)
+  const documentCode = line1.substring(0, 2);
+  const issuingCountry = line1.substring(2, 5);
+  const { surname, givenNames } = parseNames(line1.substring(5, 44));
+
+  // Line 2: Passport number (9), Check (1), Nationality (3), DOB (6), Check (1), Sex (1), Expiry (6), Check (1), Optional (14), Check (1), Composite check (1)
+  const documentNumber = line2.substring(0, 9).replace(/</g, '');
+  const docNumCheck = line2.substring(9, 10);
+  const nationality = line2.substring(10, 13);
+  const dateOfBirth = parseDate(line2.substring(13, 19));
+  const dobCheck = line2.substring(19, 20);
+  const sex = line2.substring(20, 21);
+  const expirationDate = parseDate(line2.substring(21, 27));
+  const expCheck = line2.substring(27, 28);
+  const optionalData = line2.substring(28, 42).replace(/</g, '');
+
+  const isDocNumValid = validateCheckDigit(line2.substring(0, 9), docNumCheck);
+  const isDobValid = validateCheckDigit(line2.substring(13, 19), dobCheck);
+  const isExpValid = validateCheckDigit(line2.substring(21, 27), expCheck);
+
+  const isValid = isDocNumValid && isDobValid && isExpValid;
+
+  return {
+    documentType: 'TD3',
+    documentCode,
+    issuingCountry,
+    documentNumber,
+    dateOfBirth,
+    sex: sex === 'M' ? 'Male' : sex === 'F' ? 'Female' : 'Unknown',
+    expirationDate,
+    nationality,
+    surname,
+    givenNames,
+    optionalData,
+    rawMRZ: mrz,
+    isValid,
+  };
+}
+
+/**
+ * Auto-detect and parse MRZ format
+ */
+export function parseMRZ(mrzText: string): MRZData | null {
+  const normalized = normalizeMRZ(mrzText);
+  
+  // TD1: 90 characters (3 lines x 30)
+  if (normalized.length === 90) {
+    return parseTD1(normalized);
+  }
+  
+  // TD2: 72 characters (2 lines x 36)
+  if (normalized.length === 72) {
+    return parseTD2(normalized);
+  }
+  
+  // TD3: 88 characters (2 lines x 44)
+  if (normalized.length === 88) {
+    return parseTD3(normalized);
+  }
+  
+  return null;
+}
+
+/**
+ * Format MRZ data for display
+ */
+export function formatMRZData(data: MRZData): string {
+  return `
+Document Type: ${data.documentType}
+Document Code: ${data.documentCode}
+Issuing Country: ${data.issuingCountry}
+Document Number: ${data.documentNumber}
+Surname: ${data.surname}
+Given Names: ${data.givenNames}
+Date of Birth: ${data.dateOfBirth}
+Sex: ${data.sex}
+Nationality: ${data.nationality}
+Expiration Date: ${data.expirationDate}
+${data.optionalData ? `Optional Data: ${data.optionalData}` : ''}
+Valid: ${data.isValid ? 'Yes' : 'No'}
+  `.trim();
+}

package/src/utils/mrzUtils.ts

@@ -0,0 +1,70 @@
+/**
+ * MRZ Utilities
+ * Based on demo-testing-sdk implementation
+ */
+
+/**
+ * Normalize MRZ text by replacing common OCR errors
+ */
+export function normalizeMrz(text: string): string {
+  return text
+    .replace(/\s/g, '')           // Remove spaces
+    .replace(/[«»]/g, '<')        // Replace angle quotes
+    .replace(/O/g, '0')           // Letter O to zero
+    .replace(/I/g, '1')           // Letter I to one
+    .replace(/S/g, '5')           // Letter S to five
+    .replace(/[^A-Z0-9<]/gi, ''); // Keep only alphanumeric and <
+}
+
+/**
+ * Check if a line is a valid MRZ line
+ */
+export function isMRZLine(text: string): boolean {
+  return /^[A-Z0-9<]{28,46}$/.test(text);
+}
+
+/**
+ * Extract MRZ lines from text blocks
+ */
+export function extractMRZLines(textLines: string[]): string[] {
+  return textLines
+    .map(line => normalizeMrz(line))
+    .filter(line => isMRZLine(line));
+}
+
+/**
+ * Detect document type from MRZ lines
+ */
+export function detectDocumentType(mrzLines: string[]): 'TD1' | 'TD2' | 'TD3' | null {
+  if (mrzLines.length === 0) return null;
+
+  const firstLineLength = mrzLines[0].length;
+
+  // TD1: 3 lines of 30 characters (ID cards)
+  if (mrzLines.length >= 3 && firstLineLength === 30) {
+    return 'TD1';
+  }
+
+  // TD3: 2 lines of 44 characters (Passports)
+  if (mrzLines.length >= 2 && firstLineLength === 44) {
+    return 'TD3';
+  }
+
+  // TD2: 2 lines of 36 characters
+  if (mrzLines.length >= 2 && firstLineLength === 36) {
+    return 'TD2';
+  }
+
+  return null;
+}
+
+/**
+ * Validate MRZ format
+ */
+export function validateMRZ(fullText: string): boolean {
+  const lines = fullText.split('\n').filter(l => l.length > 0);
+  const mrzLines = extractMRZLines(lines);
+  const docType = detectDocumentType(mrzLines);
+  
+  return docType !== null;
+}