usa-dl-ocr 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sepehr Mohseni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# usa-dl-ocr
+
+[![npm version](https://img.shields.io/npm/v/usa-dl-ocr.svg)](https://www.npmjs.com/package/usa-dl-ocr)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+Framework-agnostic OCR extraction for USA driver licenses. Feed it an image, get structured data back.
+
+## Why This Exists
+
+Parsing driver licenses shouldn't require vendor lock-in or framework coupling. This library provides a single, clean interface that works identically whether you're building a React app, an Express server, a CLI tool, or anything else. No adapters, no plugins, no boilerplate.
+
+## Installation
+
+```bash
+npm install usa-dl-ocr
+```
+
+For CLI usage:
+```bash
+npm install usa-dl-ocr commander
+```
+
+## Quick Start
+
+```typescript
+import { extract } from 'usa-dl-ocr';
+
+const result = await extract(imageBlob);
+
+console.log(result.data.licenseNumber);  // "D1234567"
+console.log(result.data.dateOfBirth);    // "1990-01-15"
+console.log(result.data.fullName);       // "JOHN DOE"
+```
+
+That's it. No setup, no configuration, no framework integration code.
+
+## API
+
+### `extract(image, options?)`
+
+One-shot extraction. Creates a worker, processes the image, terminates the worker.
+
+```typescript
+import { extract } from 'usa-dl-ocr';
+
+// From file path (Node.js)
+const result = await extract('/path/to/license.jpg');
+
+// From URL
+const result = await extract('https://example.com/license.jpg');
+
+// From Blob/File (browser)
+const result = await extract(fileInput.files[0]);
+
+// From Buffer (Node.js)
+const result = await extract(fs.readFileSync('license.jpg'));
+
+// From ArrayBuffer or Uint8Array
+const result = await extract(arrayBuffer);
+```
+
+### `DriverLicenseOCR` Class
+
+Same functionality, class-based interface if you prefer it.
+
+```typescript
+import { DriverLicenseOCR } from 'usa-dl-ocr';
+
+const ocr = new DriverLicenseOCR({ language: 'eng', timeout: 30000 });
+const result = await ocr.extract(image);
+```
+
+### `createOCR(options?)`
+
+Persistent worker for batch processing. Significantly faster when processing multiple images.
+
+```typescript
+import { createOCR } from 'usa-dl-ocr';
+
+const ocr = await createOCR();
+
+for (const image of images) {
+  const result = await ocr.extract(image);
+  // Process result
+}
+
+await ocr.terminate(); // Clean up when done
+```
+
+### `validate(data)`
+
+Check extraction completeness.
+
+```typescript
+import { extract, validate } from 'usa-dl-ocr';
+
+const { data } = await extract(image);
+const validation = validate(data);
+
+if (!validation.isValid) {
+  console.log('Missing fields:', validation.issues);
+  console.log('Completeness score:', validation.score);
+}
+```
+
+## Options
+
+```typescript
+interface ExtractOptions {
+  language?: string;      // Tesseract language code (default: 'eng')
+  timeout?: number;       // Timeout in ms (default: 60000)
+  psm?: number;          // Page segmentation mode (default: 3)
+  oem?: number;          // OCR engine mode (default: 1)
+  workerPath?: string;   // Custom Tesseract worker path
+  corePath?: string;     // Custom Tesseract core path
+  langPath?: string;     // Custom language data path
+  onProgress?: (info: ProgressInfo) => void;
+}
+```
+
+## Extracted Fields
+
+```typescript
+interface DriverLicenseData {
+  fullName: string | null;
+  firstName: string | null;
+  middleName: string | null;
+  lastName: string | null;
+  licenseNumber: string | null;
+  dateOfBirth: string | null;      // ISO format: YYYY-MM-DD
+  expirationDate: string | null;   // ISO format: YYYY-MM-DD
+  issueDate: string | null;        // ISO format: YYYY-MM-DD
+  address: AddressInfo | null;
+  sex: 'M' | 'F' | null;
+  height: string | null;           // e.g., "5'10\""
+  weight: string | null;           // e.g., "180 lbs"
+  eyeColor: string | null;
+  hairColor: string | null;
+  issuingState: string | null;     // 2-letter code
+  licenseClass: string | null;
+  restrictions: string[];
+  endorsements: string[];
+  documentDiscriminator: string | null;
+  rawText: string;
+  confidence: number;              // 0-100
+}
+```
+
+## CLI
+
+```bash
+# Basic usage
+usa-dl-ocr license.jpg
+
+# Output formats
+usa-dl-ocr license.jpg --format json
+usa-dl-ocr license.jpg --format text
+usa-dl-ocr license.jpg --format table
+
+# Save to file
+usa-dl-ocr license.jpg -o result.json
+
+# Verbose with progress
+usa-dl-ocr license.jpg -v
+
+# Include raw OCR text
+usa-dl-ocr license.jpg -r
+
+# Custom timeout
+usa-dl-ocr license.jpg -t 30000
+```
+
+## Platform Support
+
+Works anywhere JavaScript runs:
+
+- **Node.js** ≥18.0.0
+- **Browsers**: Chrome, Firefox, Safari, Edge (modern versions)
+- **Electron**
+- **Deno** (with Node compatibility)
+- **Bun**
+
+## Image Requirements
+
+For best results:
+
+- Resolution: 300+ DPI
+- Format: JPEG, PNG, WebP, BMP, TIFF, GIF
+- Size: Under 10MB
+- Quality: Clear, in-focus, evenly lit
+- Orientation: Horizontal, minimal skew
+
+## Security
+
+- Input validation with size limits (10MB max)
+- URL validation for remote images
+- Text sanitization (control character removal)
+- No eval, no dynamic code execution
+- No network requests except to provided URLs
+- Timeout protection against hung operations
+
+## Performance Notes
+
+- First extraction takes longer due to Tesseract initialization (~2-5s)
+- Subsequent extractions with `createOCR()` are faster (~0.5-2s)
+- Higher resolution images take longer but produce better results
+- Consider resizing very large images client-side before processing
+
+## Limitations
+
+- OCR accuracy depends heavily on image quality
+- Damaged, faded, or obscured licenses may not parse correctly
+- Non-standard license formats may have lower extraction rates
+- Real-time processing not suitable for high-volume applications
+
+## Error Handling
+
+```typescript
+import { extract } from 'usa-dl-ocr';
+
+try {
+  const result = await extract(image);
+  
+  if (!result.isDriverLicense) {
+    // Image may not be a driver license
+  }
+  
+  if (result.warnings.length > 0) {
+    // Some fields couldn't be extracted
+  }
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    // OCR took too long
+  } else if (error.message.includes('exceeds maximum size')) {
+    // Image too large
+  } else if (error.message.includes('Unsupported')) {
+    // Invalid input type
+  }
+}
+```
+
+## Contributing
+
+Issues and PRs welcome at [github.com/sepehr-mohseni/usa-dl-ocr](https://github.com/sepehr-mohseni/usa-dl-ocr).
+
+## License
+
+MIT © [Sepehr Mohseni](https://github.com/sepehr-mohseni)
+
+---
+
+**Note**: This library performs local OCR processing. No data is sent to external servers. All processing happens in-browser or in your Node.js process.

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';var fs=require('fs'),path=require('path'),_=require('tesseract.js');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var ___default=/*#__PURE__*/_interopDefault(_);var E=Object.freeze({AL:"Alabama",AK:"Alaska",AZ:"Arizona",AR:"Arkansas",CA:"California",CO:"Colorado",CT:"Connecticut",DE:"Delaware",FL:"Florida",GA:"Georgia",HI:"Hawaii",ID:"Idaho",IL:"Illinois",IN:"Indiana",IA:"Iowa",KS:"Kansas",KY:"Kentucky",LA:"Louisiana",ME:"Maine",MD:"Maryland",MA:"Massachusetts",MI:"Michigan",MN:"Minnesota",MS:"Mississippi",MO:"Missouri",MT:"Montana",NE:"Nebraska",NV:"Nevada",NH:"New Hampshire",NJ:"New Jersey",NM:"New Mexico",NY:"New York",NC:"North Carolina",ND:"North Dakota",OH:"Ohio",OK:"Oklahoma",OR:"Oregon",PA:"Pennsylvania",RI:"Rhode Island",SC:"South Carolina",SD:"South Dakota",TN:"Tennessee",TX:"Texas",UT:"Utah",VT:"Vermont",VA:"Virginia",WA:"Washington",WV:"West Virginia",WI:"Wisconsin",WY:"Wyoming",DC:"District of Columbia"}),A=Object.freeze(Object.keys(E)),D=Object.freeze({BLK:"Black",BLU:"Blue",BRO:"Brown",GRY:"Gray",GRN:"Green",HAZ:"Hazel",MAR:"Maroon",PNK:"Pink",DIC:"Dichromatic",UNK:"Unknown"}),R=Object.freeze({BAL:"Bald",BLK:"Black",BLN:"Blonde",BRO:"Brown",GRY:"Gray",RED:"Red",SDY:"Sandy",WHI:"White",UNK:"Unknown"}),c=Object.freeze({NAME:["NAME","FN","FULL NAME","NM"],FIRST_NAME:["FIRST","FIRST NAME","FN","GIVEN NAME","1"],MIDDLE_NAME:["MIDDLE","MIDDLE NAME","MN","2"],LAST_NAME:["LAST","LAST NAME","LN","FAMILY NAME","SURNAME","3"],LICENSE_NUMBER:["DL","LIC","LICENSE","DL NO","LIC NO","LICENSE NO","DRIVER LICENSE","DLN","4D"],CLASS:["CLASS","CLS","9"],DOB:["DOB","DATE OF BIRTH","BIRTH DATE","BD","BORN","3"],EXPIRATION:["EXP","EXPIRES","EXPIRATION","EXP DATE","4B"],ISSUE_DATE:["ISS","ISSUED","ISSUE DATE","4A"],SEX:["SEX","GENDER","S","11"],HEIGHT:["HT","HEIGHT","15"],WEIGHT:["WT","WEIGHT","16"],EYES:["EYES","EYE","EYE COLOR","14"],HAIR:["HAIR","HAIR COLOR","13"],ADDRESS:["ADDRESS","ADDR","ADD","8"],RESTRICTIONS:["RESTR","RESTRICTIONS","REST","12"],ENDORSEMENTS:["END","ENDORSEMENTS","ENDORSE","10"],DD:["DD","DAQ","DOCUMENT DISCRIMINATOR","AUDIT"]}),p=10*1024*1024,O=6e4;function b(s){return typeof s!="string"?"":s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g,"")}function T(s){let t=b(s),e=t.toUpperCase(),r=t.split(`
+`).map(n=>n.trim()).filter(Boolean);return {fullName:C(r,e),firstName:d(r,c.FIRST_NAME),middleName:d(r,c.MIDDLE_NAME),lastName:d(r,c.LAST_NAME),licenseNumber:M(e),dateOfBirth:I(e,c.DOB),expirationDate:I(e,c.EXPIRATION),issueDate:I(e,c.ISSUE_DATE),address:B(r,e),sex:$(e),height:P(e),weight:U(e),eyeColor:v(e),hairColor:k(e),issuingState:H(e),licenseClass:d(r,c.CLASS),restrictions:x(e,c.RESTRICTIONS),endorsements:x(e,c.ENDORSEMENTS),documentDiscriminator:d(r,c.DD),rawText:t,confidence:0}}function C(s,t){for(let e of c.NAME){let r=new RegExp(`${m(e)}[:\\s]+([A-Z][A-Z'\\-]+),\\s*([A-Z][A-Z'\\s.-]+)`,"i"),n=t.match(r);if(n?.[1]&&n[2])return S(`${n[2]} ${n[1]}`)}for(let e of c.NAME){let r=new RegExp(`${m(e)}[:\\s]+([A-Z][A-Z\\s,.-]+)`,"i"),n=t.match(r);if(n?.[1])return S(n[1])}for(let e of s){let r=e.match(/^([A-Z][A-Z'-]+),\s*([A-Z][A-Z'\s.-]+)$/i);if(r?.[1]&&r[2])return S(`${r[2]} ${r[1]}`)}return null}function d(s,t){for(let e of t){let r=new RegExp(`(?:^|\\s)${m(e)}[:\\s]+([^\\n]+)`,"i");for(let n of s){let i=n.match(r);if(i?.[1])return i[1].trim()}}return null}function M(s){for(let e of c.LICENSE_NUMBER){let r=new RegExp(`${m(e)}[:\\s#]*([A-Z0-9-]{6,15})`,"i"),n=s.match(r);if(n?.[1]){let i=n[1].replace(/[^A-Z0-9]/gi,"");if(i.length>=6&&i.length<=15)return i}}return s.match(/\b([A-Z]\d{7,12}|\d{7,12}|[A-Z]{2}\d{6,10})\b/)?.[1]??null}function I(s,t){for(let e of t){let r=new RegExp(`${m(e)}[:\\s]*([\\d/\\-]+)`),n=s.match(r);if(n?.[1]){let i=y(n[1]);if(i)return i}}return null}function y(s){let t=s.match(/(\d{1,2})[\/\-](\d{1,2})[\/\-](\d{4})/);if(t?.[1]&&t[2]&&t[3]){let e=t[1].padStart(2,"0"),r=t[2].padStart(2,"0");if(N(t[3],e,r))return `${t[3]}-${e}-${r}`}return t=s.match(/(\d{4})[\/\-](\d{2})[\/\-](\d{2})/),t?.[1]&&t[2]&&t[3]&&N(t[1],t[2],t[3])?`${t[1]}-${t[2]}-${t[3]}`:(t=s.match(/^(\d{2})(\d{2})(\d{4})$/),t?.[1]&&t[2]&&t[3]&&N(t[3],t[1],t[2])?`${t[3]}-${t[1]}-${t[2]}`:null)}function N(s,t,e){let r=parseInt(s,10),n=parseInt(t,10),i=parseInt(e,10);if(r<1900||r>2100||n<1||n>12||i<1||i>31)return  false;let a=new Date(r,n-1,i);return a.getFullYear()===r&&a.getMonth()===n-1&&a.getDate()===i}function B(s,t){let e=null,r=null,n=null,i=null,a=t.match(/\b(\d{5}-\d{4})\b/)||t.match(/\b(\d{5})\b/);a?.[1]&&(i=a[1]);let o=t.match(/\b(\d+\s+[A-Z0-9\s]+(?:ST|STREET|AVE|AVENUE|BLVD|BOULEVARD|RD|ROAD|DR|DRIVE|LN|LANE|CT|COURT|WAY|PL|PLACE|CIR|CIRCLE))\b/);o?.[1]&&(e=o[1].trim());let f=t.match(/\n([A-Z][A-Z\s]+)[,\s]+([A-Z]{2})\s+(\d{5}(?:-\d{4})?)/);if(f?.[1]&&f[2]&&f[3])r=f[1].trim(),n=f[2],i=f[3];else {let l=t.match(/([A-Z][A-Z\s]{2,20}),\s*([A-Z]{2})\s+(\d{5}(?:-\d{4})?)/);if(l?.[1]&&l[2]&&l[3]){let h=l[1].trim();!h.match(/^\d+\s+/)&&(!e||!h.includes(e))&&(r=h,n=l[2],i=l[3]);}}if(!e&&!r&&!n&&!i)return null;let u=[e,r,n,i].filter(Boolean);return {street:e,city:r,state:n,zipCode:i,full:u.length>0?u.join(", "):null}}function $(s){for(let t of c.SEX){let e=new RegExp(`${m(t)}[:\\s]*(M|F|MALE|FEMALE)\\b`,"i"),r=s.match(e);if(r?.[1]){let n=r[1].toUpperCase();if(n==="M"||n==="MALE")return "M";if(n==="F"||n==="FEMALE")return "F"}}return null}function P(s){let t=[/HT[:\s]*(\d)'(\d{1,2})"/,/HT[:\s]*(\d)-(\d{1,2})/,/HT[:\s]*(\d)(\d{2})\b/,/HEIGHT[:\s]*(\d)'(\d{1,2})"/];for(let e of t){let r=s.match(e);if(r?.[1]&&r[2]){let n=parseInt(r[1],10),i=parseInt(r[2],10);if(n>=3&&n<=8&&i>=0&&i<=11)return `${n}'${i}"`}}return null}function U(s){let t=[/WT[:\s]*(\d{2,3})\s*(?:LBS?)?/i,/WEIGHT[:\s]*(\d{2,3})/i];for(let e of t){let r=s.match(e);if(r?.[1]){let n=parseInt(r[1],10);if(n>=50&&n<=500)return `${n} lbs`}}return null}function v(s){for(let t of c.EYES){let e=new RegExp(`${m(t)}[:\\s]+([A-Z]{2,4})\\b`,"i"),r=s.match(e);if(r?.[1]){let n=r[1].toUpperCase();if(n==="COLOR"||n==="COLO")continue;return D[n]??n}}return null}function k(s){for(let t of c.HAIR){let e=new RegExp(`${m(t)}[:\\s]+([A-Z]{2,4})\\b`,"i"),r=s.match(e);if(r?.[1]){let n=r[1].toUpperCase();if(n==="COLOR"||n==="COLO")continue;return R[n]??n}}return null}function H(s){for(let[r,n]of Object.entries(E))if(s.includes(n.toUpperCase()))return r;let t=/\b([A-Z]{2})\s+DRIVER(?:'?S)?\s+LICENSE/,e=s.match(t);return e?.[1]&&A.includes(e[1])?e[1]:null}function x(s,t){let e=[];for(let r of t){let n=new RegExp(`\\b${m(r)}[:\\s]+([A-Z0-9,\\s]+?)(?:\\n|$)`,"i"),i=s.match(n);if(i?.[1]){let a=i[1].trim();if(a.toUpperCase()==="NONE")return [];let o=a.split(/[,\s]+/).filter(f=>{let u=f.toUpperCase();return u.length>0&&u.length<=3&&!u.match(/^(RESTR|ICTIONS|ENDOR|SEMENTS|NONE)$/i)});e.push(...o);}}return [...new Set(e)]}function S(s){return s.replace(/[^A-Z\s,.-]/gi,"").replace(/\s+/g," ").trim()}function m(s){return s.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function L(s){let t=s.toUpperCase(),e=0,r=[/DRIVER(?:'?S)?\s*LICENSE/,/OPERATOR(?:'?S)?\s*LICENSE/,/IDENTIFICATION\s*CARD/,/\bDL\b/,/\bDOB\b/,/\bEXP(?:IRES?)?\b/,/CLASS\s*[A-Z]/];for(let n of r)n.test(t)&&e++;for(let n of Object.values(E))if(t.includes(n.toUpperCase())){e++;break}return /\d{1,2}[\/\-]\d{1,2}[\/\-]\d{4}/.test(s)&&e++,e>=2}var g=class{constructor(t={}){this.options={language:"eng",psm:3,oem:1,timeout:O,...t};}async extract(t){let e=Date.now(),r=[],n=await this.prepareImage(t),i={};this.options.workerPath&&(i.workerPath=this.options.workerPath),this.options.corePath&&(i.corePath=this.options.corePath),this.options.langPath&&(i.langPath=this.options.langPath),this.options.onProgress&&(i.logger=o=>{this.options.onProgress?.({status:o.status,progress:o.progress});});let a=await ___default.default.createWorker(this.options.language??"eng",this.options.oem??1,i);try{await a.setParameters({tessedit_pageseg_mode:String(this.options.psm??3)});let o=a.recognize(n),f=new Promise((J,w)=>{setTimeout(()=>w(new Error("OCR timeout exceeded")),this.options.timeout);}),{data:u}=await Promise.race([o,f]),l=T(u.text);l.confidence=Math.round(u.confidence);let h=L(u.text);return h||r.push("Image may not be a driver license"),l.licenseNumber||r.push("License number not detected"),!l.fullName&&!l.firstName&&!l.lastName&&r.push("Name not detected"),l.dateOfBirth||r.push("Date of birth not detected"),{data:l,processingTimeMs:Date.now()-e,isDriverLicense:h,warnings:r}}finally{await a.terminate();}}async prepareImage(t){if(typeof t=="string"){if(t.length>2048)throw new Error("URL/path too long");if(t.startsWith("http://")||t.startsWith("https://"))try{new URL(t);}catch{throw new Error("Invalid URL")}return t}if(typeof Blob<"u"&&t instanceof Blob){if(t.size>p)throw new Error(`Image exceeds maximum size of ${p/1024/1024}MB`);return t}if(typeof Buffer<"u"&&Buffer.isBuffer(t)){if(t.length>p)throw new Error(`Image exceeds maximum size of ${p/1024/1024}MB`);return t}if(t instanceof ArrayBuffer){if(t.byteLength>p)throw new Error(`Image exceeds maximum size of ${p/1024/1024}MB`);return typeof Buffer<"u"?Buffer.from(t):t}if(t instanceof Uint8Array){if(t.byteLength>p)throw new Error(`Image exceeds maximum size of ${p/1024/1024}MB`);if(typeof Buffer<"u")return Buffer.from(t.buffer,t.byteOffset,t.byteLength);let e=t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength);return new Blob([e])}throw new Error("Unsupported image input type")}};var j="1.0.0",Y=new Set([".jpg",".jpeg",".png",".bmp",".gif",".webp",".tiff",".tif"]);async function G(){let s;try{s=(await import('commander')).Command;}catch{console.error("Error: commander package required for CLI"),console.error("Install with: npm install commander"),process.exit(1);}let t=new s;t.name("usa-dl-ocr").description("Extract data from USA driver license images").version(j).argument("<image>","Image file path").option("-o, --output <file>","Output file").option("-f, --format <fmt>","Output format: json|text|table","json").option("-v, --verbose","Verbose output",false).option("-r, --raw","Include raw OCR text",false).option("-l, --language <lang>","OCR language","eng").option("-t, --timeout <ms>","Timeout in ms","60000").action(async(e,r)=>{try{await X(e,{...r,timeout:parseInt(String(r.timeout),10)});}catch(n){console.error(`Error: ${n instanceof Error?n.message:"Unknown error"}`),process.exit(1);}}),t.parse();}async function X(s,t){let e=path.resolve(s);if(!fs.existsSync(e))throw new Error(`File not found: ${e}`);let r=path.extname(e).toLowerCase();if(!Y.has(r))throw new Error(`Unsupported format: ${r}`);let n=t.verbose?u=>{process.stderr.write(`\r${u.status}: ${Math.round(u.progress*100)}%`);}:void 0;t.verbose&&console.error(`Processing: ${e}`);let i=fs.readFileSync(e),o=await new g({language:t.language,timeout:t.timeout,onProgress:n}).extract(i);t.verbose&&console.error("");let f=K(o,t);t.output?(fs.writeFileSync(t.output,f),t.verbose&&console.error(`Written to: ${t.output}`)):console.log(f),t.verbose&&o.warnings.length>0&&(console.error(`
+Warnings:`),o.warnings.forEach(u=>console.error(`  - ${u}`))),o.isDriverLicense||process.exit(2);}function K(s,t){let{data:e,processingTimeMs:r,isDriverLicense:n,warnings:i}=s;if(t.format==="json"){let o={...e,processingTimeMs:r,isDriverLicense:n};return t.raw||delete o.rawText,t.verbose&&(o.warnings=i),JSON.stringify(o,null,2)}if(t.format==="text"){let o=["=== Driver License Data ===",""];return e.fullName?o.push(`Name: ${e.fullName}`):(e.firstName&&o.push(`First: ${e.firstName}`),e.middleName&&o.push(`Middle: ${e.middleName}`),e.lastName&&o.push(`Last: ${e.lastName}`)),e.licenseNumber&&o.push(`License #: ${e.licenseNumber}`),e.issuingState&&o.push(`State: ${e.issuingState}`),e.licenseClass&&o.push(`Class: ${e.licenseClass}`),o.push(""),e.dateOfBirth&&o.push(`DOB: ${e.dateOfBirth}`),e.issueDate&&o.push(`Issued: ${e.issueDate}`),e.expirationDate&&o.push(`Expires: ${e.expirationDate}`),e.address?.full&&(o.push(""),o.push(`Address: ${e.address.full}`)),o.push(""),e.sex&&o.push(`Sex: ${e.sex}`),e.height&&o.push(`Height: ${e.height}`),e.weight&&o.push(`Weight: ${e.weight}`),e.eyeColor&&o.push(`Eyes: ${e.eyeColor}`),e.hairColor&&o.push(`Hair: ${e.hairColor}`),o.push(""),o.push(`Confidence: ${e.confidence}%`),o.push(`Time: ${r}ms`),t.raw&&e.rawText&&o.push("","--- Raw Text ---",e.rawText),o.join(`
+`)}let a=[["Field","Value"],["\u2500".repeat(18),"\u2500".repeat(38)]];return e.fullName&&a.push(["Name",e.fullName]),e.licenseNumber&&a.push(["License #",e.licenseNumber]),e.issuingState&&a.push(["State",e.issuingState]),e.dateOfBirth&&a.push(["DOB",e.dateOfBirth]),e.expirationDate&&a.push(["Expires",e.expirationDate]),e.address?.full&&a.push(["Address",e.address.full]),e.sex&&a.push(["Sex",e.sex]),e.height&&a.push(["Height",e.height]),a.push(["\u2500".repeat(18),"\u2500".repeat(38)]),a.push(["Confidence",`${e.confidence}%`]),a.push(["Time",`${r}ms`]),a.map(([o,f])=>`${o.padEnd(18)} ${f}`).join(`
+`)}G().catch(console.error);

package/dist/index.d.mts

@@ -0,0 +1,164 @@
+/**
+ * Type definitions for usa-dl-ocr
+ * @packageDocumentation
+ */
+/** Extracted address components */
+interface AddressInfo {
+    street: string | null;
+    city: string | null;
+    state: string | null;
+    zipCode: string | null;
+    full: string | null;
+}
+/** Complete driver license data structure */
+interface DriverLicenseData {
+    /** Full name as printed on license */
+    fullName: string | null;
+    /** First/given name */
+    firstName: string | null;
+    /** Middle name or initial */
+    middleName: string | null;
+    /** Last/family name */
+    lastName: string | null;
+    /** License number */
+    licenseNumber: string | null;
+    /** Date of birth in YYYY-MM-DD format */
+    dateOfBirth: string | null;
+    /** Expiration date in YYYY-MM-DD format */
+    expirationDate: string | null;
+    /** Issue date in YYYY-MM-DD format */
+    issueDate: string | null;
+    /** Parsed address */
+    address: AddressInfo | null;
+    /** Sex/gender (M or F) */
+    sex: 'M' | 'F' | null;
+    /** Height (e.g., "5'10\"") */
+    height: string | null;
+    /** Weight in pounds */
+    weight: string | null;
+    /** Eye color */
+    eyeColor: string | null;
+    /** Hair color */
+    hairColor: string | null;
+    /** Issuing state (2-letter abbreviation) */
+    issuingState: string | null;
+    /** License class */
+    licenseClass: string | null;
+    /** Restrictions codes */
+    restrictions: string[];
+    /** Endorsement codes */
+    endorsements: string[];
+    /** Document discriminator */
+    documentDiscriminator: string | null;
+    /** Raw OCR text */
+    rawText: string;
+    /** OCR confidence score 0-100 */
+    confidence: number;
+}
+/** OCR processing options */
+interface ExtractOptions {
+    /** Tesseract language code (default: 'eng') */
+    language?: string;
+    /** Custom worker path */
+    workerPath?: string;
+    /** Custom core WASM path */
+    corePath?: string;
+    /** Custom language data path */
+    langPath?: string;
+    /** Progress callback */
+    onProgress?: (progress: ProgressInfo) => void;
+    /** Page segmentation mode (default: 3) */
+    psm?: number;
+    /** OCR engine mode (default: 1) */
+    oem?: number;
+    /** Timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/** Progress callback data */
+interface ProgressInfo {
+    status: string;
+    progress: number;
+}
+/** Extraction result */
+interface ExtractionResult {
+    /** Extracted license data */
+    data: DriverLicenseData;
+    /** Processing time in ms */
+    processingTimeMs: number;
+    /** Whether image appears to be a driver license */
+    isDriverLicense: boolean;
+    /** Any warnings during processing */
+    warnings: string[];
+}
+/** Validation result */
+interface ValidationResult {
+    /** Whether data meets minimum requirements */
+    isValid: boolean;
+    /** Completeness score 0-100 */
+    score: number;
+    /** List of missing or invalid fields */
+    issues: string[];
+}
+/** Supported image input types */
+type ImageInput = Blob | File | Buffer | ArrayBuffer | Uint8Array | string;
+
+/**
+ * Sanitize input text to prevent injection attacks
+ */
+declare function sanitizeText(text: string): string;
+/**
+ * Parse OCR text into structured driver license data
+ */
+declare function parseOCRText(rawText: string): DriverLicenseData;
+/**
+ * Detect if text appears to be from a driver license
+ */
+declare function detectDriverLicense(text: string): boolean;
+
+/**
+ * Main OCR extraction class - framework agnostic
+ *
+ * @example
+ * ```typescript
+ * const ocr = new DriverLicenseOCR();
+ * const result = await ocr.extract(imageBlob);
+ * console.log(result.data.licenseNumber);
+ * ```
+ */
+declare class DriverLicenseOCR {
+    private options;
+    constructor(options?: ExtractOptions);
+    /**
+     * Extract driver license data from an image
+     */
+    extract(image: ImageInput): Promise<ExtractionResult>;
+    /**
+     * Validate and prepare image input
+     */
+    private prepareImage;
+}
+/**
+ * Stateless extraction function
+ */
+declare function extract(image: ImageInput, options?: ExtractOptions): Promise<ExtractionResult>;
+/**
+ * Create reusable OCR instance with persistent worker for batch processing
+ */
+declare function createOCR(options?: ExtractOptions): Promise<{
+    extract(image: ImageInput): Promise<ExtractionResult>;
+    terminate(): Promise<void>;
+}>;
+/**
+ * Validate extracted license data
+ */
+declare function validate(data: DriverLicenseData): ValidationResult;
+
+/** US state codes mapped to full names */
+declare const US_STATES: Readonly<Record<string, string>>;
+declare const STATE_CODES: readonly string[];
+/** Standard eye color abbreviations */
+declare const EYE_COLORS: Readonly<Record<string, string>>;
+/** Standard hair color abbreviations */
+declare const HAIR_COLORS: Readonly<Record<string, string>>;
+
+export { type AddressInfo, type DriverLicenseData, DriverLicenseOCR, EYE_COLORS, type ExtractOptions, type ExtractionResult, HAIR_COLORS, type ImageInput, type ProgressInfo, STATE_CODES, US_STATES, type ValidationResult, createOCR, detectDriverLicense, extract, parseOCRText, sanitizeText, validate };

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Type definitions for usa-dl-ocr
+ * @packageDocumentation
+ */
+/** Extracted address components */
+interface AddressInfo {
+    street: string | null;
+    city: string | null;
+    state: string | null;
+    zipCode: string | null;
+    full: string | null;
+}
+/** Complete driver license data structure */
+interface DriverLicenseData {
+    /** Full name as printed on license */
+    fullName: string | null;
+    /** First/given name */
+    firstName: string | null;
+    /** Middle name or initial */
+    middleName: string | null;
+    /** Last/family name */
+    lastName: string | null;
+    /** License number */
+    licenseNumber: string | null;
+    /** Date of birth in YYYY-MM-DD format */
+    dateOfBirth: string | null;
+    /** Expiration date in YYYY-MM-DD format */
+    expirationDate: string | null;
+    /** Issue date in YYYY-MM-DD format */
+    issueDate: string | null;
+    /** Parsed address */
+    address: AddressInfo | null;
+    /** Sex/gender (M or F) */
+    sex: 'M' | 'F' | null;
+    /** Height (e.g., "5'10\"") */
+    height: string | null;
+    /** Weight in pounds */
+    weight: string | null;
+    /** Eye color */
+    eyeColor: string | null;
+    /** Hair color */
+    hairColor: string | null;
+    /** Issuing state (2-letter abbreviation) */
+    issuingState: string | null;
+    /** License class */
+    licenseClass: string | null;
+    /** Restrictions codes */
+    restrictions: string[];
+    /** Endorsement codes */
+    endorsements: string[];
+    /** Document discriminator */
+    documentDiscriminator: string | null;
+    /** Raw OCR text */
+    rawText: string;
+    /** OCR confidence score 0-100 */
+    confidence: number;
+}
+/** OCR processing options */
+interface ExtractOptions {
+    /** Tesseract language code (default: 'eng') */
+    language?: string;
+    /** Custom worker path */
+    workerPath?: string;
+    /** Custom core WASM path */
+    corePath?: string;
+    /** Custom language data path */
+    langPath?: string;
+    /** Progress callback */
+    onProgress?: (progress: ProgressInfo) => void;
+    /** Page segmentation mode (default: 3) */
+    psm?: number;
+    /** OCR engine mode (default: 1) */
+    oem?: number;
+    /** Timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/** Progress callback data */
+interface ProgressInfo {
+    status: string;
+    progress: number;
+}
+/** Extraction result */
+interface ExtractionResult {
+    /** Extracted license data */
+    data: DriverLicenseData;
+    /** Processing time in ms */
+    processingTimeMs: number;
+    /** Whether image appears to be a driver license */
+    isDriverLicense: boolean;
+    /** Any warnings during processing */
+    warnings: string[];
+}
+/** Validation result */
+interface ValidationResult {
+    /** Whether data meets minimum requirements */
+    isValid: boolean;
+    /** Completeness score 0-100 */
+    score: number;
+    /** List of missing or invalid fields */
+    issues: string[];
+}
+/** Supported image input types */
+type ImageInput = Blob | File | Buffer | ArrayBuffer | Uint8Array | string;
+
+/**
+ * Sanitize input text to prevent injection attacks
+ */
+declare function sanitizeText(text: string): string;
+/**
+ * Parse OCR text into structured driver license data
+ */
+declare function parseOCRText(rawText: string): DriverLicenseData;
+/**
+ * Detect if text appears to be from a driver license
+ */
+declare function detectDriverLicense(text: string): boolean;
+
+/**
+ * Main OCR extraction class - framework agnostic
+ *
+ * @example
+ * ```typescript
+ * const ocr = new DriverLicenseOCR();
+ * const result = await ocr.extract(imageBlob);
+ * console.log(result.data.licenseNumber);
+ * ```
+ */
+declare class DriverLicenseOCR {
+    private options;
+    constructor(options?: ExtractOptions);
+    /**
+     * Extract driver license data from an image
+     */
+    extract(image: ImageInput): Promise<ExtractionResult>;
+    /**
+     * Validate and prepare image input
+     */
+    private prepareImage;
+}
+/**
+ * Stateless extraction function
+ */
+declare function extract(image: ImageInput, options?: ExtractOptions): Promise<ExtractionResult>;
+/**
+ * Create reusable OCR instance with persistent worker for batch processing
+ */
+declare function createOCR(options?: ExtractOptions): Promise<{
+    extract(image: ImageInput): Promise<ExtractionResult>;
+    terminate(): Promise<void>;
+}>;
+/**
+ * Validate extracted license data
+ */
+declare function validate(data: DriverLicenseData): ValidationResult;
+
+/** US state codes mapped to full names */
+declare const US_STATES: Readonly<Record<string, string>>;
+declare const STATE_CODES: readonly string[];
+/** Standard eye color abbreviations */
+declare const EYE_COLORS: Readonly<Record<string, string>>;
+/** Standard hair color abbreviations */
+declare const HAIR_COLORS: Readonly<Record<string, string>>;
+
+export { type AddressInfo, type DriverLicenseData, DriverLicenseOCR, EYE_COLORS, type ExtractOptions, type ExtractionResult, HAIR_COLORS, type ImageInput, type ProgressInfo, STATE_CODES, US_STATES, type ValidationResult, createOCR, detectDriverLicense, extract, parseOCRText, sanitizeText, validate };

package/dist/index.js

@@ -0,0 +1,3 @@
+'use strict';var M=require('tesseract.js');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var M__default=/*#__PURE__*/_interopDefault(M);var h=Object.freeze({AL:"Alabama",AK:"Alaska",AZ:"Arizona",AR:"Arkansas",CA:"California",CO:"Colorado",CT:"Connecticut",DE:"Delaware",FL:"Florida",GA:"Georgia",HI:"Hawaii",ID:"Idaho",IL:"Illinois",IN:"Indiana",IA:"Iowa",KS:"Kansas",KY:"Kentucky",LA:"Louisiana",ME:"Maine",MD:"Maryland",MA:"Massachusetts",MI:"Michigan",MN:"Minnesota",MS:"Mississippi",MO:"Missouri",MT:"Montana",NE:"Nebraska",NV:"Nevada",NH:"New Hampshire",NJ:"New Jersey",NM:"New Mexico",NY:"New York",NC:"North Carolina",ND:"North Dakota",OH:"Ohio",OK:"Oklahoma",OR:"Oregon",PA:"Pennsylvania",RI:"Rhode Island",SC:"South Carolina",SD:"South Dakota",TN:"Tennessee",TX:"Texas",UT:"Utah",VT:"Vermont",VA:"Virginia",WA:"Washington",WV:"West Virginia",WI:"Wisconsin",WY:"Wyoming",DC:"District of Columbia"}),S=Object.freeze(Object.keys(h)),R=Object.freeze({BLK:"Black",BLU:"Blue",BRO:"Brown",GRY:"Gray",GRN:"Green",HAZ:"Hazel",MAR:"Maroon",PNK:"Pink",DIC:"Dichromatic",UNK:"Unknown"}),N=Object.freeze({BAL:"Bald",BLK:"Black",BLN:"Blonde",BRO:"Brown",GRY:"Gray",RED:"Red",SDY:"Sandy",WHI:"White",UNK:"Unknown"}),c=Object.freeze({NAME:["NAME","FN","FULL NAME","NM"],FIRST_NAME:["FIRST","FIRST NAME","FN","GIVEN NAME","1"],MIDDLE_NAME:["MIDDLE","MIDDLE NAME","MN","2"],LAST_NAME:["LAST","LAST NAME","LN","FAMILY NAME","SURNAME","3"],LICENSE_NUMBER:["DL","LIC","LICENSE","DL NO","LIC NO","LICENSE NO","DRIVER LICENSE","DLN","4D"],CLASS:["CLASS","CLS","9"],DOB:["DOB","DATE OF BIRTH","BIRTH DATE","BD","BORN","3"],EXPIRATION:["EXP","EXPIRES","EXPIRATION","EXP DATE","4B"],ISSUE_DATE:["ISS","ISSUED","ISSUE DATE","4A"],SEX:["SEX","GENDER","S","11"],HEIGHT:["HT","HEIGHT","15"],WEIGHT:["WT","WEIGHT","16"],EYES:["EYES","EYE","EYE COLOR","14"],HAIR:["HAIR","HAIR COLOR","13"],ADDRESS:["ADDRESS","ADDR","ADD","8"],RESTRICTIONS:["RESTR","RESTRICTIONS","REST","12"],ENDORSEMENTS:["END","ENDORSEMENTS","ENDORSE","10"],DD:["DD","DAQ","DOCUMENT DISCRIMINATOR","AUDIT"]}),E=10*1024*1024,D=6e4;function C(s){return typeof s!="string"?"":s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g,"")}function m(s){let t=C(s),n=t.toUpperCase(),r=t.split(`
+`).map(e=>e.trim()).filter(Boolean);return {fullName:w(r,n),firstName:g(r,c.FIRST_NAME),middleName:g(r,c.MIDDLE_NAME),lastName:g(r,c.LAST_NAME),licenseNumber:y(n),dateOfBirth:T(n,c.DOB),expirationDate:T(n,c.EXPIRATION),issueDate:T(n,c.ISSUE_DATE),address:P(r,n),sex:U(n),height:_(n),weight:k(n),eyeColor:$(n),hairColor:H(n),issuingState:Z(n),licenseClass:g(r,c.CLASS),restrictions:x(n,c.RESTRICTIONS),endorsements:x(n,c.ENDORSEMENTS),documentDiscriminator:g(r,c.DD),rawText:t,confidence:0}}function w(s,t){for(let n of c.NAME){let r=new RegExp(`${p(n)}[:\\s]+([A-Z][A-Z'\\-]+),\\s*([A-Z][A-Z'\\s.-]+)`,"i"),e=t.match(r);if(e?.[1]&&e[2])return L(`${e[2]} ${e[1]}`)}for(let n of c.NAME){let r=new RegExp(`${p(n)}[:\\s]+([A-Z][A-Z\\s,.-]+)`,"i"),e=t.match(r);if(e?.[1])return L(e[1])}for(let n of s){let r=n.match(/^([A-Z][A-Z'-]+),\s*([A-Z][A-Z'\s.-]+)$/i);if(r?.[1]&&r[2])return L(`${r[2]} ${r[1]}`)}return null}function g(s,t){for(let n of t){let r=new RegExp(`(?:^|\\s)${p(n)}[:\\s]+([^\\n]+)`,"i");for(let e of s){let o=e.match(r);if(o?.[1])return o[1].trim()}}return null}function y(s){for(let n of c.LICENSE_NUMBER){let r=new RegExp(`${p(n)}[:\\s#]*([A-Z0-9-]{6,15})`,"i"),e=s.match(r);if(e?.[1]){let o=e[1].replace(/[^A-Z0-9]/gi,"");if(o.length>=6&&o.length<=15)return o}}return s.match(/\b([A-Z]\d{7,12}|\d{7,12}|[A-Z]{2}\d{6,10})\b/)?.[1]??null}function T(s,t){for(let n of t){let r=new RegExp(`${p(n)}[:\\s]*([\\d/\\-]+)`),e=s.match(r);if(e?.[1]){let o=B(e[1]);if(o)return o}}return null}function B(s){let t=s.match(/(\d{1,2})[\/\-](\d{1,2})[\/\-](\d{4})/);if(t?.[1]&&t[2]&&t[3]){let n=t[1].padStart(2,"0"),r=t[2].padStart(2,"0");if(O(t[3],n,r))return `${t[3]}-${n}-${r}`}return t=s.match(/(\d{4})[\/\-](\d{2})[\/\-](\d{2})/),t?.[1]&&t[2]&&t[3]&&O(t[1],t[2],t[3])?`${t[1]}-${t[2]}-${t[3]}`:(t=s.match(/^(\d{2})(\d{2})(\d{4})$/),t?.[1]&&t[2]&&t[3]&&O(t[3],t[1],t[2])?`${t[3]}-${t[1]}-${t[2]}`:null)}function O(s,t,n){let r=parseInt(s,10),e=parseInt(t,10),o=parseInt(n,10);if(r<1900||r>2100||e<1||e>12||o<1||o>31)return  false;let i=new Date(r,e-1,o);return i.getFullYear()===r&&i.getMonth()===e-1&&i.getDate()===o}function P(s,t){let n=null,r=null,e=null,o=null,i=t.match(/\b(\d{5}-\d{4})\b/)||t.match(/\b(\d{5})\b/);i?.[1]&&(o=i[1]);let f=t.match(/\b(\d+\s+[A-Z0-9\s]+(?:ST|STREET|AVE|AVENUE|BLVD|BOULEVARD|RD|ROAD|DR|DRIVE|LN|LANE|CT|COURT|WAY|PL|PLACE|CIR|CIRCLE))\b/);f?.[1]&&(n=f[1].trim());let l=t.match(/\n([A-Z][A-Z\s]+)[,\s]+([A-Z]{2})\s+(\d{5}(?:-\d{4})?)/);if(l?.[1]&&l[2]&&l[3])r=l[1].trim(),e=l[2],o=l[3];else {let a=t.match(/([A-Z][A-Z\s]{2,20}),\s*([A-Z]{2})\s+(\d{5}(?:-\d{4})?)/);if(a?.[1]&&a[2]&&a[3]){let d=a[1].trim();!d.match(/^\d+\s+/)&&(!n||!d.includes(n))&&(r=d,e=a[2],o=a[3]);}}if(!n&&!r&&!e&&!o)return null;let u=[n,r,e,o].filter(Boolean);return {street:n,city:r,state:e,zipCode:o,full:u.length>0?u.join(", "):null}}function U(s){for(let t of c.SEX){let n=new RegExp(`${p(t)}[:\\s]*(M|F|MALE|FEMALE)\\b`,"i"),r=s.match(n);if(r?.[1]){let e=r[1].toUpperCase();if(e==="M"||e==="MALE")return "M";if(e==="F"||e==="FEMALE")return "F"}}return null}function _(s){let t=[/HT[:\s]*(\d)'(\d{1,2})"/,/HT[:\s]*(\d)-(\d{1,2})/,/HT[:\s]*(\d)(\d{2})\b/,/HEIGHT[:\s]*(\d)'(\d{1,2})"/];for(let n of t){let r=s.match(n);if(r?.[1]&&r[2]){let e=parseInt(r[1],10),o=parseInt(r[2],10);if(e>=3&&e<=8&&o>=0&&o<=11)return `${e}'${o}"`}}return null}function k(s){let t=[/WT[:\s]*(\d{2,3})\s*(?:LBS?)?/i,/WEIGHT[:\s]*(\d{2,3})/i];for(let n of t){let r=s.match(n);if(r?.[1]){let e=parseInt(r[1],10);if(e>=50&&e<=500)return `${e} lbs`}}return null}function $(s){for(let t of c.EYES){let n=new RegExp(`${p(t)}[:\\s]+([A-Z]{2,4})\\b`,"i"),r=s.match(n);if(r?.[1]){let e=r[1].toUpperCase();if(e==="COLOR"||e==="COLO")continue;return R[e]??e}}return null}function H(s){for(let t of c.HAIR){let n=new RegExp(`${p(t)}[:\\s]+([A-Z]{2,4})\\b`,"i"),r=s.match(n);if(r?.[1]){let e=r[1].toUpperCase();if(e==="COLOR"||e==="COLO")continue;return N[e]??e}}return null}function Z(s){for(let[r,e]of Object.entries(h))if(s.includes(e.toUpperCase()))return r;let t=/\b([A-Z]{2})\s+DRIVER(?:'?S)?\s+LICENSE/,n=s.match(t);return n?.[1]&&S.includes(n[1])?n[1]:null}function x(s,t){let n=[];for(let r of t){let e=new RegExp(`\\b${p(r)}[:\\s]+([A-Z0-9,\\s]+?)(?:\\n|$)`,"i"),o=s.match(e);if(o?.[1]){let i=o[1].trim();if(i.toUpperCase()==="NONE")return [];let f=i.split(/[,\s]+/).filter(l=>{let u=l.toUpperCase();return u.length>0&&u.length<=3&&!u.match(/^(RESTR|ICTIONS|ENDOR|SEMENTS|NONE)$/i)});n.push(...f);}}return [...new Set(n)]}function L(s){return s.replace(/[^A-Z\s,.-]/gi,"").replace(/\s+/g," ").trim()}function p(s){return s.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function A(s){let t=s.toUpperCase(),n=0,r=[/DRIVER(?:'?S)?\s*LICENSE/,/OPERATOR(?:'?S)?\s*LICENSE/,/IDENTIFICATION\s*CARD/,/\bDL\b/,/\bDOB\b/,/\bEXP(?:IRES?)?\b/,/CLASS\s*[A-Z]/];for(let e of r)e.test(t)&&n++;for(let e of Object.values(h))if(t.includes(e.toUpperCase())){n++;break}return /\d{1,2}[\/\-]\d{1,2}[\/\-]\d{4}/.test(s)&&n++,n>=2}var I=class{constructor(t={}){this.options={language:"eng",psm:3,oem:1,timeout:D,...t};}async extract(t){let n=Date.now(),r=[],e=await this.prepareImage(t),o={};this.options.workerPath&&(o.workerPath=this.options.workerPath),this.options.corePath&&(o.corePath=this.options.corePath),this.options.langPath&&(o.langPath=this.options.langPath),this.options.onProgress&&(o.logger=f=>{this.options.onProgress?.({status:f.status,progress:f.progress});});let i=await M__default.default.createWorker(this.options.language??"eng",this.options.oem??1,o);try{await i.setParameters({tessedit_pageseg_mode:String(this.options.psm??3)});let f=i.recognize(e),l=new Promise((z,b)=>{setTimeout(()=>b(new Error("OCR timeout exceeded")),this.options.timeout);}),{data:u}=await Promise.race([f,l]),a=m(u.text);a.confidence=Math.round(u.confidence);let d=A(u.text);return d||r.push("Image may not be a driver license"),a.licenseNumber||r.push("License number not detected"),!a.fullName&&!a.firstName&&!a.lastName&&r.push("Name not detected"),a.dateOfBirth||r.push("Date of birth not detected"),{data:a,processingTimeMs:Date.now()-n,isDriverLicense:d,warnings:r}}finally{await i.terminate();}}async prepareImage(t){if(typeof t=="string"){if(t.length>2048)throw new Error("URL/path too long");if(t.startsWith("http://")||t.startsWith("https://"))try{new URL(t);}catch{throw new Error("Invalid URL")}return t}if(typeof Blob<"u"&&t instanceof Blob){if(t.size>E)throw new Error(`Image exceeds maximum size of ${E/1024/1024}MB`);return t}if(typeof Buffer<"u"&&Buffer.isBuffer(t)){if(t.length>E)throw new Error(`Image exceeds maximum size of ${E/1024/1024}MB`);return t}if(t instanceof ArrayBuffer){if(t.byteLength>E)throw new Error(`Image exceeds maximum size of ${E/1024/1024}MB`);return typeof Buffer<"u"?Buffer.from(t):t}if(t instanceof Uint8Array){if(t.byteLength>E)throw new Error(`Image exceeds maximum size of ${E/1024/1024}MB`);if(typeof Buffer<"u")return Buffer.from(t.buffer,t.byteOffset,t.byteLength);let n=t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength);return new Blob([n])}throw new Error("Unsupported image input type")}};async function F(s,t){return new I(t).extract(s)}async function v(s={}){let t={language:"eng",psm:3,oem:1,timeout:D,...s},n={};t.workerPath&&(n.workerPath=t.workerPath),t.corePath&&(n.corePath=t.corePath),t.langPath&&(n.langPath=t.langPath),t.onProgress&&(n.logger=e=>{t.onProgress?.({status:e.status,progress:e.progress});});let r=await M__default.default.createWorker(t.language??"eng",t.oem??1,n);return await r.setParameters({tessedit_pageseg_mode:String(t.psm??3)}),{async extract(e){let o=Date.now(),i=[],f;if(typeof e=="string")f=e;else if(typeof Blob<"u"&&e instanceof Blob)f=e;else if(typeof Buffer<"u"&&Buffer.isBuffer(e))f=e;else if(e instanceof ArrayBuffer)f=typeof Buffer<"u"?Buffer.from(e):e;else if(e instanceof Uint8Array)f=typeof Buffer<"u"?Buffer.from(e.buffer,e.byteOffset,e.byteLength):new Blob([e.buffer.slice(e.byteOffset,e.byteOffset+e.byteLength)]);else throw new Error("Unsupported image input type");let{data:l}=await r.recognize(f),u=m(l.text);u.confidence=Math.round(l.confidence);let a=A(l.text);return a||i.push("Image may not be a driver license"),u.licenseNumber||i.push("License number not detected"),{data:u,processingTimeMs:Date.now()-o,isDriverLicense:a,warnings:i}},async terminate(){await r.terminate();}}}function W(s){let t=[],n=0,r=11;s.licenseNumber?n+=2:t.push("licenseNumber"),s.dateOfBirth?n+=2:t.push("dateOfBirth"),s.expirationDate?n+=2:t.push("expirationDate"),s.fullName||s.firstName&&s.lastName?n+=1:t.push("name"),s.address?n+=1:t.push("address"),s.issuingState?n+=1:t.push("issuingState"),s.sex?n+=1:t.push("sex"),s.licenseClass?n+=1:t.push("licenseClass");let e=Math.round(n/r*100);return {isValid:e>=40&&s.licenseNumber!==null,score:e,issues:t}}
+exports.DriverLicenseOCR=I;exports.EYE_COLORS=R;exports.HAIR_COLORS=N;exports.STATE_CODES=S;exports.US_STATES=h;exports.createOCR=v;exports.detectDriverLicense=A;exports.extract=F;exports.parseOCRText=m;exports.sanitizeText=C;exports.validate=W;

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import M from'tesseract.js';var h=Object.freeze({AL:"Alabama",AK:"Alaska",AZ:"Arizona",AR:"Arkansas",CA:"California",CO:"Colorado",CT:"Connecticut",DE:"Delaware",FL:"Florida",GA:"Georgia",HI:"Hawaii",ID:"Idaho",IL:"Illinois",IN:"Indiana",IA:"Iowa",KS:"Kansas",KY:"Kentucky",LA:"Louisiana",ME:"Maine",MD:"Maryland",MA:"Massachusetts",MI:"Michigan",MN:"Minnesota",MS:"Mississippi",MO:"Missouri",MT:"Montana",NE:"Nebraska",NV:"Nevada",NH:"New Hampshire",NJ:"New Jersey",NM:"New Mexico",NY:"New York",NC:"North Carolina",ND:"North Dakota",OH:"Ohio",OK:"Oklahoma",OR:"Oregon",PA:"Pennsylvania",RI:"Rhode Island",SC:"South Carolina",SD:"South Dakota",TN:"Tennessee",TX:"Texas",UT:"Utah",VT:"Vermont",VA:"Virginia",WA:"Washington",WV:"West Virginia",WI:"Wisconsin",WY:"Wyoming",DC:"District of Columbia"}),S=Object.freeze(Object.keys(h)),R=Object.freeze({BLK:"Black",BLU:"Blue",BRO:"Brown",GRY:"Gray",GRN:"Green",HAZ:"Hazel",MAR:"Maroon",PNK:"Pink",DIC:"Dichromatic",UNK:"Unknown"}),N=Object.freeze({BAL:"Bald",BLK:"Black",BLN:"Blonde",BRO:"Brown",GRY:"Gray",RED:"Red",SDY:"Sandy",WHI:"White",UNK:"Unknown"}),c=Object.freeze({NAME:["NAME","FN","FULL NAME","NM"],FIRST_NAME:["FIRST","FIRST NAME","FN","GIVEN NAME","1"],MIDDLE_NAME:["MIDDLE","MIDDLE NAME","MN","2"],LAST_NAME:["LAST","LAST NAME","LN","FAMILY NAME","SURNAME","3"],LICENSE_NUMBER:["DL","LIC","LICENSE","DL NO","LIC NO","LICENSE NO","DRIVER LICENSE","DLN","4D"],CLASS:["CLASS","CLS","9"],DOB:["DOB","DATE OF BIRTH","BIRTH DATE","BD","BORN","3"],EXPIRATION:["EXP","EXPIRES","EXPIRATION","EXP DATE","4B"],ISSUE_DATE:["ISS","ISSUED","ISSUE DATE","4A"],SEX:["SEX","GENDER","S","11"],HEIGHT:["HT","HEIGHT","15"],WEIGHT:["WT","WEIGHT","16"],EYES:["EYES","EYE","EYE COLOR","14"],HAIR:["HAIR","HAIR COLOR","13"],ADDRESS:["ADDRESS","ADDR","ADD","8"],RESTRICTIONS:["RESTR","RESTRICTIONS","REST","12"],ENDORSEMENTS:["END","ENDORSEMENTS","ENDORSE","10"],DD:["DD","DAQ","DOCUMENT DISCRIMINATOR","AUDIT"]}),E=10*1024*1024,D=6e4;function C(s){return typeof s!="string"?"":s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g,"")}function m(s){let t=C(s),n=t.toUpperCase(),r=t.split(`
+`).map(e=>e.trim()).filter(Boolean);return {fullName:w(r,n),firstName:g(r,c.FIRST_NAME),middleName:g(r,c.MIDDLE_NAME),lastName:g(r,c.LAST_NAME),licenseNumber:y(n),dateOfBirth:T(n,c.DOB),expirationDate:T(n,c.EXPIRATION),issueDate:T(n,c.ISSUE_DATE),address:P(r,n),sex:U(n),height:_(n),weight:k(n),eyeColor:$(n),hairColor:H(n),issuingState:Z(n),licenseClass:g(r,c.CLASS),restrictions:x(n,c.RESTRICTIONS),endorsements:x(n,c.ENDORSEMENTS),documentDiscriminator:g(r,c.DD),rawText:t,confidence:0}}function w(s,t){for(let n of c.NAME){let r=new RegExp(`${p(n)}[:\\s]+([A-Z][A-Z'\\-]+),\\s*([A-Z][A-Z'\\s.-]+)`,"i"),e=t.match(r);if(e?.[1]&&e[2])return L(`${e[2]} ${e[1]}`)}for(let n of c.NAME){let r=new RegExp(`${p(n)}[:\\s]+([A-Z][A-Z\\s,.-]+)`,"i"),e=t.match(r);if(e?.[1])return L(e[1])}for(let n of s){let r=n.match(/^([A-Z][A-Z'-]+),\s*([A-Z][A-Z'\s.-]+)$/i);if(r?.[1]&&r[2])return L(`${r[2]} ${r[1]}`)}return null}function g(s,t){for(let n of t){let r=new RegExp(`(?:^|\\s)${p(n)}[:\\s]+([^\\n]+)`,"i");for(let e of s){let o=e.match(r);if(o?.[1])return o[1].trim()}}return null}function y(s){for(let n of c.LICENSE_NUMBER){let r=new RegExp(`${p(n)}[:\\s#]*([A-Z0-9-]{6,15})`,"i"),e=s.match(r);if(e?.[1]){let o=e[1].replace(/[^A-Z0-9]/gi,"");if(o.length>=6&&o.length<=15)return o}}return s.match(/\b([A-Z]\d{7,12}|\d{7,12}|[A-Z]{2}\d{6,10})\b/)?.[1]??null}function T(s,t){for(let n of t){let r=new RegExp(`${p(n)}[:\\s]*([\\d/\\-]+)`),e=s.match(r);if(e?.[1]){let o=B(e[1]);if(o)return o}}return null}function B(s){let t=s.match(/(\d{1,2})[\/\-](\d{1,2})[\/\-](\d{4})/);if(t?.[1]&&t[2]&&t[3]){let n=t[1].padStart(2,"0"),r=t[2].padStart(2,"0");if(O(t[3],n,r))return `${t[3]}-${n}-${r}`}return t=s.match(/(\d{4})[\/\-](\d{2})[\/\-](\d{2})/),t?.[1]&&t[2]&&t[3]&&O(t[1],t[2],t[3])?`${t[1]}-${t[2]}-${t[3]}`:(t=s.match(/^(\d{2})(\d{2})(\d{4})$/),t?.[1]&&t[2]&&t[3]&&O(t[3],t[1],t[2])?`${t[3]}-${t[1]}-${t[2]}`:null)}function O(s,t,n){let r=parseInt(s,10),e=parseInt(t,10),o=parseInt(n,10);if(r<1900||r>2100||e<1||e>12||o<1||o>31)return  false;let i=new Date(r,e-1,o);return i.getFullYear()===r&&i.getMonth()===e-1&&i.getDate()===o}function P(s,t){let n=null,r=null,e=null,o=null,i=t.match(/\b(\d{5}-\d{4})\b/)||t.match(/\b(\d{5})\b/);i?.[1]&&(o=i[1]);let f=t.match(/\b(\d+\s+[A-Z0-9\s]+(?:ST|STREET|AVE|AVENUE|BLVD|BOULEVARD|RD|ROAD|DR|DRIVE|LN|LANE|CT|COURT|WAY|PL|PLACE|CIR|CIRCLE))\b/);f?.[1]&&(n=f[1].trim());let l=t.match(/\n([A-Z][A-Z\s]+)[,\s]+([A-Z]{2})\s+(\d{5}(?:-\d{4})?)/);if(l?.[1]&&l[2]&&l[3])r=l[1].trim(),e=l[2],o=l[3];else {let a=t.match(/([A-Z][A-Z\s]{2,20}),\s*([A-Z]{2})\s+(\d{5}(?:-\d{4})?)/);if(a?.[1]&&a[2]&&a[3]){let d=a[1].trim();!d.match(/^\d+\s+/)&&(!n||!d.includes(n))&&(r=d,e=a[2],o=a[3]);}}if(!n&&!r&&!e&&!o)return null;let u=[n,r,e,o].filter(Boolean);return {street:n,city:r,state:e,zipCode:o,full:u.length>0?u.join(", "):null}}function U(s){for(let t of c.SEX){let n=new RegExp(`${p(t)}[:\\s]*(M|F|MALE|FEMALE)\\b`,"i"),r=s.match(n);if(r?.[1]){let e=r[1].toUpperCase();if(e==="M"||e==="MALE")return "M";if(e==="F"||e==="FEMALE")return "F"}}return null}function _(s){let t=[/HT[:\s]*(\d)'(\d{1,2})"/,/HT[:\s]*(\d)-(\d{1,2})/,/HT[:\s]*(\d)(\d{2})\b/,/HEIGHT[:\s]*(\d)'(\d{1,2})"/];for(let n of t){let r=s.match(n);if(r?.[1]&&r[2]){let e=parseInt(r[1],10),o=parseInt(r[2],10);if(e>=3&&e<=8&&o>=0&&o<=11)return `${e}'${o}"`}}return null}function k(s){let t=[/WT[:\s]*(\d{2,3})\s*(?:LBS?)?/i,/WEIGHT[:\s]*(\d{2,3})/i];for(let n of t){let r=s.match(n);if(r?.[1]){let e=parseInt(r[1],10);if(e>=50&&e<=500)return `${e} lbs`}}return null}function $(s){for(let t of c.EYES){let n=new RegExp(`${p(t)}[:\\s]+([A-Z]{2,4})\\b`,"i"),r=s.match(n);if(r?.[1]){let e=r[1].toUpperCase();if(e==="COLOR"||e==="COLO")continue;return R[e]??e}}return null}function H(s){for(let t of c.HAIR){let n=new RegExp(`${p(t)}[:\\s]+([A-Z]{2,4})\\b`,"i"),r=s.match(n);if(r?.[1]){let e=r[1].toUpperCase();if(e==="COLOR"||e==="COLO")continue;return N[e]??e}}return null}function Z(s){for(let[r,e]of Object.entries(h))if(s.includes(e.toUpperCase()))return r;let t=/\b([A-Z]{2})\s+DRIVER(?:'?S)?\s+LICENSE/,n=s.match(t);return n?.[1]&&S.includes(n[1])?n[1]:null}function x(s,t){let n=[];for(let r of t){let e=new RegExp(`\\b${p(r)}[:\\s]+([A-Z0-9,\\s]+?)(?:\\n|$)`,"i"),o=s.match(e);if(o?.[1]){let i=o[1].trim();if(i.toUpperCase()==="NONE")return [];let f=i.split(/[,\s]+/).filter(l=>{let u=l.toUpperCase();return u.length>0&&u.length<=3&&!u.match(/^(RESTR|ICTIONS|ENDOR|SEMENTS|NONE)$/i)});n.push(...f);}}return [...new Set(n)]}function L(s){return s.replace(/[^A-Z\s,.-]/gi,"").replace(/\s+/g," ").trim()}function p(s){return s.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function A(s){let t=s.toUpperCase(),n=0,r=[/DRIVER(?:'?S)?\s*LICENSE/,/OPERATOR(?:'?S)?\s*LICENSE/,/IDENTIFICATION\s*CARD/,/\bDL\b/,/\bDOB\b/,/\bEXP(?:IRES?)?\b/,/CLASS\s*[A-Z]/];for(let e of r)e.test(t)&&n++;for(let e of Object.values(h))if(t.includes(e.toUpperCase())){n++;break}return /\d{1,2}[\/\-]\d{1,2}[\/\-]\d{4}/.test(s)&&n++,n>=2}var I=class{constructor(t={}){this.options={language:"eng",psm:3,oem:1,timeout:D,...t};}async extract(t){let n=Date.now(),r=[],e=await this.prepareImage(t),o={};this.options.workerPath&&(o.workerPath=this.options.workerPath),this.options.corePath&&(o.corePath=this.options.corePath),this.options.langPath&&(o.langPath=this.options.langPath),this.options.onProgress&&(o.logger=f=>{this.options.onProgress?.({status:f.status,progress:f.progress});});let i=await M.createWorker(this.options.language??"eng",this.options.oem??1,o);try{await i.setParameters({tessedit_pageseg_mode:String(this.options.psm??3)});let f=i.recognize(e),l=new Promise((z,b)=>{setTimeout(()=>b(new Error("OCR timeout exceeded")),this.options.timeout);}),{data:u}=await Promise.race([f,l]),a=m(u.text);a.confidence=Math.round(u.confidence);let d=A(u.text);return d||r.push("Image may not be a driver license"),a.licenseNumber||r.push("License number not detected"),!a.fullName&&!a.firstName&&!a.lastName&&r.push("Name not detected"),a.dateOfBirth||r.push("Date of birth not detected"),{data:a,processingTimeMs:Date.now()-n,isDriverLicense:d,warnings:r}}finally{await i.terminate();}}async prepareImage(t){if(typeof t=="string"){if(t.length>2048)throw new Error("URL/path too long");if(t.startsWith("http://")||t.startsWith("https://"))try{new URL(t);}catch{throw new Error("Invalid URL")}return t}if(typeof Blob<"u"&&t instanceof Blob){if(t.size>E)throw new Error(`Image exceeds maximum size of ${E/1024/1024}MB`);return t}if(typeof Buffer<"u"&&Buffer.isBuffer(t)){if(t.length>E)throw new Error(`Image exceeds maximum size of ${E/1024/1024}MB`);return t}if(t instanceof ArrayBuffer){if(t.byteLength>E)throw new Error(`Image exceeds maximum size of ${E/1024/1024}MB`);return typeof Buffer<"u"?Buffer.from(t):t}if(t instanceof Uint8Array){if(t.byteLength>E)throw new Error(`Image exceeds maximum size of ${E/1024/1024}MB`);if(typeof Buffer<"u")return Buffer.from(t.buffer,t.byteOffset,t.byteLength);let n=t.buffer.slice(t.byteOffset,t.byteOffset+t.byteLength);return new Blob([n])}throw new Error("Unsupported image input type")}};async function F(s,t){return new I(t).extract(s)}async function v(s={}){let t={language:"eng",psm:3,oem:1,timeout:D,...s},n={};t.workerPath&&(n.workerPath=t.workerPath),t.corePath&&(n.corePath=t.corePath),t.langPath&&(n.langPath=t.langPath),t.onProgress&&(n.logger=e=>{t.onProgress?.({status:e.status,progress:e.progress});});let r=await M.createWorker(t.language??"eng",t.oem??1,n);return await r.setParameters({tessedit_pageseg_mode:String(t.psm??3)}),{async extract(e){let o=Date.now(),i=[],f;if(typeof e=="string")f=e;else if(typeof Blob<"u"&&e instanceof Blob)f=e;else if(typeof Buffer<"u"&&Buffer.isBuffer(e))f=e;else if(e instanceof ArrayBuffer)f=typeof Buffer<"u"?Buffer.from(e):e;else if(e instanceof Uint8Array)f=typeof Buffer<"u"?Buffer.from(e.buffer,e.byteOffset,e.byteLength):new Blob([e.buffer.slice(e.byteOffset,e.byteOffset+e.byteLength)]);else throw new Error("Unsupported image input type");let{data:l}=await r.recognize(f),u=m(l.text);u.confidence=Math.round(l.confidence);let a=A(l.text);return a||i.push("Image may not be a driver license"),u.licenseNumber||i.push("License number not detected"),{data:u,processingTimeMs:Date.now()-o,isDriverLicense:a,warnings:i}},async terminate(){await r.terminate();}}}function W(s){let t=[],n=0,r=11;s.licenseNumber?n+=2:t.push("licenseNumber"),s.dateOfBirth?n+=2:t.push("dateOfBirth"),s.expirationDate?n+=2:t.push("expirationDate"),s.fullName||s.firstName&&s.lastName?n+=1:t.push("name"),s.address?n+=1:t.push("address"),s.issuingState?n+=1:t.push("issuingState"),s.sex?n+=1:t.push("sex"),s.licenseClass?n+=1:t.push("licenseClass");let e=Math.round(n/r*100);return {isValid:e>=40&&s.licenseNumber!==null,score:e,issues:t}}
+export{I as DriverLicenseOCR,R as EYE_COLORS,N as HAIR_COLORS,S as STATE_CODES,h as US_STATES,v as createOCR,A as detectDriverLicense,F as extract,m as parseOCRText,C as sanitizeText,W as validate};

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "usa-dl-ocr",
+  "version": "1.0.0",
+  "description": "Framework-agnostic USA driver license OCR extraction using Tesseract.js",
+  "author": "Sepehr Mohseni <https://github.com/sepehr-mohseni>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sepehr-mohseni/usa-dl-ocr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sepehr-mohseni/usa-dl-ocr/issues"
+  },
+  "homepage": "https://github.com/sepehr-mohseni/usa-dl-ocr#readme",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "usa-dl-ocr": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup && node scripts/postbuild.js",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "size": "size-limit",
+    "audit:fix": "npm audit fix",
+    "clean": "rm -rf dist coverage"
+  },
+  "keywords": [
+    "ocr",
+    "driver-license",
+    "usa",
+    "tesseract",
+    "tesseract.js",
+    "document-recognition",
+    "id-extraction",
+    "license-parser"
+  ],
+  "dependencies": {
+    "tesseract.js": "^5.1.1"
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@types/node": "^22.10.5",
+    "@vitest/coverage-v8": "^3.0.0",
+    "commander": "^13.0.0",
+    "size-limit": "^11.2.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "commander": ">=12.0.0"
+  },
+  "peerDependenciesMeta": {
+    "commander": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "size-limit": [
+    {
+      "path": "dist/index.mjs",
+      "limit": "10 KB"
+    }
+  ]
+}