@visus-io/notion-sdk-ts 3.0.2 → 3.1.1

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

@@ -1,10 +1,10 @@
 import type { PaginatedList } from '../schemas';
 /**
- * Pagination helper utilities for collecting all results from paginated Notion API endpoints.
+ * Pagination helpers that collect all results from paginated Notion API endpoints.
  *
- * The Notion API uses cursor-based pagination. All list endpoints return a `PaginatedList<T>`
- * with `results`, `next_cursor`, and `has_more` properties. These helpers automate the process
- * of fetching all pages.
+ * The Notion API uses cursor-based pagination. Each list endpoint returns a
+ * `PaginatedList<T>` object with `results`, `next_cursor`, and `has_more` properties.
+ * These helpers fetch every page automatically.
  *
  * @example
  * ```typescript
@@ -35,14 +35,16 @@ import type { PaginatedList } from '../schemas';
  */
 /**
  * Fetch function that returns a paginated list.
- * Receives an optional cursor and returns the next page of results.
+ * This function receives an optional cursor. It returns the next page of results.
+ *
+ * @category Pagination
  */
 export type PaginatedFetchFunction<T> = (cursor?: string) => Promise<PaginatedList<T>>;
 /**
  * Collects all results from a paginated endpoint by automatically following cursors.
  *
- * This function will keep fetching pages until `has_more` is `false`, collecting all
- * results into a single array. Use this when you need all results at once.
+ * 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.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Array containing all results from all pages
@@ -82,14 +84,16 @@ export type PaginatedFetchFunction<T> = (cursor?: string) => Promise<PaginatedLi
  *   })
  * );
  * ```
+ *
+ * @category Pagination
  */
 export declare function paginate<T>(fetchPage: PaginatedFetchFunction<T>): Promise<T[]>;
 /**
  * Creates an async iterator that yields individual items from paginated results.
  *
- * This function provides memory-efficient iteration over large result sets by fetching
- * one page at a time and yielding items as needed. Use this with `for await...of` when
- * you want to process results one by one without loading everything into memory.
+ * This function iterates over large result sets without loading everything into
+ * memory. It fetches one page at a time and yields items as needed. Use this function
+ * with `for await...of` to process results one at a time.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @yields Individual items from each page
@@ -124,13 +128,15 @@ export declare function paginate<T>(fetchPage: PaginatedFetchFunction<T>): Promi
  *   console.log(result.url);
  * }
  * ```
+ *
+ * @category Pagination
  */
 export declare function paginateIterator<T>(fetchPage: PaginatedFetchFunction<T>): AsyncGenerator<T, void, undefined>;
 /**
- * Collects all results and returns both the items and pagination metadata.
+ * Collects all results. Returns the items together with pagination metadata.
  *
- * This function is useful when you need to know how many pages were fetched
- * or want to track the total number of API calls made.
+ * Use this function when you need the page count or the total number of API
+ * calls.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Object containing all results and pagination metadata
@@ -143,9 +149,75 @@ export declare function paginateIterator<T>(fetchPage: PaginatedFetchFunction<T>
  *
  * console.log(`Fetched ${totalCount} blocks across ${pageCount} pages`);
  * ```
+ *
+ * @category Pagination
  */
 export declare function paginateWithMetadata<T>(fetchPage: PaginatedFetchFunction<T>): Promise<{
     items: T[];
     pageCount: number;
     totalCount: number;
 }>;
