@notionhq/client 5.9.0 → 5.10.0

package/README.md

@@ -132,14 +132,55 @@ You may also set a custom `logger` to emit logs to a destination other than `std
 
 The `Client` supports the following options on initialization. These options are all keys in the single constructor parameter.
 
-| Option      | Default value              | Type         | Description                                                                                                                                                  |
-| ----------- | -------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `auth`      | `undefined`                | `string`     | Bearer token for authentication. If left undefined, the `auth` parameter should be set on each request.                                                      |
-| `logLevel`  | `LogLevel.WARN`            | `LogLevel`   | Verbosity of logs the instance will produce. By default, logs are written to `stdout`.                                                                       |
-| `timeoutMs` | `60_000`                   | `number`     | Number of milliseconds to wait before emitting a `RequestTimeoutError`                                                                                       |
-| `baseUrl`   | `"https://api.notion.com"` | `string`     | The root URL for sending API requests. This can be changed to test with a mock server.                                                                       |
-| `logger`    | Log to console             | `Logger`     | A custom logging function. This function is only called when the client emits a log that is equal or greater severity than `logLevel`.                       |
-| `agent`     | Default node agent         | `http.Agent` | Used to control creation of TCP sockets. A common use is to proxy requests with [`https-proxy-agent`](https://github.com/TooTallNate/node-https-proxy-agent) |
+| Option      | Default value              | Type           | Description                                                                                                                                                  |
+| ----------- | -------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `auth`      | `undefined`                | `string`       | Bearer token for authentication. If left undefined, the `auth` parameter should be set on each request.                                                      |
+| `logLevel`  | `LogLevel.WARN`            | `LogLevel`     | Verbosity of logs the instance will produce. By default, logs are written to `stdout`.                                                                       |
+| `timeoutMs` | `60_000`                   | `number`       | Number of milliseconds to wait before emitting a `RequestTimeoutError`                                                                                       |
+| `baseUrl`   | `"https://api.notion.com"` | `string`       | The root URL for sending API requests. This can be changed to test with a mock server.                                                                       |
+| `logger`    | Log to console             | `Logger`       | A custom logging function. This function is only called when the client emits a log that is equal or greater severity than `logLevel`.                       |
+| `agent`     | Default node agent         | `http.Agent`   | Used to control creation of TCP sockets. A common use is to proxy requests with [`https-proxy-agent`](https://github.com/TooTallNate/node-https-proxy-agent) |
+| `retry`     | `{ maxRetries: 2 }`        | `RetryOptions` | Configuration for automatic retries on rate limits (429) and server errors (500, 503). See [Automatic retries](#automatic-retries) below.                    |
+
+### Automatic retries
+
+The client automatically retries requests that fail due to rate limiting or transient server errors. By default, it will retry up to 2 times using exponential back-off with jitter.
+
+**Retryable errors:**
+
+- `rate_limited` (HTTP 429) - Too many requests; retried for all HTTP methods
+- `internal_server_error` (HTTP 500) - Server error; retried only for GET and DELETE
+- `service_unavailable` (HTTP 503) - Service temporarily unavailable; retried only for GET and DELETE
+
+Server errors (500, 503) are only retried for idempotent HTTP methods (GET, DELETE) to avoid duplicate side effects. Rate limits (429) are retried for all methods since the server explicitly asks clients to retry.
+
+**Retry behavior:**
+
+- Uses exponential back-off: delays increase with each retry attempt
+- Respects the `Retry-After` header when present (both delta-seconds and HTTP-date formats)
+- Adds random jitter to prevent thundering herd problems
+
+**Configuration:**
+
+```js
+const notion = new Client({
+  auth: process.env.NOTION_TOKEN,
+  retry: {
+    maxRetries: 5, // Maximum retry attempts (default: 2)
+    initialRetryDelayMs: 500, // Initial delay between retries (default: 1000ms)
+    maxRetryDelayMs: 60000, // Maximum delay between retries (default: 60000ms)
+  },
+})
+```
+
+To disable automatic retries:
+
+```js
+const notion = new Client({
+  auth: process.env.NOTION_TOKEN,
+  retry: false,
+})
+```
 
 ### TypeScript
 

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@notionhq/client",
-    "version": "5.9.0",
+    "version": "5.10.0",
     "description": "A simple and easy to use client for the Notion API",
     "engines": {
         "node": ">=18"
@@ -44,17 +44,17 @@
         "build/src/**"
     ],
     "devDependencies": {
-        "@types/jest": "28.1.4",
-        "@typescript-eslint/eslint-plugin": "5.39.0",
-        "@typescript-eslint/parser": "5.39.0",
-        "cspell": "5.4.1",
-        "eslint": "7.24.0",
+        "@types/jest": "29.5.14",
+        "@typescript-eslint/eslint-plugin": "7.18.0",
+        "@typescript-eslint/parser": "7.18.0",
+        "cspell": "8.17.1",
+        "eslint": "8.57.1",
         "husky": "^9.1.7",
-        "jest": "28.1.2",
+        "jest": "29.7.0",
         "lint-staged": "^16.2.6",
         "markdown-link-check": "3.13.7",
-        "prettier": "2.8.8",
-        "ts-jest": "28.0.5",
+        "prettier": "3.3.3",
+        "ts-jest": "29.2.5",
         "typescript": "5.9.2"
     }
 }

package/build/src/Client.d.ts

@@ -2,7 +2,25 @@ import type { Agent } from "node:http";
 import { type Logger, LogLevel } from "./logging";
 import { type GetBlockParameters, type GetBlockResponse, type UpdateBlockParameters, type UpdateBlockResponse, type DeleteBlockParameters, type DeleteBlockResponse, type AppendBlockChildrenParameters, type AppendBlockChildrenResponse, type ListBlockChildrenParameters, type ListBlockChildrenResponse, type QueryDataSourceParameters, type QueryDataSourceResponse, type CreateDataSourceParameters, type CreateDataSourceResponse, type UpdateDataSourceParameters, type UpdateDataSourceResponse, type GetDataSourceParameters, type GetDataSourceResponse, type CreatePageParameters, type CreatePageResponse, type GetPageParameters, type GetPageResponse, type UpdatePageParameters, type UpdatePageResponse, type MovePageParameters, type MovePageResponse, type GetUserParameters, type GetUserResponse, type ListUsersParameters, type ListUsersResponse, type SearchParameters, type SearchResponse, type GetSelfParameters, type GetSelfResponse, type GetPagePropertyParameters, type GetPagePropertyResponse, type CreateCommentParameters, type CreateCommentResponse, type ListCommentsParameters, type ListCommentsResponse, type GetCommentParameters, type GetCommentResponse, type OauthTokenResponse, type OauthTokenParameters, type OauthIntrospectResponse, type OauthIntrospectParameters, type OauthRevokeResponse, type OauthRevokeParameters, type CreateFileUploadParameters, type CreateFileUploadResponse, type GetFileUploadResponse, type GetFileUploadParameters, type SendFileUploadParameters, type SendFileUploadResponse, type CompleteFileUploadParameters, type CompleteFileUploadResponse, type ListFileUploadsParameters, type ListFileUploadsResponse, GetDatabaseParameters, GetDatabaseResponse, CreateDatabaseResponse, CreateDatabaseParameters, UpdateDatabaseParameters, UpdateDatabaseResponse, ListDataSourceTemplatesResponse, ListDataSourceTemplatesParameters } from "./api-endpoints";
 import type { SupportedFetch } from "./fetch-types";
-export interface ClientOptions {
+export type RetryOptions = {
+    /**
+     * Maximum number of retry attempts. Set to 0 to disable retries.
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay between retries in milliseconds.
+     * Used as base for exponential back-off when retry-after header is absent.
+     * @default 1000
+     */
+    initialRetryDelayMs?: number;
+    /**
+     * Maximum delay between retries in milliseconds.
+     * @default 60000
+     */
+    maxRetryDelayMs?: number;
+};
+export type ClientOptions = {
     auth?: string;
     timeoutMs?: number;
     baseUrl?: string;
@@ -12,12 +30,17 @@ export interface ClientOptions {
     fetch?: SupportedFetch;
     /** Silently ignored in the browser */
     agent?: Agent;
-}
+    /**
+     * Configuration for automatic retries on rate limit (429) and server errors.
+     * Set to false to disable retries entirely.
+     */
+    retry?: RetryOptions | false;
+};
 type FileParam = {
     filename?: string;
     data: string | Blob;
 };
-export interface RequestParameters {
+export type RequestParameters = {
     path: string;
     method: Method;
     query?: QueryParams;
@@ -33,7 +56,7 @@ export interface RequestParameters {
         client_id: string;
         client_secret: string;
     };
-}
+};
 export default class Client {
     #private;
     static readonly defaultNotionVersion = "2025-09-03";
@@ -42,6 +65,63 @@ export default class Client {
      * Sends a request.
      */
     request<ResponseBody extends object>(args: RequestParameters): Promise<ResponseBody>;
+    /**
+     * Builds the full URL with query parameters.
+     */
+    private buildRequestUrl;
+    /**
+     * Serializes the request body to JSON string if non-empty.
+     */
+    private serializeBody;
+    /**
+     * Builds the request headers including auth and content-type.
+     */
+    private buildRequestHeaders;
+    /**
+     * Builds the authorization header based on auth type.
+     */
+    private buildAuthHeader;
+    /**
+     * Builds FormData from form parameters if provided.
+     * Also removes content-type header to let fetch set the boundary.
+     */
+    private buildFormData;
+    /**
+     * Executes the request with retry logic.
+     */
+    private executeWithRetry;
+    /**
+     * Executes a single HTTP request (no retry).
+     */
+    private executeSingleRequest;
+    /**
+     * Logs a request error with appropriate detail level.
+     */
+    private logRequestError;
+    /**
+     * Extracts request_id from an object if present.
+     */
+    private extractRequestId;
+    /**
+     * Determines if an error can be retried based on its error code and method.
+     * Rate limits (429) are always retryable since the server explicitly asks us
+     * to retry. Server errors (500, 503) are only retried for idempotent methods
+     * (GET, DELETE) to avoid duplicate side effects.
+     */
+    private canRetry;
+    /**
+     * Calculates the delay before the next retry attempt.
+     * Uses retry-after header if present, otherwise exponential back-off with
+     * jitter.
+     */
+    private calculateRetryDelay;
+    /**
+     * Parses the retry-after header value.
+     * Supports both delta-seconds (e.g., "120") and HTTP-date formats.
+     * Returns the delay in milliseconds, or undefined if not present or invalid.
+     */
+    private parseRetryAfterHeader;
+    private sleep;
     readonly blocks: {
         /**
          * Retrieve block

package/build/src/Client.d.ts.map

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

package/build/src/Client.js

@@ -10,7 +10,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _Client_auth, _Client_logLevel, _Client_logger, _Client_prefixUrl, _Client_timeoutMs, _Client_notionVersion, _Client_fetch, _Client_agent, _Client_userAgent;
+var _Client_auth, _Client_logLevel, _Client_logger, _Client_prefixUrl, _Client_timeoutMs, _Client_notionVersion, _Client_fetch, _Client_agent, _Client_userAgent, _Client_maxRetries, _Client_initialRetryDelayMs, _Client_maxRetryDelayMs;
 Object.defineProperty(exports, "__esModule", { value: true });
 const logging_1 = require("./logging");
 const errors_1 = require("./errors");
@@ -19,7 +19,7 @@ const api_endpoints_1 = require("./api-endpoints");
 const package_json_1 = require("../package.json");
 class Client {
     constructor(options) {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
         _Client_auth.set(this, void 0);
         _Client_logLevel.set(this, void 0);
         _Client_logger.set(this, void 0);
@@ -29,6 +29,9 @@ class Client {
         _Client_fetch.set(this, void 0);
         _Client_agent.set(this, void 0);
         _Client_userAgent.set(this, void 0);
+        _Client_maxRetries.set(this, void 0);
+        _Client_initialRetryDelayMs.set(this, void 0);
+        _Client_maxRetryDelayMs.set(this, void 0);
         /*
          * Notion API endpoints
          */
@@ -474,6 +477,16 @@ class Client {
         __classPrivateFieldSet(this, _Client_fetch, (_f = options === null || options === void 0 ? void 0 : options.fetch) !== null && _f !== void 0 ? _f : fetch, "f");
         __classPrivateFieldSet(this, _Client_agent, options === null || options === void 0 ? void 0 : options.agent, "f");
         __classPrivateFieldSet(this, _Client_userAgent, `notionhq-client/${package_json_1.version}`, "f");
+        if ((options === null || options === void 0 ? void 0 : options.retry) === false) {
+            __classPrivateFieldSet(this, _Client_maxRetries, 0, "f");
+            __classPrivateFieldSet(this, _Client_initialRetryDelayMs, 0, "f");
+            __classPrivateFieldSet(this, _Client_maxRetryDelayMs, 0, "f");
+        }
+        else {
+            __classPrivateFieldSet(this, _Client_maxRetries, (_h = (_g = options === null || options === void 0 ? void 0 : options.retry) === null || _g === void 0 ? void 0 : _g.maxRetries) !== null && _h !== void 0 ? _h : 2, "f");
+            __classPrivateFieldSet(this, _Client_initialRetryDelayMs, (_k = (_j = options === null || options === void 0 ? void 0 : options.retry) === null || _j === void 0 ? void 0 : _j.initialRetryDelayMs) !== null && _k !== void 0 ? _k : 1000, "f");
+            __classPrivateFieldSet(this, _Client_maxRetryDelayMs, (_m = (_l = options === null || options === void 0 ? void 0 : options.retry) === null || _l === void 0 ? void 0 : _l.maxRetryDelayMs) !== null && _m !== void 0 ? _m : 60000, "f");
+        }
     }
     /**
      * Sends a request.
@@ -482,10 +495,22 @@ class Client {
         const { path, method, query, body, formDataParams, auth } = args;
         (0, errors_1.validateRequestPath)(path);
         this.log(logging_1.LogLevel.INFO, "request start", { method, path });
-        // If the body is empty, don't send the body in the HTTP request
-        const bodyAsJsonString = !body || Object.entries(body).length === 0
-            ? undefined
-            : JSON.stringify(body);
+        const url = this.buildRequestUrl(path, query);
+        const bodyAsJsonString = this.serializeBody(body);
+        const headers = this.buildRequestHeaders(args.headers, auth, bodyAsJsonString);
+        const formData = this.buildFormData(formDataParams, headers);
+        return this.executeWithRetry({
+            url,
+            method,
+            path,
+            headers,
+            body: bodyAsJsonString !== null && bodyAsJsonString !== void 0 ? bodyAsJsonString : formData,
+        });
+    }
+    /**
+     * Builds the full URL with query parameters.
+     */
+    buildRequestUrl(path, query) {
         const url = new URL(`${__classPrivateFieldGet(this, _Client_prefixUrl, "f")}${path}`);
         if (query) {
             for (const [key, value] of Object.entries(query)) {
@@ -501,25 +526,24 @@ class Client {
                 }
             }
         }
-        // Allow both client ID / client secret based auth as well as token based auth.
-        let authorizationHeader;
-        if (typeof auth === "object") {
-            // Client ID and secret based auth is **ONLY** supported when using the
-            // `/oauth/token` endpoint. If this is the case, handle formatting the
-            // authorization header as required by `Basic` auth.
-            const unencodedCredential = `${auth.client_id}:${auth.client_secret}`;
-            const encodedCredential = Buffer.from(unencodedCredential).toString("base64");
-            authorizationHeader = { authorization: `Basic ${encodedCredential}` };
-        }
-        else {
-            // Otherwise format authorization header as `Bearer` token auth.
-            authorizationHeader = this.authAsHeaders(auth);
+        return url;
+    }
+    /**
+     * Serializes the request body to JSON string if non-empty.
+     */
+    serializeBody(body) {
+        if (!body || Object.entries(body).length === 0) {
+            return undefined;
         }
+        return JSON.stringify(body);
+    }
+    /**
+     * Builds the request headers including auth and content-type.
+     */
+    buildRequestHeaders(customHeaders, auth, bodyAsJsonString) {
+        const authorizationHeader = this.buildAuthHeader(auth);
         const headers = {
-            // Request-level custom additional headers can be provided, but
-            // don't allow them to override all other headers, e.g. the
-            // standard user agent.
-            ...args.headers,
+            ...customHeaders,
             ...authorizationHeader,
             "Notion-Version": __classPrivateFieldGet(this, _Client_notionVersion, "f"),
             "user-agent": __classPrivateFieldGet(this, _Client_userAgent, "f"),
@@ -527,62 +551,208 @@ class Client {
         if (bodyAsJsonString !== undefined) {
             headers["content-type"] = "application/json";
         }
-        let formData;
-        if (formDataParams) {
-            delete headers["content-type"];
-            formData = new FormData();
-            for (const [key, value] of Object.entries(formDataParams)) {
-                if (typeof value === "string") {
-                    formData.append(key, value);
-                }
-                else if (typeof value === "object") {
-                    formData.append(key, typeof value.data === "object"
-                        ? value.data
-                        : new Blob([value.data]), value.filename);
-                }
-            }
+        return headers;
+    }
+    /**
+     * Builds the authorization header based on auth type.
+     */
+    buildAuthHeader(auth) {
+        if (typeof auth === "object") {
+            const unencodedCredential = `${auth.client_id}:${auth.client_secret}`;
+            const encodedCredential = Buffer.from(unencodedCredential).toString("base64");
+            return { authorization: `Basic ${encodedCredential}` };
+        }
+        return this.authAsHeaders(auth);
+    }
+    /**
+     * Builds FormData from form parameters if provided.
+     * Also removes content-type header to let fetch set the boundary.
+     */
+    buildFormData(formDataParams, headers) {
+        if (!formDataParams) {
+            return undefined;
         }
-        try {
-            const response = await errors_1.RequestTimeoutError.rejectAfterTimeout(__classPrivateFieldGet(this, _Client_fetch, "f").call(this, url.toString(), {
-                method: method.toUpperCase(),
-                headers,
-                body: bodyAsJsonString !== null && bodyAsJsonString !== void 0 ? bodyAsJsonString : formData,
-                agent: __classPrivateFieldGet(this, _Client_agent, "f"),
-            }), __classPrivateFieldGet(this, _Client_timeoutMs, "f"));
-            const responseText = await response.text();
-            if (!response.ok) {
-                throw (0, errors_1.buildRequestError)(response, responseText);
+        delete headers["content-type"];
+        const formData = new FormData();
+        for (const [key, value] of Object.entries(formDataParams)) {
+            if (typeof value === "string") {
+                formData.append(key, value);
+            }
+            else if (typeof value === "object") {
+                formData.append(key, typeof value.data === "object" ? value.data : new Blob([value.data]), value.filename);
             }
-            const responseJson = JSON.parse(responseText);
-            this.log(logging_1.LogLevel.INFO, "request success", {
-                method,
-                path,
-                ...("request_id" in responseJson && responseJson.request_id
-                    ? { requestId: responseJson.request_id }
-                    : {}),
-            });
-            return responseJson;
         }
-        catch (error) {
-            if (!(0, errors_1.isNotionClientError)(error)) {
+        return formData;
+    }
+    /**
+     * Executes the request with retry logic.
+     */
+    async executeWithRetry(args) {
+        const { url, method, path, headers, body } = args;
+        let attempt = 0;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            try {
+                return await this.executeSingleRequest({
+                    url,
+                    method,
+                    path,
+                    headers,
+                    body,
+                });
+            }
+            catch (error) {
+                if (!(0, errors_1.isNotionClientError)(error)) {
+                    throw error;
+                }
+                this.logRequestError(error, attempt);
+                if (attempt < __classPrivateFieldGet(this, _Client_maxRetries, "f") && this.canRetry(error, method)) {
+                    const delayMs = this.calculateRetryDelay(error, attempt);
+                    this.log(logging_1.LogLevel.INFO, "retrying request", {
+                        method,
+                        path,
+                        attempt: attempt + 1,
+                        delayMs,
+                    });
+                    await this.sleep(delayMs);
+                    attempt++;
+                    continue;
+                }
                 throw error;
             }
-            // Log the error if it's one of our known error types
-            this.log(logging_1.LogLevel.WARN, "request fail", {
-                code: error.code,
-                message: error.message,
-                ...("request_id" in error && error.request_id
-                    ? { requestId: error.request_id }
-                    : {}),
+        }
+    }
+    /**
+     * Executes a single HTTP request (no retry).
+     */
+    async executeSingleRequest(args) {
+        const { url, method, path, headers, body } = args;
+        const response = await errors_1.RequestTimeoutError.rejectAfterTimeout(__classPrivateFieldGet(this, _Client_fetch, "f").call(this, url.toString(), {
+            method: method.toUpperCase(),
+            headers,
+            body,
+            agent: __classPrivateFieldGet(this, _Client_agent, "f"),
+        }), __classPrivateFieldGet(this, _Client_timeoutMs, "f"));
+        const responseText = await response.text();
+        if (!response.ok) {
+            throw (0, errors_1.buildRequestError)(response, responseText);
+        }
+        const responseJson = JSON.parse(responseText);
+        this.log(logging_1.LogLevel.INFO, "request success", {
+            method,
+            path,
+            ...this.extractRequestId(responseJson),
+        });
+        return responseJson;
+    }
+    /**
+     * Logs a request error with appropriate detail level.
+     */
+    logRequestError(error, attempt) {
+        this.log(logging_1.LogLevel.WARN, "request fail", {
+            code: error.code,
+            message: error.message,
+            attempt,
+            ...this.extractRequestId(error),
+        });
+        if ((0, errors_1.isHTTPResponseError)(error)) {
+            this.log(logging_1.LogLevel.DEBUG, "failed response body", {
+                body: error.body,
             });
-            if ((0, errors_1.isHTTPResponseError)(error)) {
-                // The response body may contain sensitive information so it is logged separately at the DEBUG level
-                this.log(logging_1.LogLevel.DEBUG, "failed response body", {
-                    body: error.body,
-                });
+        }
+    }
+    /**
+     * Extracts request_id from an object if present.
+     */
+    extractRequestId(obj) {
+        if (obj &&
+            typeof obj === "object" &&
+            "request_id" in obj &&
+            typeof obj.request_id === "string") {
+            return { requestId: obj.request_id };
+        }
+        return {};
+    }
+    /**
+     * Determines if an error can be retried based on its error code and method.
+     * Rate limits (429) are always retryable since the server explicitly asks us
+     * to retry. Server errors (500, 503) are only retried for idempotent methods
+     * (GET, DELETE) to avoid duplicate side effects.
+     */
+    canRetry(error, method) {
+        if (!errors_1.APIResponseError.isAPIResponseError(error)) {
+            return false;
+        }
+        // Rate limits are always retryable - server says "try again later"
+        if (error.code === errors_1.APIErrorCode.RateLimited) {
+            return true;
+        }
+        // Server errors only retry for idempotent methods
+        const isIdempotent = method === "get" || method === "delete";
+        if (isIdempotent) {
+            return (error.code === errors_1.APIErrorCode.InternalServerError ||
+                error.code === errors_1.APIErrorCode.ServiceUnavailable);
+        }
+        return false;
+    }
+    /**
+     * Calculates the delay before the next retry attempt.
+     * Uses retry-after header if present, otherwise exponential back-off with
+     * jitter.
+     */
+    calculateRetryDelay(error, attempt) {
+        // Try to get retry-after from the error headers
+        if (errors_1.APIResponseError.isAPIResponseError(error)) {
+            const retryAfterMs = this.parseRetryAfterHeader(error.headers);
+            if (retryAfterMs !== undefined) {
+                return Math.min(retryAfterMs, __classPrivateFieldGet(this, _Client_maxRetryDelayMs, "f"));
             }
-            throw error;
         }
+        // Exponential back-off with full jitter
+        const baseDelay = __classPrivateFieldGet(this, _Client_initialRetryDelayMs, "f") * Math.pow(2, attempt);
+        const jitter = Math.random();
+        return Math.min(baseDelay * jitter + baseDelay / 2, __classPrivateFieldGet(this, _Client_maxRetryDelayMs, "f"));
+    }
+    /**
+     * Parses the retry-after header value.
+     * Supports both delta-seconds (e.g., "120") and HTTP-date formats.
+     * Returns the delay in milliseconds, or undefined if not present or invalid.
+     */
+    parseRetryAfterHeader(headers) {
+        var _a, _b;
+        if (!headers) {
+            return undefined;
+        }
+        let retryAfterValue = null;
+        // Handle Headers object (standard fetch API)
+        if (typeof headers === "object" && "get" in headers) {
+            const headersObj = headers;
+            retryAfterValue = headersObj.get("retry-after");
+        }
+        // Handle plain object
+        else if (typeof headers === "object") {
+            const headersRecord = headers;
+            retryAfterValue =
+                (_b = (_a = headersRecord["retry-after"]) !== null && _a !== void 0 ? _a : headersRecord["Retry-After"]) !== null && _b !== void 0 ? _b : null;
+        }
+        if (!retryAfterValue) {
+            return undefined;
+        }
+        // Try parsing as delta-seconds (integer)
+        const seconds = parseInt(retryAfterValue, 10);
+        if (!isNaN(seconds) && seconds >= 0) {
+            return seconds * 1000;
+        }
+        // Try parsing as HTTP-date
+        const date = Date.parse(retryAfterValue);
+        if (!isNaN(date)) {
+            const delayMs = date - Date.now();
+            return delayMs > 0 ? delayMs : 0;
+        }
+        return undefined;
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
     }
     /**
      * Emits a log message to the console.
@@ -613,7 +783,7 @@ class Client {
         return headers;
     }
 }
-_Client_auth = new WeakMap(), _Client_logLevel = new WeakMap(), _Client_logger = new WeakMap(), _Client_prefixUrl = new WeakMap(), _Client_timeoutMs = new WeakMap(), _Client_notionVersion = new WeakMap(), _Client_fetch = new WeakMap(), _Client_agent = new WeakMap(), _Client_userAgent = new WeakMap();
+_Client_auth = new WeakMap(), _Client_logLevel = new WeakMap(), _Client_logger = new WeakMap(), _Client_prefixUrl = new WeakMap(), _Client_timeoutMs = new WeakMap(), _Client_notionVersion = new WeakMap(), _Client_fetch = new WeakMap(), _Client_agent = new WeakMap(), _Client_userAgent = new WeakMap(), _Client_maxRetries = new WeakMap(), _Client_initialRetryDelayMs = new WeakMap(), _Client_maxRetryDelayMs = new WeakMap();
 Client.defaultNotionVersion = "2025-09-03";
 exports.default = Client;
 //# sourceMappingURL=Client.js.map