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

package/README.md

@@ -14,12 +14,12 @@ A type-safe TypeScript SDK for the Notion API with Zod validation, OOP models, a
 
 - **Type-safe** Zod v4 runtime validation on every API response; full TypeScript declarations
 - **Complete API coverage** Pages, Blocks, Databases, Data Sources, Comments, Search, Users, File Uploads, Async Tasks, Custom Emojis, Views
-- **Ergonomic helpers** `block`, `richText`, `filter`, `sort`, `prop`, `parent`, `icon`, `cover`, `paginate` factories and a `webhook` signature-verification helper eliminate verbose JSON and boilerplate
+- **Ergonomic helpers** `block`, `richText`, `filter`, `sort`, `prop`, `parent`, `icon`, `cover`, and `notionFile` factories, plus a `webhook` signature-verification helper, eliminate verbose JSON and boilerplate
 - **OOP models** `Page`, `Block`, `Database`, `User`, `Comment`, `DataSource`, `FileUpload`, `RichText`, `AsyncTask`, `CustomEmoji`, `View` with convenience methods
 - **Automatic pagination** `paginate()`, `paginateIterator()`, and `paginateWithMetadata()` helpers automatically fetch all pages, plus `iterateAllDataSourceRows()`/`collectAllDataSourceRows()` to work around the 10,000-result query cap
 - **Automatic rate limiting** Respects `Retry-After` header with exponential backoff fallback (configurable)
 - **Client-side size validation** Enforces Notion API size limits before sending requests
-- **Zero bloat** Single runtime dependency (`zod`); uses built-in `fetch` (Node 18+)
+- **Zero bloat** Single runtime dependency (`zod`); uses built-in `fetch` (Node 22+)
 
 ## Installation
 
@@ -29,7 +29,7 @@ npm install @visus-io/notion-sdk-ts
 bun add @visus-io/notion-sdk-ts
 ```
 
-**Requirements:** Node.js 18+ or Bun 1.3.10+ (uses native `fetch`)
+**Requirements:** Node.js 22+ or Bun 1.4.0+ (uses native `fetch`)
 
 ## Quick Start
 
@@ -76,92 +76,16 @@ const results = await notion.databases.query('database-id', {
 
 ## Documentation
 
-Comprehensive documentation is available in the [**GitHub Wiki**](https://github.com/visus-io/notion-sdk-ts/wiki):
+Full documentation is hosted at [nts.projects.visus.io](https://nts.projects.visus.io). It includes guides and a generated API reference. Source lives in [`docs/`](./docs). It has its own dependencies, separate from the root project. Install them once, then run the site locally:
 
-### Getting Started
-
-- [**Getting Started**](https://github.com/visus-io/notion-sdk-ts/wiki/Getting-Started) - Installation, quick start, and basic configuration
-- [**Migration Guide**](https://github.com/visus-io/notion-sdk-ts/wiki/Migration-Guide) - Migrating between API versions
-- [**Common Use Cases**](https://github.com/visus-io/notion-sdk-ts/wiki/Common-Use-Cases) - Practical examples and workflows
-
-### Core Concepts
-
-- [**Helpers**](https://github.com/visus-io/notion-sdk-ts/wiki/Helpers) - Rich Text, Block Builder, Properties, Filters, Sorting
-- [**Models**](https://github.com/visus-io/notion-sdk-ts/wiki/Models) - Page, Block, Database, DataSource, User, Comment, FileUpload
-- [**API Reference**](https://github.com/visus-io/notion-sdk-ts/wiki/API-Reference) - Complete API endpoint documentation
-
-### Configuration & Advanced Topics
-
-- [**Configuration & Features**](https://github.com/visus-io/notion-sdk-ts/wiki/Configuration) - Client options, rate limiting, retries
-- [**Error Handling**](https://github.com/visus-io/notion-sdk-ts/wiki/Error-Handling) - Error types, codes, and handling patterns
-- [**Pagination**](https://github.com/visus-io/notion-sdk-ts/wiki/Pagination) - Automatic pagination helpers
-- [**Request Size Limits**](https://github.com/visus-io/notion-sdk-ts/wiki/Request-Size-Limits) - Notion API size limits
-
-### Development
-
-- [**TypeScript Support**](https://github.com/visus-io/notion-sdk-ts/wiki/TypeScript-Support) - Types, schemas, and type safety
-- [**Development & Contributing**](https://github.com/visus-io/notion-sdk-ts/wiki/Development) - Project structure and architecture
-
-## Migration Notice
-
-**This SDK now targets Notion API version `2026-03-11`** (upgraded from `2025-09-03` in v3.x; originally `2022-06-28` in v1.x). The API version is fixed — it cannot be overridden via client options.
-
-### Key Changes (v3.x — 2026-03-11)
-
-- **`archived` → `in_trash`**: Field renamed across all schemas, models, and API request bodies
-- **`after` → `position` object**: `blocks.children.append()` now accepts a typed `position` union
-- **`transcription` → `meeting_notes`**: Block type and helper renamed (`block.meetingNotes()` is itself now deprecated — meeting-notes blocks are server-managed, not client-constructed)
-- **`notionVersion` removed**: Use the exported `NOTION_VERSION` constant to inspect the target version
-
-### Quick Migration Example (v2.x → v3.x)
-
-```typescript
-// OLD (v2.x / 2025-09-03)
-console.log(page.archived);
-await notion.blocks.children.append('page-id', {
-  children: [block.paragraph('text')],
-  after: 'block-id',
-});
-block.transcription('Transcription text');
-
-// NEW (v3.x / 2026-03-11)
-import { NOTION_VERSION } from '@visus-io/notion-sdk-ts';
-console.log(page.inTrash);
-await notion.blocks.children.append('page-id', {
-  children: [block.paragraph('text')],
-  position: { type: 'after_block', after_block: { id: 'block-id' } },
-});
-// Meeting notes are server-managed — read them instead of constructing them:
-await notion.blocks.meetingNotes.query();
+```bash
+bun run docs:install
+bun run docs:dev
 ```
 
