i-repo-sdk

ConMas i-Reporter 外部連携 Web API の TypeScript SDK。

インストール

npm install i-repo-sdk

ローカルパスからインストールする場合:

npm install /path/to/i-repo-sdk

動作環境: Node.js 18 以上

クイックスタート（v1 Public API）

import { IReporterClient } from "i-repo-sdk";

const client = new IReporterClient({
  apiEndpoint: "https://your-server.example.com/ConMasAPI/Rests/APIExecute.aspx",
  credentials: { user: "admin", password: "password" },
});

const reports = await client.reports.list({ editStatus: "4" });
for await (const report of client.reports.listAll({ editStatus: "4" })) {
  console.log(report.itemId, report.editStatus);
}

設定

const client = new IReporterClient({
  apiEndpoint: "https://example.com/ConMasAPI/Rests/APIExecute.aspx", // 必須
  credentials: { user: "admin", password: "password" }, // 指定時は API 呼び出しで自動ログイン
  timeout: 60000,             // タイムアウト ms（デフォルト: 30000）
  signal: abortController.signal, // 中断用 AbortSignal（任意）
});

認証

credentials を渡すと、API 呼び出し時に未ログインなら自動でログインします。明示的に切り替えたい場合のみ login / logout を使います。

// credentials なしで使う場合
await client.login({ user: "admin", password: "password" });
const defs = await client.definitions.list({});
await client.logout();

v1 API

• 公開API: client.definitions, client.reports, client.systems, client.definitionBatches, client.reportBatches
• v1 では旧 command 直結APIと legacy 名前空間は提供しません

API リファレンス

帳票定義（client.definitions）

// 定義一覧を取得
const defs = await client.definitions.list({
  labelId: "-9",          // ラベル指定（-9 = 全階層）
  publicStatus: "2",      // 公開ステータス（2 = 公開）
  word: "日報",           // 検索キーワード
  wordTargetName: true,   // 名前を検索対象に含む
});

// 定義の詳細を取得
const detail = await client.definitions.get({
  definitionId: "DEF001",
});

// 定義をロック/アンロック
await client.definitions.lock({ definitionId: "DEF001" });
await client.definitions.unlock({ definitionId: "DEF001" });

// 権限ファイルの取得・登録
const role = await client.definitions.downloadRoles({
  definitionId: "DEF001",
});
await client.definitions.updateRoles({
  dataFile: roleData,
  dataFileName: "role.csv",
});

// ラベルの取得・登録
const label = await client.definitions.downloadLabels({
  definitionId: "DEF001",
});
await client.definitions.updateLabels({
  dataFile: labelData,
  dataFileName: "label.csv",
});

// 帳票ラベル定義の取得・登録
const reportLabel = await client.definitions.downloadReportLabels({
  definitionId: "DEF001",
});
await client.definitions.updateReportLabels({
  dataFile: reportLabelData,
  dataFileName: "report-label.csv",
});

帳票定義バッチ（client.definitionBatches）

// セレクトアイテム更新
const result = await client.definitionBatches.updateSelectItems({
  dataFile: csvData,
  dataFileName: "select-items.csv",
  encoding: "65001", // UTF-8
});

// 定義削除
const deleteResult = await client.definitionBatches.delete({
  definitionId: "DEF001",
});

// トランザクションモード（一括処理）
const txResult = await client.definitionBatches.delete({
  definitionId: "DEF001",
  transactionMode: "1",
});

帳票（client.reports）

// 帳票一覧を取得
const reports = await client.reports.list({
  labelId: "-9",
  editStatus: "4",       // 入力完了のみ
  word: "検査",
});

// 帳票の詳細を取得
const detail = await client.reports.get({
  topId: "RPT001",
});

// 帳票をロック/アンロック
await client.reports.lock("RPT001");
await client.reports.unlock("RPT001");

// 帳票をコピー
const copied = await client.reports.copy({
  topId: "RPT001",
  labelId: "LABEL001",
});

// 帳票ファイルをダウンロード
const file = await client.reports.downloadFile({
  topId: "RPT001",
});

// クラスタ値の取得
const cluster = await client.reports.getClusterValue({
  topId: "RPT001",
});

// ソート済み帳票を生成
const sortedIds = await client.reports.createSorted({
  topId: "RPT001",
});

帳票バッチ（client.reportBatches）

