document-ocr 0.0.0-stage → 3.1.3

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+interface PassportFields {
+    surname: string | null;
+    givenNames: string | null;
+    fullName: string | null;
+    passportNumber: string | null;
+    nationality: string | null;
+    dateOfBirth: string | null;
+    sex: 'M' | 'F' | 'X' | null;
+    expiryDate: string | null;
+    issueDate: string | null;
+    placeOfBirth: string | null;
+    countryCode: string | null;
+}
+interface BackPageFields {
+    fatherName: string | null;
+    motherName: string | null;
+    spouseName: string | null;
+    address: string | null;
+    pincode: string | null;
+    city: string | null;
+    state: string | null;
+    fileNumber: string | null;
+    oldPassportNumber: string | null;
+    oldPassportDateOfIssue: string | null;
+    oldPassportPlaceOfIssue: string | null;
+}
+interface PanFields {
+    panNumber: string | null;
+    name: string | null;
+    fatherName: string | null;
+    dateOfBirth: string | null;
+}
+interface AadhaarFields {
+    aadhaarNumber: string | null;
+    name: string | null;
+    dateOfBirth: string | null;
+    yearOfBirth: string | null;
+    gender: string | null;
+    address: string | null;
+    pincode: string | null;
+    checksumValid: boolean;
+    aadhaarMasked: boolean;
+    aadhaarLast4: string | null;
+    vid: string | null;
+}
+interface DrivingLicenceFields {
+    dlNumber: string | null;
+    name: string | null;
+    dateOfBirth: string | null;
+    issueDate: string | null;
+    validityDate: string | null;
+    address: string | null;
+    relationName: string | null;
+    bloodGroup: string | null;
+    classOfVehicle: string | null;
+    validityDateTransport: string | null;
+}
+interface VoterIdFields {
+    epicNumber: string | null;
+    name: string | null;
+    relationName: string | null;
+    relationType: string | null;
+    gender: string | null;
+    dateOfBirth: string | null;
+    age: string | null;
+}
+interface NregaMember {
+    serialNumber: string | null;
+    name: string | null;
+    fatherOrHusbandName: string | null;
+    gender: 'MALE' | 'FEMALE' | 'TRANSGENDER' | null;
+    age: number | null;
+}
+interface NregaJobCardFields {
+    jobCardNumber: string | null;
+    headOfHousehold: string | null;
+    category: string | null;
+    registrationDate: string | null;
+    validityFrom: string | null;
+    validityTo: string | null;
+    address: string | null;
+    village: string | null;
+    gramPanchayat: string | null;
+    block: string | null;
+    district: string | null;
+    state: string | null;
+    bplStatus: boolean | null;
+    familyId: string | null;
+    members: NregaMember[];
+}
+interface NprLetterFields {
+    referenceNumber: string | null;
+    name: string | null;
+    address: string | null;
+    pincode: string | null;
+    issueDate: string | null;
+}
+type DocumentStatus = 'success' | 'unsupported_page' | 'failure';
+type DocumentType = 'passport' | 'pan' | 'aadhaar' | 'driving_licence' | 'voter_id' | 'nrega_job_card' | 'npr_letter' | 'us_driver_license' | 'us_state_id' | 'passport_card' | 'us_green_card' | 'us_ead' | 'visa' | 'us_i94' | 'us_w9' | 'unknown';
+type PageType = DocumentType | 'passport_biodata' | 'passport_non_biodata';
+type UnsupportedReason = 'UNSUPPORTED_DOCUMENT';
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+interface FieldEvidence {
+    text: string;
+    bbox: number[][];
+    source: 'ocr' | 'pdf_text' | 'mrz' | 'pdf417' | 'qr';
+    confidence: number;
+    page?: number;
+}
+interface BaseDocumentScanResult {
+    schemaVersion?: number;
+    documentFields?: Record<string, JsonValue> | null;
+    issuingCountry?: string | null;
+    issuingRegion?: string | null;
+    fieldEvidence?: Record<string, FieldEvidence[]>;
+    imageSize?: [number, number] | null;
+    checks?: Record<string, boolean | string | null>;
+    status: DocumentStatus;
+    documentType: DocumentType;
+    pageType: PageType;
+    confidence: number;
+    lowConfidence: boolean;
+    mrzRaw: [string, string] | null;
+    mrzValid: boolean;
+    unsupportedReason: UnsupportedReason | null;
+    identifierValid: boolean | null;
+    missingRequiredFields: string[];
+    backPageFields: BackPageFields | null;
+    panFields: PanFields | null;
+    aadhaarFields: AadhaarFields | null;
+    drivingLicenceFields: DrivingLicenceFields | null;
+    voterIdFields: VoterIdFields | null;
+    nregaJobCardFields: NregaJobCardFields | null;
+    nprLetterFields: NprLetterFields | null;
+    probeText: string[];
+    errors: string[];
+    warnings: string[];
+    processingMs: number;
+}
+interface SuccessfulDocumentScanResult extends BaseDocumentScanResult {
+    status: 'success';
+    fields: PassportFields | null;
+}
+interface UnsupportedPageDocumentScanResult extends BaseDocumentScanResult {
+    status: 'unsupported_page';
+    fields: null;
+    unsupportedReason: UnsupportedReason;
+}
+interface FailedDocumentScanResult extends BaseDocumentScanResult {
+    status: 'failure';
+    fields: PassportFields | null;
+}
+type DocumentScanResult = SuccessfulDocumentScanResult | UnsupportedPageDocumentScanResult | FailedDocumentScanResult;
+type PassportScanResult = DocumentScanResult;
+type ImageInput = File | Blob | Buffer | ArrayBuffer | string;
+type ClientMode = 'local' | 'http' | 'lambda';
+interface DocumentOCROptions {
+    mode?: ClientMode;
+    endpoint?: string;
+    functionName?: string;
+    timeoutMs?: number;
+    retries?: number;
+    apiKey?: string;
+    authHeaders?: (url: string, signal?: AbortSignal) => HeadersInit | Promise<HeadersInit>;
+}
+type PassportOCROptions = DocumentOCROptions;
+interface ScanOptions {
+    documentType?: string;
+    country?: string;
+    includeEvidence?: boolean;
+}
+interface BatchScanResult {
+    results: DocumentScanResult[];
+    status: 'success' | 'partial' | 'failure';
+    errors: string[];
+}
+interface DocumentScanGroupResult extends BatchScanResult {
+    documentFields: Record<string, JsonValue>;
+    conflicts: Array<{
+        field: string;
+        values: Array<{
+            page: number;
+            value: JsonValue;
+        }>;
+    }>;
+}
+interface JobOptions extends ScanOptions {
+    grouped?: boolean;
+    notify?: boolean;
+}
+interface OCRJob {
+    id: string;
+    status: 'queued' | 'running' | 'succeeded' | 'failed';
+    createdAt: number;
+    expiresAt: number;
+    attempts: number;
+    error: string | null;
+    result?: BatchScanResult | DocumentScanGroupResult;
+}
+interface S3ImageInput {
+    bucket: string;
+    key: string;
+    versionId?: string;
+}
+interface DocumentDefinition {
+    documentType: DocumentType;
+    label: string;
+    countries: string[];
+    fields: string[];
+    requiredFields: string[];
+    requiredFieldsByVariant?: Record<string, string[]>;
+    requirementAlternatives?: Record<string, string[][]>;
+    sources: string[];
+    experimental: boolean;
+}
+interface DocumentCatalog {
+    schemaVersion: number;
+    documents: DocumentDefinition[];
+    capabilities: {
+        barcode: boolean;
+        jobs: boolean;
+        review: boolean;
+        multipage: boolean;
+    };
+}
+
+declare class DocumentOCR {
+    private mode;
+    private endpoint?;
+    private functionName?;
+    private timeoutMs;
+    private retries;
+    private apiKey?;
+    private authHeaders?;
+    constructor(options?: DocumentOCROptions);
+    scan(image: ImageInput, options?: ScanOptions): Promise<DocumentScanResult>;
+    scanBatch(images: ImageInput[], options?: ScanOptions): Promise<BatchScanResult>;
+    scanDocument(images: ImageInput[], options?: ScanOptions): Promise<DocumentScanGroupResult>;
+    private uploadMany;
+    documents(): Promise<DocumentCatalog>;
+    enqueueJob(images: ImageInput[], options?: JobOptions): Promise<OCRJob>;
+    job(id: string): Promise<OCRJob>;
+    deleteJob(id: string): Promise<{
+        deleted: true;
+    }>;
+    scanS3(image: S3ImageInput, options?: ScanOptions): Promise<DocumentScanResult>;
+    stop(): Promise<void>;
+    private requireHttp;
+    private retry;
+    private request;
+    private invokeLambda;
+}
+declare const PassportOCR: typeof DocumentOCR;
+
+/**
+ * Manages a local Python FastAPI server for passport OCR.
+ *
+ * Uses a module-level singleton so multiple PassportOCR instances
+ * share a single server process.
+ */
+declare class LocalServer {
+    private process;
+    private ready;
+    private startupAbort;
+    private cleanupHandler;
+    /**
+     * Ensure the local Python server is running and return its endpoint URL.
+     */
+    ensureRunning(): Promise<string>;
+    private _start;
+    private _waitForReady;
+    /**
+     * Stop the local Python server if running.
+     */
+    stop(): Promise<void>;
+}
+declare function getLocalServer(): LocalServer;
+
+/** Preserve transport status separately from the server's human-readable message. */
+declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+    get retryable(): boolean;
+}
+/** Invalid client input cannot succeed by retrying the same request. */
+declare class InputValidationError extends Error {
+    constructor(message: string);
+}
+
+export { DocumentOCR, HttpError, InputValidationError, LocalServer, PassportOCR, getLocalServer };
+export type { AadhaarFields, BackPageFields, BatchScanResult, ClientMode, DocumentCatalog, DocumentDefinition, DocumentOCROptions, DocumentScanGroupResult, DocumentScanResult, DocumentStatus, DocumentType, DrivingLicenceFields, FieldEvidence, ImageInput, JobOptions, JsonValue, NprLetterFields, NregaJobCardFields, NregaMember, OCRJob, PageType, PanFields, PassportFields, PassportOCROptions, PassportScanResult, S3ImageInput, ScanOptions, UnsupportedReason, VoterIdFields };