+/**
+ * Fetch function for windowed row collection. It extends
+ * {@link PaginatedFetchFunction} with a second parameter: the ISO 8601
+ * `created_time` lower bound for the next window. This parameter appears only
+ * after the previous window hits the query result limit
+ * (`request_status.type === 'incomplete'`). Merge this bound into your own
+ * created_time-ascending query, for example
+ * `filter.createdTime().onOrAfter(createdTimeCursor)`.
+ *
+ * @category Pagination
+ */
+export type WindowedFetchFunction<T extends {
+    id: string;
+    createdTime: Date;
+}> = (cursor: string | undefined, createdTimeCursor: string | undefined) => Promise<PaginatedList<T>>;
+/**
+ * Iterates over every row of a data source query. It works around the API's
+ * 10,000-result-per-query cap.
+ *
+ * Data source and view queries cap at 10,000 results. When a query hits this cap, the
+ * response's `has_more` field is still `false`. Following `next_cursor` and `has_more`
+ * alone silently truncates the result set. When a window hits the cap
+ * (`request_status.type === 'incomplete'`), this function starts a new query filtered
+ * to `created_time >=` the last row seen. It de-duplicates rows by `id` across the
+ * window boundary. The query must sort by `created_time` in ascending order.
+ *
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
+ * @yields Individual rows across all windows
+ *
+ * @example
+ * ```typescript
+ * const rows = collectAllDataSourceRows((cursor, createdTimeCursor) =>
+ *   notion.dataSources.query(dataSourceId, {
+ *     start_cursor: cursor,
+ *     sorts: [{ timestamp: 'created_time', direction: 'ascending' }],
+ *     filter: createdTimeCursor
+ *       ? filter.and(baseFilter, filter.createdTime().onOrAfter(createdTimeCursor))
+ *       : baseFilter,
+ *   }),
+ * );
+ * ```
+ *
+ * @category Pagination
+ */
+export declare function iterateAllDataSourceRows<T extends {
+    id: string;
+    createdTime: Date;
+}>(fetchWindow: WindowedFetchFunction<T>): AsyncGenerator<T, void, undefined>;
+/**
+ * Collects every row of a data source query into an array. It works around the API's
+ * 10,000-result-per-query cap. See {@link iterateAllDataSourceRows} for the windowing
+ * behavior.
+ *
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
+ * @returns Array containing all rows across all windows
+ *
+ * @category Pagination
+ */
+export declare function collectAllDataSourceRows<T extends {
+    id: string;
+    createdTime: Date;
+}>(fetchWindow: WindowedFetchFunction<T>): Promise<T[]>;

package/dist/helpers/pagination.helpers.js

@@ -3,11 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.paginate = paginate;
 exports.paginateIterator = paginateIterator;
 exports.paginateWithMetadata = paginateWithMetadata;
