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

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,10 +39,10 @@ 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 rate_limited.
                 if (error instanceof errors_1.NotionAPIError &&
-                    ((error.isRateLimited() && this.retryOnRateLimit) || error.isServiceOverloaded()) &&
+                    error.isRetryable() &&
+                    !(error.isRateLimited() && !this.retryOnRateLimit) &&
                     attempt < this.maxRetries) {
                     // Prefer the server-supplied Retry-After value; fall back to
                     // exponential backoff when the header is absent.
@@ -55,21 +58,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 +109,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 +167,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,8 +196,9 @@ 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.
+     * 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.
      */
     parseRetryAfterHeader(response) {
         const header = response.headers.get('Retry-After');
@@ -142,7 +209,7 @@ class NotionClient {
         if (!Number.isFinite(seconds) || seconds < 0) {
             return undefined;
         }
-        return Math.ceil(seconds) * 1000;
+        return Math.min(Math.ceil(seconds) * 1000, MAX_RETRY_DELAY_MS);
     }
     /**
      * Handle an error response from the API.

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;

package/dist/helpers/filter.helpers.js

@@ -1,83 +1,117 @@
 "use strict";
-// ---------------------------------------------------------------------------
-// Filter value types
-// ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.filter = void 0;
+const validation_1 = require("../validation");
+/**
+ * Assert that a select-like filter value is a single string. Notion rejects an
+ * array for the `equals`, `does_not_equal`, `contains`, and `does_not_contain`
+ * operators on `select`, `status`, and `multi_select` properties.
+ *
+ * The parameter type still accepts `string[]` for backward compatibility. An
+ * array now fails fast with a clear error instead of a generic API 400.
+ *
+ * @throws {NotionValidationError} If `value` is an array.
+ */
+function assertScalarFilterValue(value, label) {
+    if (Array.isArray(value)) {
+        throw new validation_1.NotionValidationError(`${label} accepts a single string, not an array. Compose an OR filter with filter.or(...) to match multiple values.`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Property filter builders
 // ---------------------------------------------------------------------------
 /** Operators common to text-like properties (title, rich_text, url, email, phone_number). */
 class TextFilter {
-    constructor(property, propertyType) {
+    constructor(property, propertyType, isFormula = false) {
         this.property = property;
         this.propertyType = propertyType;
+        this.isFormula = isFormula;
+    }
+    build(condition) {
+        if (this.isFormula) {
+            return { property: this.property, formula: { string: condition } };
+        }
+        return { property: this.property, [this.propertyType]: condition };
     }
     equals(value) {
-        return { property: this.property, [this.propertyType]: { equals: value } };
+        return this.build({ equals: value });
     }
     doesNotEqual(value) {
-        return { property: this.property, [this.propertyType]: { does_not_equal: value } };
+        return this.build({ does_not_equal: value });
     }
     contains(value) {
-        return { property: this.property, [this.propertyType]: { contains: value } };
+        return this.build({ contains: value });
     }
     doesNotContain(value) {
-        return { property: this.property, [this.propertyType]: { does_not_contain: value } };
+        return this.build({ does_not_contain: value });
     }
     startsWith(value) {
-        return { property: this.property, [this.propertyType]: { starts_with: value } };
+        return this.build({ starts_with: value });
     }
     endsWith(value) {
-        return { property: this.property, [this.propertyType]: { ends_with: value } };
+        return this.build({ ends_with: value });
     }
     isEmpty() {
-        return { property: this.property, [this.propertyType]: { is_empty: true } };
+        return this.build({ is_empty: true });
     }
     isNotEmpty() {
-        return { property: this.property, [this.propertyType]: { is_not_empty: true } };
+        return this.build({ is_not_empty: true });
     }
 }
 /** Operators for number properties. */
 class NumberFilter {
-    constructor(property) {
+    constructor(property, isFormula = false) {
         this.property = property;
+        this.isFormula = isFormula;
+    }
+    build(condition) {
+        if (this.isFormula) {
+            return { property: this.property, formula: { number: condition } };
+        }
+        return { property: this.property, number: condition };
     }
     equals(value) {
-        return { property: this.property, number: { equals: value } };
+        return this.build({ equals: value });
     }
     doesNotEqual(value) {
-        return { property: this.property, number: { does_not_equal: value } };
+        return this.build({ does_not_equal: value });
     }
     greaterThan(value) {
-        return { property: this.property, number: { greater_than: value } };
+        return this.build({ greater_than: value });
     }
     greaterThanOrEqualTo(value) {
-        return { property: this.property, number: { greater_than_or_equal_to: value } };
+        return this.build({ greater_than_or_equal_to: value });
     }
     lessThan(value) {
-        return { property: this.property, number: { less_than: value } };
+        return this.build({ less_than: value });
     }
     lessThanOrEqualTo(value) {
-        return { property: this.property, number: { less_than_or_equal_to: value } };
+        return this.build({ less_than_or_equal_to: value });
     }
     isEmpty() {
-        return { property: this.property, number: { is_empty: true } };
+        return this.build({ is_empty: true });
     }
     isNotEmpty() {
-        return { property: this.property, number: { is_not_empty: true } };
+        return this.build({ is_not_empty: true });
     }
 }
 /** Operators for checkbox properties. */
 class CheckboxFilter {
-    constructor(property) {
+    constructor(property, isFormula = false) {
         this.property = property;
+        this.isFormula = isFormula;
+    }
+    build(condition) {
+        if (this.isFormula) {
+            return { property: this.property, formula: { checkbox: condition } };
+        }
+        return { property: this.property, checkbox: condition };
     }
     equals(value) {
-        return { property: this.property, checkbox: { equals: value } };
+        return this.build({ equals: value });
     }
     doesNotEqual(value) {
-        return { property: this.property, checkbox: { does_not_equal: value } };
+        return this.build({ does_not_equal: value });
     }
 }
 /** Operators for select properties. */
@@ -86,9 +120,11 @@ class SelectFilter {
         this.property = property;
     }
     equals(value) {
+        assertScalarFilterValue(value, 'select().equals');
         return { property: this.property, select: { equals: value } };
     }
     doesNotEqual(value) {
+        assertScalarFilterValue(value, 'select().doesNotEqual');
         return { property: this.property, select: { does_not_equal: value } };
     }
     isEmpty() {
@@ -104,9 +140,11 @@ class MultiSelectFilter {
         this.property = property;
     }
     contains(value) {
+        assertScalarFilterValue(value, 'multiSelect().contains');
         return { property: this.property, multi_select: { contains: value } };
     }
     doesNotContain(value) {
+        assertScalarFilterValue(value, 'multiSelect().doesNotContain');
         return { property: this.property, multi_select: { does_not_contain: value } };
     }
     isEmpty() {
@@ -122,9 +160,11 @@ class StatusFilter {
         this.property = property;
     }
     equals(value) {
+        assertScalarFilterValue(value, 'status().equals');
         return { property: this.property, status: { equals: value } };
     }
     doesNotEqual(value) {
+        assertScalarFilterValue(value, 'status().doesNotEqual');
         return { property: this.property, status: { does_not_equal: value } };
     }
     isEmpty() {
@@ -136,11 +176,15 @@ class StatusFilter {
 }
 /** Operators for date properties and timestamp filters. */
 class DateFilter {
-    constructor(key, isTimestamp) {
+    constructor(key, isTimestamp, isFormula = false) {
         this.key = key;
         this.isTimestamp = isTimestamp;
+        this.isFormula = isFormula;
     }
     wrap(condition) {
+        if (this.isFormula) {
+            return { property: this.key, formula: { date: condition } };
+        }
         if (this.isTimestamp) {
             return { timestamp: this.key, [this.key]: condition };
         }
@@ -240,17 +284,16 @@ class FormulaFilter {
         this.property = property;
     }
     text() {
-        return new TextFilter(this.property, 'formula');
+        return new TextFilter(this.property, 'formula', true);
     }
     number() {
-        // Return a NumberFilter-like but under "formula" key
-        return new NumberFilter(this.property);
+        return new NumberFilter(this.property, true);
     }
     checkbox() {
-        return new CheckboxFilter(this.property);
+        return new CheckboxFilter(this.property, true);
     }
     date() {
-        return new DateFilter(this.property, false);
+        return new DateFilter(this.property, false, true);
     }
 }
 // ---------------------------------------------------------------------------

package/dist/helpers/pagination.helpers.d.ts

@@ -43,8 +43,13 @@ export type PaginatedFetchFunction<T> = (cursor?: string) => Promise<PaginatedLi
 /**
  * Collects all results from a paginated endpoint by automatically following cursors.
  *
- * This function fetches pages until `has_more` is `false`. It collects all results
- * into one array. Use this function when you need all results at once.
+ * This function fetches pages until `has_more` is `false` or `next_cursor` is `null`.
+ * It collects all results into one array. Use this function when you need all results
+ * at once.
+ *
+ * This helper does not work around the 10,000-result cap on data source, view, and
+ * meeting-notes queries. When a query hits that cap, the result set is truncated and
+ * this helper writes a warning. Use {@link collectAllDataSourceRows} for those queries.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Array containing all results from all pages

package/dist/helpers/pagination.helpers.js

@@ -5,11 +5,32 @@ exports.paginateIterator = paginateIterator;
 exports.paginateWithMetadata = paginateWithMetadata;
 exports.iterateAllDataSourceRows = iterateAllDataSourceRows;
 exports.collectAllDataSourceRows = collectAllDataSourceRows;
+/**
+ * Return the cursor for the next page, or `undefined` when iteration must stop
+ * (`has_more` is `false`, or `next_cursor` is `null`). Warn when the result is a
+ * truncated query (`request_status.type === 'incomplete'`).
+ */
+function nextCursor(response) {
+    if (response.request_status?.type === 'incomplete') {
+        console.warn('Notion returned a truncated query result (the 10,000-result cap was reached). ' +
+            'This paginate helper stops here and the result set is incomplete. ' +
+            'Use collectAllDataSourceRows() or iterateAllDataSourceRows() to read every row.');
+    }
+    if (!response.has_more || response.next_cursor === null) {
+        return undefined;
+    }
+    return response.next_cursor ?? undefined;
+}
 /**
  * Collects all results from a paginated endpoint by automatically following cursors.
  *
- * This function fetches pages until `has_more` is `false`. It collects all results
- * into one array. Use this function when you need all results at once.
+ * This function fetches pages until `has_more` is `false` or `next_cursor` is `null`.
+ * It collects all results into one array. Use this function when you need all results
+ * at once.
+ *
+ * This helper does not work around the 10,000-result cap on data source, view, and
+ * meeting-notes queries. When a query hits that cap, the result set is truncated and
+ * this helper writes a warning. Use {@link collectAllDataSourceRows} for those queries.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Array containing all results from all pages
@@ -58,7 +79,7 @@ async function paginate(fetchPage) {
     do {
         const response = await fetchPage(cursor);
         all.push(...response.results);
-        cursor = response.next_cursor ?? undefined;
+        cursor = nextCursor(response);
     } while (cursor);
     return all;
 }
@@ -112,7 +133,7 @@ async function* paginateIterator(fetchPage) {
         for (const item of response.results) {
             yield item;
         }
-        cursor = response.next_cursor ?? undefined;
+        cursor = nextCursor(response);
     } while (cursor);
 }
 /**
@@ -142,7 +163,7 @@ async function paginateWithMetadata(fetchPage) {
     do {
         const response = await fetchPage(cursor);
         items.push(...response.results);
-        cursor = response.next_cursor ?? undefined;
+        cursor = nextCursor(response);
         pageCount++;
     } while (cursor);
     return {

package/dist/models/page.model.d.ts

@@ -28,11 +28,30 @@ export declare class Page extends BaseModel<NotionPage> {
      */
     getTitle(): string | null;
     /**
-     * Check if the page is a child of a database.
+     * Check if the page is a row in a database.
+     *
+     * On API version 2025-09-03 and later, a database row has a `data_source_id`
+     * parent. Older responses use a `database_id` parent. This method returns `true`
+     * for both.
      */
     isInDatabase(): boolean;
+    /**
+     * Check if the page is a row in a data source.
+     */
+    isInDataSource(): boolean;
     /**
      * Check if the page is a child of another page.
      */
     isSubpage(): boolean;
+    /**
+     * Get the parent data source ID.
+     * Return `null` when the parent is not a data source.
+     */
+    getParentDataSourceId(): string | null;
+    /**
+     * Get the parent database ID.
+     * A `data_source_id` parent also carries its database ID. Return `null` when the
+     * parent is neither a database nor a data source.
+     */
+    getParentDatabaseId(): string | null;
 }

package/dist/models/page.model.js

@@ -62,10 +62,20 @@ class Page extends base_model_1.BaseModel {
         return null;
     }
     /**
-     * Check if the page is a child of a database.
+     * Check if the page is a row in a database.
+     *
+     * On API version 2025-09-03 and later, a database row has a `data_source_id`
+     * parent. Older responses use a `database_id` parent. This method returns `true`
+     * for both.
      */
     isInDatabase() {
-        return this.data.parent.type === 'database_id';
+        return this.data.parent.type === 'data_source_id' || this.data.parent.type === 'database_id';
+    }
+    /**
+     * Check if the page is a row in a data source.
+     */
+    isInDataSource() {
+        return this.data.parent.type === 'data_source_id';
     }
     /**
      * Check if the page is a child of another page.
@@ -73,5 +83,26 @@ class Page extends base_model_1.BaseModel {
     isSubpage() {
         return this.data.parent.type === 'page_id';
     }
+    /**
+     * Get the parent data source ID.
+     * Return `null` when the parent is not a data source.
+     */
+    getParentDataSourceId() {
+        return this.data.parent.type === 'data_source_id' ? this.data.parent.data_source_id : null;
+    }
+    /**
+     * Get the parent database ID.
+     * A `data_source_id` parent also carries its database ID. Return `null` when the
+     * parent is neither a database nor a data source.
+     */
+    getParentDatabaseId() {
+        if (this.data.parent.type === 'database_id') {
+            return this.data.parent.database_id;
+        }
+        if (this.data.parent.type === 'data_source_id') {
+            return this.data.parent.database_id;
+        }
+        return null;
+    }
 }
 exports.Page = Page;