@capturebridge/sdk 0.7.1 → 0.9.0

package/Device.js

@@ -1,4 +1,14 @@
-import { BASE_URL, POST, DELETE, timeout, asyncToCallback } from './Common.js'
+import {
+  BASE_URL,
+  POST,
+  DELETE,
+  DEFAULT_STREAM_OPT,
+  DEFAULT_CAPTURE_OPT,
+  checkResponse,
+  timeout,
+  asyncToCallback,
+  urlParamsToString
+} from './Common.js'
 
 /**
  * Device
@@ -33,12 +43,27 @@ class Device {
     Object.assign(this, {}, properties)
   }
 
+  /**
+   * Will throw an exception if a plugin cannot perform the provided RPC command
+   * @param {string} method - The JSON RPC method to check.
+   */
   can (method) {
     if (this.plugin.methods.indexOf(method) === -1) {
       throw new Error(`${method} not supported for this device`)
     }
   }
 
+  /**
+   * Will throw an exception if the plugin cannot performa at least one of the
+   * provided JSON RPC commandss
+   * @param {string[]} methods - The JSON RPC methods to check.
+   */
+  canDoOne (methods) {
+    if (!methods.some(m => this.plugin.methods.includes(m))) {
+      throw new Error(`Device does not support any of the methods: ${methods.join(',')}`)
+    }
+  }
+
   /**
    * Get the stream endpoint URL.
    *
@@ -50,16 +75,57 @@ class Device {
    * for any reason, the live feed will automatically be stopped.
    *
    * @method
+   * @param {StreamOptions} [streamOpt] - Additional options for streaming.
    * @returns {string} stream endpoint URL
    * @example
    * const img = document.createElement('img')
    * img.src = device.streamUrl()
    * document.body.appendChild(img)
    */
