@37signals/basecamp 0.12.0 → 0.14.0

package/dist/oauth/authorization-document.d.ts

@@ -0,0 +1,201 @@
+/**
+ * The authorization document, as served by both issuers.
+ *
+ * Two different services fetch this document — {@link ../services/authorization.js | AuthorizationService}
+ * and {@link ./identity.js | discoverIdentity} — and they used to carry a copy of
+ * the mapping each. The copies had already drifted apart (`app_href` was required
+ * in one and optional in the other), which is exactly how a shape fix gets applied
+ * to one caller and missed on the other. The mapping lives here once.
+ *
+ * This module is a leaf on purpose: it imports nothing from the SDK, so either
+ * caller can take a *value* dependency on it without adding a runtime edge to the
+ * `base.ts` / `client.ts` cycle.
+ *
+ * ## Two issuers, two shapes
+ *
+ * Launchpad and a BC5 (bc3) issuer both serve `GET /authorization.json`, and the
+ * documents are not the same shape. bc3 renders its own from
+ * `app/views/api/authorizations/show.json.jbuilder`:
+ *
+ * | Field | Launchpad | BC5 |
+ * |---|---|---|
+ * | `identity.first_name` / `last_name` / `email_address` | present | absent |
+ * | `accounts[].product` / `app_href` | present | absent |
+ * | `accounts[].resource` | absent | present (RFC 8707 indicator) |
+ * | `scope` | absent | present, BC3-issued tokens only |
+ * | `expires_at` | ISO-8601 string | integer epoch **seconds** |
+ *
+ * Every field either issuer omits is typed optional here. The union is modelled
+ * rather than either shape alone, because a consumer reaches a BC5 issuer just by
+ * passing `endpoint:`, and BC5 issuers serving their own document is the intended
+ * end state.
+ *
+ * @see spec/api-gaps/bc5-authorization-document-shape.md
+ */
+/**
+ * The authenticated user's identity.
+ *
+ * Only `id` is guaranteed. A BC5 issuer emits nothing but the identity id — it
+ * deliberately drops the PII that the API docs already say not to use for
+ * identifying users — so the name and email fields are absent there.
+ */
+export interface Identity {
+    /** User's unique identifier. Emitted by both issuers. */
+    id: number;
+    /** User's first name. Launchpad only — `undefined` from a BC5 issuer. */
+    firstName?: string;
+    /** User's last name. Launchpad only — `undefined` from a BC5 issuer. */
+    lastName?: string;
+    /** User's email address. Launchpad only — `undefined` from a BC5 issuer. */
+    emailAddress?: string;
+}
+/**
+ * A Basecamp account the user has access to.
+ */
+export interface AuthorizedAccount {
+    /** Account's unique identifier. */
+    id: number;
+    /** Account name. */
+    name: string;
+    /**
+     * Product type (e.g. `"bc3"` for Basecamp, `"hey"` for HEY).
+     *
+     * Launchpad only. A BC5 issuer serves one product by construction and omits
+     * this, which is why {@link filterAccountsByProduct} treats a non-empty
+     * document with no `product` anywhere as one the filter cannot apply to.
+     */
+    product?: string;
+    /** API URL for this account. Emitted by both issuers. */
+    href: string;
+    /** Web app URL for this account. Launchpad only. */
+    appHref?: string;
+    /**
+     * RFC 8707 resource indicator for this account (`urn:bc:account:<id>`).
+     *
+     * BC5 issuers only. Pass it as the `resource` parameter when requesting a
+     * token scoped to this account.
+     */
+    resource?: string;
+    /** Whether the account is hidden from the user's view. */
+    hidden?: boolean;
+    /** Whether the account subscription has expired. */
+    expired?: boolean;
+    /** Whether this is the user's featured/primary account. */
+    featured?: boolean;
+}
+/**
+ * Authorization information response.
+ */
+export interface AuthorizationInfo {
+    /**
+     * Token expiration timestamp.
+     *
+     * Parsed from either issuer's spelling — see {@link parseExpiresAt}.
+     */
+    expiresAt: Date;
+    /** The authenticated user's identity. */
+    identity: Identity;
+    /** List of accounts the user can access. */
+    accounts: AuthorizedAccount[];
+    /**
+     * The token's granted scope.
+     *
+     * BC5 issuers only, and only for BC3-issued tokens — legacy Signal tokens
+     * predate scopes, so its absence is not an error.
+     */
+    scope?: string;
+    /**
+     * Whether a requested `product` filter was actually applied.
+     *
+     * Only meaningful when a product filter was requested. `false` means the
+     * document carried at least one account and no `product` on any of them — a
+     * BC5 document — so the filter was inapplicable and `accounts` is unfiltered
+     * rather than empty. An empty account list reports `true`: it is no evidence
+     * about the issuer either way. See {@link filterAccountsByProduct}.
+     */
+    productFilterApplied?: boolean;
+}
+/**
+ * The raw wire document, covering both issuers.
+ *
+ * Every field that *either* issuer omits is optional, so this type describes what
+ * can actually arrive rather than what one issuer happens to send. `identity` and
+ * `accounts` are the two that stay required: both issuers emit both, so a document
+ * missing either is malformed, and throwing on it beats inventing an empty account
+ * list that a caller cannot distinguish from a real one.
+ */
+export interface RawAuthorizationDocument {
+    /** ISO-8601 string (Launchpad) or integer epoch seconds (BC5). */
+    expires_at?: string | number | null;
+    /** Both issuers always emit this, so it stays required — see the note below. */
+    identity: {
+        id: number;
+        first_name?: string;
+        last_name?: string;
+        email_address?: string;
+    };
+    /** Both issuers always emit this, so it stays required — see the note below. */
+    accounts: Array<{
+        id: number;
+        name: string;
+        product?: string;
+        href: string;
+        app_href?: string;
+        resource?: string;
+        hidden?: boolean;
+        expired?: boolean;
+        featured?: boolean;
+    }>;
+    scope?: string;
+}
+/**
+ * Parses `expires_at` from either issuer's spelling.
+ *
+ * Launchpad sends an ISO-8601 string; bc3 sends `@token.expires_at.to_i`, an
+ * integer epoch **seconds**. The distinction is the whole point of branching on
+ * `typeof`: `new Date(2085213356)` treats the number as *milliseconds* and yields
+ * a date in 1970 — a wrong answer rather than an exception, which then reads as
+ * an expired credential rather than a schema mismatch.
+ *
+ * bc3 renders `.to_i`, so a nil expiry arrives as `0`, never `null`. A `0`, a
+ * `null` and an absent field are all "no expiry known" and produce an Invalid
+ * Date, which is what a `Date`-typed field can say about the absence.
+ */
+export declare function parseExpiresAt(value: string | number | null | undefined): Date;
+/**
+ * Filters accounts by product, or reports that it could not.
+ *
+ * A BC5 document carries no `product` on any account, so filtering it by product
+ * matches nothing. Returning `[]` there is silently wrong — the accounts exist,
+ * and the caller's next step is to pick a `href` out of a list the SDK just
+ * emptied. Instead: when *no* account in the document carries a `product`, the
+ * filter is inapplicable, and all accounts are returned with `applied: false` so
+ * a caller that cares can tell the two situations apart.
+ *
+ * When at least one account carries a `product`, the filter is meaningful and is
+ * applied normally — an empty result then genuinely means "no account matched".
+ *
+ * An **empty** account list is the edge that needs saying out loud. "No account
+ * carries a `product`" is vacuously true of `[]`, which would report the filter
+ * inapplicable — but Launchpad returns `accounts: []` for an identity with no
+ * currently accessible accounts, and that document is perfectly filterable. The
+ * result is the same list either way, so nothing observable changes; what changes
+ * is the claim the flag makes, and `applied: false` would assert "this issuer
+ * cannot filter by product" on no evidence at all. An empty list carries no
+ * evidence about the issuer, so treat the filter as applied: filtering nothing by
+ * anything yields nothing, which is exactly what happened.
+ */
+export declare function filterAccountsByProduct(accounts: AuthorizedAccount[], product: string): {
+    accounts: AuthorizedAccount[];
+    applied: boolean;
+};
+/**
+ * Maps a raw authorization document to {@link AuthorizationInfo}.
+ *
+ * Optionally applies a product filter; see {@link filterAccountsByProduct} for
+ * what happens when the document cannot be filtered by product.
+ */
+export declare function parseAuthorizationDocument(raw: RawAuthorizationDocument, options?: {
+    filterProduct?: string;
+}): AuthorizationInfo;
+//# sourceMappingURL=authorization-document.d.ts.map

