@joymerrevent/porters-connect 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -5,6 +5,90 @@
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-09-24
+
+**カスタム項目を宣言で `create` の必須にできるようにした版**です。あわせて、利用者の TypeScript の下限を
+**5.4** と定め、それより古い版でははっきりした型エラーになるようにしました。**TypeScript 5.4 より前を使っている
+場合は破壊的変更です**（下の Changed）。
+
+### Added
+
+- **カスタム項目を宣言で `create` の必須にできるようになりました**（[ADR-0089][adr89]）。宣言のビルダーに
+  `{ required: true }` を渡すと、その項目は `create` / `createMany` の入力型で必須になります。
+
+  ```ts
+  const fields = defineFields({
+    candidate: (f) => ({
+      U_score: f.number({ required: true }), // create で必須
+      U_source: f.option(), // 任意のまま
+    }),
+  });
+  const t = porters.tenant(1, { fields });
+
+  await t.candidate.create({ P_Owner: 5, U_score: 80 }); // U_score を渡さないとコンパイルエラー
+  ```
+
+  - `required` を書かなければ、これまでと同じく任意です。`update` / `updateMany` では常に任意です。
+  - 型で止めるだけで、実行時には検査しません（標準項目の必須と同じ扱い）。
+  - `TenantScope<typeof fields>` と書いた型でも必須になります。新しい型引数は要りません。
+  - `generateFieldDecls` は、テナントが入力必須にしている項目（Field Read の `P_Required` が `1`）に
+    `{ required: true }` を付けて出します。`create` で必須にしない項目は、生成したファイルから消します。
+  - `readCustomCatalog` の戻り値に `required`（alias → 入力必須かどうか）が増えました。
+  - `verifyFields` の報告に `requiredMismatch`（宣言の `required` とテナントの入力必須の食い違い）が増えました。
+    読み書きは壊れないので、`ok` は変わらず、`assertFieldsMatch` も止めません。
+  - 新しく公開した型: `FieldOptions` / `RequiredFor` / `DeclaredRequiredOf` / `RequiredMismatch`。
+
+### Changed
+
+- **（TypeScript 5.4 より前を使っている場合は破壊的）型を読むには TypeScript 5.4 以上が要ります**
+  （[ADR-0090][adr90]）。同梱の型定義が、5.4 で入った型（`NoInfer`）を使うためです。5.4 より前の TypeScript では、
+  このパッケージから `import` したものを使った行が、`requires TypeScript 5.4 or later` を含む型エラーになります。
+  そのときは TypeScript を上げてください。`bundler` / `node16` / `node` のどの解決方式でも同じです。
+- **`verifyFields` の報告を自分で組み立てているコード**（テストのスタブなど）は、`requiredMismatch: []` を
+  足してください。`FieldVerification` に項目が増えたためで、`verifyFields` の戻り値を読むだけのコードは変わりません。
+- 内部の検査を増やしました（利用者への影響はありません）。CI で、TypeScript の下限の版（5.4 の系で最も古い安定版）と
+  開発で使う版で利用者のコードをコンパイルし、下限より前の版では上の型エラーになることを確かめます。
+
+## [0.22.0] - 2026-09-23
+
+**読み取りの値の検証を 1 つ増やし、使い方ドキュメントを組み直した版**です。破壊的変更はありませんが、
+**宣言が実際の項目と合っていないと、これまで通っていた読み取りがエラーになることがあります**（下の Changed）。
+
+### Changed
+
+- **数値でない文字列を `Number` として読まなくなりました**。`Number` / `System[Id]` の項目と
+  `Link` のスカラ形（Contact の ID）に数値として読めない値が来ると、`PortersResourceError`
+  （`category: "validation"`・項目名つき）で失敗します。これまでは `Number("社内候補")` の結果＝**`NaN`** が
+  黙って読み取り値に入り、`typeof === "number"` と `null` 判定の両方を通り、そのまま `update` に戻すと
+  `<Alias>NaN</Alias>` を送っていました。
+
+  ```text
+  U_score: declared Number, but "社内候補" is not a PORTERS Number value
+  ```
+
+  - 起きるのは**宣言が違うとき**です（テキストの項目を `f.number()` と宣言した、など）。PORTERS が
+    Number 項目に数値以外を返す書式は出典にありません。日時（`f.date()` 等）が 0.15.0 から同じ形で
+    エラーになるのと揃えました。
+  - 数値として読める値（`"87"` / `"-1.25"` / 前後の空白）と空（`null`）は変わりません。
+  - 書き込み側は変えていません（`NaN` を渡す JS コードはこれまでどおりそのまま送られます）。
+  - 上げる前に宣言を確かめるなら、これまでどおり `verifyFields` です。
+
+- **使い方ドキュメント（`docs/usage/`）を 7 章に組み直しました**。導入／主題別／クライアント／リソース別／
+  関数／実践例／リファレンスの順で、目次（`docs/usage/index.md`）から章を辿ります。
+  - **リソース別**は 18 種に 1 ページずつで、どのページも「呼べるメソッド → 固有の注意 → 新規作成の必須項目 →
+    項目と型」の同じ順に並びます。
+  - **クライアント**（`PortersClient` の構築オプション・`porters.auth` の 6 メソッド・`tenant(id)` のスコープ）と
+    **関数**（宣言と突合・上限と接続・値の変換）の章を新設し、導入と主題別に散らばっていた一覧をまとめました。
+  - **主題別**（検索・書き込み・認証・カスタム項目・上限など）は「まず知ること → 使い方 → 細かい規則」の順に
+    書き直し、言い回しを平易にしています。内容の食い違い（`Promise` を返さない関数の一覧の漏れなど）も直しました。
+
+### Fixed
+
+- **単件の `create` / `update` が、`of()` で指定済みの項目（Phase の `Resource`）を渡されたとき、
+  同期 throw していました**。`Promise` を返すほかの公開メソッドと同じく、reject で届くようにしました。
+  入力型が `Resource` を受け付けないので、TypeScript から普通に書く限り起きません（`as any` を通した場合と
+  JavaScript から呼んだ場合だけ）。例外の種類・`message`・`category` は変わりません。
+
 ## [0.21.0] - 2026-09-21
 
 **カスタム項目の宣言を、partition を束ねる `tenant(id)` で受け取るようにした版**です。
