@37signals/basecamp 0.18.0 → 0.20.0

package/dist/services/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/services/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,aAAa,EAAiF,MAAM,cAAc,CAAC;AAE5H,OAAO,EAAE,UAAU,EAAmB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGvF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,YAAY,MAAM,eAAe,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AA0GD,8BAAsB,WAAW;;IAC/B,0CAA0C;IAC1C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAErC,uCAAuC;IACvC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAajE,yEAAyE;IACzE,SAAS,KAAK,QAAQ,IAAI,MAAM,CAE/B;IAED,mDAAmD;IACnD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEnC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAG3F,MAAM,EAAE,SAAS,EACjB,KAAK,CAAC,EAAE,aAAa,EACrB,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,EAC9C,QAAQ,CAAC,EAAE,MAAM,EACjB,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,EAC1E,OAAO,CAAC,EAAE,MAAM;IAyBlB;;;;;;;;;OASG;cACa,sBAAsB,CACpC,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,GAAG,IAAI,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;IAgGhB;;;;;;;OAOG;cACa,OAAO,CAAC,CAAC,EACvB,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC;IAiDb;;;;;;;;;;;OAWG;cACa,gBAAgB,CAAC,CAAC,EAChC,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EACrC,cAAc,CAAC,EAAE,iBAAiB,GACjC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAyEzB;;;;;;OAMG;cACa,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAC7D,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EACzD,GAAG,EAAE,CAAC,EACN,cAAc,CAAC,EAAE,iBAAiB,GACjC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IA6E3E;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,SAAS;IAcvB;;;;;OAKG;YACW,gBAAgB;IAgD9B;;;OAGG;YACW,uBAAuB;IA+CrC;;;;;;OAMG;cACa,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;CAmBzF"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/services/base.ts"],"names":[],"mappings":"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"}

package/dist/services/base.js

@@ -23,9 +23,12 @@
  */
 import { BasecampError, errorFromParsedBody, errorFromResponse, parseRetryAfter, truncateErrorMessage } from "../errors.js";
 import metadata from "../generated/metadata.js";
+import { PERSON_ID_SITES } from "../generated/person-id-sites.js";
 import { ListResult, parseTotalCount } from "../pagination.js";
+import { personIdNumber, scanPersonId } from "../person-id.js";
 import { parseNextLink, resolveURL, isSameOrigin, DEFAULT_MAX_PAGES, assertValidMaxPages } from "../pagination-utils.js";
 import { saturatingBackoff, timerSafeDelayMs } from "../retry.js";
+import { malformedResponse } from "./merge-safe.js";
 /**
  * True when the caller pinned a single page (SPEC section 8).
  *
@@ -49,22 +52,114 @@ function selectedPageResult(response, items, totalCount, maxItems) {
     return new ListResult(capped ? items.slice(0, maxItems) : items, { totalCount, truncated });
 }
 /**
- * Abstract base class for all Basecamp API services.
+ * Rewrites one Person-shaped object's string `id` in place.
  *
- * Services extend this class to inherit common functionality
- * for making API requests, handling errors, and integrating
- * with the hooks system.
+ * This is `coercePersonID` (`go/pkg/basecamp/normalize.go:38-68`), outcome for
+ * outcome, over the one rule in `../person-id.js` — Go's
+ * `strconv.ParseInt(s, 10, 64)`:
+ *
+ * - it reads a number: write the number, no `system_label` (`:58`)
+ * - SYNTAX ("basecamp", " 7", "12.0", "1e3"): id `0`, the raw string kept as
+ *   `system_label` (`:66-67`) — Go's non-numeric sentinel
+ * - RANGE ("9223372036854775808"): leave the string exactly as it arrived
+ *   (`:62-63`), so whoever reads it refuses rather than inventing an id
+ *
+ * An object whose `id` is already a number, or absent, is left alone — which is
+ * also what makes this IDEMPOTENT, and both passes below depend on that.
+ *
+ * The `^-?\d+$` + `Number.isSafeInteger` pair this replaces was wrong at both
+ * ends. It refused the leading `+` that `ParseInt` takes, so `"+7"` — a real
+ * person — became the sentinel. And it collapsed EVERY id past
+ * `Number.MAX_SAFE_INTEGER` to `id: 0` with a `system_label`: range errors and
+ * genuine large ids alike, which is to say it turned people into LocalPerson,
+ * silently, in the shape callers trust. Measured against the reference, 26 of
+ * the 74 corpus rows in `tests/helpers/person-id-corpus.ts` disagreed with Go
+ * (25 of them on the id itself; `"+0"` agreed on `0` and added a spurious
+ * label). The 11 that remain are the unrepresentable-value rows
+ * {@link personIdNumber} argues about.
  */
