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

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

@@ -1,12 +1,14 @@
-import { BaseModel } from './base.model';
-import { type NotionDataSource, type NotionFile, type NotionIcon, type NotionParent, type NotionPropertiesObject, type NotionPropertyObject, type NotionRichText, type NotionUser } from '../schemas';
+import { BaseModel, type TRUSTED } from './base.model';
+import { type DatabaseType, 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.
      */
@@ -75,6 +77,11 @@ export declare class DataSource extends BaseModel<NotionDataSource> {
      * Returns whether the data source is in trash.
      */
     get inTrash(): boolean;
+    /**
+     * Returns the canonical database type this data source's parent database was built from,
+     * if any.
+     */
+    get databaseType(): DatabaseType | undefined;
     /**
      * Extracts the plain text title from the data source.
      */

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.
@@ -114,6 +116,13 @@ class DataSource extends base_model_1.BaseModel {
     get inTrash() {
         return this.data.in_trash;
     }
+    /**
+     * Returns the canonical database type this data source's parent database was built from,
+     * if any.
+     */
+    get databaseType() {
+        return this.data.database_type;
+    }
     /**
      * Extracts the plain text title from the data source.
      */

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

@@ -1,10 +1,14 @@
-import { BaseModel } from './base.model';
-import { type DataSourceRef, type NotionDatabase, type NotionFile, type NotionIcon, type NotionParent, type NotionRichText, type NotionUser } from '../schemas';
+import { BaseModel, type TRUSTED } from './base.model';
+import { type DatabaseType, 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.
      */
@@ -73,6 +77,10 @@ export declare class Database extends BaseModel<NotionDatabase> {
      * Returns the public URL if published, otherwise null.
      */
     get publicUrl(): string | null;
+    /**
+     * Returns the canonical database type this database was built from, if any.
+     */
+    get databaseType(): DatabaseType | undefined;
     /**
      * Extracts the plain text title from the database.
      */

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.
@@ -112,6 +116,12 @@ class Database extends base_model_1.BaseModel {
     get publicUrl() {
         return this.data.public_url;
     }
+    /**
+     * Returns the canonical database type this database was built from, if any.
+     */
+    get databaseType() {
+        return this.data.database_type;
+    }
     /**
      * Extracts the plain text title from 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;

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,10 +19,12 @@ 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;

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;
@@ -26,6 +28,11 @@ export declare class User extends BaseModel<NotionUser> {
      * Get email if this is a person user.
      */
     getEmail(): string | undefined;
+    /**
+     * Get the person's email verification status.
+     * Returns `undefined` when the user is not a person.
+     */
+    getEmailVerified(): boolean | undefined;
     /**
      * Get bot information if this is a bot user.
      */

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;
@@ -46,6 +48,16 @@ class User extends base_model_1.BaseModel {
         }
         return undefined;
     }
+    /**
+     * Get the person's email verification status.
+     * Returns `undefined` when the user is not a person.
+     */
+    getEmailVerified() {
+        if (this.isPerson()) {
+            return this.data.person.email_verified;
+        }
+        return undefined;
+    }
     /**
      * Get bot information if this is a bot user.
      */

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

@@ -1,13 +1,15 @@
-import { BaseModel } from './base.model';
+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.
  *
- * Views control how a database/data source's rows are displayed (table, board,
- * calendar, etc.).
+ * 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);
+    constructor(data: NotionView, trusted?: typeof TRUSTED);
     /**
      * Returns "view" - the object type.
      */
@@ -29,7 +31,7 @@ export declare class View extends BaseModel<NotionView> {
      */
     get name(): string;
     /**
-     * Returns the view type (table, board, calendar, etc.).
+     * Returns the view type, for example table, board, or calendar.
      */
     get type(): ViewType;
     /**
@@ -69,11 +71,11 @@ export declare class View extends BaseModel<NotionView> {
      */
     get url(): string;
     /**
-     * Returns the dashboard widget ID, if this view is a widget on a dashboard.
+     * Returns the widget ID, if a dashboard shows this view as a widget.
      */
     get dashboardViewId(): string | undefined;
     /**
-     * Returns whether this view is a widget view embedded in a dashboard.
+     * Returns whether a dashboard shows this view as a widget.
      */
     isWidgetView(): boolean;
 }

package/dist/models/view.model.js

@@ -6,12 +6,14 @@ 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.).
+ * 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) {
-        super(data, schemas_1.viewSchema);
+    constructor(data, trusted) {
+        super(data, schemas_1.viewSchema, trusted);
     }
     /**
      * Returns "view" - the object type.
@@ -44,7 +46,7 @@ class View extends base_model_1.BaseModel {
         return this.data.name;
     }
     /**
-     * Returns the view type (table, board, calendar, etc.).
+     * Returns the view type, for example table, board, or calendar.
      */
     get type() {
         return this.data.type;
@@ -104,13 +106,13 @@ class View extends base_model_1.BaseModel {
         return this.data.url;
     }
     /**
-     * Returns the dashboard widget ID, if this view is a widget on a dashboard.
+     * Returns the widget ID, if a dashboard shows this view as a widget.
      */
     get dashboardViewId() {
         return this.data.dashboard_view_id;
     }
     /**
-     * Returns whether this view is a widget view embedded in a dashboard.
+     * Returns whether a dashboard shows this view as a widget.
      */
     isWidgetView() {
         return this.data.dashboard_view_id !== undefined;

package/dist/notion.d.ts

@@ -1,7 +1,10 @@
 import { type NotionClientOptions } from './client';
 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
@@ -46,6 +49,8 @@ import { AsyncTasksAPI, BlocksAPI, CommentsAPI, CustomEmojisAPI, DatabasesAPI, D
  *
  * const emojis = await notion.customEmojis.list();
  * ```
+ *
+ * @category Client & Core
  */
 export declare class Notion {
     private readonly client;

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
@@ -49,6 +52,8 @@ const api_1 = require("./api");
  *
  * const emojis = await notion.customEmojis.list();
  * ```
+ *
+ * @category Client & Core
  */
 class Notion {
     constructor(options) {

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

@@ -8,9 +8,17 @@ import * as z from 'zod';
  *
  * 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;
@@ -39,4 +47,7 @@ export declare const asyncTaskSchema: z.ZodObject<{
         message: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * @category Async Tasks
+ */
 export type NotionAsyncTask = z.infer<typeof asyncTaskSchema>;

package/dist/schemas/asyncTask.schema.js

@@ -45,6 +45,8 @@ const shared_schema_1 = require("./shared.schema");
  *
  * Notion API reference:
  * https://developers.notion.com/reference/retrieve-async-task
+ *
+ * @category Async Tasks
  */
 exports.ASYNC_TASK_STATUSES = [
     'queued',
@@ -66,6 +68,9 @@ const asyncTaskErrorSchema = z.object({
     code: z.string().trim(),
     message: z.string().trim(),
 });
+/**
+ * @category Async Tasks
+ */
 exports.asyncTaskSchema = z.object({
     object: z.literal('async_task'),
     id: z.uuid(),

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

@@ -1,6 +1,8 @@
 import * as z from 'zod';
 /**
- * Position for inserting block children in the Append Block Children endpoint.
+ * Position to insert block children in the Append Block Children endpoint.
+ *
+ * @category Blocks
  */
 export declare const blockPositionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"after_block">;
@@ -12,7 +14,13 @@ export declare const blockPositionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"end">;
 }, z.core.$strip>], "type">;
+/**
+ * @category Blocks
+ */
 export type BlockPosition = z.infer<typeof blockPositionSchema>;
+/**
+ * @category Blocks
+ */
 export declare const blockSchema: z.ZodObject<{
     object: z.ZodLiteral<"block">;
     id: z.ZodUUID;
@@ -4177,4 +4185,7 @@ export declare const blockSchema: z.ZodObject<{
         }, z.core.$strip>;
     }, z.core.$strip>], "type">>;
 }, z.core.$strip>;
+/**
+ * @category Blocks
+ */
 export type NotionBlock = z.infer<typeof blockSchema>;

package/dist/schemas/block.schema.js

@@ -58,7 +58,9 @@ const getChildrenSchema = () => {
     return childrenSchema;
 };
 /**
- * Position for inserting block children in the Append Block Children endpoint.
+ * Position to insert block children in the Append Block Children endpoint.
+ *
+ * @category Blocks
  */
 exports.blockPositionSchema = z.discriminatedUnion('type', [
     z.object({ type: z.literal('after_block'), after_block: z.object({ id: z.uuid() }) }),
@@ -73,6 +75,9 @@ const headingsObjectSchema = z.object({
         return getChildrenSchema();
     },
 });
+/**
+ * @category Blocks
+ */
 exports.blockSchema = z.object({
     object: z.literal('block'),
     id: z.uuid(),

package/dist/schemas/codeLanguages.d.ts

@@ -1,3 +1,9 @@
-/** All programming languages supported by Notion code blocks. */
+/** All programming languages supported by Notion code blocks.
+ *
+ * @category Blocks
+ */
 export declare const CODE_BLOCK_LANGUAGES: readonly ["abap", "arduino", "bash", "basic", "c", "clojure", "coffeescript", "c++", "c#", "css", "dart", "diff", "docker", "elixir", "elm", "erlang", "flow", "fortran", "f#", "gherkin", "glsl", "go", "graphql", "groovy", "haskell", "html", "java", "javascript", "json", "julia", "kotlin", "latex", "less", "lisp", "livescript", "lua", "makefile", "markdown", "markup", "matlab", "mermaid", "nix", "objective-c", "ocaml", "pascal", "perl", "php", "plain text", "powershell", "prolog", "protobuf", "python", "r", "reason", "ruby", "rust", "sass", "scala", "scheme", "scss", "shell", "sql", "swift", "typescript", "vb.net", "verilog", "vhdl", "visual basic", "webassembly", "xml", "yaml", "java/c/c++/c#"];
+/**
+ * @category Blocks
+ */
 export type CodeBlockLanguage = (typeof CODE_BLOCK_LANGUAGES)[number];

package/dist/schemas/codeLanguages.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CODE_BLOCK_LANGUAGES = void 0;
-/** All programming languages supported by Notion code blocks. */
+/** All programming languages supported by Notion code blocks.
+ *
+ * @category Blocks
+ */
 exports.CODE_BLOCK_LANGUAGES = [
     'abap',
     'arduino',

package/dist/schemas/colors.d.ts

@@ -1,3 +1,9 @@
-/** All color options supported by Notion. */
+/** All color options supported by Notion.
+ *
+ * @category Shared Types
+ */
 export declare const NOTION_COLORS: readonly ["blue", "blue_background", "brown", "brown_background", "default", "gray", "gray_background", "green", "green_background", "orange", "orange_background", "pink", "pink_background", "purple", "purple_background", "red", "red_background", "yellow", "yellow_background"];
+/**
+ * @category Shared Types
+ */
 export type NotionColor = (typeof NOTION_COLORS)[number];

package/dist/schemas/colors.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NOTION_COLORS = void 0;
-/** All color options supported by Notion. */
+/** All color options supported by Notion.
+ *
+ * @category Shared Types
+ */
 exports.NOTION_COLORS = [
     'blue',
     'blue_background',

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

@@ -1,5 +1,8 @@
 import * as z from 'zod';
-/** Comment attachment schema. */
+/** Comment attachment schema.
+ *
+ * @category Comments
+ */
 export declare const commentAttachmentSchema: z.ZodObject<{
     category: z.ZodEnum<{
         file: "file";
@@ -13,8 +16,14 @@ export declare const commentAttachmentSchema: z.ZodObject<{
         expiry_time: z.ZodUnion<readonly [z.ZodISODateTime, z.ZodISODate]>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/**
+ * @category Comments
+ */
 export type CommentAttachment = z.infer<typeof commentAttachmentSchema>;
-/** Comment display name schema (user or custom). */
+/** Comment display name schema (user or custom).
+ *
+ * @category Comments
+ */
 export declare const commentDisplayNameSchema: z.ZodUnion<readonly [z.ZodObject<{
     type: z.ZodLiteral<"user">;
     resolved_name: z.ZodString;
@@ -22,7 +31,13 @@ export declare const commentDisplayNameSchema: z.ZodUnion<readonly [z.ZodObject<
     type: z.ZodLiteral<"custom">;
     resolved_name: z.ZodString;
 }, z.core.$strip>]>;
+/**
+ * @category Comments
+ */
 export type CommentDisplayName = z.infer<typeof commentDisplayNameSchema>;
+/**
+ * @category Comments
+ */
 export declare const commentSchema: z.ZodObject<{
     object: z.ZodLiteral<"comment">;
     id: z.ZodUUID;
@@ -279,4 +294,7 @@ export declare const commentSchema: z.ZodObject<{
         resolved_name: z.ZodString;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;
+/**
+ * @category Comments
+ */
 export type NotionComment = z.infer<typeof commentSchema>;