@capturebridge/sdk 0.7.1 → 0.8.0

package/Camera.js

@@ -1,20 +1,25 @@
 import StreamingCapturePlugin from './StreamingCapturePlugin.js'
-import { BASE_URL, asyncToCallback } from './Common.js'
+import {
+  BASE_URL,
+  DEFAULT_CAPTURE_OPT,
+  DEPRECATION_01,
+  asyncToCallback
+} from './Common.js'
 
 /**
  * Camera
  * @classdesc Class for invoking methods on a Camera
- *
+ * @extends StreamingCapturePlugin
  * @see {@link CanonCamera}
  */
 class Camera extends StreamingCapturePlugin {
   /**
    * Instantiate a Generic Camera
    * @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.
+   * camera instance. The plugin must support the `start_feed`, `stop_feed`,
+   * `devices`, and `capture` methods.
+   * @param {string} [baseURL] - Protocol, domain, and port for the service.
    * @example
    * const camera = new Camera('capture_camera_canon')
    */
@@ -24,44 +29,34 @@ class Camera extends StreamingCapturePlugin {
 
   /**
    * Capture a photo
-   * @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
+   * photo.
    * @param {string|object} [deviceOpt] - Take the photo using either a specific
    * Device ID or a Device Object. The default is the first available device.
    *
    * @async
    * @example
-   * // Capture a photo as an ArrayBuffer and add it to an img tag appended to
+   * // Capture a photo as an ObjectURL, add it to an img element and append to
    * // the document's body.
    * const img = document.createElement('img')
-   * img.src = await camera.takePhoto('base64')
+   * img.src = await camera.takePhoto()
    * document.body.appendChild(img)
    */
-  async takePhoto (kind = 'buffer', deviceOpt) {
-    return await this.fullCapture(kind, deviceOpt)
+  async takePhoto (captureOpt = {}, deviceOpt) {
+    if (typeof captureOpt === 'string' && DEPRECATION_01) {
+      captureOpt = { kind: captureOpt }
+      console.warn('CaptureBridge SDK Deprecation Warning: ' +
+        '`Camera.takePhoto()` 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)
   }
 
-  takePhotoHandler (kind = 'buffer', deviceOpt, callback) {
-    asyncToCallback(this, this.fullCapture, callback, kind, deviceOpt)
+  takePhotoHandler (captureOpt = {}, deviceOpt, callback) {
+    asyncToCallback(this, this.fullCapture, callback, captureOpt, deviceOpt)
   }
 }
 

package/CanonCamera.js

@@ -5,7 +5,7 @@ import { BASE_URL } from './Common.js'
  * CanonCamera
  * @classdesc Convenience class for instantiating a Canon Camera Object.
  * Inherits all methods on the {@link Camera} class.
- *
+ * @extends Camera
  * @see {@link Camera}
  */
 class CanonCamera extends Camera {
@@ -15,7 +15,7 @@ class CanonCamera extends Camera {
    * @param {string} [baseURL] - Protocol, domain, and port for the service.
    * @example
    * const camera = new CanonCamera()
-   * const base64 = await camera.takePhoto('base64')
+   * const base64 = await camera.takePhoto({kind: 'base64'})
    */
   constructor (baseUrl = BASE_URL) {
     super('capture_camera_canon', baseUrl)

package/CaptureBridge.js

@@ -1,5 +1,5 @@
 import Plugin from './Plugin.js'
-import { BASE_URL, asyncToCallback } from './Common.js'
+import { BASE_URL, asyncToCallback, checkResponse } from './Common.js'
 
 /**
  * Capture Bridge
@@ -24,7 +24,7 @@ class CaptureBridge {
    * @method
    * @async
    * @returns {object} Service version info.
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Service-GetVersion|API Endpoint (/version)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Service-GetVersion|API Endpoint (/version)}
    * @example
    * const captureBridge = new CaptureBridge()
    * const {version} = await captureBridge.version()
@@ -38,7 +38,7 @@ class CaptureBridge {
   /**
    * Get service version info (Callback)
    * @method
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Service-GetVersion|API Endpoint (/version)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Service-GetVersion|API Endpoint (/version)}
    * @param {function} callback - Invoked with two arguments. The first argument
    * is an Error object (if an error occurred) or null. The second argument is
    * the version info.
@@ -59,7 +59,7 @@ class CaptureBridge {
    * Get service status information
    * @method
    * @async
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Service-GetStatus|API Endpoint (/status)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Service-GetStatus|API Endpoint (/status)}
    * @returns {object} Service status information.
    * @example
    * const captureBridge = new CaptureBridge()
@@ -74,7 +74,7 @@ class CaptureBridge {
   /**
    * Get service status information (Callback)
    * @method
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Service-GetStatus|API Endpoint (/status)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Service-GetStatus|API Endpoint (/status)}
    * @param {function} callback - Invoked with two arguments. The first argument
    * is an Error object (if an error occurred) or null. The second argument is
    * the status info.
@@ -91,7 +91,7 @@ class CaptureBridge {
    * Get all installed plugins
    * @method
    * @async
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPlugins|API Endpoint (/plugin)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Plugin-GetPlugins|API Endpoint (/plugin)}
    * @see {@link Plugin}
    * @returns {object[]} Array of {@link Plugin} objects.
    * @example
@@ -106,7 +106,7 @@ class CaptureBridge {
   /**
    * Get all installed plugins (Callback)
    * @method
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPlugins|API Endpoint (/plugin)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Plugin-GetPlugins|API Endpoint (/plugin)}
    * @see {@link Plugin}
    * @param {function} callback - Invoked with two arguments. The first argument
    * is an Error object (if an error occurred) or null. The second argument is
@@ -123,7 +123,7 @@ class CaptureBridge {
    * Get a single plugin by ID
    * @method
    * @async
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPlugins|API Endpoint (/plugin)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Plugin-GetPlugins|API Endpoint (/plugin)}
    * @see {@link Plugin}
    * @param {string} id - Plugin ID
    * @returns {object?} {@link Plugin} object or null
@@ -131,18 +131,16 @@ class CaptureBridge {
    * const plugin = await captureBridge.plugin('capture_camera_canon')
    */
   async plugin (id) {
-    // See: ValidRD/wa_capture_bridge/issues/48
-    // TODO: we need a  /plugin/:id endpoint
-    const response = await fetch(`${this.baseUrl}/plugin`)
-    const plugins = await response.json()
-    const plugin = plugins.find(p => p.id === id)
-    return plugin ? new Plugin(plugin) : null
+    const response = await fetch(`${this.baseUrl}/plugin/${id}`)
+    await checkResponse(response)
+    const pluginJSON = await response.json()
+    return new Plugin(pluginJSON)
   }
 
   /**
    * Get a single plugin by ID (Callback version).
    * @method
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPlugins|API Endpoint (/plugin)}
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Plugin-GetPlugins|API Endpoint (/plugin)}
    * @see {@link Plugin}
    * @param {string} id - Plugin ID
    * @param {function} callback - Invoked with two arguments. The first argument

package/CapturePlugin.js

@@ -1,11 +1,16 @@
 import Plugin from './Plugin.js'
-import { BASE_URL, DATAURL_JPEG, blobToBuffer } from './Common.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}
@@ -16,8 +21,8 @@ class CapturePlugin extends Plugin {
    * @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.
+   * camera instance. The plugin must support the `start_feed`, `stop_feed`,
+   * `devices`, and `capture` methods.
    * @example
    * const capture = new CapturePlugin('capture_camera_canon')
    */
@@ -27,27 +32,8 @@ class CapturePlugin extends Plugin {
 
   /**
    * 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 {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.
@@ -60,19 +46,22 @@ class CapturePlugin extends Plugin {
    * img.src = await capture.fullCapture()
    * document.body.appendChild(img)
    */
-  async fullCapture (kind = 'buffer', deviceOpt) {
+  async fullCapture (captureOpt = {}, deviceOpt) {
     const device = await this.setupDevice(deviceOpt)
-    switch (kind) {
+    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()
+        return await device.captureAsBlob(mergedOpt)
       case 'buffer':
-        return await blobToBuffer(await device.captureAsBlob())
+        return await blobToBuffer(await device.captureAsBlob(mergedOpt))
       case 'base64':
-        return await device.captureAsBase64()
+        return await device.captureAsBase64(mergedOpt)
       case 'dataurl':
-        return DATAURL_JPEG + (await device.captureAsBase64())
+        return DATAURL_JPEG + (await device.captureAsBase64(mergedOpt))
     }
-    throw new Error(`Unknown image response type: ${kind}`)
+    throw new Error(`Unknown image response kind: ${mergedOpt.kind}`)
   }
 }
 

package/Common.js

@@ -1,10 +1,10 @@
 /**
- * Default base URL for making API requests.
+ * @summary Default base URL for making API requests.
  * @constant
  * @type {string}
- * @default https://capture.local.valididcloud.com:9001
+ * @default {@link https://local.capturebridge.net:9001}
  */
-export const BASE_URL = 'https://capture.local.valididcloud.com:9001'
+export const BASE_URL = 'https://local.capturebridge.net:9001'
 
 /**
  * Common {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API|Fetch}
@@ -12,7 +12,7 @@ export const BASE_URL = 'https://capture.local.valididcloud.com:9001'
  * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST|POST}
  * requests to the API.
  * @constant
- * @type {string}
+ * @type {object}
  */
 export const POST = {
   mode: 'cors',
@@ -20,12 +20,13 @@ export const 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 {string}
+ * @type {object}
  */
 export const DELETE = {
   mode: 'cors',
@@ -33,7 +34,69 @@ export const DELETE = {
 }
 
 /**
- * `data:` prefix for JPEG
+ * @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}
@@ -41,7 +104,7 @@ export const DELETE = {
 export const DATAURL_JPEG = 'data:image/jpeg;base64,'
 
 /**
- * `data:` prefix for PNG
+ * @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}
@@ -96,3 +159,24 @@ export const asyncToCallback = (thisValue, asyncFn, callback, ...params) => {
     }
   })()
 }
+
+/**
+ * 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