petrus-react-native 0.1.0

package/src/scanPassport.tsx

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

package/src/scanSouthAfricanDriversLicense.native.tsx

@@ -0,0 +1,11 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { SouthAfricanDriversLicenseResult } from './types';
+
+/**
+ * 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. Rejects on timeout (~20s) or if
+ * no Activity is available.
+ */
+export function scanSouthAfricanDriversLicense(): Promise<SouthAfricanDriversLicenseResult> {
+  return PetrusReactNative.scanSouthAfricanDriversLicense();
+}

package/src/scanSouthAfricanDriversLicense.tsx

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

package/src/scanVehicleRegistration.native.tsx

@@ -0,0 +1,12 @@
+import PetrusReactNative from './NativePetrusReactNative';
+import type { VehicleRegistrationResult } from './types';
+
+/**
+ * Opens a headless (no preview UI) camera session, runs OCR on frames, and parses
+ * each result as a vehicle registration document -- stops once a frame yields a
+ * registration number or VIN. Rejects on timeout (~20s) or if no Activity is
+ * available.
+ */
+export function scanVehicleRegistration(): Promise<VehicleRegistrationResult> {
+  return PetrusReactNative.scanVehicleRegistration();
+}

package/src/scanVehicleRegistration.tsx

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

package/src/types.ts

