@capturebridge/sdk 0.12.0 → 0.14.1

package/CapturePlugin.js

@@ -1,68 +1,68 @@
-import Plugin from './Plugin.js'
-import {
-  BASE_URL,
-  DATAURL_JPEG,
-  DEFAULT_CAPTURE_OPT,
-  blobToBuffer
-} from './Common.js'
-
-/**
- * CapturePlugin
- * @classdesc Class for working with a plugin that acquires high resolution
- * images from a device.
- * @extends Plugin
- * @see {@link Camera}
- * @see {@link SignatureTablet}
- * @see {@link Scanner}
- */
-class CapturePlugin extends Plugin {
-  /**
-   * Instantiate a CapturePlugin
-   * @constructor
-   * @param {string} [baseURL] - Protocol, domain, and port for the service.
-   * @param {string} pluginId - The Id of the desired plugin to use for this
-   * camera instance. The plugin must support the `start_feed`, `stop_feed`,
-   * `devices`, and `capture` methods.
-   * @example
-   * const capture = new CapturePlugin('capture_camera_canon')
-   */
-  constructor (plugin, baseUrl = BASE_URL) {
-    super(plugin, baseUrl)
-  }
-
-  /**
-   * Take a full capture
-   * @param {CaptureOptions} [captureOpt] - Additional options for capturing an
-   * image.
-   * @param {string|object} [deviceOpt] - Take the capture using either a
-   * specific Device ID or a Device Object. The default is the first available
-   * device.
-   *
-   * @async
-   * @example
-   * // Capture an image as an ArrayBuffer and add it to an img tag appended to
-   * // the document's body.
-   * const img = document.createElement('img')
-   * img.src = await capture.fullCapture()
-   * document.body.appendChild(img)
-   */
-  async fullCapture (captureOpt = {}, deviceOpt) {
-    const device = await this.setupDevice(deviceOpt)
-    const mergedOpt = Object.assign({}, DEFAULT_CAPTURE_OPT, captureOpt)
-    switch (mergedOpt.kind) {
-      case 'objecturl':
-        return URL.createObjectURL(await device.captureAsBlob(mergedOpt))
-      case 'blob':
-        return await device.captureAsBlob(mergedOpt)
-      case 'buffer':
-        return await blobToBuffer(await device.captureAsBlob(mergedOpt))
-      case 'base64':
-        return await device.captureAsBase64(mergedOpt)
-      case 'dataurl':
-        return DATAURL_JPEG + (await device.captureAsBase64(mergedOpt))
-    }
-    throw new Error(`Unknown image response kind: ${mergedOpt.kind}`)
-  }
-}
-
-export default CapturePlugin
+import Plugin from './Plugin.js'
+import {
+  BASE_URL,
+  DATAURL_JPEG,
+  DEFAULT_CAPTURE_OPT,
+  blobToBuffer
+} from './Common.js'
+
+/**
+ * CapturePlugin
+ * @classdesc Class for working with a plugin that acquires high resolution
+ * images from a device.
+ * @extends Plugin
+ * @see {@link Camera}
+ * @see {@link SignatureTablet}
+ * @see {@link Scanner}
+ */
+class CapturePlugin extends Plugin {
+  /**
+   * Instantiate a CapturePlugin
+   * @constructor
+   * @param {string} [baseURL] - Protocol, domain, and port for the service.
+   * @param {string} pluginId - The Id of the desired plugin to use for this
+   * camera instance. The plugin must support the `start_feed`, `stop_feed`,
+   * `devices`, and `capture` methods.
+   * @example
+   * const capture = new CapturePlugin('capture_camera_canon')
+   */
+  constructor (plugin, baseUrl = BASE_URL) {
+    super(plugin, baseUrl)
+  }
+
+  /**
+   * Take a full capture
+   * @param {CaptureOptions} [captureOpt] - Additional options for capturing an
+   * image.
+   * @param {string|object} [deviceOpt] - Take the capture using either a
+   * specific Device ID or a Device Object. The default is the first available
+   * device.
+   *
+   * @async
+   * @example
+   * // Capture an image as an ArrayBuffer and add it to an img tag appended to
+   * // the document's body.
+   * const img = document.createElement('img')
+   * img.src = await capture.fullCapture()
+   * document.body.appendChild(img)
+   */
+  async fullCapture (captureOpt = {}, deviceOpt) {
+    const device = await this.setupDevice(deviceOpt)
+    const mergedOpt = Object.assign({}, DEFAULT_CAPTURE_OPT, captureOpt)
+    switch (mergedOpt.kind) {
+      case 'objecturl':
+        return URL.createObjectURL(await device.captureAsBlob(mergedOpt))
+      case 'blob':
+        return await device.captureAsBlob(mergedOpt)
+      case 'buffer':
+        return await blobToBuffer(await device.captureAsBlob(mergedOpt))
+      case 'base64':
+        return await device.captureAsBase64(mergedOpt)
+      case 'dataurl':
+        return DATAURL_JPEG + (await device.captureAsBase64(mergedOpt))
+    }
+    throw new Error(`Unknown image response kind: ${mergedOpt.kind}`)
+  }
+}
+
+export default CapturePlugin