-### Key Changes (v2.x — 2025-09-03)
-
-- **Database creation**: Properties moved to `initial_data_source.properties`
-- **Database updates**: Use Data Sources API for property changes
-- **Page creation**: Requires both data source ID and database ID
-- **Search API**: Returns `DataSource` objects instead of `Database`
-
-### Quick Migration Example (v1.x → v2.x)
-
-```typescript
-// OLD (v1.x / 2022-06-28)
-await notion.pages.create({
-  parent: parent.database('database-id'),
-  properties: { Name: prop.title('Task') },
-});
-
-// NEW (v2.x / 2025-09-03)
-const db = await notion.databases.retrieve('database-id');
-const dataSourceId = db.dataSources[0].id;
-
-await notion.pages.create({
-  parent: parent.dataSource(dataSourceId, db.id),
-  properties: { Name: prop.title('Task') },
-});
-```
+## Migration Notice
 
-See the [**Migration Guide**](https://github.com/visus-io/notion-sdk-ts/wiki/Migration-Guide) for complete details.
+**This SDK now targets Notion API version `2026-03-11`** (upgraded from `2025-09-03` in v3.x; originally `2022-06-28` in v1.x). The API version is fixed — it cannot be overridden via client options. See the [Migration Guide](./docs/src/content/docs/migration-guide.md) for complete upgrade details.
 
 ## Development
 
@@ -188,15 +112,23 @@ bun run test:coverage    # Coverage report
 bun run lint             # ESLint
 bun run lint:fix         # Auto-fix
 bun run format           # Prettier
+
+bun run docs:install     # Install the docs site's dependencies (run once, or after they change)
+bun run docs:dev         # Run the docs site locally
+bun run docs:build       # Build the docs site
 ```
 
-> **Note:** While this project uses Bun for development, the published package works with both Node.js 18+ and Bun 1.3.10+.
+> **Note:** While this project uses Bun for development, the published package works with both Node.js 22+ and Bun 1.4.0+.
+
+See [**ARCHITECTURE.md**](./ARCHITECTURE.md) for project structure and architecture.
+
+## Contributing
 
-See [**Development & Contributing**](https://github.com/visus-io/notion-sdk-ts/wiki/Development) for more details.
+Contributions are welcome! See [**CONTRIBUTING.md**](./CONTRIBUTING.md) for how to get started.
 
 ## Links
 
-- [**Documentation Wiki**](https://github.com/visus-io/notion-sdk-ts/wiki)
+- [**Documentation**](https://nts.projects.visus.io)
 - [**GitHub Repository**](https://github.com/visus-io/notion-sdk-ts)
 - [**npm Package**](https://www.npmjs.com/package/@visus-io/notion-sdk-ts)
 - [**Notion API Documentation**](https://developers.notion.com/reference/intro)

package/dist/api/asyncTasks.api.d.ts

@@ -11,6 +11,8 @@ export interface PollAsyncTaskOptions {
 }
 /**
  * Async Tasks API client for polling long-running Notion operations.
+ *
+ * @category Async Tasks
  */
 export declare class AsyncTasksAPI extends BaseAPI<NotionAsyncTask, AsyncTask> {
     protected readonly client: NotionClient;
@@ -56,9 +58,9 @@ export declare class AsyncTasksAPI extends BaseAPI<NotionAsyncTask, AsyncTask> {
      */
     retrieve(taskId: string): Promise<AsyncTask>;
     /**
-     * Poll an async task until it reaches a terminal status (succeeded or failed),
-     * waiting at least `poll_after_seconds` (from the response body, not a header)
-     * between polls, per the API's guidance.
+     * Poll an async task until it reaches a terminal status: succeeded or failed.
+     * Wait at least `poll_after_seconds` between each poll, per the API's guidance.
+     * This value comes from the response body, not a header.
      *
      * @param taskId - The ID of the async task to poll
      * @param options - Polling options

package/dist/api/asyncTasks.api.js

@@ -10,6 +10,8 @@ function sleep(ms) {
 }
 /**
  * Async Tasks API client for polling long-running Notion operations.
+ *
+ * @category Async Tasks
  */
 class AsyncTasksAPI extends base_api_1.BaseAPI {
     constructor(client) {
@@ -32,9 +34,9 @@ class AsyncTasksAPI extends base_api_1.BaseAPI {
         return this.retrieveResource(`/async_tasks/${taskId}`);
     }
     /**
-     * Poll an async task until it reaches a terminal status (succeeded or failed),
-     * waiting at least `poll_after_seconds` (from the response body, not a header)
-     * between polls, per the API's guidance.
+     * Poll an async task until it reaches a terminal status: succeeded or failed.
+     * Wait at least `poll_after_seconds` between each poll, per the API's guidance.
+     * This value comes from the response body, not a header.
      *
      * @param taskId - The ID of the async task to poll
      * @param options - Polling options

package/dist/api/base.api.d.ts

@@ -1,8 +1,10 @@
 import type { NotionClient } from '../client';
+import { TRUSTED } from '../models/base.model';
 import type { PaginatedList, PaginatedListType, PaginationParameters } from '../schemas';
 import type * as z from 'zod';
 /**
- * Configuration for API resource operations, including paths, schemas, and model classes.
+ * Configuration for API resource operations. It defines the schema, model class,
+ * and list type that parse and wrap API responses.
  *
  * @template TResponse - The raw response type from the API
  * @template TModel - The model class type that wraps the response
@@ -11,7 +13,7 @@ interface ResourceConfig<TResponse, TModel> {
     /** Zod schema to validate the API response */
     schema: z.ZodSchema<TResponse>;
     /** Model class constructor to wrap the validated response */
-    ModelClass: new (data: TResponse) => TModel;
+    ModelClass: new (data: TResponse, trusted?: typeof TRUSTED) => TModel;
     /** Type of items in the paginated list (used for typing the results) */
     listType?: PaginatedListType;
 }
@@ -24,7 +26,15 @@ interface ResourceConfig<TResponse, TModel> {
 export declare abstract class BaseAPI<TResponse, TModel> {
     protected readonly client: NotionClient;
     protected abstract config: ResourceConfig<TResponse, TModel>;
+    private cachedPaginatedListSchema?;
     protected constructor(client: NotionClient);
+    /**
+     * Return whether a query object has at least one entry.
+     *
+     * @param query - Query object to check
+     * @returns `true` if `query` has at least one own enumerable key
+     */
+    private hasQueryParams;
     /**
      * Delete a resource via DELETE request.
      *
@@ -49,8 +59,9 @@ export declare abstract class BaseAPI<TResponse, TModel> {
     /**
      * Build filter_properties query parameter from an array of property names.
      *
-     * Notion sends this as a repeated query key (`filter_properties=a&filter_properties=b`),
-     * not a single comma-joined value, so the array is preserved for `NotionClient` to expand.
+     * Notion sends this parameter as a repeated query key
+     * (`filter_properties=a&filter_properties=b`), not as a single comma-joined value.
+     * This method keeps the array intact so `NotionClient` can expand it.
      *
      * @param filterProperties - Optional array of property names to include in the response
      * @returns Query object with filter_properties parameter for API requests

package/dist/api/base.api.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseAPI = void 0;
+const base_model_1 = require("../models/base.model");
 const schemas_1 = require("../schemas");
 const validation_1 = require("../validation");
 /**
@@ -13,6 +14,15 @@ class BaseAPI {
     constructor(client) {
         this.client = client;
     }
+    /**
+     * Return whether a query object has at least one entry.
+     *
+     * @param query - Query object to check
+     * @returns `true` if `query` has at least one own enumerable key
+     */
+    hasQueryParams(query) {
+        return !!query && Object.keys(query).length > 0;
+    }
     /**
      * Delete a resource via DELETE request.
      *
@@ -52,8 +62,9 @@ class BaseAPI {
     /**
      * Build filter_properties query parameter from an array of property names.
      *
-     * Notion sends this as a repeated query key (`filter_properties=a&filter_properties=b`),
-     * not a single comma-joined value, so the array is preserved for `NotionClient` to expand.
+     * Notion sends this parameter as a repeated query key
+     * (`filter_properties=a&filter_properties=b`), not as a single comma-joined value.
+     * This method keeps the array intact so `NotionClient` can expand it.
      *
      * @param filterProperties - Optional array of property names to include in the response
      * @returns Query object with filter_properties parameter for API requests
@@ -127,7 +138,7 @@ class BaseAPI {
         const response = await this.client.request({
             method: 'GET',
             path: resourcePath,
-            query: Object.keys(query || {}).length > 0 ? query : undefined,
+            query: this.hasQueryParams(query) ? query : undefined,
         });
         return this.parseAndWrap(response);
     }
@@ -148,7 +159,7 @@ class BaseAPI {
         const response = await this.client.request({
             method: 'GET',
             path: resourcePath,
-            query: Object.keys(query || {}).length > 0 ? query : undefined,
+            query: this.hasQueryParams(query) ? query : undefined,
         });
         return this.parsePaginatedList(response);
     }
@@ -185,7 +196,7 @@ class BaseAPI {
      */
     parseAndWrap(response) {
         const parsed = this.config.schema.parse(response);
-        return new this.config.ModelClass(parsed);
+        return new this.config.ModelClass(parsed, base_model_1.TRUSTED);
     }
     /**
      * Parse a paginated list response and wrap each item in the specified model class.
@@ -198,11 +209,11 @@ class BaseAPI {
      * return this.parsePaginatedList(response);
      */
     parsePaginatedList(response) {
-        const schema = (0, schemas_1.paginatedListSchema)(this.config.schema);
-        const parsed = schema.parse(response);
+        this.cachedPaginatedListSchema ??= (0, schemas_1.paginatedListSchema)(this.config.schema);
+        const parsed = this.cachedPaginatedListSchema.parse(response);
         return {
             object: 'list',
-            results: parsed.results.map((item) => new this.config.ModelClass(item)),
+            results: parsed.results.map((item) => new this.config.ModelClass(item, base_model_1.TRUSTED)),
             next_cursor: parsed.next_cursor,
             has_more: parsed.has_more,
             type: this.config.listType || 'unknown',

package/dist/api/blocks.api.d.ts

@@ -80,6 +80,8 @@ export interface UpdateBlockOptions {
 }
 /**
  * Blocks API client for working with Notion blocks.
+ *
+ * @category Blocks
  */
 export declare class BlocksAPI extends BaseAPI<NotionBlock, Block> {
     protected readonly client: NotionClient;

package/dist/api/blocks.api.js

@@ -3,10 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BlocksAPI = 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");
 /**
  * Blocks API client for working with Notion blocks.
+ *
+ * @category Blocks
  */
 class BlocksAPI extends base_api_1.BaseAPI {
     constructor(client) {
@@ -53,7 +56,7 @@ class BlocksAPI extends base_api_1.BaseAPI {
                 const listSchema = (0, schemas_1.paginatedListSchema)(schemas_1.blockSchema);
                 const parsed = listSchema.parse(response);
                 return {
-                    results: parsed.results.map((block) => new models_1.Block(block)),
+                    results: parsed.results.map((block) => new models_1.Block(block, base_model_1.TRUSTED)),
                     next_cursor: parsed.next_cursor,
                     has_more: parsed.has_more,
                 };
@@ -92,7 +95,7 @@ class BlocksAPI extends base_api_1.BaseAPI {
                 });
                 const parsed = schemas_1.meetingNotesQueryResponseSchema.parse(response);
                 return {
-                    results: parsed.results.map((b) => new models_1.Block(b)),
+                    results: parsed.results.map((b) => new models_1.Block(b, base_model_1.TRUSTED)),
                     hasMore: parsed.has_more,
                     requestStatus: parsed.request_status,
                 };

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

@@ -56,6 +56,8 @@ export interface UpdateCommentOptions {
 }
 /**
  * Comments API client for working with Notion comments.
+ *
+ * @category Comments
  */
 export declare class CommentsAPI extends BaseAPI<NotionComment, Comment> {
     protected readonly client: NotionClient;

package/dist/api/comments.api.js

@@ -19,6 +19,8 @@ function validateCommentContent(options) {
 }
 /**
  * Comments API client for working with Notion comments.
+ *
+ * @category Comments
  */
 class CommentsAPI extends base_api_1.BaseAPI {
     constructor(client) {

package/dist/api/customEmojis.api.d.ts

@@ -11,6 +11,8 @@ export interface ListCustomEmojisOptions extends PaginationParameters {
 }
 /**
  * Custom Emojis API client for working with Notion workspace custom emojis.
+ *
+ * @category Custom Emoji & Icons
  */
 export declare class CustomEmojisAPI extends BaseAPI<NotionCustomEmoji, CustomEmoji> {
     protected readonly client: NotionClient;

package/dist/api/customEmojis.api.js

@@ -6,6 +6,8 @@ const models_1 = require("../models");
 const base_api_1 = require("./base.api");
 /**
  * Custom Emojis API client for working with Notion workspace custom emojis.
+ *
+ * @category Custom Emoji & Icons
  */
 class CustomEmojisAPI extends base_api_1.BaseAPI {
     constructor(client) {

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

@@ -52,7 +52,7 @@ export interface ListDataSourceTemplatesOptions extends PaginationParameters {
 }
 /**
  * Filter condition for data source queries.
- * This is a simplified type - the actual Notion API supports many filter types.
+ * This type is simplified. The Notion API supports many more filter types.
  * See: https://developers.notion.com/reference/filter-data-source-entries
  */
 export type DataSourceFilter = Record<string, unknown>;
@@ -89,8 +89,8 @@ export interface QueryDataSourceOptions extends PaginationParameters {
     /**
      * Whether to return only trashed pages (true) or only non-trashed pages (false).
      *
-     * @deprecated Use `is_archived` instead. Kept as an alias forwarded into
-     * `is_archived`; if both are provided, `is_archived` takes precedence.
+     * @deprecated Use `is_archived` instead. This field is an alias that forwards
+     * into `is_archived`. If you provide both fields, `is_archived` takes precedence.
      */
     in_trash?: boolean;
 }
@@ -99,6 +99,8 @@ export interface QueryDataSourceOptions extends PaginationParameters {
  *
  * Data sources are individual tables of data that live under a Notion database.
  * As of API version 2025-09-03, data sources have their own API endpoints.
+ *
+ * @category Databases & Data Sources
  */
 export declare class DataSourcesAPI extends BaseAPI<NotionDataSource, DataSource> {
     protected readonly client: NotionClient;
@@ -915,6 +917,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/dataSources.api.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DataSourcesAPI = 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");
 /**
@@ -10,6 +11,8 @@ const base_api_1 = require("./base.api");
  *
  * Data sources are individual tables of data that live under a Notion database.
  * As of API version 2025-09-03, data sources have their own API endpoints.
+ *
+ * @category Databases & Data Sources
  */
 class DataSourcesAPI extends base_api_1.BaseAPI {
     constructor(client) {
@@ -103,7 +106,7 @@ class DataSourcesAPI extends base_api_1.BaseAPI {
         const parsed = listSchema.parse(response);
         return {
             object: 'list',
-            results: parsed.results.map((page) => new models_1.Page(page)),
+            results: parsed.results.map((page) => new models_1.Page(page, base_model_1.TRUSTED)),
             next_cursor: parsed.next_cursor,
             has_more: parsed.has_more,
             type: 'page',

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';
 /**
@@ -11,7 +11,7 @@ export interface RetrieveDatabaseOptions {
 }
 /**
  * Filter condition for database queries.
- * This is a simplified type - the actual Notion API supports many filter types.
+ * This type is simplified. The Notion API supports many more filter types.
  * See: https://developers.notion.com/reference/post-database-query-filter
  */
 export type DatabaseFilter = Record<string, unknown>;
@@ -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 are created with an initial_data_source
- * containing the properties schema, rather than properties at the top level.
+ * 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) */
@@ -81,8 +86,8 @@ export interface CreateDatabaseOptions {
 }
 /**
  * Options for updating a database.
- * As of API version 2025-09-03, properties are managed at the data source level.
- * Use the DataSourcesAPI to update properties.
+ * As of API version 2025-09-03, manage properties at the data source level.
+ * Use DataSourcesAPI to update properties.
  */
 export interface UpdateDatabaseOptions {
     /** Update the database title */
@@ -102,6 +107,8 @@ export interface UpdateDatabaseOptions {
 }
 /**
  * Databases API client for working with Notion databases.
+ *
+ * @category Databases & Data Sources
  */
 export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
     protected readonly client: NotionClient;
@@ -619,6 +626,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";
@@ -650,6 +662,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

@@ -3,10 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DatabasesAPI = 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");
 /**
  * Databases API client for working with Notion databases.
+ *
+ * @category Databases & Data Sources
  */
 class DatabasesAPI extends base_api_1.BaseAPI {
     constructor(client) {
@@ -60,7 +63,7 @@ class DatabasesAPI extends base_api_1.BaseAPI {
         const parsed = listSchema.parse(response);
         return {
             object: 'list',
-            results: parsed.results.map((page) => new models_1.Page(page)),
+            results: parsed.results.map((page) => new models_1.Page(page, base_model_1.TRUSTED)),
             next_cursor: parsed.next_cursor,
             has_more: parsed.has_more,
             type: 'page',
@@ -71,19 +74,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

@@ -19,6 +19,8 @@ export interface InitiateFileUploadOptions {
 export type FileData = Buffer | ArrayBuffer | Blob | ReadableStream;
 /**
  * FileUploads API client for uploading files to Notion.
+ *
+ * @category File Uploads
  */
 export declare class FileUploadsAPI extends BaseAPI<NotionFileUpload, FileUpload> {
     protected readonly client: NotionClient;
@@ -55,7 +57,8 @@ export declare class FileUploadsAPI extends BaseAPI<NotionFileUpload, FileUpload
     initiate(options: InitiateFileUploadOptions): Promise<FileUpload>;
     /**
      * 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
@@ -74,9 +77,9 @@ export declare class FileUploadsAPI extends BaseAPI<NotionFileUpload, FileUpload
      */
     complete(completeUrl: string): Promise<FileUpload>;
     /**
-     * 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.
      */
     private static toRequestPath;
     /**