@capturebridge/sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.9.0] - 2024-06-06
+
+### Added
+
+- Introduced Changelog.
+- Add Verifone class and examples (features signature capture support for the M450)
+- Add `format` parameter to `DEFAULT_CAPTURE_OPT` (defaults to `null` which will
+  use the plugin's default image format.)
+- Add `CaptureResponseFormat` type definition to documentation.
+
+### Fixed
+
+- Fix bug where `null` would be sent for some URL parameters.
+
+[0.9.0]: https://www.npmjs.com/package/@capturebridge/sdk/v/0.9.0

package/Common.js

@@ -75,6 +75,25 @@ export const DEFAULT_STREAM_OPT = {
  *
  */
 
+/**
+ * @typedef {string} CaptureResponseFormat
+ * @summary The image format to be returned.
+ *
+ * Valid values:
+ *
+ *  - `jpg`
+ *  - `tiff`
+ *
+ * If not provided, a plugin or device-specific format will be returned.
+ *
+ * **Note:**
+ *  - Some plugins have configuration options for specifying the return format,
+ * such configuration options should be used instead of this parameter to
+ * prevent unecessary transcoding.
+ * - Web browsers are not typically capable of displaying TIFF images.
+ *
+ */
+
 /**
  * @summary Default options for capture operations.
  * @constant
@@ -87,11 +106,14 @@ export const DEFAULT_STREAM_OPT = {
  * 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.
+ * @property {CaptureResponseFormat} format - The image format to be returned.
+ *
  * @typedef {object} CaptureOptions
  */
 export const DEFAULT_CAPTURE_OPT = {
   rotate: 0,
   base64: false,
+  format: null,
   kind: 'objecturl'
 }
 
@@ -175,6 +197,22 @@ export const checkResponse = async (response) => {
   }
 }
 
+/**
+ * Helper function to convert a key/value map to a string, removing any items
+ * that are null or undefined (instead of converting them to a string which
+ * URLSearchParams().toString() will do.)
+ * @private
+ */
+export const urlParamsToString = (params) => {
+  const filtered = {}
+  Object.keys(params).forEach(key => {
+    if (params[key] !== null && params[key] !== undefined) {
+      filtered[key] = params[key]
+    }
+  })
+  return new URLSearchParams(filtered).toString()
+}
+
 /**
  * Allows passing in a string for the response type of capture methods
  * @private

package/Device.js

@@ -6,7 +6,8 @@ import {
   DEFAULT_CAPTURE_OPT,
   checkResponse,
   timeout,
-  asyncToCallback
+  asyncToCallback,
+  urlParamsToString
 } from './Common.js'
 
 /**
@@ -42,12 +43,27 @@ class Device {
     Object.assign(this, {}, properties)
   }
 
+  /**
+   * Will throw an exception if a plugin cannot perform the provided RPC command
+   * @param {string} method - The JSON RPC method to check.
+   */
   can (method) {
     if (this.plugin.methods.indexOf(method) === -1) {
       throw new Error(`${method} not supported for this device`)
     }
   }
 
+  /**
+   * Will throw an exception if the plugin cannot performa at least one of the
+   * provided JSON RPC commandss
+   * @param {string[]} methods - The JSON RPC methods to check.
+   */
+  canDoOne (methods) {
+    if (!methods.some(m => this.plugin.methods.includes(m))) {
+      throw new Error(`Device does not support any of the methods: ${methods.join(',')}`)
+    }
+  }
+
   /**
    * Get the stream endpoint URL.
    *
@@ -106,7 +122,7 @@ class Device {
     // Method ignores kind, always returns an object URL
     delete captureParams.kind
 
-    const params = new URLSearchParams(captureParams).toString()
+    const params = urlParamsToString(captureParams)
     const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture?${params}`
     const response = await fetch(url, POST)
     return await response.blob()
@@ -141,7 +157,7 @@ class Device {
     // Method ignores kind, always returns binary data (blob)
     delete captureParams.kind
 
-    const params = new URLSearchParams(captureParams).toString()
+    const params = urlParamsToString(captureParams)
     const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture?${params}`
     const response = await fetch(url, POST)
     return await response.blob()
@@ -200,7 +216,7 @@ class Device {
     delete captureParams.kind
     captureParams.base64 = true
 
-    const params = new URLSearchParams(captureParams).toString()
+    const params = urlParamsToString(captureParams)
     const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/capture?${params}`
     const response = await fetch(url, POST)
     await checkResponse(response)
@@ -262,7 +278,7 @@ class Device {
     delete captureParams.kind
     captureParams.base64 = true
 
-    const params = new URLSearchParams(captureParams).toString()
+    const params = urlParamsToString(captureParams)
     const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/livefeed?${params}`
     const response = await fetch(url)
     const result = await response.json()
@@ -352,7 +368,7 @@ class Device {
     // Method ignores kind, always returns binary data (blob)
     delete captureParams.kind
 
-    const params = new URLSearchParams(captureParams).toString()
+    const params = urlParamsToString(captureParams)
     const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/livefeed?${params}`
     const result = await this.frameAsBase64(captureOpt, millis)
     if (typeof result === 'string') {
@@ -459,7 +475,7 @@ class Device {
    * console.log(await await device.clear())
    */
   async clear (backlight) {
-    this.can('draw')
+    this.canDoOne(['draw', 'clear'])
     let url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/display`
     if (typeof backlight === 'boolean') {
       url += `?backlight=${backlight}`
@@ -542,6 +558,38 @@ class Device {
   async displayObjectsHandler (objects, clear = true, callback) {
     asyncToCallback(this, this.displayObjects, callback, objects, clear)
   }
+
+  /**
+   * Get detailed information about a device
+   *
+   * @description Returns detailed information about a device.
+   *
+   * @async
+   * @method
+   * @returns {object} Device info
+   * @example
+   * const info = await device.info()
+   */
+  async info () {
+    this.can('device_info')
+    const url = `${this.baseUrl}/plugin/${this.plugin.id}/device/${this.id}/info`
+    const response = await fetch(url)
+    return await response.json()
+  }
+
+  /**
+   * Get detailed information about a device
+   *
+   * @description Returns detailed information about a device.
+   *
+   * @method
+   * @returns {object} Device info
+   * @example
+   * const info = await device.info()
+   */
+  async infoHandler (callback) {
+    asyncToCallback(this, this.info, callback)
+  }
 }
 
 export default Device

package/Verifone.js

@@ -0,0 +1,68 @@
+import SignatureTablet from './SignatureTablet.js'
+import { BASE_URL } from './Common.js'
+
+/**
+ * Verifone
+ * @classdesc Captures a signature on Verifone device.
+ * @extends SignatureTablet
+ * @see {@link SignatureTablet}
+ */
+class Verifone extends SignatureTablet {
+  /**
+   * Instantiate a Verifone Class
+   * @constructor
+   * @param {string} [baseURL] - Protocol, domain, and port for the service.
+   * @example
+   * const tablet = new Verifone()
+   *
+   */
+  constructor (baseUrl = BASE_URL) {
+    super('capture_signature_verifone', baseUrl)
+  }
+
+  /**
+   * Not currently supported for this plugin.
+   * @throws Not implemented error
+   * @example
+   * // Not currently supported for this plugin
+   * @override
+   */
+  async streamUrl () {
+    throw new Error('streamUrl() is not implemented for the Verifone Plugin')
+  }
+
+  /**
+   * Not currently supported for this plugin.
+   * @throws Not implemented error
+   * @example
+   * // Not currently supported for this plugin
+   * @override
+   */
+  async getMostRecentFrame () {
+    throw new Error('getMostRecentFrame() is not implemented for the Verifone Plugin')
+  }
+
+  /**
+   * Not currently supported for this plugin.
+   * @throws Not implemented error
+   * @example
+   * // Not currently supported for this plugin
+   * @override
+   */
+  async stopFeed () {
+    throw new Error('stopFeed() is not implemented for the Verifone Plugin')
+  }
+
+  /**
+   * Not currently supported for this plugin.
+   * @throws Not implemented error
+   * @example
+   * // Not currently supported for this plugin
+   * @override
+   */
+  async displayObjects () {
+    throw new Error('displayObjects() is not implemented for the Verifone Plugin')
+  }
+}
+
+export default Verifone

package/Version.js

@@ -4,5 +4,5 @@
  * @constant
  * @type {string}
  */
-const VERSION = '0.8.0'
+const VERSION = '0.9.0'
 export default VERSION

package/examples/verifone_minimal.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html>
+<head><title>Verifone Minimal Example</title></head>
+<body>
+<script type="module">
+import Verifone from '/sdk/js/Verifone.js'
+(async () => {
+  try {
+    const tablet = new Verifone()
+
+    const img = document.createElement('img')
+    img.src = await tablet.signature({format: 'jpg'})
+    await tablet.clear()
+    document.body.appendChild(img)
+
+  } catch (e) {
+    console.error(e)
+    alert(`Error: ${e.message}`)
+  }
+})()
+</script>
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capturebridge/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Capture Bridge JavaScript SDK for web applications",
   "type": "module",
   "license": "Apache-2.0"