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

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

@@ -1,9 +1,9 @@
 /**
- * Sign a payload, for generating test webhook signatures.
+ * Sign a payload to generate 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 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
  *
@@ -16,18 +16,18 @@ 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.
+ * 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; `false` for any mismatch or malformed
- * input (never throws)
+ * @returns `true` if the signature is valid. Returns `false` for a mismatch or
+ * malformed input. This function never throws.
  *
  * @example
  * ```ts
@@ -44,6 +44,8 @@ declare function verifySignature(rawBody: string, signatureHeader: string | null
  *
  * const isValid = webhook.verifySignature(rawBody, req.headers['x-notion-signature'], verificationToken);
  * ```
+ *
+ * @category Helpers
  */
 export declare const webhook: {
     sign: typeof sign;

package/dist/helpers/webhook.helpers.js

@@ -5,9 +5,9 @@ const node_crypto_1 = require("node:crypto");
 /**
  * Webhook signature helpers.
  *
- * Notion signs webhook payloads with HMAC-SHA256, keyed by the subscription's
- * verification token, over the raw JSON request body. The signature is sent in the
- * `X-Notion-Signature` header as `sha256=<hex digest>`.
+ * 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
@@ -16,11 +16,11 @@ function computeSignature(rawBody, verificationToken) {
     return `sha256=${(0, node_crypto_1.createHmac)('sha256', verificationToken).update(rawBody).digest('hex')}`;
 }
 /**
- * Sign a payload, for generating test webhook signatures.
+ * Sign a payload to generate 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 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
  *
@@ -35,18 +35,18 @@ function sign(body, verificationToken) {
 /**
  * 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.
+ * 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; `false` for any mismatch or malformed
- * input (never throws)
+ * @returns `true` if the signature is valid. Returns `false` for a mismatch or
+ * malformed input. This function never throws.
  *
  * @example
  * ```ts
@@ -74,6 +74,8 @@ function verifySignature(rawBody, signatureHeader, verificationToken) {
  *
  * const isValid = webhook.verifySignature(rawBody, req.headers['x-notion-signature'], verificationToken);
  * ```
+ *
+ * @category Helpers
  */
 exports.webhook = {
     sign,

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

@@ -1,13 +1,15 @@
-import { BaseModel } from './base.model';
+import { BaseModel, type TRUSTED } from './base.model';
 import { type NotionAsyncTask } from '../schemas';
 /**
- * Async Task model class with helper methods.
+ * AsyncTask model class with helper methods.
  *
- * Represents a long-running operation (e.g. an async markdown write) that must be
- * polled until it reaches a terminal status.
+ * 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);
+    constructor(data: NotionAsyncTask, trusted?: typeof TRUSTED);
     /**
      * Returns "async_task" - the object type.
      */
@@ -21,7 +23,7 @@ export declare class AsyncTask extends BaseModel<NotionAsyncTask> {
      */
     get status(): NotionAsyncTask['status'];
     /**
-     * Returns the URL that can be polled for task status.
+     * Returns the URL to poll for the task status.
      */
     get statusUrl(): string;
     /**

package/dist/models/asyncTask.model.js

@@ -4,14 +4,16 @@ exports.AsyncTask = void 0;
 const base_model_1 = require("./base.model");
 const schemas_1 = require("../schemas");
 /**
- * Async Task model class with helper methods.
+ * AsyncTask model class with helper methods.
  *
- * Represents a long-running operation (e.g. an async markdown write) that must be
- * polled until it reaches a terminal status.
+ * 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) {
-        super(data, schemas_1.asyncTaskSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.asyncTaskSchema, trusted);
     }
     /**
      * Returns "async_task" - the object type.
@@ -32,7 +34,7 @@ class AsyncTask extends base_model_1.BaseModel {
         return this.data.status;
     }
     /**
-     * Returns the URL that can be polled for task status.
+     * Returns the URL to poll for the task status.
      */
     get statusUrl() {
         return this.data.status_url;

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,48 +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',
-            'heading_4',
-            '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', 'heading_4'].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',
-            'heading_4',
-            'bulleted_list_item',
-            'numbered_list_item',
-            'to_do',
-            'toggle',
-            'quote',
-            'callout',
-            'synced_block',
-            'column',
-            'column_list',
-            'tab',
-            '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

@@ -1,16 +1,18 @@
-import { BaseModel } from './base.model';
+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);
+    constructor(data: NotionCustomEmoji, trusted?: typeof TRUSTED);
     /**
      * Returns "custom_emoji" - the object type.
      *
-     * Note: individual custom emoji list items have no `object` field of their own in
-     * the API response (only the paginated list wrapper does) -- this getter is
-     * synthetic, not sourced from the payload, to satisfy {@link BaseModel}'s contract.
+     * 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';
     /**

package/dist/models/customEmoji.model.js

@@ -5,17 +5,19 @@ 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) {
-        super(data, schemas_1.customEmojiSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.customEmojiSchema, trusted);
     }
     /**
      * Returns "custom_emoji" - the object type.
      *
-     * Note: individual custom emoji list items have no `object` field of their own in
-     * the API response (only the paginated list wrapper does) -- this getter is
-     * synthetic, not sourced from the payload, to satisfy {@link BaseModel}'s contract.
+     * 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';

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

@@ -1,12 +1,14 @@
-import { BaseModel } from './base.model';
+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.
      */

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.

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

@@ -1,10 +1,14 @@
-import { BaseModel } from './base.model';
+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.
      */

package/dist/models/database.model.js

@@ -5,10 +5,12 @@ const base_model_1 = require("./base.model");
 const schemas_1 = require("../schemas");
 /**
  * Database model class with helper methods.
+ *
+ * @category Databases & Data Sources
  */
 class Database extends base_model_1.BaseModel {
-    constructor(data) {
-        super(data, schemas_1.databaseSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.databaseSchema, trusted);
     }
     /**
      * Returns "database" - the object type.
@@ -32,7 +34,8 @@ class Database extends base_model_1.BaseModel {
      * Returns the created time as a Date object.
      */
     get createdTime() {
-        return new Date(this.data.created_time);
+        this.cachedCreatedTimeMs ??= new Date(this.data.created_time).getTime();
+        return new Date(this.cachedCreatedTimeMs);
     }
     /**
      * Returns the user who created the database.
@@ -44,7 +47,8 @@ class Database extends base_model_1.BaseModel {
      * Returns the last edited time as a Date object.
      */
     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);
     }
     /**
      * Returns the user who last edited the database.

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

@@ -1,10 +1,12 @@
-import { BaseModel } from './base.model';
+import { BaseModel, type TRUSTED } from './base.model';
 import { type NotionFileUpload } from '../schemas';
 /**
  * FileUpload model class with helper methods.
+ *
+ * @category File Uploads
  */
 export declare class FileUpload extends BaseModel<NotionFileUpload> {
-    constructor(data: NotionFileUpload);
+    constructor(data: NotionFileUpload, trusted?: typeof TRUSTED);
     /**
      * Returns "file_upload" - the object type.
      */
@@ -38,11 +40,11 @@ export declare class FileUpload extends BaseModel<NotionFileUpload> {
      */
     get contentLength(): number | null;
     /**
-     * Returns the upload URL for uploading the file.
+     * Returns the URL to upload the file.
      */
     get uploadUrl(): string;
     /**
-     * Returns the complete URL for finalizing the upload.
+     * Returns the URL to complete the upload.
      */
     get completeUrl(): string;
     /**

package/dist/models/fileUpload.model.js

@@ -5,10 +5,12 @@ const base_model_1 = require("./base.model");
 const schemas_1 = require("../schemas");
 /**
  * FileUpload model class with helper methods.
+ *
+ * @category File Uploads
  */
 class FileUpload extends base_model_1.BaseModel {
-    constructor(data) {
-        super(data, schemas_1.fileUploadSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.fileUploadSchema, trusted);
     }
     /**
      * Returns "file_upload" - the object type.
@@ -59,13 +61,13 @@ class FileUpload extends base_model_1.BaseModel {
         return this.data.content_length;
     }
     /**
-     * Returns the upload URL for uploading the file.
+     * Returns the URL to upload the file.
      */
     get uploadUrl() {
         return this.data.upload_url;
     }
     /**
-     * Returns the complete URL for finalizing the upload.
+     * Returns the URL to complete the upload.
      */
     get completeUrl() {
         return this.data.complete_url;

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

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