@solidus-network/id-extract

Client-side (browser WASM) ID-document extraction: barcode decode + MRZ OCR with checksum-validated reconstruction. Framework-free, dependency-light, both WASM engines lazy — nothing heavy loads at import. This is the extraction core inside @solidus-network/capture; use it directly when you already have your own capture UI.

npm i @solidus-network/id-extract

Usage

import { extractDocument } from '@solidus-network/id-extract'

// image: File | Blob | ArrayBuffer | Uint8Array | ImageData | canvas | URL string
const result = await extractDocument(image, { docType: 'national-id', side: 'back' })

if (result.fields) {
  // checksum-valid MRZ read — safe to autofill
  console.log(result.fields.firstName, result.fields.lastName, result.fields.birthDate)
} else if (result.barcodes.length > 0) {
  // error-corrected barcode payloads (PDF417 / QR / DataMatrix / Code128)
  console.log(result.barcodes)
} else {
  // result.needsServerFallback === true — route the raw frame to your own
  // server OCR; nothing on-device was checksum-valid
}

Data-source priority: barcode > MRZ — error-corrected symbologies beat OCR. MRZ reads pass through a ported, test-covered checksum-reconstruction: only reads whose ICAO check digits validate on the actually-OCR'd characters return fields; everything else honestly reports confidence: 'low', needsServerFallback: true.

What it covers — honestly

• TD1 (ID-1 cards — national IDs, residence permits, many driving licenses): full on-device MRZ reconstruction with check-digit validation and single-character error correction.
• TD3 (passports) / TD2: not reconstructed on-device yet. OCR candidate lines are returned in rawLines, but fields stays null — ride your server fallback for passports today.
• Barcodes are decoded, not parsed — { format, text }, no AAMVA field mapping.
• OCR quality depends on the input frame: feed the MRZ band at ≥ ~1500 px width for reliable reads (the @solidus-network/capture widget's guide/crop does this for you).

Engine loading

• zxing-wasm/reader and tesseract.js are dynamic imports — first call pays the boot, later calls reuse a singleton worker (getMrzWorker() / terminateMrzWorker() are exported for control).
• tesseract.js fetches its WASM core + eng.traineddata from its package defaults (network, a few MB, browser-cached). Self-host via extractDocument(image, { ocr: { langPath, cachePath, gzip } }).
• Works in Node too (pass a Buffer/Uint8Array of an encoded image) — handy for tests.

Exports

extractDocument — the one-call pipeline above. Lower-level pieces: readDocumentBarcodes, recognizeMrz, filterMrzCandidates, reconstructTd1, gradeReconstruction, preprocessBand (+ grayscale, contrastStretch, cropBand — pure RGBA helpers).

Status

0.1.x beta. No accuracy numbers are quoted because we have not published measured ones. Apache-2.0.