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

package/dist/api/search.api.d.ts

@@ -9,8 +9,8 @@ export type SearchFilterObject = 'page' | 'data_source';
 /**
  * Search filter configuration.
  *
- * `in_trash` can be combined with the object filter (`property`/`value`) or
- * used on its own to list only trashed content.
+ * Combine `in_trash` with the object filter (`property`/`value`), or use it alone
+ * to list only trashed content.
  */
 export type SearchFilter = {
     /** Filter by object type */
@@ -50,6 +50,8 @@ export interface SearchOptions extends PaginationParameters {
 export type SearchResult = Page | DataSource;
 /**
  * Search API client for searching across the workspace.
+ *
+ * @category Search
  */
 export declare class SearchAPI {
     private readonly client;

package/dist/api/search.api.js

@@ -3,8 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchAPI = void 0;
 const schemas_1 = require("../schemas");
 const models_1 = require("../models");
+const base_model_1 = require("../models/base.model");
 /**
  * Search API client for searching across the workspace.
+ *
+ * @category Search
  */
 class SearchAPI {
     constructor(client) {
@@ -41,11 +44,11 @@ class SearchAPI {
         const results = response.results.map((item) => {
             if (item.object === 'page') {
                 const parsed = schemas_1.pageSchema.parse(item);
-                return new models_1.Page(parsed);
+                return new models_1.Page(parsed, base_model_1.TRUSTED);
             }
             else {
                 const parsed = schemas_1.dataSourceSchema.parse(item);
-                return new models_1.DataSource(parsed);
+                return new models_1.DataSource(parsed, base_model_1.TRUSTED);
             }
         });
         return {

package/dist/api/users.api.d.ts

@@ -4,6 +4,8 @@ import { User } from '../models';
 import { BaseAPI } from './base.api';
 /**
  * Users API client for working with Notion users.
+ *
+ * @category Users
  */
 export declare class UsersAPI extends BaseAPI<NotionUser, User> {
     protected readonly client: NotionClient;

package/dist/api/users.api.js

@@ -6,6 +6,8 @@ const models_1 = require("../models");
 const base_api_1 = require("./base.api");
 /**
  * Users API client for working with Notion users.
+ *
+ * @category Users
  */
 class UsersAPI extends base_api_1.BaseAPI {
     constructor(client) {

package/dist/api/views.api.d.ts

@@ -13,8 +13,8 @@ export interface ListViewsOptions extends PaginationParameters {
     data_source_id?: string;
 }
 /**
- * Options for creating a view. Exactly one of `database_id`/`view_id`/`create_database`
- * must be provided to select the parent context.
+ * Options for creating a view. Provide exactly one of
+ * `database_id`/`view_id`/`create_database` to select the parent context.
  */
 export interface CreateViewOptions {
     /** The data source the view displays */
@@ -41,8 +41,8 @@ export interface CreateViewOptions {
     position?: Record<string, unknown>;
 }
 /**
- * Options for updating a view. All fields optional; passing `null` for
- * filter/sorts/quick_filters clears the existing value.
+ * Options for updating a view. All fields are optional.
+ * Pass `null` for `filter`, `sorts`, or `quick_filters` to clear the existing value.
  */
 export interface UpdateViewOptions {
     /** Rename the view */
@@ -66,9 +66,9 @@ export interface CreateViewQueryOptions extends PaginationParameters {
     sorts?: DataSourceSort[];
 }
 /**
- * Result of a view query. Non-standard pagination shape distinct from
- * {@link PaginatedList} -- includes `totalCount` and an `expiresAt` after which the
- * query can no longer be retrieved via {@link ViewsAPI.queries.get}.
+ * Result of a view query. This shape differs from {@link PaginatedList}.
+ * It includes `totalCount` and `expiresAt`. After `expiresAt` passes,
+ * {@link ViewsAPI.queries.get} can no longer retrieve the query.
  */
 export interface ViewQueryResult {
     id: string;
@@ -85,6 +85,8 @@ export interface ViewQueryResult {
  *
  * Views control how a database/data source's rows are displayed (table, board,
  * calendar, etc.). Requires API version 2025-09-03 or later.
+ *
+ * @category Views
  */
 export declare class ViewsAPI extends BaseAPI<NotionView, View> {
     protected readonly client: NotionClient;
@@ -246,9 +248,9 @@ export declare class ViewsAPI extends BaseAPI<NotionView, View> {
     /**
      * Delete a view.
      *
-     * Note: unlike other delete methods, Notion's delete-view response only includes
-     * `object`/`id`/`parent`/`type` (not the full view shape), so this returns the raw
-     * parsed result rather than a full {@link View} model.
+     * Notion's delete-view response differs from other delete methods. It includes
+     * only `object`/`id`/`parent`/`type`, not the full view shape. This method
+     * returns the raw parsed result instead of a full {@link View} model.
      *
      * @param viewId - The ID of the view to delete
      * @returns The partial view object returned by the API
@@ -257,9 +259,9 @@ export declare class ViewsAPI extends BaseAPI<NotionView, View> {
      */
     delete(viewId: string): Promise<ViewDeleteResult>;
     /**
-     * Sub-resource for querying a view's rows. View queries are non-standard: they
-     * return a `total_count` and `expires_at`, and the query result itself expires
-     * roughly 15 minutes after creation.
+     * Sub-resource to query a view's rows. View queries are non-standard.
+     * Each query returns a `total_count` and an `expires_at` value. The query
+     * result expires about 15 minutes after creation.
      */
     readonly queries: {
         /**

package/dist/api/views.api.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ViewsAPI = void 0;
 const models_1 = require("../models");
+const base_model_1 = require("../models/base.model");
 const schemas_1 = require("../schemas");
 const validation_1 = require("../validation");
 const base_api_1 = require("./base.api");
@@ -12,7 +13,7 @@ function toViewQueryResult(response) {
         viewId: parsed.view_id,
         expiresAt: new Date(parsed.expires_at),
         totalCount: parsed.total_count,
-        results: parsed.results.map((page) => new models_1.Page(page)),
+        results: parsed.results.map((page) => new models_1.Page(page, base_model_1.TRUSTED)),
         nextCursor: parsed.next_cursor,
         hasMore: parsed.has_more,
         requestStatus: parsed.request_status,
@@ -23,6 +24,8 @@ function toViewQueryResult(response) {
  *
  * Views control how a database/data source's rows are displayed (table, board,
  * calendar, etc.). Requires API version 2025-09-03 or later.
+ *
+ * @category Views
  */
 class ViewsAPI extends base_api_1.BaseAPI {
     constructor(client) {
@@ -34,9 +37,9 @@ class ViewsAPI extends base_api_1.BaseAPI {
             listType: 'view',
         };
         /**
-         * Sub-resource for querying a view's rows. View queries are non-standard: they
-         * return a `total_count` and `expires_at`, and the query result itself expires
-         * roughly 15 minutes after creation.
+         * Sub-resource to query a view's rows. View queries are non-standard.
+         * Each query returns a `total_count` and an `expires_at` value. The query
+         * result expires about 15 minutes after creation.
          */
         this.queries = {
             /**
@@ -149,9 +152,9 @@ class ViewsAPI extends base_api_1.BaseAPI {
     /**
      * Delete a view.
      *
-     * Note: unlike other delete methods, Notion's delete-view response only includes
-     * `object`/`id`/`parent`/`type` (not the full view shape), so this returns the raw
-     * parsed result rather than a full {@link View} model.
+     * Notion's delete-view response differs from other delete methods. It includes
+     * only `object`/`id`/`parent`/`type`, not the full view shape. This method
+     * returns the raw parsed result instead of a full {@link View} model.
      *
      * @param viewId - The ID of the view to delete
      * @returns The partial view object returned by the API

package/dist/client.d.ts

@@ -1,10 +1,14 @@
 /**
- * The Notion API version targeted by this SDK.
- * All schemas, request bodies, helpers, and models are coupled to this version.
+ * The Notion API version this SDK uses.
+ * All schemas, request bodies, helpers, and models depend on this version.
+ *
+ * @category Client & Core
  */
 export declare const NOTION_VERSION: "2026-03-11";
 /**
  * Configuration options for the Notion client.
+ *
+ * @category Client & Core
  */
 export interface NotionClientOptions {
     /** Notion integration token (Bearer token) */
@@ -33,47 +37,43 @@ export interface RequestOptions {
  * Base HTTP client for Notion API requests.
  */
 export declare class NotionClient {
-    private readonly auth;
     private readonly baseUrl;
     private readonly timeoutMs;
     private readonly fetchImpl;
     private readonly maxRetries;
     private readonly retryOnRateLimit;
+    private readonly requestHeaders;
     constructor(options: NotionClientOptions);
     /**
-     * Makes an HTTP request to the Notion API with retry logic for rate limits.
+     * Send a request to the Notion API.
+     * Retry automatically on rate-limited and overloaded responses.
      */
     request<T>(options: RequestOptions): Promise<T>;
     /**
-     * Makes a single HTTP request to the Notion API.
+     * Send one HTTP request to the Notion API.
      */
     private makeRequest;
     /**
-     * Computes a fallback retry delay using exponential backoff.
-     * Used when the `Retry-After` response header is absent.
+     * Calculate a fallback retry delay with exponential backoff.
+     * Use this delay when the response has no `Retry-After` header.
      * Formula: 2^attempt * 1000 ms, capped at 60 seconds.
      */
     private getRetryAfter;
     /**
-     * Sleeps for the specified duration in milliseconds.
+     * Pause for the given duration, in milliseconds.
      */
     private sleep;
     /**
-     * Builds the full URL with query parameters.
+     * Build the full URL with query parameters.
      */
     private buildUrl;
     /**
-     * Builds request headers.
-     */
-    private buildHeaders;
-    /**
-     * Parses the `Retry-After` response header into milliseconds.
-     * Returns `undefined` when the header is absent or not a valid
-     * non-negative integer.
+     * Parse the `Retry-After` response header into milliseconds.
+     * Return `undefined` if the header is missing or not a valid non-negative number.
      */
     private parseRetryAfterHeader;
     /**
-     * Handles error responses from the API.
+     * Handle an error response from the API.
      */
     private handleErrorResponse;
 }

package/dist/client.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NotionClient = exports.NOTION_VERSION = void 0;
 const errors_1 = require("./errors");
 /**
- * The Notion API version targeted by this SDK.
- * All schemas, request bodies, helpers, and models are coupled to this version.
+ * The Notion API version this SDK uses.
+ * All schemas, request bodies, helpers, and models depend on this version.
+ *
+ * @category Client & Core
  */
 exports.NOTION_VERSION = '2026-03-11';
 /**
@@ -12,15 +14,20 @@ exports.NOTION_VERSION = '2026-03-11';
  */
 class NotionClient {
     constructor(options) {
-        this.auth = options.auth;
-        this.baseUrl = options.baseUrl ?? 'https://api.notion.com';
+        this.baseUrl = `${options.baseUrl ?? 'https://api.notion.com'}/v1`;
         this.timeoutMs = options.timeoutMs ?? 60000;
         this.fetchImpl = options.fetch ?? fetch;
         this.maxRetries = options.maxRetries ?? 3;
         this.retryOnRateLimit = options.retryOnRateLimit ?? true;
+        this.requestHeaders = {
+            Authorization: `Bearer ${options.auth}`,
+            'Content-Type': 'application/json',
+            'Notion-Version': exports.NOTION_VERSION,
+        };
     }
     /**
-     * Makes an HTTP request to the Notion API with retry logic for rate limits.
+     * Send a request to the Notion API.
+     * Retry automatically on rate-limited and overloaded responses.
      */
     async request(options) {
         let lastError;
@@ -49,17 +56,16 @@ class NotionClient {
         throw lastError ?? new Error('Request failed after all retries');
     }
     /**
-     * Makes a single HTTP request to the Notion API.
+     * Send one HTTP request to the Notion API.
      */
     async makeRequest(options) {
         const url = this.buildUrl(options.path, options.query);
-        const headers = this.buildHeaders();
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
         try {
             const response = await this.fetchImpl(url, {
                 method: options.method,
-                headers,
+                headers: this.requestHeaders,
                 body: options.body ? JSON.stringify(options.body) : undefined,
                 signal: controller.signal,
             });
@@ -89,8 +95,8 @@ class NotionClient {
         }
     }
     /**
-     * Computes a fallback retry delay using exponential backoff.
-     * Used when the `Retry-After` response header is absent.
+     * Calculate a fallback retry delay with exponential backoff.
+     * Use this delay when the response has no `Retry-After` header.
      * Formula: 2^attempt * 1000 ms, capped at 60 seconds.
      */
     getRetryAfter(attempt) {
@@ -98,16 +104,16 @@ class NotionClient {
         return Math.min(backoffMs, 60000); // Cap at 60 seconds
     }
     /**
-     * Sleeps for the specified duration in milliseconds.
+     * Pause for the given duration, in milliseconds.
      */
     sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }
     /**
-     * Builds the full URL with query parameters.
+     * Build the full URL with query parameters.
      */
     buildUrl(path, query) {
-        const url = new URL(`${this.baseUrl}/v1${path}`);
+        const url = new URL(`${this.baseUrl}${path}`);
         if (query) {
             Object.entries(query).forEach(([key, value]) => {
                 if (value === undefined) {
@@ -124,19 +130,8 @@ class NotionClient {
         return url.toString();
     }
     /**
-     * Builds request headers.
-     */
-    buildHeaders() {
-        return {
-            Authorization: `Bearer ${this.auth}`,
-            'Content-Type': 'application/json',
-            'Notion-Version': exports.NOTION_VERSION,
-        };
-    }
-    /**
-     * Parses the `Retry-After` response header into milliseconds.
-     * Returns `undefined` when the header is absent or not a valid
-     * non-negative integer.
+     * Parse the `Retry-After` response header into milliseconds.
+     * Return `undefined` if the header is missing or not a valid non-negative number.
      */
     parseRetryAfterHeader(response) {
         const header = response.headers.get('Retry-After');
@@ -150,7 +145,7 @@ class NotionClient {
         return Math.ceil(seconds) * 1000;
     }
     /**
-     * Handles error responses from the API.
+     * Handle an error response from the API.
      */
     async handleErrorResponse(response) {
         const retryAfterMs = this.parseRetryAfterHeader(response);

package/dist/errors.d.ts

@@ -1,9 +1,13 @@
 /**
  * Notion API error codes based on official documentation.
+ *
+ * @category Errors
  */
 export type NotionErrorCode = 'invalid_json' | 'invalid_request_url' | 'invalid_request' | 'validation_error' | 'missing_version' | 'unauthorized' | 'restricted_resource' | 'object_not_found' | 'conflict_error' | 'rate_limited' | 'internal_server_error' | 'service_unavailable' | 'service_overload' | 'database_connection_unavailable' | 'gateway_timeout';
 /**
  * Notion API error response structure.
+ *
+ * @category Errors
  */
 export interface NotionErrorResponse {
     object: 'error';
@@ -12,7 +16,9 @@ export interface NotionErrorResponse {
     message: string;
 }
 /**
- * Custom error class for Notion API errors.
+ * Thrown when the Notion API returns an error response.
+ *
+ * @category Errors
  */
 export declare class NotionAPIError extends Error {
     readonly status: number;
@@ -33,7 +39,7 @@ export declare class NotionAPIError extends Error {
      */
     isUnauthorized(): boolean;
     /**
-     * Check if the error is a not found error.
+     * Check if the API could not find the requested object.
      */
     isNotFound(): boolean;
     /**
@@ -50,13 +56,17 @@ export declare class NotionAPIError extends Error {
     isRetryable(): boolean;
 }
 /**
- * Request timeout error.
+ * Thrown when a request exceeds its timeout.
+ *
+ * @category Errors
  */
 export declare class NotionRequestTimeoutError extends Error {
     constructor(message?: string);
 }
 /**
- * Network error (connectivity issues, DNS failure, etc.).
+ * Thrown when a network problem, such as a DNS failure, blocks a request.
+ *
+ * @category Errors
  */
 export declare class NotionNetworkError extends Error {
     readonly cause?: Error;

package/dist/errors.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NotionNetworkError = exports.NotionRequestTimeoutError = exports.NotionAPIError = void 0;
 /**
- * Custom error class for Notion API errors.
+ * Thrown when the Notion API returns an error response.
+ *
+ * @category Errors
  */
 class NotionAPIError extends Error {
     constructor(response, retryAfterMs) {
@@ -36,7 +38,7 @@ class NotionAPIError extends Error {
         return this.code === 'unauthorized';
     }
     /**
-     * Check if the error is a not found error.
+     * Check if the API could not find the requested object.
      */
     isNotFound() {
         return this.code === 'object_not_found';
@@ -62,7 +64,9 @@ class NotionAPIError extends Error {
 }
 exports.NotionAPIError = NotionAPIError;
 /**
- * Request timeout error.
+ * Thrown when a request exceeds its timeout.
+ *
+ * @category Errors
  */
 class NotionRequestTimeoutError extends Error {
     constructor(message = 'Request timed out') {
@@ -75,7 +79,9 @@ class NotionRequestTimeoutError extends Error {
 }
 exports.NotionRequestTimeoutError = NotionRequestTimeoutError;
 /**
- * Network error (connectivity issues, DNS failure, etc.).
+ * Thrown when a network problem, such as a DNS failure, blocks a request.
+ *
+ * @category Errors
  */
 class NotionNetworkError extends Error {
     constructor(message, cause) {

package/dist/helpers/block.helpers.d.ts

@@ -2,7 +2,9 @@ import type { CodeBlockLanguage, NotionColor, NotionRichText } from '../schemas'
 import { RichTextBuilder } from './richText.helpers';
 /**
  * Accepted rich text input: a plain string, a {@link RichTextBuilder}, or
- * a pre-built `NotionRichText` array.
+ * a pre-built `NotionRichText`.
+ *
+ * @category Rich Text
  */
 export type RichTextInput = string | RichTextBuilder | NotionRichText;
 /** Common options shared by text-bearing blocks. */
@@ -10,7 +12,7 @@ interface TextBlockOptions {
     color?: NotionColor;
     children?: unknown[];
 }
-/** The minimal block object accepted by the Notion API for creation. */
+/** The Notion API accepts this minimal block object for creation. */
 interface BlockObject {
     object: 'block';
     type: string;
@@ -18,7 +20,7 @@ interface BlockObject {
 }
 /** Options for paragraph blocks. */
 interface ParagraphOptions extends TextBlockOptions {
-    /** Icon shown alongside the paragraph. Only meaningful for paragraphs used as tab items. */
+    /** Icon for the paragraph. Applies only to paragraphs used as tab items. */
     icon?: unknown;
 }
 /**
@@ -72,12 +74,12 @@ declare function template(text: RichTextInput, options?: {
     children?: unknown[];
 }): BlockObject;
 /**
- * @deprecated Meeting-notes blocks are server-managed -- their real shape (`title`,
- * `status`, and child block IDs for the summary/notes/transcript) is populated by
- * Notion, not hand-constructed by clients. This helper's `rich_text`-based output no
- * longer matches `blockSchema`'s `meeting_notes` shape and is not a valid way to
- * create a meeting-notes block. Kept only to avoid an abrupt removal from the helper
- * surface; do not use for new code.
+ * @deprecated Notion manages meeting-notes blocks on the server. Notion populates the
+ * real shape (`title`, `status`, and child block IDs for the summary, notes, and
+ * transcript). Clients do not construct this shape by hand. This helper's
+ * `rich_text`-based output no longer matches the `meeting_notes` shape in
+ * `blockSchema`. Do not use this helper to create a meeting-notes block. It remains
+ * only to avoid an abrupt removal from the helper surface. Do not use it in new code.
  */
 declare function meetingNotes(text: RichTextInput, options?: {
     children?: unknown[];
@@ -129,7 +131,10 @@ declare function table(width: number, options?: TableOptions): BlockObject;
 declare function tableRow(cells: RichTextInput[]): BlockObject;
 declare function columnList(columns: unknown[][]): BlockObject;
 declare function column(children: unknown[]): BlockObject;
-/** A single tab: its label becomes the tab's paragraph rich text, `children` its content. */
+/**
+ * A single tab. Its label becomes the tab's paragraph rich text.
+ * Its `children` become the tab's content.
+ */
 interface TabItem {
     label: RichTextInput;
     icon?: unknown;
@@ -137,9 +142,9 @@ interface TabItem {
     children?: unknown[];
 }
 /**
- * Create a tab block. Only `paragraph` blocks may be direct children of a tab block --
- * each tab is modeled as one paragraph, whose rich text is the tab label and whose
- * `children` hold the tab's content.
+ * Create a tab block. A tab block accepts only `paragraph` blocks as direct children.
+ * Each tab is one paragraph. The paragraph's rich text holds the tab label. The
+ * paragraph's `children` hold the tab's content.
  *
  * @example
  * ```ts
@@ -161,9 +166,9 @@ declare function syncedBlock(options?: {
     children?: unknown[];
 }): BlockObject;
 /**
- * Factory functions for constructing Notion block objects.
+ * Factory functions that create Notion block objects.
  *
- * Every function returns a plain object ready to pass to
+ * Every function returns a plain object. Pass this object to
  * `blocks.children.append()` or `pages.create()`.
  *
  * @example
@@ -189,6 +194,8 @@ declare function syncedBlock(options?: {
  *   }),
  * ];
  * ```
+ *
+ * @category Helpers
  */
 export declare const block: {
     paragraph: typeof paragraph;

package/dist/helpers/block.helpers.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.block = void 0;
 const validation_1 = require("../validation");
 const richText_helpers_1 = require("./richText.helpers");
-/** Resolve a {@link RichTextInput} into a `NotionRichText` array. */
+/** Resolve a {@link RichTextInput} into a `NotionRichText`. */
 function resolveRichText(input) {
     if (typeof input === 'string') {
         (0, validation_1.validateStringLength)(input, validation_1.LIMITS.RICH_TEXT_CONTENT, 'Rich text content');
@@ -181,12 +181,12 @@ function template(text, options) {
     };
 }
 /**
- * @deprecated Meeting-notes blocks are server-managed -- their real shape (`title`,
- * `status`, and child block IDs for the summary/notes/transcript) is populated by
- * Notion, not hand-constructed by clients. This helper's `rich_text`-based output no
- * longer matches `blockSchema`'s `meeting_notes` shape and is not a valid way to
- * create a meeting-notes block. Kept only to avoid an abrupt removal from the helper
- * surface; do not use for new code.
+ * @deprecated Notion manages meeting-notes blocks on the server. Notion populates the
+ * real shape (`title`, `status`, and child block IDs for the summary, notes, and
+ * transcript). Clients do not construct this shape by hand. This helper's
+ * `rich_text`-based output no longer matches the `meeting_notes` shape in
+ * `blockSchema`. Do not use this helper to create a meeting-notes block. It remains
+ * only to avoid an abrupt removal from the helper surface. Do not use it in new code.
  */
 function meetingNotes(text, options) {
     return {
@@ -367,9 +367,9 @@ function column(children) {
     };
 }
 /**
- * Create a tab block. Only `paragraph` blocks may be direct children of a tab block --
- * each tab is modeled as one paragraph, whose rich text is the tab label and whose
- * `children` hold the tab's content.
+ * Create a tab block. A tab block accepts only `paragraph` blocks as direct children.
+ * Each tab is one paragraph. The paragraph's rich text holds the tab label. The
+ * paragraph's `children` hold the tab's content.
  *
  * @example
  * ```ts
@@ -411,9 +411,9 @@ function syncedBlock(options) {
 // Public export
 // ---------------------------------------------------------------------------
 /**
- * Factory functions for constructing Notion block objects.
+ * Factory functions that create Notion block objects.
  *
- * Every function returns a plain object ready to pass to
+ * Every function returns a plain object. Pass this object to
  * `blocks.children.append()` or `pages.create()`.
  *
  * @example
@@ -439,6 +439,8 @@ function syncedBlock(options) {
  *   }),
  * ];
  * ```
+ *
+ * @category Helpers
  */
 exports.block = {
     // Text blocks