epson-connect-ts

Epson Connect API の TypeScript クライアント。

ランタイム依存ゼロ（Node.js 18+ のネイティブ fetch を使用）。型定義付きで、印刷・スキャンまわりの操作を型安全に扱えます。

Install

npm install epson-connect-ts

Quick Start

import { Client } from "epson-connect-ts";

const client = new Client({
  printerEmail: "[email protected]",
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
});

await client.initialize();

// PDF を印刷
const jobId = await client.printer.print("./invoice.pdf");
console.log(`Job ID: ${jobId}`);

環境変数でも設定できます。

export [email protected]
export EPSON_CONNECT_API_CLIENT_ID=your-client-id
export EPSON_CONNECT_API_CLIENT_SECRET=your-client-secret

const client = new Client(); // 環境変数から自動読み込み
await client.initialize();

Usage

印刷（シンプル）

// デフォルト設定で PDF を印刷
const jobId = await client.printer.print("./report.pdf");

印刷（設定付き）

const jobId = await client.printer.print("./photo.jpg", {
  print_mode: "photo",
  print_setting: {
    media_size: "ms_l",
    media_type: "mt_photopaper",
    print_quality: "high",
    borderless: true,
    color_mode: "color",
  },
});

印刷（ステップごと）

アップロードの進捗表示などが必要な場合は、ステップを分けて実行できます。

const printer = client.printer;

// 1. ジョブ作成
const job = await printer.printSetting({
  print_setting: { copies: 3, two_sided: "long" },
});

// 2. ファイルアップロード
await printer.uploadFile(job.upload_uri, "./doc.pdf", job.settings.print_mode);

// 3. 印刷実行
await printer.executePrint(job.id);

ジョブ管理

// ジョブ状態を確認
const info = await client.printer.jobInfo(jobId);
console.log(info.status); // "pending" | "pending_held" | "printing" | ...

// ジョブをキャンセル（pending / pending_held のみ）
await client.printer.cancelPrint(jobId);

プリンター情報

// プリンター情報
const info = await client.printer.info();

// 対応機能を取得
const caps = await client.printer.capabilities("document");

Webhook 通知

// 通知を有効化
await client.printer.notification("https://your-server.com/webhook");

// 通知を無効化
await client.printer.notification("https://your-server.com/webhook", false);

スキャナー（宛先管理）

const scanner = client.scanner;

// 宛先一覧
const { destinations } = await scanner.list();

// 宛先を追加
const dest = await scanner.add("Office", "[email protected]", "mail");

// 宛先を更新
await scanner.update(dest.id, "Office (updated)");

// 宛先を削除
await scanner.remove(dest.id);

// キャッシュから取得（API リクエストなし）
const cached = await scanner.list(true);

切断

await client.deauthenticate();

Print Settings

print / printSetting にはオプションで設定を渡せます。すべて省略可能で、省略時はデフォルト値が適用されます。

| フィールド | 型 | デフォルト | 選択肢 | |---|---|---|---| | job_name | string | job-xxxxxxxx | 任意（256 文字以内） | | print_mode | PrintMode | document | document photo |

print_setting:

| フィールド | 型 | デフォルト | 選択肢 | |---|---|---|---| | media_size | MediaSize | ms_a4 | ms_a3 ms_a4 ms_a5 ms_a6 ms_b5 ms_tabloid ms_letter ms_legal ms_halfletter ms_kg ms_l ms_2l ms_10x12 ms_8x10 ms_hivision ms_5x8 ms_postcard | | media_type | MediaType | mt_plainpaper | mt_plainpaper mt_photopaper mt_hagaki mt_hagakiphoto mt_hagakiinkjet | | borderless | boolean | false | — | | print_quality | PrintQuality | normal | high normal draft | | source | PaperSource | auto | auto rear front1 front2 front3 front4 | | color_mode | ColorMode | color | color mono | | two_sided | TwoSided | none | none long short | | reverse_order | boolean | false | — | | copies | number | 1 | 1–99 | | collate | boolean | true | — |

Supported File Types

doc docx xls xlsx ppt pptx pdf jpeg jpg bmp gif png tiff

Error Handling

各モジュール別のエラークラスが用意されています。

import {
  ClientError,
  AuthenticationError,
  ApiError,
  PrinterError,
  PrintSettingError,
  ScannerError,
} from "epson-connect-ts";

try {
  await client.printer.print("./file.pdf");
} catch (e) {
  if (e instanceof AuthenticationError) {
    // 認証エラー（トークン失効など）
  } else if (e instanceof PrinterError) {
    // 印刷固有のエラー
  } else if (e instanceof ApiError) {
    // API レスポンスエラー
  }
}

Requirements

• Node.js >= 18（ネイティブ fetch を使用）
• Epson Connect API のアカウントとクレデンシャル

License

MIT