@capturebridge/sdk 0.7.0

package/IFace.js

@@ -0,0 +1,274 @@
+import ICAO from './ICAO.js'
+import { BASE_URL, blobToBase64 } from './Common.js'
+
+// This is not exported as we may eventually detect this from the plugin
+// See: Iface.matchModes()
+const VALID_MODES = ['accurate', 'balanced', 'fast', 'accurate_server']
+
+/**
+ * Probe
+ * @classdesc Probe Class for Innovatrics IFace SDK
+ *
+ * @see {@link IFace}
+ */
+export class Probe {
+  source
+  url
+  imageData
+  /**
+   * Instantiate an IFace Probe
+   * @constructor
+   * @param {string} source - The image source for the probe.
+   * @param {string} [type] - The type of data in the image source, valid values
+   * are 'url', 'base64', and 'dataurl'. If not provided 'base64' is the default.
+   *
+   * @example
+   * const candidate = new Candidate('/person/123.jpg', '123', 'url')
+   */
+  constructor (source, type = 'base64') {
+    // TODO:
+    // If the source is typeof object and/or type=object we should do some duck
+    // typing and accept any of...
+    // - The result of an ICAO check that contains a cropped image
+    // - An Image tag (fetch the source)
+    // - A Blob
+    // - An Array Buffer
+    // - An object that has a fullCapture method (call function in .data())
+    switch (type) {
+      case 'url':
+        this.url = source
+        break
+      case 'base64':
+        this.imageData = source
+        break
+      case 'dataurl':
+        this.imageData = source.split(',')[1]
+        break
+      case undefined:
+      case null:
+      default:
+        throw new Error('Invalid image source type provided')
+    }
+  }
+
+  /**
+   * Fetch the image data and base64 encode it
+   * @async
+   * @example
+   * const probe = new Probe("/img/photo.jpg")
+   * await probe.data()
+   * console.log(probe.imageData)
+   */
+  async data () {
+    if (!this.imageData) {
+      const response = await fetch(this.url)
+      const blob = await response.blob()
+      this.imageData = await blobToBase64(blob)
+    }
+  }
+
+  toJSON () {
+    return this.imageData
+  }
+}
+
+/**
+ * Candidate
+ * @classdesc Candidate Class for Innovatrics IFace SDK
+ *
+ * @see {@link IFace}
+ */
+export class Candidate extends Probe {
+  id
+
+  // TODO: Support setting different modes on individual candidates
+  // an example usecase for this is to set 'accurate_server' the most recent
+  // photo, and 'fast' for the remaining set (since they likely have already
+  // been verified at some point) In the plugin we would have to re-template the
+  // probe for each additional mode and it doesn't make sense to do so until
+  // the plugin is checking each photo against the probe in a separate thread.
+  mode
+
+  /**
+   * Instantiate an IFace Candidate
+   * @constructor
+   * @param {string} source - The image source for the candidate.
+   * @param {string} id - The ID for the candidate when the match results are
+   * returned this Id will be returned with it's respective results.
+   * @param {string} [type] - The type of data in the image source, valid values
+   * are 'url', 'base64', and 'dataurl'. If not provided 'base64' is the default.
+   *
+   * @example
+   * const candidate = new Candidate('/person/123.jpg', '123', 'url')
+   */
+  constructor (source, id, type = 'base64') {
+    super(source, type)
+    if (id) {
+      this.id = id
+    } else {
+      throw new Error('Candidate ID not provided')
+    }
+  }
+
+  toJSON () {
+    return {
+      id: this.id,
+      base64: this.imageData
+    }
+  }
+}
+
+/**
+ * IFace
+ * @classdesc Class for Innovatrics IFace SDK
+ *
+ */
+export class IFace extends ICAO {
+  /**
+   * Instantiate an IFace plugin
+   * @constructor
+   * @param {string} [baseURL] - Protocol, domain, and port for the service.
+   *
+   * @example
+   * const iface = new IFace()
+   */
+  constructor (baseUrl = BASE_URL) {
+    super('capture_verify_iface', baseUrl)
+  }
+
+  /**
+   * Return list of available face matching modes
+   *
+   * @returns {string[]} List of available face matching modes
+   *
+   * @async
+   * @example
+   * const iface = new IFace()
+   * const modes = await iface.matchModes()
+   * // do something with modes, such as build a <select> element
+   * const select = document.createElement('select')
+   * modes.forEach(mode => {
+   *   const option = document.createElement('option')
+   *   option.value = mode
+   *   select.appendChild(mode)
+   * })
+   * document.body.appendChild(select)
+   */
+  async matchModes () {
+    // This is async as we may later get this from the plugin at runtime
+    return VALID_MODES
+  }
+
+  matchModesHandler (callback) {
+    callback(null, VALID_MODES)
+  }
+
+  /**
+   * 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 iface = new IFace()
+   * const results = await iface.icao(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 icao (image, cropMethod = false) {
+    return await this.check(image, cropMethod)
+  }
+
+  /**
+   * Perform a facial match against one or more photos.
+   *
+   * @param {object|string} probe - Either a Probe object or a base64 encoded
+   * image that is being compared or searched against one or more candidates
+   *
+   * @param {object[]} candidates - An array of candidate objects against which
+   * the probe photo is compared.
+   * @param {string} candidates[].id - Id of the photo, when the results of the
+   * matched are returned, this id will be returned so results can be matched
+   * back to their original image. Must be less than 16 characters.
+   * @param {string} candidates[].base64 - Base64 encoded string containing the
+   * photo.
+   * @param {string} [candidates[].mode] - Matching mode to use for this photo.
+   * If left unspecified will use the mode provided in the mode parameter.
+   *
+   * @param {string} [mode=fast] - Matching mode to use for all images, can be
+   * overriden on each candidate if desired. Valid values are: 'accurate',
+   * 'balanced', 'fast', and 'accurate_server'.
+   *
+   * @async
+   * @example
+   * // Create an iface object
+   * const iface = new IFace()
+   *
+   * // Obtain a photo for the probe photo
+   * const probe = await camera.takePhoto('base64')
+   *
+   * // Create a candidate set from the person's previous photos
+   * const candidates = [
+   *   new Candidate('/person/1/photo/2.jpg', '3', 'url'),
+   *   new Candidate('/person/1/photo/1.jpg', '2', 'url')
+   * ]
+   *
+   * // Match the probe to all the candidates using the 'balanced' mode
+   * const results = await iface.match(probe, candidates, 'balanced')
+   *
+   * // use the results
+   * console.log(results)
+   */
+  async match (probe, candidates, mode = 'fast') {
+    if (VALID_MODES.indexOf(mode) === -1) {
+      throw new Error('Invalid mode provided')
+    }
+
+    // If this is a Probe object fetch it's image data
+    if (typeof probe === 'object' && probe.constructor.name === 'Probe') {
+      await probe.data()
+    }
+
+    // And fetch data for candidates
+    const asyncOperations = candidates.map(async candidate => {
+      if (typeof candidate === 'object' &&
+        candidate.constructor.name === 'Candidate') {
+        await candidate.data()
+      }
+    })
+
+    // Wait for all async operations to complete
+    await Promise.all(asyncOperations)
+
+    const body = {
+      probe,
+      mode,
+      candidates
+    }
+    const options = {
+      method: 'POST',
+      mode: 'cors',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(body)
+    }
+    const url = `${this.baseUrl}/plugin/${this.id}/face/match`
+    const response = await fetch(url, options)
+    return await response.json()
+  }
+}
+
+export default IFace