+function coercePersonId(rec) {
+    if (typeof rec.id !== "string")
+        return;
+    const idStr = rec.id;
+    const scan = scanPersonId(idStr);
+    if (scan.kind === "syntax") {
+        // Go's non-numeric sentinel, with the label the id came in as.
+        rec.system_label = idStr;
+        rec.id = 0;
+    }
+    else if (scan.kind === "value") {
+        const id = personIdNumber(scan.value);
+        // `undefined` is an id Go read and a `number` cannot hold. Leaving the
+        // string is the RANGE treatment, for the reason at personIdNumber: a
+        // rounded id names a different person and `0` names the system actor,
+        // while the digits, left alone, name whoever they always named.
+        if (id !== undefined)
+            rec.id = id;
+    }
+    // RANGE: nothing. The string stays put and the caller refuses it.
+}
+/** A JSON object — what Go's `.(map[string]any)` assertion accepts, and no array. */
+function isJSONObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /**
- * Normalizes Person-shaped objects in API responses.
+ * The keys Go's positional pass finds a person under, with the shape each holds.
+ *
+ * These are `normalizeEmbeddedPersonIds`'s two (`go/pkg/basecamp/normalize.go:83-104`)
+ * and nothing else, and the pass runs only on {@link EMBEDDED_PERSON_SERVICES}.
+ * `tests/services/person-id-normalization.test.ts` pins both halves.
+ *
+ * THIS REPLACED A WIDER SET, and the reason is worth keeping. Go has two ways a
+ * person id becomes a number: this normalizer, on the wrapper paths whose
+ * `basecamp.Person.ID` is a plain `int64`; and its decoder, because
+ * `generated.Person.Id` is `types.FlexibleInt64`, so every other `Person`-typed
+ * field converts at read time. TypeScript has no decoder, so the set was
+ * briefly widened to all twelve keys the spec types as `Person` — `assignees`,
+ * `subscribers`, `completion_subscribers` among them — to stand in for both.
+ *
+ * The derivation was right and the application was not. The keys were matched
+ * by NAME at any depth in every response, and a name that is `Person`-valued on
+ * one schema is not on every other: `creator`, `participants`, `assignees` and
+ * `person` also hold people whose id is a plain `int64` in the reference
+ * (`UpcomingSchedulePerson`, `MyAssignmentAssignee`, `OutOfOfficePerson`). A
+ * string there is a decode error in Go, and this turned it into the system
+ * actor. See {@link normalizeEmbeddedPersonIds} for the six sites.
+ *
+ * The arity is honoured because Go's type assertions carry it: the wrapper pass
+ * asserts `.(map[string]any)` for the creator and `[]any` for participants
+ * (`:85-95`), so a `creator` that is not an object is not a person.
+ */
+export const EMBEDDED_PERSON_KEYS = new Map([
+    ["creator", "object"],
+    ["participants", "array"],
+]);
+/**
+ * The services whose responses Go runs the positional pass over.
+ *
+ * `normalizeEmbeddedPeopleJSON` is a FUNCTION in the reference, not a layer, and
+ * it is called from exactly two places: `gauges.go:171` and
+ * `my_notifications.go:171,281,296`. Matching that is the whole point — see
+ * {@link normalizeEmbeddedPersonIds}.
+ */
+const EMBEDDED_PERSON_SERVICES = new Set(["Gauges", "MyNotifications"]);
+/**
+ * Normalizes Person-shaped objects in API responses, by `personable_type`.
  *
  * The BC3 API conflates real Person records (numeric id) with system actors
- * like LocalPerson (symbolic id: "basecamp", "campfire"). This function
- * walks a response tree and, for any object with a `personable_type` field
- * whose `id` is a string:
- * - Numeric strings in safe integer range: coerced to number, no system_label
- * - Non-numeric sentinels (e.g. "basecamp"): id becomes 0, original preserved as system_label
- * - Numeric overflow (beyond Number.MAX_SAFE_INTEGER): id becomes 0, original preserved as system_label
+ * like LocalPerson (symbolic id: "basecamp", "campfire"), and it serializes
+ * person ids as strings in some payloads. This is Go's `normalizePersonIds`
+ * (`go/pkg/basecamp/normalize.go:16-29`): any object at any depth carrying a
+ * `personable_type` key, whatever its value, gets {@link coercePersonId}.
+ *
+ * The key's presence is the whole test, and it is a safe one to run on every
+ * response: an object that declares itself personable IS the Person projection,
+ * whose id is `FlexibleInt64` in the reference and therefore a number to every
+ * caller. This pass predates the person-id work and its reach is unchanged by
+ * it.
+ *
+ * The POSITIONAL pass is a separate function with a much smaller reach, for
+ * reasons {@link normalizeEmbeddedPersonIds} sets out.
  */
 function normalizePersonIds(obj) {
     if (!obj || typeof obj !== "object")
@@ -75,31 +170,249 @@ function normalizePersonIds(obj) {
         return;
     }
     const rec = obj;
-    if ("personable_type" in rec && typeof rec.id === "string") {
-        const idStr = rec.id;
-        // Strict integer check: only bare digits (with optional leading minus).
-        // Rejects "1e3", "123.0", "0x1F", "123abc" which Number() would accept.
-        if (/^-?\d+$/.test(idStr) && Number.isSafeInteger(Number(idStr))) {
-            // Numeric string in safe integer range (e.g. "12345") — coerce to number
-            rec.id = Number(idStr);
-        }
-        else if (/^-?\d+$/.test(idStr)) {
-            // Pure digits but overflows JS safe integer range — preserve as
-            // system_label since we can't represent it losslessly as a number
-            rec.system_label = idStr;
-            rec.id = 0;
-        }
-        else {
-            // Non-numeric sentinel (e.g. "basecamp" for LocalPerson)
-            rec.system_label = idStr;
-            rec.id = 0;
-        }
-    }
+    if ("personable_type" in rec)
+        coercePersonId(rec);
     for (const val of Object.values(rec)) {
         if (typeof val === "object" && val !== null)
             normalizePersonIds(val);
     }
 }
