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

package/dist/api/blocks.api.js

@@ -71,6 +71,7 @@ class BlocksAPI extends base_api_1.BaseAPI {
              *
              * @param options - Filter, sort, and limit options
              * @returns Matching meeting-notes blocks
+             * @throws {NotionValidationError} If `limit` is outside the range 1 to 50.
              *
              * @see https://developers.notion.com/reference/query-meeting-notes
              */
@@ -78,6 +79,9 @@ class BlocksAPI extends base_api_1.BaseAPI {
                 if (options?.sort) {
                     (0, validation_1.validateArrayLength)(options.sort, validation_1.LIMITS.ARRAY_ELEMENTS, 'sort');
                 }
+                if (options?.limit !== undefined) {
+                    (0, validation_1.validateNumberRange)(options.limit, 1, 50, 'limit');
+                }
                 const body = {};
                 if (options?.filter) {
                     body.filter = options.filter;

package/dist/api/comments.api.d.ts

@@ -162,10 +162,23 @@ export declare class CommentsAPI extends BaseAPI<NotionComment, Comment> {
             }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                 type: import("zod").ZodLiteral<"mention">;
                 mention: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"custom_emoji">;
+                    custom_emoji: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        name: import("zod").ZodString;
+                        url: import("zod").ZodURL;
+                    }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"database">;
                     database: import("zod").ZodObject<{
                         id: import("zod").ZodUUID;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"data_source">;
+                    data_source: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        database_id: import("zod").ZodOptional<import("zod").ZodUUID>;
+                    }, import("zod/v4/core").$strip>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"date">;
                     date: import("zod").ZodObject<{
@@ -173,6 +186,11 @@ export declare class CommentsAPI extends BaseAPI<NotionComment, Comment> {
                         end: import("zod").ZodNullable<import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>>;
                         time_zone: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"link_mention">;
+                    link_mention: import("zod").ZodObject<{
+                        href: import("zod").ZodString;
+                    }, import("zod/v4/core").$loose>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"link_preview">;
                     link_preview: import("zod").ZodObject<{
@@ -329,7 +347,7 @@ export declare class CommentsAPI extends BaseAPI<NotionComment, Comment> {
      * @param params - Pagination parameters
      * @returns Paginated list of comments
      *
-     * @see https://developers.notion.com/reference/retrieve-a-comment
+     * @see https://developers.notion.com/reference/retrieve-a-comment-list
      */
     list(parentId: string, params?: PaginationParameters): Promise<PaginatedList<Comment>>;
     /**

package/dist/api/comments.api.js

@@ -39,7 +39,7 @@ class CommentsAPI extends base_api_1.BaseAPI {
      * @param params - Pagination parameters
      * @returns Paginated list of comments
      *
-     * @see https://developers.notion.com/reference/retrieve-a-comment
+     * @see https://developers.notion.com/reference/retrieve-a-comment-list
      */
     async list(parentId, params) {
         const query = {

package/dist/api/dataSources.api.d.ts

@@ -541,10 +541,23 @@ export declare class DataSourcesAPI extends BaseAPI<NotionDataSource, DataSource
             }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                 type: import("zod").ZodLiteral<"mention">;
                 mention: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"custom_emoji">;
+                    custom_emoji: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        name: import("zod").ZodString;
+                        url: import("zod").ZodURL;
+                    }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"database">;
                     database: import("zod").ZodObject<{
                         id: import("zod").ZodUUID;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"data_source">;
+                    data_source: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        database_id: import("zod").ZodOptional<import("zod").ZodUUID>;
+                    }, import("zod/v4/core").$strip>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"date">;
                     date: import("zod").ZodObject<{
@@ -552,6 +565,11 @@ export declare class DataSourcesAPI extends BaseAPI<NotionDataSource, DataSource
                         end: import("zod").ZodNullable<import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>>;
                         time_zone: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"link_mention">;
+                    link_mention: import("zod").ZodObject<{
+                        href: import("zod").ZodString;
+                    }, import("zod/v4/core").$loose>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"link_preview">;
                     link_preview: import("zod").ZodObject<{
@@ -717,10 +735,23 @@ export declare class DataSourcesAPI extends BaseAPI<NotionDataSource, DataSource
             }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                 type: import("zod").ZodLiteral<"mention">;
                 mention: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"custom_emoji">;
+                    custom_emoji: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        name: import("zod").ZodString;
+                        url: import("zod").ZodURL;
+                    }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"database">;
                     database: import("zod").ZodObject<{
                         id: import("zod").ZodUUID;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"data_source">;
+                    data_source: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        database_id: import("zod").ZodOptional<import("zod").ZodUUID>;
+                    }, import("zod/v4/core").$strip>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"date">;
                     date: import("zod").ZodObject<{
@@ -728,6 +759,11 @@ export declare class DataSourcesAPI extends BaseAPI<NotionDataSource, DataSource
                         end: import("zod").ZodNullable<import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>>;
                         time_zone: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"link_mention">;
+                    link_mention: import("zod").ZodObject<{
+                        href: import("zod").ZodString;
+                    }, import("zod/v4/core").$loose>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"link_preview">;
                     link_preview: import("zod").ZodObject<{
@@ -917,6 +953,11 @@ export declare class DataSourcesAPI extends BaseAPI<NotionDataSource, DataSource
             public_url: import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>;
             is_inline: import("zod").ZodBoolean;
             in_trash: import("zod").ZodBoolean;
+            database_type: import("zod").ZodOptional<import("zod").ZodEnum<{
+                tasks: "tasks";
+                projects: "projects";
+                skills: "skills";
+            }>>;
         }, import("zod/v4/core").$strip>;
         ModelClass: typeof DataSource;
         listType: "data_source";

package/dist/api/databases.api.d.ts

@@ -1,5 +1,5 @@
 import type { NotionClient } from '../client';
-import { type NotionDatabase, type PaginatedList, type PaginationParameters } from '../schemas';
+import { type DatabaseType, type NotionDatabase, type PaginatedList, type PaginationParameters } from '../schemas';
 import { Database, Page } from '../models';
 import { BaseAPI } from './base.api';
 /**
@@ -52,7 +52,9 @@ export type CreateDatabaseParent = {
 };
 /**
  * Initial data source configuration for creating a database.
- * As of API version 2025-09-03, databases are created with an initial data source.
+ * Provide this to create a database with a custom properties schema. To create a database
+ * from one of Notion's canonical schemas instead, use `database_type` on
+ * {@link CreateDatabaseOptions}.
  */
 export interface InitialDataSource {
     /** Data source properties schema */
@@ -62,14 +64,17 @@ export interface InitialDataSource {
 }
 /**
  * Options for creating a database.
- * As of API version 2025-09-03, databases require an `initial_data_source` object.
- * This object holds the properties schema. It replaces top-level properties.
+ * Provide exactly one of `database_type` or `initial_data_source`. `database_type` builds
+ * the database from one of Notion's canonical schemas. `initial_data_source` holds a custom
+ * properties schema. It replaces top-level properties.
  */
 export interface CreateDatabaseOptions {
     /** The parent object (page or workspace) */
     parent: CreateDatabaseParent;
+    /** Build the database from a canonical Notion schema instead of a custom one */
+    database_type?: DatabaseType;
     /** Initial data source configuration (contains properties schema) */
-    initial_data_source: InitialDataSource;
+    initial_data_source?: InitialDataSource;
     /** Database title as rich text array */
     title?: unknown[];
     /** Database icon (emoji, file, or external) */
@@ -224,10 +229,23 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
             }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                 type: import("zod").ZodLiteral<"mention">;
                 mention: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"custom_emoji">;
+                    custom_emoji: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        name: import("zod").ZodString;
+                        url: import("zod").ZodURL;
+                    }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"database">;
                     database: import("zod").ZodObject<{
                         id: import("zod").ZodUUID;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"data_source">;
+                    data_source: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        database_id: import("zod").ZodOptional<import("zod").ZodUUID>;
+                    }, import("zod/v4/core").$strip>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"date">;
                     date: import("zod").ZodObject<{
@@ -235,6 +253,11 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
                         end: import("zod").ZodNullable<import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>>;
                         time_zone: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"link_mention">;
+                    link_mention: import("zod").ZodObject<{
+                        href: import("zod").ZodString;
+                    }, import("zod/v4/core").$loose>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"link_preview">;
                     link_preview: import("zod").ZodObject<{
@@ -400,10 +423,23 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
             }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                 type: import("zod").ZodLiteral<"mention">;
                 mention: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"custom_emoji">;
+                    custom_emoji: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        name: import("zod").ZodString;
+                        url: import("zod").ZodURL;
+                    }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"database">;
                     database: import("zod").ZodObject<{
                         id: import("zod").ZodUUID;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"data_source">;
+                    data_source: import("zod").ZodObject<{
+                        id: import("zod").ZodUUID;
+                        database_id: import("zod").ZodOptional<import("zod").ZodUUID>;
+                    }, import("zod/v4/core").$strip>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"date">;
                     date: import("zod").ZodObject<{
@@ -411,6 +447,11 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
                         end: import("zod").ZodNullable<import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>>;
                         time_zone: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
                     }, import("zod/v4/core").$strip>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"link_mention">;
+                    link_mention: import("zod").ZodObject<{
+                        href: import("zod").ZodString;
+                    }, import("zod/v4/core").$loose>;
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"link_preview">;
                     link_preview: import("zod").ZodObject<{
@@ -621,6 +662,11 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
             is_inline: import("zod").ZodBoolean;
             is_locked: import("zod").ZodOptional<import("zod").ZodBoolean>;
             public_url: import("zod").ZodNullable<import("zod").ZodURL>;
+            database_type: import("zod").ZodOptional<import("zod").ZodEnum<{
+                tasks: "tasks";
+                projects: "projects";
+                skills: "skills";
+            }>>;
         }, import("zod/v4/core").$strip>;
         ModelClass: typeof Database;
         listType: "database";
@@ -652,6 +698,7 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
      *
      * @param options - Options for creating the database
      * @returns The created database wrapped in a Database model
+     * @throws {NotionValidationError} If not exactly one of `database_type`/`initial_data_source` is provided
      *
      * @see https://developers.notion.com/reference/create-a-database
      */

package/dist/api/databases.api.js

@@ -67,6 +67,7 @@ class DatabasesAPI extends base_api_1.BaseAPI {
             next_cursor: parsed.next_cursor,
             has_more: parsed.has_more,
             type: 'page',
+            request_status: parsed.request_status,
         };
     }
     /**
@@ -74,19 +75,20 @@ class DatabasesAPI extends base_api_1.BaseAPI {
      *
      * @param options - Options for creating the database
      * @returns The created database wrapped in a Database model
+     * @throws {NotionValidationError} If not exactly one of `database_type`/`initial_data_source` is provided
      *
      * @see https://developers.notion.com/reference/create-a-database
      */
     async create(options) {
+        if (Boolean(options.database_type) === Boolean(options.initial_data_source)) {
+            throw new validation_1.NotionValidationError('Exactly one of database_type or initial_data_source must be provided');
+        }
         if (options.title) {
             (0, validation_1.validateArrayLength)(options.title, validation_1.LIMITS.ARRAY_ELEMENTS, 'title');
         }
         if (options.initial_data_source?.title) {
             (0, validation_1.validateArrayLength)(options.initial_data_source.title, validation_1.LIMITS.ARRAY_ELEMENTS, 'initial_data_source.title');
         }
-        if (options.initial_data_source.title) {
-            (0, validation_1.validateArrayLength)(options.initial_data_source.title, validation_1.LIMITS.ARRAY_ELEMENTS, 'initial_data_source.title');
-        }
         return this.createResource('/databases', options);
     }
     /**

package/dist/api/fileUploads.api.d.ts

@@ -14,9 +14,12 @@ export interface InitiateFileUploadOptions {
     content_length: number;
 }
 /**
- * File data for uploading (can be Buffer, ArrayBuffer, Blob, or ReadableStream).
+ * File data for uploading. Accepts a `Buffer`, `Uint8Array`, `ArrayBuffer`, or
+ * `Blob`. The upload endpoint uses `multipart/form-data`, so the SDK cannot
+ * stream a `ReadableStream` without buffering it in full. Read a stream into a
+ * `Buffer` yourself before you call `upload()`.
  */
-export type FileData = Buffer | ArrayBuffer | Blob | ReadableStream;
+export type FileData = Buffer | Uint8Array | ArrayBuffer | Blob;
 /**
  * FileUploads API client for uploading files to Notion.
  *
@@ -56,17 +59,24 @@ export declare class FileUploadsAPI extends BaseAPI<NotionFileUpload, FileUpload
      */
     initiate(options: InitiateFileUploadOptions): Promise<FileUpload>;
     /**
-     * Upload file data to the upload URL.
-     * This method sends a PUT request directly to the upload URL. It does not go
-     * through the Notion API.
+     * Upload file data to the upload URL from initiate(). Sends `multipart/form-data`
+     * through the configured `NotionClient`.
      *
      * @param uploadUrl - The upload URL from initiate()
      * @param fileData - The file data to upload
      * @param contentType - The MIME type of the file
+     * @param partNumber - The 1-based part number, for a multi-part upload of a file
+     * larger than 20 MB. Pass a positive integer.
+     * @throws {NotionValidationError} If `partNumber` is not a positive integer.
+     * @throws {NotionAPIError} If the upload endpoint returns an error response.
      *
-     * @see https://developers.notion.com/reference/upload-a-file
+     * @see https://developers.notion.com/reference/upload-file
      */
-    upload(uploadUrl: string, fileData: FileData, contentType: string): Promise<void>;
+    upload(uploadUrl: string, fileData: FileData, contentType: string, partNumber?: number): Promise<void>;
+    /**
+     * Convert file data into a `Blob` for the multipart request body.
+     */
+    private static toBlob;
     /**
      * Complete the file upload after uploading to the URL.
      *

package/dist/api/fileUploads.api.js

@@ -4,6 +4,7 @@ exports.FileUploadsAPI = void 0;
 const schemas_1 = require("../schemas");
 const models_1 = require("../models");
 const base_model_1 = require("../models/base.model");
+const validation_1 = require("../validation");
 const base_api_1 = require("./base.api");
 /**
  * FileUploads API client for uploading files to Notion.
@@ -37,27 +38,38 @@ class FileUploadsAPI extends base_api_1.BaseAPI {
         return new models_1.FileUpload(parsed, base_model_1.TRUSTED);
     }
     /**
-     * Upload file data to the upload URL.
-     * This method sends a PUT request directly to the upload URL. It does not go
-     * through the Notion API.
+     * Upload file data to the upload URL from initiate(). Sends `multipart/form-data`
+     * through the configured `NotionClient`.
      *
      * @param uploadUrl - The upload URL from initiate()
      * @param fileData - The file data to upload
      * @param contentType - The MIME type of the file
+     * @param partNumber - The 1-based part number, for a multi-part upload of a file
+     * larger than 20 MB. Pass a positive integer.
+     * @throws {NotionValidationError} If `partNumber` is not a positive integer.
+     * @throws {NotionAPIError} If the upload endpoint returns an error response.
      *
-     * @see https://developers.notion.com/reference/upload-a-file
+     * @see https://developers.notion.com/reference/upload-file
      */
-    async upload(uploadUrl, fileData, contentType) {
-        const response = await fetch(uploadUrl, {
-            method: 'PUT',
-            headers: {
-                'Content-Type': contentType,
-            },
-            body: fileData,
-        });
-        if (!response.ok) {
-            throw new Error(`File upload failed: ${response.status} ${response.statusText}`);
+    async upload(uploadUrl, fileData, contentType, partNumber) {
+        const form = new FormData();
+        form.append('file', FileUploadsAPI.toBlob(fileData, contentType));
+        if (partNumber !== undefined) {
+            if (!Number.isInteger(partNumber) || partNumber < 1) {
+                throw new validation_1.NotionValidationError(`partNumber must be a positive integer (got ${partNumber})`);
+            }
+            form.append('part_number', String(partNumber));
         }
+        await this.client.sendFileUpload(uploadUrl, form);
+    }
+    /**
+     * Convert file data into a `Blob` for the multipart request body.
+     */
+    static toBlob(fileData, contentType) {
+        if (fileData instanceof Blob) {
+            return fileData;
+        }
+        return new Blob([new Uint8Array(fileData)], { type: contentType });
     }
     /**
      * Complete the file upload after uploading to the URL.
@@ -101,11 +113,13 @@ class FileUploadsAPI extends base_api_1.BaseAPI {
      * @returns The completed file upload object
      */
     async uploadFile(filename, fileData, contentType) {
-        // Get content length
         let contentLength;
         if (fileData instanceof Buffer) {
             contentLength = fileData.length;
         }
+        else if (fileData instanceof Uint8Array) {
+            contentLength = fileData.byteLength;
+        }
         else if (fileData instanceof ArrayBuffer) {
             contentLength = fileData.byteLength;
         }
@@ -113,7 +127,7 @@ class FileUploadsAPI extends base_api_1.BaseAPI {
             contentLength = fileData.size;
         }
         else {
-            throw new TypeError('Cannot determine content length for ReadableStream. Use initiate/upload/complete separately.');
+            throw new TypeError('Unsupported file data type. Pass a Buffer, Uint8Array, ArrayBuffer, or Blob.');
         }
         // Step 1: Initiate upload
         const fileUpload = await this.initiate({

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

@@ -380,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;
@@ -493,6 +496,16 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
                 id: import("zod").ZodString;
                 type: import("zod").ZodLiteral<"phone_number">;
                 phone_number: import("zod").ZodNullable<import("zod").ZodString>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                id: import("zod").ZodString;
+                type: import("zod").ZodLiteral<"place">;
+                place: import("zod").ZodNullable<import("zod").ZodObject<{
+                    name: import("zod").ZodOptional<import("zod").ZodString>;
+                    address: import("zod").ZodOptional<import("zod").ZodString>;
+                    latitude: import("zod").ZodOptional<import("zod").ZodNumber>;
+                    longitude: import("zod").ZodOptional<import("zod").ZodNumber>;
+                    google_place_id: import("zod").ZodOptional<import("zod").ZodString>;
+                }, import("zod/v4/core").$loose>>;
             }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                 id: import("zod").ZodString;
                 type: import("zod").ZodLiteral<"relation">;
@@ -544,10 +557,23 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"mention">;
                     mention: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"custom_emoji">;
+                        custom_emoji: import("zod").ZodObject<{
+                            id: import("zod").ZodUUID;
+                            name: import("zod").ZodString;
+                            url: import("zod").ZodURL;
+                        }, import("zod/v4/core").$strip>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                         type: import("zod").ZodLiteral<"database">;
                         database: import("zod").ZodObject<{
                             id: import("zod").ZodUUID;
                         }, import("zod/v4/core").$strip>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"data_source">;
+                        data_source: import("zod").ZodObject<{
+                            id: import("zod").ZodUUID;
+                            database_id: import("zod").ZodOptional<import("zod").ZodUUID>;
+                        }, import("zod/v4/core").$strip>;
                     }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                         type: import("zod").ZodLiteral<"date">;
                         date: import("zod").ZodObject<{
@@ -555,6 +581,11 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
                             end: import("zod").ZodNullable<import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>>;
                             time_zone: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
                         }, import("zod/v4/core").$strip>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"link_mention">;
+                        link_mention: import("zod").ZodObject<{
+                            href: import("zod").ZodString;
+                        }, import("zod/v4/core").$loose>;
                     }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                         type: import("zod").ZodLiteral<"link_preview">;
                         link_preview: import("zod").ZodObject<{
@@ -824,10 +855,23 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"mention">;
                     mention: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"custom_emoji">;
+                        custom_emoji: import("zod").ZodObject<{
+                            id: import("zod").ZodUUID;
+                            name: import("zod").ZodString;
+                            url: import("zod").ZodURL;
+                        }, import("zod/v4/core").$strip>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                         type: import("zod").ZodLiteral<"database">;
                         database: import("zod").ZodObject<{
                             id: import("zod").ZodUUID;
                         }, import("zod/v4/core").$strip>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"data_source">;
+                        data_source: import("zod").ZodObject<{
+                            id: import("zod").ZodUUID;
+                            database_id: import("zod").ZodOptional<import("zod").ZodUUID>;
+                        }, import("zod/v4/core").$strip>;
                     }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                         type: import("zod").ZodLiteral<"date">;
                         date: import("zod").ZodObject<{
@@ -835,6 +879,11 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
                             end: import("zod").ZodNullable<import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>>;
                             time_zone: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
                         }, import("zod/v4/core").$strip>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"link_mention">;
+                        link_mention: import("zod").ZodObject<{
+                            href: import("zod").ZodString;
+                        }, import("zod/v4/core").$loose>;
                     }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                         type: import("zod").ZodLiteral<"link_preview">;
                         link_preview: import("zod").ZodObject<{

package/dist/client.d.ts

@@ -49,10 +49,40 @@ export declare class NotionClient {
      * Retry automatically on rate-limited and overloaded responses.
      */
     request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Send a `multipart/form-data` `POST` to a Notion file-upload URL. Reuses the
+     * configured `fetch` and the request timeout. Does not retry. Does not set
+     * `Content-Type`, so `fetch` adds the multipart boundary.
+     *
+     * @param uploadUrl - The absolute `upload_url` from `fileUploads.initiate()`.
+     * @param form - A `FormData` body with the file bytes under the `file` key.
+     * @throws {NotionValidationError} If `uploadUrl` is not a valid `https` URL.
+     * @throws {NotionAPIError} If the endpoint returns an error response.
+     * @throws {NotionRequestTimeoutError} If the request exceeds the timeout.
+     * @throws {NotionNetworkError} If a network problem blocks the request.
+     */
+    sendFileUpload(uploadUrl: string, form: FormData): Promise<void>;
     /**
      * Send one HTTP request to the Notion API.
      */
     private makeRequest;
+    /**
+     * Call the configured `fetch` with an abort timeout of `timeoutMs`.
+     * Clear the timer as soon as the response headers arrive or the request fails.
+     */
+    private fetchWithTimeout;
+    /**
+     * Map a transport-layer failure to the matching SDK error and throw it.
+     * Rethrow a `NotionAPIError` unchanged. Map an `AbortError` to
+     * `NotionRequestTimeoutError`. Map any other `Error` to `NotionNetworkError`.
+     */
+    private mapTransportError;
+    /**
+     * Assert that `url` is a valid `https` URL. The SDK sends the API token in the
+     * `Authorization` header of a file upload. Reject a plaintext `http` URL so the
+     * token never travels unencrypted.
+     */
+    private assertHttpsUrl;
     /**
      * Calculate a fallback retry delay with exponential backoff.
      * Use this delay when the response has no `Retry-After` header.
@@ -68,8 +98,9 @@ export declare class NotionClient {
      */
     private buildUrl;
     /**
-     * Parse the `Retry-After` response header into milliseconds.
-     * Return `undefined` if the header is missing or not a valid non-negative number.
+     * Parse the `Retry-After` response header into milliseconds, clamped to
+     * {@link MAX_RETRY_DELAY_MS}. Return `undefined` if the header is missing or
+     * not a valid non-negative number.
      */
     private parseRetryAfterHeader;
     /**