import { readFileSync } from "node:fs";

// CSV で帳票を自動生成
const csvData = readFileSync("reports.csv");
const result = await client.reportBatches.generate({
  type: "csv",
  dataFile: csvData,
  dataFileName: "reports.csv",
  encoding: "932", // Shift_JIS
});

// 簡易 CSV で帳票を自動生成
const simpleResult = await client.reportBatches.generateSimpleCsv({
  type: "csv",
  dataFile: csvData,
  dataFileName: "simple.csv",
  encoding: "65001", // UTF-8
});

// 帳票を更新
const updateResult = await client.reportBatches.update({
  type: "csv",
  dataFile: csvData,
  dataFileName: "update.csv",
});

// 帳票をダウンロード
const { data, contentType } = await client.reportBatches.download({
  definition: "DEF001",
  withPDF: "true",
  encoding: "65001",
});

// CSV ダウンロード
const csv = await client.reportBatches.downloadCsv({
  definition: "DEF001",
  encoding: "65001",
});

// 帳票一覧 CSV ダウンロード
const viewCsv = await client.reportBatches.downloadViewCsv({
  definition: "DEF001",
  encoding: "65001",
});

// 結合 PDF ダウンロード
const pdf = await client.reportBatches.downloadMergedPdf({
  topId: "RPT001",
});

// 帳票削除
const deleteResult = await client.reportBatches.delete({
  topId: "RPT001",
});

// バインダー作成
const binder = await client.reportBatches.createBinder({
  topId: "RPT001",
  binderName: "検査結果まとめ",
});

システム管理（client.systems）

// ユーザー管理
const users = await client.systems.getUsers({ encoding: "65001" });
await client.systems.registerUsers({
  dataFile: userData,
  dataFileName: "users.csv",
});

// グループ管理
const groups = await client.systems.getGroups({ encoding: "65001" });
await client.systems.registerGroups({
  dataFile: groupData,
  dataFileName: "groups.csv",
});

// グループ所属
const affiliations = await client.systems.getGroupAffiliations({
  encoding: "65001",
});
await client.systems.registerGroupAffiliations({
  dataFile: affiliationData,
  dataFileName: "affiliations.csv",
});

// ラベルマスター
const defLabels = await client.systems.getDefinitionLabelMasters({
  encoding: "65001",
});
const rptLabels = await client.systems.getReportLabelMasters({
  encoding: "65001",
});

// 端末一覧
const terminals = await client.systems.getTerminals({ encoding: "65001" });

// URL スキーム取得
const scheme = await client.systems.getUrlScheme();

// ラベル削除
await client.systems.deleteLabel({
  labelId: "LABEL001",
  target: "definition",
});

定数・列挙値

import {
  EditStatus,
  PublicStatus,
  ItemType,
  FileType,
  Encoding,
  ErrorCode,
} from "i-repo-sdk";

// 編集ステータス
EditStatus.BeforeInput;     // "0" - 入力前
EditStatus.Editing;         // "1" - 編集中
EditStatus.WaitingApproval; // "2" - 承認待ち
EditStatus.Rejected;        // "3" - 差し戻し
EditStatus.Completed;       // "4" - 入力完了
EditStatus.Applying;        // "5" - 申請中

// 公開ステータス
PublicStatus.Test;          // "1" - テスト
PublicStatus.Published;     // "2" - 公開

// エンコーディング
Encoding.SJIS;              // "932"
Encoding.UTF8;              // "65001"

// ファイルタイプ
FileType.XML;               // "xml"
FileType.CSV;               // "csv"
FileType.XMLZip;            // "xmlZip"
FileType.CSVZip;            // "csvZip"

エラーハンドリング

import {
  IReporterError,
  ApiError,
  AuthenticationError,
  SessionError,
  HttpError,
  NetworkError,
} from "i-repo-sdk";

try {
  await client.login({ user: "admin", password: "wrong" });
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.error("認証失敗:", e.message, "コード:", e.code);
  } else if (e instanceof SessionError) {
    console.error("セッションなし:", e.message);
  } else if (e instanceof ApiError) {
    console.error("APIエラー:", e.message, "コード:", e.code, "備考:", e.remarks);
  } else if (e instanceof HttpError) {
    console.error("HTTPエラー:", e.status, e.statusText);
  } else if (e instanceof NetworkError) {
    console.error("ネットワークエラー:", e.message);
  }
}