@@ -0,0 +1,272 @@
+export type PetrusCameraPermissionStatus = 'granted' | 'denied' | 'blocked';
+
+export interface PetrusFrameMetadata {
+  width: number;
+  height: number;
+  rotation: number;
+  /** Epoch milliseconds. */
+  timestamp: number;
+}
+
+export interface PetrusPoint2D {
+  x: number;
+  y: number;
+}
+
+/**
+ * Corners are normalized (0..1) relative to frameWidth x frameHeight -- the analysis
+ * frame's own (unrotated) buffer space, before rotationDegrees is applied.
+ */
+export interface PetrusDocumentCorners {
+  topLeft: PetrusPoint2D;
+  topRight: PetrusPoint2D;
+  bottomRight: PetrusPoint2D;
+  bottomLeft: PetrusPoint2D;
+  frameWidth: number;
+  frameHeight: number;
+  rotationDegrees: number;
+}
+
+export interface PetrusDocumentDetectedEvent {
+  detected: boolean;
+  isStable: boolean;
+  stableDurationMs: number;
+  confidence: number;
+  /** Meaningless (zeroed) when `detected` is false -- check `detected` first. */
+  corners: PetrusDocumentCorners;
+}
+
+export interface PetrusCapturedEvent {
+  corners: PetrusDocumentCorners;
+  confidence: number;
+  /** Epoch milliseconds. */
+  timestamp: number;
+}
+
+export interface OCRBoundingBox {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+/** One recognized word (ML Kit's finest granularity). */
+export interface OCRWord {
+  text: string;
+  boundingBox: OCRBoundingBox;
+  /** [0, 1]; may read 0 on older Play Services versions -- see README. */
+  confidence: number;
+}
+
+export interface OCRLine {
+  text: string;
+  boundingBox: OCRBoundingBox;
+  /** [0, 1]; may read 0 on older Play Services versions -- see README. */
+  confidence: number;
+  words: OCRWord[];
+}
+
+/** ML Kit reports no confidence at block level -- only OCRLine/OCRWord carry one. */
+export interface OCRBlock {
+  text: string;
+  boundingBox: OCRBoundingBox;
+  lines: OCRLine[];
+}
+
+/**
+ * Raw OCR output: text, geometry, confidence. Deliberately has no notion of document
+ * type or fields -- SA ID/driver's licence/MRZ/PDF417 parsing all consume this from
+ * outside; none of that logic lives in petrus-react-native or petrus-core.
+ */
+export interface OCRResult {
+  fullText: string;
+  /** Average confidence across all recognized words; 0 if none. */
+  confidence: number;
+  blocks: OCRBlock[];
+}
+
+export type SouthAfricanGender = 'male' | 'female';
+
+/** 0 = SA citizen, 1 = permanent resident, 2 = refugee; anything else is 'unknown'. */
+export type SouthAfricanCitizenship =
+  | 'citizen'
+  | 'permanent_resident'
+  | 'refugee'
+  | 'unknown';
+
+export interface SouthAfricanDateOfBirth {
+  year: number;
+  month: number;
+  day: number;
+}
+
+export interface SouthAfricanIDValidation {
+  isValid: boolean;
+  hasValidChecksum: boolean;
+  hasValidDateOfBirth: boolean;
+  hasValidCitizenshipDigit: boolean;
+}
+
+/**
+ * `idNumber` is the best 13-digit candidate found in the text (digit-lookalike-
+ * corrected), even if it failed validation -- `isValid`/`validation` say whether it
+ * actually checks out. `dateOfBirth`/`gender`/`citizenship` are derived straight
+ * from `idNumber`'s digits regardless of checksum validity. All fields are `null`
+ * when no 13-digit candidate was found in the text at all.
+ */
+export interface SouthAfricanIDResult {
+  idNumber: string | null;
+  isValid: boolean;
+  dateOfBirth: SouthAfricanDateOfBirth | null;
+  gender: SouthAfricanGender | null;
+  citizenship: SouthAfricanCitizenship | null;
+  validation: SouthAfricanIDValidation | null;
+}
+
+/**
+ * Raw output of scanning a PDF417 barcode -- no SA-specific interpretation. SA
+ * driver's licence barcodes carry binary (RSA-"encrypted") data, so `rawText` is
+ * rarely human-readable for them; pass `rawDataBase64` to
+ * parseSouthAfricanDriversLicense instead.
+ */
+export interface PDF417ScanResult {
+  /** Base64-encoded raw decoded barcode bytes. */
+  rawDataBase64: string;
+  rawText: string;
+}
+
+/** Which reverse-engineered generation of the SA driver's licence barcode format was detected. */
+export type SouthAfricanDriversLicenseVersion = 'v1' | 'v2';
+
+export interface CalendarDate {
+  year: number;
+  month: number;
+  day: number;
+}
+
+/**
+ * Structured SA driver's licence fields decoded from a PDF417 barcode. See the
+ * README's confidence note on this reverse-engineered format before relying on
+ * these fields in production -- `parseWarnings` flags anything that looked
+ * malformed or implausible while parsing *this* barcode specifically.
+ */
+export interface SouthAfricanDriversLicenseResult {
+  version: SouthAfricanDriversLicenseVersion;
+  surname: string;
+  initials: string;
+  idNumber: string | null;
+  /** Reuses the same SA ID validation used by parseSouthAfricanID. */
+  idNumberValidation: SouthAfricanIDValidation | null;
+  licenseNumber: string;
+  vehicleCodes: string[];
+  vehicleRestrictions: string[];
+  prdpCode: string | null;
+  idCountryOfIssue: string;
+  licenseCountryOfIssue: string;
+  gender: SouthAfricanGender | null;
+  dateOfBirth: CalendarDate | null;
+  licenseIssueNumber: number | null;
+  licenseValidFrom: CalendarDate | null;
+  licenseValidTo: CalendarDate | null;
+  prdpExpiry: CalendarDate | null;
+  driverRestrictionCodes: number[];
+  parseWarnings: string[];
+}
+
+/** Which NATIS/eNaTIS vehicle document type was detected -- see the README's confidence note. */
+export type VehicleDocumentType =
+  | 'registration_certificate'
+  | 'license_disc'
+  | 'notification_of_change'
+  | 'roadworthy_certificate'
+  | 'unknown';
+
+/**
+ * ISO 3779 structural checks (universal) plus an optional North American
+ * (SAE J853/NHTSA) position-9 check digit signal -- NOT universal, since South
+ * Africa isn't a North-American-format vehicle market. `null` when the VIN wasn't
+ * structurally valid to begin with (no check digit to evaluate).
+ */
+export interface VINValidation {
+  hasValidLength: boolean;
+  hasValidCharacterSet: boolean;
+  isStructurallyValid: boolean;
+  northAmericanCheckDigitValid: boolean | null;
+}
+
+export interface VehicleRegistrationValidation {
+  isValid: boolean;
+  hasStructurallyValidVin: boolean;
+  hasPlausibleRegistrationNumber: boolean;
+  hasPlausibleYearModel: boolean;
+}
+
+/**
+ * Structured fields parsed from a NATIS/eNaTIS vehicle registration document. See
+ * the README's confidence note on label wording before relying on these fields in
+ * production -- `parseWarnings` flags anything that looked malformed or
+ * implausible while parsing *this* document specifically. `ownerIdNumber`/
+ * `ownerIdValidation` are a bonus cross-check using the same SA ID validation as
+ * parseSouthAfricanID, when an ID number happens to appear near the owner's name.
+ */
+export interface VehicleRegistrationResult {
+  documentType: VehicleDocumentType;
+  registrationNumber: string | null;
+  vin: string | null;
+  vinValidation: VINValidation | null;
+  engineNumber: string | null;
+  make: string | null;
+  model: string | null;
+  yearModel: number | null;
+  ownerName: string | null;
+  ownerIdNumber: string | null;
+  ownerIdValidation: SouthAfricanIDValidation | null;
+  validation: VehicleRegistrationValidation;
+  parseWarnings: string[];
+}
+
+/** MRZ sex marker. `'unspecified'` covers ICAO 9303's `<` (unspecified) value, not just an OCR failure. */
+export type MRZSex = 'male' | 'female' | 'unspecified';
+
+/**
+ * A date decoded from an MRZ's 2-digit-year `YYMMDD` field, with the century
+ * resolved by `parseMRZ`/`scanPassport` -- ICAO 9303 doesn't itself specify a
+ * resolution rule; see the README's confidence note.
+ */
+export interface MRZDate {
+  year: number;
+  month: number;
+  day: number;
+  twoDigitYear: number;
+}
+
+export interface MRZValidation {
+  isValid: boolean;
+  passportNumberCheckValid: boolean;
+  dateOfBirthCheckValid: boolean;
+  expiryDateCheckValid: boolean;
+  personalNumberCheckValid: boolean;
+  compositeCheckValid: boolean;
+}
+
+/**
+ * Structured fields parsed from an ICAO 9303 TD3 (passport) MRZ. `parseWarnings`
+ * flags anything that looked malformed or implausible while parsing *this*
+ * MRZ -- including "no MRZ found at all", in which case every `string` field is
+ * `""` and the date/personalNumber fields are `null` (this function never
+ * throws/returns null -- see the README's confidence note).
+ */
+export interface PassportResult {
+  documentCode: string;
+  issuingCountry: string;
+  surname: string;
+  givenNames: string;
+  passportNumber: string;
+  nationality: string;
+  dateOfBirth: MRZDate | null;
+  sex: MRZSex;
+  dateOfExpiry: MRZDate | null;
+  personalNumber: string | null;
+  validation: MRZValidation;
+  parseWarnings: string[];
+}