npm - @joymerrevent/porters-connect - Versions diffs - 0.7.0 → 0.8.0 - Mend

@joymerrevent/porters-connect 0.7.0 → 0.8.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.

Files changed (4) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,27 @@
 ## [Unreleased]
+## [0.8.0] - 2026-08-14
+**「0 件」と「届いていない」を区別できるようにした版**です。HTTP 200 を返す中間装置
+（キャプティブポータル・SSO のログイン画面・WAF の通知ページ）の応答が、これまで**正常な空ページ**として
+通っていました。公開 API の形（型・メソッド）は不変で、**正しい PORTERS 応答に対する挙動も変わりません**。
+### Fixed
+- **HTTP 200 で返る「PORTERS 以外の応答」を 0 件として扱わなくなりました**（[ADR-0051][adr51]）。
+  Read 応答は**ルート要素名（`<Candidate>` などリソース名）と `<Code>` の両方**で同定します。
+  どちらかを欠くボディは `PortersResourceError`（`category: "unknown"` ＋ `httpStatus: 200` ＋ 中間装置を疑う `hint`）で拒否します。
+  - 従来は**キャプティブポータル・SSO のログイン画面・WAF の通知ページ**（いずれも HTTP 200）が
+    `total: 0` の**正常な空ページ**として返っていました。`get(id)` は `undefined` を返すため、
+    **「無ければ作る」コードが重複レコードを作りにいく**状態でした（データが無いのか届いていないのかを区別できない）。
+  - メッセージは原因を名指しします — `resource response root is <html>, expected <Candidate>` ／
+    `resource response has no <Code> (not a PORTERS envelope)`。**観測したルート名**が載るので切り分けできます。
+  - **正しい PORTERS 応答に対する挙動は変わりません**（[エラーハンドリング ガイド][guide]に判定表を追加）。
+  - ⚠️ **`createMockTransport` でモックを手書きしている場合**は、ボディに**リソース名のルート要素と `<Code>`** が
+    必要です（例 `<Candidate Total="1" Count="1" Start="0"><Code>0</Code>…</Candidate>`）。
+    実際の応答と同じ形にしていれば変更は不要です。
 ## [0.7.0] - 2026-08-13
 エラーの見え方をまとめて是正した版です。**PORTERS の応答ではない HTTP エラー**が分類されるようになり、
