@37signals/basecamp 0.11.0 → 0.13.0

package/dist/client.js

@@ -10,15 +10,16 @@ import metadata from "./generated/metadata.js";
 import { PATH_TO_OPERATION } from "./generated/path-mapping.js";
 import { BasecampError } from "./errors.js";
 import { isLocalhost, requireSameOrigin } from "./security.js";
-import { parseNextLink, resolveURL, isSameOrigin } from "./pagination-utils.js";
+import { parseNextLink, resolveURL, isSameOrigin, DEFAULT_MAX_PAGES, assertValidMaxPages } from "./pagination-utils.js";
 import { bearerAuth } from "./auth-strategy.js";
 import { createDownloadURL } from "./download.js";
+import { DEFAULT_RETRY_CONFIG, NO_RETRY_CONFIG, TerminalRetryError, executeWithRetry, } from "./retry.js";
 // ============================================================================
 // Services - Generated from OpenAPI spec (spec-driven, not hand-written)
 // ============================================================================
 import { ProjectsService } from "./generated/services/projects.js";
 import { TodosService } from "./services/todos-extensions.js";
-import { TodolistsService } from "./generated/services/todolists.js";
+import { TodolistsService } from "./services/todolists-extensions.js";
 import { TodosetsService } from "./generated/services/todosets.js";
 import { HillChartsService } from "./generated/services/hill-charts.js";
 import { PeopleService } from "./generated/services/people.js";
@@ -38,12 +39,19 @@ import { ClientApprovalsService } from "./generated/services/client-approvals.js
 import { ClientCorrespondencesService } from "./generated/services/client-correspondences.js";
 import { ClientRepliesService } from "./generated/services/client-replies.js";
 import { WebhooksService } from "./generated/services/webhooks.js";
+import { BookmarksService } from "./generated/services/bookmarks.js";
+import { FoldersService } from "./generated/services/folders.js";
+import { DraftsService } from "./generated/services/drafts.js";
+import { CalendarsService } from "./generated/services/calendars.js";
+import { MyNotesService } from "./generated/services/my-notes.js";
 import { SubscriptionsService } from "./generated/services/subscriptions.js";
 import { AttachmentsService } from "./generated/services/attachments.js";
 import { VaultsService } from "./generated/services/vaults.js";
-import { DocumentsService } from "./generated/services/documents.js";
+import { DocumentsService } from "./services/documents-extensions.js";
 import { UploadsService } from "./services/uploads-extensions.js";
-import { SchedulesService } from "./generated/services/schedules.js";
+import { CloudFilesService } from "./generated/services/cloud-files.js";
+import { GoogleDocumentsService } from "./generated/services/google-documents.js";
+import { SchedulesService } from "./services/schedules-extensions.js";
 import { EventsService } from "./generated/services/events.js";
 import { RecordingsService } from "./generated/services/recordings.js";
 import { SearchService } from "./generated/services/search.js";
@@ -72,14 +80,14 @@ import { AuthorizationService } from "./services/authorization.js";
  * a TimeoutOverflowWarning rather than honored.
  */
 const MAX_TIMEOUT_MS = 2_147_483_647;
