@joymerrevent/porters-connect 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-08-20
+
+**Candidate でメモ・住所詳細が扱えるようになった版**です。標準項目でありながらカタログから漏れていた
+4 項目を追加し、同じ取りこぼしが二度と起きないよう reference との突合を CI で検査するようにしました。
+併せて `defineFields` と Read クエリの**利用ガイドを新設**しています。
+
+### Added
+
+- **Candidate に標準 4 項目**（`P_Memo`（メモ）／`P_Street`（住所詳細）／`P_Fax`（FAX）／`P_PhaseMemo`（フェーズメモ））。
+  カタログが型の真実源（[ADR-0019][adr19]）なので、これまで **`Candidate` 型にも `CandidateCreateInput` /
+  `CandidateUpdateInput` にも現れず**、`candidate.create({ P_Memo: "…" })` は型エラーでした。
+  `field` 省略時の既定 field（[ADR-0020][adr20]）にも含まれないため **Read でも取得されません**でした。
+  同じ 4 種は Client には最初から載っており、リソース間で非一貫でした。
+  - `field` を省略した Read は**既定 field が 4 つ増えるぶん URL が長くなります**（Candidate で約 100 文字）。
+- **公開ジェネリクスの制約型を export**（`DeclaredCatalogs` / `CustomFor` / `CustomFieldResource`）。
+  `PortersClient<C>` / `TenantScope<C>` は公開型なのに制約側が非公開で、
+  クライアントを引数に取るヘルパーの型を**名前で書けません**でした（`typeof porters` での回避のみ）。
+  型の追加のみで、既存コードへの影響はありません。
+- **利用ガイドを 2 本新設**（[ADR-0035][adr35] の型）。
+  - [カスタム項目ガイド][custom-fields-guide] — `defineFields` の宣言、**宣言しないとどうなるか**
+    （型が付かず `field` 省略時に取得されない）、宣言できる 11 の Data Type、
+    Field Read でテナントの項目を調べる手順、複数テナントでの使い分け。
+  - [Read クエリ ガイド][read-query-guide] — `field` の 3 通りの意味、**Data Type ごとの演算子一覧**、
+    削除済み Read の制約（condition は 3 項目・90 日以内）、送信前に落ちるものの一覧。
+
+### Changed
+
+- **Read の `count` が範囲外なら送信前に落ちます**。`count` は PORTERS 上 **1〜200**（既定 10）ですが、
+  これまで範囲外の値をそのまま送っており、不透明なサーバー応答に倒れていました。
+  今後は `PortersConfigError`（`category: "config"` ＋ `searchAll()` を案内する `hint`）で**リクエストの前に**弾きます。
+  整数でない値（`1.5` など）も同様です。
+  - keywords の 100 文字・itemstate の condition 制限・リクエスト長 ~15000 字と同じ
+    「早く・明確に落とす」系列に揃いました。データ系・マスタ系・Attachment の**すべての Read 経路**に効きます。
+  - `count` を省略した場合の挙動は変わりません（API 既定に委ねます）。
+
+### Fixed
+
+- **reference と静的カタログの突合を CI で検査**するようになりました。値を持つ標準項目の取りこぼし・
+  カタログ側の幻の項目・Field Type → Data Type の取り違えを検出します。
+  上記 Candidate の欠落は **0.1.0 から 12 版・563 テストをすべて素通り**していたため、
+  人の目ではなく仕組みで守ります。
+
 ## [0.8.0] - 2026-08-14
 
 **「0 件」と「届いていない」を区別できるようにした版**です。HTTP 200 を返す中間装置
@@ -241,9 +283,15 @@
 [adr51]: docs/adr/0051-read-envelope-identification.md
 [adr47]: docs/adr/0047-access-point-scheme.md
 [oauth-guide]: docs/guide/oauth.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/guide/custom-fields.md
