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

package/dist/helpers/webhook.helpers.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webhook = void 0;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Webhook signature helpers.
+ *
+ * Notion signs webhook payloads with HMAC-SHA256. It signs the raw JSON request body
+ * and keys the signature with the subscription's verification token. Notion sends the
+ * signature in the `X-Notion-Signature` header as `sha256=<hex digest>`.
+ *
+ * Notion API reference:
+ * https://developers.notion.com/reference/webhooks
+ */
+function computeSignature(rawBody, verificationToken) {
+    return `sha256=${(0, node_crypto_1.createHmac)('sha256', verificationToken).update(rawBody).digest('hex')}`;
+}
+/**
+ * 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);
+ * ```
+ */
+function sign(body, verificationToken) {
+    return computeSignature(typeof body === 'string' ? body : JSON.stringify(body), verificationToken);
+}
+/**
+ * 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);
+ * ```
+ */
+function verifySignature(rawBody, signatureHeader, verificationToken) {
+    if (!signatureHeader) {
+        return false;
+    }
+    const expected = Buffer.from(computeSignature(rawBody, verificationToken));
+    const actual = Buffer.from(signatureHeader);
+    // timingSafeEqual throws on mismatched buffer lengths, so guard explicitly.
+    if (expected.length !== actual.length) {
+        return false;
+    }
+    return (0, node_crypto_1.timingSafeEqual)(expected, actual);
+}
+/**
+ * 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
+ */
+exports.webhook = {
+    sign,
+    verifySignature,
+};

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

@@ -0,0 +1,61 @@
+import { BaseModel, type TRUSTED } from './base.model';
+import { type NotionAsyncTask } from '../schemas';
+/**
+ * AsyncTask model class with helper methods.
+ *
+ * Represents a long-running operation, for example an async markdown write. Poll the
+ * task until it reaches a terminal status.
+ *
+ * @category Async Tasks
+ */
+export declare class AsyncTask extends BaseModel<NotionAsyncTask> {
+    constructor(data: NotionAsyncTask, trusted?: typeof TRUSTED);
+    /**
+     * Returns "async_task" - the object type.
+     */
+    get object(): 'async_task';
+    /**
+     * Returns the task ID.
+     */
+    get id(): string;
+    /**
+     * Returns the task status.
+     */
+    get status(): NotionAsyncTask['status'];
+    /**
+     * Returns the URL to poll for the task status.
+     */
+    get statusUrl(): string;
+    /**
+     * Returns the task creation time as a Date object.
+     */
+    get createdTime(): Date;
+    /**
+     * Returns the operation that created this task.
+     */
+    get operation(): NotionAsyncTask['operation'];
+    /**
+     * Returns the minimum number of seconds to wait before polling again, if provided.
+     */
+    get pollAfterSeconds(): number | undefined;
+    /**
+     * Returns the operation-specific result, present only when the task succeeded.
+     */
+    get result(): unknown;
+    /**
+     * Returns the error details, present only when the task failed.
+     */
+    get error(): NotionAsyncTask['error'];
+    /**
+     * Returns whether the task completed successfully.
+     */
+    isSucceeded(): boolean;
+    /**
+     * Returns whether the task failed.
+     */
+    isFailed(): boolean;
+    /**
+     * Returns whether the task has reached a terminal status (succeeded or failed).
+     */
+    isTerminal(): boolean;
+}

package/dist/models/asyncTask.model.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncTask = void 0;
+const base_model_1 = require("./base.model");
+const schemas_1 = require("../schemas");
+/**
+ * AsyncTask model class with helper methods.
+ *
+ * Represents a long-running operation, for example an async markdown write. Poll the
+ * task until it reaches a terminal status.
+ *
+ * @category Async Tasks
+ */
+class AsyncTask extends base_model_1.BaseModel {
+    constructor(data, trusted) {
+        super(data, schemas_1.asyncTaskSchema, trusted);
+    }
+    /**
+     * Returns "async_task" - the object type.
+     */
+    get object() {
+        return this.data.object;
+    }
+    /**
+     * Returns the task ID.
+     */
+    get id() {
+        return this.data.id;
+    }
+    /**
+     * Returns the task status.
+     */
+    get status() {
+        return this.data.status;
+    }
+    /**
+     * Returns the URL to poll for the task status.
+     */
+    get statusUrl() {
+        return this.data.status_url;
+    }
+    /**
+     * Returns the task creation time as a Date object.
+     */
+    get createdTime() {
+        return new Date(this.data.created_time);
+    }
+    /**
+     * Returns the operation that created this task.
+     */
+    get operation() {
+        return this.data.operation;
+    }
+    /**
+     * Returns the minimum number of seconds to wait before polling again, if provided.
+     */
+    get pollAfterSeconds() {
+        return this.data.poll_after_seconds;
+    }
+    /**
+     * Returns the operation-specific result, present only when the task succeeded.
+     */
+    get result() {
+        return this.data.result;
+    }
+    /**
+     * Returns the error details, present only when the task failed.
+     */
+    get error() {
+        return this.data.error;
+    }
+    /**
+     * Returns whether the task completed successfully.
+     */
+    isSucceeded() {
+        return this.data.status === 'succeeded';
+    }
+    /**
+     * Returns whether the task failed.
+     */
+    isFailed() {
+        return this.data.status === 'failed';
+    }
+    /**
+     * Returns whether the task has reached a terminal status (succeeded or failed).
+     */
+    isTerminal() {
+        return this.isSucceeded() || this.isFailed();
+    }
+}
+exports.AsyncTask = AsyncTask;

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