エラークラスの階層:

IReporterError
├── ApiError          - API がエラーコードを返した
├── AuthenticationError - ログイン失敗
├── SessionError      - 未ログイン状態で API 呼び出し
├── HttpError         - HTTP ステータスエラー
├── XmlParseError     - XML パース失敗
└── NetworkError      - ネットワーク/タイムアウト

使用例

完了済み帳票の一覧をCSVで取得

import { IReporterClient, Encoding } from "i-repo-sdk";
import { writeFileSync } from "node:fs";

const client = new IReporterClient({
  apiEndpoint: "https://ireporter.example.com/ConMasAPI/Rests/APIExecute.aspx",
  credentials: { user: "admin", password: "password" },
});

const { data } = await client.reportBatches.downloadCsv({
  definition: "DEF001",
  editStatus: "4",
  encoding: Encoding.UTF8,
});

writeFileSync("reports.csv", Buffer.from(data));
console.log("CSV を保存しました");

帳票を CSV から一括生成

import { IReporterClient, Encoding } from "i-repo-sdk";
import { readFileSync } from "node:fs";

const client = new IReporterClient({
  apiEndpoint: "https://ireporter.example.com/ConMasAPI/Rests/APIExecute.aspx",
  credentials: { user: "admin", password: "password" },
});

const csvData = readFileSync("input.csv");

const result = await client.reportBatches.generate({
  type: "csv",
  dataFile: csvData,
  dataFileName: "input.csv",
  encoding: Encoding.SJIS,
  labelMode: "1",
  thumbnailUpdate: "1",
});

console.log("生成結果:", result);

定義一覧を検索してPDFダウンロード

import { IReporterClient, PublicStatus } from "i-repo-sdk";
import { writeFileSync } from "node:fs";

const client = new IReporterClient({
  apiEndpoint: "https://ireporter.example.com/ConMasAPI/Rests/APIExecute.aspx",
  credentials: { user: "admin", password: "password" },
});

// 公開中の定義を検索
const defs = await client.definitions.list({
  publicStatus: PublicStatus.Published,
  word: "点検",
  wordTargetName: true,
});

console.log(`${defs.length} 件の定義が見つかりました`);

for (const def of defs) {
  console.log(`- ${def.definitionName} (${def.definitionId})`);
}

// 最初の定義の帳票を PDF 付きでダウンロード
if (defs.length > 0) {
  const { data } = await client.reportBatches.download({
    definition: defs[0].definitionId,
    withPDF: "true",
    encoding: Encoding.UTF8,
  });

  writeFileSync("reports.zip", Buffer.from(data));
  console.log("ダウンロード完了");
}

ユーザー・グループの管理

import { IReporterClient, Encoding } from "i-repo-sdk";
import { writeFileSync } from "node:fs";

const client = new IReporterClient({
  apiEndpoint: "https://ireporter.example.com/ConMasAPI/Rests/APIExecute.aspx",
  credentials: { user: "admin", password: "password" },
});

// ユーザー一覧を取得
const { data: userData } = await client.systems.getUsers({
  encoding: Encoding.UTF8,
});
writeFileSync("users.csv", Buffer.from(userData));

// グループ一覧を取得
const { data: groupData } = await client.systems.getGroups({
  encoding: Encoding.UTF8,
});
writeFileSync("groups.csv", Buffer.from(groupData));

console.log("ユーザー・グループ情報を保存しました");

リクエストのキャンセル

const controller = new AbortController();

const client = new IReporterClient({
  apiEndpoint: "https://ireporter.example.com/ConMasAPI/Rests/APIExecute.aspx",
  credentials: { user: "admin", password: "password" },
  signal: controller.signal,
});

// 5秒後にキャンセル
setTimeout(() => controller.abort(), 5000);

try {
  const reports = await client.reports.list({});
  console.log(reports);
} catch (e) {
  if (e instanceof NetworkError) {
    console.log("リクエストがキャンセルされました");
  }
}

サブパスインポート

型やコアモジュールを個別にインポートできます。

// 型のみ
import type { IReporterConfig, Credentials } from "i-repo-sdk/types";

// コアユーティリティ
import { parseXml, BaseApi } from "i-repo-sdk/core";

ライセンス

MIT