@pixelverse/strichjs-sdk 1.7.1 → 1.7.3

package/dist/strich.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Fine-grained audio feedback configuration object
+ */
+export declare interface AudioFeedbackConfiguration {
+    /**
+     * Toggle audible beep upon successful scan.
+     *
+     * @remarks
+     * Uses the WebAudio API to emit a "cash register"-like beep. Beeping is done on a best-effort
+     * basis and should not be relied upon. If the browser does not support the WebAudio API,
+     * beeping will not work, and no error will be thrown.
+     *
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * Explicitly set the AudioSession type used for audible feedback.
+     *
+     * See https://github.com/w3c/audio-session/blob/main/explainer.md#api-design for a list of acceptable values.
+     *
+     * By default, the value `transient` is used if the AudioSession API is available.
+     * Setting this value to `null` will disable setting the AudioSession type.
+     */
+    audioSessionType?: string | null;
+}
+
 /**
  * BarcodeReader is the primary interface of the STRICH SDK.
  */
@@ -16,40 +42,66 @@ export declare class BarcodeReader {
      */
     onError?: (error: Error) => (void);
     /**
-     * Create a new BarcodeReader using a Configuration.
+     * Create a new BarcodeReader using a {@link Configuration} object.
+     *
+     * @remarks
+     * This will perform some basic checks, such as if the SDK was initialized, the browser supports the required APIs
+     * and the host element is visible and has a non-zero size. This will not access the camera yet, that happens
+     * in the {@link BarcodeReader#initialize} method.
      *
      * @param configuration - A configuration object.
      */
-    constructor(/* @internal */ configuration: Configuration);
+    constructor(configuration: Configuration);
     /**
      * Initialize the BarcodeReader instance.
      *
-     * @returns A promise resolving to an initialized BarcodeReader instance, or an error object.
+     * @remarks
+     * This will attempt to acquire a camera stream, so it is essential that the returned Promise is awaited, and that
+     * measures are taken so that the returned BarcodeReader instance is destroyed when it is no longer need. That
+     * will free the camera stream for subsequent use.
+     *
+     * If you are getting camera-related initialization errors, the most likely cause is that you are
+     * attempting to initialize a BarcodeReader and the camera feed has not been released yet.
+     *
+     * @returns A promise resolving to an initialized BarcodeReader instance, or an {@link SdkError} object.
      */
     initialize(): Promise<BarcodeReader>;
     /**
-     * Start scanning for barcodes.
+     * Start barcode recognition.
+     *
+     * @remarks
+     * The BarcodeReader instance must have previously been successfully initialized using the
+     * {@link BarcodeReader#initialize} method.
      */
     start(): Promise<void>;
     /**
-     * Stop the BarcodeReader instance.
+     * Stop barcode recognition.
+     *
+     * @remarks
+     * This will suspend camera frame processing/barcode recognition, but will not release the camera stream.
+     * If you no longer intend to use the BarcodeReader instance, call {@link BarcodeReader#destroy} afterward.
      *
-     * This will temporarily suspend processing of camera frames / detection of codes.
+     * If you intend to only temporarily stop recognition of barcodes and resume later, call
+     * {@link BarcodeReader#start} again.
      */
     stop(): Promise<void>;
     /**
      * Destroy this BarcodeReader instance, making it unusable.
      *
-     * This will release all associated resources, and should be called whenever an application no longer needs to
-     * scan.
+     * @remarks
+     * This will release all associated resources, including the camera stream, and should be called whenever an
+     * application no longer needs the BarcodeReader.
      *
      * @returns Promise that resolves when the BarcodeReader and its associated resources are fully destroyed.
      */
     destroy(): Promise<void>;
     /**
-     * Show/hide the BarcodeReader instance.
+     * Show or hide the BarcodeReader instance.
+     *
+     * @remarks
+     * This will not release the camera stream.
      *
-     * @param visible - True/false for visible/hidden
+     * @param visible - True to display the BarcodeReader, false to hide it
      */
     setVisible(visible: boolean): Promise<void>;
     /**
@@ -208,9 +260,14 @@ export declare interface FeedbackConfiguration {
     /**
      * Toggle audible beep upon successful scan.
      *
+     * @remarks
+     * Uses the WebAudio API to emit a "cash register"-like beep. Beeping is done on a best-effort
+     * basis and should not be relied upon. If the browser does not support the WebAudio API,
+     * beeping will not work, and no error will be thrown.
+     *
      * @defaultValue true
      */
-    audio?: boolean;
+    audio?: boolean | AudioFeedbackConfiguration;
     /**
      * Toggle vibration upon successful scan, if supported by device.
      *
@@ -560,9 +617,10 @@ export declare class PopupScanner {
     /**
      * Scan barcodes using a pre-built, modal popup interface.
      *
+     * @remarks
      * Scanning is active until one or more barcodes of the configured symbologies
-     * (see {@link PopupConfiguration#symbologies}) are detected. If a detection handler is provided
-     * (see {@link PopupConfiguration#detectionHandler}), scanning will continue until the detection
+     * (see {@link PopupConfiguration.symbologies}) are detected. If a detection handler is provided
+     * (see {@link PopupConfiguration.detectionHandler}), scanning will continue until the detection
      * handler returns a truthy value.
      *
      * @param configuration - The popup scanner configuration
@@ -672,44 +730,59 @@ export declare interface Size {
 }
 
 /**
- * Before the STRICH SDK {@link BarcodeReader} can be used, a one-time initialization of the SDK must be performed.
+ * Main entrypoint for the STRICH Barcode Scanning SDK, containing initialization and utility methods.
+ *
+ * The SDK has to be initialized with a license key using the {@link StrichSDK.initialize} method before barcodes may be scanned.
  */
 export declare class StrichSDK {
     /**
-     * Return the version of the STRICH SDK.
+     * @returns The semantic version of the SDK, as MAJOR.MINOR.PATCH
      */
     static version(): string;
     /**
-     * Return true if the SDK was successfully initialized, false otherwise.
+     * @returns True if the SDK was successfully initialized, false otherwise
      */
     static isInitialized(): boolean;
     /**
-     * One-time initialization of the SDK.
+     * One-time initialization of the SDK
+     *
+     * @remarks
+     * For online licenses, this will invoke an HTTPS call to our license service. If possible, we recommend calling
+     * this method early in the lifecycle of your scanning flow, to avoid any delay at the time a {@link BarcodeReader}
+     * instance is required.
      *
      * @param licenseKey - The license key obtained from the Customer Portal.
+     * @returns A Promise that resolves when the SDK was initialized successfully, or an {@link SdkError} instance.
      */
     static initialize(licenseKey: string): Promise<void>;
     /**
-     * Set custom ID for analytics.
+     * Set a custom ID for additional context.
      *
+     * @remarks
      * The custom ID is independent of the device ID, and can be used for custom device
      * identifiers, location identifiers or anonymous user identifiers.
+     * Unless you opt out of usage tracking (an Enterprise-only capability), the custom ID will also be
+     * available in the CSV export of your scans.
+     *
+     * The custom ID is not a per-scan identifier.
      *
      * USING THE CUSTOM ID TO TRANSMIT PERSONALLY IDENTIFYING DATA IS FORBIDDEN AND
      * CONSTITUTES A BREACH OF THE TERMS OF THE LICENSE AGREEMENT.
      *
      * @param customId - The custom ID. Use `null` to unset the custom ID.
-     * @defaultValue No custom ID is set by default
      */
     static setCustomId(customId: string | null): void;
     /**
-     * Override the language that was detected from the browser's language (navigator.language)
+     * Override the language of built-in error messages shown in the scanning UI.
+     * By default, browser's language (navigator.language) will be used.
      *
-     * @param lang - The ISO language code, e.g. 'en'
+     * @param lang - The lower-case ISO language code, e.g. 'en'
      */
     static setLanguage(lang: string): void;
     /**
      * Check if the browser has access to a camera device, which is required for scanning barcodes.
+     *
+     * @remarks
      * This can be used as a check if a BarcodeReader should be presented, or a fallback to a manual input method
      * or error page should be displayed.
      *
@@ -727,8 +800,8 @@ export declare class StrichSDK {
      * @remarks
      * The Permissions API is currently not available on Firefox: 'unknown' will be returned.
      *
-     * @returns The current state of the camera permission: 'granted' if it is granted, 'denied' if it is denied,
-     * 'prompt' if a prompt will occur, and 'unknown' if it could not be determined for any reason.
+     * @returns A Promise resolving to the current state of the camera permission: 'granted' if it is granted, 'denied'
+     * if it is denied, 'prompt' if a prompt will occur, and 'unknown' if it could not be determined for any reason.
      */
     static getCameraPermissionState(): Promise<'denied' | 'granted' | 'prompt' | 'unknown'>;
 }