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

package/dist/helpers/webhook.helpers.js

@@ -0,0 +1,81 @@
+"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, 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 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, 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);
+ * ```
+ */
+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 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);
+ * ```
+ */
+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);
+ * ```
+ */
+exports.webhook = {
+    sign,
+    verifySignature,
+};

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

@@ -0,0 +1,59 @@
+import { BaseModel } from './base.model';
+import { type NotionAsyncTask } from '../schemas';
+/**
+ * Async Task 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.
+ */
+export declare class AsyncTask extends BaseModel<NotionAsyncTask> {
+    constructor(data: NotionAsyncTask);
+    /**
+     * 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 that can be polled for 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,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncTask = void 0;
+const base_model_1 = require("./base.model");
+const schemas_1 = require("../schemas");
+/**
+ * Async Task 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.
+ */
+class AsyncTask extends base_model_1.BaseModel {
+    constructor(data) {
+        super(data, schemas_1.asyncTaskSchema);
+    }
+    /**
+     * 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 that can be polled for 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/block.model.js

@@ -40,6 +40,7 @@ class Block extends base_model_1.BaseModel {
             'heading_1',
             'heading_2',
             'heading_3',
+            'heading_4',
             'quote',
             'callout',
             'bulleted_list_item',
@@ -52,7 +53,7 @@ class Block extends base_model_1.BaseModel {
      * Check if this is a heading block.
      */
     isHeading() {
-        return ['heading_1', 'heading_2', 'heading_3'].includes(this.data.type);
+        return ['heading_1', 'heading_2', 'heading_3', 'heading_4'].includes(this.data.type);
     }
     /**
      * Check if this block can contain children.
@@ -63,6 +64,7 @@ class Block extends base_model_1.BaseModel {
             'heading_1',
             'heading_2',
             'heading_3',
+            'heading_4',
             'bulleted_list_item',
             'numbered_list_item',
             'to_do',
@@ -72,6 +74,7 @@ class Block extends base_model_1.BaseModel {
             'synced_block',
             'column',
             'column_list',
+            'tab',
             'table',
         ].includes(this.data.type);
     }

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

@@ -0,0 +1,28 @@
+import { BaseModel } from './base.model';
+import { type NotionCustomEmoji } from '../schemas';
+/**
+ * Custom Emoji model class with helper methods.
+ */
+export declare class CustomEmoji extends BaseModel<NotionCustomEmoji> {
+    constructor(data: NotionCustomEmoji);
+    /**
+     * 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.
+     */
+    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,42 @@
+"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.
+ */
+class CustomEmoji extends base_model_1.BaseModel {
+    constructor(data) {
+        super(data, schemas_1.customEmojiSchema);
+    }
+    /**
+     * 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.
+     */
+    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,5 +1,5 @@
 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 { 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.
  *
@@ -52,9 +52,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

@@ -79,7 +79,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,5 +1,5 @@
 import { BaseModel } from './base.model';
-import { type DataSourceRef, type NotionDatabase, type NotionEmoji, type NotionFile, type NotionParent, type NotionRichText, type NotionUser } from '../schemas';
+import { type DataSourceRef, type NotionDatabase, type NotionFile, type NotionIcon, type NotionParent, type NotionRichText, type NotionUser } from '../schemas';
 /**
  * Database model class with helper methods.
  */
@@ -42,9 +42,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 +65,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.
      */

package/dist/models/database.model.js

@@ -65,7 +65,7 @@ class Database extends base_model_1.BaseModel {
         return this.data.description;
     }
     /**
-     * Returns the database icon (file or emoji).
+     * Returns the database icon (file, emoji, native icon, or custom emoji).
      */
     get icon() {
         return this.data.icon;
@@ -100,6 +100,12 @@ class Database extends base_model_1.BaseModel {
     get isInline() {
         return this.data.is_inline;
     }
+    /**
+     * Returns whether the database is locked from editing.
+     */
+    get isLocked() {
+        return this.data.is_locked ?? false;
+    }
     /**
      * Returns the public URL if published, otherwise null.
      */

package/dist/models/index.d.ts

@@ -1,9 +1,12 @@
+export { AsyncTask } from './asyncTask.model';
 export { BaseModel } from './base.model';
 export { Block } from './block.model';
 export { Comment } from './comment.model';
+export { CustomEmoji } from './customEmoji.model';
 export { Database } from './database.model';
 export { DataSource } from './dataSource.model';
 export { FileUpload } from './fileUpload.model';
 export { Page } from './page.model';
 export { RichText } from './richText.model';
 export { User } from './user.model';
+export { View } from './view.model';

package/dist/models/index.js

@@ -1,12 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.User = exports.RichText = exports.Page = exports.FileUpload = exports.DataSource = exports.Database = exports.Comment = exports.Block = exports.BaseModel = void 0;
+exports.View = exports.User = exports.RichText = exports.Page = exports.FileUpload = exports.DataSource = exports.Database = exports.CustomEmoji = exports.Comment = exports.Block = exports.BaseModel = exports.AsyncTask = void 0;
+var asyncTask_model_1 = require("./asyncTask.model");
+Object.defineProperty(exports, "AsyncTask", { enumerable: true, get: function () { return asyncTask_model_1.AsyncTask; } });
 var base_model_1 = require("./base.model");
 Object.defineProperty(exports, "BaseModel", { enumerable: true, get: function () { return base_model_1.BaseModel; } });
 var block_model_1 = require("./block.model");
 Object.defineProperty(exports, "Block", { enumerable: true, get: function () { return block_model_1.Block; } });
 var comment_model_1 = require("./comment.model");
 Object.defineProperty(exports, "Comment", { enumerable: true, get: function () { return comment_model_1.Comment; } });
+var customEmoji_model_1 = require("./customEmoji.model");
+Object.defineProperty(exports, "CustomEmoji", { enumerable: true, get: function () { return customEmoji_model_1.CustomEmoji; } });
 var database_model_1 = require("./database.model");
 Object.defineProperty(exports, "Database", { enumerable: true, get: function () { return database_model_1.Database; } });
 var dataSource_model_1 = require("./dataSource.model");
@@ -19,3 +23,5 @@ var richText_model_1 = require("./richText.model");
 Object.defineProperty(exports, "RichText", { enumerable: true, get: function () { return richText_model_1.RichText; } });
 var user_model_1 = require("./user.model");
 Object.defineProperty(exports, "User", { enumerable: true, get: function () { return user_model_1.User; } });
+var view_model_1 = require("./view.model");
+Object.defineProperty(exports, "View", { enumerable: true, get: function () { return view_model_1.View; } });

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

@@ -10,6 +10,8 @@ export declare class Page extends BaseModel<NotionPage> {
     get createdTime(): Date;
     get lastEditedTime(): Date;
     get inTrash(): boolean;
+    get isArchived(): boolean;
+    get isLocked(): boolean;
     get url(): string;
     get publicUrl(): string | null;
     get properties(): Record<string, NotionPageProperties>;

package/dist/models/page.model.js

@@ -25,6 +25,12 @@ class Page extends base_model_1.BaseModel {
     get inTrash() {
         return this.data.in_trash;
     }
+    get isArchived() {
+        return this.data.is_archived ?? false;
+    }
+    get isLocked() {
+        return this.data.is_locked ?? false;
+    }
     get url() {
         return this.data.url;
     }

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

@@ -0,0 +1,79 @@
+import { BaseModel } from './base.model';
+import { type NotionParent, type NotionUser, type NotionView, type ViewConfiguration, type ViewType } from '../schemas';
+/**
+ * View model class with helper methods.
+ *
+ * Views control how a database/data source's rows are displayed (table, board,
+ * calendar, etc.).
+ */
+export declare class View extends BaseModel<NotionView> {
+    constructor(data: NotionView);
+    /**
+     * Returns "view" - the object type.
+     */
+    get object(): 'view';
+    /**
+     * Returns the view ID.
+     */
+    get id(): string;
+    /**
+     * Returns the parent object (database reference).
+     */
+    get parent(): NotionParent;
+    /**
+     * Returns the data source ID this view belongs to, or null for dashboard views.
+     */
+    get dataSourceId(): string | null;
+    /**
+     * Returns the view name.
+     */
+    get name(): string;
+    /**
+     * Returns the view type (table, board, calendar, etc.).
+     */
+    get type(): ViewType;
+    /**
+     * Returns the view's filter, if any.
+     */
+    get filter(): Record<string, unknown> | null | undefined;
+    /**
+     * Returns the view's sorts, if any.
+     */
+    get sorts(): Record<string, unknown>[] | null | undefined;
+    /**
+     * Returns the view's quick filters, if any.
+     */
+    get quickFilters(): Record<string, unknown> | null | undefined;
+    /**
+     * Returns the view's per-layout configuration, if any.
+     */
+    get configuration(): ViewConfiguration | undefined;
+    /**
+     * Returns the created time as a Date object.
+     */
+    get createdTime(): Date;
+    /**
+     * Returns the last edited time as a Date object.
+     */
+    get lastEditedTime(): Date;
+    /**
+     * Returns the user who created the view.
+     */
+    get createdBy(): NotionUser;
+    /**
+     * Returns the user who last edited the view.
+     */
+    get lastEditedBy(): NotionUser;
+    /**
+     * Returns the Notion URL of the view.
+     */
+    get url(): string;
+    /**
+     * Returns the dashboard widget ID, if this view is a widget on a dashboard.
+     */
+    get dashboardViewId(): string | undefined;
+    /**
+     * Returns whether this view is a widget view embedded in a dashboard.
+     */
+    isWidgetView(): boolean;
+}

package/dist/models/view.model.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.View = void 0;
+const base_model_1 = require("./base.model");
+const schemas_1 = require("../schemas");
+/**
+ * View model class with helper methods.
+ *
+ * Views control how a database/data source's rows are displayed (table, board,
+ * calendar, etc.).
+ */
+class View extends base_model_1.BaseModel {
+    constructor(data) {
+        super(data, schemas_1.viewSchema);
+    }
+    /**
+     * Returns "view" - the object type.
+     */
+    get object() {
+        return this.data.object;
+    }
+    /**
+     * Returns the view ID.
+     */
+    get id() {
+        return this.data.id;
+    }
+    /**
+     * Returns the parent object (database reference).
+     */
+    get parent() {
+        return this.data.parent;
+    }
+    /**
+     * Returns the data source ID this view belongs to, or null for dashboard views.
+     */
+    get dataSourceId() {
+        return this.data.data_source_id;
+    }
+    /**
+     * Returns the view name.
+     */
+    get name() {
+        return this.data.name;
+    }
+    /**
+     * Returns the view type (table, board, calendar, etc.).
+     */
+    get type() {
+        return this.data.type;
+    }
+    /**
+     * Returns the view's filter, if any.
+     */
+    get filter() {
+        return this.data.filter;
+    }
+    /**
+     * Returns the view's sorts, if any.
+     */
+    get sorts() {
+        return this.data.sorts;
+    }
+    /**
+     * Returns the view's quick filters, if any.
+     */
+    get quickFilters() {
+        return this.data.quick_filters;
+    }
+    /**
+     * Returns the view's per-layout configuration, if any.
+     */
+    get configuration() {
+        return this.data.configuration;
+    }
+    /**
+     * Returns the created time as a Date object.
+     */
+    get createdTime() {
+        return new Date(this.data.created_time);
+    }
+    /**
+     * Returns the last edited time as a Date object.
+     */
+    get lastEditedTime() {
+        return new Date(this.data.last_edited_time);
+    }
+    /**
+     * Returns the user who created the view.
+     */
+    get createdBy() {
+        return this.data.created_by;
+    }
+    /**
+     * Returns the user who last edited the view.
+     */
+    get lastEditedBy() {
+        return this.data.last_edited_by;
+    }
+    /**
+     * Returns the Notion URL of the view.
+     */
+    get url() {
+        return this.data.url;
+    }
+    /**
+     * Returns the dashboard widget ID, if this view is a widget on a dashboard.
+     */
+    get dashboardViewId() {
+        return this.data.dashboard_view_id;
+    }
+    /**
+     * Returns whether this view is a widget view embedded in a dashboard.
+     */
+    isWidgetView() {
+        return this.data.dashboard_view_id !== undefined;
+    }
+}
+exports.View = View;