+/**
+ * Coerces the string ids of people embedded under `creator` and `participants`.
+ *
+ * Go's `normalizeEmbeddedPersonIds` (`go/pkg/basecamp/normalize.go:83-104`),
+ * with Go's reach: it runs ONLY where `normalizeEmbeddedPeopleJSON` is called,
+ * which is `gauges.go:171` and `my_notifications.go:171,281,296` and nowhere
+ * else. {@link EMBEDDED_PERSON_SERVICES} is that call list.
+ *
+ * It exists because the wrapper types on those two paths (Notification, Gauge,
+ * GaugeNeedle) embed a `*Person` whose `ID` is a plain `int64`, and embedded
+ * creator and participant people frequently omit `personable_type`, so the pass
+ * above skips exactly the payloads this one exists to fix.
+ *
+ * WHY IT IS NOT WIDER, WHICH IS A CORRECTION. This walk briefly ran on every
+ * response over a twelve-key set derived from the spec's `Person`-valued
+ * fields, to stand in for the decoder TypeScript does not have. The derivation
+ * was right and the APPLICATION was wrong: the keys were matched by NAME at any
+ * depth, so a name that is `Person`-valued on one schema reached every other
+ * schema that happens to use it. Three schemas have a person-shaped field under
+ * one of these names whose id is a plain `int64` in the reference, so a string
+ * there is a decode error in Go and became the SYSTEM ACTOR here:
+ *
+ * - `UpcomingSchedulePerson` — `UpcomingScheduleEntry.creator`, `.participants`,
+ *   `UpcomingAssignable.assignees`, `UpcomingAssignableCompletion.creator`
+ * - `MyAssignmentAssignee` — `MyAssignment.assignees`
+ * - `OutOfOfficePerson` — `DisableOutOfOfficeOutput.person`
+ *
+ * A body the reference REFUSES outright read as person 0 with a `system_label`,
+ * on the field that says who acted — a divergence in the accepting direction on
+ * an identity field, which is the exact class this work exists to remove. It was
+ * latent (BC3 sends integers at all six sites today) and it was still wrong, and
+ * the rule it broke is the one that settles these: a port normalizes exactly
+ * where the reference does, never wider.
+ *
+ * The gap that widening was covering is real and is NOT closed here: `assignees`,
+ * `subscribers` and `completion_subscribers` carry string ids that Go's decoder
+ * converts. That is decoder coverage rather than normalizer reach, and it is
+ * closed by {@link decodeResponsePersonIds}, per operation at the generated
+ * `FlexibleInt64` sites. On the write path `writableIdList` in `merge-safe.ts`
+ * also reads the id by the same scan (PR #913).
+ */
+function normalizeEmbeddedPersonIds(obj) {
+    if (!obj || typeof obj !== "object")
+        return;
+    if (Array.isArray(obj)) {
+        for (const item of obj)
+            normalizeEmbeddedPersonIds(item);
+        return;
+    }
+    const rec = obj;
+    for (const [key, val] of Object.entries(rec)) {
+        // Go's type assertions skip anything else — a `creator: "me"` or a
+        // `participants: {}` is not a person (`:85-95`), and neither is a list
+        // element that is not an object.
+        const arity = EMBEDDED_PERSON_KEYS.get(key);
+        if (arity === "object") {
+            if (isJSONObject(val))
+                coercePersonId(val);
+        }
+        else if (arity === "array" && Array.isArray(val)) {
+            for (const element of val) {
+                if (isJSONObject(element))
+                    coercePersonId(element);
+            }
+        }
+        if (typeof val === "object" && val !== null)
+            normalizeEmbeddedPersonIds(val);
+    }
+}
+/**
+ * Both of the reference's passes, applied the way the reference applies them:
+ * the `personable_type` pass to every response, the positional pass only on the
+ * services Go calls `normalizeEmbeddedPeopleJSON` from.
+ */
+function normalizeResponsePersonIds(obj, service) {
+    normalizePersonIds(obj);
+    if (EMBEDDED_PERSON_SERVICES.has(service))
+        normalizeEmbeddedPersonIds(obj);
+}
+/** `ParseInt`'s int64 bounds as doubles. `2^63 - 1` rounds to `2^63`; see {@link decodeFlexiblePersonId}. */
+const INT64_MIN_DOUBLE = -(2 ** 63);
+const INT64_MAX_DOUBLE = 2 ** 63;
+/** Parsed {@link PERSON_ID_SITES} paths, split once per operation. */
+const personIdSiteSegments = new Map();
+function siteSegments(operation) {
+    let segments = personIdSiteSegments.get(operation);
+    if (segments === undefined) {
+        const sites = Object.hasOwn(PERSON_ID_SITES, operation) ? PERSON_ID_SITES[operation] : undefined;
+        if (sites === undefined)
+            return undefined;
+        segments = sites.map((site) => (site === "$" ? [] : site.split(".")));
+        personIdSiteSegments.set(operation, segments);
+    }
+    return segments;
+}
+/**
+ * Reads one person's `id` the way `types.FlexibleInt64.UnmarshalJSON` does
+ * (`go/pkg/types/flexible_int64.go:27-65`), writing the result in place.
+ *
+ * - a string goes through {@link scanPersonId}: a value is written as the
+ *   number (`:34-37`), SYNTAX writes `0` (`:46` — no `system_label`, which only
+ *   the pre-decode normalizer adds), RANGE fails the read (`:43-44`). A value
+ *   outside ±(2^53 − 1) leaves the string, the {@link personIdNumber} residual.
+ * - a number must be an integer inside int64 (`:59-61`). `JSON.parse` has
+ *   already rounded it, so `1024.0` and `1e3` are indistinguishable from `1024`
+ *   and `1000`, and the one double both `2^63 − 1` and `2^63` round to is
+ *   accepted rather than refusing a real int64 Go reads.
+ * - `null`, a boolean, an array or an object is not an int64 and fails the read
+ *   (`:56-61`).
+ */
+function decodeFlexiblePersonId(person, operation, site, scope) {
+    const id = person.id;
+    // A plain `int64` field reads JSON null as 0 without error; left as null here,
+    // the same representation residual as an absent id. See {@link DecodeScope}.
+    if (id === null && scope.nullIdReadsZero)
+        return;
+    if (typeof id === "string") {
+        const scan = scanPersonId(id);
+        if (scan.kind === "syntax") {
+            person.id = 0;
+            return;
+        }
+        if (scan.kind === "value") {
+            const value = personIdNumber(scan.value);
+            if (value !== undefined)
+                person.id = value;
+            return;
+        }
+        throw malformedPersonId(operation, site, id, "overflows int64");
+    }
+    if (typeof id === "number" && Number.isInteger(id) && id >= INT64_MIN_DOUBLE && id <= INT64_MAX_DOUBLE) {
+        return;
+    }
+    throw malformedPersonId(operation, site, id, "is not a valid int64");
+}
+function malformedPersonId(operation, site, id, why) {
+    return malformedResponse(`${operation} returned a person id at ${site} that ${why}: ${JSON.stringify(id)}`, "The reference SDK refuses this response when it decodes the person id; it is not retryable.");
+}
+function decodeSite(node, segments, index, operation, site, scope) {
+    // The last `[]` of an array site is the list of people, handled below, so the
+    // walk stops one segment short of it.
+    const arraySite = segments.length > 0 && segments[segments.length - 1] === "[]";
+    const end = arraySite ? segments.length - 1 : segments.length;
+    if (index === end) {
+        if (arraySite) {
+            if (!Array.isArray(node))
+                return;
+            for (const person of node) {
+                if (isJSONObject(person) && Object.hasOwn(person, "id"))
+                    decodeFlexiblePersonId(person, operation, site, scope);
+            }
+        }
+        else if (isJSONObject(node) && Object.hasOwn(node, "id")) {
+            decodeFlexiblePersonId(node, operation, site, scope);
+        }
+        return;
+    }
+    const segment = segments[index];
+    if (segment === "[]") {
+        if (Array.isArray(node))
+            for (const element of node)
+                decodeSite(element, segments, index + 1, operation, site, scope);
+    }
+    else if (segment === "{}") {
+        if (isJSONObject(node))
+            for (const value of Object.values(node))
+                decodeSite(value, segments, index + 1, operation, site, scope);
+    }
+    else if (isJSONObject(node) && Object.hasOwn(node, segment)) {
+        decodeSite(node[segment], segments, index + 1, operation, site, scope);
+    }
+}
+/**
+ * The one typed decode Go performs on a person id, at the fields Go performs it.
+ *
+ * `generated.Person.Id` is `types.FlexibleInt64`, and every generated Go service
+ * decodes its body through `Parse<Op>Response`, so an untagged `creator` of
+ * `{"id": "7"}` on a comment is `7` in Go. This SDK has no decoder, and after
+ * the pre-decode normalizer it was still the string `"7"` in a field typed
+ * `number` (SPEC.md section 10, "Person Ids Off the Wire").
+ *
+ * The sites are {@link PERSON_ID_SITES}, generated per OPERATION from the
+ * `x-go-type` marker on `Person.id` — not by key name, which is what reached
+ * `UpcomingSchedulePerson`, `MyAssignmentAssignee` and `OutOfOfficePerson`
+ * (plain `int64` in Go) when the normalizer was widened. An operation with no
+ * entry is left exactly as the normalizer left it.
+ *
+ * Runs AFTER the normalizer on the same body, which keeps both idempotent: an id
+ * the normalizer converted is a number here, and one it left (RANGE) is refused
+ * here, as Go's decoder refuses it. A person that is `null`, not an object, or
+ * has no `id` is left alone: Go zero-fills or refuses it as part of a
+ * whole-body decode this SDK does for no field.
+ */
+function decodeResponsePersonIds(body, operation, scope = {}) {
+    const segments = siteSegments(operation);
+    if (segments === undefined)
+        return;
+    const sites = PERSON_ID_SITES[operation];
+    const prefix = scope.wrappedKey === undefined ? undefined : `${scope.wrappedKey}.`;
+    segments.forEach((path, i) => {
+        const site = sites[i];
+        if (prefix !== undefined && !site.startsWith(prefix))
+            return;
+        decodeSite(body, path, 0, operation, site, scope);
+    });
+}
+/**
+ * The operations whose followed-page items Go decodes into HAND-WRITTEN types
+ * after the positional normalizer — `Gauge`, `GaugeNeedle`, `Notification` —
+ * whose `Person.ID` is a plain `int64` (`go/pkg/basecamp/todos.go:77-78`), not
+ * `FlexibleInt64`: `gauges.go:236-241`, `gauges.go:307-312`,
+ * `my_notifications.go:266-268,295-304`. A plain `int64` refuses what
+ * `FlexibleInt64` refuses once the normalizer has run, with one exception —
+ * JSON `null`, which `encoding/json` leaves at 0 without error. Page 1 of these
+ * still goes through `Parse<Op>Response`, where `null` is refused.
+ */
+const PLAIN_INT64_FOLLOWED_PAGE_OPERATIONS = new Set(["ListGauges", "ListGaugeNeedles", "GetBubbleUps"]);
+/**
+ * Everything a generated read does to a decoded body's person ids, in Go's
+ * order: the pre-decode normalizer, then the `FlexibleInt64` decode.
+ */
+function processResponsePersonIds(body, info) {
+    normalizeResponsePersonIds(body, info.service);
+    decodeResponsePersonIds(body, info.operation);
+}
+/**
+ * The same, for a page reached by following `Link: rel="next"`: the kept items
+ * of a bare-array page, or a wrapped page. See {@link DecodeScope}.
+ */
+function processFollowedPagePersonIds(body, info, wrappedKey) {
+    normalizeResponsePersonIds(body, info.service);
+    decodeResponsePersonIds(body, info.operation, {
+        wrappedKey,
+        nullIdReadsZero: PLAIN_INT64_FOLLOWED_PAGE_OPERATIONS.has(info.operation),
+    });
+}
 /**
  * Whether a rejection denotes invalid JSON rather than a failed read.
  *
@@ -123,6 +436,13 @@ function normalizePersonIds(obj) {
 function isJsonSyntaxError(err) {
     return typeof err === "object" && err !== null && err.name === "SyntaxError";
 }
+/**
+ * Abstract base class for all Basecamp API services.
+ *
+ * Services extend this class to inherit common functionality
+ * for making API requests, handling errors, and integrating
+ * with the hooks system.
+ */
 export class BaseService {
     /** The underlying openapi-fetch client */
     client;
@@ -241,21 +561,24 @@ export class BaseService {
                 }
                 // Drain response body before retry to free resources and enable connection reuse
                 response.body?.cancel();
-                // Backoff before retry. The header goes through errors.ts's
-                // parseRetryAfter — the single SPEC §6 implementation — rather than a
-                // local parseInt: the copy this replaced had no HTTP-date branch and
-                // guarded with `>= 0`, so it honoured `Retry-After: 0` as a
-                // zero-millisecond delay and retried with no wait at all.
-                const retryAfterSeconds = response.status === 429
-                    ? parseRetryAfter(response.headers.get("Retry-After"))
-                    : undefined;
+                // Backoff before retry. A Retry-After replaces the curve at every
+                // status this branch reaches (SPEC §6 "Retry-After Honouring"), and
+                // the header goes through errors.ts's parseRetryAfter — the single
+                // SPEC §6 implementation — rather than a local parseInt: the copy this
+                // replaced had no HTTP-date branch and guarded with `>= 0`, so it
+                // honoured `Retry-After: 0` as a zero-millisecond delay and retried
+                // with no wait at all.
+                const retryAfterSeconds = parseRetryAfter(response.headers.get("Retry-After"));
                 // The locally-computed term is bounded by SPEC §7's ceiling; the
                 // server-directed Retry-After is not, per the same section.
                 const delay = retryAfterSeconds !== undefined
                     ? timerSafeDelayMs(retryAfterSeconds)
                     : saturatingBackoff(retryConfig.baseDelayMs ?? 1000, "exponential", attempt);
                 try {
-                    const retryError = new Error(`${response.status} ${response.statusText}`);
+                    // SPEC §7 step 3i: the status-mapped error, carrying the parsed
+                    // retryAfter that governs this sleep — the same value, not a
+                    // second parse — rather than a bare Error.
+                    const retryError = errorFromParsedBody(response, null, response.headers.get("X-Request-Id") ?? undefined, retryAfterSeconds);
                     // SPEC section 7: RequestInfo.attempt is the attempt that just failed
                     // (1-based), while the standalone argument is the UPCOMING attempt.
                     this.hooks?.onRetry?.({ method, url, attempt: attempt + 1 }, attempt + 2, retryError, delay);
@@ -319,7 +642,7 @@ export class BaseService {
             if (response.status === 204 || data === undefined) {
                 return undefined;
             }
-            normalizePersonIds(data);
+            processResponsePersonIds(data, info);
             return data;
         }
         catch (err) {
@@ -374,7 +697,7 @@ export class BaseService {
                 throw basecampError;
             }
             const firstPageItems = data ?? [];
-            normalizePersonIds(firstPageItems);
+            processResponsePersonIds(firstPageItems, info);
             const totalCount = parseTotalCount(response);
             const maxItems = paginationOpts?.maxItems;
             // A pinned page is the whole answer: return it without following links.
@@ -392,7 +715,7 @@ export class BaseService {
                 return new ListResult(firstPageItems.slice(0, maxItems), { totalCount, truncated: hasMore });
             }
             // Follow pagination
-            const { items: allItems, truncated } = await this.followPagination(response, firstPageItems, maxItems);
+            const { items: allItems, truncated } = await this.followPagination(response, firstPageItems, maxItems, info);
             // Update duration to reflect total time across all pages
             result.durationMs = Math.round(performance.now() - start);
             return new ListResult(allItems, { totalCount, truncated });
@@ -441,7 +764,7 @@ export class BaseService {
                 throw basecampError;
             }
             const firstPageData = (data ?? {});
-            normalizePersonIds(firstPageData);
+            processResponsePersonIds(firstPageData, info);
             const totalCount = parseTotalCount(response);
             // Extract wrapper fields (everything except the paginated key)
             const wrapper = {};
@@ -466,7 +789,7 @@ export class BaseService {
                 return { ...wrapper, [key]: listResult };
             }
             // Follow pagination, extracting items from key on each subsequent page
-            const { items: allItems, truncated } = await this.followPaginationWrapped(response, firstPageItems, key, maxItems);
+            const { items: allItems, truncated } = await this.followPaginationWrapped(response, firstPageItems, key, maxItems, info);
             result.durationMs = Math.round(performance.now() - start);
             const listResult = new ListResult(allItems, { totalCount, truncated });
             return { ...wrapper, [key]: listResult };
@@ -527,7 +850,7 @@ export class BaseService {
      * beyond maxItems were dropped, or a next-page link was left unfetched
      * (maxItems met at a page boundary, or the page safety cap).
      */
-    async followPagination(initialResponse, firstPageItems, maxItems) {
+    async followPagination(initialResponse, firstPageItems, maxItems, info) {
         const allItems = [...firstPageItems];
         let response = initialResponse;
         const initialUrl = initialResponse.url;
@@ -545,14 +868,21 @@ export class BaseService {
                 throw await errorFromResponse(response, response.headers.get("X-Request-Id") ?? undefined);
             }
             const pageItems = await this.parsePage(response, page + 1);
-            normalizePersonIds(pageItems);
-            allItems.push(...pageItems);
-            // Check maxItems cap. Only mark truncated when items were actually
-            // dropped, or the just-fetched page links to a further page.
-            if (maxItems && maxItems > 0 && allItems.length >= maxItems) {
-                const hasMore = allItems.length > maxItems
+            // Trim to the cap BEFORE decoding. Go collects followed pages as
+            // `[]json.RawMessage`, trims them to the limit, and only the kept items
+            // are decoded (`go/pkg/basecamp/client.go:620-631`), so an item past the
+            // cap on a followed page can never fail the read. Page 1 is decoded whole
+            // by `Parse<Op>Response` before the cap, and is processed that way above.
+            const capped = !!maxItems && maxItems > 0 && allItems.length + pageItems.length >= maxItems;
+            const kept = capped ? pageItems.slice(0, maxItems - allItems.length) : pageItems;
+            processFollowedPagePersonIds(kept, info);
+            allItems.push(...kept);
+            // Only mark truncated when items were actually dropped, or the
+            // just-fetched page links to a further page.
+            if (capped) {
+                const hasMore = kept.length < pageItems.length
                     || parseNextLink(response.headers.get("Link")) !== null;
-                return { items: allItems.slice(0, maxItems), truncated: hasMore };
+                return { items: allItems, truncated: hasMore };
             }
         }
         // If we exited the loop because page >= maxPages and there's still a next link,
@@ -564,7 +894,7 @@ export class BaseService {
      * Follows Link header pagination for wrapped responses.
      * Each page is a wrapper object; items are extracted from data[key].
      */
-    async followPaginationWrapped(initialResponse, firstPageItems, key, maxItems) {
+    async followPaginationWrapped(initialResponse, firstPageItems, key, maxItems, info) {
         const allItems = [...firstPageItems];
         let response = initialResponse;
         const initialUrl = initialResponse.url;
@@ -581,7 +911,9 @@ export class BaseService {
                 throw await errorFromResponse(response, response.headers.get("X-Request-Id") ?? undefined);
             }
             const pageData = await this.parsePage(response, page + 1);
-            normalizePersonIds(pageData);
+            // Every item on the page is decoded before the cap trims, as Go's
+            // `GetPersonProgress` loop does (timeline.go:452-464) — but only under the key.
+            processFollowedPagePersonIds(pageData, info, key);
             const pageItems = pageData[key] ?? [];
             allItems.push(...pageItems);
             // Check maxItems cap. Only mark truncated when items were actually