@@ -20,8 +104,9 @@
 
   カスタム項目（`U_` / `A_`）は **partition（Company DB）ごとのもの**です — 出典の各リソース記事が
   「テナント毎に異なる」としています。これまで宣言は client に 1 つしか持てず、項目構成の違う
-  テナントを同じ client で扱うと、**別テナントの宣言が黙って適用される**形でした（実物が Option の
-  項目をテキストで読めば値が `null` になり、例外も警告も出ません）。partition を束ねる `tenant(id)` が、
+  テナントを同じ client で扱うと、**別テナントの宣言が黙って適用される**形でした（ずれは読み取り時の
+  `validation` エラーで見えますが〔0.15.0〕、どのテナントの宣言を当てたのかをライブラリは知らないので、
+  正しい宣言に取り替える手掛かりがありません）。partition を束ねる `tenant(id)` が、
   その partition の項目の形も束ねます。
 
   ```ts
@@ -1245,7 +1330,7 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 - **エラー対処ガイド**: [docs/howto/handle-failures.md][guide]（症状別早見表＋2 系統のコード対応表）。
 - **配布**: ESM / Node.js 18+ / 型定義同梱 / MIT。`X-P-ConnectAPI-Version: 2` を既定送信（PORTERS 8.x・9.x 想定）。
 
-[guide]: docs/usage/howto/handle-failures.md
+[guide]: docs/usage/topics/errors.md
 [adr44]: docs/adr/0044-http-status-handling.md
 [adr45]: docs/adr/0045-write-response-root-code.md
 [adr46]: docs/adr/0046-guard-error-contract.md
@@ -1254,12 +1339,12 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [adr50]: docs/adr/0050-auth-http-status-handling.md
 [adr51]: docs/adr/0051-read-envelope-identification.md
 [adr47]: docs/adr/0047-access-point-scheme.md
-[oauth-guide]: docs/usage/howto/authenticate.md
+[oauth-guide]: docs/usage/topics/auth.md
 [adr19]: docs/adr/0019-static-resource-types.md
 [adr20]: docs/adr/0020-read-field-default.md
 [adr35]: docs/adr/0035-usage-documentation-structure.md
-[custom-fields-guide]: docs/usage/howto/custom-fields.md
-[read-query-guide]: docs/usage/howto/search-records.md
+[custom-fields-guide]: docs/usage/topics/custom-fields.md
+[read-query-guide]: docs/usage/topics/query.md
 [adr55]: docs/adr/0055-partition-binding-guard.md
 [adr56]: docs/adr/0056-deleted-flag-typing.md
 [adr57]: docs/adr/0057-itemstate-existing-explicit.md
@@ -1272,7 +1357,7 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [rv22]: docs/reviews/rv/0022-ratelimit-create-no-retry.md
 [rv32]: docs/reviews/rv/0032-searchall-query-mutation.md
 [rv44]: docs/reviews/rv/0044-fields-excluded-from-coverage.md
-[write-constraints]: docs/usage/concepts/limits.md
+[write-constraints]: docs/usage/topics/limits.md
 [adr68]: docs/adr/0068-api-reference-tooling.md
 [adr69]: docs/adr/0069-tenant-field-catalog-tooling.md
 [adr73]: docs/adr/0073-throttle-sharing.md
@@ -1285,14 +1370,16 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [adr80]: docs/adr/0080-resource-parameter-binding.md
 [adr81]: docs/adr/0081-attachment-read-parameters.md
 [adr82]: docs/adr/0082-module-format-and-node-baseline.md
-[limits]: docs/usage/concepts/limits.md
-[failures]: docs/usage/howto/handle-failures.md
+[limits]: docs/usage/topics/limits.md
+[failures]: docs/usage/topics/errors.md
 [adr85]: docs/adr/0085-option-alias-validation.md
 [lv]: docs/live-verification.md
 [ref]: docs/usage/reference/README.md
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
-[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.21.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.23.0...HEAD
+[0.23.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.22.0...v0.23.0
+[0.22.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.20.1...v0.21.0
 [0.20.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.20.0...v0.20.1
 [0.20.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.19.1...v0.20.0
@@ -1330,5 +1417,7 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [fastcheck]: https://github.com/dubzzz/fast-check
 [adr86]: docs/adr/0086-time-of-day-fields.md
 [adr87]: docs/adr/0087-tenant-scoped-field-declarations.md
-[howto-custom-fields]: docs/usage/howto/custom-fields.md
+[howto-custom-fields]: docs/usage/topics/custom-fields.md
 [ref-department]: docs/usage/reference/resource-api/resources/department.md
+[adr89]: docs/adr/0089-custom-field-required-on-create.md
+[adr90]: docs/adr/0090-typescript-floor.md

package/README.md

@@ -10,36 +10,35 @@ PORTERS Connect API（旧 HRBC）を **TypeScript から型安全・簡単に**
 > 利用には **PORTERS の契約 ＋ Connect API オプション契約**が必要です（ホスト名・App ID/Secret は契約時に通知されます）。
 
 XML レスポンスを型付きオブジェクトに変換し、独自仕様の OAuth・レート制御・エラー整理を内側に隠します。
-**薄く・堅く**を方針に、フェイルセーフ（壊れたときに安全側へ倒れる）設計です。
 
 ---
 
 ## 特徴
 
-- **型安全**：リソース・項目の値を型で表現。`any` を撒きません。
-- **XML を外に出さない**：返り値は型付きオブジェクト、入力も素直な JS の値。
-- **独自 OAuth を透過**：`code_direct` によるトークン取得・キャッシュ・更新を自動化。
-- **上限内に自制する**：スロットリング・リトライ（指数バックオフ）・リクエストサイズガード内蔵。
+- **型安全**：リソース・項目の値を型で表現。`any` を使いません。
+- **XML を外に出さない**：返り値は型付きオブジェクト、入力もふつうの JS の値。
+- **独自 OAuth を意識させない**：`code_direct` によるトークン取得・キャッシュ・更新を自動化。
+- **上限を守る**：スロットリング・リトライ（指数バックオフ）・リクエストの長さの検査を内蔵。
 - **日時は ISO 8601（UTC）に正規化**。業務タイムゾーン変換はしません（利用側の責務）。
-- **PORTERS の全リソースに対応**：データ系 13 種（Phase・Attachment を含む）＋ マスタ Read 5 種。
+- **PORTERS の全リソースに対応**：データ系 13 種（Phase・Attachment を含む）＋ マスタ系 5 種（読み取り専用）。
 
 ## 前提
 
-繋ぐ前に、**PORTERS 側で 4 つ**が要ります。揃っていないと 1 行も動きません。
+繋ぐ前に、**PORTERS 側で 4 つ**が要ります。揃っていないと PORTERS を呼べません。
 
 1. **PORTERS 契約 ＋ Connect API オプション契約**（オプションは別契約）。
 2. **API アプリの登録**。ここで Redirect URL を決め、**ホスト名・App ID・App Secret** が
-   通知されます（いずれも機密情報・ハードコード禁止）。
+   通知されます（いずれも機密情報なので、コードに直接書かず環境変数で渡します）。
 3. **初回のみブラウザで権限付与**（人手・Company DB ごとに 1 回）。以降はライブラリが
    `code_direct`（サーバ間）で無人運用します。
 4. **付与するスコープ**の決定（リソース別に `_r` / `_w`。Read でも複数要ることがあります）。
 
 揃えかたは[始める前に][s-prereq]に、権限付与の手順は[認証を通して、疎通を確認する][s-auth]に
-あります。実行環境は **Node.js 22.12 以上**で、型定義は同梱です。配るのは ESM 1 本ですが、
-CJS からも `require("@joymerrevent/porters-connect")` で読めます（[CJS から使う][s-cjs]）。
+あります。実行環境は **Node.js 22.12 以上**で、型定義は同梱です（型を読むには **TypeScript 5.4 以上**が要ります）。ビルド済みの JavaScript ファイルは ESM（`import`）の 1 つですが、
+CJS（`require`）からも `require("@joymerrevent/porters-connect")` で読めます（[CJS から使う][s-cjs]）。
 
 契約や権限付与を**待っている間**も、PORTERS に繋がずにコードとテストは書けます
-（[契約なしでテストを書きたい][test-without-contract]）。
+（[契約なしでテストする][test-without-contract]）。
 
 ## インストール
 
@@ -55,12 +54,12 @@ npm i @joymerrevent/porters-connect
 import { PortersClient } from "@joymerrevent/porters-connect";
 
 const porters = new PortersClient({
-  hostname: process.env.PORTERS_HOST ?? "", // 契約時に通知される値。ハードコード禁止
+  hostname: process.env.PORTERS_HOST ?? "", // 契約時に通知される値。コードに直接書かず環境変数で渡す
   appId: process.env.PORTERS_APP_ID ?? "",
   appSecret: process.env.PORTERS_APP_SECRET ?? "",
 });
 
-// partition（Company DB）は tenant で一度だけ束ねる。**単一テナントでもこの形**
+// partition（Company DB）は tenant(id) で指定する（既定の Partition は無い）。単一テナントでも同じ書き方
 const t = porters.tenant(456);
 
 const page = await t.candidate.search({
@@ -73,7 +72,7 @@ const page = await t.candidate.search({
 console.log(page.total, page.items[0]?.P_Name);
 ```
 
