@capturebridge/sdk 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -5,11 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.0] - 2024-10-18
+
+### Added
+
+- When running in a web browser, the value for `BASE_URL` will first be checked
+  in a `capturebridge:url` meta tag, followed by `window.CAPTURE_BRIDGE_URL`, 
+  and finally `window.location.origin`. When running the SDK in Node.js a 
+  `CAPTURE_BRIDGE_URL` environment variable will be checked.
+- Added the `Verifone.cancel()` method to gracefully cancel long-running
+operations such as the `Verifone.displayObjects()` and
+`Verifone.readMagstripe()` requests.
+- Added the `Verifone.reset()` method to reset a device's state.
+- Several Verifone SDK examples now contain a "Cancel Request" button.
+- Added a Reset demo to the Verifone SDK examples allowing the SDK to reset the
+device state, forms processor app, and reboot the device.
+- Added a Live ICAO demo containing face detection auto capture to the ICAO
+examples.
+
+### Changed
+
+- `Verifone.displayObjects()` and `Verifone.readMagstripe()` now accept an
+additional `requestOpt` argument containing an optional
+[AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) and
+`readyTimeout` parameter. `Verifone.cancel()` should be typically be used
+instead of the `AbortSignal` as it will block until the device is freed and
+available for another request.
+
 ## [0.16.0] - 2024-10-03
 
 ### Changed
 
-- `Plugin.shutdown` now accepts a `timeout` argument.
+- `Plugin.shutdown()` now accepts a `timeout` argument.
 
 ### Removed
 
@@ -20,7 +47,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add `Plugin.hasMethod()` method for checking if a plugin has a specific RPC
-  method.
+method.
 - Add suppport for transcoding captured images to gif.
 
 ## [0.14.0] - 2024-09-17

package/Common.js

@@ -5,13 +5,63 @@
  */
 export const DEFAULT_URL = 'https://local.capturebridge.net:9001'
 
+function CaptureBridgeSetDefaultURL () {
+  // Prefer <meta name="capturebridge:url" content="proto://fqdn" /> if set
+  if (typeof document === 'object') {
+    const url = document.querySelector('meta[name="capturebridge:url"]')
+    if (url && url.content) {
+      return url.content
+    }
+  }
+
+  // Prefer CAPTURE_BRIDGE_URL if set on the global window object (Browser)
+  if (typeof window === 'object' && window?.CAPTURE_BRIDGE_URL) {
+    return window.CAPTURE_BRIDGE_URL
+  }
+
+  // Prefer CAPTURE_BRIDGE_URL if set on in the environment (Node.js)
+  if (typeof process === 'object' && process?.env?.CAPTURE_BRIDGE_URL) {
+    return process?.env?.CAPTURE_BRIDGE_URL
+  }
+
+  // Failing an explicit CAPTURE_BRIDGE_URL, use the URL in which the SDK
+  // is being served from (Browser)
+  if (typeof window === 'object' && window?.location?.origin) {
+    return window.location.origin
+  }
+
+  // If all else fails, use the default vanity URL
+  return DEFAULT_URL
+}
+
 /**
- * @summary Base URL for API requests.
+ * @summary Base URL for all HTTP API requests.
+ *
+ * Due to the various environments in which the SDK can be loaded and the
+ * different ways that a Capture Bridge instance may be configured. The
+ * `BASE_URL` variable used for all default HTTP API request can be set in
+ * several ways:
+ *
+ * When running the SDK within a web browser the following locations are
+ * checked, in order:
+ * 1. A {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta|meta} tag containing a url: `<meta name="capturebridge:url" content="proto://fqdn:port" />`
+ * 2. In the global {@link https://developer.mozilla.org/en-US/docs/Web/API/Window|Window} object: `window.CAPTURE_BRIDGE_URL`
+ * 3. In the {@link https://developer.mozilla.org/en-US/docs/Web/API/Location/origin|origin} in which the SDK is running: `window.location.origin`
+ * 4. The `DEFAULT_URL` constant from `Common.js`
+ *
+ * When running the SDK within Node.js the following locations are
+ * checked, in order:
+ * 1. In a `CAPTURE_BRIDGE_URL` {@link https://nodejs.org/api/process.html#processenv|environment variable}
+ * 2. The `DEFAULT_URL` constant from `Common.js`
+ *
+ * **Note** that each constructor also accepts a `baseUrl` parameter that will override
+ * any value for `BASE_URL` previously set.
+ *
  * @constant
  * @type {string}
  * @default {@link https://local.capturebridge.net:9001}
  */
