@visus-io/notion-sdk-ts 3.2.1 → 3.3.0

package/dist/api/pages.api.d.ts

@@ -1130,6 +1130,10 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
      * In that case, the API returns an `async_task` handle instead of the completed
      * content. Poll the task with `notion.asyncTasks.poll(task.id)`.
      *
+     * A `504 gateway_timeout` response does not guarantee the write failed. The SDK
+     * does not retry this call automatically on a `504`. Verify the page content before
+     * you retry.
+     *
      * @param pageId - The ID of the page to update
      * @param options - The markdown update to apply
      * @returns The updated markdown content, or an async task handle if processed asynchronously

package/dist/api/pages.api.js

@@ -87,6 +87,10 @@ class PagesAPI extends base_api_1.BaseAPI {
      * In that case, the API returns an `async_task` handle instead of the completed
      * content. Poll the task with `notion.asyncTasks.poll(task.id)`.
      *
+     * A `504 gateway_timeout` response does not guarantee the write failed. The SDK
+     * does not retry this call automatically on a `504`. Verify the page content before
+     * you retry.
+     *
      * @param pageId - The ID of the page to update
      * @param options - The markdown update to apply
      * @returns The updated markdown content, or an async task handle if processed asynchronously
@@ -98,6 +102,7 @@ class PagesAPI extends base_api_1.BaseAPI {
             method: 'PATCH',
             path: `/pages/${pageId}/markdown`,
             body: options,
+            retryOnGatewayTimeout: false,
         });
         return schemas_1.markdownContentResponseSchema.parse(response);
     }

package/dist/client.d.ts

@@ -32,6 +32,12 @@ export interface RequestOptions {
     path: string;
     query?: Record<string, string | number | boolean | string[] | undefined>;
     body?: unknown;
+    /**
+     * Whether to retry a `504 gateway_timeout` response automatically (default: `true`).
+     * A `504` does not guarantee the original request failed. Set this to `false` for
+     * a write that is not safe to repeat blindly, such as a non-idempotent content update.
+     */
+    retryOnGatewayTimeout?: boolean;
 }
 /**
  * Base HTTP client for Notion API requests.
@@ -97,12 +103,37 @@ export declare class NotionClient {
      * Build the full URL with query parameters.
      */
     private buildUrl;
+    /**
+     * Convert a whole-seconds string into milliseconds, clamped to
+     * {@link MAX_RETRY_DELAY_MS}. `value` comes from an unvalidated header or
+     * JSON body, so this accepts `unknown`. Return `undefined` if it is not a
+     * non-blank string, or not a valid non-negative number.
+     */
+    private secondsToClampedMs;
     /**
      * Parse the `Retry-After` response header into milliseconds, clamped to
-     * {@link MAX_RETRY_DELAY_MS}. Return `undefined` if the header is missing or
-     * not a valid non-negative number.
+     * {@link MAX_RETRY_DELAY_MS}. Return `undefined` if the header is missing,
+     * blank, or not a valid non-negative number.
      */
     private parseRetryAfterHeader;
+    /**
+     * Parse `additional_data.retry_after` from the error body into milliseconds,
+     * clamped to {@link MAX_RETRY_DELAY_MS}. The Notion API repeats the
+     * `Retry-After` value here for clients that cannot read response headers.
+     * Return `undefined` if the field is missing, blank, or not a valid
+     * non-negative number.
+     */
+    private parseRetryAfterBody;
+    /**
+     * Check if `value` is a plain, non-null, non-array object. Use this to
+     * guard a cast from unvalidated JSON before treating it as a record.
+     */
+    private isRecord;
+    /**
+     * Build a generic error body for a response the SDK cannot parse into a
+     * {@link NotionErrorResponse}.
+     */
+    private genericErrorBody;
     /**
      * Handle an error response from the API.
      */

package/dist/client.js