package/dist/oauth/authorization-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-document.d.ts","sourceRoot":"","sources":["../../src/oauth/authorization-document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,SAAS,EAAE,IAAI,CAAC;IAChB,yCAAyC;IACzC,QAAQ,EAAE,QAAQ,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,gFAAgF;IAChF,QAAQ,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,gFAAgF;IAChF,QAAQ,EAAE,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAS9E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAMrD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,wBAAwB,EAC7B,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,iBAAiB,CAqCnB"}

package/dist/oauth/authorization-document.js

@@ -0,0 +1,130 @@
+/**
+ * The authorization document, as served by both issuers.
+ *
+ * Two different services fetch this document — {@link ../services/authorization.js | AuthorizationService}
+ * and {@link ./identity.js | discoverIdentity} — and they used to carry a copy of
+ * the mapping each. The copies had already drifted apart (`app_href` was required
+ * in one and optional in the other), which is exactly how a shape fix gets applied
+ * to one caller and missed on the other. The mapping lives here once.
+ *
+ * This module is a leaf on purpose: it imports nothing from the SDK, so either
+ * caller can take a *value* dependency on it without adding a runtime edge to the
+ * `base.ts` / `client.ts` cycle.
+ *
+ * ## Two issuers, two shapes
+ *
+ * Launchpad and a BC5 (bc3) issuer both serve `GET /authorization.json`, and the
+ * documents are not the same shape. bc3 renders its own from
+ * `app/views/api/authorizations/show.json.jbuilder`:
+ *
+ * | Field | Launchpad | BC5 |
+ * |---|---|---|
+ * | `identity.first_name` / `last_name` / `email_address` | present | absent |
+ * | `accounts[].product` / `app_href` | present | absent |
+ * | `accounts[].resource` | absent | present (RFC 8707 indicator) |
+ * | `scope` | absent | present, BC3-issued tokens only |
+ * | `expires_at` | ISO-8601 string | integer epoch **seconds** |
+ *
+ * Every field either issuer omits is typed optional here. The union is modelled
+ * rather than either shape alone, because a consumer reaches a BC5 issuer just by
+ * passing `endpoint:`, and BC5 issuers serving their own document is the intended
+ * end state.
+ *
+ * @see spec/api-gaps/bc5-authorization-document-shape.md
+ */
+/**
+ * Parses `expires_at` from either issuer's spelling.
+ *
+ * Launchpad sends an ISO-8601 string; bc3 sends `@token.expires_at.to_i`, an
+ * integer epoch **seconds**. The distinction is the whole point of branching on
+ * `typeof`: `new Date(2085213356)` treats the number as *milliseconds* and yields
+ * a date in 1970 — a wrong answer rather than an exception, which then reads as
+ * an expired credential rather than a schema mismatch.
+ *
+ * bc3 renders `.to_i`, so a nil expiry arrives as `0`, never `null`. A `0`, a
+ * `null` and an absent field are all "no expiry known" and produce an Invalid
+ * Date, which is what a `Date`-typed field can say about the absence.
+ */
+export function parseExpiresAt(value) {
+    if (typeof value === "number") {
+        // Epoch seconds, not milliseconds. `0` is bc3's rendering of a nil expiry.
+        return value === 0 ? new Date(NaN) : new Date(value * 1000);
+    }
+    if (typeof value === "string" && value !== "") {
+        return new Date(value);
+    }
+    return new Date(NaN);
+}
+/**
+ * Filters accounts by product, or reports that it could not.
+ *
+ * A BC5 document carries no `product` on any account, so filtering it by product
+ * matches nothing. Returning `[]` there is silently wrong — the accounts exist,
+ * and the caller's next step is to pick a `href` out of a list the SDK just
+ * emptied. Instead: when *no* account in the document carries a `product`, the
+ * filter is inapplicable, and all accounts are returned with `applied: false` so
+ * a caller that cares can tell the two situations apart.
+ *
+ * When at least one account carries a `product`, the filter is meaningful and is
+ * applied normally — an empty result then genuinely means "no account matched".
+ *
+ * An **empty** account list is the edge that needs saying out loud. "No account
+ * carries a `product`" is vacuously true of `[]`, which would report the filter
+ * inapplicable — but Launchpad returns `accounts: []` for an identity with no
+ * currently accessible accounts, and that document is perfectly filterable. The
+ * result is the same list either way, so nothing observable changes; what changes
+ * is the claim the flag makes, and `applied: false` would assert "this issuer
+ * cannot filter by product" on no evidence at all. An empty list carries no
+ * evidence about the issuer, so treat the filter as applied: filtering nothing by
+ * anything yields nothing, which is exactly what happened.
+ */
+export function filterAccountsByProduct(accounts, product) {
+    const filterable = accounts.length === 0 || accounts.some((a) => a.product !== undefined);
+    if (!filterable) {
+        return { accounts, applied: false };
+    }
+    return { accounts: accounts.filter((a) => a.product === product), applied: true };
+}
+/**
+ * Maps a raw authorization document to {@link AuthorizationInfo}.
+ *
+ * Optionally applies a product filter; see {@link filterAccountsByProduct} for
+ * what happens when the document cannot be filtered by product.
+ */
+export function parseAuthorizationDocument(raw, options = {}) {
+    let accounts = raw.accounts.map((a) => ({
+        id: a.id,
+        name: a.name,
+        product: a.product,
+        href: a.href,
+        appHref: a.app_href,
+        resource: a.resource,
+        hidden: a.hidden,
+        expired: a.expired,
+        featured: a.featured,
+    }));
+    let productFilterApplied;
+    if (options.filterProduct !== undefined && options.filterProduct !== "") {
+        const filtered = filterAccountsByProduct(accounts, options.filterProduct);
+        accounts = filtered.accounts;
+        productFilterApplied = filtered.applied;
+    }
+    const info = {
+        expiresAt: parseExpiresAt(raw.expires_at),
+        identity: {
+            id: raw.identity.id,
+            firstName: raw.identity.first_name,
+            lastName: raw.identity.last_name,
+            emailAddress: raw.identity.email_address,
+        },
+        accounts,
+    };
+    if (raw.scope !== undefined) {
+        info.scope = raw.scope;
+    }
+    if (productFilterApplied !== undefined) {
+        info.productFilterApplied = productFilterApplied;
+    }
+    return info;
+}
+//# sourceMappingURL=authorization-document.js.map

