{"id":28257829,"url":"https://github.com/chriscarrollsmith/epson-connect-js","last_synced_at":"2026-03-11T13:19:47.521Z","repository":{"id":182104337,"uuid":"667655897","full_name":"chriscarrollsmith/epson-connect-js","owner":"chriscarrollsmith","description":"A JavaScript library for interacting with the Epson Connect API","archived":false,"fork":false,"pushed_at":"2025-12-25T03:52:33.000Z","size":684,"stargazers_count":5,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-26T17:30:42.259Z","etag":null,"topics":["api","epson","javascript","printing","scanning","sdk"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/epson-connect-js","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chriscarrollsmith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-18T02:42:26.000Z","updated_at":"2025-12-25T03:52:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"e6e17f0e-b5b5-4f88-87b6-53d4b3021528","html_url":"https://github.com/chriscarrollsmith/epson-connect-js","commit_stats":null,"previous_names":["chriscarrollsmith/epson-connect-js"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/chriscarrollsmith/epson-connect-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriscarrollsmith%2Fepson-connect-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriscarrollsmith%2Fepson-connect-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriscarrollsmith%2Fepson-connect-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriscarrollsmith%2Fepson-connect-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chriscarrollsmith","download_url":"https://codeload.github.com/chriscarrollsmith/epson-connect-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chriscarrollsmith%2Fepson-connect-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30382670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T12:49:11.341Z","status":"ssl_error","status_checked_at":"2026-03-11T12:46:41.342Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","epson","javascript","printing","scanning","sdk"],"created_at":"2025-05-20T00:14:09.160Z","updated_at":"2026-03-11T13:19:47.515Z","avatar_url":"https://github.com/chriscarrollsmith.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Epson Connect JS\n\nA JavaScript library for interacting with the Epson Connect API. This library provides a set of methods for authentication and various printer and scanner functionalities.\n\n## Installation\n\n### From npm\n\nTo install using the `npm` package manager, use:\n\n```bash\nnpm install epson-connect-js\n```\n\n### From the Github repo\n\nTo install from Github, use:\n\n```bash\nnpm install https://github.com/chriscarrollsmith/epson-connect-js.git#main\n```\n\nHere's what it will look like as a dependency in `package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"epson-connect-js\": \"github:chriscarrollsmith/epson-connect-js#main\",\n  }\n}\n```\n\n## Usage\n\nThis 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.\n\n### Client\n\nIn your JavaScript files, `import` or `require` the `Client` module from the library as follows:\n\n```javascript\nconst { Client } = require('epson-connect-js');\n```\n\nYou 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](https://www.epsondevelopers.com/api/epson-connect/) 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.)\n\n```javascript\n  // printerEmail, clientId, and clientSecret must be obtained from Epson\n  const printerEmail = 'printerid@someemail.com' \n  const clientId = 'someclientid'\n  const clientSecret = 'someclientsecret'\n  const baseUrl = 'https://api.epsonconnect.com'\n\n  // If no baseUrl is provided, the default will be 'https://api.epsonconnect.com'\n  const client = new Client(printerEmail, clientId, clientSecret, baseUrl); \n  ```\n\nThe `initialize()` method of the `Client` class is responsible for initiating the authentication process, and it must be awaited, as it's an asynchronous operation.\n\n```javascript\n(async () =\u003e {\n  // Initiate the authentication process\n  await client.initialize();\n\n  // Now that we're authenticated, we can scan, print, and deauthenticate here\n})();\n```\n\nAlternatively, 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:\n\n```javascript\n// Construct the client as part of application startup\nconst client = new Client(printerEmail, clientId, clientSecret, baseUrl);\n\n// Save the initialization promise for later use\nconst initializePromise = client.initialize().catch((error) =\u003e {\n  console.error('Error initializing client:', error);\n});\n\n// Later in your code, you might have a function triggered by a user action\nasync function handlePrintRequest() {\n  // Wait for the client to finish initializing before attempting to print\n  await initializePromise;\n\n  // Now that we're authenticated, we can scan, print, and deauthenticate here\n}\n```\n\nOnce 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.\n\nFor example:\n\n```javascript\n// Get the printer and scanner from the client\nconst printer = client.printer;\nconst scanner = client.scanner;\n\n// Use printer or scanner to perform printing/scanning operations here\n```\n\nWhen 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.\n\n```javascript\n// When the application is about to close or no longer needs the client, you can deauthenticate\nawait client.deauthenticate()\n```\n\n### Printer\n\nThe `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.\n\nBefore you can utilize the printer methods, make sure you have an initialized `Client` instance.\n\n```javascript\n(async () =\u003e {\n  const client = new Client(printerEmail, clientId, clientSecret, baseUrl); \n  await client.initialize();\n})();\n```\n\nThen, get the `Printer` instance:\n\n```javascript\nconst printer = client.printer;\n```\n\nYou 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:\n\n#### Handle a Complete Print Operation with a Single Method\n\nThe 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:\n\n```javascript\n// Set the path of the file to print\nconst filePath = './path/to/file.pdf'\n\n// Define your print job settings\nlet settings = {\n  job_name: \"MyFirstPrintJob\",\n  print_mode: \"document\",\n  print_setting: {\n    media_size: \"ms_a4\",\n    media_type: \"mt_plainpaper\",\n    borderless: false,\n    print_quality: \"normal\",\n    source: \"auto\",\n    color_mode: \"color\",\n    two_sided: \"none\",\n    reverse_order: false,\n    copies: 1,\n    collate: true\n  }\n};\n\n// Execute the print operation\nconst jobId = await printer.print(filePath, settings)\n```\n\nThis method returns a `jobId` which can be used to get information about the print job or cancel the print job (see below).\n\n#### Getting Printer Info\n\nTo get general information about the printer, use the `info()` method:\n\n```javascript\nconst response = await printer.info()\n```\n\n#### Retrieve Printer Capabilities\n\nTo retrieve the printer capabilities, use the `capabilities(mode)` method, where the `mode` argument is either 'document' or 'photo':\n\n```javascript\nconst response = printer.capabilities(mode='document')\n```\n\n#### Setting Up Print Job\n\nTo 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. \n\nThen call the printSetting method and capture the response.\n\n```javascript\n// Use the printer instance to set up a print job and capture the jobData object\nconst jobData = await printer.printSetting(settings)\n```\n\nNote 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.\n\nThe `settings` object can contain the following parameters:\n\n- `job_name`: The name of the print job. If not set, a default name will be generated.\n- `print_mode`: The print mode which can be either 'document' or 'photo'. Defaults to 'document'.\n- `print_setting`: An object containing specific settings for the print job.\n\nThe `print_setting` object can contain:\n\n- `media_size`: The size of the paper. Default is 'ms_a4'.\n- `media_type`: The type of paper. Default is 'mt_plainpaper'.\n- `borderless`: Whether or not the print should be borderless. Default is false.\n- `print_quality`: The quality of the print. Can be 'high', 'normal', or 'draft'. Default is 'normal'.\n- `source`: The paper source. Default is 'auto'.\n- `color_mode`: The color mode. Can be 'color' or 'mono'. Default is 'color'.\n- `two_sided`: The two-sided mode. Can be 'none', 'long', or 'short'. Default is 'none'.\n- `reverse_order`: Whether or not to print in reverse order. Default is false.\n- `copies`: The number of copies to print. Default is 1.\n- `collate`: Whether or not to collate when printing multiple copies. Default is true. Must be true when using two-sided printing.\n\nThe 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.\n\n#### Uploading File to Print\n\nTo upload a file to be printed, use the `uploadFile(uploadUri, filePath, printMode)` method, where printMode is 'document' or 'photo':\n\n```javascript\nconst uploadUri = jobData.upload_uri\nconst filePath = '/path/to/file.jpg'\nconst printMode = 'photo'\n\nawait printer.uploadFile(uploadUri, filePath, printMode)\n```\n\n#### Executing Print Job\n\nTo execute a print job, use the `executePrint(jobId)` method\n\n```javascript\nconst response = await printer.executePrint(jobId=jobData.id)\n```\n\n#### Getting Print Job Info\n\nTo 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.\n\n```javascript\nconst response = await printer.jobInfo(jobData.id)\n```\n\n#### Cancelling Print Job\n\nTo cancel a print job, use the `cancelPrint(jobId, operatedBy)` method:\n\n```javascript\nawait printer.cancelPrint(jobId=jobData.upload_uri, operatedBy='user')\n```\n\n#### Setting Up Notifications\n\nTo set up notifications for printer events, use the `notification(callbackUri, enabled)` method:\n\n```javascript\nconst callbackUri = 'http://example.com/webhook'\nconst enabled = true\n\nawait printer.notification(callbackUri, enabled)\n```\n\nThe notification HTTP body will look like this:\n\n```json\n{ \n \"Param\": { \n  \"JobId\": \"d318caa88966442faaee090f858aef35\", \n  \"JobStatus\": { \n    \"Status\": \"Pending\", \n    \"StatusReason\": \"JobQueued\", \n    \"UpdateDate\": \"2021/08/06 06:42:13\" \n  } \n } \n}\n```\n\nThis functionality has not yet been tested. We welcome your contributions to improve it or to add unit tests.\n\n### Scanner\n\nDocuments 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:\n\n```javascript\nconst scanner = client.scanner;\nscanner.list();\nscanner.add(name, destination, type);\nscanner.update(id, name, destination, type);\nscanner.remove(id);\n```\n\nOnce 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.\n\n## Error Handling\n\nThe library defines a set of custom error types (`ClientError`, `AuthenticationError`, `ApiError`, `PrinterError`, `PrintSettingError`, `ScannerError`) to provide detailed error information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchriscarrollsmith%2Fepson-connect-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchriscarrollsmith%2Fepson-connect-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchriscarrollsmith%2Fepson-connect-js/lists"}