@capturebridge/sdk 0.7.0

package/Device.js

@@ -0,0 +1,451 @@
+import { BASE_URL, POST, DELETE, timeout, asyncToCallback } from './Common.js'
+
+/**
+ * Device
+ * @classdesc Class for interacting with a Device returned from a plugin.
+ */
+class Device {
+  /*
+   * @property {Object} device - Device object as received from the API
+   * @property {string} device.id - URL safe device identified, this can often be hashed or encoded and should be considered opaque.
+   * @property {string?} device.raw_id - When possible, if the id is of some encoded or hashed type, this is the underlying value and can be shown to users.
+   * @property {string} device.name - Human friendly name of the device.
+   */
+  baseUrl
+  plugin
+  id
+  raw_id
+  name
+
+  /**
+   * Instantiate a device.
+   * @constructor
+   * @param {object} device - Device object as received from the API
+   * @param {string} device.id - URL safe device identified, this can often be hashed or encoded and should be considered opaque.
+   * @param {string?} device.raw_id - When possible, if the id is of some encoded or hashed type, this is the underlying value and can be shown to users.
+   * @param {string} device.name - Human friendly name of the device.
+   * @param {object} plugin - Plugin serviced by this device.
+   * @param {string} [baseURL] - Protocol, domain, and port for the service.
+   */
+  constructor (properties, plugin, baseUrl = BASE_URL) {
+    this.baseUrl = baseUrl
+    this.plugin = plugin
+    Object.assign(this, {}, properties)
+  }
+
+  can (method) {
+    if (this.plugin.methods.indexOf(method) === -1) {
+      throw new Error(`${method} not supported for this device`)
+    }
+  }
+
+  /**
+   * Get the stream endpoint URL.
+   *
+   * @description the URL returned from this endpoint can be attached to an
+   * img tag's src attribute. The device's live stream will be started and
+   * begin streaming to the img tag as a
+   * {@link https://en.wikipedia.org/wiki/Motion_JPEG|Motion JPEG} stream.
+   * If the src is changed, the img removed from the DOM, or client disconnected
+   * for any reason, the live feed will automatically be stopped.
+   *
+   * @method
+   * @returns {string} stream endpoint URL
+   * @example
+   * const img = document.createElement('img')
+   * img.src = device.streamUrl()
+   * document.body.appendChild(img)
+   */
+  streamUrl () {
+    this.can('start_feed')
+    this.can('stop_feed')
+    return `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/stream`
+  }
+
+  /**
+   * Take full capture from the specified device and 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}
+   * (Async/Await version)
+   *
+   * @method
+   * @async
+   * @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
+   * 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 captureAsBlob () {
+    this.can('capture')
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture`
+    const response = await fetch(url, POST)
+    return await response.blob()
+  }
+
+  /**
+   * Take full capture from the specified device and 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}
+   * (Callback version)
+   *
+   * @method
+   * @param {function} callback - {@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
+   * device.captureAsBlobHandler((error, blob) => {
+   *   const reader = new FileReader()
+   *   reader.onload = event => {
+   *     const img = document.createElement('img')
+   *     img.src = event.target.result
+   *     document.body.appendChild(img)
+   *    }
+   *   reader.readAsDataURL(blob)
+   * })
+   */
+  captureAsBlobHandler (callback) {
+    asyncToCallback(this, this.captureAsBlob, callback)
+  }
+
+  /**
+   * Take full capture from the specified device and return a
+   * base64 encoded string of the image that can be used with a
+   * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URL}
+   * (Async/Await version)
+   *
+   * @method
+   * @async
+   * @returns {string} Base64 Encoded image
+   * @example
+   * // Add the base64 string as a Data URL to an img tag and append to
+   * // the document's body
+   * const base64 = await device.captureAsBase64()
+   * const img = document.createElement('img')
+   * img.src = 'data:image/jpeg;base64,' + base64
+   * document.body.appendChild(img)
+   */
+  async captureAsBase64 () {
+    this.can('capture')
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture?base64=true`
+    const response = await fetch(url, POST)
+    const { image } = await response.json()
+    return image
+  }
+
+  /**
+   * Take full capture from the specified device and return a
+   * base64 encoded string of the image that can be used with a
+   * {@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
+   */
+  captureAsBase64Handler (callback) {
+    asyncToCallback(this, this.captureAsBase64, callback)
+  }
+
+  /**
+   * Get a base64 encoded frame from a device's live feed.
+   * @method
+   *
+   * @description This method will startup the live
+   * feed if necessary and wait for it to initialize before returning a frame.
+   * Subsequent calls will return the next available frame.
+   * You must manually stop the live feed if you are using this method.
+   *
+   * The frame returned will be a base64 encoded string of the image that can
+   * be used with a
+   * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URL}
+   *
+   * If implementing a real-time preview, it is highly recommended to use the
+   * stream endpoint which will stream a Motion JPEG.
+   *
+   * @see {@link streamUrl}
+   * @see {@link stopFeed}
+   *
+   * @async
+   * @param {number} [millis] - Milliseconds to wait if feed is not ready
+   * @returns {string} Base64 Encoded image
+   * @example
+   * // Add the base64 string as a Data URL to an img tag and append to
+   * // the document's body
+   * const base64 = await device.frameAsBase64()
+   * const img = document.createElement('img')
+   * img.src = 'data:image/jpeg;base64,' + base64
+   * document.body.appendChild(img)
+   */
+  async frameAsBase64 (millis = 1000) {
+    this.can('start_feed')
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/livefeed?base64=true`
+    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)
+    } else {
+      return result.image
+    }
+  }
+
+  /**
+   * Get a base64 encoded frame from a device's live feed. (Callback version)
+   * @method
+   *
+   * @description This method will startup the live
+   * feed if necessary and wait for it to initialize before returning a frame.
+   * Subsequent calls will return the next available frame.
+   * You must manually stop the live feed if you are using this method.
+   *
+   * The frame returned will be a base64 encoded string of the image that can
+   * be used with a
+   * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs|Data URL}
+   *
+   * If implementing a real-time preview, it is highly recommended to use the
+   * stream endpoint which will stream a Motion JPEG.
+   *
+   * @see {@link streamUrl}
+   * @see {@link setStopFeed}
+   *
+   * @param {function} callback - Base64 Encoded image
+   * @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
+   * // the document's body
+   * device.frameAsBase64Handler(base64 => {
+   *   const img = document.createElement('img')
+   *   img.src = 'data:image/jpeg;base64,' + base64
+   *   document.body.appendChild(img)
+   * })
+   */
+  frameAsBase64Handler (callback, millis = 1000) {
+    asyncToCallback(this, this.frameAsBase64, callback, millis)
+  }
+
+  /**
+   * Get a binary frame from a device's live feed. (Async/await version)
+   * @method
+   *
+   * @description This method will startup the live
+   * feed if necessary and wait for it to initialize before returning a frame.
+   * Subsequent calls will return the next available frame.
+   * You must manually stop the live feed if you are using this method.
+   *
+   * The frame returned will be 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}
+   *
+   * If implementing a real-time preview, it is highly recommended to use the
+   * stream endpoint which will stream a Motion JPEG.
+   *
+   * @see {@link streamUrl}
+   * @see {@link stopFeed}
+   *
+   * @async
+   * @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
+   * // Load the blob into FileReader and append to the document's body
+   * const blob = await device.frameAsBlob()
+   * 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 frameAsBlob (millis = 1000) {
+    this.can('start_feed')
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/livefeed`
+    const result = await this.frameAsBase64(millis)
+    if (typeof result === 'string') {
+      timeout(millis)
+      const response = await fetch(url)
+      return await response.blob()
+    }
+    throw new Error(result || 'Failed to get frame')
+  }
+
+  /**
+   * Get a binary frame from a device's live feed. (Callback version)
+   * @method
+   *
+   * @description This method will startup the live
+   * feed if necessary and wait for it to initialize before returning a frame.
+   * Subsequent calls will return the next available frame.
+   * You must manually stop the live feed if you are using this method.
+   *
+   * The frame returned will be 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}
+   *
+   * If implementing a real-time preview, it is highly recommended to use the
+   * stream endpoint which will stream a Motion JPEG.
+   *
+   * @see {@link streamUrl}
+   * @see {@link setStopFeed}
+   *
+   * @param {function} callback -{@link https://developer.mozilla.org/en-US/docs/Web/API/Blob|Blob}
+   * @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) => {
+   *   const reader = new FileReader()
+   *   reader.onload = event => {
+   *     const img = document.createElement('img')
+   *     img.src = event.target.result
+   *     document.body.appendChild(img)
+   *   }
+   *   reader.readAsDataURL(blob)
+   * })
+   */
+  frameAsBlobHandler (callback, millis = 1000) {
+    asyncToCallback(this, this.frameAsBlob, callback, millis)
+  }
+
+  /**
+   * Stop the live feed if it is running.
+   * (Async/Await version)
+   *
+   * @method
+   * @async
+   * @returns {object} Status of the stop operation
+   * @example
+   * // Plugin is now running it's live feed in a background thread
+   * const blob = await device.frameAsBlob()
+   * // Live feed is now stopping
+   * console.log(await device.stopFeed())
+   */
+  async stopFeed () {
+    this.can('stop_feed')
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/livefeed`
+    const response = await fetch(url, DELETE)
+    return await response.json()
+  }
+
+  /**
+   * Stop the live feed if it is running.
+   * (Callback version)
+   *
+   * @method
+   * @param {number} [millis] - Milliseconds to wait if feed is not ready
+   * @param {function} callback with the status of the stop operation
+   * @example
+   * device.stopFeedHandler((error, blob) => {
+   *   // Plugin is now running it's live feed in a background thread
+   *   device.setStopFeed(result => {
+   *     // Live feed is now stopping
+   *     console.log(result)
+   *   })
+   * })
+   */
+  stopFeedHandler (callback) {
+    asyncToCallback(this, this.frameAsBlob, callback)
+  }
+
+  /**
+   * Clear a device's display.
+   * (Async/Await version)
+   *
+   * @method
+   * @async
+   * @param {boolean} [backlight] If provided and set to true, will enable
+   * backlight. If false, it will be disabled. If unspecified no action will be
+   * taken on the backlight.
+   * @returns {object} Status of the clear operation
+   * @example
+   * console.log(await await device.clear())
+   */
+  async clear (backlight) {
+    this.can('draw')
+    let url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/display`
+    if (typeof backlight === 'boolean') {
+      url += `?backlight=${backlight}`
+    }
+    const response = await fetch(url, DELETE)
+    return await response.json()
+  }
+
+  /**
+   * Clear a device's display.
+   * (Callback version)
+   *
+   * @method
+   * @param {function} callback with the status of the clear operation
+   * @param {boolean} [backlight] If provided and set to true, will enable
+   * backlight. If false, it will be disabled. If unspecified no action will be
+   * taken on the backlight.
+   * @example
+   *  device.clearHandler((error, result) => {
+   *    console.log(result)
+   *  })
+   */
+  clearHandler (callback, backlight) {
+    asyncToCallback(this, this.clear, callback, backlight)
+  }
+
+  /**
+   * Display an Array of objects on the display.
+   *
+   * @description If any objects are Button types, the method will wait for one
+   * to be clicked and will then return the ID of the clicked object.
+   *
+   * @param {object[]} objects An array of Signature Tablet Widgets to display.
+   *
+   * @param {boolean} [clear] If true (the default), the display will be cleared
+   * before adding the objects.
+   *
+   *
+   * @async
+   * @method
+   * @returns {string?} ID of the clicked object if any
+   * @example
+   * const result = await tablet.displayObjects([
+   *  new TextButton("OK", 20, 200),
+   *  new TextButton("Cancel", 80, 200)
+   * ])
+   *
+   * console.log(`${result} was clicked`)
+   */
+  async displayObjects (objects, clear = true) {
+    this.can('draw')
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/display`
+
+    const asyncOperations = objects.map(async obj => {
+      if (obj.constructor.name === 'Image') {
+        await obj.data()
+      }
+    })
+
+    // Wait for all async operations to complete
+    await Promise.all(asyncOperations)
+
+    const options = {
+      method: 'POST',
+      mode: 'cors',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        clear,
+        backlight: true,
+        objects
+      })
+    }
+    const response = await fetch(url, options)
+    const { clicked } = await response.json()
+    return clicked
+  }
+
+  async displayObjectsHandler (objects, clear = true, callback) {
+    asyncToCallback(this, this.displayObjects, callback, objects, clear)
+  }
+}
+
+export default Device

package/ICAO.js

@@ -0,0 +1,70 @@
+import Plugin from './Plugin.js'
+import { BASE_URL } from './Common.js'
+
+/**
+ * ICAO
+ * @classdesc Class for invoking ICAO checks on an image
+ *
+ * @see {@link CanonScanner}
+ */
+class ICAO extends Plugin {
+  /**
+   * Instantiate an ICAO plugin
+   * @constructor
+   * @param {string} [baseURL] - Protocol, domain, and port for the service.
+   * @param {string|object} plugin - The ID of the desired plugin to use for
+   * this instance or an existing Plugin object. The plugin must support the
+   * "icao" method.
+   *
+   * @example
+   * const icao = new ICAO('capture_verify_iface')
+   */
+  constructor (plugin, baseUrl = BASE_URL) {
+    super(plugin, baseUrl)
+  }
+
+  /**
+   * Check the ICAO compliance of an image
+   * @param {string} image - A base64 encoded image.
+   *
+   * @param {string|bool} [crop] - If falsy image will not be cropped, otherwise
+   * the value will be interpreted as the preferred crop method which will vary
+   * by plugin implementation.
+   *
+   * @returns {object} Results of the ICAO check, this may vary by plugin
+   * implementation.
+   *
+   * @async
+   * @example
+   * // Take a photo with a Canon Camera and perform ICAO checks on the
+   * // returned image
+   * const camera = new CanonCamera()
+   * const photo = await camera.takePhoto('base64')
+   * const icao = new ICAO('capture_verify_iface')
+   * const results = await icao.check(photo)
+   * const img = document.createElement('img')
+   * img.src = 'data:image/jpeg;base64,' + results.cropped
+   * console.log(`found ${result.faces_found} faces in the image`)
+   * document.body.appendChild(img)
+   */
+  async check (image, cropMethod = false) {
+    const body = {
+      base64: image,
+      crop: Boolean(cropMethod),
+      crop_method: cropMethod || undefined
+    }
+    const options = {
+      method: 'POST',
+      mode: 'cors',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(body)
+    }
+    const url = `${this.baseUrl}/plugin/${this.id}/icao`
+    const response = await fetch(url, options)
+    return await response.json()
+  }
+}
+
+export default ICAO