@joymerrevent/porters-connect

PORTERS Connect API（旧 HRBC）を TypeScript から型安全・簡単に扱うための、 Joymerrevent（ジョイメリベント） 製の 非公式（unofficial） ラッパーです。

[!IMPORTANT] これは非公式ライブラリです。ポーターズ株式会社とは無関係で、公式ロゴ・商標は使用していません。 利用には PORTERS の契約 ＋ Connect API オプション契約が必要です（ホスト名・App ID/Secret は契約時に通知されます）。

XML レスポンスを型付きオブジェクトに変換し、独自仕様の OAuth・レート制御・エラー整理を内側に隠します。 薄く・堅くを方針に、フェイルセーフ（壊れたときに安全側へ倒れる）設計です。

特徴

• 型安全：リソース・項目の値を型で表現。any を撒きません。
• XML を外に出さない：返り値は型付きオブジェクト、入力も素直な JS の値。
• 独自 OAuth を透過：code_direct によるトークン取得・キャッシュ・更新を自動化。
• 上限内に自制する：スロットリング・リトライ（指数バックオフ）・リクエストサイズガード内蔵。
• 日時は ISO 8601（UTC）に正規化。業務タイムゾーン変換はしません（利用側の責務）。
• PORTERS の全リソースに対応：データ系 13 種（Phase・Attachment を含む）＋ マスタ Read 5 種。

前提

繋ぐ前に、PORTERS 側で 4 つが要ります。揃っていないと 1 行も動きません。

1. PORTERS 契約 ＋ Connect API オプション契約（オプションは別契約）。
2. API アプリの登録。ここで Redirect URL を決め、ホスト名・App ID・App Secret が 通知されます（いずれも機密情報・ハードコード禁止）。
3. 初回のみブラウザで権限付与（人手・Company DB ごとに 1 回）。以降はライブラリが code_direct（サーバ間）で無人運用します。
4. 付与するスコープの決定（リソース別に _r / _w。Read でも複数要ることがあります）。

揃えかたは始める前にに、権限付与の手順は認証を通して、疎通を確認するに あります。実行環境は Node.js 22.12 以上で、型定義は同梱です。配るのは ESM 1 本ですが、 CJS からも require("@joymerrevent/porters-connect") で読めます（CJS から使う）。

契約や権限付与を待っている間も、PORTERS に繋がずにコードとテストは書けます （契約なしでテストを書きたい）。

インストール

npm i @joymerrevent/porters-connect
# pnpm add @joymerrevent/porters-connect
# yarn add @joymerrevent/porters-connect

最短で動かす

import { PortersClient } from "@joymerrevent/porters-connect";

const porters = new PortersClient({
  hostname: process.env.PORTERS_HOST ?? "", // 契約時に通知される値。ハードコード禁止
  appId: process.env.PORTERS_APP_ID ?? "",
  appSecret: process.env.PORTERS_APP_SECRET ?? "",
});

// partition（Company DB）は tenant で一度だけ束ねる。**単一テナントでもこの形**
const t = porters.tenant(456);

const page = await t.candidate.search({
  field: ["P_Id", "P_Name", "P_UpdateDate"], // 省略時は標準項目（P_）が全部返る
  condition: { P_Name: { part: "山田" } }, // part = 部分一致 / full = 完全一致
  order: [{ P_UpdateDate: "desc" }],
  count: 50, // 1 ページ最大 200
});

console.log(page.total, page.items[0]?.P_Name);

続きは入門（6 ページ）へ。準備・認証・読み取り・書き込み・本番に出す前の確認まで順に進みます。

リソースと操作

| アクセサ | リソース | アクセサ | リソース | | --------------- | -------------- | -------------- | ------------ | | t.candidate | 個人連絡先 | t.contract | 契約 | | t.job | JOB | t.sales | 成約・売上 | | t.client | 企業 | t.process | 選考プロセス | | t.recruiter | 企業担当者 | t.resume | レジュメ | | t.contact | コンタクト | t.attachment | 添付ファイル | | t.opportunity | 商談管理 | t.phase | フェーズ履歴 | | t.activity | アクティビティ | | |

マスタ Read は porters.partition / t.user / t.department / t.field / t.option の 5 種（読み取り専用）。

どのメソッドが呼べるかはリソースごとに違います（searchAll が無いもの、先に of() で 束ねるものがあります）。一覧はリソースと操作、引数・戻り値・項目の一覧は API リファレンスが正典です。

ドキュメント

docs/usage が目次です。4 層に分かれています。

| 層 | 何が書いてあるか | | ---------------- | ---------------------------------------------------------------------------------- | | 入門 | 順に読む 6 ページ。準備 → 導入 → 認証と疎通 → 読み → 書き → 本番前 | | 目的別 | 「〜したい」から引く 9 ページ（検索・一括書き込み・添付・同期バッチ・テスト ほか） | | 考え方 | PORTERS 固有の前提（Partition ／ alias と Data Type ／ UTC ／ 削除が無い ／ 上限） | | リファレンス | 公開 API の全記号（JSDoc から生成）と PORTERS API の事実 |

PORTERS 固有の注意

このライブラリを使ううえで、PORTERS 側の前提として先に知っておくと迷いません。詳しくは それぞれの「考え方」ページにあります。

• 削除 API が存在しない。delete() は型の上でも生やしていません（削除 API が無いということ）。
• 日時は UTC 前提。ISO 8601（…Z）で入出力し、JST 等への変換はしません（日時は UTC）。
• データは Partition に分かれる。tenant(id) で毎回束ねます（Partition とテナント）。
• 上限がある。リクエスト長 約 15000 文字・1 リクエスト 200 件・1 分あたり Read 2000 / Write 500 は ライブラリが自制しますが、月 15 万アクセスは契約条件で利用側の運用責務です（上限）。
• ホスト名は非公開。PORTERS_HOST で受け取り、ハードコードしません。

対応バージョン

• 契約は Connect API Version 2：X-P-ConnectAPI-Version: 2 を既定送信し、v2 を動作の前提とします（担当者型・部署型 Link 等は v2 必須）。互換性はこの API version で明示します。
• PORTERS 製品 8.x / 9.x は参考：v2 が提供される製品世代です（個別マイナーの動作保証はしません）。正典は PORTERS API の事実（実 API ドキュメントに接地）。

リンク

この README は「最短で動かす」ところまでです。網羅は目次側が担当します。

• 利用者向け：docs/usage（目次）／公開 API の全記号／PORTERS API の事実
• 開発・保守：docs/README.md（ADR・基本設計・ロードマップ・台帳への入口）
• 提供元：Joymerrevent

コントリビュート / セキュリティ

• バグ報告・要望・質問は Issues へ（外部からの提案は Issue 経由・PR 作成はコラボレーター限定）。詳しくは CONTRIBUTING。
• 脆弱性は公開 Issue ではなく セキュリティポリシー の手順で非公開で報告してください。
• 行動規範：Contributor Covenant。

念のため：本ライブラリは非公式です。PORTERS 製品・Connect API 本体の不具合や要望は PORTERS 公式へお願いします。

ライセンス

MIT © Joymerrevent