@microblink/camera-manager 7.2.1 → 7.2.2

package/types/core/utils.d.ts

@@ -1,7 +1,25 @@
 /**
  * Copyright (c) 2025 Microblink Ltd. All rights reserved.
  */
+/**
+ * Gets the average of an array of numbers.
+ *
+ * @param arr - The array of numbers to get the average of.
+ * @returns The average of the array.
+ */
 export declare function getAverage(arr: number[]): number;
+/**
+ * Converts an unknown value to an error.
+ *
+ * @param thrown - The value to convert to an error.
+ * @returns The error.
+ */
 export declare const asError: (thrown: unknown) => Error;
+/**
+ * Gets the key with the highest value in a map.
+ *
+ * @param map - The map to get the key with the highest value from.
+ * @returns The key with the highest value.
+ */
 export declare function getKeyWithHighestValue(map: Map<string, number>): null;
 //# sourceMappingURL=utils.d.ts.map

package/types/core/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAEvC;AAED,eAAO,MAAM,OAAO,GAAI,QAAQ,OAAO,KAAG,KASzC,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAY9D"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAEvC;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,QAAQ,OAAO,KAAG,KASzC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAY9D"}

package/types/index.d.ts

@@ -1,6 +1,12 @@
 /**
  * Copyright (c) 2025 Microblink Ltd. All rights reserved.
  */
+/**
+ * @packageDocumentation
+ * Camera management utilities for web applications - provides camera access, selection, and video stream handling.
+ * This package includes both core camera management functionality and UI components for camera selection
+ * and feedback, with support for multiple camera devices and orientations.
+ */
 import "rvfc-polyfill";
 export * from "./core/cameraManagerStore";
 export * from "./core/Camera";
@@ -11,6 +17,9 @@ export { cameraUiRefStore } from "./ui/zustandRefStore";
 export type { CameraUiRefs } from "./ui/zustandRefStore";
 export type { CameraUiLocalizationStrings, CameraUiLocaleRecord, } from "./ui/LocalizationContext";
 declare const testSymbol: unique symbol;
+/**
+ * The global interface.
+ */
 declare global {
     var __CAMERA_MANAGER__: typeof testSymbol;
 }

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,eAAe,CAAC;AAEvB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EACV,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAGlC,QAAA,MAAM,UAAU,eAAW,CAAC;AAE5B,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,kBAAkB,EAAE,OAAO,UAAU,CAAC;CAC3C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AAEH,OAAO,eAAe,CAAC;AAEvB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EACV,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAGlC,QAAA,MAAM,UAAU,eAAW,CAAC;AAE5B;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,kBAAkB,EAAE,OAAO,UAAU,CAAC;CAC3C"}

package/types/index.rollup.d.ts

@@ -5,9 +5,14 @@ import { StoreApi } from 'zustand/vanilla';
 
 /**
  * Represents a camera device and its active stream.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getCapabilities for more details.
  */
 export declare class Camera {
     #private;
+    /**
+     * The device info.
+     */
     deviceInfo: InputDeviceInfo;
     /**
      * Stream capabilities as reported by the stream.
@@ -31,78 +36,162 @@ export declare class Camera {
     original: this;
     notify: (reason?: unknown) => void;
     notifyStateChange?: (camera: Camera, reason?: unknown) => void;
+    /**
+     * Creates a new Camera instance.
+     *
+     * @param deviceInfo - The device info.
+     */
     constructor(deviceInfo: InputDeviceInfo);
+    /**
+     * Starts a stream with the specified resolution.
+     *
+     * @param resolution - The resolution to start the stream with.
+     * @returns The stream.
+     */
     startStream(resolution: VideoResolutionName): Promise<MediaStream>;
     /**
      * Acquires a camera stream with the specified resolution.
      * If acquisition fails, it tries a lower resolution as fallback.
+     *
+     * @param resolution - The resolution to acquire the stream with.
+     * @returns The stream.
      */
     private acquireStreamWithFallback;
     /**
      * Populates the camera instance with capabilities from the stream.
+     *
+     * @param stream - The stream to populate the capabilities from.
      */
     private populateCapabilities;
+    /**
+     * Toggles the torch on the camera.
+     *
+     * @returns The torch status.
+     */
     toggleTorch(): Promise<boolean>;
+    /**
+     * Stops the stream on the camera.
+     */
     stopStream(): void;
+    /**
+     * Gets the video track on the camera.
+     *
+     * @returns The video track.
+     */
     getVideoTrack(): MediaStreamTrack | undefined;
 }
 
