epson-connect-js v1.0.6

Epson Connect JS

A JavaScript library for interacting with the Epson Connect API. This library provides a set of methods for authentication and various printer and scanner functionalities.

Installation

From npm

To install using the npm package manager, use:

npm install epson-connect-js

From the Github repo

To install from Github, use:

npm install https://github.com/chriscarrollsmith/epson-connect-js.git#main

Here's what it will look like as a dependency in package.json:

{
  "dependencies": {
    "epson-connect-js": "github:chriscarrollsmith/epson-connect-js#main",
  }
}

Usage

This library provides a set of classes that correspond to the different aspects of the Epson Connect API. The Client class is the primary interface for interacting with the API, and it manages authentication and provides access to printer and scanner functionality. The Printer and Scanner classes provide methods for interacting with the printer and scanner functionalities of the API respectively. Please ensure you have a good understanding of the asynchronous nature of JavaScript to effectively use this library, as many operations rely on Promises and should be properly awaited or handled.

Client

In your JavaScript files, import or require the Client module from the library as follows:

const { Client } = require('epson-connect-js');

You will need to construct an object of the Client class with the arguments printerEmail, clientId, clientSecret. Alternatively, you can set the environment variables EPSON_CONNECT_API_PRINTER_EMAIL,EPSON_CONNECT_API_CLIENT_ID, and EPSON_CONNECT_API_CLIENT_SECRET. Note that you will have to register for a license with the Epson Connect API in order to obtain these credentials. (The baseUrl argument of the Client class is optional, and if not provided, the default value of https://api.epsonconnect.com will be used.)

  // printerEmail, clientId, and clientSecret must be obtained from Epson
  const printerEmail = 'printerid@someemail.com' 
  const clientId = 'someclientid'
  const clientSecret = 'someclientsecret'
  const baseUrl = 'https://api.epsonconnect.com'

  // If no baseUrl is provided, the default will be 'https://api.epsonconnect.com'
  const client = new Client(printerEmail, clientId, clientSecret, baseUrl); 

The initialize() method of the Client class is responsible for initiating the authentication process, and it must be awaited, as it's an asynchronous operation.

(async () => {
  // Initiate the authentication process
  await client.initialize();

  // Now that we're authenticated, we can scan, print, and deauthenticate here
})();

Alternatively, to speed up execution, you can save the returned Promise directly with .catch() and await it later in your code. This is useful if you want to authenticate at application startup but you don't need to use the printer or scanner until later. For example:

// Construct the client as part of application startup
const client = new Client(printerEmail, clientId, clientSecret, baseUrl);

// Save the initialization promise for later use
const initializePromise = client.initialize().catch((error) => {
  console.error('Error initializing client:', error);
});

// Later in your code, you might have a function triggered by a user action
async function handlePrintRequest() {
  // Wait for the client to finish initializing before attempting to print
  await initializePromise;

  // Now that we're authenticated, we can scan, print, and deauthenticate here
}

Once you've constructed and initialized an object of the Client class, you can use its printer and scanner properties as getters that return instances of the Printer and Scanner classes, providing various methods to interact with the printing and scanning functionalities of the Epson Connect API.

For example:

// Get the printer and scanner from the client
const printer = client.printer;
const scanner = client.scanner;

// Use printer or scanner to perform printing/scanning operations here

When the application is about to close or no longer needs the client, you can deauthenticate. The deauthenticate() method clears any active authentication sessions, and it also should be awaited, as it's also asynchronous.

// When the application is about to close or no longer needs the client, you can deauthenticate
await client.deauthenticate()

Printer

The Printer class offers a suite of methods that enable interactions with an Epson printer. It is typically accessed via the printer getter of a Client instance.

Before you can utilize the printer methods, make sure you have an initialized Client instance.

(async () => {
  const client = new Client(printerEmail, clientId, clientSecret, baseUrl); 
  await client.initialize();
})();

Then, get the Printer instance:

const printer = client.printer;

You can now interact with the printer. Remember, each printer method returns a promise which should be properly handled to ensure error situations are adequately addressed. Use then-catch or async-await with a try-catch block to handle the promises. Here are some examples:

Handle a Complete Print Operation with a Single Method

The simplest way to execute a complete print operation, including setting up the print job, uploading the file, and executing the print job, is the print(filePath, settings) method:

// Set the path of the file to print
const filePath = './path/to/file.pdf'

// Define your print job settings
let settings = {
  job_name: "MyFirstPrintJob",
  print_mode: "document",
  print_setting: {
    media_size: "ms_a4",
    media_type: "mt_plainpaper",
    borderless: false,
    print_quality: "normal",
    source: "auto",
    color_mode: "color",
    two_sided: "none",
    reverse_order: false,
    copies: 1,
    collate: true
  }
};

// Execute the print operation
const jobId = await printer.print(filePath, settings)

This method returns a jobId which can be used to get information about the print job or cancel the print job (see below).

Getting Printer Info

To get general information about the printer, use the info() method:

const response = await printer.info()

Retrieve Printer Capabilities

To retrieve the printer capabilities, use the capabilities(mode) method, where the mode argument is either 'document' or 'photo':

const response = printer.capabilities(mode='document')

Setting Up Print Job

To set up a print job, you need to define a settings object which contains your printer settings, as shown in the section above titled 'Handle a Complete Print Operation with a Single Method'. Each setting has default values that are automatically applied if not explicitly set. We also have validation in place to ensure your settings are correct and will be accepted by the printer.

Then call the printSetting method and capture the response.

// Use the printer instance to set up a print job and capture the jobData object
const jobData = await printer.printSetting(settings)

Note that calling printSetting before printing is mandatory, and that you must capture the jobData returned by the printSetting call for use in other functions. jobData is an object that contains id, upload_uri, and settings properties. The id property is a unique job ID, and the upload_uri property is the URI to which you will upload the file to be printed for this job. The settings property is the settings object you passed in, but with any default values applied.

The settings object can contain the following parameters:

• job_name: The name of the print job. If not set, a default name will be generated.
• print_mode: The print mode which can be either 'document' or 'photo'. Defaults to 'document'.
• print_setting: An object containing specific settings for the print job.

The print_setting object can contain:

• media_size: The size of the paper. Default is 'ms_a4'.
• media_type: The type of paper. Default is 'mt_plainpaper'.
• borderless: Whether or not the print should be borderless. Default is false.
• print_quality: The quality of the print. Can be 'high', 'normal', or 'draft'. Default is 'normal'.
• source: The paper source. Default is 'auto'.
• color_mode: The color mode. Can be 'color' or 'mono'. Default is 'color'.
• two_sided: The two-sided mode. Can be 'none', 'long', or 'short'. Default is 'none'.
• reverse_order: Whether or not to print in reverse order. Default is false.
• copies: The number of copies to print. Default is 1.
• collate: Whether or not to collate when printing multiple copies. Default is true. Must be true when using two-sided printing.

The validation process ensures that all settings are in acceptable formats and values. If the validation fails, a PrintSettingError will be thrown. Handle this error appropriately in your implementation.

Uploading File to Print

To upload a file to be printed, use the uploadFile(uploadUri, filePath, printMode) method, where printMode is 'document' or 'photo':

const uploadUri = jobData.upload_uri
const filePath = '/path/to/file.jpg'
const printMode = 'photo'

await printer.uploadFile(uploadUri, filePath, printMode)

Executing Print Job

To execute a print job, use the executePrint(jobId) method

const response = await printer.executePrint(jobId=jobData.id)

Getting Print Job Info

To get the information about a print job you've executed, use the jobInfo(jobId) method. Note that this endpoint will only work after you've executed a print job.

const response = await printer.jobInfo(jobData.id)

Cancelling Print Job

To cancel a print job, use the cancelPrint(jobId, operatedBy) method:

await printer.cancelPrint(jobId=jobData.upload_uri, operatedBy='user')

Setting Up Notifications

To set up notifications for printer events, use the notification(callbackUri, enabled) method:

const callbackUri = 'http://example.com/webhook'
const enabled = true

await printer.notification(callbackUri, enabled)

The notification HTTP body will look like this:

{ 
 "Param": { 
  "JobId": "d318caa88966442faaee090f858aef35", 
  "JobStatus": { 
    "Status": "Pending", 
    "StatusReason": "JobQueued", 
    "UpdateDate": "2021/08/06 06:42:13" 
  } 
 } 
}

This functionality has not yet been tested. We welcome your contributions to improve it or to add unit tests.

Scanner

Documents scanned with the Epson Connect API can be either uploaded to a url (such as a cloud storage bucket) or delivered to an email. The Scanner class provides methods for adding, updating, removing, and fetching a list of scanner destinations:

const scanner = client.scanner;
scanner.list();
scanner.add(name, destination, type);
scanner.update(id, name, destination, type);
scanner.remove(id);

Once you have added at least one destination, the destination will be available to select from the control panel of the physical scanner. If you select a destination and scan a document, the scanned document will be delivered to the selected destination.

Error Handling

The library defines a set of custom error types (ClientError, AuthenticationError, ApiError, PrinterError, PrintSettingError, ScannerError) to provide detailed error information.