petrus-react-native 0.1.0

package/src/NativePetrusReactNative.ts

@@ -0,0 +1,303 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+export interface Spec extends TurboModule {
+  // Phase 0 placeholder: proves the JS <-> native TurboModule <-> petrus-core
+  // wiring works end to end. Replaced by the real capture/detect/OCR/parse API
+  // surface in later phases.
+  getPipelineVersion(): string;
+
+  // Phase 1: camera runtime permission (Android only -- see PetrusReactNativeModule.kt).
+  checkPermission(): Promise<'granted' | 'denied' | 'blocked'>;
+  requestPermission(): Promise<'granted' | 'denied' | 'blocked'>;
+
+  // Phase 3: ML Kit-based OCR (Android only). Raw text/boxes/confidence -- no
+  // document-specific field parsing. `imagePath` may be a bare filesystem path or a
+  // URI (file://, content://, ...).
+  recognizeText(imagePath: string): Promise<{
+    fullText: string;
+    confidence: number;
+    blocks: Array<{
+      text: string;
+      boundingBox: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+      };
+      lines: Array<{
+        text: string;
+        confidence: number;
+        boundingBox: {
+          left: number;
+          top: number;
+          right: number;
+          bottom: number;
+        };
+        words: Array<{
+          text: string;
+          confidence: number;
+          boundingBox: {
+            left: number;
+            top: number;
+            right: number;
+            bottom: number;
+          };
+        }>;
+      }>;
+    }>;
+  }>;
+
+  // Phase 4: SA ID parsing (Android only). Pure CPU work (regex + arithmetic on a
+  // short string) -- synchronous, no Promise needed, same as getPipelineVersion.
+  // `text` is expected to be OCR output (e.g. recognizeText's `fullText`), not tied
+  // to any specific OCR engine.
+  parseSouthAfricanID(text: string): {
+    idNumber: string | null;
+    isValid: boolean;
+    dateOfBirth: {
+      year: number;
+      month: number;
+      day: number;
+    } | null;
+    gender: 'male' | 'female' | null;
+    citizenship: 'citizen' | 'permanent_resident' | 'refugee' | 'unknown' | null;
+    validation: {
+      isValid: boolean;
+      hasValidChecksum: boolean;
+      hasValidDateOfBirth: boolean;
+      hasValidCitizenshipDigit: boolean;
+    } | null;
+  };
+
+  // Phase 5: PDF417 barcode scanning + SA driver's licence parsing (Android only).
+  // See the README's confidence note on the reverse-engineered barcode format
+  // before relying on the decoded *licence fields* in production -- the barcode
+  // detection/decoding itself (ZXing) has no such caveat.
+
+  // Decodes a PDF417 barcode from a still image. `imagePath` may be a bare
+  // filesystem path or a URI. Rejects (does not resolve null) if no barcode is
+  // found in the image -- there's no meaningful "empty" PDF417 scan result.
+  scanPDF417(imagePath: string): Promise<{
+    /** Base64-encoded raw decoded barcode bytes (binary for SA licence barcodes). */
+    rawDataBase64: string;
+    /** Best-effort ISO-8859-1 text view of the same bytes; rarely meaningful for encrypted payloads. */
+    rawText: string;
+  }>;
+
+  // Parses already-scanned raw barcode bytes (e.g. scanPDF417's rawDataBase64) into
+  // SA driver's licence fields. Synchronous -- pure CPU work (RSA modPow over a few
+  // hundred bytes + nibble parsing), no I/O. Throws if rawDataBase64 doesn't decode
+  // to a recognized SA driver's licence barcode format -- unlike parseSouthAfricanID,
+  // there's no meaningful partial/not-found result to return here since this is
+  // expected to be called on data that already came from a barcode scan.
+  parseSouthAfricanDriversLicense(rawDataBase64: string): {
+    version: 'v1' | 'v2';
+    surname: string;
+    initials: string;
+    idNumber: string | null;
+    idNumberValidation: {
+      isValid: boolean;
+      hasValidChecksum: boolean;
+      hasValidDateOfBirth: boolean;
+      hasValidCitizenshipDigit: boolean;
+    } | null;
+    licenseNumber: string;
+    vehicleCodes: string[];
+    vehicleRestrictions: string[];
+    prdpCode: string | null;
+    idCountryOfIssue: string;
+    licenseCountryOfIssue: string;
+    gender: 'male' | 'female' | null;
+    dateOfBirth: { year: number; month: number; day: number } | null;
+    licenseIssueNumber: number | null;
+    licenseValidFrom: { year: number; month: number; day: number } | null;
+    licenseValidTo: { year: number; month: number; day: number } | null;
+    prdpExpiry: { year: number; month: number; day: number } | null;
+    driverRestrictionCodes: number[];
+    parseWarnings: string[];
+  };
+
+  // Convenience: opens a headless (no preview UI) camera session, scans for a
+  // PDF417 barcode, and parses it as an SA driver's licence in one call -- i.e.
+  // scanPDF417 + parseSouthAfricanDriversLicense composed natively. Rejects on
+  // timeout (~20s) or if no Activity is available, rather than resolving null.
+  scanSouthAfricanDriversLicense(): Promise<{
+    version: 'v1' | 'v2';
+    surname: string;
+    initials: string;
+    idNumber: string | null;
+    idNumberValidation: {
+      isValid: boolean;
+      hasValidChecksum: boolean;
+      hasValidDateOfBirth: boolean;
+      hasValidCitizenshipDigit: boolean;
+    } | null;
+    licenseNumber: string;
+    vehicleCodes: string[];
+    vehicleRestrictions: string[];
+    prdpCode: string | null;
+    idCountryOfIssue: string;
+    licenseCountryOfIssue: string;
+    gender: 'male' | 'female' | null;
+    dateOfBirth: { year: number; month: number; day: number } | null;
+    licenseIssueNumber: number | null;
+    licenseValidFrom: { year: number; month: number; day: number } | null;
+    licenseValidTo: { year: number; month: number; day: number } | null;
+    prdpExpiry: { year: number; month: number; day: number } | null;
+    driverRestrictionCodes: number[];
+    parseWarnings: string[];
+  }>;
+
+  // Phase 6: SA vehicle registration document parsing (Android only). Label
+  // wording is based on general knowledge of NATIS/eNaTIS documents, not verified
+  // against a physical sample -- see the README's confidence note before relying
+  // on extracted fields in production. Government API integration, face matching,
+  // driver's licence, and passport parsing are explicitly out of scope here.
+
+  // Parses OCR text (e.g. recognizeText's `fullText`) into vehicle registration
+  // fields. Synchronous -- pure CPU work (regex-based field extraction), same
+  // reasoning as parseSouthAfricanID. Never throws for unrecognized/partial text --
+  // returns as much as could be extracted, with `documentType: 'unknown'` and/or
+  // `parseWarnings` entries flagging what looked off.
+  parseVehicleRegistration(text: string): {
+    documentType:
+      | 'registration_certificate'
+      | 'license_disc'
+      | 'notification_of_change'
+      | 'roadworthy_certificate'
+      | 'unknown';
+    registrationNumber: string | null;
+    vin: string | null;
+    vinValidation: {
+      hasValidLength: boolean;
+      hasValidCharacterSet: boolean;
+      isStructurallyValid: boolean;
+      northAmericanCheckDigitValid: boolean | null;
+    } | null;
+    engineNumber: string | null;
+    make: string | null;
+    model: string | null;
+    yearModel: number | null;
+    ownerName: string | null;
+    ownerIdNumber: string | null;
+    ownerIdValidation: {
+      isValid: boolean;
+      hasValidChecksum: boolean;
+      hasValidDateOfBirth: boolean;
+      hasValidCitizenshipDigit: boolean;
+    } | null;
+    validation: {
+      isValid: boolean;
+      hasStructurallyValidVin: boolean;
+      hasPlausibleRegistrationNumber: boolean;
+      hasPlausibleYearModel: boolean;
+    };
+    parseWarnings: string[];
+  };
+
+  // Convenience: opens a headless (no preview UI) camera session, runs OCR on
+  // frames, and parses each result as a vehicle registration document in one call
+  // -- stops once a frame yields a registration number or VIN, or the scan window
+  // (~20s) elapses. Rejects on timeout or if no Activity is available, rather than
+  // resolving null (same convention as scanSouthAfricanDriversLicense).
+  scanVehicleRegistration(): Promise<{
+    documentType:
+      | 'registration_certificate'
+      | 'license_disc'
+      | 'notification_of_change'
+      | 'roadworthy_certificate'
+      | 'unknown';
+    registrationNumber: string | null;
+    vin: string | null;
+    vinValidation: {
+      hasValidLength: boolean;
+      hasValidCharacterSet: boolean;
+      isStructurallyValid: boolean;
+      northAmericanCheckDigitValid: boolean | null;
+    } | null;
+    engineNumber: string | null;
+    make: string | null;
+    model: string | null;
+    yearModel: number | null;
+    ownerName: string | null;
+    ownerIdNumber: string | null;
+    ownerIdValidation: {
+      isValid: boolean;
+      hasValidChecksum: boolean;
+      hasValidDateOfBirth: boolean;
+      hasValidCitizenshipDigit: boolean;
+    } | null;
+    validation: {
+      isValid: boolean;
+      hasStructurallyValidVin: boolean;
+      hasPlausibleRegistrationNumber: boolean;
+      hasPlausibleYearModel: boolean;
+    };
+    parseWarnings: string[];
+  }>;
+
+  // Phase 7: ICAO 9303 TD3 (passport) MRZ parsing (Android only). Everything
+  // runs on-device -- ML Kit text recognition is on-device, and MRZChecksum/
+  // MRZParser/PassportParser are pure Kotlin with no network calls. NFC chip
+  // reading, face matching, visa parsing (TD1/TD2), driver's licence, and
+  // vehicle documents are explicitly out of scope for this phase.
+
+  // Parses MRZ text (e.g. recognizeText's `fullText`, already cropped to the MRZ
+  // region, or pasted raw) into passport fields. Synchronous -- pure CPU work
+  // (regex + checksum arithmetic over two 44-character lines), same reasoning as
+  // parseSouthAfricanID/parseVehicleRegistration. Never throws/rejects -- when no
+  // MRZ-shaped line pair can be located in the text at all, every string field
+  // comes back empty and `parseWarnings` explains why, same "always return a
+  // result object" convention as parseSouthAfricanID's null idNumber.
+  parseMRZ(text: string): {
+    documentCode: string;
+    issuingCountry: string;
+    surname: string;
+    givenNames: string;
+    passportNumber: string;
+    nationality: string;
+    dateOfBirth: { year: number; month: number; day: number; twoDigitYear: number } | null;
+    sex: 'male' | 'female' | 'unspecified';
+    dateOfExpiry: { year: number; month: number; day: number; twoDigitYear: number } | null;
+    personalNumber: string | null;
+    validation: {
+      isValid: boolean;
+      passportNumberCheckValid: boolean;
+      dateOfBirthCheckValid: boolean;
+      expiryDateCheckValid: boolean;
+      personalNumberCheckValid: boolean;
+      compositeCheckValid: boolean;
+    };
+    parseWarnings: string[];
+  };
+
+  // Convenience: opens a headless (no preview UI) camera session; per frame,
+  // detects the document boundary, crops just the MRZ band (ICAO 9303's
+  // Effective Reading Zone geometry), runs OCR on *only that crop*, and parses
+  // it -- stops once a frame yields a non-empty passport number, or the scan
+  // window (~20s) elapses. Rejects on timeout or if no Activity is available
+  // (same convention as scanSouthAfricanDriversLicense/scanVehicleRegistration).
+  scanPassport(): Promise<{
+    documentCode: string;
+    issuingCountry: string;
+    surname: string;
+    givenNames: string;
+    passportNumber: string;
+    nationality: string;
+    dateOfBirth: { year: number; month: number; day: number; twoDigitYear: number } | null;
+    sex: 'male' | 'female' | 'unspecified';
+    dateOfExpiry: { year: number; month: number; day: number; twoDigitYear: number } | null;
+    personalNumber: string | null;
+    validation: {
+      isValid: boolean;
+      passportNumberCheckValid: boolean;
+      dateOfBirthCheckValid: boolean;
+      expiryDateCheckValid: boolean;
+      personalNumberCheckValid: boolean;
+      compositeCheckValid: boolean;
+    };
+    parseWarnings: string[];
+  }>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('PetrusReactNative');

