@joymerrevent/porters-connect 0.19.0 → 0.19.1

package/CHANGELOG.md

@@ -5,6 +5,68 @@
 
 ## [Unreleased]
 
+## [0.19.1] - 2026-09-20
+
+**定期レビューで見つけた 7 件を塞いだ版**です。破壊的変更はありません。公開 API の形は変わらず、
+**壊れたときの倒れ方**が変わります。
+
+いちばん重いのは **Option の選択肢 alias から書き込み XML を注入できた**こと。PORTERS は Option の値を
+**タグ名**として書くため（`<FieldAlias><OptionAlias/></FieldAlias>`）、その値を検証していないと
+**呼び出し側が指定していないレコードが書き換わり**ます。要素名はエスケープできないので、検証して弾く形にしました
+（[ADR-0085][adr85]）。
+
+### Security
+
+- **Option の選択肢 alias と書き込み項目 alias を、XML の名前として妥当か検証するようになりました**
+  （[ADR-0085][adr85]）。公開型が `string[]` なので cast なしで到達でき、`<Item>` を閉じて開き直す文字列を
+  渡すと **well-formed な XML に別レコードを名指す `<Item>` を注入**できていました（更新先が
+  すり替わる／頼んでいない項目が書き足される）。
+
+  ```ts
+  await t.candidate.update(10001, { P_Phase: [userInput] });
+  // 不正なら送信前に PortersConfigError（category: "validation"）
+  ```
+
+  通るのは **XML の `Name`**（英数字・`_`・`-`・`.`・日本語など。先頭に数字や `-` は置けません）。
+  出典が alias の書式を定めていないので**XML が許すものはすべて許します** — `Option.P_東京` のような
+  alias も従来どおり書けます。**本文になる値（テキスト項目など）の扱いは変わりません。**
+
+### Fixed
+
+- **`createThrottle` が実質 0 件の上限を受け付けて永久に待つのをやめました**。バケットのトークンは
+  `floor(上限 × safety)` 個で、既定 `safety` は 0.9。そのため `createThrottle({ readPerMin: 1 })` は
+  容量 0 になり、**すべての呼び出しが返らなく**なっていました（例外もログも無し）。
+
+  ```ts
+  createThrottle({ readPerMin: 1 }); // PortersConfigError（floor(1 × 0.9) = 0）
+  createThrottle({ readPerMin: 2 }); // OK（floor(1.8) = 1）
+  ```
+
+  `readPerMin` / `writePerMin` は**正の整数**、`safety` は **0 より大きく 1 以下**。加えて
+  **積が 1 以上**であることを見ます。「1 件も通さない」は `take()` が解決しない `Throttle` を
+  自分で渡してください。
+
+- **XML の解析に失敗したとき、例外が必ず `PortersError` になるようになりました**。
+  `fast-xml-parser` は `prototype` / `constructor` / `__proto__` をタグ名として拒否します。
+  これらは妥当な XML Name なので書き込みは通り、**読み取りだけ**が素の `Error` で落ちていました
+  — `catch (e) { if (e instanceof PortersError) … }` に**引っかからず**、アプリの最上位まで
+  素通りします。Read は `PortersResourceError`、認証は `PortersAuthError` に包み、パーサ自身の
+  説明は `cause` に残します。壊れた XML も同じ経路になりました。
+
+- **公開 API リファレンス**（`docs/usage/api/`）に残っていた日本語を英語に直しました。
+  公開サーフェスの JSDoc は英語、README とガイドは日本語ファースト、という切り分けは変わりません。
+
+### Changed
+
+- **CI が `engines` の下限そのものを走らせるようになりました**。`engines.node` は `>=22.12.0` を
+  約束していますが、テストの Node マトリクスは `22`（その時点の 22 系最新に解決される）だったため、
+  **22.12.0 は一度も走っていません**でした。Node 22.12.0 で動かしている場合、そのバージョンが
+  実際に検証されるようになります。
+
+- 内部の検査を 2 本増やしました（利用者への影響はありません）。契約後に実機確認する仮定と
+  コード側のコメントの対応を双方向で見る検査と、リファレンスへの日本語混入を見る検査です。
+  前者では**コードに仮定があるのに一覧に無いもの**が 3 件見つかり、起票しました。
+
 ## [0.19.0] - 2026-09-18
 
 **CJS からの入口を開け、Node の下限を 22.12 に上げた版**です。**破壊的変更を 1 つ**含みます
