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

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.
@@ -65,7 +69,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 +104,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/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/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

@@ -1,15 +1,21 @@
-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;
     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

@@ -5,10 +5,12 @@ const base_model_1 = require("./base.model");
 const schemas_1 = require("../schemas");
 /**
  * Page model wrapping a validated Notion page object with helper methods.
+ *
+ * @category Pages
  */
 class Page extends base_model_1.BaseModel {
-    constructor(data) {
-        super(data, schemas_1.pageSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.pageSchema, trusted);
     }
     get object() {
         return this.data.object;
@@ -17,14 +19,22 @@ class Page extends base_model_1.BaseModel {
         return this.data.id;
     }
     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;
     }
+    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/richText.model.d.ts

@@ -1,6 +1,8 @@
 import { type NotionRichText } from '../schemas';
 /**
- * RichText helper class for working with Notion rich text arrays.
+ * RichText helper class to work with Notion rich text arrays.
+ *
+ * @category Rich Text
  */
 export declare class RichText {
     private readonly data;

package/dist/models/richText.model.js

@@ -3,7 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RichText = void 0;
 const schemas_1 = require("../schemas");
 /**
- * RichText helper class for working with Notion rich text arrays.
+ * RichText helper class to work with Notion rich text arrays.
+ *
+ * @category Rich Text
  */
 class RichText {
     constructor(data) {

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

@@ -1,10 +1,12 @@
-import { BaseModel } from './base.model';
+import { BaseModel, type TRUSTED } from './base.model';
 import { type BotUser, type NotionUser, type PersonUser } from '../schemas';
 /**
  * User model wrapping a validated Notion user object with helper methods.
+ *
+ * @category Users
  */
 export declare class User extends BaseModel<NotionUser> {
-    constructor(data: unknown);
+    constructor(data: unknown, trusted?: typeof TRUSTED);
     get object(): string;
     get id(): string;
     get type(): 'person' | 'bot' | undefined;

package/dist/models/user.model.js

@@ -5,10 +5,12 @@ const base_model_1 = require("./base.model");
 const schemas_1 = require("../schemas");
 /**
  * User model wrapping a validated Notion user object with helper methods.
+ *
+ * @category Users
  */
 class User extends base_model_1.BaseModel {
-    constructor(data) {
-        super(data, schemas_1.userSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.userSchema, trusted);
     }
     get object() {
         return this.data.object;

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

@@ -0,0 +1,81 @@
+import { BaseModel, type TRUSTED } from './base.model';
+import { type NotionParent, type NotionUser, type NotionView, type ViewConfiguration, type ViewType } from '../schemas';
+/**
+ * View model class with helper methods.
+ *
+ * A view controls how a database or data source shows its rows, for example as a
+ * table, board, or calendar.
+ *
+ * @category Views
+ */
+export declare class View extends BaseModel<NotionView> {
+    constructor(data: NotionView, trusted?: typeof TRUSTED);
+    /**
+     * 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, for example table, board, or calendar.
+     */
+    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 widget ID, if a dashboard shows this view as a widget.
+     */
+    get dashboardViewId(): string | undefined;
+    /**
+     * Returns whether a dashboard shows this view as a widget.
+     */
+    isWidgetView(): boolean;
+}

package/dist/models/view.model.js

@@ -0,0 +1,121 @@
+"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.
+ *
+ * A view controls how a database or data source shows its rows, for example as a
+ * table, board, or calendar.
+ *
+ * @category Views
+ */
+class View extends base_model_1.BaseModel {
+    constructor(data, trusted) {
+        super(data, schemas_1.viewSchema, trusted);
+    }
+    /**
+     * 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, for example table, board, or calendar.
+     */
+    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 widget ID, if a dashboard shows this view as a widget.
+     */
+    get dashboardViewId() {
+        return this.data.dashboard_view_id;
+    }
+    /**
+     * Returns whether a dashboard shows this view as a widget.
+     */
+    isWidgetView() {
+        return this.data.dashboard_view_id !== undefined;
+    }
+}
+exports.View = View;

package/dist/notion.d.ts

@@ -1,7 +1,10 @@
 import { type NotionClientOptions } from './client';
-import { BlocksAPI, CommentsAPI, DatabasesAPI, DataSourcesAPI, FileUploadsAPI, PagesAPI, SearchAPI, UsersAPI } from './api';
+import { AsyncTasksAPI, BlocksAPI, CommentsAPI, CustomEmojisAPI, DatabasesAPI, DataSourcesAPI, FileUploadsAPI, PagesAPI, SearchAPI, UsersAPI, ViewsAPI } from './api';
 /**
- * Main Notion SDK class.
+ * The public entry point for the SDK.
+ *
+ * Create one `Notion` instance, then call its API properties, such as
+ * `pages` or `blocks`, to reach Notion endpoints.
  *
  * @example
  * ```typescript
@@ -32,25 +35,46 @@ import { BlocksAPI, CommentsAPI, DatabasesAPI, DataSourcesAPI, FileUploadsAPI, P
  * await notion.comments.create({ parent: { page_id: 'page-id' }, rich_text: [...] });
  *
  * const fileUpload = await notion.fileUploads.uploadFile('image.png', buffer, 'image/png');
+ *
+ * const views = await notion.views.list({ data_source_id: 'data-source-id' });
+ * const queryResult = await notion.views.queries.create(views.results[0].id);
+ *
+ * const markdown = await notion.pages.getMarkdown('page-id');
+ * const task = await notion.pages.updateMarkdown('page-id', {
+ *   type: 'replace_content',
+ *   new_str: 'Updated content',
+ *   allow_async: true,
+ * });
+ * await notion.asyncTasks.poll(task.id);
+ *
+ * const emojis = await notion.customEmojis.list();
  * ```
+ *
+ * @category Client & Core
  */
 export declare class Notion {
     private readonly client;
-    /** Pages API for working with Notion pages */
-    readonly pages: PagesAPI;
+    /** Async Tasks API for polling long-running Notion operations */
+    readonly asyncTasks: AsyncTasksAPI;
     /** Blocks API for working with Notion blocks */
     readonly blocks: BlocksAPI;
+    /** Comments API for working with Notion comments */
+    readonly comments: CommentsAPI;
+    /** Custom Emojis API for listing workspace custom emojis */
+    readonly customEmojis: CustomEmojisAPI;
     /** Databases API for working with Notion databases */
     readonly databases: DatabasesAPI;
     /** Data Sources API for working with Notion data sources */
     readonly dataSources: DataSourcesAPI;
+    /** FileUploads API for uploading files to Notion */
+    readonly fileUploads: FileUploadsAPI;
+    /** Pages API for working with Notion pages */
+    readonly pages: PagesAPI;
     /** Search API for searching across the workspace */
     readonly search: SearchAPI;
     /** Users API for working with Notion users */
     readonly users: UsersAPI;
-    /** Comments API for working with Notion comments */
-    readonly comments: CommentsAPI;
-    /** FileUploads API for uploading files to Notion */
-    readonly fileUploads: FileUploadsAPI;
+    /** Views API for working with Notion database/data source views */
+    readonly views: ViewsAPI;
     constructor(options: NotionClientOptions);
 }

package/dist/notion.js

@@ -4,7 +4,10 @@ exports.Notion = void 0;
 const client_1 = require("./client");
 const api_1 = require("./api");
 /**
- * Main Notion SDK class.
+ * The public entry point for the SDK.
+ *
+ * Create one `Notion` instance, then call its API properties, such as
+ * `pages` or `blocks`, to reach Notion endpoints.
  *
  * @example
  * ```typescript
@@ -35,19 +38,37 @@ const api_1 = require("./api");
  * await notion.comments.create({ parent: { page_id: 'page-id' }, rich_text: [...] });
  *
  * const fileUpload = await notion.fileUploads.uploadFile('image.png', buffer, 'image/png');
+ *
+ * const views = await notion.views.list({ data_source_id: 'data-source-id' });
+ * const queryResult = await notion.views.queries.create(views.results[0].id);
+ *
+ * const markdown = await notion.pages.getMarkdown('page-id');
+ * const task = await notion.pages.updateMarkdown('page-id', {
+ *   type: 'replace_content',
+ *   new_str: 'Updated content',
+ *   allow_async: true,
+ * });
+ * await notion.asyncTasks.poll(task.id);
+ *
+ * const emojis = await notion.customEmojis.list();
  * ```
+ *
+ * @category Client & Core
  */
 class Notion {
     constructor(options) {
         this.client = new client_1.NotionClient(options);
-        this.pages = new api_1.PagesAPI(this.client);
+        this.asyncTasks = new api_1.AsyncTasksAPI(this.client);
         this.blocks = new api_1.BlocksAPI(this.client);
+        this.comments = new api_1.CommentsAPI(this.client);
+        this.customEmojis = new api_1.CustomEmojisAPI(this.client);
         this.databases = new api_1.DatabasesAPI(this.client);
         this.dataSources = new api_1.DataSourcesAPI(this.client);
+        this.fileUploads = new api_1.FileUploadsAPI(this.client);
+        this.pages = new api_1.PagesAPI(this.client);
         this.search = new api_1.SearchAPI(this.client);
         this.users = new api_1.UsersAPI(this.client);
-        this.comments = new api_1.CommentsAPI(this.client);
-        this.fileUploads = new api_1.FileUploadsAPI(this.client);
+        this.views = new api_1.ViewsAPI(this.client);
     }
 }
 exports.Notion = Notion;

package/dist/schemas/asyncTask.schema.d.ts

@@ -0,0 +1,53 @@
+import * as z from 'zod';
+/**
+ * Async task object schema.
+ *
+ * Long-running operations (e.g. markdown writes with `allow_async: true`) return an
+ * async task handle instead of completing synchronously. Poll `GET /v1/async_tasks/{id}`
+ * until the task reaches a terminal status.
+ *
+ * Notion API reference:
+ * https://developers.notion.com/reference/retrieve-async-task
+ *
+ * @category Async Tasks
+ */
+export declare const ASYNC_TASK_STATUSES: readonly ["queued", "running", "retrying", "succeeded", "failed"];
+/**
+ * @category Async Tasks
+ */
+export type AsyncTaskStatus = (typeof ASYNC_TASK_STATUSES)[number];
+/**
+ * @category Async Tasks
+ */
+export declare const asyncTaskSchema: z.ZodObject<{
+    object: z.ZodLiteral<"async_task">;
+    id: z.ZodUUID;
+    status: z.ZodEnum<{
+        queued: "queued";
+        running: "running";
+        retrying: "retrying";
+        succeeded: "succeeded";
+        failed: "failed";
+    }>;
+    status_url: z.ZodURL;
+    created_time: z.ZodUnion<readonly [z.ZodISODateTime, z.ZodISODate]>;
+    operation: z.ZodObject<{
+        surface: z.ZodEnum<{
+            rest: "rest";
+            mcp: "mcp";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    poll_after_seconds: z.ZodOptional<z.ZodNumber>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        object: z.ZodLiteral<"error">;
+        status: z.ZodNumber;
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * @category Async Tasks
+ */
+export type NotionAsyncTask = z.infer<typeof asyncTaskSchema>;