package/src/PetrusCameraView.native.tsx

@@ -0,0 +1,44 @@
+import type { NativeSyntheticEvent } from 'react-native';
+import NativePetrusCameraView from './PetrusCameraViewNativeComponent';
+import type {
+  PetrusFrameMetadata,
+  PetrusDocumentDetectedEvent,
+  PetrusCapturedEvent,
+} from './types';
+import type { PetrusCameraViewProps } from './PetrusCameraView';
+
+export type { PetrusCameraViewProps } from './PetrusCameraView';
+
+export function PetrusCameraView({
+  onFrameMetadata,
+  onDocumentDetected,
+  onCaptured,
+  ...rest
+}: PetrusCameraViewProps) {
+  return (
+    <NativePetrusCameraView
+      {...rest}
+      onFrameMetadata={
+        onFrameMetadata == null
+          ? undefined
+          : (event: NativeSyntheticEvent<PetrusFrameMetadata>) => {
+              onFrameMetadata(event.nativeEvent);
+            }
+      }
+      onDocumentDetected={
+        onDocumentDetected == null
+          ? undefined
+          : (event: NativeSyntheticEvent<PetrusDocumentDetectedEvent>) => {
+              onDocumentDetected(event.nativeEvent);
+            }
+      }
+      onCaptured={
+        onCaptured == null
+          ? undefined
+          : (event: NativeSyntheticEvent<PetrusCapturedEvent>) => {
+              onCaptured(event.nativeEvent);
+            }
+      }
+    />
+  );
+}

