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

package/dist/client.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NotionClient = exports.NOTION_VERSION = void 0;
 const errors_1 = require("./errors");
+const validation_1 = require("./validation");
 /**
  * The Notion API version this SDK uses.
  * All schemas, request bodies, helpers, and models depend on this version.
@@ -9,6 +10,8 @@ const errors_1 = require("./errors");
  * @category Client & Core
  */
 exports.NOTION_VERSION = '2026-03-11';
+/** Upper bound for a single retry wait, in milliseconds. */
+const MAX_RETRY_DELAY_MS = 60_000;
 /**
  * Base HTTP client for Notion API requests.
  */
@@ -36,13 +39,18 @@ class NotionClient {
                 return await this.makeRequest(options);
             }
             catch (error) {
-                // Retry rate-limited requests (if enabled) and service-overload (529)
-                // responses, which the API recommends always retrying.
+                // 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.isRateLimited() && this.retryOnRateLimit) || error.isServiceOverloaded()) &&
+                    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;
@@ -55,21 +63,46 @@ class NotionClient {
         // If we exhausted all retries, throw the last error
         throw lastError ?? new Error('Request failed after all retries');
     }
+    /**
+     * Send a `multipart/form-data` `POST` to a Notion file-upload URL. Reuses the
+     * configured `fetch` and the request timeout. Does not retry. Does not set
+     * `Content-Type`, so `fetch` adds the multipart boundary.
+     *
+     * @param uploadUrl - The absolute `upload_url` from `fileUploads.initiate()`.
+     * @param form - A `FormData` body with the file bytes under the `file` key.
+     * @throws {NotionValidationError} If `uploadUrl` is not a valid `https` URL.
+     * @throws {NotionAPIError} If the endpoint returns an error response.
+     * @throws {NotionRequestTimeoutError} If the request exceeds the timeout.
+     * @throws {NotionNetworkError} If a network problem blocks the request.
+     */
+    async sendFileUpload(uploadUrl, form) {
+        this.assertHttpsUrl(uploadUrl);
+        const { 'Content-Type': _contentType, ...headers } = this.requestHeaders;
+        try {
+            const response = await this.fetchWithTimeout(uploadUrl, {
+                method: 'POST',
+                headers,
+                body: form,
+            });
+            if (!response.ok) {
+                await this.handleErrorResponse(response);
+            }
+        }
+        catch (error) {
+            this.mapTransportError(error);
+        }
+    }
     /**
      * Send one HTTP request to the Notion API.
      */
     async makeRequest(options) {
         const url = this.buildUrl(options.path, options.query);
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
         try {
-            const response = await this.fetchImpl(url, {
+            const response = await this.fetchWithTimeout(url, {
                 method: options.method,
                 headers: this.requestHeaders,
                 body: options.body ? JSON.stringify(options.body) : undefined,
-                signal: controller.signal,
             });
-            clearTimeout(timeoutId);
             if (!response.ok) {
                 await this.handleErrorResponse(response);
             }
@@ -81,18 +114,56 @@ class NotionClient {
             return data;
         }
         catch (error) {
+            this.mapTransportError(error);
+        }
+    }
+    /**
+     * Call the configured `fetch` with an abort timeout of `timeoutMs`.
+     * Clear the timer as soon as the response headers arrive or the request fails.
+     */
+    async fetchWithTimeout(url, init) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            return await this.fetchImpl(url, { ...init, signal: controller.signal });
+        }
+        finally {
             clearTimeout(timeoutId);
-            if (error instanceof errors_1.NotionAPIError) {
-                throw error;
-            }
-            if (error instanceof Error) {
-                if (error.name === 'AbortError') {
-                    throw new errors_1.NotionRequestTimeoutError(`Request timed out after ${this.timeoutMs}ms`);
-                }
-                throw new errors_1.NotionNetworkError('Network request failed', error);
-            }
+        }
+    }
+    /**
+     * Map a transport-layer failure to the matching SDK error and throw it.
+     * Rethrow a `NotionAPIError` unchanged. Map an `AbortError` to
+     * `NotionRequestTimeoutError`. Map any other `Error` to `NotionNetworkError`.
+     */
+    mapTransportError(error) {
+        if (error instanceof errors_1.NotionAPIError) {
             throw error;
         }
+        if (error instanceof Error) {
+            if (error.name === 'AbortError') {
+                throw new errors_1.NotionRequestTimeoutError(`Request timed out after ${this.timeoutMs}ms`);
+            }
+            throw new errors_1.NotionNetworkError('Network request failed', error);
+        }
+        throw error;
+    }
+    /**
+     * Assert that `url` is a valid `https` URL. The SDK sends the API token in the
+     * `Authorization` header of a file upload. Reject a plaintext `http` URL so the
+     * token never travels unencrypted.
+     */
+    assertHttpsUrl(url) {
+        let protocol;
+        try {
+            protocol = new URL(url).protocol;
+        }
+        catch {
+            throw new validation_1.NotionValidationError(`Invalid file upload URL: ${url}`);
+        }
+        if (protocol !== 'https:') {
+            throw new validation_1.NotionValidationError(`File upload URL must use https, got "${protocol}"`);
+        }
     }
     /**
      * Calculate a fallback retry delay with exponential backoff.
@@ -101,7 +172,7 @@ class NotionClient {
      */
     getRetryAfter(attempt) {
         const backoffMs = Math.pow(2, attempt) * 1000;
-        return Math.min(backoffMs, 60000); // Cap at 60 seconds
+        return Math.min(backoffMs, MAX_RETRY_DELAY_MS);
     }
     /**
      * Pause for the given duration, in milliseconds.
@@ -130,38 +201,81 @@ class NotionClient {
         return url.toString();
     }
     /**
-     * Parse the `Retry-After` response header into milliseconds.
-     * 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.ceil(seconds) * 1000;
+        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/dist/helpers/filter.helpers.d.ts

@@ -4,7 +4,9 @@ type FilterCondition = Record<string, unknown>;
 declare class TextFilter {
     private readonly property;
     private readonly propertyType;
-    constructor(property: string, propertyType: string);
+    private readonly isFormula;
+    constructor(property: string, propertyType: string, isFormula?: boolean);
+    private build;
     equals(value: string): FilterCondition;
     doesNotEqual(value: string): FilterCondition;
     contains(value: string): FilterCondition;
@@ -17,7 +19,9 @@ declare class TextFilter {
 /** Operators for number properties. */
 declare class NumberFilter {
     private readonly property;
-    constructor(property: string);
+    private readonly isFormula;
+    constructor(property: string, isFormula?: boolean);
+    private build;
     equals(value: number): FilterCondition;
     doesNotEqual(value: number): FilterCondition;
     greaterThan(value: number): FilterCondition;
@@ -30,7 +34,9 @@ declare class NumberFilter {
 /** Operators for checkbox properties. */
 declare class CheckboxFilter {
     private readonly property;
-    constructor(property: string);
+    private readonly isFormula;
+    constructor(property: string, isFormula?: boolean);
+    private build;
     equals(value: boolean): FilterCondition;
     doesNotEqual(value: boolean): FilterCondition;
 }
@@ -65,7 +71,8 @@ declare class StatusFilter {
 declare class DateFilter {
     private readonly key;
     private readonly isTimestamp;
-    constructor(key: string, isTimestamp: boolean);
+    private readonly isFormula;
+    constructor(key: string, isTimestamp: boolean, isFormula?: boolean);
     private wrap;
     equals(value: string): FilterCondition;
     before(value: string): FilterCondition;