@microblink/capture 1.1.1 → 1.2.0

package/types/index.d.ts

@@ -40,7 +40,7 @@ export declare class Analyzer extends EmbindObject {
 }
 
 /**
- * Copyright (c) 2023 Microblink Ltd. All rights reserved.
+ * Copyright (c) 2024 Microblink Ltd. All rights reserved.
  *
  * ANY UNAUTHORIZED USE OR SALE, DUPLICATION, OR DISTRIBUTION
  * OF THIS PROGRAM OR ANY OF ITS PARTS, IN SOURCE OR BINARY FORMS,
@@ -64,7 +64,7 @@ export declare type AnalyzerResult = {
 };
 
 /**
- * Copyright (c) 2023 Microblink Ltd. All rights reserved.
+ * Copyright (c) 2024 Microblink Ltd. All rights reserved.
  *
  * ANY UNAUTHORIZED USE OR SALE, DUPLICATION, OR DISTRIBUTION
  * OF THIS PROGRAM OR ANY OF ITS PARTS, IN SOURCE OR BINARY FORMS,
@@ -78,12 +78,13 @@ export declare type AnalyzerResult = {
  */
 export declare type AnalyzerSettings = {
     /**
-     * Whether to capture a single side or capture both sides
+     * Whether to capture a single side or capture all possible sides
+     * Determines whether to capture a single side or capture all possible sides
      * of a document with automatic side detection.
      */
     captureSingleSide: boolean;
     /**
-     * Whether to return an image of a cropped and perspective-corrected document.
+     * Determines whether to return an image of a cropped and perspective-corrected document.
      */
     returnTransformedDocumentImage: boolean;
     /**
@@ -110,10 +111,15 @@ export declare type AnalyzerSettings = {
      */
     documentFramingMargin: number;
     /**
-     * Whether to return an image of the transformed document with applied margin
+     * Determines whether to return an image of the transformed document with applied margin
      * used during document framing.
      */
     keepMarginOnTransformedDocumentImage: boolean;
+    /**
+     * Determines whether to preserve the captured document DPI in transformed document image.
+     * If disabled, the document DPI is downscaled to 400 DPI.
+     */
+    keepDpiOnTransformedDocumentImage: boolean;
     /**
      * Parameters for lighting estimation.
      *
@@ -131,32 +137,45 @@ export declare type AnalyzerSettings = {
      */
     lightingThresholds: LightingThresholds;
     /**
-     * Whether to discard frames with blurred documents.
+     * Defines percentage of the document area that is allowed to be occluded by hand.
      *
-     * If it is enabled, the capture process is allowed to finish with blur on the
-     * document.
+     * Allowed values are from 0 to 1.
      */
-    ignoreBlur: boolean;
+    handOcclusionThreshold: number;
     /**
-     * Whether to discard frames with glare detected on the document.
+     * Defines the tolerance for discarding overly tilted frames.
+     * The following values are possible:
      *
-     * If it is enabled, the capture process is allowed to finish with glare on
-     * the document.
+     * - `"disabled"` - Disables tilt detection.
+     * - `"strict"` - The policy is strict, resulting in more frames being discarded.
+     * - `"normal"` - Trade-off between `"strict"` and `"relaxed"`.
+     * - `"relaxed"` - The policy is relaxed, resulting in fewer frames being discarded.
+     *
+     * @defaultValue `"normal"`
      */
-    ignoreGlare: boolean;
+    tiltPolicy: StrictnessLevel;
     /**
-     * Defines percentage of the document area that is allowed to be occluded by hand.
+     * Defines the tolerance for discarding overly blurred frames.
+     * The following values are possible:
      *
-     * Allowed values are from 0 to 1.
+     * - `"disabled"` - Disables blur detection.
+     * - `"strict"` - The policy is strict, resulting in more frames being discarded.
+     * - `"normal"` - Trade-off between `"strict"` and `"relaxed"`.
+     * - `"relaxed"` - The policy is relaxed, resulting in fewer frames being discarded.
+     *
+     * @defaultValue `"normal"`
      */
-    handOcclusionThreshold: number;
+    blurPolicy: StrictnessLevel;
     /**
-     * Threshold for detecting tilted documents. Frames with documents tilted more
-     * than defined by this threshold are discarded.
+     * Defines the tolerance for discarding frames with excessive glare.
+     * - `"disabled"` - Disables glare detection.
+     * - `"strict"` - The policy is strict, resulting in more frames being discarded.
+     * - `"normal"` - Trade-off between `"strict"` and `"relaxed"`.
+     * - `"relaxed"` - The policy is relaxed, resulting in fewer frames being discarded.
      *
-     * Allowed values are from 0 to 1.
+     * @defaultValue `"normal"`
      */
-    tiltThreshold: number;
+    glarePolicy: StrictnessLevel;
     /**
      * Required minimum DPI of the captured document on transformed image.
      *
@@ -167,9 +186,9 @@ export declare type AnalyzerSettings = {
      */
     minimumDocumentDpi: number;
     /**
-     * Whether to automatically adjust minimum document dpi.
+     * Determines whether to automatically adjust minimum document DPI.
      *
-     * If it is enabled, the minimum dpi is adjusted to optimal value for the
+     * If it is enabled, the minimum DPI is adjusted to optimal value for the
      * provided input resolution to enable capture of all document groups.
      */
     adjustMinimumDocumentDpi: boolean;
@@ -178,6 +197,7 @@ export declare type AnalyzerSettings = {
 export declare type BaltazarRequest = Readonly<{
     licenseId: string;
     licensee: string;
+    applicationIds: Array<string>;
     packageName: string;
     platform: string;
     sdkName: string;
@@ -219,10 +239,17 @@ export declare type CaptureCallbacks = Partial<{
     onCaptureResult: (result: AnalyzerResult) => void;
 }>;
 
+/**
+ * The Capture UI component. Provides methods for controlling the Capture SDK and the UI
+ */
 export declare type CaptureComponent = {
+    /** The instance of the Capture SDK wrapped by the UI */
+    captureSdk: CaptureSdk;
+    /** Updates the localization strings */
+    updateLocalization: SetStoreFunction<LocalizationStrings>;
     /** Dismounts the component from the DOM and unloads the SDK */
     dismount: () => void;
-} & ExposedComponentApi;
+};
 
 /**
  * Singleton that represents the Capture SDK
@@ -443,6 +470,13 @@ declare type CreateCaptureUiSettings = {
     uiSettings?: UiSettings;
 };
 
+/**
+ * Creates the capture UI with an existing instance of the Capture SDK
+ * @param captureSdk
+ * @param uiSettings
+ */
+export declare function createCaptureUiWithInstance(captureSdk: CaptureSdk, uiSettings?: UiSettings): CaptureComponent;
+
 /**
  * Creates a new `DirectApi` instance.
  * @param settings - The settings for the `DirectApi` instance.
@@ -453,7 +487,7 @@ export declare function createDirectApi(settings: DirectApiSettings): Promise<Di
 declare const createEndpoint: unique symbol;
 
 /**
- * Copyright (c) 2023 Microblink Ltd. All rights reserved.
+ * Copyright (c) 2024 Microblink Ltd. All rights reserved.
  *
  * ANY UNAUTHORIZED USE OR SALE, DUPLICATION, OR DISTRIBUTION
  * OF THIS PROGRAM OR ANY OF ITS PARTS, IN SOURCE OR BINARY FORMS,
@@ -463,43 +497,43 @@ declare const createEndpoint: unique symbol;
  * REVERSE ENGINEER, DECOMPILE, OR DISASSEMBLE IT.
  */
 declare const _default: {
-    scan_the_front_side: string;
-    flip_document: string;
-    scan_the_back_side: string;
-    scanning_wrong_side: string;
-    move_closer: string;
-    move_farther: string;
-    camera_angle_too_steep: string;
-    document_too_close_to_edge: string;
-    rotate_phone_animation: string;
-    rotate_phone: string;
-    lightning_too_bright: string;
-    lightning_too_dark: string;
-    blur_detected: string;
-    glare_detected: string;
-    occluded: string;
-    need_help_tooltip: string;
-    onboarding_field_visible_title: string;
-    onboarding_field_visible_details: string;
-    tutorial_fields_visible_title: string;
-    tutorial_fields_visible_start: string;
-    tutorial_fields_visible_details: string;
-    tutorial_harsh_light_title: string;
-    tutorial_harsh_light_details: string;
-    tutorial_keep_still_title: string;
-    tutorial_keep_still_details: string;
-    camera_unavailable: string;
-    camera_permission_error: string;
-    settings: string;
-    camera_media_capture_error: string;
-    camera_unable_to_resume_session: string;
-    camera_query_in_progress: string;
-    done: string;
-    cancel: string;
-    back: string;
-    next: string;
-    ok: string;
-    dismiss: string;
+    readonly scan_the_front_side: "Scan the front side of the document";
+    readonly flip_document: "Flip the document";
+    readonly scan_the_back_side: "Scan the back side of the document";
+    readonly scanning_wrong_side: "Scanning wrong side";
+    readonly move_closer: "Move closer";
+    readonly move_farther: "Move farther";
+    readonly camera_angle_too_steep: "Keep document parallel to phone";
+    readonly document_too_close_to_edge: "Move farther";
+    readonly rotate_phone_animation: "Rotate card or turn phone to landscape";
+    readonly rotate_phone: "Rotate phone or card";
+    readonly lightning_too_bright: "Move to spot with less lighting";
+    readonly lightning_too_dark: "Move to brighter spot";
+    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 need_help_tooltip: "Need help?";
+    readonly onboarding_field_visible_title: "Keep all the details visible";
+    readonly onboarding_field_visible_details: "Make sure you keep the document well lit. All document fields should be visible on the camera screen.";
+    readonly tutorial_fields_visible_title: "Keep all the fields visible";
+    readonly tutorial_fields_visible_start: "Start scanning";
+    readonly tutorial_fields_visible_details: "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 tutorial_harsh_light_title: "Watch out for harsh light";
+    readonly tutorial_harsh_light_details: "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 tutorial_keep_still_title: "Keep still while scanning";
+    readonly tutorial_keep_still_details: "Try to keep the phone and document still while scanning. Moving either can blur the image and make data on the document unreadable.";
+    readonly camera_unavailable: "Camera Unavailable";
+    readonly camera_permission_error: "App doesn't have permission to use the camera, please change privacy settings";
+    readonly settings: "Settings";
+    readonly camera_media_capture_error: "Unable to capture media";
+    readonly camera_unable_to_resume_session: "Unable to resume";
+    readonly camera_query_in_progress: "Selecting best camera, please wait";
+    readonly done: "Done";
+    readonly cancel: "Cancel";
+    readonly back: "Back";
+    readonly next: "Next";
+    readonly ok: "OK";
+    readonly dismiss: "Dismiss";
 };
 
 /**
@@ -625,7 +659,7 @@ export declare type DocumentOcclusionStatus = "not-available" | "occluded" | "no
 export declare type DocumentSideAnalysisStatus = "not-available" | "side-already-captured" | "side-not-captured";
 
 /**
- * Copyright (c) 2023 Microblink Ltd. All rights reserved.
+ * Copyright (c) 2024 Microblink Ltd. All rights reserved.
  *
  * ANY UNAUTHORIZED USE OR SALE, DUPLICATION, OR DISTRIBUTION
  * OF THIS PROGRAM OR ANY OF ITS PARTS, IN SOURCE OR BINARY FORMS,
@@ -649,14 +683,6 @@ declare abstract class EmbindObject {
     delete(): Promise<void>;
 }
 
-export declare type ExposedComponentApi = {
-    /** Can return undefined if called after the SDK has been
-     * destroyed
-     */
-    captureSdk: CaptureSdk | undefined;
-    updateLocalization: SetStoreFunction<LocalizationStrings>;
-};
-
 declare class FeedbackParser {
     private timeWindow;
     private decayRate;
@@ -695,7 +721,7 @@ export declare type FrameAnalysisError = {
 export declare type FrameAnalysisErrorType = "analyzer-settings-unsuitable-error" | "unknown-error";
 
 /**
- * Copyright (c) 2023 Microblink Ltd. All rights reserved.
+ * Copyright (c) 2024 Microblink Ltd. All rights reserved.
  *
  * ANY UNAUTHORIZED USE OR SALE, DUPLICATION, OR DISTRIBUTION
  * OF THIS PROGRAM OR ANY OF ITS PARTS, IN SOURCE OR BINARY FORMS,
@@ -729,7 +755,7 @@ export declare type FrameAnalysisStatus = {
 export declare const getBase64StringFromDataURL: (dataURL: string) => string;
 
 /**
- * Copyright (c) 2023 Microblink Ltd. All rights reserved.
+ * Copyright (c) 2024 Microblink Ltd. All rights reserved.
  *
  * ANY UNAUTHORIZED USE OR SALE, DUPLICATION, OR DISTRIBUTION
  * OF THIS PROGRAM OR ANY OF ITS PARTS, IN SOURCE OR BINARY FORMS,
@@ -747,7 +773,7 @@ export declare enum LicenseTokenState {
 }
 
 /**
- * Copyright (c) 2023 Microblink Ltd. All rights reserved.
+ * Copyright (c) 2024 Microblink Ltd. All rights reserved.
  *
  * ANY UNAUTHORIZED USE OR SALE, DUPLICATION, OR DISTRIBUTION
  * OF THIS PROGRAM OR ANY OF ITS PARTS, IN SOURCE OR BINARY FORMS,
@@ -758,8 +784,10 @@ export declare enum LicenseTokenState {
  */
 export declare type LicenseUnlockResult = Readonly<{
     isTrial: boolean;
+    hasPing: boolean;
     licenseId: string;
     licensee: string;
+    applicationIds: Array<string>;
     packageName: string;
     sdkName: string;
     sdkVersion: string;
@@ -796,7 +824,11 @@ declare type Local<T> = Omit<LocalObject<T>, keyof ProxyMethods> & (T extends (.
     }): MaybePromise<Local<Unpromisify<TInstance>>>;
 } : unknown);
 
-declare type LocalizationStrings = typeof _default;
+declare type LocaleRecord = typeof _default;
+
+declare type LocalizationStrings = {
+    [K in keyof LocaleRecord]: LocaleRecord[K] | (string & {});
+};
 
 /**
  * Takes the type of an object as a remote thread would see it through a proxy (e.g. when passed in as a function
@@ -1033,6 +1065,8 @@ declare interface StoreApi<T> {
     destroy: () => void;
 }
 
+export declare type StrictnessLevel = "disabled" | "strict" | "normal" | "relaxed";
+
 /**
  * Branded type for type safety. Requires casting where required.
  */
@@ -1058,7 +1092,15 @@ declare type UiSettings = {
     /**
      * User provided localization keys
      */
-    localization?: Partial<Record<keyof LocalizationStrings, string>>;
+    localization?: Partial<LocalizationStrings>;
+    /**
+     * If `true`, the SDK will be destroyed when the component is dismounted.
+     * This is useful if you want to re-initialize the SDK on the same page.
+     *
+     * Defaults to `true` when using `createCaptureUi` and `false` when using
+     * `createCaptureUiWithInstance`.
+     */
+    destroyInstanceOnDismount?: boolean;
 };
 
 export declare type UiState = Readonly<{