@@ -1062,11 +1124,13 @@ Attachment）あるのに、受け口の形が 3 つとも違っていました
 [adr82]: docs/adr/0082-module-format-and-node-baseline.md
 [limits]: docs/usage/concepts/limits.md
 [failures]: docs/usage/howto/handle-failures.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.19.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.19.1...HEAD
+[0.19.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.19.0...v0.19.1
 [0.19.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.17.0...v0.18.0
 [0.17.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.16.0...v0.17.0

package/dist/index.d.cts

@@ -110,9 +110,22 @@ type Throttle = {
     take(write: boolean): Promise<void>;
 };
 type ThrottleOptions = {
+    /**
+     * Reads allowed per minute before headroom. Default 2000 (PORTERS' own cap). A positive
+     * integer, and **`readPerMin * safety` must still leave at least one token** — see
+     * {@link ThrottleOptions.safety}.
+     */
     readPerMin?: number;
+    /** Writes allowed per minute before headroom. Default 500. Same rules as `readPerMin`. */
     writePerMin?: number;
-    /** Fraction of the limit to actually use (headroom). Default 0.9. */
+    /**
+     * Fraction of the limit to actually use (headroom). Default 0.9. Greater than 0, at most 1.
+     *
+     * The bucket holds `floor(limit * safety)` tokens, so a small limit and a small `safety`
+     * multiply into **zero capacity** — `{ readPerMin: 1 }` at the default 0.9 already does.
+     * A bucket that can never hold a token would make every call wait forever, so the
+     * combination is rejected at construction rather than hanging (RV-49).
+     */
     safety?: number;
     now?: () => number;
 };
@@ -1736,8 +1749,8 @@ type SalesPage = ResourcePage<typeof FIELDS$7>;
 type SalesSearchQuery = SearchQuery<typeof FIELDS$7, typeof REFERENCES$2>;
 /**
  * Fields for `create`: only `P_Owner` is unconditionally required. The six references are
- * required *conditionally* (a dependency chain PORTERS validates server-side) — see the
- * module comment and docs/usage/concepts/limits.md.
+ * required *conditionally* (a dependency chain PORTERS validates server-side), so they stay
+ * optional here (ADR-0083) — see the module comment and docs/usage/concepts/limits.md.
  */
 type SalesCreateInput = CreateInput<typeof FIELDS$7, (typeof REQUIRED_ON_CREATE$3)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
@@ -2337,8 +2350,8 @@ type AttachmentUpdate = {
  *
  * ```ts
  * const files = t.attachment.of("resume");
- * await files.search({ resourceId: 10006 }); // メタデータだけ
- * await files.get(900); // 本体つき
+ * await files.search({ resourceId: 10006 }); // metadata only
+ * await files.get(900); // with the file body
  * ```
  *
  * PORTERS requires `resource=` on every Attachment Read, and the same value goes into the
@@ -2646,7 +2659,7 @@ type ReadCustomCatalogOptions = {
      * The default is `-1` deliberately. Narrowing to `1` would hide fields that exist but are
      * unused, and a comparison against a declaration would then report them as **missing** — a
      * false alarm. `generateFieldDecls` overrides it to `1`, where "only what is in use" is what
-     * you want in a template (ADR-0069, accept 時の決定).
+     * you want in a template (ADR-0069, decided on accept).
      */
     readonly active?: -1 | 0 | 1;
 };
@@ -2669,7 +2682,7 @@ type GenerateFieldDeclsOptions = {
      * Field Read's `active` filter. Defaults to `1` — **in-use fields only**, which is what belongs
      * in a template; there is no reason to declare a field the tenant is not using. This is the
      * opposite of `verifyFields`, where narrowing would cause false "missing" reports
-     * (ADR-0069, accept 時の決定).
+     * (ADR-0069, decided on accept).
      */
     readonly active?: -1 | 0 | 1;
     /**
@@ -2758,7 +2771,7 @@ type VerifyFieldsOptions = {
     /**
      * Field Read's `active` filter. Defaults to `-1` (every field) and should stay there: with `1`
      * a field that exists but is currently unused is absent from the response, and its declaration
-     * would be reported as {@link MissingField} — a false alarm (ADR-0069, accept 時の決定).
+     * would be reported as {@link MissingField} — a false alarm (ADR-0069, decided on accept).
      */
     readonly active?: -1 | 0 | 1;
 };

package/dist/index.d.ts

@@ -110,9 +110,22 @@ type Throttle = {
     take(write: boolean): Promise<void>;
 };
 type ThrottleOptions = {
+    /**
+     * Reads allowed per minute before headroom. Default 2000 (PORTERS' own cap). A positive
+     * integer, and **`readPerMin * safety` must still leave at least one token** — see
+     * {@link ThrottleOptions.safety}.
+     */
     readPerMin?: number;
+    /** Writes allowed per minute before headroom. Default 500. Same rules as `readPerMin`. */
     writePerMin?: number;
-    /** Fraction of the limit to actually use (headroom). Default 0.9. */
+    /**
+     * Fraction of the limit to actually use (headroom). Default 0.9. Greater than 0, at most 1.
+     *
+     * The bucket holds `floor(limit * safety)` tokens, so a small limit and a small `safety`
+     * multiply into **zero capacity** — `{ readPerMin: 1 }` at the default 0.9 already does.
+     * A bucket that can never hold a token would make every call wait forever, so the
+     * combination is rejected at construction rather than hanging (RV-49).
+     */
     safety?: number;
     now?: () => number;
 };
@@ -1736,8 +1749,8 @@ type SalesPage = ResourcePage<typeof FIELDS$7>;
 type SalesSearchQuery = SearchQuery<typeof FIELDS$7, typeof REFERENCES$2>;
 /**
  * Fields for `create`: only `P_Owner` is unconditionally required. The six references are
- * required *conditionally* (a dependency chain PORTERS validates server-side) — see the
- * module comment and docs/usage/concepts/limits.md.
+ * required *conditionally* (a dependency chain PORTERS validates server-side), so they stay
+ * optional here (ADR-0083) — see the module comment and docs/usage/concepts/limits.md.
  */
 type SalesCreateInput = CreateInput<typeof FIELDS$7, (typeof REQUIRED_ON_CREATE$3)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
@@ -2337,8 +2350,8 @@ type AttachmentUpdate = {
  *
  * ```ts
  * const files = t.attachment.of("resume");
- * await files.search({ resourceId: 10006 }); // メタデータだけ
- * await files.get(900); // 本体つき
+ * await files.search({ resourceId: 10006 }); // metadata only
+ * await files.get(900); // with the file body
  * ```
  *
  * PORTERS requires `resource=` on every Attachment Read, and the same value goes into the
@@ -2646,7 +2659,7 @@ type ReadCustomCatalogOptions = {
      * The default is `-1` deliberately. Narrowing to `1` would hide fields that exist but are
      * unused, and a comparison against a declaration would then report them as **missing** — a
      * false alarm. `generateFieldDecls` overrides it to `1`, where "only what is in use" is what
-     * you want in a template (ADR-0069, accept 時の決定).
+     * you want in a template (ADR-0069, decided on accept).
      */
     readonly active?: -1 | 0 | 1;
 };
@@ -2669,7 +2682,7 @@ type GenerateFieldDeclsOptions = {
      * Field Read's `active` filter. Defaults to `1` — **in-use fields only**, which is what belongs
      * in a template; there is no reason to declare a field the tenant is not using. This is the
      * opposite of `verifyFields`, where narrowing would cause false "missing" reports
-     * (ADR-0069, accept 時の決定).
+     * (ADR-0069, decided on accept).
      */
     readonly active?: -1 | 0 | 1;
     /**
@@ -2758,7 +2771,7 @@ type VerifyFieldsOptions = {
     /**
      * Field Read's `active` filter. Defaults to `-1` (every field) and should stay there: with `1`
      * a field that exists but is currently unused is absent from the response, and its declaration
-     * would be reported as {@link MissingField} — a false alarm (ADR-0069, accept 時の決定).
+     * would be reported as {@link MissingField} — a false alarm (ADR-0069, decided on accept).
      */
     readonly active?: -1 | 0 | 1;
 };

package/dist/index.js

@@ -265,6 +265,30 @@ var createMockTransport = (handler, options = {}) => {
 
 // src/http/throttle.ts
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var capacityOf = (limit, safety, option) => {
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new PortersConfigError(
+      `${option} must be a positive integer, got ${JSON.stringify(limit)}`,
+      {
+        category: "config",
+        hint: "Pass requests per minute (defaults: readPerMin 2000, writePerMin 500)."
+      }
+    );
+  }
+  const capacity = Math.floor(limit * safety);
+  if (capacity < 1) {
+    throw new PortersConfigError(
+      `${option} ${limit} with safety ${safety} leaves no capacity (floor(${limit * safety}) = 0), so every call would wait forever`,
+      {
+        category: "config",
+        // 「まったく通さない」を表現したいなら、それ専用の Throttle を書くのが正しい道。
+        // 上限 0 を黙って受けて永久に待つのは、許可と沈黙を混ぜる形（ADR-0047 と同じ考え）。
+        hint: `Raise ${option} to at least ${Math.ceil(1 / safety)} at this safety, or raise safety. To block every request on purpose, pass your own Throttle whose take() never resolves.`
+      }
+    );
+  }
+  return capacity;
+};
 var makeBucket = (capacity, now) => {
   const ratePerMs = capacity / 6e4;
   let tokens = capacity;
@@ -284,9 +308,24 @@ var makeBucket = (capacity, now) => {
 };
 var createThrottle = (opts = {}) => {
   const safety = opts.safety ?? 0.9;
+  if (!(safety > 0) || safety > 1) {
+    throw new PortersConfigError(
+      `safety must be greater than 0 and at most 1, got ${JSON.stringify(opts.safety)}`,
+      {
+        category: "config",
+        hint: "safety is the fraction of the limit to use (default 0.9 = 90%). Use 1 to run right at PORTERS' cap."
+      }
+    );
+  }
   const now = opts.now ?? (() => Date.now());
-  const read = makeBucket(Math.floor((opts.readPerMin ?? 2e3) * safety), now);
-  const write = makeBucket(Math.floor((opts.writePerMin ?? 500) * safety), now);
+  const read = makeBucket(
+    capacityOf(opts.readPerMin ?? 2e3, safety, "readPerMin"),
+    now
+  );
+  const write = makeBucket(
+    capacityOf(opts.writePerMin ?? 500, safety, "writePerMin"),
+    now
+  );
   return { take: (isWrite) => isWrite ? write() : read() };
 };
 var createThrottleRegistry = (make = () => createThrottle()) => {
@@ -415,19 +454,28 @@ var parser = new XMLParser({
   // Stryker disable next-line ArrowFunction,ConditionalExpression,StringLiteral: equivalent — asArray() normalizes regardless
   isArray: (name) => name === "Item"
 });
+var parseXml = (xml, unparseable) => {
+  try {
+    return parser.parse(xml);
+  } catch (cause) {
+    throw unparseable(cause);
+  }
+};
 var toInt = (v) => {
   const s = asString(v);
   return s === void 0 ? 0 : Number(s);
 };
 var MIDDLEBOX_HINT = "A middlebox (proxy, captive portal, SSO login page, WAF notice) may be answering instead of PORTERS. Check PORTERS_HOST and the network path from this process to the API.";
 var parseResourcePage = (xml, resource) => {
-  const root = asRecord(parser.parse(xml));
+  const unparseable = (cause) => new PortersResourceError("unparseable resource response", {
+    category: "unknown",
+    cause
+  });
+  const root = asRecord(parseXml(xml, unparseable));
   const rootKey = root ? Object.keys(root)[0] : void 0;
   const body = root && rootKey ? asRecord(root[rootKey]) : void 0;
   if (!body) {
-    throw new PortersResourceError("unparseable resource response", {
-      category: "unknown"
-    });
+    throw unparseable();
   }
   if (rootKey !== resource) {
     throw new PortersResourceError(
@@ -453,13 +501,15 @@ var parseResourcePage = (xml, resource) => {
   };
 };
 var parseWriteResult = (xml) => {
-  const root = asRecord(parser.parse(xml));
+  const unparseable = (cause) => new PortersResourceError("unparseable write response", {
+    category: "unknown",
+    cause
+  });
+  const root = asRecord(parseXml(xml, unparseable));
   const rootKey = root ? Object.keys(root)[0] : void 0;
   const body = root && rootKey ? asRecord(root[rootKey]) : void 0;
   if (!body) {
-    throw new PortersResourceError("unparseable write response", {
-      category: "unknown"
-    });
+    throw unparseable();
   }
   const code = toInt(body.Code);
   if (code !== 0) {
@@ -474,12 +524,14 @@ var parseWriteResult = (xml) => {
   });
 };
 var parseAuthentication = (xml) => {
-  const root = asRecord(parser.parse(xml));
+  const unparseable = (cause) => new PortersAuthError("unparseable authentication response", {
+    category: "unknown",
+    cause
+  });
+  const root = asRecord(parseXml(xml, unparseable));
   const body = root ? asRecord(root.Authentication) : void 0;
   if (!body) {
-    throw new PortersAuthError("unparseable authentication response", {
-      category: "unknown"
-    });
+    throw unparseable();
   }
   const error = toInt(body.Error);
   if (error !== 0) {
@@ -978,6 +1030,12 @@ var paginateOnce = async function* (prepare) {
   yield* paginate(prepare());
 };
 
+// src/util/xml-name.ts
+var NAME_START_CHAR = ":A-Z_a-z\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u02FF\\u0370-\\u037D\\u037F-\\u1FFF\\u200C-\\u200D\\u2070-\\u218F\\u2C00-\\u2FEF\\u3001-\\uD7FF\\uF900-\\uFDCF\\uFDF0-\\uFFFD\\u{10000}-\\u{EFFFF}";
+var NAME_CHAR = NAME_START_CHAR + "\\-.0-9\\u00B7\\u0300-\\u036F\\u203F-\\u2040";
+var XML_NAME = new RegExp(`^[${NAME_START_CHAR}][${NAME_CHAR}]*$`, "u");
+var isXmlName = (value) => XML_NAME.test(value);
+
 // src/xml/encode.ts
 var IMAGE_CONTENT_TYPES = [
   "image/jpeg",
@@ -989,6 +1047,19 @@ var escapeXml = (s) => s.replace(
   /[&<>]/g,
   (c) => c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"
 );
+var assertTagName = (name, kind, alias) => {
+  if (isXmlName(name)) return;
+  throw new PortersConfigError(
+    `${alias}: ${kind} ${JSON.stringify(name)} is not a valid XML element name`,
+    {
+      category: "validation",
+      // PORTERS writes this value as a tag (`<FieldAlias><OptionAlias/></FieldAlias>`), so an
+      // arbitrary string cannot be sent. Say that, and say where a real one comes from.
+      hint: "PORTERS writes it as an XML element name, so it must be a valid XML Name (letters, digits, `_`, `-`, `.`, no spaces or markup). Option aliases come from the Option master (`t.option`) or the field's option list in the reference.",
+      context: { operation: "encode" }
+    }
+  );
+};
 var text = (v) => typeof v === "object" && !Array.isArray(v) ? JSON.stringify(v) : String(v);
 var scalar = (v) => escapeXml(text(v));
 var IMAGE_SUBFIELDS = [
@@ -1025,7 +1096,10 @@ var encodeField = (type, value, alias) => {
     // array (ADR-0017, symmetric with read); a lone string is wrapped as a 1-element
     // selection (fail-safe).
     case "Option":
-      return (Array.isArray(value) ? value : [text(value)]).map((alias2) => `<${alias2}/>`).join("");
+      return (Array.isArray(value) ? value : [text(value)]).map((selected) => {
+        assertTagName(selected, "option alias", alias);
+        return `<${selected}/>`;
+      }).join("");
     // System[DateTime] (registration/update) is Write-restricted by PORTERS; we still
     // serialize it identically — rejecting the write is the input type's job (SD-3).
     case "DateTime":
@@ -1065,6 +1139,7 @@ var encodeItem = (prefix, fields, item) => {
   const parts = [];
   for (const [alias, value] of Object.entries(item)) {
     if (value === null || value === void 0) continue;
+    assertTagName(alias, "field alias", alias);
     const type = fields.get(alias);
     const inner = type === void 0 || type === null ? scalar(value) : encodeField(type, value, alias);
     const tag2 = qualify(prefix, alias);
@@ -1860,7 +1935,8 @@ var FIELDS7 = {
   P_Memo: "MultilineText",
   // VERIFY(live): participants is a `User` field that can hold several people. Whether the
   // Read response repeats the nested <User> element (and how) is unconfirmed; the decoder
-  // takes the first, like every other User field. See docs/live-verification.md.
+  // takes the first, like every other User field — so a second participant would be dropped
+  // silently. docs/live-verification.md (LV-27).
   P_EventParticipants: "User",
   P_EventResources: "Option",
   // 削除状態（"0" / "1"）。PORTERS が Data Type を与えていない項目＝`null`（ADR-0056。
@@ -2454,6 +2530,10 @@ var createFieldAccessor = (deps) => ({
 var FIELDS16 = {
   P_Id: "System[Id]",
   P_Name: "SinglelineText",
+  // VERIFY(live): LV-26。選択肢 alias は Write でタグ名になるので ADR-0085 が XML Name を要求するが、
+  // ここは**スカラのテキスト**として読むだけで、読めた値がその範囲に収まる保証は無い
+  // （Read 応答の入れ子タグ名から来る値は定義上 Name — 保証が効かないのはこの経路だけ）。
+  // docs/live-verification.md（LV-26）。
   P_Alias: "SinglelineText",
   P_ParentId: "Number",
   P_Type: "Number",