+exports.iterateAllDataSourceRows = iterateAllDataSourceRows;
+exports.collectAllDataSourceRows = collectAllDataSourceRows;
 /**
  * Collects all results from a paginated endpoint by automatically following cursors.
  *
- * This function will keep fetching pages until `has_more` is `false`, collecting all
- * results into a single array. Use this when you need all results at once.
+ * 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.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Array containing all results from all pages
@@ -47,6 +49,8 @@ exports.paginateWithMetadata = paginateWithMetadata;
  *   })
  * );
  * ```
+ *
+ * @category Pagination
  */
 async function paginate(fetchPage) {
     const all = [];
@@ -61,9 +65,9 @@ async function paginate(fetchPage) {
 /**
  * Creates an async iterator that yields individual items from paginated results.
  *
- * This function provides memory-efficient iteration over large result sets by fetching
- * one page at a time and yielding items as needed. Use this with `for await...of` when
- * you want to process results one by one without loading everything into memory.
+ * This function iterates over large result sets without loading everything into
+ * memory. It fetches one page at a time and yields items as needed. Use this function
+ * with `for await...of` to process results one at a time.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @yields Individual items from each page
@@ -98,6 +102,8 @@ async function paginate(fetchPage) {
  *   console.log(result.url);
  * }
  * ```
+ *
+ * @category Pagination
  */
 async function* paginateIterator(fetchPage) {
     let cursor;
@@ -110,10 +116,10 @@ async function* paginateIterator(fetchPage) {
     } while (cursor);
 }
 /**
- * Collects all results and returns both the items and pagination metadata.
+ * Collects all results. Returns the items together with pagination metadata.
  *
- * This function is useful when you need to know how many pages were fetched
- * or want to track the total number of API calls made.
+ * Use this function when you need the page count or the total number of API
+ * calls.
  *
  * @param fetchPage - Function that fetches a single page of results
  * @returns Object containing all results and pagination metadata
@@ -126,6 +132,8 @@ async function* paginateIterator(fetchPage) {
  *
  * console.log(`Fetched ${totalCount} blocks across ${pageCount} pages`);
  * ```
+ *
+ * @category Pagination
  */
 async function paginateWithMetadata(fetchPage) {
     const items = [];
@@ -143,3 +151,101 @@ async function paginateWithMetadata(fetchPage) {
         totalCount: items.length,
     };
 }
+/**
+ * Iterates over every row of a data source query. It works around the API's
+ * 10,000-result-per-query cap.
+ *
+ * Data source and view queries cap at 10,000 results. When a query hits this cap, the
+ * response's `has_more` field is still `false`. Following `next_cursor` and `has_more`
+ * alone silently truncates the result set. When a window hits the cap
+ * (`request_status.type === 'incomplete'`), this function starts a new query filtered
+ * to `created_time >=` the last row seen. It de-duplicates rows by `id` across the
+ * window boundary. The query must sort by `created_time` in ascending order.
+ *
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
+ * @yields Individual rows across all windows
+ *
+ * @example
+ * ```typescript
+ * const rows = collectAllDataSourceRows((cursor, createdTimeCursor) =>
+ *   notion.dataSources.query(dataSourceId, {
+ *     start_cursor: cursor,
+ *     sorts: [{ timestamp: 'created_time', direction: 'ascending' }],
+ *     filter: createdTimeCursor
+ *       ? filter.and(baseFilter, filter.createdTime().onOrAfter(createdTimeCursor))
+ *       : baseFilter,
+ *   }),
+ * );
+ * ```
+ *
+ * @category Pagination
+ */
+async function* iterateAllDataSourceRows(fetchWindow) {
+    // Rows repeat across a window boundary only when they share the exact `created_time`
+    // used as the next window's lower bound (results are sorted ascending by created_time,
+    // so ties are always contiguous). Tracking only that trailing tie group -- instead of
+    // every id ever yielded -- keeps memory bounded regardless of result set size.
+    let tailTimeMs;
+    let tailIds = new Set();
+    let cursor;
+    let createdTimeCursor;
+    let lastCreatedTime;
+    let hasMore = true;
+    while (hasMore) {
+        const response = await fetchWindow(cursor, createdTimeCursor);
+        let yieldedThisWindow = false;
+        for (const item of response.results) {
+            const itemTimeMs = item.createdTime.getTime();
+            if (tailTimeMs !== undefined && itemTimeMs === tailTimeMs && tailIds.has(item.id)) {
+                continue;
+            }
+            if (tailTimeMs === undefined || itemTimeMs > tailTimeMs) {
+                tailTimeMs = itemTimeMs;
+                tailIds = new Set();
+            }
+            tailIds.add(item.id);
+            lastCreatedTime = item.createdTime;
+            yieldedThisWindow = true;
+            yield item;
+        }
+        if (response.request_status?.type === 'incomplete' && lastCreatedTime) {
+            // has_more is false here, so normal cursor pagination would silently stop short.
+            // Start a fresh window scoped to created_time >= the last row seen, de-duping by
+            // id across the boundary (created_time, not last_edited_time -- the latter shifts
+            // rows between windows).
+            if (!yieldedThisWindow) {
+                // Every row in this capped window was already seen, meaning more rows share
+                // this exact created_time than fit in one window -- the created_time >= filter
+                // can't disambiguate further, so re-querying would return the same page forever.
+                throw new Error(`More than one window's worth of rows share the same created_time (${lastCreatedTime.toISOString()}); ` +
+                    'iterateAllDataSourceRows cannot make forward progress past this timestamp.');
+            }
+            cursor = undefined;
+            createdTimeCursor = lastCreatedTime.toISOString();
+            hasMore = true;
+        }
+        else {
+            cursor = response.next_cursor ?? undefined;
+            hasMore = cursor !== undefined;
+        }
+    }
+}
+/**
+ * Collects every row of a data source query into an array. It works around the API's
+ * 10,000-result-per-query cap. See {@link iterateAllDataSourceRows} for the windowing
+ * behavior.
+ *
+ * @param fetchWindow - Function that fetches one page. Pass the current cursor. After
+ * a window hits the cap, also pass a `created_time` lower bound for the next window.
+ * @returns Array containing all rows across all windows
+ *
+ * @category Pagination
+ */
+async function collectAllDataSourceRows(fetchWindow) {
+    const all = [];
+    for await (const item of iterateAllDataSourceRows(fetchWindow)) {
+        all.push(item);
+    }
+    return all;
+}

package/dist/helpers/parent.helpers.d.ts

@@ -22,8 +22,8 @@ declare function database(databaseId: string): {
 };
 /**
  * Create a data source parent object.
- * Both data_source_id and database_id are required when creating a page
- * with a data source parent.
+ * A page with a data source parent needs both `data_source_id` and
+ * `database_id`.
  *
  * @example
  * ```ts
@@ -51,7 +51,7 @@ declare function workspace(): {
     workspace: true;
 };
 /**
- * Create a block parent object (used for comments on blocks).
+ * Create a block parent object for comments on blocks.
  *
  * @example
  * ```ts
@@ -86,6 +86,8 @@ declare function blockParent(blockId: string): {
  *   rich_text: [...],
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const parent: {
     page: typeof page;

package/dist/helpers/parent.helpers.js

@@ -28,8 +28,8 @@ function database(databaseId) {
 }
 /**
  * Create a data source parent object.
- * Both data_source_id and database_id are required when creating a page
- * with a data source parent.
+ * A page with a data source parent needs both `data_source_id` and
+ * `database_id`.
  *
  * @example
  * ```ts
@@ -56,7 +56,7 @@ function workspace() {
     return { workspace: true };
 }
 /**
- * Create a block parent object (used for comments on blocks).
+ * Create a block parent object for comments on blocks.
  *
  * @example
  * ```ts
@@ -94,6 +94,8 @@ function blockParent(blockId) {
  *   rich_text: [...],
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.parent = {
     page,

package/dist/helpers/property.helpers.d.ts

@@ -181,6 +181,34 @@ declare function people(userIds: string[]): {
         id: string;
     }>;
 };
+/** Options for the verification property's optional date. */
+interface VerificationDateOptions {
+    start: string;
+    end?: string | null;
+    timeZone?: string | null;
+}
+/** The shape of a verification property value. */
+interface VerificationValue {
+    verification: {
+        state: 'verified' | 'unverified';
+        date?: {
+            start: string;
+            end: string | null;
+            time_zone: string | null;
+        } | null;
+    };
+}
+/**
+ * Create a verification property value.
+ *
+ * @example
+ * ```ts
+ * prop.verification('verified')
+ * prop.verification('verified', { start: '2025-01-15' })
+ * prop.verification('unverified')
+ * ```
+ */
+declare function verification(state: 'verified' | 'unverified', date?: VerificationDateOptions): VerificationValue;
 /** A single file entry for the files' property. */
 interface FileEntry {
     name: string;
@@ -227,6 +255,8 @@ declare function files(entries: FileEntry[]): {
  *   },
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const prop: {
     title: typeof title;
@@ -243,5 +273,6 @@ export declare const prop: {
     relation: typeof relation;
     people: typeof people;
     files: typeof files;
+    verification: typeof verification;
 };
 export {};

package/dist/helpers/property.helpers.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.prop = void 0;
 const validation_1 = require("../validation");
 const richText_helpers_1 = require("./richText.helpers");
-/** Resolve rich text input to a `NotionRichText` array. */
+/** Resolve rich text input to a `NotionRichText`. */
 function resolveRichText(input) {
     if (typeof input === 'string') {
         (0, validation_1.validateStringLength)(input, validation_1.LIMITS.RICH_TEXT_CONTENT, 'Rich text content');
@@ -210,6 +210,32 @@ function people(userIds) {
     (0, validation_1.validateArrayLength)(userIds, validation_1.LIMITS.PEOPLE, 'People');
     return { people: userIds.map((id) => ({ object: 'user', id })) };
 }
+/**
+ * Create a verification property value.
+ *
+ * @example
+ * ```ts
+ * prop.verification('verified')
+ * prop.verification('verified', { start: '2025-01-15' })
+ * prop.verification('unverified')
+ * ```
+ */
+function verification(state, date) {
+    return {
+        verification: {
+            state,
+            ...(date
+                ? {
+                    date: {
+                        start: date.start,
+                        end: date.end ?? null,
+                        time_zone: date.timeZone ?? null,
+                    },
+                }
+                : {}),
+        },
+    };
+}
 /**
  * Create a files property value.
  *
@@ -252,6 +278,8 @@ function files(entries) {
  *   },
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.prop = {
     title,
@@ -268,4 +296,5 @@ exports.prop = {
     relation,
     people,
     files,
+    verification,
 };

package/dist/helpers/richText.helpers.d.ts

@@ -5,8 +5,9 @@ import type { NotionColor, NotionRichText, NotionUser, TextRichText } from '../s
  * Do not instantiate directly — use the {@link richText} factory function or
  * the static helpers on it (`richText.mentionPage`, `richText.equation`, etc.).
  *
- * Call `.build()` to produce a `NotionRichText` array (single-element),
- * or pass builders directly to `richText.join()` which calls `.build()` for you.
+ * Call `.build()` to produce a single-element `NotionRichText`.
+ * Alternatively, pass builders directly to `richText.join()`. This method
+ * calls `.build()` for you.
  *
  * @example
  * ```ts
@@ -26,6 +27,8 @@ import type { NotionColor, NotionRichText, NotionUser, TextRichText } from '../s
  *   richText('!'),
  * );
  * ```
+ *
+ * @category Rich Text
  */
 export declare class RichTextBuilder {
     /** @internal */
@@ -52,7 +55,7 @@ export declare class RichTextBuilder {
      */
     link(url: string): this;
     /**
-     * Build a single-element `NotionRichText` array from this builder.
+     * Build a single-element `NotionRichText` from this builder.
      */
     build(): NotionRichText;
 }
@@ -99,8 +102,8 @@ declare function mentionLinkPreview(url: string): RichTextBuilder;
  */
 declare function equation(expression: string): RichTextBuilder;
 /**
- * Combine multiple rich text builders (or pre-built `NotionRichText` arrays)
- * into a single `NotionRichText` array.
+ * Combine multiple rich text builders (or pre-built `NotionRichText` values)
+ * into a single `NotionRichText`.
  *
  * @example
  * ```ts
@@ -136,6 +139,8 @@ declare function join(...parts: Array<RichTextBuilder | NotionRichText>): Notion
  *   richText('italic').italic(),
  * );
  * ```
+ *
+ * @category Rich Text
  */
 export declare const richText: typeof createRichText & {
     mentionPage: typeof mentionPage;

package/dist/helpers/richText.helpers.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.richText = exports.RichTextBuilder = void 0;
 const validation_1 = require("../validation");
 /**
- * Default annotations object with no formatting applied.
+ * Default annotations object with no formatting.
  */
 const DEFAULT_ANNOTATIONS = {
     bold: false,
@@ -19,8 +19,9 @@ const DEFAULT_ANNOTATIONS = {
  * Do not instantiate directly — use the {@link richText} factory function or
  * the static helpers on it (`richText.mentionPage`, `richText.equation`, etc.).
  *
- * Call `.build()` to produce a `NotionRichText` array (single-element),
- * or pass builders directly to `richText.join()` which calls `.build()` for you.
+ * Call `.build()` to produce a single-element `NotionRichText`.
+ * Alternatively, pass builders directly to `richText.join()`. This method
+ * calls `.build()` for you.
  *
  * @example
  * ```ts
@@ -40,6 +41,8 @@ const DEFAULT_ANNOTATIONS = {
  *   richText('!'),
  * );
  * ```
+ *
+ * @category Rich Text
  */
 class RichTextBuilder {
     /** @internal */
@@ -93,7 +96,7 @@ class RichTextBuilder {
         return this;
     }
     /**
-     * Build a single-element `NotionRichText` array from this builder.
+     * Build a single-element `NotionRichText` from this builder.
      */
     build() {
         return [{ ...this.segment, annotations: { ...this.annotations } }];
@@ -218,8 +221,8 @@ function equation(expression) {
     return new RichTextBuilder(segment);
 }
 /**
- * Combine multiple rich text builders (or pre-built `NotionRichText` arrays)
- * into a single `NotionRichText` array.
+ * Combine multiple rich text builders (or pre-built `NotionRichText` values)
+ * into a single `NotionRichText`.
  *
  * @example
  * ```ts
@@ -269,6 +272,8 @@ function join(...parts) {
  *   richText('italic').italic(),
  * );
  * ```
+ *
+ * @category Rich Text
  */
 exports.richText = Object.assign(createRichText, {
     mentionPage,

package/dist/helpers/sort.helpers.d.ts

@@ -34,6 +34,8 @@ declare class TimestampSortBuilder {
  *   ],
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const sort: {
     /**

package/dist/helpers/sort.helpers.js

@@ -46,6 +46,8 @@ class TimestampSortBuilder {
  *   ],
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.sort = {
     /**

package/dist/helpers/webhook.helpers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Sign a payload to generate test webhook signatures.
+ *
+ * @param body - The payload to sign. This function signs a string as-is. It
+ * converts anything else with `JSON.stringify` first. This is safe because the
+ * caller controls the serialization of their own payload.
+ * @param verificationToken - The webhook subscription's verification token
+ * @returns The `sha256=<hex digest>` signature
+ *
+ * @example
+ * ```ts
+ * const signature = webhook.sign({ event: 'page.updated' }, verificationToken);
+ * ```
+ */
+declare function sign(body: unknown, verificationToken: string): string;
+/**
+ * Verify an incoming webhook's `X-Notion-Signature` header via constant-time comparison.
+ *
+ * IMPORTANT: `rawBody` must be the exact raw request body that Notion sent. Do not use
+ * `JSON.stringify(parsedBody)`. Re-serializing a parsed object can produce a different
+ * byte sequence (key order, whitespace) than the original signed body, and this
+ * silently breaks verification. Use your framework's raw-body access, for example
+ * Express's `express.raw()` or `req.rawBody`. Do not use `req.body` after JSON
+ * middleware parses it.
+ *
+ * @param rawBody - The exact raw request body string Notion sent
+ * @param signatureHeader - The value of the `X-Notion-Signature` request header
+ * @param verificationToken - The webhook subscription's verification token
+ * @returns `true` if the signature is valid. Returns `false` for a mismatch or
+ * malformed input. This function never throws.
+ *
+ * @example
+ * ```ts
+ * const isValid = webhook.verifySignature(rawBody, req.headers['x-notion-signature'], verificationToken);
+ * ```
+ */
+declare function verifySignature(rawBody: string, signatureHeader: string | null | undefined, verificationToken: string): boolean;
+/**
+ * Helpers for signing and verifying Notion webhook payloads.
+ *
+ * @example
+ * ```ts
+ * import { webhook } from '@visus-io/notion-sdk-ts';
+ *
+ * const isValid = webhook.verifySignature(rawBody, req.headers['x-notion-signature'], verificationToken);
+ * ```
+ *
+ * @category Helpers
+ */
+export declare const webhook: {
+    sign: typeof sign;
+    verifySignature: typeof verifySignature;
+};
+export {};