@capturebridge/sdk 0.7.0 → 0.8.0

package/Camera.js

@@ -1,68 +1,63 @@
-import StreamingCapturePlugin from './StreamingCapturePlugin.js'
-import { BASE_URL, asyncToCallback } from './Common.js'
-
-/**
- * Camera
- * @classdesc Class for invoking methods on a Camera
- *
- * @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.
-   * @example
-   * const camera = new Camera('capture_camera_canon')
-   */
-  constructor (pluginId, baseUrl = BASE_URL) {
-    super(pluginId, baseUrl)
-  }
-
-  /**
-   * 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 {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
-   * // the document's body.
-   * const img = document.createElement('img')
-   * img.src = await camera.takePhoto('base64')
-   * document.body.appendChild(img)
-   */
-  async takePhoto (kind = 'buffer', deviceOpt) {
-    return await this.fullCapture(kind, deviceOpt)
-  }
-
-  takePhotoHandler (kind = 'buffer', deviceOpt, callback) {
-    asyncToCallback(this, this.fullCapture, callback, kind, deviceOpt)
-  }
-}
-
-export default Camera
+import StreamingCapturePlugin from './StreamingCapturePlugin.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} 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.
+   * @param {string} [baseURL] - Protocol, domain, and port for the service.
+   * @example
+   * const camera = new Camera('capture_camera_canon')
+   */
+  constructor (pluginId, baseUrl = BASE_URL) {
+    super(pluginId, baseUrl)
+  }
+
+  /**
+   * Capture a photo
+   * @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 ObjectURL, add it to an img element and append to
+   * // the document's body.
+   * const img = document.createElement('img')
+   * img.src = await camera.takePhoto()
+   * document.body.appendChild(img)
+   */
+  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 (captureOpt = {}, deviceOpt, callback) {
+    asyncToCallback(this, this.fullCapture, callback, captureOpt, deviceOpt)
+  }
+}
+
+export default Camera

package/CanonCamera.js

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

package/CaptureBridge.js