package/dist/oauth/authorization-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-document.js","sourceRoot":"","sources":["../../src/oauth/authorization-document.ts"],"names":[],"mappings":"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"}

package/dist/oauth/identity.d.ts

@@ -3,9 +3,15 @@
  *
  * Fetches authorization information (identity and accounts) from
  * the Launchpad endpoint without requiring a full client instance.
+ *
+ * The endpoint is fixed to Launchpad here — unlike
+ * {@link ../services/authorization.js | AuthorizationService.getInfo}, which
+ * accepts an `endpoint:` override and so can be pointed at a BC5 issuer. Both
+ * share one mapping regardless; see `./authorization-document.js` for why the two
+ * documents differ and how the shared parser reconciles them.
  */
 import type { TokenProvider } from "../client.js";
-import type { AuthorizationInfo } from "../services/authorization.js";
+import { type AuthorizationInfo } from "./authorization-document.js";
 /**
  * Fetches authorization information using an access token.
  *

package/dist/oauth/identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/oauth/identity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AA2BtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsD7F"}
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/oauth/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,6BAA6B,CAAC;AAIrC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAoC7F"}

package/dist/oauth/identity.js

@@ -3,8 +3,15 @@
  *
  * Fetches authorization information (identity and accounts) from
  * the Launchpad endpoint without requiring a full client instance.
+ *
+ * The endpoint is fixed to Launchpad here — unlike
+ * {@link ../services/authorization.js | AuthorizationService.getInfo}, which
+ * accepts an `endpoint:` override and so can be pointed at a BC5 issuer. Both
+ * share one mapping regardless; see `./authorization-document.js` for why the two
+ * documents differ and how the shared parser reconciles them.
  */
 import { BasecampError } from "../errors.js";