-export const BASE_URL = window?.location?.origin ?? DEFAULT_URL
+export const BASE_URL = CaptureBridgeSetDefaultURL()
 
 /**
  * Common {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch}

package/Device.js

@@ -359,10 +359,16 @@ class Device {
    * @param {Object} [sceneOpt.backlight] If `true`, the backlight will be
    * enabled before adding the Objects.
    *
+   * @param {AbortSignal} [signal] - An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal|AbortSignal}
+   * obtained from an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortController|AbortController}
+   * allowing the request to be aborted. If the request is aborted or the HTTP
+   * connection is closed for any reason before a user has interacted with the
+   * display, the device state will be reset and the screen will be cleared.
+   *
    * @async
    * @method
    */
-  async displayObjects (objects, sceneOpt = {}) {
+  async displayObjects (objects, sceneOpt = {}, signal) {
     this.can('draw')
     const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/display`
 
@@ -386,6 +392,10 @@ class Device {
       body: JSON.stringify(sceneOpt)
     }
 
+    if (signal instanceof AbortSignal) {
+      options.signal = signal
+    }
+
     const response = await fetch(url, options)
     await checkResponse(response)
     return await response.json()
@@ -408,6 +418,77 @@ class Device {
     const response = await fetch(url)
     return await response.json()
   }
+
+  /**
+   * Cancel a pending device operation
+   *
+   * @description Will attempt to cancel any active long-running operation
+   *
+   * @param {Number?} [timeout] If provided, will attempt to
+   * wait at least this long (in seconds) for the operation to be cancelled
+   * before returning a response. By default this endpoint will request a
+   * cancellation and return immediately, however if you'd like to block, waiting
+   * for the device to be ready before attempting another operation you may supply
+   * this timeout.
+   *
+   * @async
+   * @method
+   * @returns {object} Cancellation status
+   * @example
+   * const {status} = await device.cancel()
+   */
+  async cancel (timeout) {
+    this.can('cancel')
+    let url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/cancel`
+    if (typeof timeout === 'number') {
+      this.can('ready')
+      url += `?timeout=${timeout}`
+    }
+    const options = {
+      method: 'POST',
+      mode: 'cors',
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }
+    const response = await fetch(url, options)
+    await checkResponse(response)
+    return await response.json()
+  }
+
+  /**
+   * Restart a device or reset its state.
+   *
+   * @description Used to restart a device or reset its state
+   *
+   * @param {Number?} [depth=0] Some devices have several abstractions layers
+   * that can be reset separately. For example, the entire device might be
+   * rebooted or an outstanding operation could be cancelled.
+   *
+   * @async
+   * @method
+   * @returns {object} Reset status
+   * @example
+   * const {status} = await device.reset()
+   */
+  async reset (depth = 0) {
+    this.can('reset')
+    let url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/reset`
+    if (typeof depth === 'number') {
+      this.can('reset')
+      url += `?depth=${depth}`
+    }
+    const options = {
+      method: 'POST',
+      mode: 'cors',
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    }
+    const response = await fetch(url, options)
+    await checkResponse(response)
+    return await response.json()
+  }
 }
 
 export default Device

package/Verifone.js

@@ -126,6 +126,7 @@ export class Verifone extends SignatureTablet {
   /**
    * Not currently supported for this plugin.
    * @throws Not implemented error
+   * @see {@link Verifone#cancel}
    * @example
    * // Not currently supported for this plugin
    * @override
@@ -134,6 +135,58 @@ export class Verifone extends SignatureTablet {
     throw new Error('stopFeed() is not implemented for the Verifone Plugin')
   }
 
+  /**
+   * Cancel a pending device operation
+   *
+   * @description Will attempt to cancel any active long-running operation
+   *
+   * @param {Number?} [timeout] If provided, will attempt to
+   * wait at least this long (in seconds) for the operation to be cancelled
+   * before returning a response. By default this endpoint will request a
+   * cancellation and return immediately, however if you'd like to block, waiting
+   * for the device to be ready before attempting another operation you may supply
+   * this timeout.
+   *
+   * @param {string|object} [deviceOpt] - Cancel the operation for either a
+   * specific Device ID or a Device Object. The default is the first available
+   * device.
+   *
+   * @async
+   * @method
+   * @returns {object} Cancellation status
+   * @example
+   * const {status} = await device.cancel()
+   */
+  async cancel (timeout = null, deviceOpt) {
+    const device = await this.setupDevice(deviceOpt)
+    return device.cancel(timeout)
+  }
+
+  /**
+   * Restart the device or reset state.
+   *
+   * @description Reset the Verifone's internal state, reboot the device, or
+   * Forms Processor application.
+   *
+   * @param {Number?} [depth=3] 0 = Reboot the device, 1 = Restart Forms
+   * Processor, 2 = Reset device state, 3 = Reset device state and drain serial
+   * port.
+   *
+   * @param {string|object} [deviceOpt] - Display the objects on either a
+   * specific Device ID or a Device Object. The default is the first available
+   * device.
+   *
+   * @async
+   * @method
+   * @returns {object} Reset status
+   * @example
+   * const {status} = await device.reset()
+   */
+  async reset (depth = 3, deviceOpt) {
+    const device = await this.setupDevice(deviceOpt)
+    return device.reset(depth)
+  }
+
   /**
    * Render an array of form controls.
    *
@@ -150,6 +203,22 @@ export class Verifone extends SignatureTablet {
    * specific Device ID or a Device Object. The default is the first available
    * device.
    *
+   * @param {object} [requestOpt] - Additional options for the request
+   *
+   * @param {AbortSignal} [requestOpt.signal=null] - An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal|AbortSignal}
+   * obtained from an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortController|AbortController}
+   * allowing the request to be aborted. If the request is aborted or the HTTP
+   * connection is closed for any reason before a user has interacted with the
+   * display, the device state will be reset and the screen will be cleared.
+   * The {@link Verifone#cancel} method is the preferred method for cancelling
+   * a displayObjects request and should usually be used instead of an AbortSignal.
+   *
+   * @param {Number?} [requestOpt.readyTimeout=10] Attempt to wait at least this
+   * long (in seconds) for the device to be ready before sending the
+   * displayObjects request. This reduces the chance that the request will fail
+   * due to the serial port being locked after a previously cancelled or aborted
+   * request.
+   *
    * @async
    * @method
    * @returns {string?} ID of the clicked object if any
@@ -161,9 +230,18 @@ export class Verifone extends SignatureTablet {
    *
    * console.log(result)
    */
-  async displayObjects (objects, formOpt = {}, deviceOpt) {
+  async displayObjects (objects, formOpt = {}, deviceOpt, requestOpt = {}) {
     const device = await this.setupDevice(deviceOpt)
-    return device.displayObjects(objects, formOpt)
+    const defaultRequestOpt = { signal: null, readyTimeout: 10 }
+    const mergedOpts = Object.assign({}, defaultRequestOpt, requestOpt)
+
+    if (typeof mergedOpts.readyTimeout === 'number') {
+      // Abort any active in-flight requests and wait at most readyTimeout
+      // seconds for the device to be ready
+      await this.cancel(mergedOpts.readyTimeout)
+    }
+
+    return device.displayObjects(objects, formOpt, mergedOpts.signal)
   }
 
   /**
@@ -173,7 +251,7 @@ export class Verifone extends SignatureTablet {
    * object with addtional configuration details.
    * @param {ControlProperty[]} [controlProps] - Array of {@link ControlProperty}
    * objects.
-   * @param {string|object} [deviceOpt] - Clear the display of a either a
+   * @param {string|object} [deviceOpt] - Display the objects on either a
    * specific Device ID or a Device Object. The default is the first available
    * device.
    *
@@ -217,10 +295,26 @@ export class Verifone extends SignatureTablet {
    * @param {string|object} [deviceOpt] - Read magstrip using a specific Device
    * ID or a Device Object. The default is the first available device.
    *
+   * @param {object} [requestOpt] - Additional options for the request
+   *
+   * @param {AbortSignal} [requestOpt.signal=null] - An {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal|AbortSignal}
+   * obtained from an {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortController|AbortController}
+   * allowing the request to be aborted. If the request is aborted or the HTTP
+   * connection is closed for any reason before a user has interacted with the
+   * display, the device state will be reset and the screen will be cleared.
+   * The {@link Verifone#cancel} method is the preferred method for cancelling
+   * a readMagstripe request and should usually be used instead of an AbortSignal.
+   *
+   * @param {Number?} [requestOpt.readyTimeout=10] Attempt to wait at least this
+   * long (in seconds) for the device to be ready before sending the
+   * readMagstripe request. This reduces the chance that the request will fail
+   * due to the serial port being locked after a previously cancelled or aborted
+   * request.
    */
-  async readMagstripe (readOpts = { timeout: 30 }, deviceOpt) {
+  async readMagstripe (readOpts = { timeout: 30 }, deviceOpt, requestOpt = {}) {
     const device = await this.setupDevice(deviceOpt)
-    device.can('read_magstripe')
+    const defaultRequestOpt = { signal: null, readyTimeout: 10 }
+    const mergedOpts = Object.assign({}, defaultRequestOpt, requestOpt)
 
     const options = {
       method: 'GET',
@@ -229,6 +323,19 @@ export class Verifone extends SignatureTablet {
         'Content-Type': 'application/json'
       }
     }
+
+    device.can('read_magstripe')
+
+    if (typeof mergedOpts.readyTimeout === 'number') {
+      // Abort any active in-flight requests and wait at most readyTimeout
+      // seconds for the device to be ready
+      await this.cancel(mergedOpts.readyTimeout)
+    }
+
+    if (requestOpt.signal instanceof AbortSignal) {
+      options.signal = requestOpt.signal
+    }
+
     const url = `${this.baseUrl}/plugin/${this.id}/device/${device.id}/magstripe?timeout=${readOpts.timeout}`
     const response = await fetch(url, options)
     await checkResponse(response)

package/VerifoneControls.js

@@ -1,10 +1,15 @@
 /**
-* @module SignatureTabletWidgets
+* @module VerifoneControls
 */
 
 import { blobToBase64 } from './Common.js'
 import { DisplayWidget } from './SignatureTabletWidgets.js'
 
+/**
+ * AccessKey
+ * @classdesc Special keys which can be mapped to a button
+ * @see {@link Verifone}
+ */
 export class AccessKey {
   static STAR = 'Š'
   static HASH = '‹'
@@ -17,7 +22,7 @@ export class AccessKey {
  * Button
  * @classdesc A button for displaying clickable text on a tablet
  * @extends DisplayWidget
- * @see {@link SignatureTablet}
+ * @see {@link Verifone}
  */
 export class Button extends DisplayWidget {
   id
@@ -82,7 +87,7 @@ export class Button extends DisplayWidget {
  * Text
  * @classdesc Text to be displayed on a tablet
  * @extends DisplayWidget
- * @see {@link SignatureTablet}
+ * @see {@link Verifone}
  */
 export class Text extends DisplayWidget {
   id
@@ -145,7 +150,7 @@ export class Text extends DisplayWidget {
  * Image
  * @classdesc Image to be displayed on a tablet
  * @extends DisplayWidget
- * @see {@link SignatureTablet}
+ * @see {@link Verifone}
  */
 export class Image extends DisplayWidget {
   id
@@ -219,7 +224,7 @@ export class Image extends DisplayWidget {
  * SignatureBox
  * @classdesc Bounding box to capture a signature
  * @extends DisplayWidget
- * @see {@link SignatureTablet}
+ * @see {@link Verifone}
  */
 export class SignatureBox extends DisplayWidget {
   id
@@ -265,7 +270,7 @@ export class SignatureBox extends DisplayWidget {
  * Rect
  * @classdesc A rectangle
  * @extends DisplayWidget
- * @see {@link SignatureTablet}
+ * @see {@link Verifone}
  */
 export class Rect extends DisplayWidget {
   id
@@ -318,7 +323,7 @@ export class Rect extends DisplayWidget {
  * CheckBox
  * @classdesc A check box object
  * @extends DisplayWidget
- * @see {@link SignatureTablet}
+ * @see {@link Verifone}
  */
 export class CheckBox extends DisplayWidget {
   id
@@ -363,7 +368,7 @@ export class CheckBox extends DisplayWidget {
  * RadioButton
  * @classdesc A radio button object
  * @extends DisplayWidget
- * @see {@link SignatureTablet}
+ * @see {@link Verifone}
  */
 export class RadioButton extends DisplayWidget {
   id
@@ -415,7 +420,7 @@ export class RadioButton extends DisplayWidget {
  * TextInput
  * @classdesc A text input object
  * @extends DisplayWidget
- * @see {@link SignatureTablet}
+ * @see {@link Verifone}
  */
 export class TextInput extends DisplayWidget {
   id

package/Version.js

@@ -4,5 +4,5 @@
  * @constant
  * @type {string}
  */
-const VERSION = '0.17.1'
+const VERSION = '0.18.0'
 export default VERSION

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capturebridge/sdk",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Capture Bridge JavaScript SDK for web applications",
   "type": "module",
   "types": "types.d.ts",