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

package/dist/api/fileUploads.api.js

@@ -3,9 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileUploadsAPI = void 0;
 const schemas_1 = require("../schemas");
 const models_1 = require("../models");
+const base_model_1 = require("../models/base.model");
 const base_api_1 = require("./base.api");
 /**
  * FileUploads API client for uploading files to Notion.
+ *
+ * @category File Uploads
  */
 class FileUploadsAPI extends base_api_1.BaseAPI {
     constructor(client) {
@@ -31,11 +34,12 @@ class FileUploadsAPI extends base_api_1.BaseAPI {
             body: options,
         });
         const parsed = schemas_1.fileUploadSchema.parse(response);
-        return new models_1.FileUpload(parsed);
+        return new models_1.FileUpload(parsed, base_model_1.TRUSTED);
     }
     /**
      * Upload file data to the upload URL.
-     * This is a direct PUT request to the upload URL (not through Notion API).
+     * This method sends a PUT request directly to the upload URL. It does not go
+     * through the Notion API.
      *
      * @param uploadUrl - The upload URL from initiate()
      * @param fileData - The file data to upload
@@ -70,12 +74,12 @@ class FileUploadsAPI extends base_api_1.BaseAPI {
             body: {},
         });
         const parsed = schemas_1.fileUploadSchema.parse(response);
-        return new models_1.FileUpload(parsed);
+        return new models_1.FileUpload(parsed, base_model_1.TRUSTED);
     }
     /**
-     * Extracts the request path from a complete URL, accepting both absolute
-     * URLs (e.g. `https://api.notion.com/v1/file_uploads/.../complete`) and
-     * relative paths (e.g. `/v1/file_uploads/.../complete` or the path alone).
+     * Extract the request path from a complete URL.
+     * Accept absolute URLs, for example `https://api.notion.com/v1/file_uploads/.../complete`.
+     * Accept relative paths too, for example `/v1/file_uploads/.../complete` or the path alone.
      */
     static toRequestPath(completeUrl) {
         let path;
@@ -136,7 +140,7 @@ class FileUploadsAPI extends base_api_1.BaseAPI {
             path: `/file_uploads/${fileUploadId}`,
         });
         const parsed = schemas_1.fileUploadSchema.parse(response);
-        return new models_1.FileUpload(parsed);
+        return new models_1.FileUpload(parsed, base_model_1.TRUSTED);
     }
 }
 exports.FileUploadsAPI = FileUploadsAPI;

package/dist/api/pages.api.d.ts

@@ -143,6 +143,8 @@ export interface UpdatePageOptions {
 }
 /**
  * Pages API client for working with Notion pages.
+ *
+ * @category Pages
  */
 export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
     protected readonly client: NotionClient;
@@ -378,6 +380,9 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"string">;
                     string: import("zod").ZodNullable<import("zod").ZodString>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"unsupported">;
+                    unsupported: import("zod").ZodObject<{}, import("zod/v4/core").$strip>;
                 }, import("zod/v4/core").$strip>], "type">;
             }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                 id: import("zod").ZodString;
@@ -1075,9 +1080,9 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
     /**
      * Update a page's content as markdown.
      *
-     * When `allow_async: true` is set and the write is large, the API may return an
-     * `async_task` handle instead of completing synchronously -- poll it via
-     * `notion.asyncTasks.poll(task.id)`.
+     * Set `allow_async: true` to allow asynchronous processing for large writes.
+     * In that case, the API returns an `async_task` handle instead of the completed
+     * content. Poll the task with `notion.asyncTasks.poll(task.id)`.
      *
      * @param pageId - The ID of the page to update
      * @param options - The markdown update to apply

package/dist/api/pages.api.js

@@ -17,6 +17,8 @@ function validateMarkdownExclusivity(options) {
 }
 /**
  * Pages API client for working with Notion pages.
+ *
+ * @category Pages
  */
 class PagesAPI extends base_api_1.BaseAPI {
     constructor(client) {
@@ -81,9 +83,9 @@ class PagesAPI extends base_api_1.BaseAPI {
     /**
      * Update a page's content as markdown.
      *
-     * When `allow_async: true` is set and the write is large, the API may return an
-     * `async_task` handle instead of completing synchronously -- poll it via
-     * `notion.asyncTasks.poll(task.id)`.
+     * Set `allow_async: true` to allow asynchronous processing for large writes.
+     * In that case, the API returns an `async_task` handle instead of the completed
+     * content. Poll the task with `notion.asyncTasks.poll(task.id)`.
      *
      * @param pageId - The ID of the page to update
      * @param options - The markdown update to apply

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,18 +1,26 @@
 /**
  * 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';
     status: number;
     code: NotionErrorCode;
     message: string;
+    /** Extra machine-readable context for some error codes, for example `restricted_resource`. */
+    additional_data?: Record<string, unknown>;
 }
 /**
- * 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,9 +41,14 @@ 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;
+    /**
+     * Check if a workspace restriction blocked the request.
+     * The Free workspace block limit is one example.
+     */
+    isRestrictedResource(): boolean;
     /**
      * Check if the error is a validation error.
      */
@@ -50,13 +63,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,11 +38,18 @@ 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';
     }
+    /**
+     * Check if a workspace restriction blocked the request.
+     * The Free workspace block limit is one example.
+     */
+    isRestrictedResource() {
+        return this.code === 'restricted_resource';
+    }
     /**
      * Check if the error is a validation error.
      */
@@ -62,7 +71,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 +86,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) {