+import { parseAuthorizationDocument, } from "./authorization-document.js";
 const AUTHORIZATION_ENDPOINT = "https://launchpad.37signals.com/authorization.json";
 /**
  * Fetches authorization information using an access token.
@@ -59,24 +66,6 @@ export async function discoverIdentity(accessToken) {
     catch {
         throw new BasecampError("api_error", "Identity discovery returned invalid JSON");
     }
-    return {
-        expiresAt: new Date(raw.expires_at),
-        identity: {
-            id: raw.identity.id,
-            firstName: raw.identity.first_name,
-            lastName: raw.identity.last_name,
-            emailAddress: raw.identity.email_address,
-        },
-        accounts: raw.accounts.map((a) => ({
-            id: a.id,
-            name: a.name,
-            product: a.product,
-            href: a.href,
-            appHref: a.app_href ?? "",
-            hidden: a.hidden,
-            expired: a.expired,
-            featured: a.featured,
-        })),
-    };
+    return parseAuthorizationDocument(raw);
 }
 //# sourceMappingURL=identity.js.map

package/dist/oauth/identity.js.map

@@ -1 +1 @@
-{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/oauth/identity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA2B7C,MAAM,sBAAsB,GAAG,oDAAoD,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,WAA0B;IAC/D,MAAM,KAAK,GAAG,OAAO,WAAW,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;IAEpF,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,sBAAsB,EAAE;YAC7C,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,KAAK,EAAE;gBAChC,MAAM,EAAE,kBAAkB;aAC3B;SACF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,aAAa,CAAC,SAAS,EAAE,8BAA8B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACvH,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,IAAI,aAAa,CAAC,eAAe,EAAE,iCAAiC,EAAE;gBAC1E,UAAU,EAAE,GAAG;gBACf,IAAI,EAAE,2CAA2C;aAClD,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAI,aAAa,CAAC,WAAW,EAAE,mCAAmC,QAAQ,CAAC,MAAM,EAAE,EAAE;YACzF,UAAU,EAAE,QAAQ,CAAC,MAAM;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,IAAI,GAA6B,CAAC;IAClC,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA6B,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,aAAa,CAAC,WAAW,EAAE,0CAA0C,CAAC,CAAC;IACnF,CAAC;IAED,OAAO;QACL,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC;QACnC,QAAQ,EAAE;YACR,EAAE,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE;YACnB,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU;YAClC,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,SAAS;YAChC,YAAY,EAAE,GAAG,CAAC,QAAQ,CAAC,aAAa;SACzC;QACD,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACjC,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,QAAQ,IAAI,EAAE;YACzB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;SACrB,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/oauth/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EACL,0BAA0B,GAG3B,MAAM,6BAA6B,CAAC;AAErC,MAAM,sBAAsB,GAAG,oDAAoD,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,WAA0B;IAC/D,MAAM,KAAK,GAAG,OAAO,WAAW,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;IAEpF,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,sBAAsB,EAAE;YAC7C,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,KAAK,EAAE;gBAChC,MAAM,EAAE,kBAAkB;aAC3B;SACF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,aAAa,CAAC,SAAS,EAAE,8BAA8B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACvH,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,MAAM,IAAI,aAAa,CAAC,eAAe,EAAE,iCAAiC,EAAE;gBAC1E,UAAU,EAAE,GAAG;gBACf,IAAI,EAAE,2CAA2C;aAClD,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAI,aAAa,CAAC,WAAW,EAAE,mCAAmC,QAAQ,CAAC,MAAM,EAAE,EAAE;YACzF,UAAU,EAAE,QAAQ,CAAC,MAAM;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,IAAI,GAA6B,CAAC;IAClC,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA6B,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,aAAa,CAAC,WAAW,EAAE,0CAA0C,CAAC,CAAC;IACnF,CAAC;IAED,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC"}

package/dist/oauth/index.d.ts

@@ -50,4 +50,5 @@ export { TokenManager, type TokenManagerOptions, } from "./token-manager.js";
 export { startCallbackServer, type CallbackResult, type CallbackServerOptions, } from "./callback-server.js";
 export { performInteractiveLogin, type InteractiveLoginOptions, } from "./interactive-login.js";
 export { discoverIdentity, } from "./identity.js";
+export { parseAuthorizationDocument, parseExpiresAt, filterAccountsByProduct, type RawAuthorizationDocument, } from "./authorization-document.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/oauth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,YAAY,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,6BAA6B,EAC7B,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,sBAAsB,EACtB,KAAK,gCAAgC,EACrC,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,eAAe,EACf,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,QAAQ,EACR,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,2BAA2B,GACjC,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,KAAK,IAAI,GACV,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,cAAc,EACd,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,uBAAuB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,gBAAgB,GACjB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,YAAY,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,6BAA6B,EAC7B,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,sBAAsB,EACtB,KAAK,gCAAgC,EACrC,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,eAAe,EACf,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,QAAQ,EACR,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,2BAA2B,GACjC,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,KAAK,IAAI,GACV,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,cAAc,EACd,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,uBAAuB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,0BAA0B,EAC1B,cAAc,EACd,uBAAuB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,6BAA6B,CAAC"}

package/dist/oauth/index.js

@@ -59,4 +59,6 @@ export { startCallbackServer, } from "./callback-server.js";
 export { performInteractiveLogin, } from "./interactive-login.js";
 // Identity
 export { discoverIdentity, } from "./identity.js";
+// The authorization document, shared by discoverIdentity and AuthorizationService
+export { parseAuthorizationDocument, parseExpiresAt, filterAccountsByProduct, } from "./authorization-document.js";
 //# sourceMappingURL=index.js.map

package/dist/oauth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAiBH,yBAAyB;AACzB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,sBAAsB,GAIvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,GAEnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,eAAe,GAEhB,MAAM,oBAAoB,CAAC;AAE5B,YAAY;AACZ,OAAO,EACL,QAAQ,EACR,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,GAGnB,MAAM,gBAAgB,CAAC;AAExB,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,cAAc,GAEf,MAAM,eAAe,CAAC;AAEvB,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,aAAa,GAEd,MAAM,WAAW,CAAC;AAEnB,oBAAoB;AACpB,OAAO,EACL,qBAAqB,GAEtB,MAAM,gBAAgB,CAAC;AAExB,cAAc;AACd,OAAO,EACL,cAAc,GAEf,MAAM,kBAAkB,CAAC;AAE1B,gBAAgB;AAChB,OAAO,EACL,YAAY,GAEb,MAAM,oBAAoB,CAAC;AAE5B,kBAAkB;AAClB,OAAO,EACL,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAE9B,oBAAoB;AACpB,OAAO,EACL,uBAAuB,GAExB,MAAM,wBAAwB,CAAC;AAEhC,WAAW;AACX,OAAO,EACL,gBAAgB,GACjB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAiBH,yBAAyB;AACzB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,sBAAsB,GAIvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,GAEnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,eAAe,GAEhB,MAAM,oBAAoB,CAAC;AAE5B,YAAY;AACZ,OAAO,EACL,QAAQ,EACR,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,GAGnB,MAAM,gBAAgB,CAAC;AAExB,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,cAAc,GAEf,MAAM,eAAe,CAAC;AAEvB,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,aAAa,GAEd,MAAM,WAAW,CAAC;AAEnB,oBAAoB;AACpB,OAAO,EACL,qBAAqB,GAEtB,MAAM,gBAAgB,CAAC;AAExB,cAAc;AACd,OAAO,EACL,cAAc,GAEf,MAAM,kBAAkB,CAAC;AAE1B,gBAAgB;AAChB,OAAO,EACL,YAAY,GAEb,MAAM,oBAAoB,CAAC;AAE5B,kBAAkB;AAClB,OAAO,EACL,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAE9B,oBAAoB;AACpB,OAAO,EACL,uBAAuB,GAExB,MAAM,wBAAwB,CAAC;AAEhC,WAAW;AACX,OAAO,EACL,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,kFAAkF;AAClF,OAAO,EACL,0BAA0B,EAC1B,cAAc,EACd,uBAAuB,GAExB,MAAM,6BAA6B,CAAC"}

package/dist/pagination-utils.d.ts

@@ -5,6 +5,52 @@
  * client.ts (which imports generated services) and base.ts (which
  * generated services extend).
  */
