@parselo/capacitor-mrz 0.2.0

package/ParseloCapacitorMrz.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name    = 'ParseloCapacitorMrz'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage    = 'https://github.com/your-org/idscan-canada'
+  s.author      = 'IDScan Canada'
+  s.source      = { :git => 'https://github.com/your-org/idscan-canada.git', :tag => s.version.to_s }
+  s.source_files        = 'ios/**/*.{swift,h,m}'
+  s.ios.deployment_target = '13.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

package/README.md

@@ -0,0 +1,107 @@
+# @parselo/capacitor-mrz
+
+Capacitor plugin for on-device MRZ (Machine Readable Zone) text recognition.
+Wraps Apple Vision (`VNRecognizeTextRequest`) on iOS and ML Kit Text Recognition
+on Android. Returns the recognised text lines; pair with `@parselo/scanner-core`
+to locate, parse, and validate the ICAO 9303 MRZ.
+
+Supports all ICAO TD3 travel document types: standard passports (`P<`),
+emergency travel documents (`PU`), permanent resident travel documents (`PR`),
+and foreign passports.
+
+## Platform support
+
+| Platform | Backend | Min version |
+|---|---|---|
+| iOS | Vision — `VNRecognizeTextRequest`, `.accurate` level | iOS 13 |
+| Android | ML Kit Text Recognition v2, Latin script | API 21 |
+
+Language correction is disabled on both platforms — it would corrupt MRZ
+tokens and check digits.
+
+## Install
+
+```bash
+npm install @parselo/capacitor-mrz @parselo/scanner-core
+npx cap sync
+```
+
+### iOS — camera permission
+
+Add to `ios/App/App/Info.plist` (if not already present):
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Used to scan the MRZ on your travel document.</string>
+```
+
+CocoaPods installs the `MrzPlugin.m` ObjC bridge automatically. If the plugin
+throws "not implemented" at runtime, verify that `pod install` ran after
+`cap sync` and that `MrzPlugin.m` is listed in the Xcode target's Compile
+Sources.
+
+### Android
+
+No extra configuration needed — the ML Kit dependency is declared in the
+plugin's `build.gradle`.
+
+## API
+
+```ts
+import { Mrz } from "@parselo/capacitor-mrz";
+
+const { lines, raw } = await Mrz.recognizeText({ image });
+// lines: string[]  — one element per Vision/ML Kit text observation
+// raw:   string    — lines joined with "\n"
+```
+
+`image` accepts a `data:` URI, `file://` URI, bare absolute path, or raw base64 string.
+
+Pass the full camera frame — the plugin sends the entire image to the OCR
+engine. `scanner-core` locates the two 44-char MRZ lines anywhere in the
+returned array and handles OCR noise in the surrounding biographical text.
+
+## Integration with scanner-core
+
+```ts
+import { Scanner } from "@parselo/scanner-core";
+import { Mrz }     from "@parselo/capacitor-mrz";
+
+const scanner = new Scanner({
+  license: {
+    token:      "…",
+    bundleId:   "com.example.app",
+    publicKeys: { "<kid>": "<base64-spki>" },
+  },
+  analytics: {
+    ingestUrl: "…",
+    store: { get, set },
+  },
+  native:    { captureAndDecodePdf417: … },  // still needed for barcode scanning
+  mrzNative: {
+    captureAndRecognizeMrz: async () => {
+      const { lines } = await Mrz.recognizeText({ image: dataUrl });
+      return lines;
+    },
+  },
+});
+
+await scanner.init();
+const result = await scanner.scanPassport();
+// result.document.documentType === "passport"
+// result.document.fields.firstName.value, .dateOfBirth.value, .country.value, …
+```
+
+### How name extraction works
+
+OCR-B MRZ uses `<` as a word separator, which Vision and ML Kit frequently
+misread as `C`, `S`, `K`, `@`, etc. `scanner-core` automatically cross-references
+Vision's biographical-zone lines (the human-readable area above the MRZ, read
+in a standard font) to recover correct first and last names even when the MRZ
+separator characters are corrupted.
+
+See the [full integration guide](https://github.com/parselo-io/parselo-sdk/blob/main/integration-guide.md) for a complete setup walkthrough including the camera UI component.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,49 @@
+// Android build for @parselo/capacitor-mrz.
+// SDK/AGP/Kotlin versions fall back to the host app's rootProject.ext when synced.
+
+ext {
+    mrzMlkitVersion = project.hasProperty('mlkitTextVersion') ? rootProject.ext.mlkitTextVersion : '16.0.1'
+}
+
+buildscript {
+    ext.kotlin_version = project.hasProperty('kotlinVersion') ? rootProject.ext.kotlinVersion : '1.9.25'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.2.1'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace "com.parselo.mrz"
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 34
+    defaultConfig {
+        minSdkVersion    project.hasProperty('minSdkVersion')    ? rootProject.ext.minSdkVersion    : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 34
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    // ML Kit Text Recognition v2 — Latin script; no network call, fully on-device.
+    implementation "com.google.mlkit:text-recognition:$mrzMlkitVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- No permissions declared here: the plugin receives an already-captured
+         image and runs text recognition on it. Camera permission is the app's
+         responsibility, not the plugin's. -->
+</manifest>

package/android/src/main/java/com/parselo/mrz/MrzPlugin.kt

@@ -0,0 +1,72 @@
+package com.parselo.mrz
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.net.Uri
+import android.util.Base64
+import com.getcapacitor.JSArray
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import com.google.mlkit.vision.common.InputImage
+import com.google.mlkit.vision.text.TextRecognition
+import com.google.mlkit.vision.text.latin.TextRecognizerOptions
+
+@CapacitorPlugin(name = "Mrz")
+class MrzPlugin : Plugin() {
+
+    @PluginMethod
+    fun recognizeText(call: PluginCall) {
+        val imageStr = call.getString("image") ?: run {
+            call.reject("Missing 'image'"); return
+        }
+        val bitmap = loadBitmap(imageStr) ?: run {
+            call.reject("Could not load image from the provided string"); return
+        }
+        recognize(bitmap) { lines ->
+            val arr = JSArray()
+            lines.forEach { arr.put(it) }
+            val ret = JSObject()
+            ret.put("lines", arr)
+            ret.put("raw", lines.joinToString("\n"))
+            call.resolve(ret)
+        }
+    }
+
+    // ML Kit Text Recognition v2, Latin script, fully on-device.
+    private fun recognize(bitmap: Bitmap, callback: (List<String>) -> Unit) {
+        val recognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS)
+        val image = InputImage.fromBitmap(bitmap, 0)
+        recognizer.process(image)
+            .addOnSuccessListener { result ->
+                // Flatten to one entry per line so scanner-core can scan
+                // the array for consecutive 44-char TD3 lines.
+                val lines = result.textBlocks.flatMap { block ->
+                    block.lines.map { line -> line.text }
+                }
+                callback(lines)
+            }
+            .addOnFailureListener { callback(emptyList()) }
+    }
+
+    // Image loading: file path, file:// URI, data: URI, or bare base64.
+    private fun loadBitmap(s: String): Bitmap? {
+        return try {
+            when {
+                s.startsWith("data:") -> {
+                    val b64   = s.substringAfter(",", "")
+                    val bytes = Base64.decode(b64, Base64.DEFAULT)
+                    BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
+                }
+                s.startsWith("file://") -> BitmapFactory.decodeFile(Uri.parse(s).path)
+                s.startsWith("/")       -> BitmapFactory.decodeFile(s)
+                else -> {
+                    val bytes = Base64.decode(s, Base64.DEFAULT)
+                    BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
+                }
+            }
+        } catch (e: Exception) { null }
+    }
+}

package/dist/definitions.d.ts

@@ -0,0 +1,16 @@
+export interface MrzPlugin {
+    /**
+     * Run on-device text recognition on an image and return all detected lines.
+     * Pass the result to scanner-core's parseMrz() to locate and parse the MRZ.
+     *
+     * @param options.image  file path, file:// URI, data: URI, or bare base64 string
+     * @returns lines  — every text line detected by Vision / ML Kit
+     * @returns raw    — lines joined by "\n" (convenience for logging/debugging)
+     */
+    recognizeText(options: {
+        image: string;
+    }): Promise<{
+        lines: string[];
+        raw: string;
+    }>;
+}

package/dist/definitions.js

@@ -0,0 +1,6 @@
+// definitions.ts
+// Capacitor plugin interface for native MRZ text recognition.
+// The plugin recognises text in an image and returns all detected lines.
+// scanner-core is responsible for locating the MRZ within those lines and
+// parsing it — keeping all parsing logic cross-platform in the TS core.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { MrzPlugin } from "./definitions";
+declare const Mrz: MrzPlugin;
+export * from "./definitions";
+export { Mrz };

package/dist/index.js

@@ -0,0 +1,7 @@
+// index.ts
+import { registerPlugin } from "@capacitor/core";
+const Mrz = registerPlugin("Mrz", {
+    web: () => import("./web").then((m) => new m.MrzWeb()),
+});
+export * from "./definitions";
+export { Mrz };

package/dist/web.d.ts

@@ -0,0 +1,8 @@
+import { WebPlugin } from "@capacitor/core";
+import type { MrzPlugin } from "./definitions";
+export declare class MrzWeb extends WebPlugin implements MrzPlugin {
+    recognizeText(): Promise<{
+        lines: string[];
+        raw: string;
+    }>;
+}

package/dist/web.js

@@ -0,0 +1,7 @@
+// web.ts
+import { WebPlugin } from "@capacitor/core";
+export class MrzWeb extends WebPlugin {
+    async recognizeText() {
+        throw this.unimplemented("MRZ text recognition is native-only — run on a device.");
+    }
+}

package/ios/MrzPlugin.m

@@ -0,0 +1,7 @@
+#import <Foundation/Foundation.h>
+#import <Capacitor/Capacitor.h>
+
+// Registers the Swift plugin with Capacitor and exposes its methods to JS.
+CAP_PLUGIN(MrzPlugin, "Mrz",
+    CAP_PLUGIN_METHOD(recognizeText, CAPPluginReturnPromise);
+)

package/ios/MrzPlugin.swift

@@ -0,0 +1,100 @@
+import Foundation
+import Capacitor
+import Vision
+import UIKit
+
+@objc(MrzPlugin)
+public class MrzPlugin: CAPPlugin {
+
+    @objc func recognizeText(_ call: CAPPluginCall) {
+        guard let imageStr = call.getString("image") else {
+            print("[MrzPlugin] ERROR: Missing 'image' parameter")
+            call.reject("Missing 'image'")
+            return
+        }
+        print("[MrzPlugin] recognizeText called, image string length: \(imageStr.count)")
+        guard let image = Self.loadImage(imageStr) else {
+            print("[MrzPlugin] ERROR: Could not load image from the provided string")
+            call.reject("Could not load image from the provided string")
+            return
+        }
+        print("[MrzPlugin] Image loaded: \(Int(image.size.width))×\(Int(image.size.height)), orientation: \(image.imageOrientation.rawValue)")
+        Self.recognize(in: image) { lines in
+            print("[MrzPlugin] Vision returned \(lines.count) line(s):")
+            lines.enumerated().forEach { i, l in print("[MrzPlugin]   [\(i)] (\(l.count) chars): \(l)") }
+            call.resolve([
+                "lines": lines,
+                "raw":   lines.joined(separator: "\n"),
+            ])
+        }
+    }
+
+    // MARK: - Vision text recognition
+
+    private static func recognize(in image: UIImage, completion: @escaping ([String]) -> Void) {
+        guard let cgImage = image.cgImage else { completion([]); return }
+
+        let request = VNRecognizeTextRequest { req, err in
+            if let err = err {
+                print("[MrzPlugin] Vision error: \(err.localizedDescription)")
+                completion([]); return
+            }
+            guard let results = req.results as? [VNRecognizedTextObservation] else {
+                print("[MrzPlugin] Vision: no results")
+                completion([]); return
+            }
+            print("[MrzPlugin] Vision: \(results.count) text observation(s)")
+            let lines = results.compactMap { $0.topCandidates(1).first?.string }
+            completion(lines)
+        }
+        // Accurate mode is required for MRZ — fast mode misses characters.
+        request.recognitionLevel = .accurate
+        // Language correction must be off: it replaces valid MRZ tokens (e.g. "<<")
+        // with natural-language words and corrupts check digits.
+        request.usesLanguageCorrection = false
+        request.recognitionLanguages   = ["en-US"]
+
+        let orientation = cgOrientation(from: image.imageOrientation)
+        let handler = VNImageRequestHandler(cgImage: cgImage, orientation: orientation, options: [:])
+        do {
+            try handler.perform([request])
+        } catch {
+            completion([])
+        }
+    }
+
+    // MARK: - Image loading (file path, file:// URI, data: URI, or bare base64)
+
+    private static func loadImage(_ s: String) -> UIImage? {
+        if s.hasPrefix("data:") {
+            guard let comma = s.firstIndex(of: ","),
+                  let data  = Data(base64Encoded: String(s[s.index(after: comma)...])) else { return nil }
+            return UIImage(data: data)
+        }
+        if s.hasPrefix("file://") {
+            guard let path = URL(string: s)?.path else { return nil }
+            return UIImage(contentsOfFile: path)
+        }
+        if s.hasPrefix("/") {
+            return UIImage(contentsOfFile: s)
+        }
+        if let data = Data(base64Encoded: s) {
+            return UIImage(data: data)
+        }
+        return nil
+    }
+
+    private static func cgOrientation(from o: UIImage.Orientation) -> CGImagePropertyOrientation {
+        switch o {
+        case .up:            return .up
+        case .down:          return .down
+        case .left:          return .left
+        case .right:         return .right
+        case .upMirrored:    return .upMirrored
+        case .downMirrored:  return .downMirrored
+        case .leftMirrored:  return .leftMirrored
+        case .rightMirrored: return .rightMirrored
+        @unknown default:    return .up
+        }
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@parselo/capacitor-mrz",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/parselo-io/parselo-sdk.git",
+    "directory": "packages/capacitor-mrz"
+  },
+  "description": "Native MRZ text recognition (Apple Vision / Android ML Kit) for Capacitor. Returns recognised lines; scanner-core locates and parses the MRZ.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "ios/",
+    "android/",
+    "ParseloCapacitorMrz.podspec",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    },
+    "android": {
+      "src": "android"
+    }
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^6.0.0"
+  },
+  "devDependencies": {
+    "@capacitor/core": "^6.0.0",
+    "typescript": "^5.5.0"
+  }
+}