@@ -1,162 +1,160 @@
-import Plugin from './Plugin.js'
-import { BASE_URL, asyncToCallback } from './Common.js'
-
-/**
- * Capture Bridge
- *
- * @classdesc Class for interacting with the HTTP API's base methods.
- */
-class CaptureBridge {
-  baseUrl
-  /**
-   * Instantiate a client for interacting with the Capture Bridge service.
-   * @constructor
-   * @param {string} [baseURL] - Protocol, domain, and port for the service.
-   * @example
-   * const captureBridge = new CaptureBridge()
-   */
-  constructor (baseUrl = BASE_URL) {
-    this.baseUrl = baseUrl
-  }
-
-  /**
-   * Get service version info
-   * @method
-   * @async
-   * @returns {object} Service version info.
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Service-GetVersion|API Endpoint (/version)}
-   * @example
-   * const captureBridge = new CaptureBridge()
-   * const {version} = await captureBridge.version()
-   * console.log(version)
-   */
-  async version () {
-    const response = await fetch(`${this.baseUrl}/version`)
-    return await response.json()
-  }
-
-  /**
-   * Get service version info (Callback)
-   * @method
-   * @see {@link https://capture.local.valididcloud.com: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.
-   * @example
-   * captureBridge.versionHandler((error, {version}) => {
-   *   if (error) {
-   *     console.error('Error fetching version:', error)
-   *   } else {
-   *     console.log(`Version: ${version}`)
-   *   }
-   * })
-   */
-  versionHandler (callback) {
-    asyncToCallback(this, this.version, callback)
-  }
-
-  /**
-   * Get service status information
-   * @method
-   * @async
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Service-GetStatus|API Endpoint (/status)}
-   * @returns {object} Service status information.
-   * @example
-   * const captureBridge = new CaptureBridge()
-   * const statusInfo = await captureBridge.status()
-   * console.log(statusInfo)
-   */
-  async status () {
-    const response = await fetch(`${this.baseUrl}/status`)
-    return await response.json()
-  }
-
-  /**
-   * Get service status information (Callback)
-   * @method
-   * @see {@link https://capture.local.valididcloud.com: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.
-   * object.
-   * @example
-   * const captureBridge = new CaptureBridge()
-   * captureBridge.statusHandler(statusInfo => console.log(statusInfo))
-   */
-  statusHandler (callback) {
-    asyncToCallback(this, this.status, callback)
-  }
-
-  /**
-   * Get all installed plugins
-   * @method
-   * @async
-   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPlugins|API Endpoint (/plugin)}
-   * @see {@link Plugin}
-   * @returns {object[]} Array of {@link Plugin} objects.
-   * @example
-   * const plugins = await captureBridge.plugins()
-   */
-  async plugins () {
-    const response = await fetch(`${this.baseUrl}/plugin`)
-    const plugins = await response.json()
-    return plugins.map(p => new Plugin(p, this.baseUrl))
-  }
-
-  /**
-   * Get all installed plugins (Callback)
-   * @method
-   * @see {@link https://capture.local.valididcloud.com: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
-   * an Array of {@link Plugin} objects. If no plugins are installed the second
-   * argument will be an empty Array.
-   * @example
-   * captureBridge.pluginsHandler(plugins => console.log(plugins))
-   */
-  pluginsHandler (callback) {
-    asyncToCallback(this, this.plugins, callback)
-  }
-
-  /**
-   * 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 Plugin}
-   * @param {string} id - Plugin ID
-   * @returns {object?} {@link Plugin} object or null
-   * @example
-   * 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
-  }
-
-  /**
-   * 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 Plugin}
-   * @param {string} id - Plugin 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
-   * the requested {@link Plugin} object. If no matching plugin was found the
-   * second argument will be null.
-   * @example
-   * captureBridge.pluginHandler('capture_camera_canon', (error, plugin) => {
-   *   console.log(error, plugin)
-   * })
-   */
-  pluginHandler (id, callback) {
-    asyncToCallback(this, this.plugin, callback, id)
-  }
-}
-
-export default CaptureBridge
+import Plugin from './Plugin.js'
+import { BASE_URL, asyncToCallback, checkResponse } from './Common.js'
+
+/**
+ * Capture Bridge
+ *
+ * @classdesc Class for interacting with the HTTP API's base methods.
+ */
+class CaptureBridge {
+  baseUrl
+  /**
+   * Instantiate a client for interacting with the Capture Bridge service.
+   * @constructor
+   * @param {string} [baseURL] - Protocol, domain, and port for the service.
+   * @example
+   * const captureBridge = new CaptureBridge()
+   */
+  constructor (baseUrl = BASE_URL) {
+    this.baseUrl = baseUrl
+  }
+
+  /**
+   * Get service version info
+   * @method
+   * @async
+   * @returns {object} Service version info.
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Service-GetVersion|API Endpoint (/version)}
+   * @example
+   * const captureBridge = new CaptureBridge()
+   * const {version} = await captureBridge.version()
+   * console.log(version)
+   */
+  async version () {
+    const response = await fetch(`${this.baseUrl}/version`)
+    return await response.json()
+  }
+
+  /**
+   * Get service version info (Callback)
+   * @method
+   * @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.
+   * @example
+   * captureBridge.versionHandler((error, {version}) => {
+   *   if (error) {
+   *     console.error('Error fetching version:', error)
+   *   } else {
+   *     console.log(`Version: ${version}`)
+   *   }
+   * })
+   */
+  versionHandler (callback) {
+    asyncToCallback(this, this.version, callback)
+  }
+
+  /**
+   * Get service status information
+   * @method
+   * @async
+   * @see {@link https://local.capturebridge.net:9001/doc/#api-Service-GetStatus|API Endpoint (/status)}
+   * @returns {object} Service status information.
+   * @example
+   * const captureBridge = new CaptureBridge()
+   * const statusInfo = await captureBridge.status()
+   * console.log(statusInfo)
+   */
+  async status () {
+    const response = await fetch(`${this.baseUrl}/status`)
+    return await response.json()
+  }
+
+  /**
+   * Get service status information (Callback)
+   * @method
+   * @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.
+   * object.
+   * @example
+   * const captureBridge = new CaptureBridge()
+   * captureBridge.statusHandler(statusInfo => console.log(statusInfo))
+   */
+  statusHandler (callback) {
+    asyncToCallback(this, this.status, callback)
+  }
+
+  /**
+   * Get all installed plugins
+   * @method
+   * @async
+   * @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
+   * const plugins = await captureBridge.plugins()
+   */
+  async plugins () {
+    const response = await fetch(`${this.baseUrl}/plugin`)
+    const plugins = await response.json()
+    return plugins.map(p => new Plugin(p, this.baseUrl))
+  }
+
+  /**
+   * Get all installed plugins (Callback)
+   * @method
+   * @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
+   * an Array of {@link Plugin} objects. If no plugins are installed the second
+   * argument will be an empty Array.
+   * @example
+   * captureBridge.pluginsHandler(plugins => console.log(plugins))
+   */
+  pluginsHandler (callback) {
+    asyncToCallback(this, this.plugins, callback)
+  }
+
+  /**
+   * Get a single plugin by ID
+   * @method
+   * @async
+   * @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
+   * @example
+   * const plugin = await captureBridge.plugin('capture_camera_canon')
+   */
+  async plugin (id) {
+    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://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
+   * is an Error object (if an error occurred) or null. The second argument is
+   * the requested {@link Plugin} object. If no matching plugin was found the
+   * second argument will be null.
+   * @example
+   * captureBridge.pluginHandler('capture_camera_canon', (error, plugin) => {
+   *   console.log(error, plugin)
+   * })
+   */
+  pluginHandler (id, callback) {
+    asyncToCallback(this, this.plugin, callback, id)
+  }
+}
+
+export default CaptureBridge