+[read-query-guide]: docs/guide/read-query.md
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
-[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.8.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.6.2...v0.7.0
 [0.6.2]: https://github.com/Joymerrevent/porters-connect/compare/v0.6.1...v0.6.2

package/README.md

@@ -192,10 +192,40 @@ await porters.auth.exchangeAuthorizationCode(code);
 - `order`：並び順。`[{ 項目: "asc" | "desc" }]`（数値・日時・System 型のみ）。
 - `keywords`：テキスト項目のキーワード AND 検索（`string[]`・カンマ込み **100 文字まで**）。
 - `itemstate`：`"existing"`（既定）/ `"deleted"` / `"all"`。削除済みデータの取得。
-- `count`（1–200・既定 10）、`start`（0 始まり）。
+- `count`（1–200・既定 10）、`start`（0 始まり）。**範囲外の `count` は送信前に `PortersConfigError`** で落ちます。
 
 > **削除 API はありません**（PORTERS 仕様）。`delete()` メソッドは提供しません。削除済みは `itemstate: "deleted"` で読みます
 > （`condition` は `P_Id` / `P_UpdateDate` / `P_UpdatedBy` に限られ、更新日は 90 日以内）。
+>
+> `field` の 3 通りの意味（省略＝全項目 / `[]`＝主キーのみ / 明示）、Data Type ごとの演算子一覧、
+> 削除済み Read の制約、送信前に落ちる条件は [Read クエリ ガイド][read-query-guide] にまとめています。
+
+### カスタム項目（`U_` / `A_`）
+
+テナント固有のカスタム項目は `defineFields` で宣言すると、**読み書きの型に現れ**、Data Type どおりに変換されます。
+
+```ts
+import { PortersClient, defineFields } from "@joymerrevent/porters-connect";
+
+const fields = defineFields({
+  candidate: (f) => ({ U_score: f.number(), U_source: f.option() }),
+});
+const porters = new PortersClient({
+  host,
+  appId,
+  appSecret,
+  partition,
+  fields,
+});
+
+const one = await porters.candidate.get(10001);
+one?.U_score; // number | null | undefined
+```
+
+宣言しなくても読み書きはできますが（生の文字列として通ります）、**型が付かず、`field` 省略時に取得もされません**。
+
+> 宣言できる型の一覧、テナントの項目を Field Read で調べる方法、複数テナントでの扱いは
+> [カスタム項目 ガイド][custom-fields-guide] にまとめています。
 
 ### マスタ Read（読み取り専用）
 
@@ -407,6 +437,8 @@ try {
 [auth-flow]: ./docs/reference/authentication-api/README.md
 [oauth-guide]: ./docs/guide/oauth.md
 [error-handling]: ./docs/guide/error-handling.md
+[custom-fields-guide]: ./docs/guide/custom-fields.md
+[read-query-guide]: ./docs/guide/read-query.md
 [multi-tenancy]: ./docs/guide/multi-tenancy.md
 [bulk-write]: ./docs/guide/bulk-write.md
 [sandbox]: ./examples/offline-sandbox.ts

package/dist/index.d.ts

@@ -332,15 +332,19 @@ declare const FIELDS$8: {
     readonly P_UpdatedBy: "User";
     readonly P_Phase: "Option";
     readonly P_PhaseDate: "DateTime";
+    readonly P_PhaseMemo: "MultilineText";
     readonly P_Name: "SinglelineText";
     readonly P_Reading: "SinglelineText";
+    readonly P_Memo: "MultilineText";
     readonly P_Mail: "Mail";
     readonly P_MobileMail: "Mail";
     readonly P_Telephone: "Telephone";
     readonly P_Mobile: "Telephone";
+    readonly P_Fax: "Telephone";
     readonly P_Country: "SinglelineText";
     readonly P_Prefecture: "SinglelineText";
     readonly P_City: "SinglelineText";
+    readonly P_Street: "MultilineText";
     readonly P_Zipcode: "SinglelineText";
 };
 declare const REQUIRED_ON_CREATE$4: readonly ["P_Owner"];
@@ -901,4 +905,4 @@ declare const bytesToBase64: (bytes: Uint8Array) => string;
 /** Decode a Base64 string back to raw bytes. */
 declare const base64ToBytes: (b64: string) => Uint8Array;
 
-export { type Attachment, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type AuthApi, type AuthorizationUrlOptions, type BulkWriteResult, type BulkWriteResultItem, type Candidate, type CandidateCreateInput, type CandidatePage, type CandidateResource, type CandidateSearchQuery, type CandidateUpdateInput, type Client, type ClientCreateInput, type ClientPage, type ClientResource, type ClientSearchQuery, type ClientUpdateInput, type Condition, type CustomDataType, type DefinedFields, type ErrorCategory, type Field, type FieldBuilder, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldValue, type GetAccessTokenOptions, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type MockHandler, type MockReply, type MockTransportOptions, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, PortersAuthError, PortersClient, type PortersClientOptions, PortersConfigError, PortersError, type PortersErrorContext, type PortersErrorOptions, PortersNetworkError, PortersResourceError, type Process, type ProcessCreateInput, type ProcessPage, type ProcessResource, type ProcessSearchQuery, type ProcessUpdateInput, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Scheme, type Scope, type SearchQuery, type StoredTokens, type TenantScope, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, base64ToBytes, bytesToBase64, createMockTransport, defineFields };
+export { type Attachment, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type AuthApi, type AuthorizationUrlOptions, type BulkWriteResult, type BulkWriteResultItem, type Candidate, type CandidateCreateInput, type CandidatePage, type CandidateResource, type CandidateSearchQuery, type CandidateUpdateInput, type Client, type ClientCreateInput, type ClientPage, type ClientResource, type ClientSearchQuery, type ClientUpdateInput, type Condition, type CustomDataType, type CustomFieldResource, type CustomFor, type DeclaredCatalogs, type DefinedFields, type ErrorCategory, type Field, type FieldBuilder, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldValue, type GetAccessTokenOptions, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type MockHandler, type MockReply, type MockTransportOptions, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, PortersAuthError, PortersClient, type PortersClientOptions, PortersConfigError, PortersError, type PortersErrorContext, type PortersErrorOptions, PortersNetworkError, PortersResourceError, type Process, type ProcessCreateInput, type ProcessPage, type ProcessResource, type ProcessSearchQuery, type ProcessUpdateInput, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Scheme, type Scope, type SearchQuery, type StoredTokens, type TenantScope, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, base64ToBytes, bytesToBase64, createMockTransport, defineFields };

package/dist/index.js

@@ -846,7 +846,24 @@ var runRead = (requester, resource, url, decode) => requester.request({ method:
     start: page.start
   };
 });
-var PAGE_SIZE = 200;
+var MIN_READ_COUNT = 1;
+var MAX_READ_COUNT = 200;
+var PAGE_SIZE = MAX_READ_COUNT;
+var appendPaging = (p, count, start) => {
+  if (count !== void 0) {
+    if (!Number.isInteger(count) || count < MIN_READ_COUNT || count > MAX_READ_COUNT) {
+      throw new PortersConfigError(
+        `count must be an integer between ${MIN_READ_COUNT} and ${MAX_READ_COUNT}, got ${count}`,
+        {
+          category: "config",
+          hint: `PORTERS returns 1\u2013${MAX_READ_COUNT} records per Read. Use searchAll() to walk every page instead of raising count.`
+        }
+      );
+    }
+    p.set("count", String(count));
+  }
+  if (start !== void 0) p.set("start", String(start));
+};
 var paginate = async function* (fetchPage) {
   let start = 0;
   for (; ; ) {
@@ -1043,8 +1060,7 @@ var buildReadUrl = (accessPoint, partition, path, q, ctx) => {
   p.set("partition", String(partition));
   if (q.field && q.field.length > 0) p.set("field", q.field.join(","));
   appendReadQuery(p, q, ctx);
-  if (q.count !== void 0) p.set("count", String(q.count));
-  if (q.start !== void 0) p.set("start", String(q.start));
+  appendPaging(p, q.count, q.start);
   return apiUrl(accessPoint, path, p);
 };
 var buildWriteUrl = (accessPoint, partition, path) => apiUrl(
@@ -1122,15 +1138,19 @@ var FIELDS = {
   P_UpdatedBy: "User",
   P_Phase: "Option",
   P_PhaseDate: "DateTime",
+  P_PhaseMemo: "MultilineText",
   P_Name: "SinglelineText",
   P_Reading: "SinglelineText",
+  P_Memo: "MultilineText",
   P_Mail: "Mail",
   P_MobileMail: "Mail",
   P_Telephone: "Telephone",
   P_Mobile: "Telephone",
+  P_Fax: "Telephone",
   P_Country: "SinglelineText",
   P_Prefecture: "SinglelineText",
   P_City: "SinglelineText",
+  P_Street: "MultilineText",
   P_Zipcode: "SinglelineText"
 };
 var REQUIRED_ON_CREATE = [
@@ -1365,8 +1385,7 @@ var buildAttachmentReadUrl = (accessPoint, partition, q) => {
     const conds = Object.entries(q.condition).map(([k, v]) => `${k}=${v}`);
     if (conds.length > 0) p.set("condition", conds.join(","));
   }
-  if (q.count !== void 0) p.set("count", String(q.count));
-  if (q.start !== void 0) p.set("start", String(q.start));
+  appendPaging(p, q.count, q.start);
   return apiUrl(accessPoint, "attachment", p);
 };
 var numOrNull = (v) => {
@@ -1461,8 +1480,7 @@ var PARTITION_DESCRIPTOR = {
 var buildUrl = (accessPoint, q) => {
   const p = new URLSearchParams();
   p.set("request_type", String(q.requestType ?? 1));
-  if (q.count !== void 0) p.set("count", String(q.count));
-  if (q.start !== void 0) p.set("start", String(q.start));
+  appendPaging(p, q.count, q.start);
   return apiUrl(accessPoint, "partition", p);
 };
 var createPartitionResource = (deps) => {
@@ -1496,8 +1514,7 @@ var buildUrl2 = (accessPoint, partition, q) => {
   p.set("request_type", String(q.requestType ?? 1));
   p.set("user_type", String(q.userType ?? -1));
   if (q.field && q.field.length > 0) p.set("field", q.field.join(","));
-  if (q.count !== void 0) p.set("count", String(q.count));
-  if (q.start !== void 0) p.set("start", String(q.start));
+  appendPaging(p, q.count, q.start);
   return apiUrl(accessPoint, "user", p);
 };
 var createUserResource = (deps) => {
@@ -1552,8 +1569,7 @@ var buildUrl3 = (accessPoint, partition, q) => {
   p.set("partition", String(partition));
   p.set("resource", String(RESOURCE_VALUE[q.resource]));
   p.set("active", String(q.active ?? -1));
-  if (q.count !== void 0) p.set("count", String(q.count));
-  if (q.start !== void 0) p.set("start", String(q.start));
+  appendPaging(p, q.count, q.start);
   return apiUrl(accessPoint, "field", p);
 };
 var createFieldResource = (deps) => {
@@ -1589,7 +1605,7 @@ var buildUrl4 = (accessPoint, partition, q) => {
   if (q.alias !== void 0) p.set("alias", q.alias);
   if (q.level !== void 0) p.set("level", String(q.level));
   if (q.enabled !== void 0) p.set("enabled", String(q.enabled));
-  if (q.count !== void 0) p.set("count", String(q.count));
+  appendPaging(p, q.count);
   return apiUrl(accessPoint, "option", p);
 };
 var withoutItems = (raw) => Object.fromEntries(Object.entries(raw).filter(([k]) => k !== "Items"));