package/src/PetrusCameraView.tsx

@@ -0,0 +1,19 @@
+import type { ViewProps } from 'react-native';
+import type {
+  PetrusFrameMetadata,
+  PetrusDocumentDetectedEvent,
+  PetrusCapturedEvent,
+} from './types';
+
+export interface PetrusCameraViewProps extends ViewProps {
+  isActive?: boolean;
+  onFrameMetadata?: (metadata: PetrusFrameMetadata) => void;
+  onDocumentDetected?: (event: PetrusDocumentDetectedEvent) => void;
+  onCaptured?: (event: PetrusCapturedEvent) => void;
+}
+
+export function PetrusCameraView(_props: PetrusCameraViewProps): never {
+  throw new Error(
+    "'petrus-react-native's PetrusCameraView is only supported on native platforms."
+  );
+}

package/src/PetrusCameraViewNativeComponent.ts

@@ -0,0 +1,47 @@
+import { codegenNativeComponent, type ViewProps, type CodegenTypes } from 'react-native';
+
+type NativePoint2D = Readonly<{
+  x: CodegenTypes.Double;
+  y: CodegenTypes.Double;
+}>;
+
+// Always sent as a well-formed object (zeroed when nothing's detected), never
+// null/omitted -- avoids relying on nullable/optional object support in the event
+// codegen path. `detected`/callers should treat these as meaningless when unset.
+type NativeDocumentCorners = Readonly<{
+  topLeft: NativePoint2D;
+  topRight: NativePoint2D;
+  bottomRight: NativePoint2D;
+  bottomLeft: NativePoint2D;
+  frameWidth: CodegenTypes.Int32;
+  frameHeight: CodegenTypes.Int32;
+  rotationDegrees: CodegenTypes.Int32;
+}>;
+
+export interface NativeProps extends ViewProps {
+  isActive?: CodegenTypes.WithDefault<boolean, false>;
+
+  onFrameMetadata?: CodegenTypes.DirectEventHandler<{
+    width: CodegenTypes.Int32;
+    height: CodegenTypes.Int32;
+    rotation: CodegenTypes.Int32;
+    // Epoch milliseconds -- exceeds Int32 range, so this must be Double.
+    timestamp: CodegenTypes.Double;
+  }>;
+
+  onDocumentDetected?: CodegenTypes.DirectEventHandler<{
+    detected: boolean;
+    isStable: boolean;
+    stableDurationMs: CodegenTypes.Double;
+    confidence: CodegenTypes.Double;
+    corners: NativeDocumentCorners;
+  }>;
+
+  onCaptured?: CodegenTypes.DirectEventHandler<{
+    corners: NativeDocumentCorners;
+    confidence: CodegenTypes.Double;
+    timestamp: CodegenTypes.Double;
+  }>;
+}
+
+export default codegenNativeComponent<NativeProps>('PetrusCameraView');