+/**
+ * Rejects any `maxPages` that would defeat or invert the cap.
+ *
+ * Lives here, beside `DEFAULT_MAX_PAGES` and for the same reason: `client.ts`,
+ * `services/base.ts` and this module's own helpers all need it, and this is the
+ * only one of them they can all import without a cycle. Three entry points set
+ * a cap — `createBasecampClient`, the standalone `fetchAllPages`/`paginateAll`,
+ * and `BaseService`'s constructor, which is exported and directly constructible
+ * — and a guard on two of the three is not a guard.
+ *
+ * `Number.isSafeInteger(n) && n > 0` is one predicate covering every value that
+ * breaks the bound, each of which passed silently while `maxPages` was
+ * unvalidated:
+ *
+ * - `Infinity` — `page === maxPages` is never true, so the loop is unbounded
+ *   and the cap does nothing at all. Precisely the runaway it exists to stop.
+ * - Anything ABOVE `2 ** 53`, such as `Number.MAX_VALUE` — the same runaway
+ *   through a different door, and the reason this is `isSafeInteger` rather
+ *   than `isInteger`. `Number.isInteger(Number.MAX_VALUE)` is `true`, so the
+ *   obvious predicate admits it. Past `2 ** 53` the counter stalls: `page++`
+ *   on `2 ** 53` yields `2 ** 53` again, because the next integer is not
+ *   representable, so a bound of `2 ** 53 + 2` is never reached. `2 ** 53`
+ *   ITSELF is fine — the counter arrives there from `2 ** 53 - 1` and breaks
+ *   — so rejecting it is deliberately conservative rather than necessary. A
+ *   cap must be a number the counter can actually arrive at, and
+ *   `MAX_SAFE_INTEGER` is the honest edge of that guarantee.
+ * - `2.5` — consumes 2 pages, then fetches a 3rd and discards it: a request to
+ *   a URL taken from an attacker-influenceable header, whose response is never
+ *   parsed or returned.
+ * - `0`, negative, `NaN` — consume ZERO pages, throwing away a response the
+ *   caller already fetched and passed in.
+ *
+ * SPEC.md §2 step 5: "Validate `max_pages > 0`. → `⊥ BasecampError(code:
+ * "usage")` otherwise."
+ */
+export declare function assertValidMaxPages(maxPages: number): void;
+/**
+ * Default maximum pages to follow as a safety cap against infinite loops.
+ *
+ * Lives here rather than in base.ts because both base.ts and client.ts need it
+ * and this module is the one they can both import without a cycle. A malformed
+ * or hostile Link header can name the page it was served from, so every loop
+ * that follows rel="next" needs a bound that does not depend on the server
+ * ever stopping.
+ */
+export declare const DEFAULT_MAX_PAGES = 10000;
 /**
  * Parses the next URL from a Link header.
  * Looks for rel="next" in the header value.

package/dist/pagination-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination-utils.d.ts","sourceRoot":"","sources":["../src/pagination-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAYtE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAQ1D"}
+{"version":3,"file":"pagination-utils.d.ts","sourceRoot":"","sources":["../src/pagination-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6BH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ1D;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAgBtE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAQ1D"}

package/dist/pagination-utils.js

@@ -5,6 +5,84 @@
  * client.ts (which imports generated services) and base.ts (which
  * generated services extend).
  */