package/Common.js

@@ -1,252 +1,258 @@
-/**
- * @summary Default URL for API requests.
- * @constant
- * @type {string}
- */
-export const DEFAULT_URL = 'https://local.capturebridge.net:9001'
-
-/**
- * @summary Base URL for API requests.
- * @constant
- * @type {string}
- * @default {@link https://local.capturebridge.net:9001}
- */
-export const BASE_URL = window?.location?.origin ?? DEFAULT_URL
-
-/**
- * Common {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch}
- * options for making
- * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST|POST}
- * requests to the API.
- * @constant
- * @type {object}
- */
-export const POST = {
-  mode: 'cors',
-  method: 'post'
-}
-
-/**
- * @summary
- * Common {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch}
- * options for making
- * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE|DELETE}
- * requests to the API.
- * @constant
- * @type {object}
- */
-export const DELETE = {
-  mode: 'cors',
-  method: 'delete'
-}
-
-/**
- * @summary Default options for stream operations
- * @constant
- * @property {number} rotate - Angle, in degrees to rotate the stream. Must be
- * a value from -359 to 359. A value outside of that range, or a 0 will perform
- * no rotation.
- * @typedef {object} StreamOptions
- */
-export const DEFAULT_STREAM_OPT = {
-  rotate: 0
-}
-
-/**
- * @typedef {string} CaptureResponseKind
- * @summary Specifies the desired return type for a captured object. Valid
- * values are `objecturl`, `blob`, `buffer`, `base64`, or `dataurl`.
- *
- *  - `objecturl` will load the captured object into 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 these URLs
- * should be {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/revokeObjectURL_static|revoked}
- * when they are no longer needed.
- *
- * - `buffer` will load the image into an
- * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer|ArrayBuffer}
- *
- * - `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}.
- *
- * - `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.
- *
- * - `dataurl` will return a
- * {@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.
- *
- */
-
-/**
- * @typedef {string} CaptureResponseFormat
- * @summary The image format to be returned.
- *
- * Valid values:
- *
- *  - `jpg`
- *  - `tiff`
- *
- * If not provided, a plugin or device-specific format will be returned.
- *
- * **Note:**
- *  - Some plugins have configuration options for specifying the return format,
- * such configuration options should be used instead of this parameter to
- * prevent unecessary transcoding.
- * - Web browsers are not typically capable of displaying TIFF images.
- *
- */
-
-/**
- * @summary Default options for capture operations.
- * @constant
- * @property {number?} rotate - Angle, in degrees to rotate the captured object.
- * Must be a value from -359 to 359. A value of 0 will perform no rotation.
- * @property {boolean?} base64 - Return the captured object as a base64 encoded
- * string. The default behavior is to return the image as binary data.
- * @property {CaptureResponseKind} kind - Specifies how to return the captured
- * object. Some SDK methods that are designed to only return a particular type,
- * such as {@link Device#frameAsBase64}, ignore this parameter. This parameter
- * is also not sent in API requests, it is used internally by the SDK for
- * constructing the appropriate response type.
- * @property {CaptureResponseFormat} format - The image format to be returned.
- *
- * @typedef {object} CaptureOptions
- */
-export const DEFAULT_CAPTURE_OPT = {
-  rotate: 0,
-  base64: false,
-  format: null,
-  kind: 'objecturl'
-}
-
-/**
- * @summary `data:` prefix for JPEG
- * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URLs}
- * @constant
- * @type {string}
- */
-export const DATAURL_JPEG = 'data:image/jpeg;base64,'
-
-/**
- * @summary `data:` prefix for PNG
- * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URLs}
- * @constant
- * @type {string}
- */
-export const DATAURL_PNG = 'data:image/png;base64,'
-
-/**
- * @summary For a given base64 string, convert it to the appropriate Data URL
- * @constant
- * @type {string}
- */
-export const base64ToDataURL = base64 => {
-  const magicBytes = atob(base64.slice(0, 6))
-  const byteArray = new Uint8Array(magicBytes.length)
-  for (let i = 0; i < magicBytes.length; i++) {
-    byteArray[i] = magicBytes.charCodeAt(i)
-  }
-
-  // Check for JPEG magic number (FF D8 FF)
-  if (byteArray[0] === 0xFF && byteArray[1] === 0xD8 && byteArray[2] === 0xFF) {
-    return DATAURL_JPEG + base64
-  }
-
-  // Check for PNG magic number (89 50 4E 47)
-  if (byteArray[0] === 0x89 && byteArray[1] === 0x50 && byteArray[2] === 0x4E && byteArray[3] === 0x47) {
-    return DATAURL_PNG + base64
-  }
-
-  throw new Error('Unknown image format provided in Base64 string')
-}
-
-/**
- * An Async/Await version of
- * {@link https://developer.mozilla.org/en-US/docs/Web/API/setTimeout|setTimeout}
- * @private
- */
-export const timeout = millis => {
-  return new Promise(resolve => setTimeout(resolve, millis))
-}
-
-/**
- * Convert a Blob to a Buffer
- * @private
- */
-export const blobToBuffer = blob => {
-  return new Promise(resolve => {
-    const reader = new window.FileReader()
-    reader.onload = event => resolve(event.target.result)
-    reader.readAsArrayBuffer(blob)
-  })
-}
-
-/**
- * Convert a Blob to a Base64 String
- * @private
- */
-export const blobToBase64 = blob => {
-  return new Promise(resolve => {
-    const reader = new window.FileReader()
-    reader.onload = event => resolve(event.target.result.split(',')[1])
-    reader.readAsDataURL(blob)
-  })
-}
-
-/**
- * Helper function for classes to easily add callback style support to their
- * async/await methods.
- * @private
- */
-export const asyncToCallback = (thisValue, asyncFn, callback, ...params) => {
-  (async () => {
-    try {
-      const result = await asyncFn.call(thisValue, ...(params.length ? params : []))
-      callback(null, result)
-    } catch (ex) {
-      callback(ex)
-    }
-  })()
-}
-
-/**
- * Helper function to throw if an http response was a error.
- * @private
- */
-export const checkResponse = async (response) => {
-  if (!response.ok) {
-    const error = await response.json()
-    const msg = error.message || error.summary || error.code || 'Unexpected error'
-    const ex = new Error(msg)
-    ex.code = error.code || 500
-    ex.summary = error.summary || 'Unexpected error'
-    throw ex
-  }
-}
-
-/**
- * Helper function to convert a key/value map to a string, removing any items
- * that are null or undefined (instead of converting them to a string which
- * URLSearchParams().toString() will do.)
- * @private
- */
-export const urlParamsToString = (params) => {
-  const filtered = {}
-  Object.keys(params).forEach(key => {
-    if (params[key] !== null && params[key] !== undefined) {
-      filtered[key] = params[key]
-    }
-  })
-  return new URLSearchParams(filtered).toString()
-}
-
-/**
- * Allows passing in a string for the response type of capture methods
- * @private
- */
-export const DEPRECATION_01 = true
+/**
+ * @summary Default URL for API requests.
+ * @constant
+ * @type {string}
+ */
+export const DEFAULT_URL = 'https://local.capturebridge.net:9001'
+
+/**
+ * @summary Base URL for API requests.
+ * @constant
+ * @type {string}
+ * @default {@link https://local.capturebridge.net:9001}
+ */
+export const BASE_URL = window?.location?.origin ?? DEFAULT_URL
+
+/**
+ * Common {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch}
+ * options for making
+ * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST|POST}
+ * requests to the API.
+ * @constant
+ * @type {object}
+ */
+export const POST = {
+  mode: 'cors',
+  method: 'post'
+}
+
+/**
+ * @summary
+ * Common {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch}
+ * options for making
+ * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE|DELETE}
+ * requests to the API.
+ * @constant
+ * @type {object}
+ */
+export const DELETE = {
+  mode: 'cors',
+  method: 'delete'
+}
+
+/**
+ * @summary Default options for stream operations
+ * @constant
+ * @property {number} rotate - Angle, in degrees to rotate the stream. Must be
+ * a value from -359 to 359. A value outside of that range, or a 0 will perform
+ * no rotation.
+ * @typedef {object} StreamOptions
+ */
+export const DEFAULT_STREAM_OPT = {
+  rotate: 0
+}
+
+/**
+ * @typedef {string} CaptureResponseKind
+ * @summary Specifies the desired return type for a captured object. Valid
+ * values are `objecturl`, `blob`, `buffer`, `base64`, or `dataurl`.
+ *
+ *  - `objecturl` will load the captured object into 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 these URLs
+ * should be {@link https://developer.mozilla.org/en-US/docs/Web/API/URL/revokeObjectURL_static|revoked}
+ * when they are no longer needed.
+ *
+ * - `buffer` will load the image into an
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer|ArrayBuffer}
+ *
+ * - `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}.
+ *
+ * - `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.
+ *
+ * - `dataurl` will return a
+ * {@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.
+ *
+ */
+
+/**
+ * @typedef {string} CaptureResponseFormat
+ * @summary The image format to be returned.
+ *
+ * Valid values:
+ *
+ *  - `jpg`
+ *  - `tiff`
+ *
+ * If not provided, a plugin or device-specific format will be returned.
+ *
+ * **Note:**
+ *  - Some plugins have configuration options for specifying the return format,
+ * such configuration options should be used instead of this parameter to
+ * prevent unecessary transcoding.
+ * - Web browsers are not typically capable of displaying TIFF images.
+ *
+ */
+
+/**
+ * @summary Default options for capture operations.
+ * @constant
+ * @property {number?} rotate - Angle, in degrees to rotate the captured object.
+ * Must be a value from -359 to 359. A value of 0 will perform no rotation.
+ * @property {boolean?} base64 - Return the captured object as a base64 encoded
+ * string. The default behavior is to return the image as binary data.
+ * @property {CaptureResponseKind} kind - Specifies how to return the captured
+ * object. Some SDK methods that are designed to only return a particular type,
+ * such as {@link Device#frameAsBase64}, ignore this parameter. This parameter
+ * is also not sent in API requests, it is used internally by the SDK for
+ * constructing the appropriate response type.
+ * @property {CaptureResponseFormat} format - The image format to be returned.
+ *
+ * @typedef {object} CaptureOptions
+ */
+export const DEFAULT_CAPTURE_OPT = {
+  rotate: 0,
+  base64: false,
+  format: null,
+  kind: 'objecturl'
+}
+
+/**
+ * @summary `data:` prefix for JPEG
+ * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URLs}
+ * @constant
+ * @type {string}
+ */
+export const DATAURL_JPEG = 'data:image/jpeg;base64,'
+
+/**
+ * @summary `data:` prefix for PNG
+ * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URLs}
+ * @constant
+ * @type {string}
+ */
+export const DATAURL_PNG = 'data:image/png;base64,'
+
+/**
+ * @summary For a given base64 string, convert it to the appropriate Data URL
+ * @constant
+ * @type {string}
+ */
+export const base64ToDataURL = base64 => {
+  const magicBytes = atob(base64.slice(0, 6))
+  const byteArray = new Uint8Array(magicBytes.length)
+  for (let i = 0; i < magicBytes.length; i++) {
+    byteArray[i] = magicBytes.charCodeAt(i)
+  }
+
+  // Check for JPEG magic number (FF D8 FF)
+  if (byteArray[0] === 0xFF && byteArray[1] === 0xD8 && byteArray[2] === 0xFF) {
+    return DATAURL_JPEG + base64
+  }
+
+  // Check for PNG magic number (89 50 4E 47)
+  if (byteArray[0] === 0x89 && byteArray[1] === 0x50 && byteArray[2] === 0x4E && byteArray[3] === 0x47) {
+    return DATAURL_PNG + base64
+  }
+
+  throw new Error('Unknown image format provided in Base64 string')
+}
+
+/**
+ * An Async/Await version of
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/setTimeout|setTimeout}
+ * @private
+ */
+export const timeout = millis => {
+  return new Promise(resolve => setTimeout(resolve, millis))
+}
+
+/**
+ * Convert a Blob to a Buffer
+ * @private
+ */
+export const blobToBuffer = blob => {
+  return new Promise(resolve => {
+    const reader = new window.FileReader()
+    reader.onload = event => resolve(event.target.result)
+    reader.readAsArrayBuffer(blob)
+  })
+}
+
+/**
+ * Convert a Blob to a Base64 String
+ * @private
+ */
+export const blobToBase64 = blob => {
+  return new Promise(resolve => {
+    const reader = new window.FileReader()
+    reader.onload = event => resolve(event.target.result.split(',')[1])
+    reader.readAsDataURL(blob)
+  })
+}
+
+/**
+ * Helper function for classes to easily add callback style support to their
+ * async/await methods.
+ * @private
+ */
+export const asyncToCallback = (thisValue, asyncFn, callback, ...params) => {
+  (async () => {
+    try {
+      const result = await asyncFn.call(thisValue, ...(params.length ? params : []))
+      callback(null, result)
+    } catch (ex) {
+      callback(ex)
+    }
+  })()
+}
+
+/**
+ * Helper function to throw if an http response was a error.
+ * @private
+ */
+export const checkResponse = async (response) => {
+  if (!response.ok) {
+    const error = await response.json()
+    const msg = error.message || error.summary || error.code || 'Unexpected error'
+    const ex = new Error(msg)
+    ex.code = error.code || 500
+    ex.summary = error.summary || 'Unexpected error'
+    throw ex
+  }
+}
+
+/**
+ * Helper function to convert a key/value map to a string, removing any items
+ * that are null or undefined (instead of converting them to a string which
+ * URLSearchParams().toString() will do.)
+ * @private
+ */
+export const urlParamsToString = (params) => {
+  const filtered = {}
+  Object.keys(params).forEach(key => {
+    if (params[key] !== null && params[key] !== undefined) {
+      filtered[key] = params[key]
+    }
+  })
+  return new URLSearchParams(filtered).toString()
+}
+
+/**
+ * Allows passing in a string for the response type of capture methods
+ * @private
+ */
+export const DEPRECATION_01 = true
+
+/**
+ * Allows passing in a boolean to clear the screen for display methods
+ * @private
+ */
+export const DEPRECATION_02 = true