@visus-io/notion-sdk-ts 2.1.0 → 3.0.2

package/README.md

@@ -1,13 +1,12 @@
 # @visus-io/notion-sdk-ts
 
 [![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/visus-io/notion-sdk-ts/ci.yml?style=for-the-badge&logo=github)](https://github.com/visus-io/notion-sdk-ts/actions/workflows/ci.yaml)
-
-[![Sonar Quality Gate](https://img.shields.io/sonar/quality_gate/visus%3Anotion-sdk-ts?server=https%3A%2F%2Fsonarcloud.io&style=for-the-badge&logo=sonarcloud&logoColor=white)](https://sonarcloud.io/summary/overall?id=visus%3Anotion-sdk-ts)
-[![Sonar Coverage](https://img.shields.io/sonar/coverage/visus%3Anotion-sdk-ts?server=https%3A%2F%2Fsonarcloud.io&style=for-the-badge&logo=sonarcloud&logoColor=white)](https://sonarcloud.io/summary/overall?id=visus%3Anotion-sdk-ts)
+[![Sonar Quality Gate](https://img.shields.io/sonar/quality_gate/visus%3Anotion-sdk-ts?server=https%3A%2F%2Fsonarcloud.io&style=for-the-badge&logo=sonar&logoColor=white)](https://sonarcloud.io/summary/overall?id=visus%3Anotion-sdk-ts)
+[![Sonar Coverage](https://img.shields.io/sonar/coverage/visus%3Anotion-sdk-ts?server=https%3A%2F%2Fsonarcloud.io&style=for-the-badge&logo=sonar&logoColor=white)](https://sonarcloud.io/summary/overall?id=visus%3Anotion-sdk-ts)
 
 [![NPM Version](https://img.shields.io/npm/v/%40visus-io%2Fnotion-sdk-ts?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@visus-io/notion-sdk-ts)
 ![NPM Downloads](https://img.shields.io/npm/dm/%40visus-io%2Fnotion-sdk-ts?style=for-the-badge&logo=npm)
-![GitHub](https://img.shields.io/github/license/visus-io/notion-sdk-ts?style=for-the-badge)
+![Static Badge](https://img.shields.io/badge/license-mit-green?style=for-the-badge)
 
 A type-safe TypeScript SDK for the Notion API with Zod validation, OOP models, and ergonomic helpers.
 
@@ -82,7 +81,7 @@ Comprehensive documentation is available in the [**GitHub Wiki**](https://github
 ### 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 to API version 2025-09-03
+- [**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
@@ -105,25 +104,53 @@ Comprehensive documentation is available in the [**GitHub Wiki**](https://github
 
 ## Migration Notice
 
-**This SDK now defaults to Notion API version `2025-09-03`** (previously `2022-06-28`). This version introduces breaking changes for multi-source database support.
+**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
+- **`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' } },
+});
+block.meetingNotes('Meeting notes text');
+```
 
-### Key Changes
+### 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`
+- **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
+### Quick Migration Example (v1.x → v2.x)
 
 ```typescript
-// OLD (2022-06-28)
+// OLD (v1.x / 2022-06-28)
 await notion.pages.create({
   parent: parent.database('database-id'),
   properties: { Name: prop.title('Task') },
 });
 
-// NEW (2025-09-03)
+// NEW (v2.x / 2025-09-03)
 const db = await notion.databases.retrieve('database-id');
 const dataSourceId = db.dataSources[0].id;
 

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

@@ -35,18 +35,6 @@ export declare abstract class BaseAPI<TResponse, TModel> {
      * return this.deleteResource(`/pages/${pageId}`);
      */
     protected deleteResource(resourcePath: string): Promise<TModel>;
-    /**
-     * Build filter_properties body parameter from an array of property names.
-     *
-     * @param filterProperties - Optional array of property names to include in the response
-     * @returns Body object with filter_properties parameter for API requests
-     *
-     * @throws {NotionValidationError} If array exceeds LIMITS.ARRAY_ELEMENTS
-     * @example
-     * const body = this.buildFilterPropertiesBody(['Name', 'Status']);
-     * // body will be: { filter_properties: ['Name', 'Status'] }
-     */
-    protected buildFilterPropertiesBody(filterProperties?: string[]): Record<string, unknown>;
     /**
      * Build pagination body parameters from PaginationParameters.
      *
@@ -61,6 +49,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.
+     *
      * @param filterProperties - Optional array of property names to include in the response
      * @returns Query object with filter_properties parameter for API requests
      *
@@ -68,9 +59,9 @@ export declare abstract class BaseAPI<TResponse, TModel> {
      *
      * @example
      * const query = this.buildFilterPropertiesQuery(['Name', 'Status']);
-     * // query will be: { filter_properties: 'Name,Status' }
+     * // query will be: { filter_properties: ['Name', 'Status'] }
      */
-    protected buildFilterPropertiesQuery(filterProperties?: string[]): Record<string, string>;
+    protected buildFilterPropertiesQuery(filterProperties?: string[]): Record<string, string[]>;
     /**
      * Build pagination query parameters from PaginationParameters.
      *
@@ -106,7 +97,7 @@ export declare abstract class BaseAPI<TResponse, TModel> {
      * @example
      * return this.retrieveResource(`/pages/${pageId}`, query);
      */
-    protected retrieveResource(resourcePath: string, query?: Record<string, string>): Promise<TModel>;
+    protected retrieveResource(resourcePath: string, query?: Record<string, string | string[]>): Promise<TModel>;
     /**
      * Retrieve a paginated list of resources via GET request.
      *
@@ -120,7 +111,7 @@ export declare abstract class BaseAPI<TResponse, TModel> {
      *   { page_size: '50' },
      * );
      */
-    protected listResources(resourcePath: string, query?: Record<string, string>): Promise<PaginatedList<TModel>>;
+    protected listResources(resourcePath: string, query?: Record<string, string | string[]>): Promise<PaginatedList<TModel>>;
     /**
      * Update an existing resource via PATCH request.
      *

package/dist/api/base.api.js

@@ -29,25 +29,6 @@ class BaseAPI {
         });
         return this.parseAndWrap(response);
     }
-    /**
-     * Build filter_properties body parameter from an array of property names.
-     *
-     * @param filterProperties - Optional array of property names to include in the response
-     * @returns Body object with filter_properties parameter for API requests
-     *
-     * @throws {NotionValidationError} If array exceeds LIMITS.ARRAY_ELEMENTS
-     * @example
-     * const body = this.buildFilterPropertiesBody(['Name', 'Status']);
-     * // body will be: { filter_properties: ['Name', 'Status'] }
-     */
-    buildFilterPropertiesBody(filterProperties) {
-        const body = {};
-        if (filterProperties) {
-            (0, validation_1.validateArrayLength)(filterProperties, validation_1.LIMITS.ARRAY_ELEMENTS, 'filter_properties');
-            body.filter_properties = filterProperties;
-        }
-        return body;
-    }
     /**
      * Build pagination body parameters from PaginationParameters.
      *
@@ -71,6 +52,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.
+     *
      * @param filterProperties - Optional array of property names to include in the response
      * @returns Query object with filter_properties parameter for API requests
      *
@@ -78,13 +62,13 @@ class BaseAPI {
      *
      * @example
      * const query = this.buildFilterPropertiesQuery(['Name', 'Status']);
-     * // query will be: { filter_properties: 'Name,Status' }
+     * // query will be: { filter_properties: ['Name', 'Status'] }
      */
     buildFilterPropertiesQuery(filterProperties) {
         const query = {};
         if (filterProperties) {
             (0, validation_1.validateArrayLength)(filterProperties, validation_1.LIMITS.ARRAY_ELEMENTS, 'filter_properties');
-            query.filter_properties = filterProperties.join(',');
+            query.filter_properties = filterProperties;
         }
         return query;
     }

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

@@ -1,5 +1,5 @@
 import type { NotionClient } from '../client';
-import { type NotionBlock, type PaginatedList, type PaginationParameters } from '../schemas';
+import { type BlockPosition, type NotionBlock, type PaginatedList, type PaginationParameters } from '../schemas';
 import { Block } from '../models';
 import { BaseAPI } from './base.api';
 /**
@@ -12,11 +12,11 @@ export interface RetrieveBlockOptions {
 /**
  * Options for appending children to a block.
  */
-export interface AppendBlockChildrenOptions extends PaginationParameters {
+export interface AppendBlockChildrenOptions {
     /** Array of block objects to append (max 100) */
     children: unknown[];
-    /** Position to insert the children */
-    after?: string;
+    /** Position to insert the children (default: end) */
+    position?: BlockPosition;
 }
 /**
  * Response from appending children to a block.
@@ -35,8 +35,8 @@ export interface AppendBlockChildrenResponse {
 export interface UpdateBlockOptions {
     /** Block type-specific properties to update (depends on block type) */
     [blockType: string]: unknown;
-    /** Archive or restore the block */
-    archived?: boolean;
+    /** Move to trash or restore from trash */
+    in_trash?: boolean;
 }
 /**
  * Blocks API client for working with Notion blocks.
@@ -95,7 +95,7 @@ export declare class BlocksAPI extends BaseAPI<NotionBlock, Block> {
                 template: "template";
                 to_do: "to_do";
                 toggle: "toggle";
-                transcription: "transcription";
+                meeting_notes: "meeting_notes";
                 unsupported: "unsupported";
                 video: "video";
             }>;
@@ -165,7 +165,6 @@ export declare class BlocksAPI extends BaseAPI<NotionBlock, Block> {
                 object: import("zod").ZodLiteral<"user">;
                 id: import("zod").ZodUUID;
             }, import("zod/v4/core").$strip>]>;
-            archived: import("zod").ZodBoolean;
             in_trash: import("zod").ZodBoolean;
             has_children: import("zod").ZodBoolean;
             audio: import("zod").ZodOptional<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
@@ -3706,7 +3705,7 @@ export declare class BlocksAPI extends BaseAPI<NotionBlock, Block> {
                 }>;
                 children: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>>;
             }, import("zod/v4/core").$strip>>;
-            transcription: import("zod").ZodOptional<import("zod").ZodObject<{
+            meeting_notes: import("zod").ZodOptional<import("zod").ZodObject<{
                 rich_text: import("zod").ZodArray<import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"text">;
                     text: import("zod").ZodObject<{

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

@@ -31,8 +31,6 @@ export interface UpdateDataSourceOptions {
     icon?: unknown;
     /** Update the data source properties schema */
     properties?: Record<string, unknown>;
-    /** Archive or restore the data source */
-    archived?: boolean;
     /** Move to trash or restore from trash */
     in_trash?: boolean;
     /** Move the data source to a different database */
@@ -77,12 +75,17 @@ export interface QueryDataSourceOptions extends PaginationParameters {
     sorts?: DataSourceSort[];
     /** Filter properties to include in results */
     filter_properties?: string[];
-    /** Filter by archived status */
-    archived?: boolean;
-    /** Filter by trash status */
-    in_trash?: boolean;
     /** Filter by result type (for wikis) */
     result_type?: 'page' | 'data_source';
+    /** Whether to return only archived pages (true) or only non-archived pages (false, default) */
+    is_archived?: boolean;
+    /**
+     * 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.
+     */
+    in_trash?: boolean;
 }
 /**
  * Data Sources API client for working with Notion data sources.
@@ -870,7 +873,6 @@ export declare class DataSourcesAPI extends BaseAPI<NotionDataSource, DataSource
             url: import("zod").ZodURL;
             public_url: import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>;
             is_inline: import("zod").ZodBoolean;
-            archived: import("zod").ZodBoolean;
             in_trash: import("zod").ZodBoolean;
         }, import("zod/v4/core").$strip>;
         ModelClass: typeof DataSource;
@@ -918,31 +920,33 @@ export declare class DataSourcesAPI extends BaseAPI<NotionDataSource, DataSource
      */
     update(dataSourceId: string, options: UpdateDataSourceOptions): Promise<DataSource>;
     /**
-     * Archive a data source (convenience method).
+     * Move a data source to trash (convenience method).
      *
-     * @param dataSourceId - The ID of the data source to archive
-     * @returns The archived data source wrapped in a DataSource model
+     * @param dataSourceId - The ID of the data source to trash
+     * @returns The trashed data source wrapped in a DataSource model
      */
-    archive(dataSourceId: string): Promise<DataSource>;
+    trash(dataSourceId: string): Promise<DataSource>;
     /**
-     * Restore an archived data source (convenience method).
+     * Restore a data source from trash (convenience method).
      *
-     * @param dataSourceId - The ID of the data source to restore
+     * @param dataSourceId - The ID of the data source to restore from trash
      * @returns The restored data source wrapped in a DataSource model
      */
-    restore(dataSourceId: string): Promise<DataSource>;
+    untrash(dataSourceId: string): Promise<DataSource>;
     /**
-     * Move a data source to trash (convenience method).
+     * Move a data source to trash.
      *
+     * @deprecated Use {@link trash} instead.
      * @param dataSourceId - The ID of the data source to trash
      * @returns The trashed data source wrapped in a DataSource model
      */
-    trash(dataSourceId: string): Promise<DataSource>;
+    archive(dataSourceId: string): Promise<DataSource>;
     /**
-     * Restore a data source from trash (convenience method).
+     * Restore a trashed data source.
      *
-     * @param dataSourceId - The ID of the data source to restore from trash
+     * @deprecated Use {@link untrash} instead.
+     * @param dataSourceId - The ID of the data source to restore
      * @returns The restored data source wrapped in a DataSource model
      */
-    untrash(dataSourceId: string): Promise<DataSource>;
+    restore(dataSourceId: string): Promise<DataSource>;
 }

package/dist/api/dataSources.api.js

@@ -61,22 +61,21 @@ class DataSourcesAPI extends base_api_1.BaseAPI {
         if (options?.start_cursor) {
             body.start_cursor = options.start_cursor;
         }
-        if (options?.filter_properties) {
-            (0, validation_1.validateArrayLength)(options.filter_properties, validation_1.LIMITS.ARRAY_ELEMENTS, 'filter_properties');
-            body.filter_properties = options.filter_properties;
+        if (options?.in_trash !== undefined && options?.is_archived === undefined) {
+            console.warn('[notion-sdk-ts] QueryDataSourceOptions.in_trash is deprecated, use is_archived instead.');
         }
-        if (options?.archived !== undefined) {
-            body.archived = options.archived;
-        }
-        if (options?.in_trash !== undefined) {
-            body.in_trash = options.in_trash;
+        const isArchived = options?.is_archived ?? options?.in_trash;
+        if (isArchived !== undefined) {
+            body.is_archived = isArchived;
         }
         if (options?.result_type) {
             body.result_type = options.result_type;
         }
+        const query = this.buildFilterPropertiesQuery(options?.filter_properties);
         const response = await this.client.request({
             method: 'POST',
             path: `/data_sources/${dataSourceId}/query`,
+            query: Object.keys(query).length > 0 ? query : undefined,
             body: Object.keys(body).length > 0 ? body : undefined,
         });
         const listSchema = (0, schemas_1.paginatedListSchema)(schemas_1.pageSchema);
@@ -119,40 +118,42 @@ class DataSourcesAPI extends base_api_1.BaseAPI {
         return this.updateResource(`/data_sources/${dataSourceId}`, options);
     }
     /**
-     * Archive a data source (convenience method).
+     * Move a data source to trash (convenience method).
      *
-     * @param dataSourceId - The ID of the data source to archive
-     * @returns The archived data source wrapped in a DataSource model
+     * @param dataSourceId - The ID of the data source to trash
+     * @returns The trashed data source wrapped in a DataSource model
      */
-    async archive(dataSourceId) {
-        return this.update(dataSourceId, { archived: true });
+    async trash(dataSourceId) {
+        return this.update(dataSourceId, { in_trash: true });
     }
     /**
-     * Restore an archived data source (convenience method).
+     * Restore a data source from trash (convenience method).
      *
-     * @param dataSourceId - The ID of the data source to restore
+     * @param dataSourceId - The ID of the data source to restore from trash
      * @returns The restored data source wrapped in a DataSource model
      */
-    async restore(dataSourceId) {
-        return this.update(dataSourceId, { archived: false });
+    async untrash(dataSourceId) {
+        return this.update(dataSourceId, { in_trash: false });
     }
     /**
-     * Move a data source to trash (convenience method).
+     * Move a data source to trash.
      *
+     * @deprecated Use {@link trash} instead.
      * @param dataSourceId - The ID of the data source to trash
      * @returns The trashed data source wrapped in a DataSource model
      */
-    async trash(dataSourceId) {
-        return this.update(dataSourceId, { in_trash: true });
+    async archive(dataSourceId) {
+        return this.trash(dataSourceId);
     }
     /**
-     * Restore a data source from trash (convenience method).
+     * Restore a trashed data source.
      *
-     * @param dataSourceId - The ID of the data source to restore from trash
+     * @deprecated Use {@link untrash} instead.
+     * @param dataSourceId - The ID of the data source to restore
      * @returns The restored data source wrapped in a DataSource model
      */
-    async untrash(dataSourceId) {
-        return this.update(dataSourceId, { in_trash: false });
+    async restore(dataSourceId) {
+        return this.untrash(dataSourceId);
     }
 }
 exports.DataSourcesAPI = DataSourcesAPI;

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

@@ -52,7 +52,7 @@ export type CreateDatabaseParent = {
 };
 /**
  * Initial data source configuration for creating a database.
- * In API version 2025-09-03, databases are created with an initial data source.
+ * As of API version 2025-09-03, databases are created with an initial data source.
  */
 export interface InitialDataSource {
     /** Data source properties schema */
@@ -91,8 +91,6 @@ export interface UpdateDatabaseOptions {
     icon?: unknown;
     /** Update the database cover */
     cover?: unknown;
-    /** Archive or restore the database */
-    archived?: boolean;
     /** Move to trash or restore from trash */
     in_trash?: boolean;
     /** Whether the database is inline */
@@ -584,7 +582,6 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
                 block_id: import("zod").ZodUUID;
             }, import("zod/v4/core").$strip>], "type">;
             url: import("zod").ZodURL;
-            archived: import("zod").ZodBoolean;
             in_trash: import("zod").ZodBoolean;
             is_inline: import("zod").ZodBoolean;
             public_url: import("zod").ZodNullable<import("zod").ZodURL>;
@@ -624,7 +621,7 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
      */
     create(options: CreateDatabaseOptions): Promise<Database>;
     /**
-     * Update a database's properties, title, description, or archived status.
+     * Update a database's properties, title, description, or trash status.
      *
      * @param databaseId - The ID of the database to update
      * @param options - Options for updating the database
@@ -634,17 +631,25 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
      */
     update(databaseId: string, options: UpdateDatabaseOptions): Promise<Database>;
     /**
-     * Archive a database (convenience method).
+     * Move a database to trash (convenience method).
      *
-     * @param databaseId - The ID of the database to archive
-     * @returns The archived database wrapped in a Database model
+     * @param databaseId - The ID of the database to trash
+     * @returns The trashed database wrapped in a Database model
      */
-    archive(databaseId: string): Promise<Database>;
+    trash(databaseId: string): Promise<Database>;
     /**
-     * Restore an archived database (convenience method).
+     * Restore a trashed database (convenience method).
      *
      * @param databaseId - The ID of the database to restore
      * @returns The restored database wrapped in a Database model
      */
     restore(databaseId: string): Promise<Database>;
+    /**
+     * Move a database to trash (convenience method).
+     *
+     * @deprecated Use {@link trash} instead.
+     * @param databaseId - The ID of the database to trash
+     * @returns The trashed database wrapped in a Database model
+     */
+    archive(databaseId: string): Promise<Database>;
 }

package/dist/api/databases.api.js

@@ -48,11 +48,12 @@ class DatabasesAPI extends base_api_1.BaseAPI {
             ...(options?.filter ? { filter: options.filter } : {}),
             ...(options?.sorts ? { sorts: options.sorts } : {}),
             ...this.buildPaginationBody(options),
-            ...this.buildFilterPropertiesBody(options?.filter_properties),
         };
+        const query = this.buildFilterPropertiesQuery(options?.filter_properties);
         const response = await this.client.request({
             method: 'POST',
             path: `/databases/${databaseId}/query`,
+            query: Object.keys(query).length > 0 ? query : undefined,
             body: Object.keys(body).length > 0 ? body : undefined,
         });
         const listSchema = (0, schemas_1.paginatedListSchema)(schemas_1.pageSchema);
@@ -86,7 +87,7 @@ class DatabasesAPI extends base_api_1.BaseAPI {
         return this.createResource('/databases', options);
     }
     /**
-     * Update a database's properties, title, description, or archived status.
+     * Update a database's properties, title, description, or trash status.
      *
      * @param databaseId - The ID of the database to update
      * @param options - Options for updating the database
@@ -101,22 +102,32 @@ class DatabasesAPI extends base_api_1.BaseAPI {
         return this.updateResource(`/databases/${databaseId}`, options);
     }
     /**
-     * Archive a database (convenience method).
+     * Move a database to trash (convenience method).
      *
-     * @param databaseId - The ID of the database to archive
-     * @returns The archived database wrapped in a Database model
+     * @param databaseId - The ID of the database to trash
+     * @returns The trashed database wrapped in a Database model
      */
-    async archive(databaseId) {
-        return this.update(databaseId, { archived: true });
+    async trash(databaseId) {
+        return this.update(databaseId, { in_trash: true });
     }
     /**
-     * Restore an archived database (convenience method).
+     * Restore a trashed database (convenience method).
      *
      * @param databaseId - The ID of the database to restore
      * @returns The restored database wrapped in a Database model
      */
     async restore(databaseId) {
-        return this.update(databaseId, { archived: false });
+        return this.update(databaseId, { in_trash: false });
+    }
+    /**
+     * Move a database to trash (convenience method).
+     *
+     * @deprecated Use {@link trash} instead.
+     * @param databaseId - The ID of the database to trash
+     * @returns The trashed database wrapped in a Database model
+     */
+    async archive(databaseId) {
+        return this.trash(databaseId);
     }
 }
 exports.DatabasesAPI = DatabasesAPI;

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

@@ -73,6 +73,12 @@ export declare class FileUploadsAPI extends BaseAPI<NotionFileUpload, FileUpload
      * @see https://developers.notion.com/reference/complete-a-file-upload
      */
     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).
+     */
+    private static toRequestPath;
     /**
      * Helper method to upload a file in one call.
      * This combines initiate, upload, and complete steps.

package/dist/api/fileUploads.api.js

@@ -66,12 +66,27 @@ class FileUploadsAPI extends base_api_1.BaseAPI {
     async complete(completeUrl) {
         const response = await this.client.request({
             method: 'POST',
-            path: completeUrl.replace(/^https:\/\/api\.notion\.com\/v1/, ''),
+            path: FileUploadsAPI.toRequestPath(completeUrl),
             body: {},
         });
         const parsed = schemas_1.fileUploadSchema.parse(response);
         return new models_1.FileUpload(parsed);
     }
+    /**
+     * 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).
+     */
+    static toRequestPath(completeUrl) {
+        let path;
+        try {
+            path = new URL(completeUrl).pathname;
+        }
+        catch {
+            path = completeUrl;
+        }
+        return path.replace(/^\/v1/, '');
+    }
     /**
      * Helper method to upload a file in one call.
      * This combines initiate, upload, and complete steps.

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

@@ -68,8 +68,6 @@ export interface UpdatePageOptions {
     cover?: unknown;
     /** Lock or unlock the page from editing */
     is_locked?: boolean;
-    /** Archive or restore the page */
-    archived?: boolean;
     /** Move to trash or restore from trash */
     in_trash?: boolean;
     /** Template to apply to the page */
@@ -157,7 +155,6 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
                 object: import("zod").ZodLiteral<"user">;
                 id: import("zod").ZodUUID;
             }, import("zod/v4/core").$strip>]>;
-            archived: import("zod").ZodBoolean;
             in_trash: import("zod").ZodBoolean;
             icon: import("zod").ZodNullable<import("zod").ZodUnion<readonly [import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
                 type: import("zod").ZodLiteral<"file">;
@@ -968,7 +965,7 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
      */
     create(options: CreatePageOptions): Promise<Page>;
     /**
-     * Update a page's properties, icon, cover, or archived status.
+     * Update a page's properties, icon, cover, or trash status.
      *
      * @param pageId - The ID of the page to update
      * @param options - Options for updating the page
@@ -978,17 +975,25 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
      */
     update(pageId: string, options: UpdatePageOptions): Promise<Page>;
     /**
-     * Archive a page (convenience method).
+     * Move a page to trash (convenience method).
      *
-     * @param pageId - The ID of the page to archive
-     * @returns The archived page wrapped in a Page model
+     * @param pageId - The ID of the page to trash
+     * @returns The trashed page wrapped in a Page model
      */
-    archive(pageId: string): Promise<Page>;
+    trash(pageId: string): Promise<Page>;
     /**
-     * Restore an archived page (convenience method).
+     * Restore a trashed page (convenience method).
      *
      * @param pageId - The ID of the page to restore
      * @returns The restored page wrapped in a Page model
      */
     restore(pageId: string): Promise<Page>;
+    /**
+     * Move a page to trash (convenience method).
+     *
+     * @deprecated Use {@link trash} instead.
+     * @param pageId - The ID of the page to trash
+     * @returns The trashed page wrapped in a Page model
+     */
+    archive(pageId: string): Promise<Page>;
 }

package/dist/api/pages.api.js

@@ -48,7 +48,7 @@ class PagesAPI extends base_api_1.BaseAPI {
         return this.createResource('/pages', options);
     }
     /**
-     * Update a page's properties, icon, cover, or archived status.
+     * Update a page's properties, icon, cover, or trash status.
      *
      * @param pageId - The ID of the page to update
      * @param options - Options for updating the page
@@ -60,22 +60,32 @@ class PagesAPI extends base_api_1.BaseAPI {
         return this.updateResource(`/pages/${pageId}`, options);
     }
     /**
-     * Archive a page (convenience method).
+     * Move a page to trash (convenience method).
      *
-     * @param pageId - The ID of the page to archive
-     * @returns The archived page wrapped in a Page model
+     * @param pageId - The ID of the page to trash
+     * @returns The trashed page wrapped in a Page model
      */
-    async archive(pageId) {
-        return this.update(pageId, { archived: true });
+    async trash(pageId) {
+        return this.update(pageId, { in_trash: true });
     }
     /**
-     * Restore an archived page (convenience method).
+     * Restore a trashed page (convenience method).
      *
      * @param pageId - The ID of the page to restore
      * @returns The restored page wrapped in a Page model
      */
     async restore(pageId) {
-        return this.update(pageId, { archived: false });
+        return this.update(pageId, { in_trash: false });
+    }
+    /**
+     * Move a page to trash (convenience method).
+     *
+     * @deprecated Use {@link trash} instead.
+     * @param pageId - The ID of the page to trash
+     * @returns The trashed page wrapped in a Page model
+     */
+    async archive(pageId) {
+        return this.trash(pageId);
     }
 }
 exports.PagesAPI = PagesAPI;

package/dist/client.d.ts

@@ -1,3 +1,8 @@
+/**
+ * The Notion API version targeted by this SDK.
+ * All schemas, request bodies, helpers, and models are coupled to this version.
+ */
+export declare const NOTION_VERSION: "2026-03-11";
 /**
  * Configuration options for the Notion client.
  */
@@ -6,8 +11,6 @@ export interface NotionClientOptions {
     auth: string;
     /** Base URL for API requests (default: https://api.notion.com) */
     baseUrl?: string;
-    /** Notion API version (default: 2025-09-03) */
-    notionVersion?: string;
     /** Request timeout in milliseconds (default: 60000) */
     timeoutMs?: number;
     /** Custom fetch implementation (defaults to global fetch) */
@@ -23,7 +26,7 @@ export interface NotionClientOptions {
 export interface RequestOptions {
     method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
     path: string;
-    query?: Record<string, string | number | boolean | undefined>;
+    query?: Record<string, string | number | boolean | string[] | undefined>;
     body?: unknown;
 }
 /**
@@ -32,7 +35,6 @@ export interface RequestOptions {
 export declare class NotionClient {
     private readonly auth;
     private readonly baseUrl;
-    private readonly notionVersion;
     private readonly timeoutMs;
     private readonly fetchImpl;
     private readonly maxRetries;

package/dist/client.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NotionClient = void 0;
+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.
+ */
+exports.NOTION_VERSION = '2026-03-11';
 /**
  * Base HTTP client for Notion API requests.
  */
@@ -9,7 +14,6 @@ class NotionClient {
     constructor(options) {
         this.auth = options.auth;
         this.baseUrl = options.baseUrl ?? 'https://api.notion.com';
-        this.notionVersion = options.notionVersion ?? '2025-09-03';
         this.timeoutMs = options.timeoutMs ?? 60000;
         this.fetchImpl = options.fetch ?? fetch;
         this.maxRetries = options.maxRetries ?? 3;
@@ -106,7 +110,13 @@ class NotionClient {
         const url = new URL(`${this.baseUrl}/v1${path}`);
         if (query) {
             Object.entries(query).forEach(([key, value]) => {
-                if (value !== undefined) {
+                if (value === undefined) {
+                    return;
+                }
+                if (Array.isArray(value)) {
+                    value.forEach((item) => url.searchParams.append(key, item));
+                }
+                else {
                     url.searchParams.append(key, String(value));
                 }
             });
@@ -120,7 +130,7 @@ class NotionClient {
         return {
             Authorization: `Bearer ${this.auth}`,
             'Content-Type': 'application/json',
-            'Notion-Version': this.notionVersion,
+            'Notion-Version': exports.NOTION_VERSION,
         };
     }
     /**

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

@@ -65,7 +65,7 @@ declare function callout(text: RichTextInput, options?: CalloutOptions): BlockOb
 declare function template(text: RichTextInput, options?: {
     children?: unknown[];
 }): BlockObject;
-declare function transcription(text: RichTextInput, options?: {
+declare function meetingNotes(text: RichTextInput, options?: {
     children?: unknown[];
 }): BlockObject;
 /** Options for code blocks. */
@@ -167,7 +167,7 @@ export declare const block: {
     quote: typeof quote;
     callout: typeof callout;
     template: typeof template;
-    transcription: typeof transcription;
+    meetingNotes: typeof meetingNotes;
     code: typeof code;
     equation: typeof equation;
     image: typeof image;

package/dist/helpers/block.helpers.js

@@ -170,11 +170,11 @@ function template(text, options) {
         },
     };
 }
-function transcription(text, options) {
+function meetingNotes(text, options) {
     return {
         object: 'block',
-        type: 'transcription',
-        transcription: {
+        type: 'meeting_notes',
+        meeting_notes: {
             rich_text: resolveRichText(text),
             ...(options?.children ? { children: options.children } : {}),
         },
@@ -413,7 +413,7 @@ exports.block = {
     quote,
     callout,
     template,
-    transcription,
+    meetingNotes,
     // Code & equation
     code,
     equation,

package/dist/helpers/parent.helpers.d.ts

@@ -22,8 +22,8 @@ declare function database(databaseId: string): {
 };
 /**
  * Create a data source parent object.
- * In API version 2025-09-03, both data_source_id and database_id are required
- * when creating a page with a data source parent.
+ * Both data_source_id and database_id are required when creating a page
+ * with a data source parent.
  *
  * @example
  * ```ts

package/dist/helpers/parent.helpers.js

@@ -28,8 +28,8 @@ function database(databaseId) {
 }
 /**
  * Create a data source parent object.
- * In API version 2025-09-03, both data_source_id and database_id are required
- * when creating a page with a data source parent.
+ * Both data_source_id and database_id are required when creating a page
+ * with a data source parent.
  *
  * @example
  * ```ts

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { Notion } from './notion';
+export { NOTION_VERSION } from './client';
 export type { NotionClientOptions } from './client';
 export * from './api';
 export * from './errors';

package/dist/index.js

@@ -14,10 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Notion = void 0;
+exports.NOTION_VERSION = exports.Notion = void 0;
 // Export main SDK class
 var notion_1 = require("./notion");
 Object.defineProperty(exports, "Notion", { enumerable: true, get: function () { return notion_1.Notion; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "NOTION_VERSION", { enumerable: true, get: function () { return client_1.NOTION_VERSION; } });
 // Export API namespaces
 __exportStar(require("./api"), exports);
 // Export error classes

package/dist/models/block.model.d.ts

@@ -10,7 +10,6 @@ export declare class Block extends BaseModel<NotionBlock> {
     get type(): NotionBlock['type'];
     get createdTime(): Date;
     get lastEditedTime(): Date;
-    get archived(): boolean;
     get inTrash(): boolean;
     get hasChildren(): boolean;
     /**

package/dist/models/block.model.js

@@ -25,9 +25,6 @@ class Block extends base_model_1.BaseModel {
     get lastEditedTime() {
         return new Date(this.data.last_edited_time);
     }
-    get archived() {
-        return this.data.archived;
-    }
     get inTrash() {
         return this.data.in_trash;
     }

package/dist/models/dataSource.model.d.ts

@@ -71,10 +71,6 @@ export declare class DataSource extends BaseModel<NotionDataSource> {
      * Returns whether the data source is inline.
      */
     get isInline(): boolean;
-    /**
-     * Returns the archived status.
-     */
-    get archived(): boolean;
     /**
      * Returns whether the data source is in trash.
      */

package/dist/models/dataSource.model.js

@@ -108,12 +108,6 @@ class DataSource extends base_model_1.BaseModel {
     get isInline() {
         return this.data.is_inline;
     }
-    /**
-     * Returns the archived status.
-     */
-    get archived() {
-        return this.data.archived;
-    }
     /**
      * Returns whether the data source is in trash.
      */

package/dist/models/database.model.d.ts

@@ -57,10 +57,6 @@ export declare class Database extends BaseModel<NotionDatabase> {
      * Returns the Notion URL of the database.
      */
     get url(): string;
-    /**
-     * Returns the archived status.
-     */
-    get archived(): boolean;
     /**
      * Returns whether the database is in trash.
      */

package/dist/models/database.model.js

@@ -88,12 +88,6 @@ class Database extends base_model_1.BaseModel {
     get url() {
         return this.data.url;
     }
-    /**
-     * Returns the archived status.
-     */
-    get archived() {
-        return this.data.archived;
-    }
     /**
      * Returns whether the database is in trash.
      */

package/dist/models/page.model.d.ts

@@ -9,7 +9,6 @@ export declare class Page extends BaseModel<NotionPage> {
     get id(): string;
     get createdTime(): Date;
     get lastEditedTime(): Date;
-    get archived(): boolean;
     get inTrash(): boolean;
     get url(): string;
     get publicUrl(): string | null;

package/dist/models/page.model.js

@@ -22,9 +22,6 @@ class Page extends base_model_1.BaseModel {
     get lastEditedTime() {
         return new Date(this.data.last_edited_time);
     }
-    get archived() {
-        return this.data.archived;
-    }
     get inTrash() {
         return this.data.in_trash;
     }

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

@@ -1,4 +1,18 @@
 import * as z from 'zod';
+/**
+ * Position for inserting block children in the Append Block Children endpoint.
+ */
+export declare const blockPositionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"after_block">;
+    after_block: z.ZodObject<{
+        id: z.ZodUUID;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"start">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"end">;
+}, z.core.$strip>], "type">;
+export type BlockPosition = z.infer<typeof blockPositionSchema>;
 export declare const blockSchema: z.ZodObject<{
     object: z.ZodLiteral<"block">;
     id: z.ZodUUID;
@@ -50,7 +64,7 @@ export declare const blockSchema: z.ZodObject<{
         template: "template";
         to_do: "to_do";
         toggle: "toggle";
-        transcription: "transcription";
+        meeting_notes: "meeting_notes";
         unsupported: "unsupported";
         video: "video";
     }>;
@@ -120,7 +134,6 @@ export declare const blockSchema: z.ZodObject<{
         object: z.ZodLiteral<"user">;
         id: z.ZodUUID;
     }, z.core.$strip>]>;
-    archived: z.ZodBoolean;
     in_trash: z.ZodBoolean;
     has_children: z.ZodBoolean;
     audio: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -3661,7 +3674,7 @@ export declare const blockSchema: z.ZodObject<{
         }>;
         children: z.ZodOptional<z.ZodArray<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
     }, z.core.$strip>>;
-    transcription: z.ZodOptional<z.ZodObject<{
+    meeting_notes: z.ZodOptional<z.ZodObject<{
         rich_text: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"text">;
             text: z.ZodObject<{

package/dist/schemas/block.schema.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.blockSchema = void 0;
+exports.blockSchema = exports.blockPositionSchema = void 0;
 const z = __importStar(require("zod"));
 const codeLanguages_1 = require("./codeLanguages");
 const colors_1 = require("./colors");
@@ -57,6 +57,14 @@ const getChildrenSchema = () => {
     childrenSchema ??= z.array(exports.blockSchema).optional();
     return childrenSchema;
 };
+/**
+ * Position for inserting block children in the Append Block Children endpoint.
+ */
+exports.blockPositionSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('after_block'), after_block: z.object({ id: z.uuid() }) }),
+    z.object({ type: z.literal('start') }),
+    z.object({ type: z.literal('end') }),
+]);
 const headingsObjectSchema = z.object({
     rich_text: richText_schema_1.richTextSchema,
     color: z.enum(colors_1.NOTION_COLORS),
@@ -100,7 +108,7 @@ exports.blockSchema = z.object({
         'template',
         'to_do',
         'toggle',
-        'transcription',
+        'meeting_notes',
         'unsupported',
         'video',
     ]),
@@ -108,7 +116,6 @@ exports.blockSchema = z.object({
     created_by: user_schema_1.userSchema,
     last_edited_time: shared_schema_1.notionDateStringSchema,
     last_edited_by: user_schema_1.userSchema,
-    archived: z.boolean(),
     in_trash: z.boolean(),
     has_children: z.boolean(),
     // Block-specific properties
@@ -288,7 +295,7 @@ exports.blockSchema = z.object({
         },
     })
         .optional(),
-    transcription: z
+    meeting_notes: z
         .object({
         rich_text: richText_schema_1.richTextSchema,
         get children() {

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

@@ -785,7 +785,6 @@ export declare const dataSourceSchema: z.ZodObject<{
     url: z.ZodURL;
     public_url: z.ZodUnion<readonly [z.ZodURL, z.ZodNull]>;
     is_inline: z.ZodBoolean;
-    archived: z.ZodBoolean;
     in_trash: z.ZodBoolean;
 }, z.core.$strip>;
 export type NotionDataSource = z.infer<typeof dataSourceSchema>;

package/dist/schemas/dataSource.schema.js

@@ -84,8 +84,6 @@ exports.dataSourceSchema = z.object({
     public_url: z.union([z.url(), z.null()]),
     /** Whether the data source is inline */
     is_inline: z.boolean(),
-    /** The archived status of the data source */
-    archived: z.boolean(),
-    /** Whether the data source has been deleted */
+    /** Whether the data source is in the trash */
     in_trash: z.boolean(),
 });

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

@@ -492,7 +492,6 @@ export declare const databaseSchema: z.ZodObject<{
         block_id: z.ZodUUID;
     }, z.core.$strip>], "type">;
     url: z.ZodURL;
-    archived: z.ZodBoolean;
     in_trash: z.ZodBoolean;
     is_inline: z.ZodBoolean;
     public_url: z.ZodNullable<z.ZodURL>;

package/dist/schemas/database.schema.js

@@ -69,7 +69,6 @@ exports.databaseSchema = z.object({
     cover: z.nullable(file_schema_1.fileSchema),
     parent: parent_schema_1.parentSchema,
     url: z.url(),
-    archived: z.boolean(),
     in_trash: z.boolean(),
     is_inline: z.boolean(),
     public_url: z.nullable(z.url()),

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

@@ -77,7 +77,6 @@ export declare const pageSchema: z.ZodObject<{
         object: z.ZodLiteral<"user">;
         id: z.ZodUUID;
     }, z.core.$strip>]>;
-    archived: z.ZodBoolean;
     in_trash: z.ZodBoolean;
     icon: z.ZodNullable<z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"file">;

package/dist/schemas/page.schema.js

@@ -57,7 +57,6 @@ exports.pageSchema = z.object({
     created_by: user_schema_1.userSchema,
     last_edited_time: shared_schema_1.notionDateStringSchema,
     last_edited_by: user_schema_1.userSchema,
-    archived: z.boolean(),
     in_trash: z.boolean(),
     icon: z.nullable(z.union([file_schema_1.fileSchema, emoji_schema_1.emojiSchema])),
     cover: z.nullable(file_schema_1.fileSchema),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visus-io/notion-sdk-ts",
-  "version": "2.1.0",
+  "version": "3.0.2",
   "private": false,
   "description": "TypeScript SDK for the Notion API",
   "keywords": [
@@ -37,7 +37,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint .",
@@ -63,17 +63,18 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.4.1",
-    "@commitlint/config-conventional": "^20.4.1",
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "@types/node": "^25.2.1",
     "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^9.39.2",
-    "eslint-plugin-zod": "3.4.0",
+    "eslint": "^10.0.0",
+    "eslint-plugin-zod": "4.8.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
+    "msw": "2.15.0",
     "prettier": "^3.8.1",
     "prettier-plugin-packagejson": "^3.0.0",
-    "typescript": "^5.5.3",
+    "typescript": "^6.0.0",
     "typescript-eslint": "^8.54.0",
     "vitest": "^4.0.18"
   },