@capturebridge/sdk 0.7.0 → 0.8.0

package/CapturePlugin.js

@@ -1,79 +1,68 @@
-import Plugin from './Plugin.js'
-import { BASE_URL, DATAURL_JPEG, blobToBuffer } from './Common.js'
-
-/**
- * CapturePlugin
- * @classdesc Class for working with a plugin that acquires high resolution
- * images from a device.
- *
- * @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 {string} [kind=buffer] - Specify how to return the captured image. 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 {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 (kind = 'buffer', deviceOpt) {
-    const device = await this.setupDevice(deviceOpt)
-    switch (kind) {
-      case 'blob':
-        return await device.captureAsBlob()
-      case 'buffer':
-        return await blobToBuffer(await device.captureAsBlob())
-      case 'base64':
-        return await device.captureAsBase64()
-      case 'dataurl':
-        return DATAURL_JPEG + (await device.captureAsBase64())
-    }
-    throw new Error(`Unknown image response type: ${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,98 +1,182 @@
-/**
- * Default base URL for making API requests.
- * @constant
- * @type {string}
- * @default https://capture.local.valididcloud.com:9001
- */
-export const BASE_URL = 'https://capture.local.valididcloud.com:9001'
-
-/**
- * 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 {string}
- */
-export const POST = {
-  mode: 'cors',
-  method: 'post'
-}
-
-/**
- * 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 {string}
- */
-export const DELETE = {
-  mode: 'cors',
-  method: 'delete'
-}
-
-/**
- * `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,'
-
-/**
- * `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,'
-
-/**
- * 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)
-    }
-  })()
-}
+/**
+ * @summary Default base URL for making API requests.
+ * @constant
+ * @type {string}
+ * @default {@link https://local.capturebridge.net:9001}
+ */
+export const BASE_URL = 'https://local.capturebridge.net:9001'
+
+/**
+ * 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.
+ *
+ */
+
+/**
+ * @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.
+ * @typedef {object} CaptureOptions
+ */
+export const DEFAULT_CAPTURE_OPT = {
+  rotate: 0,
+  base64: false,
+  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,'
+
+/**
+ * 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
+  }
+}
+
+/**
+ * Allows passing in a string for the response type of capture methods
+ * @private
+ */
+export const DEPRECATION_01 = true