@@ -39,13 +39,18 @@ class NotionClient {
                 return await this.makeRequest(options);
             }
             catch (error) {
-                // Retry per isRetryable(); retryOnRateLimit:false suppresses only rate_limited.
+                // Retry per isRetryable(); retryOnRateLimit:false suppresses only HTTP 429
+                // (isRateLimited() is status-based, so this holds regardless of a
+                // malformed body's `code`). options.retryOnGatewayTimeout:false suppresses
+                // only HTTP 504; `status` is always authoritative there too (see
+                // handleErrorResponse()).
                 if (error instanceof errors_1.NotionAPIError &&
                     error.isRetryable() &&
                     !(error.isRateLimited() && !this.retryOnRateLimit) &&
+                    !(error.status === 504 && options.retryOnGatewayTimeout === false) &&
                     attempt < this.maxRetries) {
-                    // Prefer the server-supplied Retry-After value; fall back to
-                    // exponential backoff when the header is absent.
+                    // Prefer the server-supplied Retry-After value (header or body fallback);
+                    // fall back to exponential backoff when neither is present or valid.
                     const retryAfter = error.retryAfterMs ?? this.getRetryAfter(attempt);
                     await this.sleep(retryAfter);
                     lastError = error;
@@ -196,39 +201,81 @@ class NotionClient {
         return url.toString();
     }
     /**
-     * Parse the `Retry-After` response header into milliseconds, clamped to
-     * {@link MAX_RETRY_DELAY_MS}. Return `undefined` if the header is missing or
-     * not a valid non-negative number.
+     * Convert a whole-seconds string into milliseconds, clamped to
+     * {@link MAX_RETRY_DELAY_MS}. `value` comes from an unvalidated header or
+     * JSON body, so this accepts `unknown`. Return `undefined` if it is not a
+     * non-blank string, or not a valid non-negative number.
      */
-    parseRetryAfterHeader(response) {
-        const header = response.headers.get('Retry-After');
-        if (header === null) {
+    secondsToClampedMs(value) {
+        if (typeof value !== 'string' || value.trim() === '') {
             return undefined;
         }
-        const seconds = Number(header);
+        const seconds = Number(value);
         if (!Number.isFinite(seconds) || seconds < 0) {
             return undefined;
         }
         return Math.min(Math.ceil(seconds) * 1000, MAX_RETRY_DELAY_MS);
     }
+    /**
+     * Parse the `Retry-After` response header into milliseconds, clamped to
+     * {@link MAX_RETRY_DELAY_MS}. Return `undefined` if the header is missing,
+     * blank, or not a valid non-negative number.
+     */
+    parseRetryAfterHeader(response) {
+        return this.secondsToClampedMs(response.headers.get('Retry-After'));
+    }
+    /**
+     * Parse `additional_data.retry_after` from the error body into milliseconds,
+     * clamped to {@link MAX_RETRY_DELAY_MS}. The Notion API repeats the
+     * `Retry-After` value here for clients that cannot read response headers.
+     * Return `undefined` if the field is missing, blank, or not a valid
+     * non-negative number.
+     */
+    parseRetryAfterBody(errorBody) {
+        return this.secondsToClampedMs(errorBody.additional_data?.retry_after);
+    }
+    /**
+     * Check if `value` is a plain, non-null, non-array object. Use this to
+     * guard a cast from unvalidated JSON before treating it as a record.
+     */
+    isRecord(value) {
+        return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
+    /**
+     * Build a generic error body for a response the SDK cannot parse into a
+     * {@link NotionErrorResponse}.
+     */
+    genericErrorBody(response) {
+        return {
+            object: 'error',
+            status: response.status,
+            code: 'internal_server_error',
+            message: response.statusText || 'Unknown error occurred',
+        };
+    }
     /**
      * Handle an error response from the API.
      */
     async handleErrorResponse(response) {
-        const retryAfterMs = this.parseRetryAfterHeader(response);
         let errorBody;
         try {
-            errorBody = (await response.json());
+            const parsed = await response.json();
+            // A syntactically valid body can still be non-object JSON, such as `null`
+            // or a bare string. Fall back to a generic error body in that case too;
+            // otherwise assigning `status` below would throw.
+            errorBody = this.isRecord(parsed)
+                ? parsed
+                : this.genericErrorBody(response);
         }
         catch {
-            // If we can't parse the error body, create a generic error
-            errorBody = {
-                object: 'error',
-                status: response.status,
-                code: 'internal_server_error',
-                message: response.statusText || 'Unknown error occurred',
-            };
+            // If the SDK cannot parse the error body, create a generic error
+            errorBody = this.genericErrorBody(response);
         }
+        // The HTTP response status is authoritative. A proxy or a malformed body
+        // can report a `status` field that disagrees with it, or omit it.
+        errorBody.status = response.status;
+        // Prefer the header. Use the body only when the header is missing or invalid.
+        const retryAfterMs = this.parseRetryAfterHeader(response) ?? this.parseRetryAfterBody(errorBody);
         throw new errors_1.NotionAPIError(errorBody, retryAfterMs);
     }
 }

package/dist/errors.d.ts

@@ -3,7 +3,28 @@
  *
  * @category Errors
  */
-export type NotionErrorCode = 'invalid_json' | 'invalid_request_url' | 'invalid_request' | 'validation_error' | 'missing_version' | 'unauthorized' | 'restricted_resource' | 'object_not_found' | 'conflict_error' | 'rate_limited' | 'internal_server_error' | 'service_unavailable' | 'service_overload' | 'database_connection_unavailable' | 'gateway_timeout';
+export declare const NOTION_ERROR_CODES: readonly ["invalid_json", "invalid_request_url", "invalid_request", "validation_error", "missing_version", "unauthorized", "restricted_resource", "object_not_found", "conflict_error", "rate_limited", "internal_server_error", "service_unavailable", "service_overload", "database_connection_unavailable", "gateway_timeout"];
+/**
+ * Notion may add new error codes over time. Treat an unrecognized code the
+ * same as any other error response; read `status` to classify it.
+ *
+ * @category Errors
+ */
+export type NotionErrorCode = (typeof NOTION_ERROR_CODES)[number] | (string & Record<never, never>);
+/**
+ * Reasons the Notion API gives for a `rate_limited` response.
+ * Appears in `NotionErrorResponse.additional_data.rate_limit_reason`.
+ *
+ * @category Errors
+ */
+export declare const RATE_LIMIT_REASONS: readonly ["public_api_request_rate_limit", "public_api_space_request_rate_limit", "public_api_endpoint_rate_limit", "mcp_tool_rate_limit", "collection_router_upstream_429", "public_api_request_blocked"];
+/**
+ * Notion may add new reason strings over time. Treat an unrecognized value the
+ * same as any other `rate_limited` response.
+ *
+ * @category Errors
+ */
+export type RateLimitReason = (typeof RATE_LIMIT_REASONS)[number] | (string & Record<never, never>);
 /**
  * Notion API error response structure.
  *
@@ -15,7 +36,12 @@ export interface NotionErrorResponse {
     code: NotionErrorCode;
     message: string;
     /** Extra machine-readable context for some error codes, for example `restricted_resource`. */
-    additional_data?: Record<string, unknown>;
+    additional_data?: {
+        /** Present on `rate_limited` responses. Duplicates `Retry-After` as whole seconds. */
+        retry_after?: string;
+        /** Present on `rate_limited` responses. Identifies why the API rate-limited the request. */
+        rate_limit_reason?: RateLimitReason;
+    } & Record<string, unknown>;
 }
 /**
  * Thrown when the Notion API returns an error response.
@@ -27,9 +53,14 @@ export declare class NotionAPIError extends Error {
     readonly code: NotionErrorCode;
     readonly body: NotionErrorResponse;
     readonly retryAfterMs?: number;
+    readonly rateLimitReason?: RateLimitReason;
     constructor(response: NotionErrorResponse, retryAfterMs?: number);
     /**
-     * Check if the error is a rate limit error.
+     * Check if the error is a rate limit error (HTTP 429).
+     * Check `status`, not `code`. A malformed body could report the wrong
+     * `code` for a real 429, or report `rate_limited` for a real non-429
+     * status. `status` always matches the real HTTP response. See
+     * `NotionClient.handleErrorResponse()`.
      */
     isRateLimited(): boolean;
     /**
@@ -59,6 +90,8 @@ export declare class NotionAPIError extends Error {
     isServerError(): boolean;
     /**
      * Check if the error is retryable (rate limit or server error).
+     * A `429` is not retryable when `rateLimitReason` is `public_api_request_blocked`,
+     * since the request cannot succeed.
      */
     isRetryable(): boolean;
 }

package/dist/errors.js

@@ -1,6 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NotionNetworkError = exports.NotionRequestTimeoutError = exports.NotionAPIError = void 0;
+exports.NotionNetworkError = exports.NotionRequestTimeoutError = exports.NotionAPIError = exports.RATE_LIMIT_REASONS = exports.NOTION_ERROR_CODES = void 0;
+/**
+ * Notion API error codes based on official documentation.
+ *
+ * @category Errors
+ */
+exports.NOTION_ERROR_CODES = [
+    'invalid_json',
+    'invalid_request_url',
+    'invalid_request',
+    'validation_error',
+    'missing_version',
+    'unauthorized',
+    'restricted_resource',
+    'object_not_found',
+    'conflict_error',
+    'rate_limited',
+    'internal_server_error',
+    'service_unavailable',
+    'service_overload',
+    'database_connection_unavailable',
+    'gateway_timeout',
+];
+/**
+ * Reasons the Notion API gives for a `rate_limited` response.
+ * Appears in `NotionErrorResponse.additional_data.rate_limit_reason`.
+ *
+ * @category Errors
+ */
+exports.RATE_LIMIT_REASONS = [
+    'public_api_request_rate_limit',
+    'public_api_space_request_rate_limit',
+    'public_api_endpoint_rate_limit',
+    'mcp_tool_rate_limit',
+    'collection_router_upstream_429',
+    'public_api_request_blocked',
+];
 /**
  * Thrown when the Notion API returns an error response.
  *
@@ -11,19 +47,33 @@ class NotionAPIError extends Error {
         super(response.message);
         this.name = 'NotionAPIError';
         this.status = response.status;
-        this.code = response.code;
         this.body = response;
         this.retryAfterMs = retryAfterMs;
+        // response comes from an unvalidated JSON body cast to NotionErrorResponse, so
+        // `code` could be any JSON type at runtime despite its string type. Check the
+        // runtime type before exposing it. Fall back to a generic code; `status` stays
+        // the authoritative field for classifying the error.
+        const rawCode = response.code;
+        this.code = typeof rawCode === 'string' ? rawCode : 'internal_server_error';
+        // additional_data comes from the same unvalidated body, so rate_limit_reason
+        // could likewise be any JSON type at runtime despite its string type. Check
+        // the runtime type before exposing it on this public property.
+        const rawRateLimitReason = response.additional_data?.rate_limit_reason;
+        this.rateLimitReason = typeof rawRateLimitReason === 'string' ? rawRateLimitReason : undefined;
         // Maintain proper stack trace for V8 engines
         if ('captureStackTrace' in Error) {
             Error.captureStackTrace(this, NotionAPIError);
         }
     }
     /**
-     * Check if the error is a rate limit error.
+     * Check if the error is a rate limit error (HTTP 429).
+     * Check `status`, not `code`. A malformed body could report the wrong
+     * `code` for a real 429, or report `rate_limited` for a real non-429
+     * status. `status` always matches the real HTTP response. See
+     * `NotionClient.handleErrorResponse()`.
      */
     isRateLimited() {
-        return this.code === 'rate_limited';
+        return this.status === 429;
     }
     /**
      * Check if the error is a service overload error (HTTP 529).
@@ -64,8 +114,13 @@ class NotionAPIError extends Error {
     }
     /**
      * Check if the error is retryable (rate limit or server error).
+     * A `429` is not retryable when `rateLimitReason` is `public_api_request_blocked`,
+     * since the request cannot succeed.
      */
     isRetryable() {
+        if (this.isRateLimited() && this.rateLimitReason === 'public_api_request_blocked') {
+            return false;
+        }
         return this.isRateLimited() || this.isServerError();
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visus-io/notion-sdk-ts",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "private": false,
   "description": "TypeScript SDK for the Notion API",
   "keywords": [
@@ -72,7 +72,7 @@
     "@types/node": "^25.9.5",
     "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^10.9.0",
-    "eslint-plugin-zod": "4.12.0",
+    "eslint-plugin-zod": "4.14.2",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
     "msw": "2.15.0",