@joymerrevent/porters-connect 0.17.0 → 0.19.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 +176 -1
- package/README.md +6 -4
- package/dist/index.d.cts +2993 -0
- package/dist/index.d.ts +139 -49
- package/dist/index.js +161 -144
- package/dist/index.js.map +1 -1
- package/package.json +14 -7
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,174 @@
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [0.19.0] - 2026-09-18
|
|
9
|
+
|
|
10
|
+
**CJS からの入口を開け、Node の下限を 22.12 に上げた版**です。**破壊的変更を 1 つ**含みます
|
|
11
|
+
（`engines.node` の引き上げ）。
|
|
12
|
+
|
|
13
|
+
`require()` は `ERR_PACKAGE_PATH_NOT_EXPORTED`、TypeScript は `TS1479` — 0.18.0 まで、CJS からは
|
|
14
|
+
**実行時もコンパイル時も入口がありませんでした**。別実体（dual）を配るのではなく、`require` 条件を
|
|
15
|
+
**同じ ESM 実体**に向けて塞いでいます（[ADR-0082][adr82]）。
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- **CJS（`require`）から読めるようになりました**（[ADR-0082][adr82]）。
|
|
20
|
+
|
|
21
|
+
```js
|
|
22
|
+
const { PortersClient } = require("@joymerrevent/porters-connect");
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
配るのは **ESM の 1 ファイルのまま**で、`require` 条件を同じ実体に向けています
|
|
26
|
+
（Node の `require(esm)`）。**CJS 用の別ファイルは配りません** — 実体が 2 つあると
|
|
27
|
+
ESM 側と CJS 側で別のクラスが読まれ、`catch (e) { if (e instanceof PortersError) … }` が
|
|
28
|
+
`false` になって素通りするためです。型は `dist/index.d.cts` を同梱しているので、
|
|
29
|
+
`moduleResolution: node16` の CJS 利用者もそのまま書けます。
|
|
30
|
+
|
|
31
|
+
0.18.0 までは `exports` が `import` 条件しか持たず、`require()` は
|
|
32
|
+
`ERR_PACKAGE_PATH_NOT_EXPORTED`、TypeScript は `TS1479` で**入口そのものがありません**でした。
|
|
33
|
+
|
|
34
|
+
### Changed
|
|
35
|
+
|
|
36
|
+
- **（破壊的）Node.js 22.12 以上が必要になりました**（[ADR-0082][adr82]）。`engines.node` が
|
|
37
|
+
`>=20` → `>=22.12.0` です。`require` 条件を ESM 実体に向ける形は Node の `require(esm)` に
|
|
38
|
+
載っており、これが既定で有効なのは **22.12.0 以降**だからです（22.0〜22.11 では
|
|
39
|
+
`ERR_REQUIRE_ESM`）。丸めて `>=22` と書くとその範囲に対して嘘になるため、成立する最小の形で
|
|
40
|
+
宣言しています。Node 20 は **2026-04-30 に EOL** で、テストの Node マトリクスからも外しました。
|
|
41
|
+
|
|
42
|
+
## [0.18.0] - 2026-09-17
|
|
43
|
+
|
|
44
|
+
**「どのリソースか」の受け取り方を 1 つの規則に揃えた版**です。**破壊的変更を 4 つ**含みます
|
|
45
|
+
（アクセスポイントの `host` 廃止／束ねた項目は書き込み入力から外れる／Field マスタの Read が
|
|
46
|
+
`of()` 経由に／添付の Read が PORTERS の語彙に）。
|
|
47
|
+
|
|
48
|
+
PORTERS が `resource=` を **URL パラメータで必須**に要求するエンドポイントは 3 つ（Field / Phase /
|
|
49
|
+
Attachment）あるのに、受け口の形が 3 つとも違っていました。**パラメータのリソースは `of(name)` で
|
|
50
|
+
束ね、項目の値は宣言した Data Type どおり（数値）**という線を引き、3 本とも `of()` に揃えています。
|
|
51
|
+
|
|
52
|
+
### Added
|
|
53
|
+
|
|
54
|
+
- **`resourceValueOf` / `resourceNameOf`** — リソース名と数値を相互変換します（[ADR-0079][adr79]）。
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
import {
|
|
58
|
+
resourceNameOf,
|
|
59
|
+
resourceValueOf,
|
|
60
|
+
} from "@joymerrevent/porters-connect";
|
|
61
|
+
|
|
62
|
+
await t.activity.create({
|
|
63
|
+
P_Owner: 5,
|
|
64
|
+
P_Title: "一次面談",
|
|
65
|
+
P_Resource: resourceValueOf("candidate"), // 1
|
|
66
|
+
P_ResourceId: 10001,
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
resourceNameOf(17); // "resume"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
PORTERS のリソース番号は**非連続**です（Candidate `1` / Job `3` / Client `5` / Recruiter `9` /
|
|
73
|
+
Sales `11` / …）。欠番も取り違えも数値リテラルでは気づけないので、名前から引いてください。
|
|
74
|
+
`resourceNameOf` は**知らない数値をそのまま返します**（`ResourceName | number`）— Resource List は
|
|
75
|
+
PORTERS のもので増えるため（Contact `27` は後から増えました）、知らない値はエラーにせず
|
|
76
|
+
データとして通します。
|
|
77
|
+
|
|
78
|
+
- 公開した型: `AttachmentAccessor` / `FieldAccessor`（`ResourceName` は 0.17.0 から公開済みで、
|
|
79
|
+
`of()` に渡す名前の型です）。
|
|
80
|
+
|
|
81
|
+
### Changed
|
|
82
|
+
|
|
83
|
+
- **（破壊的）アクセスポイントが `hostname` と `port` に分かれました**（[ADR-0078][adr78]）。
|
|
84
|
+
**`host` は無くなります。**
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
// これまで
|
|
88
|
+
new PortersClient({ host: "xxxxx.example.com", appId, appSecret });
|
|
89
|
+
new PortersClient({ host: "127.0.0.1:4010", scheme: "http" });
|
|
90
|
+
|
|
91
|
+
// これから
|
|
92
|
+
new PortersClient({ hostname: "xxxxx.example.com", appId, appSecret });
|
|
93
|
+
new PortersClient({ hostname: "127.0.0.1", port: 4010, scheme: "http" });
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**契約で渡される値にポートは無い**からです。PORTERS の記事は `{Request Host}` を「該当の
|
|
97
|
+
**サーバー名**を入れてください」と説明し、ポート表記はどの記事にも出てきません。一方 URL 仕様では
|
|
98
|
+
`host` は**ポートを含む**名前で、含まないのが `hostname` です。名前と中身を揃えました。
|
|
99
|
+
|
|
100
|
+
- **`hostname` にポートを書くと構築時に落ちます**（`PortersConfigError`）。素通しすると
|
|
101
|
+
「指定したつもりで既定ポートに送られる」ので、黙って落とさずに弾きます
|
|
102
|
+
- **`port` は 1〜65535 の整数**。省略すれば scheme の既定ポートです。使うのはローカルの
|
|
103
|
+
フェイクサーバーやプロキシに向けるときだけで、PORTERS には要りません
|
|
104
|
+
- **IPv6 は角括弧付き**で渡します（`hostname: "[::1]"`）
|
|
105
|
+
- `PortersClient` のゲッターも `host` → **`hostname` / `port`** の 2 本になります
|
|
106
|
+
- スロットルのバケット（[ADR-0073][adr73]）は**宛先ごと**になりました。同じ名前でもポートが
|
|
107
|
+
違えば別のバケットです
|
|
108
|
+
|
|
109
|
+
- **（破壊的）添付ファイルの Read が PORTERS の語彙に揃いました**（[ADR-0081][adr81]）。
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
// これまで
|
|
113
|
+
await t.attachment.search({ condition: { "ResourceId:eq": "10001" } });
|
|
114
|
+
await t.attachment.create({ resource: 17, resourceId: 10001, ...file });
|
|
115
|
+
|
|
116
|
+
// これから
|
|
117
|
+
const files = t.attachment.of("resume"); // resource を 1 回束ねる
|
|
118
|
+
await files.search({ resourceId: 10001 });
|
|
119
|
+
await files.get(900);
|
|
120
|
+
await files.create({ resourceId: 10001, ...file }); // resource は束ねた値
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
PORTERS の `Attachment - Read` が取るのは `requestType` / `resource` / `resourceId` / `id` で、
|
|
124
|
+
**`field` と `condition` は挙げられていません**。ライブラリは逆で、**必須の 2 つを送らず、
|
|
125
|
+
記載の無い 2 つを送っていました**。出典どおりなら添付の読み取りは実環境で常に失敗するので、
|
|
126
|
+
出典に一致する側へ倒しました。
|
|
127
|
+
|
|
128
|
+
- `create` の入力から **`resource` が消えました**。付け先を取り違えても添付は消せないので、
|
|
129
|
+
書ける場所を減らしています
|
|
130
|
+
- 本体（`content`）を運ぶかは引き続き**メソッドが決めます**（`get` だけが運びます。
|
|
131
|
+
PORTERS 側では `requestType` です）
|
|
132
|
+
- **絞れるのは `resourceId`（1 レコードの添付）と `id`（1 件）だけ**で、ファイル名などでの
|
|
133
|
+
検索はできません（PORTERS が提供していません）。名前で探すときは `searchAll` で歩きながら
|
|
134
|
+
絞ってください
|
|
135
|
+
- **出典どおりの形が実機で通るかは未確認**です（契約環境でのみ確かめられます）
|
|
136
|
+
|
|
137
|
+
- **（破壊的）Field マスタの Read が `of()` でリソースを束ねる形になりました**（[ADR-0080][adr80]）。
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
// これまで
|
|
141
|
+
await t.field.search({ resource: "candidate", active: 1 });
|
|
142
|
+
|
|
143
|
+
// これから
|
|
144
|
+
await t.field.of("candidate").search({ active: 1 });
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
同じ形の Phase は以前から `t.phase.of("client")` で束ねていたので、**URL パラメータのリソースは
|
|
148
|
+
`of()` で束ねる**という 1 つの規則に揃えました。`readCustomCatalog` / `verifyFields` /
|
|
149
|
+
`generateFieldDecls` の**引数は変わりません**。`porters.partition` / `t.user` / `t.option` も
|
|
150
|
+
変わりません — この 3 つは `resource=` を取らないためです。
|
|
151
|
+
|
|
152
|
+
- **（破壊的）アクセサが束ねた項目は、書き込み入力から外れます**。
|
|
153
|
+
|
|
154
|
+
`t.phase.of("client")` は「このアクセサは企業の Phase を扱う」という宣言です。これまでは
|
|
155
|
+
`Resource` を書き込み入力に渡せてしまい、**束ねた値を上書きできました** — `of("client")` から
|
|
156
|
+
JOB（`3`）の Phase が書ける状態でした。
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
const phase = (await t.phase.of("client").get(10014))!;
|
|
160
|
+
await t.phase.of("client").create({ ...phase, Date: "2026-09-17T00:00:00Z" });
|
|
161
|
+
// 読みのレコードは `Resource` を持つため、これまでは束ねた値が黙って上書きされていました
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
型で外したうえ、キャストで渡した場合も**送信前に** `PortersConfigError` で止めます（黙って
|
|
165
|
+
捨てません）。Phase に削除 API は無いので、間違ったリソースに付いた履歴は消せません。
|
|
166
|
+
|
|
167
|
+
- **エンドポイント × 機能のマトリクスのずれが無くなりました**。0.17.0 で起こした表は
|
|
168
|
+
**4 セルが食い違った状態**で出しましたが（Phase の 2 つ・Attachment の 2 つ）、本版で
|
|
169
|
+
**すべて解消**しています。パッケージの中身は変わりません。
|
|
170
|
+
|
|
171
|
+
### Removed
|
|
172
|
+
|
|
173
|
+
- **`AttachmentMetaField`** — 0.17.0 で公開した型ですが、添付の Read から `field` が無くなった
|
|
174
|
+
ため役目を終えました（[ADR-0081][adr81]）。
|
|
175
|
+
|
|
8
176
|
## [0.17.0] - 2026-09-16
|
|
9
177
|
|
|
10
178
|
**添付ファイルの運び方を決め、出典に無いパラメータを型から外した版**です。**破壊的変更を 2 つ**
|
|
@@ -887,13 +1055,20 @@
|
|
|
887
1055
|
[adr75]: docs/adr/0075-attachment-search-all.md
|
|
888
1056
|
[adr76]: docs/adr/0076-phase-read-query-surface.md
|
|
889
1057
|
[adr77]: docs/adr/0077-fetch-transport-timeout.md
|
|
1058
|
+
[adr78]: docs/adr/0078-hostname-port-split.md
|
|
1059
|
+
[adr79]: docs/adr/0079-resource-by-name.md
|
|
1060
|
+
[adr80]: docs/adr/0080-resource-parameter-binding.md
|
|
1061
|
+
[adr81]: docs/adr/0081-attachment-read-parameters.md
|
|
1062
|
+
[adr82]: docs/adr/0082-module-format-and-node-baseline.md
|
|
890
1063
|
[limits]: docs/usage/concepts/limits.md
|
|
891
1064
|
[failures]: docs/usage/howto/handle-failures.md
|
|
892
1065
|
[lv]: docs/live-verification.md
|
|
893
1066
|
[ref]: docs/usage/reference/README.md
|
|
894
1067
|
[kac]: https://keepachangelog.com/en/1.1.0/
|
|
895
1068
|
[semver]: https://semver.org/
|
|
896
|
-
[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.
|
|
1069
|
+
[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.19.0...HEAD
|
|
1070
|
+
[0.19.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.18.0...v0.19.0
|
|
1071
|
+
[0.18.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.17.0...v0.18.0
|
|
897
1072
|
[0.17.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.16.0...v0.17.0
|
|
898
1073
|
[0.16.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.15.1...v0.16.0
|
|
899
1074
|
[0.15.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.15.0...v0.15.1
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @joymerrevent/porters-connect
|
|
2
2
|
|
|
3
|
-
[![npm version][npm-badge]][npm] [![License: MIT][mit-badge]][mit] ![Node >=
|
|
3
|
+
[![npm version][npm-badge]][npm] [![License: MIT][mit-badge]][mit] ![Node >= 22.12.0][node-badge] [![OpenSSF Scorecard][scorecard-badge]][scorecard] [![OpenSSF Best Practices][bp-badge]][bp]
|
|
4
4
|
|
|
5
5
|
PORTERS Connect API（旧 HRBC）を **TypeScript から型安全・簡単に**扱うための、
|
|
6
6
|
[Joymerrevent（ジョイメリベント）][joymerrevent] 製の **非公式（unofficial）** ラッパーです。
|
|
@@ -35,7 +35,8 @@ XML レスポンスを型付きオブジェクトに変換し、独自仕様の
|
|
|
35
35
|
4. **付与するスコープ**の決定（リソース別に `_r` / `_w`。Read でも複数要ることがあります）。
|
|
36
36
|
|
|
37
37
|
揃えかたは[始める前に][s-prereq]に、権限付与の手順は[認証を通して、疎通を確認する][s-auth]に
|
|
38
|
-
あります。実行環境は Node.js
|
|
38
|
+
あります。実行環境は **Node.js 22.12 以上**で、型定義は同梱です。配るのは ESM 1 本ですが、
|
|
39
|
+
CJS からも `require("@joymerrevent/porters-connect")` で読めます（[CJS から使う][s-cjs]）。
|
|
39
40
|
|
|
40
41
|
契約や権限付与を**待っている間**も、PORTERS に繋がずにコードとテストは書けます
|
|
41
42
|
（[契約なしでテストを書きたい][test-without-contract]）。
|
|
@@ -54,7 +55,7 @@ npm i @joymerrevent/porters-connect
|
|
|
54
55
|
import { PortersClient } from "@joymerrevent/porters-connect";
|
|
55
56
|
|
|
56
57
|
const porters = new PortersClient({
|
|
57
|
-
|
|
58
|
+
hostname: process.env.PORTERS_HOST ?? "", // 契約時に通知される値。ハードコード禁止
|
|
58
59
|
appId: process.env.PORTERS_APP_ID ?? "",
|
|
59
60
|
appSecret: process.env.PORTERS_APP_SECRET ?? "",
|
|
60
61
|
});
|
|
@@ -144,7 +145,7 @@ console.log(page.total, page.items[0]?.P_Name);
|
|
|
144
145
|
[npm-badge]: https://img.shields.io/npm/v/@joymerrevent/porters-connect
|
|
145
146
|
[mit]: ./LICENSE
|
|
146
147
|
[mit-badge]: https://img.shields.io/badge/License-MIT-blue.svg
|
|
147
|
-
[node-badge]: https://img.shields.io/badge/node-%3E%
|
|
148
|
+
[node-badge]: https://img.shields.io/badge/node-%3E%3D22.12.0-brightgreen.svg
|
|
148
149
|
[scorecard]: https://scorecard.dev/viewer/?uri=github.com/Joymerrevent/porters-connect
|
|
149
150
|
[scorecard-badge]: https://api.scorecard.dev/projects/github.com/Joymerrevent/porters-connect/badge
|
|
150
151
|
[bp]: https://www.bestpractices.dev/projects/14611
|
|
@@ -160,6 +161,7 @@ console.log(page.total, page.items[0]?.P_Name);
|
|
|
160
161
|
[c-no-delete]: docs/usage/concepts/no-delete.md
|
|
161
162
|
[c-partition]: docs/usage/concepts/partition.md
|
|
162
163
|
[s-auth]: docs/usage/start/authenticate.md
|
|
164
|
+
[s-cjs]: docs/usage/start/install.md#cjs-から-require-する
|
|
163
165
|
[s-prereq]: docs/usage/start/prerequisites.md
|
|
164
166
|
[test-without-contract]: docs/usage/howto/test-without-contract.md
|
|
165
167
|
[docs-index]: docs/usage/index.md
|