-続きは[入門][s-prereq]（6 ページ）へ。準備・認証・読み取り・書き込み・本番に出す前の確認まで順に進みます。
+続きは[導入][s-prereq]（6 ページ）へ。準備・認証・読み取り・書き込み・本番に出す前の確認まで順に進みます。
 
 ## リソースと操作
 
@@ -87,46 +86,51 @@ console.log(page.total, page.items[0]?.P_Name);
 | `t.opportunity` | 商談管理       | `t.phase`      | フェーズ履歴 |
 | `t.activity`    | アクティビティ |                |              |
 
-マスタ Read は `porters.partition` / `t.user` / `t.department` / `t.field` / `t.option` の 5 種（読み取り専用）。
+マスタ系は `porters.partition` / `t.user` / `t.department` / `t.field` / `t.option` の 5 種（読み取り専用）。
 
-**どのメソッドが呼べるかはリソースごとに違います**（`searchAll` が無いもの、先に `of()` で
-束ねるものがあります）。一覧は[リソースと操作][docs-resources]、引数・戻り値・項目の一覧は
-[API リファレンス][api-ref]が正典です。
+**どのメソッドが呼べるかはリソースごとに違います**（`searchAll` が無いもの、先に `of("candidate")` のように
+対象リソースを指定するもの（Field・Phase・Attachment）があります）。一覧は[リソースと操作][docs-resources]、引数・戻り値・項目の一覧は
+[API リファレンス][api-ref]が正確な定義です。
 
 ## ドキュメント
 