package/src/cameraPermissions.native.tsx

@@ -0,0 +1,10 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { PetrusCameraPermissionStatus } from './types';
+
+export function checkPermission(): Promise<PetrusCameraPermissionStatus> {
+  return PetrusReactNative.checkPermission();
+}
+
+export function requestPermission(): Promise<PetrusCameraPermissionStatus> {
+  return PetrusReactNative.requestPermission();
+}

package/src/cameraPermissions.tsx

@@ -0,0 +1,13 @@
+import type { PetrusCameraPermissionStatus } from './types';
+
+export function checkPermission(): Promise<PetrusCameraPermissionStatus> {
+  return Promise.reject(
+    new Error("'petrus-react-native' is only supported on native platforms.")
+  );
+}
+
+export function requestPermission(): Promise<PetrusCameraPermissionStatus> {
+  return Promise.reject(
+    new Error("'petrus-react-native' is only supported on native platforms.")
+  );
+}

package/src/getPipelineVersion.native.tsx

@@ -0,0 +1,5 @@
+import PetrusReactNative from './NativePetrusReactNative';
+
+export function getPipelineVersion(): string {
+  return PetrusReactNative.getPipelineVersion();
+}

package/src/getPipelineVersion.tsx

@@ -0,0 +1,5 @@
+export function getPipelineVersion(): string {
+  throw new Error(
+    "'petrus-react-native' is only supported on native platforms."
+  );
+}

