Excella STX Scanner support for Node.js

A Node.js library for interfacing with MagTek's Excella STX check scanner. This library provides easy-to-use methods for scanning checks and IDs, extracting MICR data, and retrieving images.

Installation

npm install --save excella-scanner

Configuration

The library supports configuration through environment variables:

• MAGTEK_SCAN_URL - Scanner endpoint URL (default: /Excella?DeviceScan)
• MAGTEK_DEFAULT_PORT - Default scanner port (default: 80)
• MAGTEK_REQUEST_TIMEOUT - Request timeout in milliseconds (default: 30000)

Usage

Assuming your scanner is configured with IP address 192.168.1.23 and you scan the following check:

const Scanner = require('excella-scanner');

const scanner = new Scanner('192.168.1.23', 80);
const data = await scanner.readCheck(true);

/***
 data {
    error:          false,
    routing:        '123456789',
    account:        '123456789',
    number:         '000001012',
    frontimage:     '/chkimage/FRONT100COL24_1.JPG',
    backimage:      '/chkimage/BACK100COL24_2.JPG',
    frontimagedata: <Buffer ...>,
    backimagedata:  <Buffer ...>
  }
***/

Error Handling

try {
  const data = await scanner.readCheck(true);
  console.log('Check scanned successfully:', data.routing);
} catch (error) {
  console.error('Failed to scan check:', error.message);
}

API

Scanner Class

Constructor

new Scanner(host, port) Creates a new instance of the Scanner object.

Parameters:

• host (string, required) - IP address, hostname, or FQDN of the scanner
• port (number, optional) - Scanner port (default: 80 or MAGTEK_DEFAULT_PORT)

Throws: Error if host is not provided or is not a string

Methods

readCheck(includeImages = false)

Causes the scanner to read the current check and return the MICR information, potentially also returning the images.

Parameters:

• includeImages (boolean, default: false) - Whether to include image data in the response

Returns: Promise that resolves to an object with the following properties:

• error (boolean) - If true, the scanner cannot confirm that the information is accurate
• routing (string) - The MICR routing number
• account (string) - The MICR account number
• number (string) - The MICR check number
• frontimage (string) - The path for the front side image
• backimage (string) - The path for the back side image
• frontimagedata (Buffer|null) - JPG data of the front side (if includeImages=true)
• backimagedata (Buffer|null) - JPG data of the back side (if includeImages=true)

Throws: Error if the scan operation fails

readID(includeImage = false)

Causes the scanner to read the current ID and return the image information.

Parameters:

• includeImage (boolean, default: false) - Whether to include image data in the response

Returns: Promise that resolves to an object with the following properties:

• frontimage (string) - The path for the front side image
• imagedata (Buffer|null) - JPG data of the front side (if includeImage=true)

Throws: Error if the scan operation fails

readStatus()

Reads the current status of the scanner device.

Returns: Promise that resolves to an object with device status information including:

• AccessGuide (string) - Access guide status
• AutoFeeder (string) - Auto feeder status
• Ink (string) - Ink status
• Lamp1 (string) - Lamp 1 status
• Lamp2 (string) - Lamp 2 status
• ManualFeeder (string) - Manual feeder status
• Path (string) - Path status
• Printer (string) - Printer status
• State (string) - Overall device state

Throws: Error if the status read operation fails

readImage(imagePath)

Retrieves an image from the scanner by its path.

Parameters:

• imagePath (string) - The path to the image on the scanner

Returns: Promise that resolves to a Buffer containing the image data

Throws: Error if the image retrieval fails

Examples

Basic Check Scanning

const scanner = new Scanner('192.168.1.23');
const data = await scanner.readCheck();
console.log(`Routing: ${data.routing}, Account: ${data.account}, Number: ${data.number}`);

Check Scanning with Images

const scanner = new Scanner('192.168.1.23');
const data = await scanner.readCheck(true);
// data.frontimagedata and data.backimagedata contain Buffer objects

ID Scanning

const scanner = new Scanner('192.168.1.23');
const data = await scanner.readID(true);
// data.imagedata contains the ID image as a Buffer

Scanner Status

const scanner = new Scanner('192.168.1.23');
const status = await scanner.readStatus();
console.log(`Scanner state: ${status.State}, Ink: ${status.Ink}`);

Custom Configuration

// Using environment variables
process.env.MAGTEK_REQUEST_TIMEOUT = '60000'; // 60 second timeout
const scanner = new Scanner('192.168.1.23', 8080);

Error Handling

The library throws descriptive errors for various failure scenarios:

• Invalid host configuration
• Network timeouts
• XML parsing errors
• Scanner communication failures

Always wrap scanner operations in try-catch blocks for production use.

Testing

npm test

GitHub Actions

This repository includes GitHub Actions workflows for automated testing and publishing:

CI Workflow

• Runs on every push and pull request
• Executes linting and tests
• Ensures code quality before merging

Publish Workflow

• Automatically publishes to npm when a new GitHub release is created
• Runs tests and linting before publishing
• Requires NPM_TOKEN secret to be configured

Manual Publish Workflow

• Allows manual triggering of npm publishing
• Can be used to publish specific versions
• Available in the Actions tab of the repository

Setup for npm Publishing

1. Create an npm access token:

   • Go to https://www.npmjs.com/settings/tokens
   • Create a new token with "Automation" type
   • Copy the token

2. Add the token to GitHub repository secrets:

   • Go to your repository Settings → Secrets and variables → Actions
   • Create a new secret named NPM_TOKEN
   • Paste your npm access token

3. Publish your first version:

   • Create a new GitHub release, or
   • Use the Manual Publish workflow from the Actions tab

License

MIT