-**[docs/usage][docs-index] が目次**です。4 層に分かれています。
+**[docs/usage][docs-index] が目次**です。7 つの章に分かれていて、順に読むのは導入だけです。
 
-| 層               | 何が書いてあるか                                                                   |
-| ---------------- | ---------------------------------------------------------------------------------- |
-| **入門**         | 順に読む 6 ページ。準備 → 導入 → 認証と疎通 → 読み → 書き → 本番前                 |
-| **目的別**       | 「〜したい」から引く 9 ページ（検索・一括書き込み・添付・同期バッチ・テスト ほか） |
-| **考え方**       | PORTERS 固有の前提（Partition ／ alias と Data Type ／ UTC ／ 削除が無い ／ 上限） |
-| **リファレンス** | [公開 API の全記号][api-ref]（JSDoc から生成）と [PORTERS API の事実][ref]         |
+| 章               | 何が書いてあるか                                                                            |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| **導入**         | 順に読む 6 ページ。準備 → インストール → 認証と疎通 → 読み → 書き → 本番前                  |
+| **主題別**       | 認証・検索・書き込み・カスタム項目・上限……の 11 主題を、考え方から細かい規則まで 1 ページで |
+| **クライアント** | `PortersClient`・`auth`・`tenant(id)` のスコープ。構築オプションと呼べるメソッド            |
+| **リソース別**   | 18 リソースを 1 ページずつ。呼べるメソッド・固有の注意・必須項目・型                        |
+| **関数**         | `import` して呼ぶ関数を用途別に。宣言と突合・上限と接続・値の変換                           |
+| **実践例**       | 毎日の差分同期・複数テナントなど、用途に沿った組み立て                                      |
+| **リファレンス** | [公開 API リファレンス][api-ref]（JSDoc から生成）と [PORTERS API の事実][ref]              |
+
+目次の末尾に「〜したい → 読む場所」の索引表があります。
 
 ## PORTERS 固有の注意
 
 このライブラリを使ううえで、**PORTERS 側の前提**として先に知っておくと迷いません。詳しくは