+/**
+ * Extracts the contents of the first non-empty `<...>` pair.
+ *
+ * This is the leftmost-match semantics of `/<([^>]+)>/` in linear time. The
+ * regex form is quadratic on a header carrying many `<` with no reachable `>`,
+ * because every `<` is retried as a start position and each scans to the end.
+ * Searching for `>` from *after* the `<` visits each character once instead.
+ *
+ * An empty `<>` is skipped rather than returned, because `[^>]+` requires at
+ * least one character — the regex would move on to the next `<`, and so does
+ * this. Skipping costs nothing: the scan that found `<>` was O(1), so the loop
+ * only ever repeats after work it did not do.
+ */
+function extractAngleBracketed(part) {
+    let cursor = 0;
+    for (;;) {
+        const start = part.indexOf("<", cursor);
+        if (start < 0)
+            return null;
+        const end = part.indexOf(">", start + 1);
+        if (end < 0)
+            return null;
+        if (end > start + 1)
+            return part.slice(start + 1, end);
+        cursor = start + 1;
+    }
+}
+import { BasecampError } from "./errors.js";
+/**
+ * Rejects any `maxPages` that would defeat or invert the cap.
+ *
+ * Lives here, beside `DEFAULT_MAX_PAGES` and for the same reason: `client.ts`,
+ * `services/base.ts` and this module's own helpers all need it, and this is the
+ * only one of them they can all import without a cycle. Three entry points set
+ * a cap — `createBasecampClient`, the standalone `fetchAllPages`/`paginateAll`,
+ * and `BaseService`'s constructor, which is exported and directly constructible
+ * — and a guard on two of the three is not a guard.
+ *
+ * `Number.isSafeInteger(n) && n > 0` is one predicate covering every value that
+ * breaks the bound, each of which passed silently while `maxPages` was
+ * unvalidated:
+ *
+ * - `Infinity` — `page === maxPages` is never true, so the loop is unbounded
+ *   and the cap does nothing at all. Precisely the runaway it exists to stop.
+ * - Anything ABOVE `2 ** 53`, such as `Number.MAX_VALUE` — the same runaway
+ *   through a different door, and the reason this is `isSafeInteger` rather
+ *   than `isInteger`. `Number.isInteger(Number.MAX_VALUE)` is `true`, so the
+ *   obvious predicate admits it. Past `2 ** 53` the counter stalls: `page++`
+ *   on `2 ** 53` yields `2 ** 53` again, because the next integer is not
+ *   representable, so a bound of `2 ** 53 + 2` is never reached. `2 ** 53`
+ *   ITSELF is fine — the counter arrives there from `2 ** 53 - 1` and breaks
+ *   — so rejecting it is deliberately conservative rather than necessary. A
+ *   cap must be a number the counter can actually arrive at, and
+ *   `MAX_SAFE_INTEGER` is the honest edge of that guarantee.
+ * - `2.5` — consumes 2 pages, then fetches a 3rd and discards it: a request to
+ *   a URL taken from an attacker-influenceable header, whose response is never
+ *   parsed or returned.
+ * - `0`, negative, `NaN` — consume ZERO pages, throwing away a response the
+ *   caller already fetched and passed in.
+ *
+ * SPEC.md §2 step 5: "Validate `max_pages > 0`. → `⊥ BasecampError(code:
+ * "usage")` otherwise."
+ */
+export function assertValidMaxPages(maxPages) {
+    if (!Number.isSafeInteger(maxPages) || maxPages <= 0) {
+        throw new BasecampError("usage", `maxPages must be a positive integer no larger than ${Number.MAX_SAFE_INTEGER}, got ${String(maxPages)}`, { hint: "Pass a whole number greater than 0, or omit maxPages to use the default cap." });
+    }
+}
+/**
+ * Default maximum pages to follow as a safety cap against infinite loops.
+ *
+ * Lives here rather than in base.ts because both base.ts and client.ts need it
+ * and this module is the one they can both import without a cycle. A malformed
+ * or hostile Link header can name the page it was served from, so every loop
+ * that follows rel="next" needs a bound that does not depend on the server
+ * ever stopping.
+ */
+export const DEFAULT_MAX_PAGES = 10_000;
 /**
  * Parses the next URL from a Link header.
  * Looks for rel="next" in the header value.
@@ -18,8 +96,13 @@ export function parseNextLink(linkHeader) {
     for (const part of linkHeader.split(",")) {
         const trimmed = part.trim();
         if (trimmed.includes('rel="next"')) {
-            const match = trimmed.match(/<([^>]+)>/);
-            return match?.[1] ?? null;
+            // Keep scanning if this part is malformed. The previous code returned
+            // unconditionally here, so one unparseable `rel="next"` segment
+            // short-circuited the whole header to null; the other five SDKs fall
+            // through and keep looking.
+            const url = extractAngleBracketed(trimmed);
+            if (url !== null)
+                return url;
         }
     }
     return null;

package/dist/pagination-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination-utils.js","sourceRoot":"","sources":["../src/pagination-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,UAAyB;IACrD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAE7B,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;YACzC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAc;IACrD,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,CAAS;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"pagination-utils.js","sourceRoot":"","sources":["../src/pagination-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AACH,SAAS,qBAAqB,CAAC,IAAY;IACzC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,SAAS,CAAC;QACR,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACxC,IAAI,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACzC,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QACzB,IAAI,GAAG,GAAG,KAAK,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;QACvD,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC;IACrB,CAAC;AACH,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,aAAa,CACrB,OAAO,EACP,sDAAsD,MAAM,CAAC,gBAAgB,SAAS,MAAM,CAAC,QAAQ,CAAC,EAAE,EACxG,EAAE,IAAI,EAAE,8EAA8E,EAAE,CACzF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,UAAyB;IACrD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAE7B,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACnC,sEAAsE;YACtE,gEAAgE;YAChE,qEAAqE;YACrE,4BAA4B;YAC5B,MAAM,GAAG,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAO,GAAG,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAc;IACrD,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,CAAS;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/pagination.d.ts

@@ -26,6 +26,17 @@ export interface PaginationOptions {
      * When undefined or 0, all pages are fetched.
      */
     maxItems?: number;
+    /**
+     * Selects a single page. A positive `page` returns exactly that page in
+     * exactly one request: the `Link: rel="next"` header is not followed, and
+     * `.meta.truncated` reports whether a further page existed. When undefined,
+     * 0, or negative, auto-pagination walks the whole collection.
+     *
+     * Only meaningful for operations whose endpoint honors `?page=`; the handful
+     * of list endpoints that return their whole collection at once never emit a
+     * next link, so pinning a page there changes nothing. See SPEC section 8.
+     */
+    page?: number;
 }
 /**
  * An array of results with pagination metadata.

package/dist/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB;;;;;OAKG;IACH,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,gBAAgB,CAE9C;gBAEW,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ;CAavC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAK1D"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB;;;;;OAKG;IACH,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,gBAAgB,CAE9C;gBAEW,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ;CAavC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAK1D"}