@andresxid/xid_camera_ocr_sdk_react 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,459 @@
+import * as react from 'react';
+
+/** Default `opencv.js` URL (the bundled copy shipped with the package). */
+declare function defaultOpencvUrl(): string;
+
+/**
+ * Public SDK types.
+ */
+/**
+ * Shape hint produced by the detector. `INE` = ID-1 card shape (INE, licence,
+ * cédula…), `PASSPORT_MX` = TD3 passport shape of any country, `OTHER` = another
+ * quadrilateral. The hint is never a nationality or document-type claim; the
+ * backend decides the real type.
+ */
+type DocumentType = 'INE' | 'PASSPORT_MX' | 'OTHER';
+interface CornerPoint {
+    x: number;
+    y: number;
+}
+/** User-facing guidance for the current frame. */
+type FrameHint = 'no_document' | 'too_small' | 'too_dark' | 'glare' | 'blurry' | 'hold_still' | 'ready'
+/** OpenCV failed to load or the worker crashed: auto-capture is off, `captureNow()` gives the unwarped frame. */
+ | 'detector_unavailable';
+interface XidCameraOcrSessionOptions {
+    /** `<video>` element that renders the camera stream. */
+    videoElement: HTMLVideoElement;
+    /**
+     * Shape hints the host is interested in. Detection and capture are NOT
+     * filtered by this list (any quadrilateral in [1.25, 1.75] aspect is
+     * capturable); wrappers use it to size the fallback guide rectangle.
+     */
+    documentTypes?: DocumentType[];
+    /** When `true`, captures automatically once a stable, good-quality quad is seen. */
+    autoCapture?: boolean;
+    /** Consecutive stable frames required before auto-capture. Default 10 (≈ 1 s at 10 fps). */
+    stableFramesRequired?: number;
+    /** JPEG quality of the captured image (0–1). Default 0.92. */
+    captureQuality?: number;
+    /** Long side of the rectified capture: `standard` = 1024 px, `high` = 1600 px. Default `standard`. */
+    captureResolution?: 'standard' | 'high';
+    /**
+     * URL of the OpenCV.js asset the worker loads lazily. Defaults to the
+     * `opencv.js` file shipped next to the SDK bundle.
+     */
+    opencvUrl?: string;
+    /**
+     * URL of a self-hosted copy of `dist/cv-worker.js` (spawned as a module worker).
+     * Defaults to the worker shipped with the package. Needed, together with
+     * `opencvUrl`, for the CJS build and non-Vite bundlers.
+     */
+    workerUrl?: string;
+    /** Implemented by the host: receives the Blob, uploads it, returns the backend JSON. */
+    onUpload: (blob: Blob, detectedType: DocumentType | null) => Promise<ExtractResult>;
+    /** Optional UI feedback events. */
+    onFrameAnalyzed?: (state: FrameState) => void;
+    onCaptured?: (blob: Blob, detectedType: DocumentType | null) => void;
+    onResult?: (result: ExtractResult) => void;
+    onError?: (err: Error) => void;
+}
+interface FrameState {
+    detected: boolean;
+    documentType: DocumentType | null;
+    confidence: number;
+    aspectRatio: number | null;
+    quality: FrameQuality | null;
+    /**
+     * Document corners (TL, TR, BR, BL) in analysis-frame pixels. Present only
+     * when a quad was detected. Scale by `frameSize` to draw an overlay.
+     */
+    corners: [CornerPoint, CornerPoint, CornerPoint, CornerPoint] | null;
+    /** Size of the analysis frame (NOT the native video size). */
+    frameSize: {
+        width: number;
+        height: number;
+    } | null;
+    /** Guidance for the user, derived from quality + stability. */
+    hint?: FrameHint;
+    /** `true` while the camera torch has been enabled by the SDK. Absent when the track has no torch. */
+    torch?: boolean;
+}
+interface FrameQuality {
+    brightness: number;
+    blurScore: number;
+    glareRatio: number;
+    docFillRatio: number;
+    ok: boolean;
+}
+interface ExtractResult {
+    [key: string]: unknown;
+}
+interface SessionState {
+    status: 'idle' | 'starting' | 'loading_detector' | 'streaming' | 'capturing' | 'uploading' | 'done' | 'stopped' | 'error';
+    lastFrame: FrameState | null;
+    lastResult: ExtractResult | null;
+    lastError: Error | null;
+}
+type SessionStatus = SessionState['status'];
+
+/**
+ * Pure geometry helpers (no OpenCV, no DOM). Unit-tested in Vitest.
+ * Corner order everywhere is TL, TR, BR, BL.
+ */
+
+interface Point {
+    x: number;
+    y: number;
+}
+type Quad = [Point, Point, Point, Point];
+declare const ID1_RATIO: number;
+declare const TD3_RATIO: number;
+/**
+ * Orders 4 points as TL, TR, BR, BL (y-down). Sorts by angle around the centroid
+ * (clockwise on screen), then rotates the cycle so TL is the point with the
+ * smallest x + y (ties: smallest y). Robust to a card rotated exactly 45°.
+ */
+declare function orderCorners(points: Point[]): Quad;
+/** Aspect ratio of the rectified quad: mean(long sides) / mean(short sides), ≥ 1. */
+declare function rectifiedAspect(quad: Quad): number;
+/** Nearest nominal ratio within ±5 %, else OTHER. Bands: ID-1 1.507–1.665, TD3 1.349–1.491. */
+declare function typeHintFromAspect(aspect: number): DocumentType;
+declare function isCapturableAspect(aspect: number): boolean;
+
+/** Messages exchanged between `cv-worker-client.ts` (main thread) and `cv-worker.ts`. */
+
+interface ImageDataLike {
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+}
+interface CvDetectionResult {
+    detected: boolean;
+    documentType: DocumentType | null;
+    aspectRatio: number | null;
+    corners: Quad | null;
+    boundingBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /** Quality measured inside the quad; null when nothing was detected. */
+    quality: FrameQuality | null;
+    /** Whole-frame mean brightness 0–1 (for the torch decision when no quad). */
+    frameBrightness: number;
+    score: number | null;
+    /**
+     * How the winning quad was found: `direct` (a native 4-vertex contour), `reduced`
+     * (a 5–6-vertex hull collapsed to a quad) or `lowres` (the half-resolution fallback
+     * pass; wins over `reduced`). Non-direct winners are less precise and carry a
+     * discounted `score`. Undefined when nothing was detected.
+     */
+    provenance?: 'direct' | 'reduced' | 'lowres';
+}
+
+/**
+ * CVWorkerClient — async wrapper over the OpenCV Web Worker.
+ * One module worker; request/response by incremental id. No skip-if-busy:
+ * the session guarantees a single frame in flight (spec §5.1).
+ *
+ * Pixel buffers are copied before being transferred, so the caller's frame
+ * is never detached and the client never touches a transferred buffer again.
+ */
+
+interface CVWorkerClientOptions {
+    /**
+     * Main-thread deadline for `init()`: rejects even if the worker thread hangs
+     * and never reports `init-error`. Default 30 s.
+     */
+    initTimeoutMs?: number;
+}
+
+declare class CVWorkerClient {
+    private readonly initTimeoutMs;
+    private worker;
+    private readyPromise;
+    private rejectInit;
+    private initTimer;
+    private ready;
+    private pending;
+    private nextId;
+    constructor(options?: CVWorkerClientOptions);
+    /**
+     * Spawns the worker (`workerUrl`, default: the packaged `cv-worker.js`) and loads
+     * OpenCV from `opencvUrl`. While a load is pending or after it succeeded, returns
+     * the same promise (different urls are ignored).
+     * After any failure a later call retries with a fresh Worker.
+     */
+    init(opencvUrl?: string, workerUrl?: string): Promise<void>;
+    isReady(): boolean;
+    /** `opts.prior`: the previous frame's corners, used by the detector to rank candidates. */
+    analyze(img: ImageDataLike, opts?: {
+        prior?: Quad;
+    }): Promise<CvDetectionResult>;
+    warp(img: ImageDataLike, corners: Quad, docType: DocumentType | null, longSide?: number): Promise<ImageData>;
+    /**
+     * Stops the worker and rejects every pending request. Idempotent. A pending
+     * `init()` is left unsettled (callers that stop mid-load are not told it failed).
+     */
+    terminate(): void;
+    /** Failure path: shuts down, then rejects a pending `init()` with the same error. */
+    private fail;
+    private clearInitTimer;
+    private shutdown;
+    private request;
+}
+
+type WorkerClient = Pick<CVWorkerClient, 'init' | 'isReady' | 'analyze' | 'warp' | 'terminate'>;
+/**
+ * @internal Test seam (second constructor argument). Not part of the public,
+ * documented API and may change without notice.
+ */
+interface XidCameraOcrSessionDeps {
+    createWorkerClient(opts: {
+        initTimeoutMs: number;
+    }): WorkerClient;
+    attachCamera(video: HTMLVideoElement): Promise<MediaStream>;
+    detachCamera(video: HTMLVideoElement, stream: MediaStream | null): void;
+    sampleFrame(video: HTMLVideoElement, targetWidth: number): ImageDataLike | null;
+    grabFrame(video: HTMLVideoElement): ImageDataLike | null;
+    encodeJpeg(img: ImageData, quality: number): Promise<Blob>;
+    snapshotToBlob(video: HTMLVideoElement, quality: number): Promise<Blob>;
+    supportsTorch(track: MediaStreamTrack): boolean;
+    setTorch(track: MediaStreamTrack, on: boolean): Promise<boolean>;
+    now(): number;
+}
+declare class XidCameraOcrSession {
+    private readonly opts;
+    private readonly deps;
+    private stream;
+    private track;
+    private cv;
+    /** Bumped by start()/stop(); any async continuation from an older generation is dropped. */
+    private generation;
+    private timer;
+    private frameCallback;
+    /** The in-flight analyze request, so a manual capture never overlaps it. */
+    private inFlight;
+    /** 0 = not armed yet (armed on the first analysed frame and after each capture). */
+    private warmupUntil;
+    private capturing;
+    /** Set once a capture has been taken; the auto-shutter stays off until the next start(). */
+    private autoShutterSpent;
+    private torchSupported;
+    private torchOn;
+    private torchRejected;
+    /** True when any frame of the current stable run came from a weak (`reduced`/`lowres`) winner. */
+    private weakRun;
+    /**
+     * Temporal prior for the detector: the previous analysed frame's corners and the size
+     * of that frame. Cleared on a frame without detection, a frame-size change, start(),
+     * stop() and after a capture.
+     */
+    private prior;
+    private readonly stability;
+    state: SessionState;
+    constructor(options: XidCameraOcrSessionOptions, deps?: Partial<XidCameraOcrSessionDeps>);
+    start(): Promise<void>;
+    stop(): void;
+    captureNow(): Promise<void>;
+    getState(): SessionState;
+    /** Waits `delayMs`, then for the next video frame when the browser exposes rVFC. */
+    private scheduleNext;
+    private tick;
+    private analyzeFrame;
+    /** Non-fatal detector failure: drop the worker, stop the loop, keep the camera and manual capture. */
+    private detectorUnavailable;
+    private updateTorch;
+    /** Reprojects a sample-frame quad onto the full video frame; null when degenerate. */
+    private fullFrameQuad;
+    /** `fullQuad` is already in full-frame pixels; null means "unwarped frame". */
+    private doCapture;
+    private captureBlob;
+    /** Clears every timer and frame callback, turns the torch off, closes the camera and drops the worker. */
+    private release;
+    private setStatus;
+    private emitError;
+}
+
+/**
+ * Document detection with OpenCV (worker side). Mat work only — geometry and
+ * quality are pure modules. Every Mat is `.delete()`d in `finally`.
+ * Pipeline (spec §5.2): grey → CLAHE → bilateral → auto-Canny → dilate →
+ * findContours(RETR_LIST) → convex hull → approxPolyDP (ε = 2 % perimeter) → 4 convex
+ * vertices, ≤ 1 corner on the frame border, angles ∈ [70°, 110°] → score
+ * 0.5·area + 0.3·rectangularity + 0.2·aspect → veto a winner nested in a border-cut
+ * outline → quality on the winner inset by the dilation band.
+ *
+ * RETR_LIST, not RETR_EXTERNAL: the zero padding draws an edge around the whole
+ * frame, and RETR_EXTERNAL would return only that outer contour (area > 95 %,
+ * rejected) and hide the document inside it.
+ */
+
+interface DetectOptions {
+    /** Previous frame's corners (TL, TR, BR, BL) in analysed-frame pixels; ranking only. */
+    prior?: Quad;
+}
+declare function detectDocumentCV(cv: any, imageData: ImageDataLike, _acceptedTypes?: DocumentType[], opts?: DetectOptions): CvDetectionResult;
+
+/**
+ * Perspective warp with OpenCV: rectifies the document to its canonical rectangle.
+ *
+ *   - warpDocumentImageData: ImageData in / ImageData out, worker-safe (no DOM).
+ *   - warpDocument / warpedSnapshotToBlob: canvas based, main thread only.
+ *
+ * Corners are in the full-resolution camera frame (not the analysis sample); OpenCV
+ * computes the 3x3 homography and warpPerspective returns the document head-on.
+ */
+
+/**
+ * Pure warp: ImageData → ImageData, no DOM dependency (runs inside the Web Worker).
+ * INE / PASSPORT_MX warp to their nominal ratio; OTHER / null warp to the measured
+ * rectified aspect, clamped to the capturable range so a degenerate quad cannot yield
+ * a 0 px or absurd output.
+ */
+declare function warpDocumentImageData(cv: any, source: ImageDataLike, corners: Quad, docType: DocumentType | null, longSide?: number): ImageData;
+/** Canvas-based warp (main thread only): canvas → warpDocumentImageData → new canvas. */
+declare function warpDocument(cv: any, sourceCanvas: HTMLCanvasElement, corners: Quad, docType: DocumentType | null, longSide?: number): HTMLCanvasElement;
+/** Rectified snapshot as a JPEG Blob; without corners, a plain snapshot of the canvas. */
+declare function warpedSnapshotToBlob(cv: any, sourceCanvas: HTMLCanvasElement, corners: Quad | null, docType: DocumentType | null, quality?: number, longSide?: number): Promise<Blob>;
+
+/**
+ * Frame quality measured INSIDE the detected quad (spec §5.4). Pure TS over a
+ * grayscale buffer so it runs in the worker right after detection (one round
+ * trip) and in Vitest without OpenCV.
+ */
+
+interface GrayFrame {
+    data: Uint8Array | Uint8ClampedArray;
+    width: number;
+    height: number;
+}
+declare const QUALITY_THRESHOLDS: {
+    readonly brightnessMin: 0.18;
+    readonly brightnessMax: 0.9;
+    readonly blurMin: 60;
+    readonly glareMax: 0.04;
+    readonly fillMin: 0.25;
+    readonly glarePixel: 248;
+};
+declare function measureQuality(gray: GrayFrame, quad: Quad): FrameQuality;
+
+/**
+ * Camera helpers — getUserMedia + video element wiring.
+ */
+declare function attachCamera(videoElement: HTMLVideoElement, constraints?: MediaStreamConstraints): Promise<MediaStream>;
+declare function detachCamera(videoElement: HTMLVideoElement, stream: MediaStream | null): void;
+/** Captura un snapshot del video y devuelve un Blob JPEG. */
+declare function snapshotToBlob(videoElement: HTMLVideoElement, quality?: number): Promise<Blob>;
+/** Downscaled RGBA frame for analysis (default 640 px wide). Reuses one canvas. */
+declare function sampleFrame(videoElement: HTMLVideoElement, targetWidth?: number): ImageData | null;
+declare function supportsTorch(track: MediaStreamTrack): boolean;
+/** Best-effort torch toggle. Resolves `true` when the constraint was accepted. */
+declare function setTorch(track: MediaStreamTrack, on: boolean): Promise<boolean>;
+
+declare function decideHint(a: {
+    detected: boolean;
+    quality: FrameQuality | null;
+    stableFrames: number;
+    stableFramesRequired: number;
+}): FrameHint;
+/** Every user-visible text of the component. `retake`, `capture`, `tip_*` and `tips_dismiss` are UI copy that `copyFor` never returns. */
+type HintCopyKey = FrameHint | 'loading_detector' | 'capturing' | 'uploading' | 'done' | 'error' | 'retake' | 'idle' | 'starting' | 'capture' | 'tip_light' | 'tip_glare' | 'tip_focus' | 'tips_dismiss';
+type HintCopy = Record<HintCopyKey, string>;
+/** Default texts (es-MX). Product copy: do not reword. */
+declare const DEFAULT_TEXTS_ES: Readonly<HintCopy>;
+/** English texts (the 0.4.0 copy plus the new keys). */
+declare const DEFAULT_TEXTS_EN: Readonly<HintCopy>;
+/** Full text set: es-MX defaults with the given overrides applied per key. */
+declare function resolveTexts(overrides?: Partial<HintCopy>): HintCopy;
+declare function copyFor(status: SessionStatus, hint: FrameHint | undefined, overrides?: Partial<HintCopy>): string;
+
+/**
+ * Stability tracker (pure). A quad is stable when, frame after frame, every
+ * corner moves ≤ 1.5 % of the frame diagonal and the type hint is unchanged.
+ * Any frame without a detection resets the count (spec §5.3).
+ *
+ * The type hint has hysteresis: camera jitter can flick the measured aspect
+ * across a band edge (INE ↔ OTHER), so a different hint is only a candidate
+ * until it persists `hintSwitchFrames` consecutive frames. While pending,
+ * geometry keeps counting and the committed hint is reported; on commit the
+ * count restarts at 1 (the document really changed).
+ */
+
+interface StabilityInput {
+    quad: Quad;
+    typeHint: DocumentType;
+}
+interface StabilitySnapshot {
+    stableFrames: number;
+    isStable: boolean;
+    quad: Quad | null;
+    typeHint: DocumentType | null;
+}
+declare class StabilityTracker {
+    private readonly required;
+    private readonly maxRatio;
+    private readonly switchFrames;
+    private current;
+    private candidate;
+    constructor(opts?: {
+        stableFramesRequired?: number;
+        maxDisplacementRatio?: number;
+        hintSwitchFrames?: number;
+    });
+    get snapshot(): StabilitySnapshot;
+    reset(): void;
+    update(input: StabilityInput | null, frameSize: {
+        width: number;
+        height: number;
+    }): StabilitySnapshot;
+}
+
+/**
+ * Theme variables for the `<XidCameraOcr />` component.
+ *
+ * The component reads every colour, font and radius as `var(--xco-*, <default>)`
+ * and writes a variable only when the `theme` prop sets it, so the stylesheet
+ * defaults below are the single source of truth for the fallbacks.
+ */
+
+type XcoThemeKey = 'accent' | 'warning' | 'danger' | 'background' | 'mask' | 'hintBg' | 'hintFg' | 'buttonBg' | 'buttonFg' | 'shutter' | 'overlayBg' | 'overlayFg' | 'fontFamily' | 'radius';
+type XidCameraOcrTheme = Partial<Record<XcoThemeKey, string>>;
+declare const XCO_VARS: Readonly<Record<XcoThemeKey, {
+    name: `--xco-${string}`;
+    fallback: string;
+}>>;
+
+interface UseXidCameraOcrOptions extends Omit<XidCameraOcrSessionOptions, 'videoElement'> {
+    /** When `true`, starts the stream automatically on mount. Default `true`. */
+    autoStart?: boolean;
+}
+interface UseXidCameraOcrReturn {
+    videoRef: React.RefObject<HTMLVideoElement>;
+    status: SessionState['status'];
+    frame: FrameState | null;
+    result: ExtractResult | null;
+    error: Error | null;
+    start: () => Promise<void>;
+    stop: () => void;
+    captureNow: () => Promise<void>;
+    /** Stops the current run and starts a new one (re-arms the auto-shutter). */
+    retake: () => Promise<void>;
+}
+declare function useXidCameraOcr(options: UseXidCameraOcrOptions): UseXidCameraOcrReturn;
+
+interface XidCameraOcrProps extends UseXidCameraOcrOptions {
+    className?: string;
+    style?: React.CSSProperties;
+    hideStatusOverlay?: boolean;
+    /** Per-key override of the es-MX default texts. */
+    texts?: Partial<HintCopy>;
+    /** Theme variables written to the root as `--xco-*` custom properties. */
+    theme?: XidCameraOcrTheme;
+    /** Show the capture tips card. Default `true`. */
+    showTips?: boolean;
+}
+declare function XidCameraOcr({ className, style, hideStatusOverlay, texts: textOverrides, theme, showTips, ...sessionOptions }: XidCameraOcrProps): react.JSX.Element;
+
+export { CVWorkerClient, type CornerPoint, type CvDetectionResult, DEFAULT_TEXTS_EN, DEFAULT_TEXTS_ES, type DocumentType, type ExtractResult, type FrameHint, type FrameQuality, type FrameState, type HintCopy, type HintCopyKey, ID1_RATIO, type Point, QUALITY_THRESHOLDS, type Quad, type SessionState, type SessionStatus, StabilityTracker, TD3_RATIO, type UseXidCameraOcrOptions, type UseXidCameraOcrReturn, XCO_VARS, type XcoThemeKey, XidCameraOcr, type XidCameraOcrProps, XidCameraOcrSession, type XidCameraOcrSessionOptions, type XidCameraOcrTheme, attachCamera, copyFor, decideHint, defaultOpencvUrl, detachCamera, detectDocumentCV, isCapturableAspect, measureQuality, orderCorners, rectifiedAspect, resolveTexts, sampleFrame, setTorch, snapshotToBlob, supportsTorch, typeHintFromAspect, useXidCameraOcr, warpDocument, warpDocumentImageData, warpedSnapshotToBlob };