-それぞれの「考え方」ページにあります。
+それぞれの主題ページの「まず知ること」にあります。
 
-- **削除 API が存在しない**。`delete()` は型の上でも生やしていません（[削除 API が無いということ][c-no-delete]）。
-- **日時は UTC 前提**。ISO 8601（`…Z`）で入出力し、JST 等への変換はしません（[日時は UTC][c-datetime]）。
-- **データは Partition に分かれる**。`tenant(id)` で毎回束ねます（[Partition とテナント][c-partition]）。
+- **削除 API が存在しない**。`delete()` は型の上でも用意していません（[削除と削除済みデータ][c-no-delete]）。
+- **日時は UTC 前提**。ISO 8601（`…Z`）で入出力し、JST 等への変換はしません（[日時と時分型][c-datetime]）。
+- **データは Partition に分かれる**。`tenant(id)` で毎回指定します（[Partition とテナントスコープ][c-partition]）。
 - **上限がある**。リクエスト長 約 15000 文字・1 リクエスト 200 件・1 分あたり Read 2000 / Write 500 は
-  ライブラリが自制しますが、**月 15 万アクセスは契約条件**で利用側の運用責務です（[上限][c-limits]）。
+  ライブラリが守りますが、**月 15 万アクセスは契約条件**で利用側の運用責務です（[上限とレート][c-limits]）。
 - **ホスト名は非公開**。`PORTERS_HOST` で受け取り、ハードコードしません。
 
 ## 対応バージョン
 