-export const VERSION = "0.11.0";
-export const API_VERSION = "2026-07-30";
+export const VERSION = "0.13.0";
+export const API_VERSION = "2026-08-05";
 const DEFAULT_USER_AGENT = `basecamp-sdk-ts/${VERSION} (api:${API_VERSION})`;
 /**
  * Creates a type-safe Basecamp API client with built-in middleware for:
  * - Authentication (Bearer token)
  * - Retry with exponential backoff (respects Retry-After header)
- * - ETag-based HTTP caching
+ * - ETag-based HTTP caching, opt-in via `enableCache` (defaults to false)
  *
  * @example
  * ```ts
@@ -115,6 +123,24 @@ export function createBasecampClient(options) {
         requestTimeoutMs > MAX_TIMEOUT_MS) {
         throw new BasecampError("usage", `'requestTimeoutMs' must be an integer between 0 and ${MAX_TIMEOUT_MS}, got ${requestTimeoutMs}`);
     }
+    // The cap the standalone helpers validate is the same cap the config carries,
+    // and this is the wider door: `maxPages` here is handed to every service and
+    // reached only later, inside `BaseService`'s `page < this.maxPages` loops, far
+    // from the call that misconfigured it. Same predicate, same error, checked
+    // once at construction — see assertValidMaxPages for what each rejected value
+    // does to the bound. Only when the caller supplied one: an absent cap must
+    // keep falling through to DEFAULT_MAX_PAGES.
+    //
+    // `!= null`, matching BaseService's guard exactly. This value is not consumed
+    // here — it is handed straight to every service below, where `maxPages ??
+    // DEFAULT_MAX_PAGES` treats an explicit `null` as absent. A `!== undefined`
+    // test here made the two doors disagree on that single value: the factory
+    // threw where the equivalent direct service construction defaulted. Whichever
+    // way "not supplied" is defined, both guards have to define it the same way,
+    // because the same `??` is downstream of both.
+    if (maxPages != null) {
+        assertValidMaxPages(maxPages);
+    }
     const authStrategy = auth ?? bearerAuth(accessToken);
     // Validate configuration (skip HTTPS check for localhost in dev/test)
     if (baseUrl) {
@@ -130,28 +156,31 @@ export function createBasecampClient(options) {
             throw new BasecampError("usage", `Invalid base URL: ${baseUrl}`);
         }
     }
-    const client = createClient({ baseUrl });
-    // Apply middleware in order: auth, lifecycle, cache, retry.
+    // One lifecycle, shared between the retrying fetch and the lifecycle
+    // middleware: the fetch owns every attempt's start and each abandoned
+    // attempt's end; the middleware finalizes the terminal outcome.
+    const lifecycle = new RequestLifecycle(hooks);
+    // The retry loop lives BENEATH the middleware chain, as the client's custom
+    // fetch: openapi-fetch calls it exactly once per logical request, after every
+    // onRequest middleware and before every onError/onResponse. Installed
+    // unconditionally — with retry disabled it degenerates to a single attempt —
+    // so hook emission is single-sourced regardless of config.
+    const client = createClient({
+        baseUrl,
+        fetch: createRetryingFetch(lifecycle, authStrategy, enableRetry),
+    });
+    // Apply middleware in order: auth, lifecycle, cache.
     // onRequest runs in this order; onResponse and onError run in reverse, so the
-    // retry middleware sees a response first and the lifecycle middleware last.
+    // lifecycle middleware finalizes the terminal attempt only after the cache
+    // middleware has had its chance to transform the response.
     client.use(createAuthMiddleware(authStrategy, userAgent, requestTimeoutMs, baseUrl));
-    // One lifecycle, shared with the retry middleware: the retry loop lives inside a
-    // single middleware callback, so per-attempt hooks have to be emitted from there
-    // rather than by a middleware that is only visited once per request.
-    const lifecycle = new RequestLifecycle(hooks);
     // Registered even when no hooks are configured. It emits nothing in that case
-    // (every call is optional-chained), but it still owns releasing per-request
-    // state — and the retry middleware records an attempt whether or not anyone is
-    // listening, so skipping this would strand one map entry per retried request.
+    // (every call is optional-chained), but registering it unconditionally keeps
+    // the finalize path identical whether or not anyone is listening.
     client.use(createLifecycleMiddleware(lifecycle));
     if (enableCache) {
         client.use(createCacheMiddleware());
     }
-    // Registered last so that on the reverse-order response pass it runs first,
-    // before the cache and lifecycle middleware see the response.
-    if (enableRetry) {
-        client.use(createRetryMiddleware(lifecycle, authStrategy));
-    }
     // Create enhanced client with additional properties
     const enhancedClient = client;
     Object.defineProperty(enhancedClient, "raw", {
@@ -207,7 +236,7 @@ export function createBasecampClient(options) {
     // Wire downloadURL — raw fetch, not openapi-fetch (like fetchPage).
     // Defined before service factories so UploadsService can inject it.
     const downloadURLFn = createDownloadURL({
-        authStrategy, userAgent, baseUrl, hooks, requestTimeoutMs,
+        authStrategy, userAgent, baseUrl, hooks, requestTimeoutMs, enableRetry,
     });
     Object.defineProperty(enhancedClient, "downloadURL", {
         value: downloadURLFn,
@@ -237,10 +266,17 @@ export function createBasecampClient(options) {
     defineService("clientCorrespondences", () => new ClientCorrespondencesService(client, hooks, fetchPage, maxPages));
     defineService("clientReplies", () => new ClientRepliesService(client, hooks, fetchPage, maxPages));
     defineService("webhooks", () => new WebhooksService(client, hooks, fetchPage, maxPages));
+    defineService("bookmarks", () => new BookmarksService(client, hooks, fetchPage, maxPages));
+    defineService("folders", () => new FoldersService(client, hooks, fetchPage, maxPages));
+    defineService("drafts", () => new DraftsService(client, hooks, fetchPage, maxPages));
+    defineService("calendars", () => new CalendarsService(client, hooks, fetchPage, maxPages));
+    defineService("myNotes", () => new MyNotesService(client, hooks, fetchPage, maxPages));
     defineService("subscriptions", () => new SubscriptionsService(client, hooks, fetchPage, maxPages));
     defineService("attachments", () => new AttachmentsService(client, hooks, fetchPage, maxPages));
     defineService("vaults", () => new VaultsService(client, hooks, fetchPage, maxPages));
     defineService("documents", () => new DocumentsService(client, hooks, fetchPage, maxPages));
+    defineService("cloudFiles", () => new CloudFilesService(client, hooks, fetchPage, maxPages));
+    defineService("googleDocuments", () => new GoogleDocumentsService(client, hooks, fetchPage, maxPages));
     defineService("uploads", () => 
     // Positional args mirror BaseService (incl. authenticatedFetch/baseUrl slots the
     // factory leaves unset), with downloadURLFn appended at the end.
@@ -301,45 +337,41 @@ function createAuthMiddleware(authStrategy, userAgent, requestTimeoutMs, baseUrl
     };
 }
 /**
- * Owns the onRequestStart / onRequestEnd / onRetry lifecycle for every attempt of
- * every in-flight request, keyed by openapi-fetch's per-request `id`.
+ * Owns the onRequestStart / onRequestEnd / onRetry lifecycle for every attempt
+ * of every in-flight request, keyed by the final Request object openapi-fetch
+ * hands to its custom fetch.
  *
- * The id is minted once per logical request (one client.GET/POST/... call) and is
- * passed unchanged to onRequest, onResponse and onError, so it survives a
- * middleware replacing the Request object. It deliberately does NOT distinguish
- * attempts — per-attempt data lives nested under it here — and it never goes on
- * the wire, which is why this replaces the old `X-SDK-Request-Id` and
- * `X-Request-Id` correlation headers. (`X-Request-Id` in particular is a
- * spec-reserved BC3 *response* header; sending an SDK-internal value under that
- * name was a collision.)
+ * openapi-fetch passes that same object to onResponse and onError, so identity
+ * holds from the retrying fetch (which begins every attempt) through to the
+ * lifecycle middleware (which finalizes the terminal one). Nothing ever goes on
+ * the wire — this keying replaced the old `X-SDK-Request-Id` and `X-Request-Id`
+ * correlation headers. (`X-Request-Id` in particular is a spec-reserved BC3
+ * *response* header; sending an SDK-internal value under that name was a
+ * collision.)
  *
- * Shared with the retry middleware because the retry loop lives inside
- * one middleware callback: openapi-fetch visits each middleware once per request,
- * so per-attempt hooks cannot be emitted by a separate middleware.
+ * A WeakMap makes the release bookkeeping structural: once a request settles
+ * and its Request is unreachable, the state is collectable — there is no
+ * release() to forget.
  */
 class RequestLifecycle {
     hooks;
-    states = new Map();
+    states = new WeakMap();
     constructor(hooks) {
         this.hooks = hooks;
     }
     /** Begin an attempt and fire onRequestStart for it. */
-    begin(id, method, url, attempt) {
-        this.states.set(id, { startTime: performance.now(), attempt, finalized: false });
+    begin(request, method, url, attempt) {
+        this.states.set(request, { startTime: performance.now(), attempt, finalized: false });
         this.emit(() => this.hooks?.onRequestStart?.({ method, url, attempt }));
     }
-    /** The attempt currently in flight, or 1 if we have no record. */
-    attemptOf(id) {
-        return this.states.get(id)?.attempt ?? 1;
-    }
     /**
      * Fire onRequestEnd for the in-flight attempt, exactly once.
      *
      * A network failure or timeout carries statusCode 0 and the originating error,
      * matching the multipart transport in services/base.ts and SPEC section 7.
      */
-    finalize(id, method, url, outcome) {
-        const state = this.states.get(id);
+    finalize(request, method, url, outcome) {
+        const state = this.states.get(request);
         if (!state || state.finalized)
             return;
         state.finalized = true;
@@ -359,13 +391,9 @@ class RequestLifecycle {
      * just FAILED, while the standalone argument is the UPCOMING attempt. Go,
      * Python, Ruby and Kotlin all pass (failed, failed + 1).
      */
-    retrying(id, method, url, failedAttempt, error, delayMs) {
+    retrying(method, url, failedAttempt, error, delayMs) {
         this.emit(() => this.hooks?.onRetry?.({ method, url, attempt: failedAttempt }, failedAttempt + 1, error, delayMs));
     }
-    /** Drop all state for a logical request. Safe to call more than once. */
-    release(id) {
-        this.states.delete(id);
-    }
     emit(fn) {
         try {
             fn();
@@ -377,37 +405,32 @@ class RequestLifecycle {
 }
 function createLifecycleMiddleware(lifecycle) {
     return {
-        async onRequest({ request, id }) {
-            lifecycle.begin(id, request.method, request.url, 1);
-            return request;
-        },
-        async onResponse({ request, response, id }) {
-            // The authoritative end for whichever attempt is in flight: attempt 1 for a
-            // single-attempt request, or attempt 2 after a retry — the retry middleware
-            // deliberately does not finalize a successful attempt, so that the cache
-            // middleware (which runs between the two) can transform the response first.
-            // finalize stays idempotent as a backstop.
+        async onResponse({ request, response }) {
+            // The authoritative end for the terminal attempt: the retrying fetch
+            // begins every attempt but deliberately does not finalize the response it
+            // returns, so that this pass can record the outcome the cache middleware
+            // has since transformed (a 304 rewritten into a cached 200). finalize
+            // stays idempotent as a backstop.
             //
             // fromCache means "served out of the ETag cache", and only the header the
             // cache middleware sets proves that. A bare 304 does NOT: it reaches here
             // when the cache is disabled, or is enabled but holds no entry for this key,
             // and in both cases the caller's own conditional request went to the server.
             const fromCache = response.headers.get("X-From-Cache") === "1";
-            lifecycle.finalize(id, request.method, request.url, {
+            lifecycle.finalize(request, request.method, request.url, {
                 statusCode: response.status,
                 fromCache,
             });
-            lifecycle.release(id);
             return response;
         },
-        async onError({ request, error, id }) {
-            // openapi-fetch skips onResponse entirely when the initial fetch rejects,
-            // so this is the only place a network error or timeout can be observed.
-            lifecycle.finalize(id, request.method, request.url, {
+        async onError({ request, error }) {
+            // A terminal throw from the retrying fetch — a network error, a timeout,
+            // or a retry's auth refresh — skips onResponse entirely, so this is the
+            // only place it can be observed.
+            lifecycle.finalize(request, request.method, request.url, {
                 statusCode: 0,
                 error: error instanceof Error ? error : new Error(String(error)),
             });
-            lifecycle.release(id);
             // Returning nothing preserves the original error's identity and rethrows it.
             return undefined;
         },
@@ -523,21 +546,12 @@ function createCacheMiddleware() {
 function getCacheKey(url, tokenHash) {
     return `${tokenHash}:${url}`;
 }
-/** Default retry config used when no operation-specific config is available */
-const DEFAULT_RETRY_CONFIG = {
-    maxAttempts: 3,
-    baseDelayMs: 1000,
-    backoff: "exponential",
-    retryOn: [429, 503],
-};
-/** No-retry config for non-idempotent POST operations */
-const NO_RETRY_CONFIG = {
-    maxAttempts: 1,
-    baseDelayMs: 0,
-    backoff: "constant",
-    retryOn: [],
-};
-const MAX_JITTER_MS = 100;
+// =============================================================================
+// Retrying Fetch (the retry loop, beneath the middleware chain)
+// =============================================================================
+// The retry loop itself lives in retry.ts (executeWithRetry) so the raw-fetch
+// download hop 1 shares it; this section owns what is client-specific — the
+// operation-metadata config resolution and the openapi-fetch integration.
 // PATH_TO_OPERATION is imported from generated/path-mapping.js
 /**
  * Normalizes a URL path by replacing numeric IDs with placeholder tokens.
@@ -577,6 +591,8 @@ export function normalizeUrlPath(url) {
         comments: "{commentId}",
         tools: "{toolId}", // dock/tools/{toolId}
         documents: "{documentId}",
+        cloud_files: "{cloudFileId}",
+        google_documents: "{googleDocumentId}",
         inbox_forwards: "{forwardId}",
         inboxes: "{inboxId}",
         message_boards: "{boardId}",
@@ -679,148 +695,111 @@ function getRetryConfigForRequest(method, url) {
     }
     return DEFAULT_RETRY_CONFIG;
 }
-function createRetryMiddleware(lifecycle, authStrategy) {
-    // Serialized request bodies, keyed by openapi-fetch's per-request id, because
-    // Request.body can only be read once and the retry needs to replay it. Keyed on
-    // the id rather than method+url+timestamp: two concurrent mutations to the same
-    // URL used to collide on one slot and replay each other's bytes.
-    const bodyCache = new Map();
-    return {
-        async onRequest({ request, id }) {
-            // For methods that may have a body, clone it before the initial fetch
-            // so we can use it for retries. Request.body can only be consumed once.
-            const method = request.method.toUpperCase();
-            if (method === "POST" || method === "PUT" || method === "PATCH") {
-                if (request.body) {
-                    // Clone the body before it gets consumed
-                    const cloned = request.clone();
-                    bodyCache.set(id, await cloned.arrayBuffer());
-                }
-                else {
-                    bodyCache.set(id, null);
-                }
-            }
-            return request;
-        },
-        async onResponse({ request, response, id }) {
-            const { method, url } = request;
-            // Get operation-specific retry config from metadata
-            const retryConfig = getRetryConfigForRequest(method, url);
-            // Not retrying: let the lifecycle middleware end the attempt, and drop the body.
-            if (!retryConfig.retryOn.includes(response.status)) {
-                bodyCache.delete(id);
-                return response;
-            }
-            const failedAttempt = lifecycle.attemptOf(id);
-            // maxAttempts is a total attempt count, so attempt N is terminal when it
-            // equals the cap. TypeScript additionally chains at most one retry, since
-            // the retry below leaves the middleware chain (SPEC waiver 2B.1).
-            if (failedAttempt >= retryConfig.maxAttempts) {
-                bodyCache.delete(id);
-                return response;
-            }
-            // For 429, respect Retry-After; otherwise back off.
-            let delay;
-            const retryAfter = response.status === 429 ? response.headers.get("Retry-After") : null;
-            const retryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : NaN;
-            if (!isNaN(retryAfterSeconds)) {
-                delay = retryAfterSeconds * 1000;
-            }
-            else {
-                delay = calculateBackoffDelay(retryConfig, failedAttempt - 1);
-            }
-            const statusError = new Error(`HTTP ${response.status}: ${response.statusText || "Request failed"}`);
-            try {
-                // End the failed attempt before sleeping, so a slow backoff cannot leave
-                // an attempt open, then announce the upcoming one.
-                lifecycle.finalize(id, method, url, { statusCode: response.status });
-                lifecycle.retrying(id, method, url, failedAttempt, statusError, delay);
-                // This response is being discarded, so release its stream before we sleep
-                // rather than leaving it open across the backoff — otherwise a throttled
-                // client holds a connection per in-flight retry and cannot reuse any of
-                // them. The multipart transport in services/base.ts already does this.
-                // Errors are ignored: the body may already be consumed or closed.
-                void response.body?.cancel().catch(() => { });
-                await sleep(delay);
-                // The raw fetch below bypasses the middleware chain, so no downstream
-                // middleware sees this attempt begin — start it here.
-                //
-                // Started after the backoff but before any work that can throw. After, so
-                // the attempt's duration measures the request rather than the sleep;
-                // before, so that if the auth refresh or the fetch throws, the catch has a
-                // live attempt to finalize. Starting it later would let onRetry announce
-                // attempt 2 and then never account for it.
-                lifecycle.begin(id, method, url, failedAttempt + 1);
-                const body = bodyCache.get(id) ?? null;
-                const retryRequest = new Request(url, {
+/**
+ * The retry loop, installed beneath the middleware chain as the client's custom
+ * fetch (createClient's `fetch` option). openapi-fetch calls it exactly once
+ * per logical request, after every onRequest middleware and before every
+ * onError/onResponse — so the loop runs to the operation's full declared
+ * maxAttempts, and no attempt ever leaves the chain, because the chain sits
+ * above the loop.
+ *
+ * Division of labor with the lifecycle middleware: the loop begins EVERY
+ * attempt and finalizes the attempts it abandons (before the backoff sleep);
+ * the terminal outcome — the response it returns, or the error it throws — is
+ * deliberately NOT finalized here. It flows up through the cache middleware,
+ * which may rewrite a 304 into a cached 200 + X-From-Cache, to the lifecycle
+ * middleware, which records the post-transform result. Finalizing in the loop
+ * would freeze the pre-transformation status, and the idempotent finalize
+ * would keep the hooks pass from correcting it.
+ *
+ * With retry disabled the loop degenerates to a single attempt but still owns
+ * hook emission, so start/end events are single-sourced regardless of config.
+ */
+function createRetryingFetch(lifecycle, authStrategy, enableRetry) {
+    return async (request) => {
+        const { method, url } = request;
+        const retryConfig = getRetryConfigForRequest(method, url);
+        const effectiveConfig = {
+            ...retryConfig,
+            maxAttempts: enableRetry ? retryConfig.maxAttempts : 1,
+        };
+        // Serialize the body once, before the first send, because Request.body is
+        // a stream that can only be consumed once and a retry needs to replay it.
+        // clone() tees the stream, so attempt 1 sends the original untouched and
+        // replays read from this buffer. Requests that can never retry — including
+        // every non-idempotent POST, via NO_RETRY_CONFIG — skip the buffering.
+        const upperMethod = method.toUpperCase();
+        let bodyBuffer = null;
+        if (effectiveConfig.maxAttempts > 1 &&
+            (upperMethod === "POST" || upperMethod === "PUT" || upperMethod === "PATCH") &&
+            request.body) {
+            bodyBuffer = await request.clone().arrayBuffer();
+        }
+        let attemptRequest = request;
+        const makeAttempt = async (attempt) => {
+            if (attempt > 1) {
+                // Rebuild from the original request: the headers carry everything the
+                // onRequest middleware attached (auth, User-Agent, If-None-Match), and
+                // the signal keeps the caller's cancellation and the per-request
+                // timeout — one budget shared by all attempts and backoffs.
+                attemptRequest = new Request(url, {
                     method,
                     headers: new Headers(request.headers),
-                    body,
+                    body: bodyBuffer,
                     signal: request.signal,
                 });
-                // Refresh auth header for retry (token may have been refreshed since initial request)
-                if (authStrategy) {
-                    await authStrategy.authenticate(retryRequest.headers);
+                // Refresh auth (the token may have rotated since the last attempt).
+                // The attempt is already begun, so a throwing refresh lands on a live
+                // attempt; the terminal marker carries it raw past the loop's retry
+                // classification to the lifecycle middleware's onError.
+                try {
+                    await authStrategy.authenticate(attemptRequest.headers);
+                }
+                catch (error) {
+                    throw new TerminalRetryError(error);
                 }
-                // Deliberately NOT finalized here. The returned response still flows
-                // through the cache middleware, which may rewrite a 304 into a cached 200;
-                // finalizing now would freeze the pre-transformation status and
-                // fromCache: false, and an idempotent finalize means the hooks pass could
-                // not correct it. The lifecycle middleware ends this attempt instead, reading
-                // attempt 2 from the state begun above.
-                return await fetch(retryRequest);
-            }
-            catch (error) {
-                // openapi-fetch routes only the INITIAL fetch through onError, so anything
-                // thrown in here — the retry fetch, the auth refresh, the sleep — would
-                // otherwise escape with the attempt still open and its state stranded.
-                lifecycle.finalize(id, method, url, {
-                    statusCode: 0,
-                    error: error instanceof Error ? error : new Error(String(error)),
-                });
-                lifecycle.release(id);
-                // Rethrow the original value so its identity survives.
-                throw error;
-            }
-            finally {
-                bodyCache.delete(id);
             }
-        },
-        async onError({ id }) {
-            // The initial fetch rejected, so onResponse never ran and the cached body
-            // would leak. The lifecycle middleware owns ending the attempt.
-            bodyCache.delete(id);
-            return undefined;
-        },
+            // globalThis.fetch resolved per attempt rather than captured at client
+            // creation, so test interceptors that patch it (MSW) are honored.
+            return globalThis.fetch(attemptRequest);
+        };
+        const emit = {
+            begin: (attempt) => lifecycle.begin(request, method, url, attempt),
+            finalize: (outcome) => lifecycle.finalize(request, method, url, outcome),
+            retrying: (failedAttempt, error, delayMs) => lifecycle.retrying(method, url, failedAttempt, error, delayMs),
+        };
+        try {
+            return await executeWithRetry(makeAttempt, effectiveConfig, emit, request.signal);
+        }
+        catch (error) {
+            // Unwrap the terminal marker so the original error's identity survives
+            // to the lifecycle middleware's onError (and to the caller).
+            throw error instanceof TerminalRetryError ? error.reason : error;
+        }
     };
 }
-function calculateBackoffDelay(config, attempt) {
-    const base = config.baseDelayMs;
-    let delay;
-    switch (config.backoff) {
-        case "exponential":
-            delay = base * Math.pow(2, attempt);
-            break;
-        case "linear":
-            delay = base * (attempt + 1);
-            break;
-        case "constant":
-        default:
-            delay = base;
-    }
-    // Add jitter (0-100ms)
-    const jitter = Math.random() * MAX_JITTER_MS;
-    return delay + jitter;
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
 // =============================================================================
 // Pagination Helper
 // =============================================================================
 /**
  * Fetches all pages of a paginated resource using Link header pagination.
- * Automatically follows rel="next" links until no more pages exist.
+ * Automatically follows rel="next" links until no more pages exist, or until
+ * `maxPages` pages have been consumed.
+ *
+ * The cap is not optional in spirit: a Link header naming the page it was
+ * served from makes "until no more pages exist" never true, and the header is
+ * attacker-influenced (that is why `isSameOrigin` is checked below). Every
+ * other pagination loop in this SDK, and in the other five, is bounded the
+ * same way. Reaching the cap stops quietly — there is no meta channel on a
+ * bare `T[]` to report it, and throwing would break callers who legitimately
+ * have that many pages.
+ *
+ * @param maxPages - Safety cap on pages CONSUMED. Must be a positive integer;
+ *   `0`, negatives, `NaN`, `Infinity` and non-integers all throw
+ *   `BasecampError("usage")` before any request is made. Defaults to
+ *   `DEFAULT_MAX_PAGES`.
+ * @throws {BasecampError} with `code: "usage"` if `maxPages` is not a positive
+ *   integer.
  *
  * @example
  * ```ts
@@ -832,12 +811,22 @@ function sleep(ms) {
  * );
  * ```
  */
-export async function fetchAllPages(initialResponse, parse, authHeader) {
+export async function fetchAllPages(initialResponse, parse, authHeader, maxPages = DEFAULT_MAX_PAGES) {
+    assertValidMaxPages(maxPages);
     const results = [];
     let response = initialResponse;
-    while (true) {
+    for (let page = 1; page <= maxPages; page++) {
         const items = await parse(response.clone());
         results.push(...items);
+        // Before reading the Link header, not after fetching it. The loop consumes
+        // the current page at the head of the iteration and fetches the next at the
+        // tail, so testing the cap only in the `for` condition would let the final
+        // allowed iteration issue a request whose response is never parsed and
+        // never returned — and that request goes to a URL taken from an
+        // attacker-influenceable header. `maxPages` counts pages CONSUMED, matching
+        // BaseService.followPagination.
+        if (page === maxPages)
+            break;
         const rawNextUrl = parseNextLink(response.headers.get("Link"));
         if (!rawNextUrl)
             break;
@@ -859,6 +848,23 @@ export async function fetchAllPages(initialResponse, parse, authHeader) {
  * Async generator that yields pages of results one at a time.
  * Useful for processing large datasets without loading everything into memory.
  *
+ * Bounded by `maxPages` for the same reason as {@link fetchAllPages}: a Link
+ * header that points at its own page would otherwise yield forever.
+ *
+ * Validation is EAGER, which is why this is a plain function returning a
+ * generator rather than an `async function*`. The body of an `async function*`
+ * does not run until something iterates it, so a check written inside one would
+ * surface a bad `maxPages` at some later `for await` — possibly in a different
+ * function, on a generator that was passed along. A usage error is a programmer
+ * error and belongs at the call site that made it.
+ *
+ * @param maxPages - Safety cap on pages CONSUMED. Must be a positive integer;
+ *   `0`, negatives, `NaN`, `Infinity` and non-integers all throw
+ *   `BasecampError("usage")` from this call, before the generator is created
+ *   and before any request is made. Defaults to `DEFAULT_MAX_PAGES`.
+ * @throws {BasecampError} with `code: "usage"` if `maxPages` is not a positive
+ *   integer.
+ *
  * @example
  * ```ts
  * for await (const page of paginateAll(response.response, (r) => r.json() as Promise<any[]>)) {
@@ -866,11 +872,25 @@ export async function fetchAllPages(initialResponse, parse, authHeader) {
  * }
  * ```
  */
-export async function* paginateAll(initialResponse, parse, authHeader) {
+export function paginateAll(initialResponse, parse, authHeader, maxPages = DEFAULT_MAX_PAGES) {
+    assertValidMaxPages(maxPages);
+    return paginatePages(initialResponse, parse, authHeader, maxPages);
+}
+/**
+ * The generator body behind {@link paginateAll}. Split out only so the cap can
+ * be validated before the generator object exists; `maxPages` is already known
+ * good here.
+ */
+async function* paginatePages(initialResponse, parse, authHeader, maxPages) {
     let response = initialResponse;
-    while (true) {
+    for (let page = 1; page <= maxPages; page++) {
         const items = await parse(response.clone());
         yield items;
+        // See {@link fetchAllPages}: breaking here rather than relying on the loop
+        // condition is what keeps the last allowed iteration from issuing a fetch
+        // whose response is never yielded.
+        if (page === maxPages)
+            break;
         const rawNextUrl = parseNextLink(response.headers.get("Link"));
         if (!rawNextUrl)
             break;