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

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

@@ -255,6 +255,8 @@ declare function files(entries: FileEntry[]): {
  *   },
  * });
  * ```
+ *
+ * @category Helpers
  */
 export declare const prop: {
     title: typeof title;

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');
@@ -278,6 +278,8 @@ function files(entries) {
  *   },
  * });
  * ```
+ *
+ * @category Helpers
  */
 exports.prop = {
     title,

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

@@ -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';