-- **契約は Connect API Version 2**：`X-P-ConnectAPI-Version: 2` を既定送信し、**v2 を動作の前提**とします（担当者型・部署型 Link 等は v2 必須）。互換性はこの **API version** で明示します。
-- **PORTERS 製品 8.x / 9.x は参考**：v2 が提供される製品世代です（個別マイナーの動作保証はしません）。**正典は [PORTERS API の事実][ref]**（実 API ドキュメントに接地）。
+- **互換性の基準は Connect API Version 2**：`X-P-ConnectAPI-Version: 2` を既定で送信し、**v2 を動作の前提**とします（担当者型・部署型の参照項目（Link）などは v2 が必要）。互換性はこの **API version** で明示します。
+- **PORTERS 製品 8.x / 9.x は参考**：v2 が提供される製品世代です（個別マイナーの動作保証はしません）。**正しい情報の出どころは [PORTERS API の事実][ref]**（PORTERS の公式ドキュメントに基づく）。
 
 ## リンク
 
-**この README は「最短で動かす」ところまで**です。網羅は目次側が担当します<!-- 根拠: ADR-0070 -->。
+**この README は「最短で動かす」ところまで**です。全体は目次から読めます<!-- 根拠: ADR-0070 -->。
 
-- 利用者向け：[docs/usage][docs-index]（目次）／[公開 API の全記号][api-ref]／[PORTERS API の事実][ref]
-- 開発・保守：[docs/README.md][docs-readme]（ADR・基本設計・ロードマップ・台帳への入口）
+- 利用者向け：[docs/usage][docs-index]（目次）／[公開 API リファレンス][api-ref]／[PORTERS API の事実][ref]
+- 開発・保守：[docs/README.md][docs-readme]（ADR（設計判断の記録）・基本設計・ロードマップ・台帳）
 - 提供元：[Joymerrevent][joymerrevent]
 
 ## コントリビュート / セキュリティ
@@ -156,15 +160,15 @@ console.log(page.total, page.items[0]?.P_Name);
 [coc]: ./CODE_OF_CONDUCT.md
 [issues]: https://github.com/Joymerrevent/porters-connect/issues
 [api-ref]: docs/usage/api/index.md
-[c-datetime]: docs/usage/concepts/datetime.md
-[c-limits]: docs/usage/concepts/limits.md
-[c-no-delete]: docs/usage/concepts/no-delete.md
-[c-partition]: docs/usage/concepts/partition.md
+[c-datetime]: docs/usage/topics/datetime.md
+[c-limits]: docs/usage/topics/limits.md
+[c-no-delete]: docs/usage/topics/deleted.md
+[c-partition]: docs/usage/topics/tenant.md
 [s-auth]: docs/usage/start/authenticate.md
 [s-cjs]: docs/usage/start/install.md#cjs-から-require-する
 [s-prereq]: docs/usage/start/prerequisites.md
-[test-without-contract]: docs/usage/howto/test-without-contract.md
+[test-without-contract]: docs/usage/topics/testing.md
 [docs-index]: docs/usage/index.md
-[docs-resources]: docs/usage/index.md#リソースと操作
+[docs-resources]: docs/usage/resources/README.md
 [docs-readme]: ./docs/README.md
 [ref]: docs/usage/reference/README.md