package/src/index.tsx

@@ -0,0 +1,83 @@
+import { getPipelineVersion } from './getPipelineVersion';
+import { checkPermission, requestPermission } from './cameraPermissions';
+import { recognizeText } from './recognizeText';
+import { parseSouthAfricanID } from './parseSouthAfricanID';
+import { scanPDF417 } from './scanPDF417';
+import { parseSouthAfricanDriversLicense } from './parseSouthAfricanDriversLicense';
+import { scanSouthAfricanDriversLicense } from './scanSouthAfricanDriversLicense';
+import { parseVehicleRegistration } from './parseVehicleRegistration';
+import { scanVehicleRegistration } from './scanVehicleRegistration';
+import { parseMRZ } from './parseMRZ';
+import { scanPassport } from './scanPassport';
+
+export { getPipelineVersion } from './getPipelineVersion';
+
+export { PetrusCameraView } from './PetrusCameraView';
+export type { PetrusCameraViewProps } from './PetrusCameraView';
+
+export { checkPermission, requestPermission } from './cameraPermissions';
+
+export { recognizeText } from './recognizeText';
+
+export { parseSouthAfricanID } from './parseSouthAfricanID';
+
+export { scanPDF417 } from './scanPDF417';
+export { parseSouthAfricanDriversLicense } from './parseSouthAfricanDriversLicense';
+export { scanSouthAfricanDriversLicense } from './scanSouthAfricanDriversLicense';
+
+export { parseVehicleRegistration } from './parseVehicleRegistration';
+export { scanVehicleRegistration } from './scanVehicleRegistration';
+
+export { parseMRZ } from './parseMRZ';
+export { scanPassport } from './scanPassport';
+
+export type {
+  PetrusCameraPermissionStatus,
+  PetrusFrameMetadata,
+  PetrusPoint2D,
+  PetrusDocumentCorners,
+  PetrusDocumentDetectedEvent,
+  PetrusCapturedEvent,
+  OCRBoundingBox,
+  OCRWord,
+  OCRLine,
+  OCRBlock,
+  OCRResult,
+  SouthAfricanGender,
+  SouthAfricanCitizenship,
+  SouthAfricanDateOfBirth,
+  SouthAfricanIDValidation,
+  SouthAfricanIDResult,
+  PDF417ScanResult,
+  SouthAfricanDriversLicenseVersion,
+  CalendarDate,
+  SouthAfricanDriversLicenseResult,
+  VehicleDocumentType,
+  VINValidation,
+  VehicleRegistrationValidation,
+  VehicleRegistrationResult,
+  MRZSex,
+  MRZDate,
+  MRZValidation,
+  PassportResult,
+} from './types';
+
+/**
+ * Namespaced convenience alias over the same functions above (e.g.
+ * `Petrus.parseSouthAfricanID(text)`), for callers who prefer a single import over
+ * multiple named ones. Both forms call the same underlying implementation.
+ */
+export const Petrus = {
+  getPipelineVersion,
+  checkPermission,
+  requestPermission,
+  recognizeText,
+  parseSouthAfricanID,
+  scanPDF417,
+  parseSouthAfricanDriversLicense,
+  scanSouthAfricanDriversLicense,
+  parseVehicleRegistration,
+  scanVehicleRegistration,
+  parseMRZ,
+  scanPassport,
+};

package/src/parseMRZ.native.tsx

@@ -0,0 +1,11 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { PassportResult } from './types';
+
+/**
+ * `text` is expected to be MRZ OCR output (e.g. recognizeText's `fullText`,
+ * already cropped to the MRZ region, or pasted raw two-line MRZ text). Never
+ * throws -- see PassportResult's doc comment for the "no MRZ found" shape.
+ */
+export function parseMRZ(text: string): PassportResult {
+  return PetrusReactNative.parseMRZ(text);
+}

package/src/parseMRZ.tsx