+/**
+ * A camera error.
+ */
 declare class CameraError extends Error {
     code: CameraErrorCode;
+    /**
+     * Creates a new camera error.
+     *
+     * @param message - The error message.
+     * @param code - The error code.
+     * @param cause - The cause of the error.
+     */
     constructor(message: string, code: CameraErrorCode, cause?: Error);
 }
 
+/**
+ * A camera error code.
+ */
 declare type CameraErrorCode = "PERMISSION_DENIED" | (string & {});
 
+/**
+ * A camera getter.
+ *
+ * @param cameras - The cameras to get.
+ * @returns The camera.
+ */
 declare type CameraGetter = (cameras: Camera[]) => Camera | undefined;
 
+/**
+ * The CameraManager class.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/getCapabilities for more details.
+ */
 export declare class CameraManager {
     #private;
+    /**
+     * If true, the user has initiated an abort. This will prevent the
+     * CameraManager from throwing errors when the user interrupts the process.
+     */
     get userInitiatedAbort(): boolean;
     set userInitiatedAbort(value: boolean);
     /**
      * Sets the area of the video frame that will be extracted.
+     *
      * @param extractionArea The area of the video frame that will be extracted.
      */
     setExtractionArea(extractionArea: ExtractionArea): void;
+    /**
+     * Creates a new CameraManager instance.
+     *
+     * @param options - The options for the CameraManager.
+     * @param videoFrameProcessorOptions - The options for the VideoFrameProcessor.
+     */
     constructor(options?: Partial<CameraManagerOptions>, videoFrameProcessorOptions?: VideoFrameProcessorInitOptions);
     /**
-     * Sets the resolution of the camera stream
+     * Sets the resolution of the camera stream.
+     *
+     * @param resolution - The resolution to set.
      */
     setResolution: (resolution: VideoResolutionName) => Promise<void>;
+    /**
+     * The resolution of the camera stream.
+     */
     get resolution(): "720p" | "1080p" | "4k";
     /**
      * True if there is a video playing or capturing
-     * TODO: see if we can simplify this, by observing the video playback state
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaSession/playbackState for more details.
      */
     get isActive(): boolean;
+    /**
+     * Sets the facing filter.
+     *
+     * @param facingFilter - The facing filter.
+     */
     setFacingFilter(facingFilter: FacingMode[]): void;
     /**
      * Returns the cameras that are available to the user, filtered by the facing mode.
      * If no facing mode is set, all cameras are returned.
+     *
+     * @returns The cameras that are available to the user, filtered by the facing mode.
      */
     getCameraDevices(): Promise<Camera[]>;
     /**
      * Initializes the CameraManager with a video element.
+     *
+     * @param videoElement - The video element to initialize.
      */
     initVideoElement(videoElement: HTMLVideoElement): void;
     /**
      * Adds a callback that will be triggered on each frame when the playback state
      * is "capturing".
      *
-     * @param frameCaptureCallback
+     * @param frameCaptureCallback - The callback to add.
      * @returns a cleanup function to remove the callback
      */
     addFrameCaptureCallback(frameCaptureCallback: FrameCaptureCallback): () => boolean;
+    /**
+     * Cleans up the video element, and stops the stream.
+     */
     releaseVideoElement(): void;
     /**
      * Select a camera device from available ones.
      *
-     * TODO: might become a private method in the future as an implementation detail of `startStream`
+     * @param camera - The camera to select.
      */
     selectCamera(camera: Camera): Promise<void>;
     /**
      * Refreshes available devices on the system and updates the state.
+     *
+     * @returns resolves when the camera devices are refreshed
      */
     refreshCameraDevices(): Promise<void>;
     /**
@@ -113,15 +202,20 @@ export declare class CameraManager {
     startPlayback(): Promise<void>;
     /**
      * Starts capturing frames from the video element.
+     *
+     * @returns resolves when frame capture starts
      */
     startFrameCapture: () => Promise<void>;
     /**
      * Starts a best-effort camera stream. Will pick a camera automatically if
      * none is selected.
+     *
+     * @param params - The parameters for the camera stream.
+     * @returns resolves when the camera stream starts
      */
     startCameraStream(params?: StartCameraStreamOptions): Promise<void>;
     /**
-     * Pauses capturing frames without pausing playback.
+     * Pauses capturing frames, without stopping playback.
      */
     stopFrameCapture(): void;
     /**
@@ -134,31 +228,42 @@ export declare class CameraManager {
     pausePlayback(): void;
     /**
      * If true, the video and captured frames will be mirrored horizontally.
+     *
+     * @param mirrorX - If true, the video and captured frames will be mirrored horizontally.
      */
     setCameraMirrorX(mirrorX: boolean): void;
     /**
      * Allows the user to subscribe to state changes inside the Camera Manager.
      * Implemented using Zustand. For usage information, see
-     * {@link https://github.com/pmndrs/zustand#using-subscribe-with-selector}
+     * @see https://github.com/pmndrs/zustand#using-subscribe-with-selector for more details.
+     *
+     * @returns a cleanup function to remove the subscription
      */
     subscribe: typeof cameraManagerStore.subscribe;
     /**
      * Gets the current internal state of the CameraManager.
+     *
+     * @returns the current state of the CameraManager
      */
     getState: typeof cameraManagerStore.getState;
     /**
-     * Resets the CameraManager and stop all streams
+     * Resets the CameraManager and stops all streams.
      */
     reset(): void;
 }
 