@@ -217,11 +238,13 @@
 [adr48]: docs/adr/0048-access-point-host-validation.md
 [adr49]: docs/adr/0049-host-port-roundtrip.md
 [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/guide/oauth.md
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
-[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.7.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.8.0...HEAD
+[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
 [0.6.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.6.0...v0.6.1

package/dist/index.js CHANGED Viewed

@@ -380,7 +380,8 @@ var toInt = (v) => {
   const s = asString(v);
   return s === void 0 ? 0 : Number(s);
 };
-var parseResourcePage = (xml) => {
+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 rootKey = root ? Object.keys(root)[0] : void 0;
   const body = root && rootKey ? asRecord(root[rootKey]) : void 0;
@@ -389,11 +390,21 @@ var parseResourcePage = (xml) => {
       category: "unknown"
     });
   }
+  if (rootKey !== resource) {
+    throw new PortersResourceError(
+      `resource response root is <${rootKey}>, expected <${resource}>`,
+      { category: "unknown", hint: MIDDLEBOX_HINT, context: { resource } }
+    );
+  }
+  if (body.Code === void 0) {
+    throw new PortersResourceError(
+      "resource response has no <Code> (not a PORTERS envelope)",
+      { category: "unknown", hint: MIDDLEBOX_HINT, context: { resource } }
+    );
+  }
   const code = toInt(body.Code);
   if (code !== 0) {
-    throw resourceError(code, `resource returned code ${code}`, {
-      resource: rootKey
-    });
+    throw resourceError(code, `resource returned code ${code}`, { resource });
   }
   return {
     total: toInt(body["@_Total"]),
@@ -826,8 +837,8 @@ var decoderFor = (fields) => {
     return out;
   };
 };
-var runRead = (requester, url, decode) => requester.request({ method: "GET", url, headers: {} }, (body) => {
-  const page = parseResourcePage(body);
+var runRead = (requester, resource, url, decode) => requester.request({ method: "GET", url, headers: {} }, (body) => {
+  const page = parseResourcePage(body, resource);
   return {
     items: page.items.map(decode),
     total: page.total,
@@ -1053,6 +1064,7 @@ var createResource = (config, deps) => {
   const firstWriteId = (body) => firstWriteResultId(body, config.path, config.name);
   const search = async (query = {}) => runRead(
     deps.requester,
+    config.name,
     readUrl({ ...query, field: query.field ?? defaultFields }),
     decode
   );
@@ -1329,6 +1341,7 @@ var createResumeResource = (deps, custom) => {
 // src/resources/attachment.ts
 var MAX_CONTENT_CHARS = 14e6;
+var ATTACHMENT_RESOURCE = "Attachment";
 var ATTACHMENT_FIELD_NAMES = [
   "Id",
   "Resource",
@@ -1388,7 +1401,7 @@ var createAttachmentResource = (deps) => {
       headers: {}
     },
     (body) => {
-      const page = parseResourcePage(body);
+      const page = parseResourcePage(body, ATTACHMENT_RESOURCE);
       return {
         items: page.items.map(decodeAttachment),
         total: page.total,
@@ -1412,7 +1425,7 @@ var createAttachmentResource = (deps) => {
       headers: {},
       body: `<Attachment><Item>${inner}</Item></Attachment>`
     },
-    (body) => firstWriteResultId(body, "attachment", "Attachment"),
+    (body) => firstWriteResultId(body, "attachment", ATTACHMENT_RESOURCE),
     { write: true, idempotent, unboundedBody: true }
   );
   const create = async (input) => {
@@ -1439,6 +1452,12 @@ var FIELDS6 = {
   P_Name: "SinglelineText",
   P_CompanyId: "SinglelineText"
 };
+var PARTITION_DESCRIPTOR = {
+  name: "Partition",
+  path: "partition",
+  prefix: "Partition",
+  fields: FIELDS6
+};
 var buildUrl = (accessPoint, q) => {
   const p = new URLSearchParams();
   p.set("request_type", String(q.requestType ?? 1));
@@ -1448,7 +1467,12 @@ var buildUrl = (accessPoint, q) => {
 };
 var createPartitionResource = (deps) => {
   const decode = decoderFor(FIELDS6);
-  const search = async (query = {}) => runRead(deps.requester, buildUrl(deps.accessPoint, query), decode);
+  const search = async (query = {}) => runRead(
+    deps.requester,
+    PARTITION_DESCRIPTOR.name,
+    buildUrl(deps.accessPoint, query),
+    decode
+  );
   const searchAll = (query = {}) => paginate((count, start) => search({ ...query, count, start }));
   return { search, searchAll };
 };
@@ -1460,6 +1484,12 @@ var FIELDS7 = {
   P_Name: "SinglelineText",
   P_Mail: "Mail"
 };
+var USER_DESCRIPTOR = {
+  name: "User",
+  path: "user",
+  prefix: "User",
+  fields: FIELDS7
+};
 var buildUrl2 = (accessPoint, partition, q) => {
   const p = new URLSearchParams();
   p.set("partition", String(partition));
@@ -1474,6 +1504,7 @@ var createUserResource = (deps) => {
   const decode = decoderFor(FIELDS7);
   const search = async (query = {}) => runRead(
     deps.requester,
+    USER_DESCRIPTOR.name,
     buildUrl2(deps.accessPoint, deps.partition, query),
     decode
   );
@@ -1510,6 +1541,12 @@ var FIELDS8 = {
   P_ReferTo: "Option",
   P_ResourceType: "Number"
 };
+var FIELD_DESCRIPTOR = {
+  name: "Field",
+  path: "field",
+  prefix: "Field",
+  fields: FIELDS8
+};
 var buildUrl3 = (accessPoint, partition, q) => {
   const p = new URLSearchParams();
   p.set("partition", String(partition));
@@ -1523,6 +1560,7 @@ var createFieldResource = (deps) => {
   const decode = decoderFor(FIELDS8);
   const search = async (query) => runRead(
     deps.requester,
+    FIELD_DESCRIPTOR.name,
     buildUrl3(deps.accessPoint, deps.partition, query),
     decode
   );
@@ -1539,6 +1577,12 @@ var FIELDS9 = {
   P_Type: "Number",
   P_Order: "Number"
 };
+var OPTION_DESCRIPTOR = {
+  name: "Option",
+  path: "option",
+  prefix: "Option",
+  fields: FIELDS9
+};
 var buildUrl4 = (accessPoint, partition, q) => {
   const p = new URLSearchParams();
   p.set("partition", String(partition));
@@ -1568,7 +1612,7 @@ var createOptionResource = (deps) => {
     },
     (body) => {
       const out = [];
-      flatten(parseResourcePage(body).items, out);
+      flatten(parseResourcePage(body, OPTION_DESCRIPTOR.name).items, out);
       return out;
     }
   );