@37signals/basecamp 0.10.0 → 0.12.0

package/dist/client.js

@@ -38,6 +38,10 @@ 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 { 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";
@@ -72,8 +76,8 @@ import { AuthorizationService } from "./services/authorization.js";
  * a TimeoutOverflowWarning rather than honored.
  */
 const MAX_TIMEOUT_MS = 2_147_483_647;
-export const VERSION = "0.10.0";
-export const API_VERSION = "2026-07-28";
+export const VERSION = "0.12.0";
+export const API_VERSION = "2026-07-31";
 const DEFAULT_USER_AGENT = `basecamp-sdk-ts/${VERSION} (api:${API_VERSION})`;
 /**
  * Creates a type-safe Basecamp API client with built-in middleware for:
@@ -130,18 +134,31 @@ export function createBasecampClient(options) {
             throw new BasecampError("usage", `Invalid base URL: ${baseUrl}`);
         }
     }
-    const client = createClient({ baseUrl });
-    // Apply middleware in order: auth first, then hooks, then cache, then 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
+    // 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));
-    if (hooks) {
-        client.use(createHooksMiddleware(hooks));
-    }
+    // Registered even when no hooks are configured. It emits nothing in that case
+    // (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());
     }
-    if (enableRetry) {
-        client.use(createRetryMiddleware(hooks, authStrategy));
-    }
     // Create enhanced client with additional properties
     const enhancedClient = client;
     Object.defineProperty(enhancedClient, "raw", {
@@ -227,6 +244,10 @@ 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("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));
@@ -290,60 +311,104 @@ function createAuthMiddleware(authStrategy, userAgent, requestTimeoutMs, baseUrl
         },
     };
 }
-/** Counter for generating unique request IDs */
-let requestIdCounter = 0;
-function createHooksMiddleware(hooks) {
-    // Track request timing by unique request ID
-    const timings = new Map();
+/**
+ * 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.
+ *
+ * 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.)
+ *
+ * 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 WeakMap();
+    constructor(hooks) {
+        this.hooks = hooks;
+    }
+    /** Begin an attempt and fire onRequestStart for it. */
+    begin(request, method, url, attempt) {
+        this.states.set(request, { startTime: performance.now(), attempt, finalized: false });
+        this.emit(() => this.hooks?.onRequestStart?.({ method, url, attempt }));
+    }
+    /**
+     * 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(request, method, url, outcome) {
+        const state = this.states.get(request);
+        if (!state || state.finalized)
+            return;
+        state.finalized = true;
+        const durationMs = Math.round(performance.now() - state.startTime);
+        const result = {
+            statusCode: outcome.statusCode,
+            durationMs,
+            fromCache: outcome.fromCache ?? false,
+            ...(outcome.error ? { error: outcome.error } : {}),
+        };
+        this.emit(() => this.hooks?.onRequestEnd?.({ method, url, attempt: state.attempt }, result));
+    }
+    /**
+     * Fire onRetry between two attempts.
+     *
+     * SPEC section 7 splits the two numbers: RequestInfo.attempt is the attempt that
+     * just FAILED, while the standalone argument is the UPCOMING attempt. Go,
+     * Python, Ruby and Kotlin all pass (failed, failed + 1).
+     */
+    retrying(method, url, failedAttempt, error, delayMs) {
+        this.emit(() => this.hooks?.onRetry?.({ method, url, attempt: failedAttempt }, failedAttempt + 1, error, delayMs));
+    }
+    emit(fn) {
+        try {
+            fn();
+        }
+        catch {
+            // Hooks must never interrupt the request.
+        }
+    }
+}
+function createLifecycleMiddleware(lifecycle) {
     return {
-        async onRequest({ request }) {
-            // Generate unique request ID to handle concurrent identical requests
-            const requestId = `${++requestIdCounter}`;
-            request.headers.set("X-SDK-Request-Id", requestId);
-            const attemptHeader = request.headers.get("X-Retry-Attempt");
-            const attempt = attemptHeader ? parseInt(attemptHeader, 10) + 1 : 1;
-            timings.set(requestId, { startTime: performance.now(), attempt });
-            const info = {
-                method: request.method,
-                url: request.url,
-                attempt,
-            };
-            try {
-                hooks.onRequestStart?.(info);
-            }
-            catch {
-                // Hooks should not interrupt the request
-            }
-            return request;
-        },
         async onResponse({ request, response }) {
-            const requestId = request.headers.get("X-SDK-Request-Id") ?? "";
-            const timing = timings.get(requestId);
-            const durationMs = timing ? Math.round(performance.now() - timing.startTime) : 0;
-            const attempt = timing?.attempt ?? 1;
-            timings.delete(requestId);
-            const info = {
-                method: request.method,
-                url: request.url,
-                attempt,
-            };
-            // Check for cache hit via header set by cache middleware
-            const fromCacheHeader = response.headers.get("X-From-Cache");
-            const fromCache = fromCacheHeader === "1" ||
-                response.status === 304;
-            const result = {
+            // 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(request, request.method, request.url, {
                 statusCode: response.status,
-                durationMs,
                 fromCache,
-            };
-            try {
-                hooks.onRequestEnd?.(info, result);
-            }
-            catch {
-                // Hooks should not interrupt the response
-            }
+            });
             return response;
         },
+        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)),
+            });
+            // Returning nothing preserves the original error's identity and rethrows it.
+            return undefined;
+        },
     };
 }
 const MAX_CACHE_ENTRIES = 1000;
