@microblink/blinkid-ux-manager 7.4.2 → 7.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microblink/blinkid-ux-manager",
-  "version": "7.4.2",
+  "version": "7.4.3",
   "author": "Microblink",
   "type": "module",
   "main": "./dist/blinkid-ux-manager.js",
@@ -11,8 +11,8 @@
     "types"
   ],
   "dependencies": {
-    "@microblink/blinkid-core": "^7.4.2",
-    "@microblink/camera-manager": "^7.2.4",
+    "@microblink/blinkid-core": "^7.4.3",
+    "@microblink/camera-manager": "^7.2.5",
     "type-fest": "^4.35.0"
   },
   "access": "public",

package/types/index.rollup.d.ts

@@ -0,0 +1,584 @@
+import { BlinkIdScanningResult } from '@microblink/blinkid-core';
+import { BlinkIdSessionSettings } from '@microblink/blinkid-core';
+import { CameraManager } from '@microblink/camera-manager';
+import { CameraManagerComponent } from '@microblink/camera-manager';
+import { DocumentClassInfo } from '@microblink/blinkid-core';
+import { InputImageAnalysisResult } from '@microblink/blinkid-core';
+import { ProcessResultWithBuffer } from '@microblink/blinkid-core';
+import { RemoteScanningSession } from '@microblink/blinkid-core';
+import { ResultCompleteness } from '@microblink/blinkid-core';
+import { ScanningSettings } from '@microblink/blinkid-core';
+import { StringKeyOf } from 'type-fest';
+
+/**
+ * Copyright (c) 2025 Microblink Ltd. All rights reserved.
+ */
+/**
+ * BlinkID processing error. These errors are usually unrecoverable and require
+ * the user to retry the scanning process.
+ */
+export declare type BlinkIdProcessingError = "timeout" | "unknown";
+
+/**
+ * The type of reticle to display.
+ */
+export declare type BlinkIdReticleType = "searching" | "processing" | "error" | "done" | "flip" | "move_top" | "move_left" | "move_right";
+
+/**
+ * The UI state of BlinkID.
+ */
+export declare type BlinkIdUiState = BlinkIdUiStateMap[keyof BlinkIdUiStateMap];
+
+/**
+ * The key of the UI state.
+ */
+export declare type BlinkIdUiStateKey = "FLIP_CARD" | "DOCUMENT_CAPTURED" | "SENSING_FRONT" | "SENSING_BACK" | "SENSING_DATA_PAGE" | "SENSING_TOP_PAGE" | "SENSING_LEFT_PAGE" | "SENSING_RIGHT_PAGE" | "MOVE_TOP" | "MOVE_LEFT" | "MOVE_RIGHT" | "DOCUMENT_FRAMING_CAMERA_TOO_FAR" | "DOCUMENT_FRAMING_CAMERA_TOO_CLOSE" | "DOCUMENT_FRAMING_CAMERA_ANGLE_TOO_STEEP" | "DOCUMENT_TOO_CLOSE_TO_FRAME_EDGE" | "BLUR_DETECTED" | "GLARE_DETECTED" | "TOO_DARK" | "TOO_BRIGHT" | "OCCLUDED" | "FACE_PHOTO_OCCLUDED" | "UNSUPPORTED_DOCUMENT" | "SCAN_BARCODE" | "WRONG_TOP_PAGE" | "WRONG_LEFT_PAGE" | "WRONG_RIGHT_PAGE" | "WRONG_SIDE";
+
+/**
+ * Extended UI state for BlinkID.
+ *
+ * @template K - The key of the UI state.
+ */
+export declare type BlinkIdUiStateMap = {
+    [K in BlinkIdUiStateKey]: UiState & {
+        /** The key of the UI state. */
+        key: K;
+        /** The type of the reticle. */
+        reticleType: BlinkIdReticleType;
+    };
+};
+
+/**
+ * The UI state map of BlinkID.
+ */
+export declare const blinkIdUiStateMap: BlinkIdUiStateMap;
+
+/**
+ * The BlinkIdUxManager class. This is the main class that manages the UX of
+ * the BlinkID SDK. It is responsible for handling the UI state, the timeout,
+ * the help tooltip, and the document class filter.
+ */
+export declare class BlinkIdUxManager {
+    #private;
+    /** The camera manager. */
+    cameraManager: CameraManager;
+    /** The scanning session. */
+    scanningSession: RemoteScanningSession;
+    /** Whether the demo overlay should be shown. */
+    showDemoOverlay: boolean;
+    /** Whether the production overlay should be shown. */
+    showProductionOverlay: boolean;
+    /** The current UI state. */
+    uiState: BlinkIdUiState;
+    /** The raw UI state key. */
+    rawUiStateKey: BlinkIdUiStateKey;
+    /** The feedback stabilizer. */
+    feedbackStabilizer: FeedbackStabilizer<typeof blinkIdUiStateMap>;
+    /** The session settings. */
+    sessionSettings: BlinkIdSessionSettings;
+    /**
+     * The constructor for the BlinkIdUxManager class.
+     *
+     * @param cameraManager - The camera manager.
+     * @param scanningSession - The scanning session.
+     */
+    constructor(cameraManager: CameraManager, scanningSession: RemoteScanningSession);
+    /**
+     * Indicates whether the UI should display the demo overlay. Controlled by the
+     * license property.
+     */
+    getShowDemoOverlay(): boolean;
+    /**
+     * Indicates whether the UI should display the production overlay. Controlled by
+     * the license property.
+     */
+    getShowProductionOverlay(): boolean;
+    /**
+     * Returns the timeout duration in ms. Null if timeout won't be triggered ever.
+     */
+    getTimeoutDuration(): number | null;
+    /**
+     * Returns the time in ms before the help tooltip is shown. Null if tooltip won't be auto shown.
+     */
+    getHelpTooltipShowDelay(): number | null;
+    /**
+     * Returns the time in ms before the help tooltip is hidden. Null if tooltip won't be auto hidden.
+     */
+    getHelpTooltipHideDelay(): number | null;
+    /**
+     * Adds a callback function to be executed when the UI state changes.
+     *
+     * @param callback - Function to be called when UI state changes. Receives the
+     * new UI state as parameter.
+     * @returns A cleanup function that removes the callback when called.
+     *
+     * @example
+     * const cleanup = manager.addOnUiStateChangedCallback((newState) => {
+     *   console.log('UI state changed to:', newState);
+     * });
+     *
+     * cleanup();
+     */
+    addOnUiStateChangedCallback(callback: (uiState: BlinkIdUiState) => void): () => void;
+    /**
+     * Registers a callback function to be called when a scan result is available.
+     *
+     * @param callback - A function that will be called with the scan result.
+     * @returns A cleanup function that, when called, will remove the registered
+     * callback.
+     *
+     * @example
+     *
+     * const cleanup = manager.addOnResultCallback((result) => {
+     *   console.log('Scan result:', result);
+     * });
+     *
+     * // Later, to remove the callback:
+     * cleanup();
+     */
+    addOnResultCallback(callback: (result: BlinkIdScanningResult) => void): () => void;
+    /**
+     * Registers a callback function to filter document classes.
+     *
+     * @param callback - A function that will be called with the document class
+     * info.
+     * @returns A cleanup function that, when called, will remove the registered
+     * callback.
+     *
+     * @example
+     * const cleanup = manager.addDocumentClassFilter((docClassInfo) => {
+     *   return docClassInfo.country === 'usa';
+     * });
+     *
+     * // Later, to remove the callback:
+     * cleanup();
+     */
+    addDocumentClassFilter(callback: DocumentClassFilter): () => void;
+    /**
+     * Registers a callback function to be called when a frame is processed.
+     *
+     * @param callback - A function that will be called with the frame analysis
+     * result.
+     * @returns A cleanup function that, when called, will remove the registered
+     * callback.
+     *
+     * @example
+     * const cleanup = manager.addOnFrameProcessCallback((frameResult) => {
+     *   console.log('Frame processed:', frameResult);
+     * });
+     *
+     * // Later, to remove the callback:
+     * cleanup();
+     */
+    addOnFrameProcessCallback(callback: (frameResult: ProcessResultWithBuffer) => void): () => void;
+    /**
+     * Registers a callback function to be called when an error occurs during
+     * processing.
+     *
+     * @param callback - A function that will be called with the error state.
+     * @returns A cleanup function that, when called, will remove the registered
+     * callback.
+     *
+     * @example
+     * const cleanup = manager.addOnErrorCallback((error) => {
+     *   console.error('Processing error:', error);
+     * });
+     *
+     * // Later, to remove the callback:
+     * cleanup();
+     */
+    addOnErrorCallback(callback: (errorState: BlinkIdProcessingError) => void): () => void;
+    /**
+     * Registers a callback function to be called when a document is filtered.
+     *
+     * @param callback - A function that will be called with the document class
+     * info.
+     * @returns A cleanup function that, when called, will remove the registered
+     * callback.
+     *
+     * @example
+     * const cleanup = manager.addOnDocumentFilteredCallback((docClassInfo) => {
+     *   console.log('Document filtered:', docClassInfo);
+     * });
+     *
+     * // Later, to remove the callback:
+     * cleanup();
+     */
+    addOnDocumentFilteredCallback(callback: (documentClassInfo: DocumentClassInfo) => void): () => void;
+    /**
+     * Sets the duration after which the scanning session will timeout. The
+     * timeout can occur in various scenarios and may be restarted by different
+     * scanning events.
+     *
+     * @param duration The timeout duration in milliseconds. If null, timeout won't
+     * be triggered ever.
+     * @param setHelpTooltipShowDelay If true, also sets the help tooltip show
+     * delay to half of the provided duration. If timeout duration is null, help
+     * tooltip show delay will be set to null. Defaults to true.
+     * @throws {Error} Throws an error if duration is less than or equal to 0 when not null.
+     */
+    setTimeoutDuration(duration: number | null, setHelpTooltipShowDelay?: boolean): void;
+    /**
+     * Sets the duration in milliseconds before the help tooltip is shown.
+     * A value of null means the help tooltip will not be auto shown.
+     *
+     * @param duration The duration in milliseconds before the help tooltip is
+     * shown. If null, tooltip won't be auto shown.
+     * @throws {Error} Throws an error if duration is less than or equal to 0 when
+     * not null.
+     */
+    setHelpTooltipShowDelay(duration: number | null): void;
+    /**
+     * Sets the duration in milliseconds before the help tooltip is hidden.
+     * A value of null means the help tooltip will not be auto hidden.
+     *
+     * @param duration The duration in milliseconds before the help tooltip is
+     * hidden. If null, tooltip won't be auto hidden.
+     * @throws {Error} Throws an error if duration is less than or equal to 0 when
+     * not null.
+     */
+    setHelpTooltipHideDelay(duration: number | null): void;
+    /**
+     * Clears the scanning session timeout.
+     */
+    clearScanTimeout: () => void;
+    /**
+     * Gets the result from the scanning session.
+     *
+     * @param deleteSession - Whether to delete the session after getting the result. Note that
+     * it is not possible to get the result a second time after the document has been fully captured,
+     * so in this case we should delete the scanning session since it is no longer needed.
+     * @returns The result.
+     */
+    getSessionResult(deleteSession?: boolean): Promise<BlinkIdScanningResult>;
+    /**
+     * Safely deletes the scanning session.
+     */
+    safelyDeleteScanningSession(): Promise<void>;
+    /**
+     * Resets the scanning session.
+     *
+     * @param startFrameCapture Whether to start frame processing.
+     */
+    resetScanningSession(startFrameCapture?: boolean): Promise<void>;
+    /**
+     * Resets the BlinkIdUxManager. Clears all callbacks.
+     *
+     * Does not reset the camera manager or the scanning session.
+     */
+    reset(): void;
+}
+
+/**
+ * Creates the BlinkID feedback UI.
+ *
+ * @param blinkIdUxManager - The BlinkID Ux Manager.
+ * @param cameraManagerComponent - The Camera Manager Component.
+ * @param options - The options for the createBlinkIdFeedbackUi function.
+ *
+ * @returns The function to unmount the feedback UI.
+ */
+export declare function createBlinkIdFeedbackUi(blinkIdUxManager: BlinkIdUxManager, cameraManagerComponent: CameraManagerComponent, { localizationStrings, preserveSdkInstance, showOnboardingGuide, showHelpButton, showDocumentFilteredModal, showTimeoutModal, showUnsupportedDocumentModal, }?: FeedbackUiOptions): () => void;
+
+/**
+ * The English localization strings.
+ */
+declare const _default: {
+    readonly scan_the_front_side: "Scan the front side of the document";
+    readonly scan_data_page: "Scan the data page of the document";
+    readonly scan_top_page: "Scan the top page";
+    readonly scan_left_page: "Scan the left page";
+    readonly scan_right_page: "Scan the right page";
+    readonly flip_document: "Flip the document";
+    readonly wrong_top: "Move to the top page";
+    readonly wrong_left: "Move to the left page";
+    readonly wrong_right: "Move to the right page";
+    readonly flip_to_back_side: "Flip to the back side";
+    readonly move_top: "Move to the page on top";
+    readonly move_left: "Move to the page on the left";
+    readonly move_right: "Move to the page on the right";
+    readonly scan_the_back_side: "Scan the back side of the document";
+    readonly scan_the_barcode: "Scan the barcode";
+    readonly move_closer: "Move closer";
+    readonly move_farther: "Move farther";
+    readonly camera_angle_too_steep: "Keep document parallel to phone";
+    readonly face_photo_not_fully_visible: "Keep face photo fully visible";
+    readonly document_too_close_to_edge: "Move the document from the edge";
+    readonly blur_detected: "Keep document and phone still";
+    readonly glare_detected: "Tilt or move document to remove reflection";
+    readonly occluded: "Keep the document fully visible";
+    readonly too_dark: "Move to brighter spot";
+    readonly too_bright: "Move to spot with less lighting";
+    readonly scan_unsuccessful: "Scan unsuccessful";
+    readonly scan_unsuccessful_details: "Unable to read the document. Please try again.";
+    readonly document_not_recognized: "Document not recognized";
+    readonly document_not_recognized_details: "Scan the front side of a supported document.";
+    readonly document_filtered: "Document not accepted";
+    readonly document_filtered_details: "Try scanning a different document.";
+    readonly onboarding_modal_title: "Keep all the details visible";
+    readonly onboarding_modal_details: "Make sure you keep the document well lit. All document fields should be visible on the camera screen.";
+    readonly onboarding_modal_btn: "Start scanning";
+    readonly help_modal_title_1: "Keep all the fields visible";
+    readonly help_modal_details_1: "Make sure you aren’t covering parts of the document with a finger, including the bottom lines. Also, watch out for hologram reflections that go over the document fields.";
+    readonly help_modal_title_2: "Watch out for harsh light";
+    readonly help_modal_details_2: "Avoid direct harsh light because it reflects from the document and can make parts of the document unreadable. If you can’t read data on the document, it won’t be visible to the camera either.";
+    readonly help_modal_title_3: "Keep still while scanning";
+    readonly help_modal_details_3: "Try to keep the phone and document still while scanning. Moving either can blur the image and make data on the document unreadable.";
+    readonly help_modal_back_btn: "Back";
+    readonly help_modal_next_btn: "Next";
+    readonly help_modal_done_btn: "Done";
+    readonly help_aria_label: "Help";
+    readonly help_tooltip: "Need help?";
+    readonly alert_retry_btn: "Retry";
+    readonly alert_cancel_btn: "Cancel";
+};
+
+/**
+ * A type representing a filter function for document classification.
+ *
+ * This function is used to determine whether a document class is supported or
+ * not. It takes a `DocumentClassInfo` object as input and returns a boolean
+ * value:
+ * - `true`: The document class is supported.
+ * - `false`: The document class is not supported, and the document will be
+ * marked as "unsupported-document".
+ *
+ * @param documentClassInfo - Information about the document class, such as country and type.
+ *
+ * @returns A boolean indicating whether the document class is supported.
+ */
+export declare type DocumentClassFilter = (documentClassInfo: DocumentClassInfo) => boolean;
+
+/**
+ * FeedbackStabilizer provides UI state management with temporal smoothing.
+ *
+ * It helps prevent UI "flickering" by:
+ * - Maintaining a time-windowed history of UI state changes
+ * - Applying weighted averaging to determine the most appropriate state
+ * - Supporting immediate state changes through single-emit events
+ * - Enforcing minimum display durations for states
+ *
+ * @typeParam SdkSpecificStateMap - Type extending UiStateMap for SDK-specific states
+ */
+export declare class FeedbackStabilizer<SdkSpecificStateMap extends UiStateMap> {
+    /** The initial key. */
+    private initialKey;
+    /** The UI state map. */
+    private uiStateMap;
+    /** Time window (in ms) for considering UI state events. */
+    private timeWindow;
+    /** The decay rate. */
+    /** Rate at which event weights decay over time */
+    private decayRate;
+    /** Queue of regular UI state events within the time window */
+    private eventQueue;
+    /** Special queue for single-emit events that bypass normal stabilization */
+    private singleEventQueue;
+    /** Currently displayed state key */
+    private currentKey;
+    /** Timestamp when current state started displaying */
+    private currentStateStartTime;
+    /** Accumulated scores for each state in current calculation */
+    private summedScores;
+    /** History of scores for each state */
+    private scoreBoard;
+    /**
+     * Gets the currently active UI state configuration.
+     *
+     * @returns The currently active UI state configuration.
+     */
+    get currentState(): SdkSpecificStateMap[`${Extract<keyof SdkSpecificStateMap, string | number>}`];
+    /**
+     * Gets a copy of the current event queue for debugging.
+     *
+     * @returns A copy of the current event queue.
+     */
+    getEventQueue(): UiStateEvent[];
+    /**
+     * Gets the current summed scores for each state.
+     *
+     * @returns The current summed scores for each state.
+     */
+    getScores(): Record<string, number>;
+    /**
+     * Gets the score history for each state.
+     *
+     * @returns The score history for each state.
+     */
+    getScoreBoard(): Record<string, number[]>;
+    /**
+     * Updates the time window used for state stabilization
+     *
+     * @param timeWindow - New time window in milliseconds
+     */
+    setTimeWindow(timeWindow: number): void;
+    /**
+     * Creates a new FeedbackStabilizer instance.
+     *
+     * @param uiStateMap - Map of all possible UI states and their configurations
+     * @param initialKey - Key of the initial UI state to display
+     * @param timeWindow - Optional custom time window (in ms) for state averaging
+     * @param decayRate - Optional custom decay rate for event weights
+     */
+    constructor(uiStateMap: SdkSpecificStateMap, initialKey: StringKeyOf<SdkSpecificStateMap>, timeWindow?: number, decayRate?: number);
+    /**
+     * Resets the stabilizer to its initial state.
+     *
+     * @returns The initial state.
+     */
+    reset(): void;
+    /**
+     * Checks if enough time has passed to show a new UI state
+     *
+     * @returns true if the current state's minimum duration has elapsed
+     */
+    canShowNewUiState: () => boolean;
+    /**
+     * Processes a new UI state event and determines the state to display.
+     *
+     * This method:
+     * 1. Handles single-emit events that bypass normal stabilization
+     * 2. Maintains a time-windowed queue of regular events
+     * 3. Applies temporal averaging with decay to determine the winning state
+     *
+     * @param incomingUiStateKey - Key of the new UI state event
+     * @returns The UI state that should be displayed.
+     */
+    getNewUiState(incomingUiStateKey: StringKeyOf<SdkSpecificStateMap>): SdkSpecificStateMap[StringKeyOf<SdkSpecificStateMap>];
+}
+
+/**
+ * The options for the createBlinkIdFeedbackUi function.
+ */
+export declare type FeedbackUiOptions = {
+    /**
+     * The localization strings.
+     */
+    localizationStrings?: Partial<LocalizationStrings>;
+    /**
+     * If set to `true`, the BlinkID instance will not be terminated when the
+     * feedback UI is unmounted.
+     *
+     * @defaultValue false
+     */
+    preserveSdkInstance?: boolean;
+    /**
+     * If set to `true`, the onboarding guide will be shown.
+     *
+     * @defaultValue true
+     */
+    showOnboardingGuide?: boolean;
+    /**
+     * If set to `true`, the help button will be shown.
+     *
+     * @defaultValue true
+     */
+    showHelpButton?: boolean;
+    /**
+     * If set to `true`, the document filtered modal will be shown.
+     *
+     * @defaultValue true
+     */
+    showDocumentFilteredModal?: boolean;
+    /**
+     * If set to `true`, the timeout modal will be shown.
+     *
+     * @defaultValue true
+     */
+    showTimeoutModal?: boolean;
+    /**
+     * If set to `true`, the document unsupported modal will be shown.
+     *
+     * @defaultValue true
+     */
+    showUnsupportedDocumentModal?: boolean;
+};
+
+/**
+ * The states that are captured when the first side is captured.
+ */
+export declare const firstSideCapturedStates: BlinkIdUiStateKey[];
+
+/**
+ * Determines the appropriate UI state key based on the current frame processing
+ * result and scanning settings.
+ *
+ * This function acts as a state machine, translating the low-level analysis and
+ * completeness results into a high-level UI state that drives the user
+ * interface.
+ *
+ * @param frameProcessResult - The current (possibly partial) result of frame
+ * processing, including image analysis and completeness.
+ * @param settings - Optional scanning settings that may influence state
+ * selection.
+ * @returns The UI state key representing what should be shown to the user.
+ */
+export declare function getUiStateKey(frameProcessResult: PartialProcessResult, settings?: Partial<ScanningSettings>): BlinkIdUiStateKey;
+
+/**
+ * The locale record type.
+ */
+export declare type LocaleRecord = typeof _default;
+
+/**
+ * The localization strings type.
+ */
+export declare type LocalizationStrings = {
+    [K in keyof LocaleRecord]: LocaleRecord[K] | (string & {});
+};
+
+/**
+ * The partial process result.
+ */
+export declare type PartialProcessResult = {
+    /** The input image analysis result. */
+    inputImageAnalysisResult: Partial<InputImageAnalysisResult>;
+    /** The result completeness. */
+    resultCompleteness: Partial<ResultCompleteness>;
+};
+
+/**
+ * Represents a UI state configuration with timing and weight parameters.
+ * Used to define how different UI states should behave in the stabilization process.
+ */
+export declare type UiState = {
+    /** Unique identifier for the UI state */
+    key: string;
+    /** Minimum duration (in milliseconds) this state should be displayed */
+    minDuration: number;
+    /**
+     * If true, the event will be emitted once the previous event is done.
+     * It bypasses the averaging process and is handled separately.
+     */
+    singleEmit?: boolean;
+    /**
+     * Initial weight for this state when it enters the stabilization queue.
+     * Higher values give the state more influence in the averaging process.
+     */
+    initialWeight?: number;
+};
+
+/**
+ * Represents a UI state event in the stabilization queue.
+ * These events are processed to determine which UI state should be displayed.
+ */
+export declare type UiStateEvent = {
+    /** Identifier matching a UI state key */
+    key: string;
+    /** High-resolution timestamp when the event occurred */
+    timeStamp: DOMHighResTimeStamp;
+    /** Current weight of this event in the stabilization process */
+    currentWeight: number;
+    /**
+     * If true, this event will be emitted once the previous event completes.
+     * It bypasses the normal stabilization process.
+     */
+    singleEmit?: boolean;
+};
+
+/**
+ * Maps state keys to their corresponding UI state configurations.
+ */
+export declare type UiStateMap = Record<string, UiState>;
+
+export { }