@@ -1,17 +1,29 @@
 import type * as z from 'zod';
 /**
- * Base model class providing common functionality for all Notion models.
- * Models wrap validated data from schemas with methods and business logic.
+ * Internal marker for trusted, already-validated data.
+ *
+ * Pass this to a model constructor to skip re-parsing data an API module already
+ * validated. This symbol is not exported from the package's public barrel, so
+ * external consumers can never construct or forge it. Direct construction from
+ * outside the SDK always validates.
+ */
+export declare const TRUSTED: unique symbol;
+/**
+ * Base class for all Notion models.
+ *
+ * This class wraps validated data from a schema. It adds methods and logic for each model.
+ *
+ * @category Client & Core
  */
 export declare abstract class BaseModel<T> {
     protected readonly data: T;
-    protected constructor(data: T, schema: z.ZodType<T>);
+    protected constructor(data: T, schema: z.ZodType<T>, trusted?: typeof TRUSTED);
     /**
      * Returns the raw validated data as a plain object.
      */
     toJSON(): T;
     /**
-     * Returns the object type (e.g., "page", "block", "user").
+     * Returns the object type, for example "page", "block", or "user".
      */
     abstract get object(): string;
     /**

package/dist/models/base.model.js

@@ -1,13 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseModel = void 0;
+exports.BaseModel = exports.TRUSTED = void 0;
 /**
- * Base model class providing common functionality for all Notion models.
- * Models wrap validated data from schemas with methods and business logic.
+ * Internal marker for trusted, already-validated data.
+ *
+ * Pass this to a model constructor to skip re-parsing data an API module already
+ * validated. This symbol is not exported from the package's public barrel, so
+ * external consumers can never construct or forge it. Direct construction from
+ * outside the SDK always validates.
+ */
+exports.TRUSTED = Symbol('trusted');
+/**
+ * Base class for all Notion models.
+ *
+ * This class wraps validated data from a schema. It adds methods and logic for each model.
+ *
+ * @category Client & Core
  */
 class BaseModel {
-    constructor(data, schema) {
-        this.data = schema.parse(data);
+    constructor(data, schema, trusted) {
+        this.data = trusted === exports.TRUSTED ? data : schema.parse(data);
     }
     /**
      * Returns the raw validated data as a plain object.

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

@@ -1,10 +1,14 @@
-import { BaseModel } from './base.model';
+import { BaseModel, type TRUSTED } from './base.model';
 import { type NotionBlock } from '../schemas';
 /**
  * Block model wrapping a validated Notion block object with helper methods.
+ *
+ * @category Blocks
  */
 export declare class Block extends BaseModel<NotionBlock> {
-    constructor(data: unknown);
+    private cachedCreatedTimeMs?;
+    private cachedLastEditedTimeMs?;
+    constructor(data: unknown, trusted?: typeof TRUSTED);
     get object(): string;
     get id(): string;
     get type(): NotionBlock['type'];

package/dist/models/block.model.js

@@ -3,12 +3,51 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Block = void 0;
 const base_model_1 = require("./base.model");
 const schemas_1 = require("../schemas");
+const TEXT_BLOCK_TYPES = new Set([
+    'paragraph',
+    'heading_1',
+    'heading_2',
+    'heading_3',
+    'heading_4',
+    'quote',
+    'callout',
+    'bulleted_list_item',
+    'numbered_list_item',
+    'to_do',
+    'toggle',
+]);
+const HEADING_BLOCK_TYPES = new Set([
+    'heading_1',
+    'heading_2',
+    'heading_3',
+    'heading_4',
+]);
+const CHILD_CONTAINER_BLOCK_TYPES = new Set([
+    'paragraph',
+    'heading_1',
+    'heading_2',
+    'heading_3',
+    'heading_4',
+    'bulleted_list_item',
+    'numbered_list_item',
+    'to_do',
+    'toggle',
+    'quote',
+    'callout',
+    'synced_block',
+    'column',
+    'column_list',
+    'tab',
+    'table',
+]);
 /**
  * Block model wrapping a validated Notion block object with helper methods.
+ *
+ * @category Blocks
  */
 class Block extends base_model_1.BaseModel {
-    constructor(data) {
-        super(data, schemas_1.blockSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.blockSchema, trusted);
     }
     get object() {
         return this.data.object;
@@ -20,10 +59,12 @@ class Block extends base_model_1.BaseModel {
         return this.data.type;
     }
     get createdTime() {
-        return new Date(this.data.created_time);
+        this.cachedCreatedTimeMs ??= new Date(this.data.created_time).getTime();
+        return new Date(this.cachedCreatedTimeMs);
     }
     get lastEditedTime() {
-        return new Date(this.data.last_edited_time);
+        this.cachedLastEditedTimeMs ??= new Date(this.data.last_edited_time).getTime();
+        return new Date(this.cachedLastEditedTimeMs);
     }
     get inTrash() {
         return this.data.in_trash;
@@ -35,45 +76,19 @@ class Block extends base_model_1.BaseModel {
      * Check if this is a text-based block type.
      */
     isTextBlock() {
-        return [
-            'paragraph',
-            'heading_1',
-            'heading_2',
-            'heading_3',
-            'quote',
-            'callout',
-            'bulleted_list_item',
-            'numbered_list_item',
-            'to_do',
-            'toggle',
-        ].includes(this.data.type);
+        return TEXT_BLOCK_TYPES.has(this.data.type);
     }
     /**
      * Check if this is a heading block.
      */
     isHeading() {
-        return ['heading_1', 'heading_2', 'heading_3'].includes(this.data.type);
+        return HEADING_BLOCK_TYPES.has(this.data.type);
     }
     /**
      * Check if this block can contain children.
      */
     canHaveChildren() {
-        return [
-            'paragraph',
-            'heading_1',
-            'heading_2',
-            'heading_3',
-            'bulleted_list_item',
-            'numbered_list_item',
-            'to_do',
-            'toggle',
-            'quote',
-            'callout',
-            'synced_block',
-            'column',
-            'column_list',
-            'table',
-        ].includes(this.data.type);
+        return CHILD_CONTAINER_BLOCK_TYPES.has(this.data.type);
     }
     /**
      * Get the plain text content from text-based blocks.

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

@@ -1,10 +1,12 @@
-import { BaseModel } from './base.model';
+import { BaseModel, type TRUSTED } from './base.model';
 import { type CommentAttachment, type CommentDisplayName, type NotionComment, type NotionParent, type NotionRichText, type NotionUser } from '../schemas';
 /**
  * Comment model class with helper methods.
+ *
+ * @category Comments
  */
 export declare class Comment extends BaseModel<NotionComment> {
-    constructor(data: NotionComment);
+    constructor(data: NotionComment, trusted?: typeof TRUSTED);
     /**
      * Returns "comment" - the object type.
      */

package/dist/models/comment.model.js

@@ -5,10 +5,12 @@ const base_model_1 = require("./base.model");
 const schemas_1 = require("../schemas");
 /**
  * Comment model class with helper methods.
+ *
+ * @category Comments
  */
 class Comment extends base_model_1.BaseModel {
-    constructor(data) {
-        super(data, schemas_1.commentSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.commentSchema, trusted);
     }
     /**
      * Returns "comment" - the object type.

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

@@ -0,0 +1,30 @@
+import { BaseModel, type TRUSTED } from './base.model';
+import { type NotionCustomEmoji } from '../schemas';
+/**
+ * Custom Emoji model class with helper methods.
+ *
+ * @category Custom Emoji & Icons
+ */
+export declare class CustomEmoji extends BaseModel<NotionCustomEmoji> {
+    constructor(data: NotionCustomEmoji, trusted?: typeof TRUSTED);
+    /**
+     * Returns "custom_emoji" - the object type.
+     *
+     * Note: A custom emoji list item has no `object` field in the API response. Only
+     * the paginated list wrapper has that field. This getter returns a synthetic
+     * value, not data from the payload, to meet the {@link BaseModel} contract.
+     */
+    get object(): 'custom_emoji';
+    /**
+     * Returns the custom emoji ID.
+     */
+    get id(): string;
+    /**
+     * Returns the custom emoji name.
+     */
+    get name(): string;
+    /**
+     * Returns the custom emoji's image URL.
+     */
+    get url(): string;
+}

package/dist/models/customEmoji.model.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CustomEmoji = void 0;
+const base_model_1 = require("./base.model");
+const schemas_1 = require("../schemas");
+/**
+ * Custom Emoji model class with helper methods.
+ *
+ * @category Custom Emoji & Icons
+ */
+class CustomEmoji extends base_model_1.BaseModel {
+    constructor(data, trusted) {
+        super(data, schemas_1.customEmojiSchema, trusted);
+    }
+    /**
+     * Returns "custom_emoji" - the object type.
+     *
+     * Note: A custom emoji list item has no `object` field in the API response. Only
+     * the paginated list wrapper has that field. This getter returns a synthetic
+     * value, not data from the payload, to meet the {@link BaseModel} contract.
+     */
+    get object() {
+        return 'custom_emoji';
+    }
+    /**
+     * Returns the custom emoji ID.
+     */
+    get id() {
+        return this.data.id;
+    }
+    /**
+     * Returns the custom emoji name.
+     */
+    get name() {
+        return this.data.name;
+    }
+    /**
+     * Returns the custom emoji's image URL.
+     */
+    get url() {
+        return this.data.url;
+    }
+}
+exports.CustomEmoji = CustomEmoji;

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

@@ -1,12 +1,14 @@
-import { BaseModel } from './base.model';
-import { type NotionDataSource, type NotionEmoji, type NotionFile, type NotionParent, type NotionPropertiesObject, type NotionPropertyObject, type NotionRichText, type NotionUser } from '../schemas';
+import { BaseModel, type TRUSTED } from './base.model';
+import { type NotionDataSource, type NotionFile, type NotionIcon, type NotionParent, type NotionPropertiesObject, type NotionPropertyObject, type NotionRichText, type NotionUser } from '../schemas';
 /**
  * Data Source model class with helper methods.
  *
  * Data sources are individual tables of data that live under a Notion database.
+ *
+ * @category Databases & Data Sources
  */
 export declare class DataSource extends BaseModel<NotionDataSource> {
-    constructor(data: NotionDataSource);
+    constructor(data: NotionDataSource, trusted?: typeof TRUSTED);
     /**
      * Returns "data_source" - the object type.
      */
@@ -52,9 +54,9 @@ export declare class DataSource extends BaseModel<NotionDataSource> {
      */
     get description(): NotionRichText;
     /**
-     * Returns the data source icon (file or emoji).
+     * Returns the data source icon (file, emoji, native icon, or custom emoji).
      */
-    get icon(): NotionFile | NotionEmoji | null;
+    get icon(): NotionIcon | null;
     /**
      * Returns the data source cover image.
      */

package/dist/models/dataSource.model.js

@@ -7,10 +7,12 @@ const schemas_1 = require("../schemas");
  * Data Source model class with helper methods.
  *
  * Data sources are individual tables of data that live under a Notion database.
+ *
+ * @category Databases & Data Sources
  */
 class DataSource extends base_model_1.BaseModel {
-    constructor(data) {
-        super(data, schemas_1.dataSourceSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.dataSourceSchema, trusted);
     }
     /**
      * Returns "data_source" - the object type.
@@ -79,7 +81,7 @@ class DataSource extends base_model_1.BaseModel {
         return this.data.description;
     }
     /**
-     * Returns the data source icon (file or emoji).
+     * Returns the data source icon (file, emoji, native icon, or custom emoji).
      */
     get icon() {
         return this.data.icon;

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

@@ -1,10 +1,14 @@
-import { BaseModel } from './base.model';
-import { type DataSourceRef, type NotionDatabase, type NotionEmoji, type NotionFile, type NotionParent, type NotionRichText, type NotionUser } from '../schemas';
+import { BaseModel, type TRUSTED } from './base.model';
+import { type DataSourceRef, type NotionDatabase, type NotionFile, type NotionIcon, type NotionParent, type NotionRichText, type NotionUser } from '../schemas';
 /**
  * Database model class with helper methods.
+ *
+ * @category Databases & Data Sources
  */
 export declare class Database extends BaseModel<NotionDatabase> {
-    constructor(data: NotionDatabase);
+    private cachedCreatedTimeMs?;
+    private cachedLastEditedTimeMs?;
+    constructor(data: NotionDatabase, trusted?: typeof TRUSTED);
     /**
      * Returns "database" - the object type.
      */
@@ -42,9 +46,9 @@ export declare class Database extends BaseModel<NotionDatabase> {
      */
     get description(): NotionRichText;
     /**
-     * Returns the database icon (file or emoji).
+     * Returns the database icon (file, emoji, native icon, or custom emoji).
      */
-    get icon(): NotionFile | NotionEmoji | null;
+    get icon(): NotionIcon | null;
     /**
      * Returns the database cover image.
      */
@@ -65,6 +69,10 @@ export declare class Database extends BaseModel<NotionDatabase> {
      * Returns whether the database is inline.
      */
     get isInline(): boolean;
+    /**
+     * Returns whether the database is locked from editing.
+     */
+    get isLocked(): boolean;
     /**
      * Returns the public URL if published, otherwise null.
      */