@visus-io/notion-sdk-ts 3.0.1 → 3.1.0

package/dist/helpers/block.helpers.d.ts

@@ -16,6 +16,11 @@ interface BlockObject {
     type: string;
     [key: string]: unknown;
 }
+/** Options for paragraph blocks. */
+interface ParagraphOptions extends TextBlockOptions {
+    /** Icon shown alongside the paragraph. Only meaningful for paragraphs used as tab items. */
+    icon?: unknown;
+}
 /**
  * Create a paragraph block.
  *
@@ -25,7 +30,7 @@ interface BlockObject {
  * block.paragraph(richText('Hello').bold(), { color: 'blue' })
  * ```
  */
-declare function paragraph(text: RichTextInput, options?: TextBlockOptions): BlockObject;
+declare function paragraph(text: RichTextInput, options?: ParagraphOptions): BlockObject;
 /** Options for heading blocks. */
 interface HeadingOptions {
     color?: NotionColor;
@@ -35,6 +40,7 @@ interface HeadingOptions {
 declare function heading1(text: RichTextInput, options?: HeadingOptions): BlockObject;
 declare function heading2(text: RichTextInput, options?: HeadingOptions): BlockObject;
 declare function heading3(text: RichTextInput, options?: HeadingOptions): BlockObject;
+declare function heading4(text: RichTextInput, options?: HeadingOptions): BlockObject;
 declare function bulletedListItem(text: RichTextInput, options?: TextBlockOptions): BlockObject;
 /** Options for numbered list items. */
 interface NumberedListOptions extends TextBlockOptions {
@@ -65,6 +71,14 @@ declare function callout(text: RichTextInput, options?: CalloutOptions): BlockOb
 declare function template(text: RichTextInput, options?: {
     children?: unknown[];
 }): BlockObject;
+/**
+ * @deprecated Meeting-notes blocks are server-managed -- their real shape (`title`,
+ * `status`, and child block IDs for the summary/notes/transcript) is populated by
+ * Notion, not hand-constructed by clients. This helper's `rich_text`-based output no
+ * longer matches `blockSchema`'s `meeting_notes` shape and is not a valid way to
+ * create a meeting-notes block. Kept only to avoid an abrupt removal from the helper
+ * surface; do not use for new code.
+ */
 declare function meetingNotes(text: RichTextInput, options?: {
     children?: unknown[];
 }): BlockObject;
@@ -115,6 +129,27 @@ declare function table(width: number, options?: TableOptions): BlockObject;
 declare function tableRow(cells: RichTextInput[]): BlockObject;
 declare function columnList(columns: unknown[][]): BlockObject;
 declare function column(children: unknown[]): BlockObject;
+/** A single tab: its label becomes the tab's paragraph rich text, `children` its content. */
+interface TabItem {
+    label: RichTextInput;
+    icon?: unknown;
+    color?: NotionColor;
+    children?: unknown[];
+}
+/**
+ * Create a tab block. Only `paragraph` blocks may be direct children of a tab block --
+ * each tab is modeled as one paragraph, whose rich text is the tab label and whose
+ * `children` hold the tab's content.
+ *
+ * @example
+ * ```ts
+ * block.tab([
+ *   { label: 'Overview', children: [block.paragraph('Intro text')] },
+ *   { label: 'Details', icon: icon.emoji('📋'), children: [block.paragraph('More info')] },
+ * ])
+ * ```
+ */
+declare function tab(tabs: TabItem[]): BlockObject;
 /**
  * Create a synced block.
  *
@@ -160,6 +195,7 @@ export declare const block: {
     heading1: typeof heading1;
     heading2: typeof heading2;
     heading3: typeof heading3;
+    heading4: typeof heading4;
     bulletedListItem: typeof bulletedListItem;
     numberedListItem: typeof numberedListItem;
     toDo: typeof toDo;
@@ -185,6 +221,7 @@ export declare const block: {
     tableRow: typeof tableRow;
     columnList: typeof columnList;
     column: typeof column;
+    tab: typeof tab;
     syncedBlock: typeof syncedBlock;
 };
 export {};

package/dist/helpers/block.helpers.js

@@ -29,9 +29,6 @@ function resolveRichText(input) {
     }
     return input;
 }
-// ---------------------------------------------------------------------------
-// Text blocks
-// ---------------------------------------------------------------------------
 /**
  * Create a paragraph block.
  *
@@ -48,6 +45,7 @@ function paragraph(text, options) {
         paragraph: {
             rich_text: resolveRichText(text),
             color: options?.color ?? 'default',
+            ...(options?.icon ? { icon: options.icon } : {}),
             ...(options?.children ? { children: options.children } : {}),
         },
     };
@@ -88,6 +86,18 @@ function heading3(text, options) {
         },
     };
 }
+function heading4(text, options) {
+    return {
+        object: 'block',
+        type: 'heading_4',
+        heading_4: {
+            rich_text: resolveRichText(text),
+            color: options?.color ?? 'default',
+            is_toggleable: options?.isToggleable ?? false,
+            ...(options?.children ? { children: options.children } : {}),
+        },
+    };
+}
 function bulletedListItem(text, options) {
     return {
         object: 'block',
@@ -170,6 +180,14 @@ function template(text, options) {
         },
     };
 }
+/**
+ * @deprecated Meeting-notes blocks are server-managed -- their real shape (`title`,
+ * `status`, and child block IDs for the summary/notes/transcript) is populated by
+ * Notion, not hand-constructed by clients. This helper's `rich_text`-based output no
+ * longer matches `blockSchema`'s `meeting_notes` shape and is not a valid way to
+ * create a meeting-notes block. Kept only to avoid an abrupt removal from the helper
+ * surface; do not use for new code.
+ */
 function meetingNotes(text, options) {
     return {
         object: 'block',
@@ -348,6 +366,28 @@ function column(children) {
         column: { children },
     };
 }
+/**
+ * Create a tab block. Only `paragraph` blocks may be direct children of a tab block --
+ * each tab is modeled as one paragraph, whose rich text is the tab label and whose
+ * `children` hold the tab's content.
+ *
+ * @example
+ * ```ts
+ * block.tab([
+ *   { label: 'Overview', children: [block.paragraph('Intro text')] },
+ *   { label: 'Details', icon: icon.emoji('📋'), children: [block.paragraph('More info')] },
+ * ])
+ * ```
+ */
+function tab(tabs) {
+    return {
+        object: 'block',
+        type: 'tab',
+        tab: {
+            children: tabs.map((item) => paragraph(item.label, { color: item.color, icon: item.icon, children: item.children })),
+        },
+    };
+}
 // ---------------------------------------------------------------------------
 // Synced blocks
 // ---------------------------------------------------------------------------
@@ -406,6 +446,7 @@ exports.block = {
     heading1,
     heading2,
     heading3,
+    heading4,
     bulletedListItem,
     numberedListItem,
     toDo,
@@ -435,6 +476,7 @@ exports.block = {
     tableRow,
     columnList,
     column,
+    tab,
     // Synced
     syncedBlock,
 };

package/dist/helpers/file.helpers.d.ts

@@ -1,3 +1,4 @@
+import type { NativeIconColor } from '../schemas/icon.schema';
 interface EmojiIcon {
     type: 'emoji';
     emoji: string;
@@ -14,6 +15,19 @@ interface FileUploadRef {
         id: string;
     };
 }
+interface NativeIconRef {
+    type: 'icon';
+    icon: {
+        name: string;
+        color?: NativeIconColor;
+    };
+}
+interface CustomEmojiIconRef {
+    type: 'custom_emoji';
+    custom_emoji: {
+        id: string;
+    };
+}
 /**
  * Create an emoji icon object.
  *
@@ -42,7 +56,26 @@ declare function externalIcon(url: string): ExternalRef;
  */
 declare function fileUploadIcon(id: string): FileUploadRef;
 /**
- * Helpers for constructing icon objects (emoji, external URL, or file upload).
+ * Create a native (icon-picker) icon object.
+ *
+ * @example
+ * ```ts
+ * icon.native('star circle', 'blue')
+ * ```
+ */
+declare function nativeIcon(name: string, color?: NativeIconColor): NativeIconRef;
+/**
+ * Create a custom emoji icon object, referencing a workspace custom emoji by id.
+ *
+ * @example
+ * ```ts
+ * icon.customEmoji('emoji-id')
+ * ```
+ */
+declare function customEmojiIcon(id: string): CustomEmojiIconRef;
+/**
+ * Helpers for constructing icon objects (emoji, external URL, file upload,
+ * native icon, or custom emoji).
  *
  * @example
  * ```ts
@@ -59,6 +92,8 @@ export declare const icon: {
     emoji: typeof emojiIcon;
     external: typeof externalIcon;
     fileUpload: typeof fileUploadIcon;
+    native: typeof nativeIcon;
+    customEmoji: typeof customEmojiIcon;
 };
 /**
  * Create an external cover image object.

package/dist/helpers/file.helpers.js

@@ -1,7 +1,4 @@
 "use strict";
-// ---------------------------------------------------------------------------
-// Return types
-// ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.notionFile = exports.cover = exports.icon = void 0;
 // ---------------------------------------------------------------------------
@@ -41,7 +38,30 @@ function fileUploadIcon(id) {
     return { type: 'file_upload', file_upload: { id } };
 }
 /**
- * Helpers for constructing icon objects (emoji, external URL, or file upload).
+ * Create a native (icon-picker) icon object.
+ *
+ * @example
+ * ```ts
+ * icon.native('star circle', 'blue')
+ * ```
+ */
+function nativeIcon(name, color) {
+    return { type: 'icon', icon: { name, ...(color ? { color } : {}) } };
+}
+/**
+ * Create a custom emoji icon object, referencing a workspace custom emoji by id.
+ *
+ * @example
+ * ```ts
+ * icon.customEmoji('emoji-id')
+ * ```
+ */
+function customEmojiIcon(id) {
+    return { type: 'custom_emoji', custom_emoji: { id } };
+}
+/**
+ * Helpers for constructing icon objects (emoji, external URL, file upload,
+ * native icon, or custom emoji).
  *
  * @example
  * ```ts
@@ -58,6 +78,8 @@ exports.icon = {
     emoji: emojiIcon,
     external: externalIcon,
     fileUpload: fileUploadIcon,
+    native: nativeIcon,
+    customEmoji: customEmojiIcon,
 };
 // ---------------------------------------------------------------------------
 // Cover helpers

package/dist/helpers/filter.helpers.d.ts

@@ -38,8 +38,8 @@ declare class CheckboxFilter {
 declare class SelectFilter {
     private readonly property;
     constructor(property: string);
-    equals(value: string): FilterCondition;
-    doesNotEqual(value: string): FilterCondition;
+    equals(value: string | string[]): FilterCondition;
+    doesNotEqual(value: string | string[]): FilterCondition;
     isEmpty(): FilterCondition;
     isNotEmpty(): FilterCondition;
 }
@@ -47,8 +47,8 @@ declare class SelectFilter {
 declare class MultiSelectFilter {
     private readonly property;
     constructor(property: string);
-    contains(value: string): FilterCondition;
-    doesNotContain(value: string): FilterCondition;
+    contains(value: string | string[]): FilterCondition;
+    doesNotContain(value: string | string[]): FilterCondition;
     isEmpty(): FilterCondition;
     isNotEmpty(): FilterCondition;
 }
@@ -56,8 +56,8 @@ declare class MultiSelectFilter {
 declare class StatusFilter {
     private readonly property;
     constructor(property: string);
-    equals(value: string): FilterCondition;
-    doesNotEqual(value: string): FilterCondition;
+    equals(value: string | string[]): FilterCondition;
+    doesNotEqual(value: string | string[]): FilterCondition;
     isEmpty(): FilterCondition;
     isNotEmpty(): FilterCondition;
 }

package/dist/helpers/index.d.ts

@@ -2,9 +2,10 @@ export { block } from './block.helpers';
 export type { RichTextInput } from './block.helpers';
 export { cover, icon, notionFile } from './file.helpers';
 export { filter } from './filter.helpers';
-export { paginate, paginateIterator, paginateWithMetadata } from './pagination.helpers';
-export type { PaginatedFetchFunction } from './pagination.helpers';
+export { collectAllDataSourceRows, iterateAllDataSourceRows, paginate, paginateIterator, paginateWithMetadata, } from './pagination.helpers';
+export type { PaginatedFetchFunction, WindowedFetchFunction } from './pagination.helpers';
 export { parent } from './parent.helpers';
 export { prop } from './property.helpers';
 export { RichTextBuilder, richText } from './richText.helpers';
 export { sort } from './sort.helpers';
+export { webhook } from './webhook.helpers';

package/dist/helpers/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sort = exports.richText = exports.RichTextBuilder = exports.prop = exports.parent = exports.paginateWithMetadata = exports.paginateIterator = exports.paginate = exports.filter = exports.notionFile = exports.icon = exports.cover = exports.block = void 0;
+exports.webhook = exports.sort = exports.richText = exports.RichTextBuilder = exports.prop = exports.parent = exports.paginateWithMetadata = exports.paginateIterator = exports.paginate = exports.iterateAllDataSourceRows = exports.collectAllDataSourceRows = exports.filter = exports.notionFile = exports.icon = exports.cover = exports.block = void 0;
 var block_helpers_1 = require("./block.helpers");
 Object.defineProperty(exports, "block", { enumerable: true, get: function () { return block_helpers_1.block; } });
 var file_helpers_1 = require("./file.helpers");
@@ -10,6 +10,8 @@ Object.defineProperty(exports, "notionFile", { enumerable: true, get: function (
 var filter_helpers_1 = require("./filter.helpers");
 Object.defineProperty(exports, "filter", { enumerable: true, get: function () { return filter_helpers_1.filter; } });
 var pagination_helpers_1 = require("./pagination.helpers");
+Object.defineProperty(exports, "collectAllDataSourceRows", { enumerable: true, get: function () { return pagination_helpers_1.collectAllDataSourceRows; } });
+Object.defineProperty(exports, "iterateAllDataSourceRows", { enumerable: true, get: function () { return pagination_helpers_1.iterateAllDataSourceRows; } });
 Object.defineProperty(exports, "paginate", { enumerable: true, get: function () { return pagination_helpers_1.paginate; } });
 Object.defineProperty(exports, "paginateIterator", { enumerable: true, get: function () { return pagination_helpers_1.paginateIterator; } });
 Object.defineProperty(exports, "paginateWithMetadata", { enumerable: true, get: function () { return pagination_helpers_1.paginateWithMetadata; } });
@@ -22,3 +24,5 @@ Object.defineProperty(exports, "RichTextBuilder", { enumerable: true, get: funct
 Object.defineProperty(exports, "richText", { enumerable: true, get: function () { return richText_helpers_1.richText; } });
 var sort_helpers_1 = require("./sort.helpers");
 Object.defineProperty(exports, "sort", { enumerable: true, get: function () { return sort_helpers_1.sort; } });
+var webhook_helpers_1 = require("./webhook.helpers");
+Object.defineProperty(exports, "webhook", { enumerable: true, get: function () { return webhook_helpers_1.webhook; } });

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

@@ -149,3 +149,59 @@ export declare function paginateWithMetadata<T>(fetchPage: PaginatedFetchFunctio
     pageCount: number;
     totalCount: number;
 }>;
+/**
+ * Fetch function for windowed row collection. Same as {@link PaginatedFetchFunction} plus
+ * a second parameter carrying the ISO 8601 `created_time` lower bound for the *next*
+ * window, present once the previous window was capped at the query result limit
+ * (`request_status.type === 'incomplete'`). The caller merges this into their own
+ * created_time-ascending query, e.g. `filter.createdTime('Created time').onOrAfter(createdTimeCursor)`.
+ */
+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, transparently working around the
+ * API's 10,000-result-per-query cap.
+ *
+ * Data source (and view) queries cap at 10,000 results; when capped, the response's
+ * `has_more` is still `false`, so following `next_cursor`/`has_more` alone silently
+ * truncates the result set. When a window is capped (`request_status.type ===
+ * 'incomplete'`), this starts a new query filtered to `created_time >=` the last row
+ * seen, de-duplicating by `id` across the window boundary. Requires the query to be
+ * sorted by `created_time` ascending.
+ *
+ * @param fetchWindow - Function that fetches one page, given the current cursor and
+ * (once a window has been capped) 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('Created time').onOrAfter(createdTimeCursor))
+ *       : baseFilter,
+ *   }),
+ * );
+ * ```
+ */
+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, transparently working
+ * around the API's 10,000-result-per-query cap. See {@link iterateAllDataSourceRows}
+ * for the windowing behavior.
+ *
+ * @param fetchWindow - Function that fetches one page, given the current cursor and
+ * (once a window has been capped) a `created_time` lower bound for the next window
+ * @returns Array containing all rows across all windows
+ */
+export declare function collectAllDataSourceRows<T extends {
+    id: string;
+    createdTime: Date;
+}>(fetchWindow: WindowedFetchFunction<T>): Promise<T[]>;

package/dist/helpers/pagination.helpers.js

@@ -3,6 +3,8 @@ 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.
  *
@@ -143,3 +145,87 @@ async function paginateWithMetadata(fetchPage) {
         totalCount: items.length,
     };
 }
+/**
+ * Iterates over every row of a data source query, transparently working around the
+ * API's 10,000-result-per-query cap.
+ *
+ * Data source (and view) queries cap at 10,000 results; when capped, the response's
+ * `has_more` is still `false`, so following `next_cursor`/`has_more` alone silently
+ * truncates the result set. When a window is capped (`request_status.type ===
+ * 'incomplete'`), this starts a new query filtered to `created_time >=` the last row
+ * seen, de-duplicating by `id` across the window boundary. Requires the query to be
+ * sorted by `created_time` ascending.
+ *
+ * @param fetchWindow - Function that fetches one page, given the current cursor and
+ * (once a window has been capped) 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('Created time').onOrAfter(createdTimeCursor))
+ *       : baseFilter,
+ *   }),
+ * );
+ * ```
+ */
+async function* iterateAllDataSourceRows(fetchWindow) {
+    const seenIds = 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) {
+            if (seenIds.has(item.id)) {
+                continue;
+            }
+            seenIds.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, transparently working
+ * around the API's 10,000-result-per-query cap. See {@link iterateAllDataSourceRows}
+ * for the windowing behavior.
+ *
+ * @param fetchWindow - Function that fetches one page, given the current cursor and
+ * (once a window has been capped) a `created_time` lower bound for the next window
+ * @returns Array containing all rows across all windows
+ */
+async function collectAllDataSourceRows(fetchWindow) {
+    const all = [];
+    for await (const item of iterateAllDataSourceRows(fetchWindow)) {
+        all.push(item);
+    }
+    return all;
+}

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;
@@ -243,5 +271,6 @@ export declare const prop: {
     relation: typeof relation;
     people: typeof people;
     files: typeof files;
+    verification: typeof verification;
 };
 export {};

package/dist/helpers/property.helpers.js

@@ -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.
  *
@@ -268,4 +294,5 @@ exports.prop = {
     relation,
     people,
     files,
+    verification,
 };

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

@@ -0,0 +1,52 @@
+/**
+ * Sign a payload, for generating test webhook signatures.
+ *
+ * @param body - The payload to sign. A string is signed as-is; anything else is
+ * `JSON.stringify`'d first -- safe here because the caller controls the exact
+ * serialization of a payload they're constructing themselves.
+ * @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 Notion sent, not
+ * `JSON.stringify(parsedBody)` -- re-serializing a parsed object can produce a
+ * different byte sequence (key order, whitespace) than what was actually signed,
+ * silently breaking verification. Use your framework's raw-body access (e.g.
+ * Express's `express.raw()` / `req.rawBody`), not `req.body` after JSON middleware
+ * has already parsed 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; `false` for any mismatch or malformed
+ * input (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);
+ * ```
+ */
+export declare const webhook: {
+    sign: typeof sign;
+    verifySignature: typeof verifySignature;
+};
+export {};