+/**
+ * The camera manager component.
+ */
 export declare type CameraManagerComponent = {
+    /** The camera manager. */
     cameraManager: CameraManager;
     /** Updates the localization strings */
     updateLocalization: SetStoreFunction<CameraUiLocalizationStrings>;
     /** Dismounts the component from the DOM and unloads the SDK */
     dismount: () => void;
-    /** Sets a callback to be called when the component is unmounted.
+    /**
+     * Sets a callback to be called when the component is unmounted.
      * Returns a cleanup function that removes the callback when called.
      */
     addOnDismountCallback: (fn: DismountCallback) => () => void;
@@ -171,16 +276,26 @@ export declare type CameraManagerComponent = {
      */
     overlayLayerNode: HTMLDivElement;
     /**
-     * https://docs.solidjs.com/reference/reactive-utilities/get-owner
+     * The owner of the component.
+     *
+     * @see https://docs.solidjs.com/reference/reactive-utilities/get-owner
      */
     owner: Owner;
 };
 
+/**
+ * Options for the CameraManager.
+ *
+ * @param mirrorFrontCameras - If true, front-facing cameras will be mirrored horizontally when started.
+ */
 export declare type CameraManagerOptions = {
     /** If true, the camera stream will be mirrored horizontally when started. */
     mirrorFrontCameras: boolean;
 };
 
+/**
+ * The camera manager store.
+ */
 export declare type CameraManagerStore = {
     /**
      * The video element that will display the camera stream.
@@ -200,7 +315,7 @@ export declare type CameraManagerStore = {
      */
     selectedCamera?: Camera;
     /**
-     * Capturing / playing / idle
+     * Capturing / playing / idle.
      */
     playbackState: PlaybackState;
     /**
@@ -231,7 +346,7 @@ export declare type CameraManagerStore = {
  *
  * Prefer using subscriptions if you require observable state.
  *
- * {@link https://github.com/pmndrs/zustand}
+ * @see https://github.com/pmndrs/zustand for more details.
  */
 export declare const cameraManagerStore: Omit<StoreApi<CameraManagerStore>, "subscribe"> & {
     subscribe: {
@@ -243,7 +358,13 @@ export declare const cameraManagerStore: Omit<StoreApi<CameraManagerStore>, "sub
     };
 };
 
+/**
+ * The camera manager UI options.
+ */
 export declare type CameraManagerUiOptions = {
+    /**
+     * The localization strings.
+     */
     localizationStrings?: Partial<CameraUiLocalizationStrings>;
     /**
      * If set to `true`, the mirror camera button will be shown.
@@ -265,6 +386,11 @@ export declare type CameraManagerUiOptions = {
     showCloseButton?: boolean;
 };
 
+/**
+ * A camera preference.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/facingMode for facing mode details.
+ */
 export declare type CameraPreference = {
     preferredCamera: Camera | undefined;
     preferredFacing?: undefined;
@@ -279,18 +405,33 @@ export declare type CameraPreference = {
     preferredFacing?: undefined;
 };
 
+/**
+ * The camera UI locale record.
+ */
 export declare type CameraUiLocaleRecord = typeof _default;
 
+/**
+ * The camera UI localization strings.
+ */
 export declare type CameraUiLocalizationStrings = {
     [K in keyof CameraUiLocaleRecord]: CameraUiLocaleRecord[K] | (string & {});
 };
 
+/**
+ * The camera UI refs.
+ */
 export declare type CameraUiRefs = {
+    /** The feedback layer. */
     feedbackLayer: HTMLDivElement;
+    /** The overlay layer. */
     overlayLayer: HTMLDivElement;
+    /** The owner of the component. */
     owner: Owner;
 };
 
+/**
+ * The camera UI ref store.
+ */
 export declare const cameraUiRefStore: Omit<StoreApi<CameraUiRefs>, "subscribe"> & {
     subscribe: {
         (listener: (selectedState: CameraUiRefs, previousSelectedState: CameraUiRefs) => void): () => void;
@@ -308,11 +449,16 @@ export declare type CanvasRenderingMode = "2d" | "webgl2";
 
 /**
  * Creates a new Camera Manager UI component.
+ *
+ * @param cameraManager - The camera manager.
+ * @param target - The target element to mount the component to.
+ * @param options - The options for the camera manager UI.
+ * @returns The camera manager UI component.
  */
 export declare function createCameraManagerUi(cameraManager: CameraManager, target?: HTMLElement, { localizationStrings, showMirrorCameraButton, showTorchButton, showCloseButton, }?: CameraManagerUiOptions): Promise<CameraManagerComponent>;
 
 /**
- * Copyright (c) 2025 Microblink Ltd. All rights reserved.
+ * The default English localization strings.
  */
 declare const _default: {
     readonly selected_camera: "Selected camera";
@@ -329,10 +475,19 @@ declare const _default: {
     readonly camera_error_primary_btn: "Retry";
 };
 
+/**
+ * Default options for the CameraManager.
+ */
 export declare const defaultCameraManagerOptions: CameraManagerOptions;
 
+/**
+ * A dismount callback.
+ */
 export declare type DismountCallback = () => void;
 
+/**
+ * The extraction area.
+ */
 export declare type ExtractionArea = {
     x: number;
     y: number;
@@ -345,18 +500,38 @@ export declare type ExtractionArea = {
  */
 export declare type FacingMode = "front" | "back" | undefined;
 
+/**
+ * Finds the closest resolution key to the given resolution.
+ *
+ * @param videoTrackResolution - The resolution to find the closest key for.
+ * @returns The closest resolution key.
+ */
 export declare function findResolutionKey(videoTrackResolution: Resolution): VideoResolutionName;
 
+/**
+ * A callback that will be triggered on each frame when the playback state is
+ * "capturing".
+ *
+ * @param frame - The frame to capture.
+ * @returns The frame.
+ */
 export declare type FrameCaptureCallback = (frame: ImageData) => Promisable<ArrayBufferLike | void>;
 
 /**
  * Converts a view to a buffer, since both match the type signature of
  * `ArrayBufferLike`.
+ *
  * @param buffer - The buffer or view to convert
  * @returns The actual underlying buffer
  */
 export declare const getBuffer: (buffer: ArrayBufferLike) => ArrayBufferLike;
 
+/**
+ * Normalizes a resolution to the longer side.
+ *
+ * @param resolution - The resolution to normalize.
+ * @returns The normalized resolution.
+ */
 export declare function getNormalizedResolution(resolution: Resolution): Resolution;
 
 export declare type ImageSource = HTMLVideoElement | HTMLCanvasElement | ImageBitmap;
@@ -368,25 +543,57 @@ export declare type ImageSource = HTMLVideoElement | HTMLCanvasElement | ImageBi
  */
 export declare function isBufferDetached(buffer: ArrayBuffer): boolean;
 
+/**
+ * Matches the closest resolution to the given resolution.
+ *
+ * @param resolution - The resolution to match.
+ * @returns The closest resolution.
+ */
 export declare function matchClosestResolution(resolution: Resolution): VideoResolutionName;
 
+/**
+ * The default mount point ID.
+ */
 export declare const MOUNT_POINT_ID = "camera-manager-mount-point";
 
+/**
+ * The playback state of the camera manager.
+ */
 export declare type PlaybackState = "idle" | "playback" | "capturing";
 
 /**
  * Resets the store to its initial state.
+ *
  * Stops all camera streams as a side effect.
  */
 export declare const resetCameraManagerStore: () => void;
 
+/**
+ * Represents a video resolution.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/width for width details.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/height for height details.
+ */
 export declare type Resolution = {
     width: number;
     height: number;
 };
 
+/**
+ * Returns the longer side of a resolution.
+ *
+ * @param resolution - The resolution to get the longer side of.
+ * @returns The longer side of the resolution.
+ */
 export declare function returnLongerSide(resolution: Resolution): number;
 
+/**
+ * Options for starting a camera stream.
+ *
+ * @param autoplay - If true, the camera stream will be started automatically.
+ * @param preferredCamera - The camera to start the stream with.
+ * @param preferredFacing - The facing mode to start the stream with.
+ */
 export declare type StartCameraStreamOptions = {
     autoplay?: boolean;
 } & CameraPreference;
@@ -396,43 +603,70 @@ export declare type StartCameraStreamOptions = {
  */
 export declare class VideoFrameProcessor {
     #private;
+    /**
+     * Creates a new VideoFrameProcessor.
+     *
+     * @param options - The options for the VideoFrameProcessor.
+     */
     constructor(options?: VideoFrameProcessorInitOptions);
     /**
-     * Returns ownership of an ArrayBuffer to the processor for reuse
-     * This should only be called with ArrayBuffers that were originally from this processor
-     * Typically used after transferring the buffer to/from a worker
+     * Returns ownership of an ArrayBuffer to the processor for reuse.
+     *
+     * This should only be called with ArrayBuffers that were originally from this processor.
+     * Typically used after transferring the buffer to/from a worker.
+     *
+     * @param arrayBuffer - The array buffer to reattach.
      */
     reattachArrayBuffer(arrayBuffer: ArrayBufferLike): void;
     /**
-     * Used to check if the processor owns the buffer
+     * Used to check if the processor owns the buffer.
+     *
+     * @returns true if the processor owns the buffer, false otherwise.
      */
     isBufferDetached(): boolean;
     /**
-     * Extracts image data from a source element
+     * Extracts image data from a source element.
+     *
+     * @param source - The source element to extract image data from.
+     * @param area - The extraction area.
+     * @returns The image data.
      */
     getImageData(source: ImageSource, area?: ExtractionArea): ImageData;
     /**
      * Used to get the current ImageData object with the current buffer. Useful
      * when you need to get the same `ImageData` object multiple times after the
      * original `ImageData` buffer has been detached
+     *
      * @returns ImageData object with the current buffer
      */
     getCurrentImageData(): ImageData;
     /**
-     * Clean up resources
+     * Clean up resources.
      */
     dispose(): void;
 }
 
+/**
+ * Options for the VideoFrameProcessor.
+ */
 export declare type VideoFrameProcessorInitOptions = {
     canvasRenderingMode?: CanvasRenderingMode;
     fallbackWebGlTo2d?: boolean;
 };
 
+/**
+ * Represents a video resolution name.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/width for width details.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/height for height details.
+ */
 export declare type VideoResolutionName = keyof typeof videoResolutions;
 
 /**
  * Available video resolutions for the camera stream.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/width for width details.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/height for height details.
  */
 export declare const videoResolutions: {
     readonly "720p": {