package/Logs.js

@@ -0,0 +1,129 @@
+import { BASE_URL } from './Common.js'
+
+export const TRACE = 10
+export const DEBUG = 20
+export const INFO = 30
+export const WARN = 40
+export const ERROR = 50
+export const FATAL = 60
+
+/**
+ * @constant
+ * @type {Object.<string, number>}
+ *
+ */
+export const LOG_LEVELS = {
+  trace: TRACE,
+  debug: DEBUG,
+  info: INFO,
+  warn: WARN,
+  error: ERROR,
+  fatal: FATAL
+}
+
+/**
+ * @classdesc Plugins write
+ * {@link https://github.com/trentm/node-bunyan?tab=readme-ov-file#log-record-fields|Bunyan}
+ * formated logs to separate log files. This class provides
+ * utilities for viewing and following those logs as they're written.
+ */
+export class Logs {
+  baseUrl
+  #reader
+  #controller
+  /**
+   * Instantiate a Log Object
+   * @constructor
+   * @param {string} [baseURL] - Protocol, domain, and port for the service.
+   */
+  constructor (baseUrl = BASE_URL) {
+    this.baseUrl = baseUrl
+  }
+
+  /**
+   * End the log stream and stop following logs.
+   */
+  end () {
+    this.#reader?.cancel()
+    this.#controller?.abort()
+  }
+
+  /**
+   * Add a handler for following logs. Note that each invocation of this method
+   * opens a connection to the server and holds it open. Web browsers limit the
+   * number of connections to a single domain. Avoid using this method more than
+   * once per client.
+   * @param {string[]} plugins - Follow logs for the provided Plugin IDs.
+   * @param {string|number} level - Log Level.
+   * @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 log object.
+   */
+  follow (plugins, level, callback) {
+    let pluginList
+    if (typeof plugins === 'object' && plugins.length > 0) {
+      pluginList = plugins.join(',')
+    } else {
+      throw new Error('Invalid value provided for plugins argument')
+    }
+
+    const logLevel = (typeof level === 'number') ? level : LOG_LEVELS[level]
+
+    if (!logLevel) {
+      throw new Error('Invalid value provided for log level argument')
+    }
+
+    if (typeof callback !== 'function') {
+      throw new Error('Invalid value provided for callback argument')
+    }
+
+    const url = `${this.baseUrl}/plugin/logs/follow?plugins=${pluginList}&level=${logLevel}`
+
+    this.#controller = new AbortController()
+    const signal = this.#controller.signal
+
+    fetch(url, { signal })
+      .then(({ body }) => {
+        let buffer = ''
+        if (!body) {
+          return callback(new Error('No response body'))
+        }
+        const readData = data => {
+          if (!data.done) {
+            callback(null, data.value)
+            this.#reader.read().then(readData).catch(e => callback(e))
+          }
+        }
+        this.#reader = body
+          .pipeThrough(new TextDecoderStream())
+          .pipeThrough(new TransformStream({
+            transform (chunk, controller) {
+              buffer += chunk
+              const parts = buffer.split('\n')
+              parts.slice(0, -1).forEach(part => controller.enqueue(part))
+              buffer = parts[parts.length - 1]
+            },
+            flush (controller) {
+              if (buffer) {
+                controller.enqueue(buffer)
+              }
+            }
+          }))
+          .pipeThrough(new TransformStream({
+            transform (chunk, controller) {
+              controller.enqueue(JSON.parse(chunk))
+            }
+          }))
+          .getReader()
+        this.#reader
+          .read()
+          .then(readData)
+          .catch(e => callback(e))
+      }).catch(e => {
+        // Don't emit an error when aborting the fetch operation
+        if (e.name !== 'AbortError') {
+          callback(e)
+        }
+      })
+  }
+}