@@ -0,0 +1,7 @@
+import type { PassportResult } from './types';
+
+export function parseMRZ(_text: string): PassportResult {
+  throw new Error(
+    "'petrus-react-native' is only supported on native platforms."
+  );
+}

package/src/parseSouthAfricanDriversLicense.native.tsx

@@ -0,0 +1,13 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { SouthAfricanDriversLicenseResult } from './types';
+
+/**
+ * `rawDataBase64` is expected to be already-scanned raw barcode bytes (e.g.
+ * scanPDF417's `rawDataBase64`). Throws if it doesn't decode to a recognized SA
+ * driver's licence barcode format.
+ */
+export function parseSouthAfricanDriversLicense(
+  rawDataBase64: string
+): SouthAfricanDriversLicenseResult {
+  return PetrusReactNative.parseSouthAfricanDriversLicense(rawDataBase64);
+}

package/src/parseSouthAfricanDriversLicense.tsx

@@ -0,0 +1,9 @@
+import type { SouthAfricanDriversLicenseResult } from './types';
+
+export function parseSouthAfricanDriversLicense(
+  _rawDataBase64: string
+): SouthAfricanDriversLicenseResult {
+  throw new Error(
+    "'petrus-react-native' is only supported on native platforms."
+  );
+}

package/src/parseSouthAfricanID.native.tsx

@@ -0,0 +1,7 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { SouthAfricanIDResult } from './types';
+
+/** `text` is expected to be OCR output (e.g. recognizeText's `fullText`). */
+export function parseSouthAfricanID(text: string): SouthAfricanIDResult {
+  return PetrusReactNative.parseSouthAfricanID(text);
+}

package/src/parseSouthAfricanID.tsx

@@ -0,0 +1,7 @@
+import type { SouthAfricanIDResult } from './types';
+
+export function parseSouthAfricanID(_text: string): SouthAfricanIDResult {
+  throw new Error(
+    "'petrus-react-native' is only supported on native platforms."
+  );
+}

package/src/parseVehicleRegistration.native.tsx

@@ -0,0 +1,9 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { VehicleRegistrationResult } from './types';
+
+/** `text` is expected to be OCR output (e.g. recognizeText's `fullText`). */
+export function parseVehicleRegistration(
+  text: string
+): VehicleRegistrationResult {
+  return PetrusReactNative.parseVehicleRegistration(text);
+}

package/src/parseVehicleRegistration.tsx

@@ -0,0 +1,9 @@
+import type { VehicleRegistrationResult } from './types';
+
+export function parseVehicleRegistration(
+  _text: string
+): VehicleRegistrationResult {
+  throw new Error(
+    "'petrus-react-native' is only supported on native platforms."
+  );
+}

package/src/recognizeText.native.tsx

@@ -0,0 +1,7 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { OCRResult } from './types';
+
+/** `imagePath` may be a bare filesystem path or a URI (file://, content://, ...). */
+export function recognizeText(imagePath: string): Promise<OCRResult> {
+  return PetrusReactNative.recognizeText(imagePath);
+}

package/src/recognizeText.tsx

@@ -0,0 +1,7 @@
+import type { OCRResult } from './types';
+
+export function recognizeText(_imagePath: string): Promise<OCRResult> {
+  return Promise.reject(
+    new Error("'petrus-react-native' is only supported on native platforms.")
+  );
+}

package/src/scanPDF417.native.tsx

@@ -0,0 +1,7 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { PDF417ScanResult } from './types';
+
+/** `imagePath` may be a bare filesystem path or a URI (file://, content://, ...). */
+export function scanPDF417(imagePath: string): Promise<PDF417ScanResult> {
+  return PetrusReactNative.scanPDF417(imagePath);
+}

package/src/scanPDF417.tsx

@@ -0,0 +1,7 @@
+import type { PDF417ScanResult } from './types';
+
+export function scanPDF417(_imagePath: string): Promise<PDF417ScanResult> {
+  return Promise.reject(
+    new Error("'petrus-react-native' is only supported on native platforms.")
+  );
+}

package/src/scanPassport.native.tsx

@@ -0,0 +1,12 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { PassportResult } from './types';
+
+/**
+ * Opens a headless (no preview UI) camera session; per frame, detects the
+ * document boundary, crops just the MRZ band, runs OCR on only that crop, and
+ * parses it -- stops once a frame yields a non-empty passport number. Rejects
+ * on timeout (~20s) or if no Activity is available.
+ */
+export function scanPassport(): Promise<PassportResult> {
+  return PetrusReactNative.scanPassport();
+}