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

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;

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

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

package/dist/schemas/comment.schema.js

@@ -53,12 +53,18 @@ const commentAttachmentFileSchema = z.object({
     url: z.url(),
     expiry_time: shared_schema_1.notionDateStringSchema,
 });
-/** Comment attachment schema. */
+/** Comment attachment schema.
+ *
+ * @category Comments
+ */
 exports.commentAttachmentSchema = z.object({
     category: z.enum(['image', 'video', 'file', 'audio', 'pdf']),
     file: commentAttachmentFileSchema,
 });
-/** Comment display name schema (user or custom). */
+/** Comment display name schema (user or custom).
+ *
+ * @category Comments
+ */
 exports.commentDisplayNameSchema = z.union([
     z.object({
         type: z.literal('user'),
@@ -69,6 +75,9 @@ exports.commentDisplayNameSchema = z.union([
         resolved_name: z.string().trim(),
     }),
 ]);
+/**
+ * @category Comments
+ */
 exports.commentSchema = z.object({
     object: z.literal('comment'),
     id: z.uuid(),

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

@@ -4,10 +4,15 @@ import * as z from 'zod';
  *
  * Notion API reference:
  * https://developers.notion.com/reference/list-custom-emojis
+ *
+ * @category Custom Emoji & Icons
  */
 export declare const customEmojiSchema: z.ZodObject<{
     id: z.ZodUUID;
     name: z.ZodString;
     url: z.ZodURL;
 }, z.core.$strip>;
+/**
+ * @category Custom Emoji & Icons
+ */
 export type NotionCustomEmoji = z.infer<typeof customEmojiSchema>;

package/dist/schemas/customEmoji.schema.js

@@ -40,6 +40,8 @@ const z = __importStar(require("zod"));
  *
  * Notion API reference:
  * https://developers.notion.com/reference/list-custom-emojis
+ *
+ * @category Custom Emoji & Icons
  */
 exports.customEmojiSchema = z.object({
     id: z.uuid(),

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

@@ -7,6 +7,8 @@ import * as z from 'zod';
  *
  * Notion API reference:
  * https://developers.notion.com/reference/data-source
+ *
+ * @category Databases & Data Sources
  */
 export declare const dataSourceSchema: z.ZodObject<{
     object: z.ZodLiteral<"data_source">;
@@ -821,21 +823,32 @@ export declare const dataSourceSchema: z.ZodObject<{
     is_inline: z.ZodBoolean;
     in_trash: z.ZodBoolean;
 }, z.core.$strip>;
+/**
+ * @category Databases & Data Sources
+ */
 export type NotionDataSource = z.infer<typeof dataSourceSchema>;
 /**
- * A single data source template reference, as returned by the
- * List data source templates endpoint.
+ * A single data source template reference. The List data source templates endpoint
+ * returns an array of these.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/list-data-source-templates
+ *
+ * @category Databases & Data Sources
  */
 export declare const dataSourceTemplateSchema: z.ZodObject<{
     id: z.ZodUUID;
     name: z.ZodString;
     is_default: z.ZodBoolean;
 }, z.core.$strip>;
+/**
+ * @category Databases & Data Sources
+ */
 export type DataSourceTemplate = z.infer<typeof dataSourceTemplateSchema>;
-/** Response shape of the List data source templates endpoint. */
+/** Response shape of the List data source templates endpoint.
+ *
+ * @category Databases & Data Sources
+ */
 export declare const dataSourceTemplateListSchema: z.ZodObject<{
     templates: z.ZodArray<z.ZodObject<{
         id: z.ZodUUID;
@@ -845,4 +858,7 @@ export declare const dataSourceTemplateListSchema: z.ZodObject<{
     has_more: z.ZodBoolean;
     next_cursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * @category Databases & Data Sources
+ */
 export type DataSourceTemplateList = z.infer<typeof dataSourceTemplateListSchema>;

package/dist/schemas/dataSource.schema.js

@@ -50,6 +50,8 @@ const propertyObjects_schema_1 = require("./propertyObjects.schema");
  *
  * Notion API reference:
  * https://developers.notion.com/reference/data-source
+ *
+ * @category Databases & Data Sources
  */
 exports.dataSourceSchema = z.object({
     /** Always "data_source" */
@@ -62,11 +64,11 @@ exports.dataSourceSchema = z.object({
     parent: parent_schema_1.parentSchema,
     /** Information about the database's parent (the data source's grandparent) */
     database_parent: parent_schema_1.parentSchema,
-    /** Date and time when this data source was created (ISO 8601) */
+    /** Creation date and time for this data source, in ISO 8601 format */
     created_time: shared_schema_1.notionDateStringSchema,
     /** User who created the data source */
     created_by: user_schema_1.userSchema,
-    /** Date and time when this data source was updated (ISO 8601) */
+    /** Last edited date and time for this data source, in ISO 8601 format */
     last_edited_time: shared_schema_1.notionDateStringSchema,
     /** User who last edited the data source */
     last_edited_by: user_schema_1.userSchema,
@@ -88,18 +90,23 @@ exports.dataSourceSchema = z.object({
     in_trash: z.boolean(),
 });
 /**
- * A single data source template reference, as returned by the
- * List data source templates endpoint.
+ * A single data source template reference. The List data source templates endpoint
+ * returns an array of these.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/list-data-source-templates
+ *
+ * @category Databases & Data Sources
  */
 exports.dataSourceTemplateSchema = z.object({
     id: z.uuid(),
     name: z.string().trim(),
     is_default: z.boolean(),
 });
-/** Response shape of the List data source templates endpoint. */
+/** Response shape of the List data source templates endpoint.
+ *
+ * @category Databases & Data Sources
+ */
 exports.dataSourceTemplateListSchema = z.object({
     templates: z.array(exports.dataSourceTemplateSchema),
     has_more: z.boolean(),

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

@@ -8,12 +8,21 @@ import * as z from 'zod';
  * Notion API reference:
  * https://developers.notion.com/reference/database
  */
-/** Data source reference with id and name. */
+/** Data source reference with id and name.
+ *
+ * @category Databases & Data Sources
+ */
 export declare const dataSourceRefSchema: z.ZodObject<{
     id: z.ZodUUID;
     name: z.ZodString;
 }, z.core.$strip>;
+/**
+ * @category Databases & Data Sources
+ */
 export type DataSourceRef = z.infer<typeof dataSourceRefSchema>;
+/**
+ * @category Databases & Data Sources
+ */
 export declare const databaseSchema: z.ZodObject<{
     object: z.ZodLiteral<"database">;
     id: z.ZodUUID;
@@ -528,4 +537,7 @@ export declare const databaseSchema: z.ZodObject<{
     is_locked: z.ZodOptional<z.ZodBoolean>;
     public_url: z.ZodNullable<z.ZodURL>;
 }, z.core.$strip>;
+/**
+ * @category Databases & Data Sources
+ */
 export type NotionDatabase = z.infer<typeof databaseSchema>;

package/dist/schemas/database.schema.js

@@ -50,11 +50,17 @@ const user_schema_1 = require("./user.schema");
  * Notion API reference:
  * https://developers.notion.com/reference/database
  */
-/** Data source reference with id and name. */
+/** Data source reference with id and name.
+ *
+ * @category Databases & Data Sources
+ */
 exports.dataSourceRefSchema = z.object({
     id: z.uuid(),
     name: z.string().trim(),
 });
+/**
+ * @category Databases & Data Sources
+ */
 exports.databaseSchema = z.object({
     object: z.literal('database'),
     id: z.uuid(),

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

@@ -2,14 +2,19 @@ import * as z from 'zod';
 /**
  * Notion emoji object schema.
  *
- * Emojis can be used as icons for pages, databases, and other objects.
- * Contains the emoji character as a string.
+ * You can use emojis as icons for pages, databases, and other objects.
+ * This schema stores the emoji character as a string.
  *
  * Notion API reference:
  * https://developers.notion.com/reference/emoji-object
+ *
+ * @category Custom Emoji & Icons
  */
 export declare const emojiSchema: z.ZodObject<{
     type: z.ZodLiteral<"emoji">;
     emoji: z.ZodString;
 }, z.core.$strip>;
+/**
+ * @category Custom Emoji & Icons
+ */
 export type NotionEmoji = z.infer<typeof emojiSchema>;