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

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;