package/MockCamera.js

@@ -0,0 +1,10 @@
+import Camera from './Camera.js'
+import { BASE_URL } from './Common.js'
+
+class MockCamera extends Camera {
+  constructor (baseUrl = BASE_URL) {
+    super('capture_camera_mock', baseUrl)
+  }
+}
+
+export default MockCamera

package/Plugin.js

@@ -0,0 +1,298 @@
+import Device from './Device.js'
+
+import { BASE_URL, DELETE, asyncToCallback } from './Common.js'
+
+/**
+ * @classdesc CaptureBridge utilizes a plugin system for interacting with
+ * hardware devices and vendor SDKs. Clients will interact with plugins via the
+ * REST API using their unique plugin ID. This class provides basic methods
+ * for working with these plugins such as obtaining a list of compatible devices
+ * and managing the plugin's configuration.
+ *
+ * @see {@link CaptureBridge#plugins} Get all installed plugin.
+ * @see {@link CaptureBridge#plugin} Get a single plugin by ID.
+ */
+class Plugin {
+/**
+ * @property {string} id - ID of the plugin, used when building REST endpoint paths.
+ * @property {string} name - Human friendly name for the plugin.
+ * @property {string} description - Human friendly description of plugin.
+ * @property {string} version - {@link https://semver.org/|Semantic version} version of the plugin.
+ * @property {string[]} methods - A plugin's list of supported RPC methods.
+ * @property {boolean} ready - True if plugin has been loaded into memory and is ready to receive requests.
+ * @property {object} defaultDevice - Default device to use for the plugin.
+ * @property {string[]} configMethods - Methods required to implement configuration.
+ */
+  baseUrl
+  id
+  name
+  description
+  version
+  methods = []
+  ready = false
+  defaultDevice = null
+  configMethods = ['config_schema', 'get_config', 'set_config']
+
+  /**
+   * Instantiate a plugin.
+   * @constructor
+   * @param {object|string} plugin - plugin object as received from the API or a plugin ID string.
+   * @param {string} plugin.id - ID of the plugin, used when building endpoint paths to call methods on the plugin.
+   * @param {string} plugin.name - Human friendly name of plugin.
+   * @param {string} plugin.description - Human friendly description of plugin.
+   * @param {string} plugin.version - {@link https://semver.org/|Semantic version} version of the plugin.
+   * @param {string[]} plugin.methods - plugin's capabilities.
+   * @param {boolean} plugin.ready - True if plugin has been loaded into memory and is ready.
+   * @param {string} [baseURL=BASE_URL] - Override the default protocol, domain, and port for the service.
+   * @throws Will throw an Error the plugin argument is not a plugin ID (String) or an object.
+   */
+  constructor (plugin, baseUrl = BASE_URL) {
+    this.baseUrl = baseUrl
+    if (typeof plugin === 'string') {
+      this.id = plugin
+    } else if (typeof plugin === 'object') {
+      Object.assign(this, {}, plugin)
+    } else {
+      throw new Error('Invalid properties supplied to Plugin constructor')
+    }
+  }
+
+  /**
+   * Get all devices for this plugin
+   *
+   * @method
+   * @async
+   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
+   * @returns {object[]} Array of {@link Device} objects.
+   * @example
+   * const plugin = await captureBridge.plugin('capture_camera_canon')
+   * const devices = await plugin.devices()
+   */
+  async devices () {
+    const response = await fetch(`${this.baseUrl}/plugin/${this.id}/device`)
+    const devices = await response.json()
+    return devices.map(d => new Device(d, this, this.baseUrl))
+  }
+
+  /**
+   * Get all Devices for this plugin
+   *
+   * @method
+   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
+   * @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 Device} objects. If no devices are available the second
+   * argument will be an empty Array.
+   * @example
+   * captureBridge.pluginHandler('capture_camera_canon', (error, plugin) => {
+   *   plugin.devicesHandler((error, devices) => console.log(devices))
+   * })
+   */
+  devicesHandler (callback) {
+    asyncToCallback(this, this.devices, callback)
+  }
+
+  /**
+   * Get a device by ID for this plugin
+   *
+   * @method
+   * @async
+   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
+   * @param {string} id - Device ID
+   * @returns {object?} Requested {@link Device} or null
+   * @example
+   * const plugin = await captureBridge.plugin('capture_camera_canon')
+   * const device = await plugin.device('AWOOO56709')
+   */
+  async device (id) {
+    const response = await fetch(`${this.baseUrl}/plugin/${this.id}/device`)
+    const devices = await response.json()
+    const device = devices.find(d => d.id === id)
+    return device ? new Device(device, this, this.baseUrl) : null
+  }
+
+  /**
+   * Get a Device by ID for this plugin
+   * @method
+   * @see {@link https://capture.local.valididcloud.com:9001/doc/#api-Plugin-GetPluginDevices|API Endpoint (/plugin/:pluginId/device)}
+   * @param {string} id - Device 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
+   * a {@link Device} object. If the requested device is not available the
+   * second argument will be null.
+   * @example
+   * captureBridge.pluginHandler('capture_camera_canon', (error, plugin) => {
+   *   plugin.deviceHandler('AWOOO56709', (error, device) => console.log(device))
+   * })
+   */
+  deviceHandler (id, callback) {
+    asyncToCallback(this, this.device, callback, id)
+  }
+
+  async configSchema () {
+    if (!await this.supportsConfig()) {
+      throw new Error('Plugin does not support config')
+    }
+    const response = await fetch(`${this.baseUrl}/plugin/${this.id}/config/schema`)
+    return await response.json()
+  }
+
+  configSchemaHandler (callback) {
+    asyncToCallback(this, this.configSchema, callback)
+  }
+
+  async config () {
+    if (!await this.supportsConfig()) {
+      throw new Error('Plugin does not support config')
+    }
+    const response = await fetch(`${this.baseUrl}/plugin/${this.id}/config`)
+    return await response.json()
+  }
+
+  configHandler (callback) {
+    asyncToCallback(this, this.config, callback)
+  }
+
+  async saveConfig (config) {
+    if (!await this.supportsConfig()) {
+      throw new Error('Plugin does not support config')
+    }
+    const options = {
+      method: 'POST',
+      mode: 'cors',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(config)
+    }
+    const url = `${this.baseUrl}/plugin/${this.id}/config`
+    const response = await fetch(url, options)
+    return await response.json()
+  }
+
+  async saveConfigHandler (config, callback) {
+    asyncToCallback(this, this.saveConfig, callback, config)
+  }
+
+  async supportsConfig () {
+    await this.update()
+    return this.configMethods.every(m => this.methods.includes(m))
+  }
+
+  supportsConfigHandler (callback) {
+    asyncToCallback(this, this.configHandler, callback)
+  }
+
+  async shutdown () {
+    const url = `${this.baseUrl}/plugin/${this.id}`
+    const response = await fetch(url, DELETE)
+    return await response.json()
+  }
+
+  shutdownHandler (callback) {
+    asyncToCallback(this, this.shutdown, callback)
+  }
+
+  async startup () {
+    // See: ValidRD/wa_capture_bridge/issues/48
+    // We need an explicit endpoint for this instead
+    const devices = await this.devices()
+    if (devices) {
+      await this.update(true)
+      return { status: 'starting' }
+    }
+    return { status: 'failed' }
+  }
+
+  startupHandler (callback) {
+    asyncToCallback(this, this.startup, callback)
+  }
+
+  /**
+   * This class can be instantiated from either a plugin ID or a full plugin
+   * object from an API request.
+   * Because constructors cannot be async we use this method to hydrate the
+   * plugin properties if needed.
+   *
+   * @private
+   * @method
+   */
+  async update (force = false) {
+    if (force || this.methods.length === 0) {
+      const response = await fetch(`${this.baseUrl}/plugin`)
+      const plugins = await response.json()
+      const plugin = plugins.find(p => p.id === this.id)
+      Object.assign(this, plugin)
+    }
+  }
+
+  updateHandler (force = false, callback) {
+    asyncToCallback(this, this.update, callback, force)
+  }
+
+  async rpc (request) {
+    const options = {
+      method: 'POST',
+      mode: 'cors',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(request)
+    }
+    const url = `${this.baseUrl}/plugin/${this.id}/rpc`
+    const response = await fetch(url, options)
+    return await response.json()
+  }
+
+  rpcHandler (request, callback) {
+    asyncToCallback(this, this.rpc, callback, request)
+  }
+
+  async ping () {
+    const response = await fetch(`${this.baseUrl}/plugin/${this.id}/ping`)
+    return await response.json()
+  }
+
+  pingHandler (callback) {
+    asyncToCallback(this, this.ping, callback)
+  }
+
+  /**
+   * Classes that extend this one will add their own methods to perform
+   * operations on a device. They will call this method first to get a device
+   * object to use for making calls to the appropriate endpoint.
+   *
+   * This method really should be "protected" in classical OOP terms but
+   * Javascript does not currently have support for such scopes, and it's not
+   * marked using the ES6 private modifier so that it can be inherited by it's
+   * children.
+   * @private
+   * @method
+   */
+  async setupDevice (deviceOpt) {
+    await this.update()
+
+    if (deviceOpt instanceof Device) {
+      this.defaultDevice = deviceOpt
+      return this.defaultDevice
+    }
+
+    if (typeof deviceOpt === 'string') {
+      this.defaultDevice = this.device(deviceOpt)
+      return this.defaultDevice
+    }
+
+    if (!this.defaultDevice) {
+      const devices = await this.devices()
+      if (!devices.length) {
+        throw new Error('No devices found for the plugin')
+      }
+      this.defaultDevice = devices[0]
+      return this.defaultDevice
+    }
+
+    return this.defaultDevice
+  }
+}
+
+export default Plugin