@@ -612,113 +677,138 @@ function getRetryConfigForRequest(method, url) {
     }
     return DEFAULT_RETRY_CONFIG;
 }
-function createRetryMiddleware(hooks, authStrategy) {
-    // Store request body clones keyed by a request identifier
-    // This is needed because Request.body can only be read once
-    const bodyCache = new Map();
-    return {
-        async onRequest({ request }) {
-            // 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") {
-                const requestId = `${method}:${request.url}:${Date.now()}`;
-                request.headers.set("X-Request-Id", requestId);
-                if (request.body) {
-                    // Clone the body before it gets consumed
-                    const cloned = request.clone();
-                    bodyCache.set(requestId, await cloned.arrayBuffer());
-                }
-                else {
-                    bodyCache.set(requestId, null);
-                }
+/**
+ * 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 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 (maxAttempts > 1 &&
+            (upperMethod === "POST" || upperMethod === "PUT" || upperMethod === "PATCH") &&
+            request.body) {
+            bodyBuffer = await request.clone().arrayBuffer();
+        }
+        let attempt = 1;
+        let attemptRequest = request;
+        lifecycle.begin(request, method, url, attempt);
+        for (;;) {
+            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: bodyBuffer,
+                    signal: request.signal,
+                });
+                // 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 and propagates to the lifecycle middleware's onError.
+                await authStrategy.authenticate(attemptRequest.headers);
             }
-            return request;
-        },
-        async onResponse({ request, response }) {
-            // Get operation-specific retry config from metadata
-            const retryConfig = getRetryConfigForRequest(request.method, request.url);
-            const requestId = request.headers.get("X-Request-Id");
-            // Helper to clean up cached body
-            const cleanupBody = () => {
-                if (requestId)
-                    bodyCache.delete(requestId);
-            };
-            // Check if status code should trigger retry
-            if (!retryConfig.retryOn.includes(response.status)) {
-                cleanupBody();
-                return response;
+            let response;
+            try {
+                // globalThis.fetch resolved per attempt rather than captured at client
+                // creation, so test interceptors that patch it (MSW) are honored.
+                response = await globalThis.fetch(attemptRequest);
+            }
+            catch (error) {
+                // An abort is terminal no matter what the budget says: a caller
+                // cancellation must not re-send, and the per-request timeout is one
+                // budget shared by every attempt and backoff — once it fires, a retry
+                // would instantly re-reject. Terminal errors are rethrown as-is so
+                // their identity survives to the lifecycle middleware's onError (and
+                // to the caller).
+                //
+                // The signal is the authoritative abort test: a caller can abort with
+                // a CUSTOM reason — AbortController.abort(reason) — and fetch then
+                // rejects with that reason, not a DOMException named AbortError. The
+                // DOMException check remains for abort-shaped rejections that arrive
+                // without an aborted request signal.
+                const isAbort = request.signal?.aborted === true ||
+                    (error instanceof DOMException &&
+                        (error.name === "AbortError" || error.name === "TimeoutError"));
+                if (isAbort || attempt >= maxAttempts) {
+                    throw error;
+                }
+                // Network-error retry rides the same per-operation gate as status
+                // retry: a non-idempotent POST resolves NO_RETRY_CONFIG (maxAttempts
+                // 1), so it is rethrown above after its single attempt.
+                const cause = error instanceof Error ? error : new Error(String(error));
+                const delay = calculateBackoffDelay(retryConfig, attempt - 1);
+                lifecycle.finalize(request, method, url, { statusCode: 0, error: cause });
+                lifecycle.retrying(method, url, attempt, cause, delay);
+                await sleep(delay, request.signal);
+                // Same placement rationale as the status path below.
+                attempt += 1;
+                lifecycle.begin(request, method, url, attempt);
+                continue;
             }
-            // Extract current retry attempt from custom header
-            const attemptHeader = request.headers.get("X-Retry-Attempt");
-            const attempt = attemptHeader ? parseInt(attemptHeader, 10) : 0;
-            // Check if we've exhausted retries (maxAttempts is total attempts, not retries)
-            // With maxAttempts=3: attempt 0 (initial), 1 (retry 1), 2 (retry 2) = 3 total
-            if (attempt >= retryConfig.maxAttempts - 1) {
-                cleanupBody();
+            // Terminal: a status outside the operation's declared retryOn set, or a
+            // spent budget — maxAttempts is a total attempt count, so attempt N is
+            // terminal when it equals the cap.
+            if (!retryConfig.retryOn.includes(response.status) || attempt >= maxAttempts) {
                 return response;
             }
-            // Calculate delay
+            // For 429, respect Retry-After; otherwise back off.
             let delay;
-            // For 429, respect Retry-After header
-            if (response.status === 429) {
-                const retryAfter = response.headers.get("Retry-After");
-                if (retryAfter) {
-                    const seconds = parseInt(retryAfter, 10);
-                    if (!isNaN(seconds)) {
-                        delay = seconds * 1000;
-                    }
-                    else {
-                        delay = calculateBackoffDelay(retryConfig, attempt);
-                    }
-                }
-                else {
-                    delay = calculateBackoffDelay(retryConfig, attempt);
-                }
+            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, attempt);
-            }
-            // Notify hooks of retry
-            if (hooks?.onRetry) {
-                const info = {
-                    method: request.method,
-                    url: request.url,
-                    attempt: attempt + 1,
-                };
-                const error = new Error(`HTTP ${response.status}: ${response.statusText || "Request failed"}`);
-                try {
-                    hooks.onRetry(info, attempt + 1, error, delay);
-                }
-                catch {
-                    // Hooks should not interrupt the retry
-                }
+                delay = calculateBackoffDelay(retryConfig, attempt - 1);
             }
-            // Wait before retry
-            await sleep(delay);
-            // Get cached body for methods that may have one
-            let body = null;
-            if (requestId && bodyCache.has(requestId)) {
-                const cachedBody = bodyCache.get(requestId);
-                if (cachedBody) {
-                    body = cachedBody;
-                }
-            }
-            // Create retry request with fresh body
-            const retryRequest = new Request(request.url, {
-                method: request.method,
-                headers: new Headers(request.headers),
-                body,
-                signal: request.signal,
-            });
-            retryRequest.headers.set("X-Retry-Attempt", String(attempt + 1));
-            // Refresh auth header for retry (token may have been refreshed since initial request)
-            if (authStrategy) {
-                await authStrategy.authenticate(retryRequest.headers);
-            }
-            // Retry using native fetch
-            return fetch(retryRequest);
-        },
+            const statusError = new Error(`HTTP ${response.status}: ${response.statusText || "Request failed"}`);
+            // End the failed attempt before sleeping, so a slow backoff cannot leave
+            // an attempt open, then announce the upcoming one.
+            lifecycle.finalize(request, method, url, { statusCode: response.status });
+            lifecycle.retrying(method, url, attempt, 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, request.signal);
+            // Begun 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 lifecycle
+            // middleware's onError still finds a live attempt to finalize. Starting
+            // it later would let onRetry announce an attempt and then never account
+            // for it.
+            attempt += 1;
+            lifecycle.begin(request, method, url, attempt);
+        }
     };
 }
 function calculateBackoffDelay(config, attempt) {
@@ -739,8 +829,29 @@ function calculateBackoffDelay(config, attempt) {
     const jitter = Math.random() * MAX_JITTER_MS;
     return delay + jitter;
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Signal-aware sleep for backoff waits: resolves after `ms`, or rejects with
+ * the signal's abort reason the moment it fires. Without this, a caller abort
+ * or the request-timeout budget expiring during a backoff would leave the
+ * request pending for the full delay and then start another attempt — begin,
+ * auth refresh, fetch — against an already-aborted signal.
+ */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
 }
 // =============================================================================
 // Pagination Helper
@@ -755,7 +866,7 @@ function sleep(ms) {
  *
  * const allProjects = await fetchAllPages(
  *   response.response,
- *   (r) => r.json()
+ *   (r) => r.json() as Promise<any[]>
  * );
  * ```
  */
@@ -788,7 +899,7 @@ export async function fetchAllPages(initialResponse, parse, authHeader) {
  *
  * @example
  * ```ts
- * for await (const page of paginateAll(response.response, (r) => r.json())) {
+ * for await (const page of paginateAll(response.response, (r) => r.json() as Promise<any[]>)) {
  *   console.log(`Processing ${page.length} items`);
  * }
  * ```