-  streamUrl () {
+  streamUrl (streamOpt = {}) {
     this.can('start_feed')
     this.can('stop_feed')
-    return `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/stream`
+    const mergedOpts = Object.assign({}, DEFAULT_STREAM_OPT, streamOpt)
+    const params = new URLSearchParams(mergedOpts).toString()
+    return `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/stream?${params}`
+  }
+
+  /**
+   * Take full capture from the specified device and return an
+   * {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL_static|ObjectURL}
+   * that can be set directly on an img tag's src attribute. Note that URLs
+   * created by this method should be
+   * {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/revokeObjectURL_static|revoked}
+   * when they are no longer needed.
+   * (Async/Await version)
+   *
+   * @method
+   * @async
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * frame.
+   * @returns {string}
+   * @example
+   * // Load the blob into FileReader and append to the document's body
+   * const blob = await device.captureAsBlob()
+   * const reader = new FileReader()
+   * reader.onload = event => {
+   *   const img = document.createElement('img')
+   *   img.src = event.target.result
+   *   document.body.appendChild(img)
+   * }
+   * reader.readAsDataURL(blob)
+   */
+  async captureAsObjectURL (captureOpt = {}) {
+    this.can('capture')
+    const captureParams = Object.assign({}, DEFAULT_CAPTURE_OPT, captureOpt)
+
+    // Method ignores kind, always returns an object URL
+    delete captureParams.kind
+
+    const params = urlParamsToString(captureParams)
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture?${params}`
+    const response = await fetch(url, POST)
+    return await response.blob()
   }
 
   /**
@@ -70,6 +136,8 @@ class Device {
    *
    * @method
    * @async
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * frame.
    * @returns {object} {@link https://developer.mozilla.org/en-US/docs/Web/API/Blob|Blob}
    * @example
    * // Load the blob into FileReader and append to the document's body
@@ -82,9 +150,15 @@ class Device {
    * }
    * reader.readAsDataURL(blob)
    */
-  async captureAsBlob () {
+  async captureAsBlob (captureOpt = {}) {
     this.can('capture')
-    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture`
+    const captureParams = Object.assign({}, DEFAULT_CAPTURE_OPT, captureOpt)
+
+    // Method ignores kind, always returns binary data (blob)
+    delete captureParams.kind
+
+    const params = urlParamsToString(captureParams)
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture?${params}`
     const response = await fetch(url, POST)
     return await response.blob()
   }
@@ -96,7 +170,9 @@ class Device {
    * (Callback version)
    *
    * @method
-   * @param {function} callback - {@link https://developer.mozilla.org/en-US/docs/Web/API/Blob|Blob}
+   * @param {function} callback
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * frame.
    * @example
    * // Load the blob into FileReader and append to the document's body
    * device.captureAsBlobHandler((error, blob) => {
@@ -109,8 +185,8 @@ class Device {
    *   reader.readAsDataURL(blob)
    * })
    */
-  captureAsBlobHandler (callback) {
-    asyncToCallback(this, this.captureAsBlob, callback)
+  captureAsBlobHandler (callback, captureOpt = {}) {
+    asyncToCallback(this, this.captureAsBlob, captureOpt, callback)
   }
 
   /**
@@ -121,6 +197,8 @@ class Device {
    *
    * @method
    * @async
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * frame.
    * @returns {string} Base64 Encoded image
    * @example
    * // Add the base64 string as a Data URL to an img tag and append to
@@ -130,10 +208,18 @@ class Device {
    * img.src = 'data:image/jpeg;base64,' + base64
    * document.body.appendChild(img)
    */
-  async captureAsBase64 () {
+  async captureAsBase64 (captureOpt = {}) {
     this.can('capture')
-    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture?base64=true`
+    const captureParams = Object.assign({}, DEFAULT_CAPTURE_OPT, captureOpt)
+
+    // Method ignores kind, always returns base64 data
+    delete captureParams.kind
+    captureParams.base64 = true
+
+    const params = urlParamsToString(captureParams)
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture?${params}`
     const response = await fetch(url, POST)
+    await checkResponse(response)
     const { image } = await response.json()
     return image
   }
@@ -144,9 +230,11 @@ class Device {
    * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URL}
    *  (Callback version)
    * @method
-   * @param {function} callback - Base64 Encoded image
+   * @param {function} callback
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * frame.
    */
-  captureAsBase64Handler (callback) {
+  captureAsBase64Handler (callback, captureOpt = {}) {
     asyncToCallback(this, this.captureAsBase64, callback)
   }
 
@@ -171,6 +259,8 @@ class Device {
    *
    * @async
    * @param {number} [millis] - Milliseconds to wait if feed is not ready
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * frame.
    * @returns {string} Base64 Encoded image
    * @example
    * // Add the base64 string as a Data URL to an img tag and append to
@@ -180,14 +270,21 @@ class Device {
    * img.src = 'data:image/jpeg;base64,' + base64
    * document.body.appendChild(img)
    */
-  async frameAsBase64 (millis = 1000) {
+  async frameAsBase64 (captureOpt = {}, millis = 500) {
     this.can('start_feed')
-    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/livefeed?base64=true`
+    const captureParams = Object.assign({}, DEFAULT_CAPTURE_OPT, captureOpt)
+
+    // Method ignores kind, always returns base64 data
+    delete captureParams.kind
+    captureParams.base64 = true
+
+    const params = urlParamsToString(captureParams)
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/livefeed?${params}`
     const response = await fetch(url)
     const result = await response.json()
     if (result.error && (result.code === 425 || result.code === 400)) {
       await timeout(millis)
-      return await this.frameAsBase64(millis)
+      return await this.frameAsBase64(captureOpt, millis)
     } else {
       return result.image
     }
@@ -212,7 +309,9 @@ class Device {
    * @see {@link streamUrl}
    * @see {@link setStopFeed}
    *
-   * @param {function} callback - Base64 Encoded image
+   * @param {function} callback
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * frame.
    * @param {number} [millis] - Milliseconds to wait if feed is not ready
    * @example
    * // Add the base64 string as a Data URL to an img tag and append to
@@ -223,8 +322,8 @@ class Device {
    *   document.body.appendChild(img)
    * })
    */
-  frameAsBase64Handler (callback, millis = 1000) {
-    asyncToCallback(this, this.frameAsBase64, callback, millis)
+  frameAsBase64Handler (callback, captureOpt = {}, millis = 500) {
+    asyncToCallback(this, this.frameAsBase64, callback, captureOpt, millis)
   }
 
   /**
@@ -247,6 +346,8 @@ class Device {
    * @see {@link stopFeed}
    *
    * @async
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * frame.
    * @param {number} [millis] - Milliseconds to wait if feed is not ready
    * @returns {object} {@link https://developer.mozilla.org/en-US/docs/Web/API/Blob|Blob}
    * @example
@@ -260,10 +361,16 @@ class Device {
    * }
    * reader.readAsDataURL(blob)
    */
-  async frameAsBlob (millis = 1000) {
+  async frameAsBlob (captureOpt = {}, millis = 500) {
     this.can('start_feed')
-    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/livefeed`
-    const result = await this.frameAsBase64(millis)
+    const captureParams = Object.assign({}, DEFAULT_CAPTURE_OPT, captureOpt)
+
+    // Method ignores kind, always returns binary data (blob)
+    delete captureParams.kind
+
+    const params = urlParamsToString(captureParams)
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/livefeed?${params}`
+    const result = await this.frameAsBase64(captureOpt, millis)
     if (typeof result === 'string') {
       timeout(millis)
       const response = await fetch(url)
@@ -291,8 +398,13 @@ class Device {
    * @see {@link streamUrl}
    * @see {@link setStopFeed}
    *
-   * @param {function} callback -{@link https://developer.mozilla.org/en-US/docs/Web/API/Blob|Blob}
+   * @param {function} callback
+   *
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * frame.
+   *
    * @param {number} [millis] - Milliseconds to wait if feed is not ready
+   *
    * @example
    * // Load the blob into FileReader and append to the document's body
    * device.frameAsBlobHandler((error, blob) => {
@@ -305,8 +417,8 @@ class Device {
    *   reader.readAsDataURL(blob)
    * })
    */
-  frameAsBlobHandler (callback, millis = 1000) {
-    asyncToCallback(this, this.frameAsBlob, callback, millis)
+  frameAsBlobHandler (callback, captureOpt = {}, millis = 500) {
+    asyncToCallback(this, this.frameAsBlob, callback, captureOpt, millis)
   }
 
   /**
@@ -363,7 +475,7 @@ class Device {
    * console.log(await await device.clear())
    */
   async clear (backlight) {
-    this.can('draw')
+    this.canDoOne(['draw', 'clear'])
     let url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/display`
     if (typeof backlight === 'boolean') {
       url += `?backlight=${backlight}`
@@ -446,6 +558,38 @@ class Device {
   async displayObjectsHandler (objects, clear = true, callback) {
     asyncToCallback(this, this.displayObjects, callback, objects, clear)
   }
+
+  /**
+   * Get detailed information about a device
+   *
+   * @description Returns detailed information about a device.
+   *
+   * @async
+   * @method
+   * @returns {object} Device info
+   * @example
+   * const info = await device.info()
+   */
+  async info () {
+    this.can('device_info')
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/info`
+    const response = await fetch(url)
+    return await response.json()
+  }
+
+  /**
+   * Get detailed information about a device
+   *
+   * @description Returns detailed information about a device.
+   *
+   * @method
+   * @returns {object} Device info
+   * @example
+   * const info = await device.info()
+   */
+  async infoHandler (callback) {
+    asyncToCallback(this, this.info, callback)
+  }
 }
 
 export default Device

package/ICAO.js

@@ -4,7 +4,7 @@ import { BASE_URL } from './Common.js'
 /**
  * ICAO
  * @classdesc Class for invoking ICAO checks on an image
- *
+ * @extends Plugin
  * @see {@link CanonScanner}
  */
 class ICAO extends Plugin {

package/IFace.js

@@ -1,3 +1,7 @@
+/**
+* @module IFace
+*/
+
 import ICAO from './ICAO.js'
 import { BASE_URL, blobToBase64 } from './Common.js'
 
@@ -75,7 +79,7 @@ export class Probe {
 /**
  * Candidate
  * @classdesc Candidate Class for Innovatrics IFace SDK
- *
+ * @extends Probe
  * @see {@link IFace}
  */
 export class Candidate extends Probe {

package/MockCamera.js

@@ -1,6 +1,13 @@
 import Camera from './Camera.js'
 import { BASE_URL } from './Common.js'
 
+/**
+ * MockCamera
+ * @classdesc Convenience class for instantiating a Mock Camera Object.
+ * Inherits all methods on the {@link Camera} class.
+ * @extends Camera
+ * @see {@link Camera}
+ */
 class MockCamera extends Camera {
   constructor (baseUrl = BASE_URL) {
     super('capture_camera_mock', baseUrl)

package/Plugin.js

@@ -1,6 +1,6 @@
 import Device from './Device.js'
 
-import { BASE_URL, DELETE, asyncToCallback } from './Common.js'
+import { BASE_URL, DELETE, checkResponse, asyncToCallback } from './Common.js'
 
 /**
  * @classdesc CaptureBridge utilizes a plugin system for interacting with
@@ -62,7 +62,7 @@ class Plugin {
    *
    * @method
    * @async
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
    * @returns {object[]} Array of {@link Device} objects.
    * @example
    * const plugin = await captureBridge.plugin('capture_camera_canon')
@@ -70,6 +70,7 @@ class Plugin {
    */
   async devices () {
     const response = await fetch(`${this.baseUrl}/plugin/${this.id}/device`)
+    await checkResponse(response)
     const devices = await response.json()
     return devices.map(d => new Device(d, this, this.baseUrl))
   }
@@ -78,7 +79,7 @@ class Plugin {
    * Get all Devices for this plugin
    *
    * @method
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
    * @param {function} callback - Invoked with two arguments. The first argument
    * is an Error object (if an error occurred) or null. The second argument is
    * an Array of {@link Device} objects. If no devices are available the second
@@ -97,7 +98,7 @@ class Plugin {
    *
    * @method
    * @async
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
    * @param {string} id - Device ID
    * @returns {object?} Requested {@link Device} or null
    * @example
@@ -114,7 +115,7 @@ class Plugin {
   /**
    * Get a Device by ID for this plugin
    * @method
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
    * @param {string} id - Device ID
    * @param {function} callback - Invoked with two arguments. The first argument
    * is an Error object (if an error occurred) or null. The second argument is

package/Scanner.js

@@ -1,5 +1,5 @@
 import CapturePlugin from './CapturePlugin.js'
-import { BASE_URL } from './Common.js'
+import { BASE_URL, DEFAULT_CAPTURE_OPT, DEPRECATION_01 } from './Common.js'
 
 /**
  * Scanner
@@ -24,26 +24,9 @@ class Scanner extends CapturePlugin {
 
   /**
    * Scan a document
-   * @param {string} [kind] - Specify how to return the scanned document. Valid
-   * values are 'blob', 'buffer', 'base64', or 'dataurl'.
    *
-   * The default value of 'buffer' will load the image into an
-   * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer|ArrayBuffer}
-   * that can be set directly on an img tag's src attribute.
-   *
-   * The value of 'blob' will return a
-   * {@link https://developer.mozilla.org/en-US/docs/Web/API/Blob|Blob} that can
-   * be used with a
-   * {@link https://developer.mozilla.org/en-US/docs/Web/API/FileReader|FileReader}.
-   *
-   * The value of 'base64' will return the image contents as a
-   * {@link https://en.wikipedia.org/wiki/Base64|Base64} encoded string that is
-   * suitable for use with JSON serialization.
-   *
-   * The value of 'dataurl' will return a JPEG
-   * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URL}
-   * that can be set on an img tag's src attribute or loaded as a document
-   * location.
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * signature.
    *
    * @param {string|object} [deviceOpt] - Can a document using either a specific
    * Device ID or a Device Object. The default is the first available device.
@@ -56,8 +39,16 @@ class Scanner extends CapturePlugin {
    * img.src = await scanner.scan()
    * document.body.appendChild(img)
    */
-  async scan (kind = 'buffer', deviceOpt) {
-    return await this.fullCapture(kind, deviceOpt)
+  async scan (captureOpt = {}, deviceOpt) {
+    if (typeof captureOpt === 'string' && DEPRECATION_01) {
+      captureOpt = { kind: captureOpt }
+      console.warn('CaptureBridge SDK Deprecation Warning: `Scanner.scan()` ' +
+        'converted the `captureOpt` argument from a string (%s) to an object ' +
+        '(%s). This conversion may not be performed in future SDK versions.',
+      captureOpt.kind, JSON.stringify(captureOpt))
+    }
+    const mergedOpt = Object.assign({}, DEFAULT_CAPTURE_OPT, captureOpt)
+    return await this.fullCapture(mergedOpt, deviceOpt)
   }
 }
 

package/SignatureTablet.js

@@ -1,6 +1,12 @@
 import StreamingCapturePlugin from './StreamingCapturePlugin.js'
-import { BASE_URL } from './Common.js'
+import { BASE_URL, DEFAULT_CAPTURE_OPT, DEPRECATION_01 } from './Common.js'
 
+/**
+ * SignatureTablet
+ * @classdesc  Class for invoking methods on a Signature Capture Tablet
+ * @extends StreamingCapturePlugin
+ * @see {@link TopazSigGem}
+ */
 class SignatureTablet extends StreamingCapturePlugin {
   #captureBridge
   #scene = {}
@@ -69,29 +75,13 @@ class SignatureTablet extends StreamingCapturePlugin {
 
   /**
    * Capture a high resolution signature
-   * @param {string} [kind] - Specify how to return the captured photo. Valid
-   * values are 'blob', 'buffer', 'base64', or 'dataurl'.
    *
-   * The default value of 'buffer' will load the image into an
-   * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer|ArrayBuffer}
-   * that can be set directly on an img tag's src attribute.
-   *
-   * The value of 'blob' will return a
-   * {@link https://developer.mozilla.org/en-US/docs/Web/API/Blob|Blob} that can
-   * be used with a
-   * {@link https://developer.mozilla.org/en-US/docs/Web/API/FileReader|FileReader}.
-   *
-   * The value of 'base64' will return the image contents as a
-   * {@link https://en.wikipedia.org/wiki/Base64|Base64} encoded string that is
-   * suitable for use with JSON serialization.
-   *
-   * The value of 'dataurl' will return a JPEG
-   * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URL}
-   * that can be set on an img tag's src attribute or loaded as a document
-   * location.
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing a
+   * signature.
    *
    * @param {string|object} [deviceOpt] - Capture the signature using either a
-   * specific Device ID or a Device Object. The default is the first available device.
+   * specific Device ID or a Device Object. The default is the first available
+   * device.
    *
    * @async
    * @example
@@ -101,8 +91,17 @@ class SignatureTablet extends StreamingCapturePlugin {
    * img.src = await tablet.signature()
    * document.body.appendChild(img)
    */
-  async signature (kind = 'buffer', deviceOpt) {
-    return await this.fullCapture(kind, deviceOpt)
+  async signature (captureOpt = {}, deviceOpt) {
+    if (typeof captureOpt === 'string' && DEPRECATION_01) {
+      captureOpt = { kind: captureOpt }
+      console.warn('CaptureBridge SDK Deprecation Warning: ' +
+        '`SignatureTablet.signature()` converted the `captureOpt` argument ' +
+        'from a string (%s) to an object (%s). This conversion may not be ' +
+        'performed in future SDK versions.',
+      captureOpt.kind, JSON.stringify(captureOpt))
+    }
+    const mergedOpt = Object.assign({}, DEFAULT_CAPTURE_OPT, captureOpt)
+    return await this.fullCapture(mergedOpt, deviceOpt)
   }
 }
 

package/SignatureTabletWidgets.js

@@ -1,5 +1,16 @@
+/**
+* @module SignatureTabletWidgets
+*/
+
 import { blobToBase64 } from './Common.js'
 
+/**
+ * DisplayWidget
+ * @classdesc Represents a widget that can be displayed at some x and y coordinates
+ * @see {@link TextButton}
+ * @see {@link Text}
+ * @see {@link Image}
+ */
 export class DisplayWidget {
   x
   y
@@ -12,7 +23,7 @@ export class DisplayWidget {
 /**
  * TextButton
  * @classdesc A button for displaying clickable text on a tablet
- *
+ * @extends DisplayWidget
  * @see {@link SignatureTablet}
  */
 export class TextButton extends DisplayWidget {
@@ -64,7 +75,7 @@ export class TextButton extends DisplayWidget {
 /**
  * Text
  * @classdesc Text to be displayed on a tablet
- *
+ * @extends DisplayWidget
  * @see {@link SignatureTablet}
  */
 export class Text extends DisplayWidget {
@@ -106,7 +117,7 @@ export class Text extends DisplayWidget {
 /**
  * Image
  * @classdesc Image to be displayed on a tablet
- *
+ * @extends DisplayWidget
  * @see {@link SignatureTablet}
  */
 export class Image extends DisplayWidget {