@joymerrevent/porters-connect 0.24.0 → 0.26.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +239 -1
- package/README.md +51 -62
- package/dist/index.d.cts +1195 -364
- package/dist/index.d.ts +1195 -364
- package/dist/index.js +1790 -941
- package/dist/index.js.map +1 -1
- package/dist/requires-newer-typescript.d.cts +3 -1
- package/dist/requires-newer-typescript.d.ts +3 -1
- package/package.json +3 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,226 @@
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [0.26.0] - 2026-09-27
|
|
9
|
+
|
|
10
|
+
**読み取りの型を要求した項目で絞り、複数の ID でまとめて読めるようにし、`src` 全体のレビューで見つけた不具合をまとめて直した版**です。
|
|
11
|
+
**破壊的変更を 2 つ**含みます（検索クエリの型からページ送りを外したことと、読み取りの戻り値の型を要求した項目で絞ったこと）。
|
|
12
|
+
あわせて、Result Code の 5 と 113 の `category` が `unknown` から `auth` に変わります。
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
|
|
16
|
+
- **（破壊的）検索クエリの型（`SearchQuery` と `CandidateSearchQuery` などの各 `…SearchQuery`）から `count` / `start` を外し、
|
|
17
|
+
ページ送りを別の型 `Paging`（`count` / `start`）にしました**（[ADR-0099][adr99]）。`search` はクエリと `Paging` を一緒に受け取り、
|
|
18
|
+
`searchAll` はクエリだけを受け取ります。同じクエリを `search` と `searchAll` の両方に渡せます。
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
// 変更前
|
|
22
|
+
const query: CandidateSearchQuery = {
|
|
23
|
+
condition: { P_Name: { part: "山田" } },
|
|
24
|
+
count: 50,
|
|
25
|
+
};
|
|
26
|
+
// 変更後
|
|
27
|
+
const query: CandidateSearchQuery & Paging = {
|
|
28
|
+
condition: { P_Name: { part: "山田" } },
|
|
29
|
+
count: 50,
|
|
30
|
+
};
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- `t.candidate.search({ field: ["P_Name"], count: 50 })` のように、その場でオブジェクトを書いているコードはそのまま動きます。
|
|
34
|
+
- Option の `search` は件数の上限だけを受け取るので、`count` だけを持つ `Limit` を受けます（`OptionSearchQuery & Limit`）。
|
|
35
|
+
- `AttachmentWalkQuery` は無くしました。`AttachmentSearchQuery` に書き換えてください。
|
|
36
|
+
|
|
37
|
+
- **（破壊的）読み取り（`search` / `searchAll` / `get` / `getMany`）の戻り値の型が、要求した項目だけを持つようになりました**
|
|
38
|
+
（[ADR-0096][adr96]）。要求した項目とは、`field` に書いた項目と、`expand` / `image` で選んだ項目です（`get` / `getMany` では ID も）。
|
|
39
|
+
|
|
40
|
+
- `field` に書いていない項目に触るコードは型エラーになります。そうしたコードは実行時にいつも `undefined` を読んでいたので、
|
|
41
|
+
`field` に足してください。型に無い項目を読む必要があるときは `rawValue` を使います。
|
|
42
|
+
- `field` を省略したとき、または中身をコンパイラが読めない配列（`string[]` の変数など）を渡したときは、これまでどおり
|
|
43
|
+
知っている項目すべてを持つ型です。
|
|
44
|
+
- `search` / `searchAll` に `field: []` を渡したときは、項目を 1 つも持たない型になります。このとき `expand` / `image` も
|
|
45
|
+
送られません。
|
|
46
|
+
|
|
47
|
+
- **Resource の Code `5`（ユーザー ID 無効）と、Authentication の Code `113`（登録アプリのサイトが無い）の `category` が、
|
|
48
|
+
`unknown` から `auth` になりました**（[ADR-0106][adr106]）。`category` でエラーを振り分けている場合は、振る舞いが変わります。
|
|
49
|
+
再試行しないことは変わりません。`createMany` の 2 つ目以降のバッチが Code `5` で失敗したときは、そのバッチを
|
|
50
|
+
「書き込まれていない」と案内します。
|
|
51
|
+
|
|
52
|
+
- **送った後の `create` が、Code `1000`（処理失敗）・表に無いコード・HTTP 200 で本文が読めない応答で終わったときも、
|
|
53
|
+
`hint` に「登録された可能性がある」ことが書かれます**（[ADR-0106][adr106]）。これまでは、再試行できる失敗（通信の失敗、
|
|
54
|
+
Code `302` など）のときだけでした。元の `hint` があれば、その後ろに続きます。
|
|
55
|
+
|
|
56
|
+
- **送った後に失敗した `create` は、自動で再送せず `retryable: false` で届きます**（[ADR-0103][adr103]）。これまでは、接続エラーの
|
|
57
|
+
ときに `retryable: true` のまま届き、Code `302` のときは自動で再送していました（二重登録のおそれ）。`hint` に「登録された可能性が
|
|
58
|
+
ある」ことが書かれ、元のエラーは `cause` にあります。Code `9` は今までどおり再送します。
|
|
59
|
+
|
|
60
|
+
- **内蔵のスロットルは、どの 60 秒を切り取っても上限の 90%（既定）を超えない形になりました**（[ADR-0102][adr102]）。これまでは
|
|
61
|
+
起動直後の 60 秒で、Read を最大約 3600 件送ることがありました。`createThrottle` の設定は変わりません。
|
|
62
|
+
|
|
63
|
+
- **HTTP のリダイレクトを追いかけなくなりました。** これまでは 3xx の先へ Access Token や App Secret を送っていました。
|
|
64
|
+
3xx はエラーとして届き、`hint` がリダイレクトであることと、確かめる設定を案内します。
|
|
65
|
+
|
|
66
|
+
- **検索の条件の値にカンマがあると、送る前に `PortersConfigError` になります**（[ADR-0105][adr105]）。PORTERS には値の中の
|
|
67
|
+
カンマを書く方法が無く、値の途中から別の条件として読まれていました。`or` / `and` の値のカンマとコロン、キーワードのカンマと
|
|
68
|
+
空のキーワード、知らない演算子、カンマ・コロン・等号を含む項目名も同じです。テキストや日時の値のコロンは拒否しません。
|
|
69
|
+
|
|
70
|
+
- **`verifyFields` が、宣言では表せない項目（Reference など値を持たない型や、システムの項目）の宣言を見つけるようになりました**
|
|
71
|
+
（[ADR-0104][adr104]）。レポートの `declaredUndeclarable` に載り、`ok` が `false` になり、`assertFieldsMatch` も例外を投げます。
|
|
72
|
+
ライブラリがまだ知らない型は、知らせるだけで `ok` は倒しません。
|
|
73
|
+
|
|
74
|
+
- **API リファレンスの `CandidateResource` などデータ系 12 種の型のページに、各メソッドの引数・戻り値・説明を載せました**
|
|
75
|
+
（[ADR-0100][adr100]）。型の中身は変わりません。
|
|
76
|
+
|
|
77
|
+
- 内部の構成を変えました（利用者への影響はありません）。`src/` のモジュールを層に並べて依存の向きを lint で守り
|
|
78
|
+
（[ADR-0097][adr97]）、PORTERS が決めた値と定義表を `src/porters/` に（[ADR-0098][adr98]）、読み書きの共通の仕組みを
|
|
79
|
+
`src/accessor/` にまとめました（[ADR-0101][adr101]）。
|
|
80
|
+
|
|
81
|
+
### Added
|
|
82
|
+
|
|
83
|
+
- **複数の ID でまとめて読む `getMany(ids, { field?, expand?, image? })` を足しました**（[ADR-0095][adr95]。Attachment を除く
|
|
84
|
+
データ系 11 種と Phase）。戻り値は渡した ID と同じ順の配列で、見つからない ID の位置は `undefined` です。ID は 1 回の
|
|
85
|
+
リクエストで最大 200 件をまとめて送り、リクエストの長さの上限に収まるように自動で分けます。渡していない ID のレコードが
|
|
86
|
+
返ってきたときは、何も返さずに `PortersResourceError`（`category: "unknown"`）になります。
|
|
87
|
+
あわせて、`get(id, { field })` で取得する項目を指定できるようにしました。
|
|
88
|
+
|
|
89
|
+
- **データ系 11 種の検索クエリと書き込みの入力の型が、宣言したカスタム項目を型引数で受け取れるようになりました**
|
|
90
|
+
（例: `CandidateSearchQuery<CustomFor<typeof fields, "candidate">>`、
|
|
91
|
+
`CandidateCreateInput<CustomFor<typeof fields, "candidate">, RequiredFor<typeof fields, "candidate">>`）。
|
|
92
|
+
型引数を省くと、これまでと同じ型です。
|
|
93
|
+
|
|
94
|
+
### Fixed
|
|
95
|
+
|
|
96
|
+
`src` 全体をレビューし、黙って誤った結果を返していた入力や応答を、送る前・受け取った時点・起動時に止めるようにしました。
|
|
97
|
+
新しく止めるものはすべて `PortersError` の系統（多くは `PortersConfigError`）で届きます。
|
|
98
|
+
|
|
99
|
+
- **書き込み・id**
|
|
100
|
+
- `update(-1, …)` が、更新ではなく新規作成になっていました。`update` / `updateMany` / `get` / `getMany`（添付ファイルの
|
|
101
|
+
`update` / `get` も）の id は、1 以上の整数でなければ送る前に止めます（文字列や BigInt の id も）。
|
|
102
|
+
- 書き込みで、`NaN`・`Infinity`・指数表記の数（`1e21` など）、XML に書けない文字（制御文字など）、文字列でない選択肢、
|
|
103
|
+
接頭辞が付いた項目名（`Person.P_Name` など。項目名は素の alias で書きます）を送らなくなりました。
|
|
104
|
+
- `Date` / `Age` / `DateTime` の値で、暦に無い日付や、日付の後ろに別の文字が続く値を送らなくなりました。`Date` / `Age` の
|
|
105
|
+
時刻の付いた値は UTC（末尾が `Z` または `+00:00`）のものだけを受けます。書き込む年は 4 桁（0001〜9999 年）にそろえます。
|
|
106
|
+
- 画像の値の `FileName` / `ContentType` / `Content` のどれかが文字列でないと、送る前に止めます。改行を含む Base64 は、
|
|
107
|
+
改行を除いた大きさで 2MB の上限と比べます。
|
|
108
|
+
- 添付ファイルの `create` / `update` は、`resourceId`（正の整数）・`contentType` と `fileName`（空でない文字列）・
|
|
109
|
+
`content`（Base64 として成り立つ形）を送る前に確かめます。これまでは渡し忘れると壊れた添付ファイルができていました。
|
|
110
|
+
|
|
111
|
+
- **一括書き込み（`createMany` / `updateMany`）**
|
|
112
|
+
- 途中のバッチで止まったとき、`hint` に次のことを書くようになりました。
|
|
113
|
+
- 失敗したバッチの範囲と、それが書き込まれた可能性があるか
|
|
114
|
+
- まだ送っていない範囲
|
|
115
|
+
- 先のバッチで断られた index
|
|
116
|
+
- `updateMany` のときは、失敗したバッチもそのまま送り直してよいことを案内します。
|
|
117
|
+
- 最初のバッチで、トークンの取得に失敗して何も送らなかったときは、元のエラーをそのまま返します。
|
|
118
|
+
- `field` に同じ項目を 2 回書いても、1 回だけ送ります。
|
|
119
|
+
|
|
120
|
+
- **読み取り**
|
|
121
|
+
- 崩れた応答を、成功として読まなくなりました。
|
|
122
|
+
- 読めないとして `PortersResourceError`（`category: "unknown"`）にする応答:
|
|
123
|
+
- `<Code>` が数でない・入れ子になっている・2 つある
|
|
124
|
+
- 書き込みの応答に件ごとの `<Code>` が無い
|
|
125
|
+
- 成功した件に `<Id>` が無い
|
|
126
|
+
- 件数の属性が無い
|
|
127
|
+
- DOCTYPE がある
|
|
128
|
+
- 書き込んだリソースと違うルート要素
|
|
129
|
+
- 1 件の書き込みに複数の結果が返ったときもエラーにします。
|
|
130
|
+
- `searchAll` が、件数の属性が無い応答で 1 ページで黙って終わることがなくなりました。応答が頼んだページと合わないときも
|
|
131
|
+
止まります。`get` / `getMany` も、返ってきたレコードを頼んだ id と突き合わせます。
|
|
132
|
+
- 値の前後の空白と改行が消えなくなりました（複数行テキストを読んで書き戻しても変わりません）。数値文字参照（`あ` など）
|
|
133
|
+
も文字に直して返します。日時・数・件数の属性・トークンの前後の空白は、取ってから読みます。
|
|
134
|
+
- 数は 10 進の表記だけを読みます。16 進・指数表記や、丸めが起きる大きな整数はエラーにします。暦に無い日時や日付
|
|
135
|
+
（2/30・24:00 など）もエラーにします。
|
|
136
|
+
- ユーザー・部署・参照の項目の `P_Id` が空なら `null` を返します（これまでは `0`）。Option の項目に User / Department の形の
|
|
137
|
+
値が来たら、`["User"]` のような値にせず `validation` のエラーにします。
|
|
138
|
+
- XML の属性が値に混ざらなくなりました（読むのはルート要素の属性だけです）。
|
|
139
|
+
|
|
140
|
+
- **通信・認証・クライアント**
|
|
141
|
+
- `PortersClient` の構築時に、次のオプションの形を確かめるようになりました。
|
|
142
|
+
- `transport` / `throttle` / `tokenStore` がメソッドを持つか
|
|
143
|
+
- `appId` / `appSecret` が文字列か
|
|
144
|
+
- `scopes` が文字列の配列か
|
|
145
|
+
- `hostname` に `%` を含む名前や、https の URL として組み立てられない名前は、起動時に止めます。
|
|
146
|
+
- `tenant(id)` の id は正の整数だけを受け付けます。添付ファイル・Phase・Field の `of(name)` も、知らない名前を止めます。
|
|
147
|
+
- 同じサーバーに届く書き方（`a.test`・`A.test`・`a.test.`・`port: 443`）は、1 つのレート制限を共有します。
|
|
148
|
+
- 同時に届いたトークン切れ（401 / 402）で、取り直しが 1 回にまとまるようになりました。起動直後に同時に呼んだときも、
|
|
149
|
+
保存済みのトークンがあれば新しく取得しません。
|
|
150
|
+
- トークンの読み込みや取り直しの途中で `porters.auth` の操作をしても、古いトークンで上書きしなくなりました。
|
|
151
|
+
- 認証の応答に `<Error>` が無いときは、成功と読まずにエラーにします。期限が数でないときは、期限切れとして取り直します。
|
|
152
|
+
- `createFetchTransport` の `timeoutMs` は 2,147,483,647 までになりました（超える値では、すべてのリクエストがすぐ
|
|
153
|
+
中断されていました）。
|
|
154
|
+
- 自作の `transport` が投げた `PortersError` を、書き込みの結果が分からないエラーとして作り直すとき、元のクラスを保ちます。
|
|
155
|
+
|
|
156
|
+
- **カスタム項目**
|
|
157
|
+
- `defineFields` と `tenant()` が、存在しない Data Type の宣言を受け付けなくなりました。`tenant()` は、`defineFields` を
|
|
158
|
+
通さずに渡された宣言も確かめます。
|
|
159
|
+
- `generateFieldDecls` が、テナントの項目名や alias で生成物を壊さなくなりました（識別子でない alias は文字列のキーに、
|
|
160
|
+
項目名の改行は空白に）。`constName` が識別子でなければ止めます。
|
|
161
|
+
|
|
162
|
+
- **関数**
|
|
163
|
+
- `base64ToBytes` は、Base64 でない値を `PortersConfigError` で止めます。
|
|
164
|
+
- 時分型のエラーの範囲を、受け付ける範囲（47:59:59 まで）に合わせました。
|
|
165
|
+
|
|
166
|
+
- **使い方ドキュメント**
|
|
167
|
+
- `searchAll` は、辿っている途中でレコードが減ると取りこぼすことと、減りうるときの辿り方を書きました。
|
|
168
|
+
- `createMany` の件ごとの `code` が `302` のときは、作られたかを確かめてから再送することを書きました。
|
|
169
|
+
|
|
170
|
+
- `createMockTransport` などで自前の偽の応答を返しているテストは、次の応答を返していると、エラーになります。
|
|
171
|
+
本物の PORTERS と同じ応答を返してください。
|
|
172
|
+
- `get` に一覧（2 件以上）を返している。
|
|
173
|
+
- `searchAll` の 2 ページ目以降も `Start="0"` を返している。
|
|
174
|
+
- 書き込みの応答のルート要素が、書き込んだリソースの名前でない。
|
|
175
|
+
|
|
176
|
+
## [0.25.0] - 2026-09-25
|
|
177
|
+
|
|
178
|
+
**設定の誤りを黙って通さないようにし、トークンを期限つきで取り出せるようにした版**です。**破壊的変更を 2 つ**含みます
|
|
179
|
+
（定義していないオプションの拒否と、`porters.auth.getToken()` の戻り値）。あわせて、トークンの保存と中央のサービスからの
|
|
180
|
+
受け取りの実践例を足し、README と目次を読みやすく直しました。
|
|
181
|
+
|
|
182
|
+
### Changed
|
|
183
|
+
|
|
184
|
+
- **（破壊的）`new PortersClient(options)` と `porters.tenant(id, options)` は、定義していないオプションのキーを渡すと
|
|
185
|
+
`PortersConfigError`（`category: "config"`）になります**（[ADR-0092][adr92]）。これまでは打ち間違い（`hostName` など）や
|
|
186
|
+
存在しないオプションを黙って無視し、誤った設定のまま動いていました。
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
new PortersClient({ hostname, appId, appSecret, hostName: "x" });
|
|
190
|
+
// PortersConfigError: PortersClient: unknown option "hostName"
|
|
191
|
+
// hint: Valid options: hostname, port, scheme, appId, appSecret, scopes, tokenProvider, tokenStore, transport, throttle.
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
- 値が `undefined` のキーは未指定と同じ扱いです（設定をスプレッドで組み立てると混ざりやすいため）。
|
|
195
|
+
- **アプリの設定オブジェクトを丸ごと渡している場合は、使うキーだけを取り出して渡してください。**
|
|
196
|
+
- `tenant(id, options)` に渡せるのは `fields` だけです。
|
|
197
|
+
- `PortersClientOptions` の型から、使えない項目だった `auth` と `fields` を外しました。
|
|
198
|
+
|
|
199
|
+
- **（破壊的）`porters.auth.getToken()` は、Access Token の文字列ではなく `{ token, expiresAt? }`（`IssuedToken`）を
|
|
200
|
+
返すようになりました**（[ADR-0093][adr93]）。
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
// 変更前
|
|
204
|
+
const token = await porters.auth.getToken();
|
|
205
|
+
// 変更後
|
|
206
|
+
const { token, expiresAt } = await porters.auth.getToken();
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
- 返すのはリソースの呼び出しに使うのと同じトークンで、期限が近ければ取り直してから返します。`expiresAt` は
|
|
210
|
+
1970-01-01 からのミリ秒で、取り方が期限を返さなかったときは省かれます。
|
|
211
|
+
- 中央のサービスが各アプリの `tokenProvider` にトークンを渡すとき、期限もそのまま渡せます。アプリのクライアントは
|
|
212
|
+
期限切れで失敗する前に取り直せます。
|
|
213
|
+
- Refresh Token はこれまでどおり返しません。
|
|
214
|
+
|
|
215
|
+
- **使い方ドキュメントに実践例を 2 本足しました**:
|
|
216
|
+
[トークンを DB に保存する][recipe-token-store-db]（`tokenStore` を Drizzle ORM と PostgreSQL で組む）と、
|
|
217
|
+
[中央のサービスからトークンを受け取る][recipe-central-token-service]（App Secret を中央だけに置き、各アプリは
|
|
218
|
+
`tokenProvider` で受け取る）。
|
|
219
|
+
|
|
220
|
+
- **README と目次を見直しました**。README の「リソースと操作」の節を外して入口に絞り、見出し「最短で動かす」を
|
|
221
|
+
「クイックスタート」に、各章の説明を概要の要約にしました。使い方ドキュメントの章の名前を「主題別」から
|
|
222
|
+
「ガイド」に、「リソース別」から「リソース」に改めました（ページの場所は変わりません）。
|
|
223
|
+
`tokenProvider` に渡す関数が、取るのに要るもの（App Secret など）を自分で持つことも書き足しました。
|
|
224
|
+
|
|
225
|
+
- 内部の検査を変えました（利用者への影響はありません）。PR のミューテーションテストは変更したファイルだけに掛け、
|
|
226
|
+
`main` への PR は必ず全体を検査します。
|
|
227
|
+
|
|
8
228
|
## [0.24.0] - 2026-09-24
|
|
9
229
|
|
|
10
230
|
**トークンの取り方と置き場所を別々に渡せるようにした版**です。**破壊的変更を 2 つ**含みます
|
|
@@ -1456,7 +1676,9 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
|
|
|
1456
1676
|
[ref]: docs/usage/reference/README.md
|
|
1457
1677
|
[kac]: https://keepachangelog.com/en/1.1.0/
|
|
1458
1678
|
[semver]: https://semver.org/
|
|
1459
|
-
[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.
|
|
1679
|
+
[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.26.0...HEAD
|
|
1680
|
+
[0.26.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.25.0...v0.26.0
|
|
1681
|
+
[0.25.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.24.0...v0.25.0
|
|
1460
1682
|
[0.24.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.23.0...v0.24.0
|
|
1461
1683
|
[0.23.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.22.0...v0.23.0
|
|
1462
1684
|
[0.22.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.21.0...v0.22.0
|
|
@@ -1502,4 +1724,20 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
|
|
|
1502
1724
|
[adr89]: docs/adr/0089-custom-field-required-on-create.md
|
|
1503
1725
|
[adr90]: docs/adr/0090-typescript-floor.md
|
|
1504
1726
|
[adr91]: docs/adr/0091-token-provider-and-store.md
|
|
1727
|
+
[adr92]: docs/adr/0092-reject-unknown-options.md
|
|
1728
|
+
[adr93]: docs/adr/0093-get-token-with-expiry.md
|
|
1729
|
+
[adr95]: docs/adr/0095-get-many-by-ids.md
|
|
1730
|
+
[adr96]: docs/adr/0096-narrow-record-type-by-field.md
|
|
1731
|
+
[adr97]: docs/adr/0097-src-module-layout.md
|
|
1732
|
+
[adr98]: docs/adr/0098-porters-rules-folder.md
|
|
1733
|
+
[adr99]: docs/adr/0099-search-query-without-paging.md
|
|
1734
|
+
[adr100]: docs/adr/0100-expand-resource-types.md
|
|
1735
|
+
[adr101]: docs/adr/0101-accessor-layer-and-file-names.md
|
|
1736
|
+
[adr102]: docs/adr/0102-throttle-any-minute-window.md
|
|
1737
|
+
[adr103]: docs/adr/0103-create-code-302-not-retried.md
|
|
1738
|
+
[adr104]: docs/adr/0104-verify-fields-declared-undeclarable.md
|
|
1739
|
+
[adr105]: docs/adr/0105-reject-delimiters-in-query-values.md
|
|
1740
|
+
[adr106]: docs/adr/0106-unknown-outcome-scope-and-unmapped-codes.md
|
|
1741
|
+
[recipe-token-store-db]: docs/usage/recipes/token-store-db.md
|
|
1742
|
+
[recipe-central-token-service]: docs/usage/recipes/central-token-service.md
|
|
1505
1743
|
[troubleshooting]: docs/usage/reference/troubleshooting.md
|
package/README.md
CHANGED
|
@@ -9,35 +9,39 @@ PORTERS Connect API（旧 HRBC）を **TypeScript から型安全・簡単に**
|
|
|
9
9
|
> これは**非公式**ライブラリです。ポーターズ株式会社とは無関係で、公式ロゴ・商標は使用していません。
|
|
10
10
|
> 利用には **PORTERS の契約 ＋ Connect API オプション契約**が必要です（ホスト名・App ID/Secret は契約時に通知されます）。
|
|
11
11
|
|
|
12
|
-
XML
|
|
12
|
+
PORTERS が返す XML は、型の付いたオブジェクトに変換して返します。PORTERS 独自の OAuth、上限を守るための制御、
|
|
13
|
+
エラーの分類はライブラリが受け持ちます。
|
|
13
14
|
|
|
14
15
|
---
|
|
15
16
|
|
|
16
17
|
## 特徴
|
|
17
18
|
|
|
18
|
-
-
|
|
19
|
-
- **XML
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
- **日時は ISO 8601（UTC
|
|
23
|
-
- **PORTERS
|
|
19
|
+
- **型安全**：リソースと項目の値に型が付きます。`any` は使いません。
|
|
20
|
+
- **XML を扱わなくてよい**：戻り値は型の付いたオブジェクトで、渡す値もふつうの JavaScript の値です。
|
|
21
|
+
- **OAuth の手続きを自動で行う**：`code_direct` でのトークンの取得・キャッシュ・更新をライブラリが行います。
|
|
22
|
+
- **上限を守る**：スロットリング、リトライ（指数バックオフ）、リクエストの長さの検査を備えています。
|
|
23
|
+
- **日時は ISO 8601（UTC）でやり取りする**：JST などへの変換はしません（利用側で行います）。
|
|
24
|
+
- **PORTERS の全リソースに対応**：マスタ系 5 種（読み取り専用）＋ データ系 13 種（Phase・Attachment を含む）。
|
|
25
|
+
一覧と呼べるメソッドは[リソースと操作][docs-resources]にあります。
|
|
24
26
|
|
|
25
27
|
## 前提
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
使い始める前に、次の **4 つ**を済ませておく必要があります。揃っていないと PORTERS を呼べません。
|
|
28
30
|
|
|
29
31
|
1. **PORTERS 契約 ＋ Connect API オプション契約**（オプションは別契約）。
|
|
30
|
-
2. **API アプリの登録**。ここで Redirect URL を決め、**ホスト名・App ID・App Secret** が
|
|
32
|
+
2. **PORTERS への API アプリの登録**。ここで Redirect URL を決め、**ホスト名・App ID・App Secret** が
|
|
31
33
|
通知されます（いずれも機密情報なので、コードに直接書かず環境変数で渡します）。
|
|
32
|
-
3.
|
|
33
|
-
`code_direct
|
|
34
|
-
4.
|
|
34
|
+
3. **初回だけ、ブラウザで権限を付与する**（人の操作が要ります。Company DB ごとに 1 回）。2 回目以降は、ライブラリが
|
|
35
|
+
`code_direct`（サーバ間）で人の操作なしにトークンを取ります。
|
|
36
|
+
4. **付与するスコープを決める**（リソースごとに読み `_r` / 書き `_w`。読み取りだけでも複数のスコープが要ることがあります）。
|
|
35
37
|
|
|
36
|
-
|
|
37
|
-
あります。実行環境は **Node.js 22.12 以上**で、型定義は同梱です（型を読むには **TypeScript 5.4 以上**が要ります）。ビルド済みの JavaScript ファイルは ESM（`import`）の 1 つですが、
|
|
38
|
-
CJS（`require`）からも `require("@joymerrevent/porters-connect")` で読めます（[CJS から使う][s-cjs]）。
|
|
38
|
+
揃え方は[始める前に][s-prereq]に、権限付与の手順は[認証を通して、疎通を確認する][s-auth]にあります。
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
実行環境は **Node.js 22.12 以上**です。型定義は同梱していて、型を読むには **TypeScript 5.4 以上**が要ります。
|
|
41
|
+
配布しているのは ESM（`import`）のファイル 1 つですが、CJS（`require`）からも
|
|
42
|
+
`require("@joymerrevent/porters-connect")` で読み込めます（[CJS から使う][s-cjs]）。
|
|
43
|
+
|
|
44
|
+
契約や権限付与を**待っている間**も、PORTERS に接続せずにコードとテストを書けます
|
|
41
45
|
（[契約なしでテストする][test-without-contract]）。
|
|
42
46
|
|
|
43
47
|
## インストール
|
|
@@ -48,7 +52,7 @@ npm i @joymerrevent/porters-connect
|
|
|
48
52
|
# yarn add @joymerrevent/porters-connect
|
|
49
53
|
```
|
|
50
54
|
|
|
51
|
-
##
|
|
55
|
+
## クイックスタート
|
|
52
56
|
|
|
53
57
|
```ts
|
|
54
58
|
import { PortersClient } from "@joymerrevent/porters-connect";
|
|
@@ -59,7 +63,7 @@ const porters = new PortersClient({
|
|
|
59
63
|
appSecret: process.env.PORTERS_APP_SECRET ?? "",
|
|
60
64
|
});
|
|
61
65
|
|
|
62
|
-
//
|
|
66
|
+
// Partition（Company DB）は tenant(id) で指定する（既定の Partition は無い）。テナントが 1 つでも同じ書き方
|
|
63
67
|
const t = porters.tenant(456);
|
|
64
68
|
|
|
65
69
|
const page = await t.candidate.search({
|
|
@@ -72,74 +76,59 @@ const page = await t.candidate.search({
|
|
|
72
76
|
console.log(page.total, page.items[0]?.P_Name);
|
|
73
77
|
```
|
|
74
78
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
## リソースと操作
|
|
78
|
-
|
|
79
|
-
| アクセサ | リソース | アクセサ | リソース |
|
|
80
|
-
| --------------- | -------------- | -------------- | ------------ |
|
|
81
|
-
| `t.candidate` | 個人連絡先 | `t.contract` | 契約 |
|
|
82
|
-
| `t.job` | JOB | `t.sales` | 成約・売上 |
|
|
83
|
-
| `t.client` | 企業 | `t.process` | 選考プロセス |
|
|
84
|
-
| `t.recruiter` | 企業担当者 | `t.resume` | レジュメ |
|
|
85
|
-
| `t.contact` | コンタクト | `t.attachment` | 添付ファイル |
|
|
86
|
-
| `t.opportunity` | 商談管理 | `t.phase` | フェーズ履歴 |
|
|
87
|
-
| `t.activity` | アクティビティ | | |
|
|
88
|
-
|
|
89
|
-
マスタ系は `porters.partition` / `t.user` / `t.department` / `t.field` / `t.option` の 5 種（読み取り専用）。
|
|
90
|
-
|
|
91
|
-
**どのメソッドが呼べるかはリソースごとに違います**（`searchAll` が無いもの、先に `of("candidate")` のように
|
|
92
|
-
対象リソースを指定するもの（Field・Phase・Attachment）があります）。一覧は[リソースと操作][docs-resources]、引数・戻り値・項目の一覧は
|
|
93
|
-
[API リファレンス][api-ref]が正確な定義です。
|
|
79
|
+
README で説明するのはここまでです。認証の準備・書き込み・エラーの扱いなど、使い方の全体は
|
|
80
|
+
[docs/usage][docs-index] の目次から読めます<!-- 根拠: ADR-0070（README は入口に絞る） -->。はじめての人は[導入][s-prereq]（6 ページ）から順に進んでください。
|
|
94
81
|
|
|
95
82
|
## ドキュメント
|
|
96
83
|
|
|
97
84
|
**[docs/usage][docs-index] が目次**です。7 つの章に分かれていて、順に読むのは導入だけです。
|
|
98
85
|
|
|
99
|
-
| 章 |
|
|
100
|
-
| ---------------- |
|
|
101
|
-
| **導入** |
|
|
102
|
-
|
|
|
103
|
-
| **クライアント** |
|
|
104
|
-
|
|
|
105
|
-
| **関数** | `import`
|
|
106
|
-
| **実践例** |
|
|
107
|
-
| **リファレンス** | [公開 API リファレンス][api-ref]
|
|
86
|
+
| 章 | 概要 |
|
|
87
|
+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
88
|
+
| **導入** | PORTERS への接続から、データの読み書き、本番での運用までを、6 ページで順に説明します |
|
|
89
|
+
| **ガイド** | Partition・検索・書き込み・認証・上限など、PORTERS を使ううえで欠かせない事柄を 1 ページずつ説明します。PORTERS 側の前提と、ライブラリが受け持つ範囲が分かります |
|
|
90
|
+
| **クライアント** | クライアントの作り方と、クライアントから呼び出せる機能をまとめています |
|
|
91
|
+
| **リソース** | 18 のリソースごとに、使えるメソッド・注意点・新規作成の必須項目をまとめています |
|
|
92
|
+
| **関数** | `import` して使う関数ごとに、使い方と失敗したときの扱いをまとめています |
|
|
93
|
+
| **実践例** | 毎日の差分同期や複数テナントなど、よくある用途ごとに、機能の組み合わせ方をサンプルコードで示します |
|
|
94
|
+
| **リファレンス** | 型やメソッドの正確な定義（[公開 API リファレンス][api-ref]）と、PORTERS 側の仕様（[PORTERS API の事実][ref]）をまとめています |
|
|
108
95
|
|
|
109
|
-
|
|
96
|
+
目次の末尾の「目的から探す」から、やりたいことに合うページへ直接進めます。
|
|
110
97
|
|
|
111
98
|
## PORTERS 固有の注意
|
|
112
99
|
|
|
113
|
-
|
|
114
|
-
|
|
100
|
+
PORTERS 側の仕様で、使い始める前に知っておきたいものです。詳しくは、それぞれのガイドのページの「まず知ること」に
|
|
101
|
+
あります。
|
|
115
102
|
|
|
116
|
-
-
|
|
117
|
-
- **日時は UTC
|
|
118
|
-
- **データは Partition
|
|
119
|
-
-
|
|
120
|
-
|
|
121
|
-
|
|
103
|
+
- **PORTERS には削除の API がありません**。このライブラリにも `delete()` はありません（[削除と削除済みデータ][c-no-delete]）。
|
|
104
|
+
- **日時は UTC です**。ISO 8601（`…Z`）で受け渡しし、JST などへの変換はしません（[日時と時分型][c-datetime]）。
|
|
105
|
+
- **データは Partition（Company DB）ごとに分かれています**。`tenant(id)` で Partition を指定してから読み書きします
|
|
106
|
+
（[Partition とテナントスコープ][c-partition]）。
|
|
107
|
+
- **上限があります**。リクエストの長さ（約 15000 文字）・1 リクエスト 200 件・1 分あたり Read 2000 / Write 500 は
|
|
108
|
+
ライブラリが守ります。**月 15 万アクセスは契約の条件**で、数えて守るのは利用側です（[上限とレート][c-limits]）。
|
|
109
|
+
- **ホスト名は契約時に通知されます**。環境変数（`PORTERS_HOST` など）で渡し、コードに直接書かないでください。
|
|
122
110
|
|
|
123
111
|
## 対応バージョン
|
|
124
112
|
|
|
125
|
-
-
|
|
126
|
-
|
|
113
|
+
- **Connect API Version 2 を前提にしています**。リクエストには `X-P-ConnectAPI-Version: 2` を付けて送ります
|
|
114
|
+
（担当者型・部署型の参照項目（Link）などは v2 が必要です）。互換性は、この Connect API のバージョンで示します。
|
|
115
|
+
- **PORTERS の製品バージョン 8.x / 9.x は参考です**。どちらも v2 を提供している世代ですが、マイナーバージョンごとの動作は
|
|
116
|
+
保証しません。PORTERS 側の仕様は [PORTERS API の事実][ref]（PORTERS の公式ドキュメントに基づく）にまとめています。
|
|
127
117
|
|
|
128
118
|
## リンク
|
|
129
119
|
|
|
130
|
-
**この README は「最短で動かす」ところまで**です。全体は目次から読めます<!-- 根拠: ADR-0070 -->。
|
|
131
|
-
|
|
132
120
|
- 利用者向け：[docs/usage][docs-index]（目次）／[公開 API リファレンス][api-ref]／[PORTERS API の事実][ref]
|
|
133
121
|
- 開発・保守：[docs/README.md][docs-readme]（ADR（設計判断の記録）・基本設計・ロードマップ・台帳）
|
|
134
122
|
- 提供元：[Joymerrevent][joymerrevent]
|
|
135
123
|
|
|
136
124
|
## コントリビュート / セキュリティ
|
|
137
125
|
|
|
138
|
-
- バグ報告・要望・質問は [Issues][issues]
|
|
126
|
+
- バグ報告・要望・質問は [Issues][issues] へお願いします。外部の方からの提案は Issue で受け付けていて、PR を作れるのは
|
|
127
|
+
コラボレーターだけです。詳しくは [CONTRIBUTING][contributing] にあります。
|
|
139
128
|
- 脆弱性は公開 Issue ではなく [セキュリティポリシー][security] の手順で**非公開**で報告してください。
|
|
140
|
-
-
|
|
129
|
+
- 行動規範は [Contributor Covenant][coc] です。
|
|
141
130
|
|
|
142
|
-
>
|
|
131
|
+
> このライブラリは**非公式**です。PORTERS の製品や Connect API そのものの不具合・要望は、PORTERS の公式窓口へお問い合わせください。
|
|
143
132
|
|
|
144
133
|
## ライセンス
|
|
145
134
|
|