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

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/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,10 @@ 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';
+    /** Filter by trash status */
+    in_trash?: boolean;
 }
 /**
  * Data Sources API client for working with Notion data sources.
@@ -870,7 +866,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 +913,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

@@ -65,9 +65,6 @@ class DataSourcesAPI extends base_api_1.BaseAPI {
             (0, validation_1.validateArrayLength)(options.filter_properties, validation_1.LIMITS.ARRAY_ELEMENTS, 'filter_properties');
             body.filter_properties = options.filter_properties;
         }
-        if (options?.archived !== undefined) {
-            body.archived = options.archived;
-        }
         if (options?.in_trash !== undefined) {
             body.in_trash = options.in_trash;
         }
@@ -119,40 +116,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

@@ -86,7 +86,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 +101,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/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) */
@@ -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;
@@ -120,7 +124,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.1",
   "private": false,
   "description": "TypeScript SDK for the Notion API",
   "keywords": [
@@ -63,17 +63,17 @@
     "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.7.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
     "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"
   },