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

package/dist/api/search.api.d.ts

@@ -8,13 +8,21 @@ import { DataSource, Page } from '../models';
 export type SearchFilterObject = 'page' | 'data_source';
 /**
  * Search filter configuration.
+ *
+ * `in_trash` can be combined with the object filter (`property`/`value`) or
+ * used on its own to list only trashed content.
  */
-export interface SearchFilter {
+export type SearchFilter = {
     /** Filter by object type */
     value: SearchFilterObject;
     /** Property to filter on (always "object" for this filter type) */
     property: 'object';
-}
+    /** Whether to list only trashed pages and data sources */
+    in_trash?: boolean;
+} | {
+    /** Whether to list only trashed pages and data sources */
+    in_trash: boolean;
+};
 /**
  * Search sort configuration.
  */

package/dist/api/users.api.d.ts

@@ -16,6 +16,7 @@ export declare class UsersAPI extends BaseAPI<NotionUser, User> {
             avatar_url: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>>;
             person: import("zod").ZodObject<{
                 email: import("zod").ZodEmail;
+                email_verified: import("zod").ZodOptional<import("zod").ZodBoolean>;
             }, import("zod/v4/core").$strip>;
         }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
             object: import("zod").ZodLiteral<"user">;

package/dist/api/views.api.d.ts

@@ -0,0 +1,284 @@
+import type { NotionClient } from '../client';
+import { Page, View } from '../models';
+import { type NotionView, type PaginatedList, type PaginationParameters, type RequestStatus, type ViewDeleteResult, type ViewType } from '../schemas';
+import { BaseAPI } from './base.api';
+import type { DataSourceSort } from './dataSources.api';
+/**
+ * Options for listing views. Exactly one of `database_id`/`data_source_id` must be provided.
+ */
+export interface ListViewsOptions extends PaginationParameters {
+    /** List views for this database (mutually exclusive with data_source_id) */
+    database_id?: string;
+    /** List views for this data source (mutually exclusive with database_id) */
+    data_source_id?: string;
+}
+/**
+ * Options for creating a view. Exactly one of `database_id`/`view_id`/`create_database`
+ * must be provided to select the parent context.
+ */
+export interface CreateViewOptions {
+    /** The data source the view displays */
+    data_source_id: string;
+    /** The view name */
+    name: string;
+    /** The view layout type */
+    type: ViewType;
+    /** Attach the view to this existing database */
+    database_id?: string;
+    /** Clone the configuration of this existing view */
+    view_id?: string;
+    /** Create a new database to hold the view */
+    create_database?: true;
+    /** Filter configuration */
+    filter?: Record<string, unknown>;
+    /** Sort configuration */
+    sorts?: DataSourceSort[];
+    /** Quick filter configuration */
+    quick_filters?: Record<string, unknown>;
+    /** Per-layout configuration */
+    configuration?: Record<string, unknown>;
+    /** Where to place the new view relative to existing views */
+    position?: Record<string, unknown>;
+}
+/**
+ * Options for updating a view. All fields optional; passing `null` for
+ * filter/sorts/quick_filters clears the existing value.
+ */
+export interface UpdateViewOptions {
+    /** Rename the view */
+    name?: string;
+    /** Update or clear (`null`) the filter configuration */
+    filter?: Record<string, unknown> | null;
+    /** Update or clear (`null`) the sort configuration */
+    sorts?: DataSourceSort[] | null;
+    /** Update or clear (`null`) the quick filter configuration */
+    quick_filters?: Record<string, unknown> | null;
+    /** Shallow-merged per-layout configuration update */
+    configuration?: Record<string, unknown>;
+}
+/**
+ * Options for creating a view query.
+ */
+export interface CreateViewQueryOptions extends PaginationParameters {
+    /** Filter configuration */
+    filter?: Record<string, unknown>;
+    /** Sort configuration */
+    sorts?: DataSourceSort[];
+}
+/**
+ * Result of a view query. Non-standard pagination shape distinct from
+ * {@link PaginatedList} -- includes `totalCount` and an `expiresAt` after which the
+ * query can no longer be retrieved via {@link ViewsAPI.queries.get}.
+ */
+export interface ViewQueryResult {
+    id: string;
+    viewId: string;
+    expiresAt: Date;
+    totalCount: number;
+    results: Page[];
+    nextCursor: string | null;
+    hasMore: boolean;
+    requestStatus?: RequestStatus;
+}
+/**
+ * Views API client for working with Notion views.
+ *
+ * Views control how a database/data source's rows are displayed (table, board,
+ * calendar, etc.). Requires API version 2025-09-03 or later.
+ */
+export declare class ViewsAPI extends BaseAPI<NotionView, View> {
+    protected readonly client: NotionClient;
+    protected config: {
+        schema: import("zod").ZodObject<{
+            object: import("zod").ZodLiteral<"view">;
+            id: import("zod").ZodUUID;
+            parent: import("zod").ZodObject<{
+                type: import("zod").ZodLiteral<"database_id">;
+                database_id: import("zod").ZodUUID;
+            }, import("zod/v4/core").$strip>;
+            data_source_id: import("zod").ZodNullable<import("zod").ZodUUID>;
+            name: import("zod").ZodString;
+            type: import("zod").ZodEnum<{
+                map: "map";
+                table: "table";
+                list: "list";
+                board: "board";
+                calendar: "calendar";
+                timeline: "timeline";
+                gallery: "gallery";
+                form: "form";
+                chart: "chart";
+                dashboard: "dashboard";
+            }>;
+            filter: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
+            sorts: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodArray<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>>;
+            quick_filters: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>>;
+            configuration: import("zod").ZodOptional<import("zod").ZodObject<{
+                type: import("zod").ZodEnum<{
+                    map: "map";
+                    table: "table";
+                    list: "list";
+                    board: "board";
+                    calendar: "calendar";
+                    timeline: "timeline";
+                    gallery: "gallery";
+                    form: "form";
+                    chart: "chart";
+                    dashboard: "dashboard";
+                }>;
+            }, import("zod/v4/core").$catchall<import("zod").ZodUnknown>>>;
+            created_time: import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>;
+            last_edited_time: import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>;
+            created_by: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+                type: import("zod").ZodLiteral<"person">;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                avatar_url: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>>;
+                person: import("zod").ZodObject<{
+                    email: import("zod").ZodEmail;
+                    email_verified: import("zod").ZodOptional<import("zod").ZodBoolean>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+                type: import("zod").ZodLiteral<"bot">;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                avatar_url: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>>;
+                bot: import("zod").ZodObject<{
+                    owner: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"workspace">;
+                        workspace: import("zod").ZodLiteral<true>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"user">;
+                    }, import("zod/v4/core").$strip>], "type">;
+                    workspace_name: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+                    workspace_id: import("zod").ZodOptional<import("zod").ZodString>;
+                    workspace_limits: import("zod").ZodOptional<import("zod").ZodObject<{
+                        max_file_upload_size_in_bytes: import("zod").ZodInt;
+                    }, import("zod/v4/core").$strip>>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+            }, import("zod/v4/core").$strip>]>;
+            last_edited_by: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+                type: import("zod").ZodLiteral<"person">;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                avatar_url: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>>;
+                person: import("zod").ZodObject<{
+                    email: import("zod").ZodEmail;
+                    email_verified: import("zod").ZodOptional<import("zod").ZodBoolean>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+                type: import("zod").ZodLiteral<"bot">;
+                name: import("zod").ZodOptional<import("zod").ZodString>;
+                avatar_url: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>>;
+                bot: import("zod").ZodObject<{
+                    owner: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"workspace">;
+                        workspace: import("zod").ZodLiteral<true>;
+                    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                        type: import("zod").ZodLiteral<"user">;
+                    }, import("zod/v4/core").$strip>], "type">;
+                    workspace_name: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+                    workspace_id: import("zod").ZodOptional<import("zod").ZodString>;
+                    workspace_limits: import("zod").ZodOptional<import("zod").ZodObject<{
+                        max_file_upload_size_in_bytes: import("zod").ZodInt;
+                    }, import("zod/v4/core").$strip>>;
+                }, import("zod/v4/core").$strip>;
+            }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"user">;
+                id: import("zod").ZodUUID;
+            }, import("zod/v4/core").$strip>]>;
+            url: import("zod").ZodURL;
+            dashboard_view_id: import("zod").ZodOptional<import("zod").ZodUUID>;
+        }, import("zod/v4/core").$strip>;
+        ModelClass: typeof View;
+        listType: "view";
+    };
+    constructor(client: NotionClient);
+    /**
+     * List the views for a database or data source.
+     *
+     * @param options - Exactly one of `database_id`/`data_source_id`, plus pagination
+     * @returns Paginated list of views
+     *
+     * @throws {NotionValidationError} If neither or both of `database_id`/`data_source_id` are provided
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    list(options: ListViewsOptions): Promise<PaginatedList<View>>;
+    /**
+     * Retrieve a view by ID.
+     *
+     * @param viewId - The ID of the view to retrieve
+     * @returns The view wrapped in a View model
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    retrieve(viewId: string): Promise<View>;
+    /**
+     * Create a new view.
+     *
+     * @param options - Options for creating the view
+     * @returns The created view wrapped in a View model
+     *
+     * @throws {NotionValidationError} If not exactly one of `database_id`/`view_id`/`create_database` is provided
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    create(options: CreateViewOptions): Promise<View>;
+    /**
+     * Update a view's name, filter, sorts, quick filters, or configuration.
+     *
+     * @param viewId - The ID of the view to update
+     * @param options - Options for updating the view
+     * @returns The updated view wrapped in a View model
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    update(viewId: string, options: UpdateViewOptions): Promise<View>;
+    /**
+     * Delete a view.
+     *
+     * Note: unlike other delete methods, Notion's delete-view response only includes
+     * `object`/`id`/`parent`/`type` (not the full view shape), so this returns the raw
+     * parsed result rather than a full {@link View} model.
+     *
+     * @param viewId - The ID of the view to delete
+     * @returns The partial view object returned by the API
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    delete(viewId: string): Promise<ViewDeleteResult>;
+    /**
+     * Sub-resource for querying a view's rows. View queries are non-standard: they
+     * return a `total_count` and `expires_at`, and the query result itself expires
+     * roughly 15 minutes after creation.
+     */
+    readonly queries: {
+        /**
+         * Create a new query against a view.
+         *
+         * @see https://developers.notion.com/guides/data-apis/working-with-views
+         */
+        create: (viewId: string, options?: CreateViewQueryOptions) => Promise<ViewQueryResult>;
+        /**
+         * Retrieve the results of a previously created view query.
+         *
+         * @see https://developers.notion.com/guides/data-apis/working-with-views
+         */
+        get: (viewId: string, queryId: string) => Promise<ViewQueryResult>;
+        /**
+         * Delete a view query.
+         *
+         * @see https://developers.notion.com/guides/data-apis/working-with-views
+         */
+        delete: (viewId: string, queryId: string) => Promise<void>;
+    };
+}

package/dist/api/views.api.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewsAPI = void 0;
+const models_1 = require("../models");
+const schemas_1 = require("../schemas");
+const validation_1 = require("../validation");
+const base_api_1 = require("./base.api");
+function toViewQueryResult(response) {
+    const parsed = schemas_1.viewQueryResponseSchema.parse(response);
+    return {
+        id: parsed.id,
+        viewId: parsed.view_id,
+        expiresAt: new Date(parsed.expires_at),
+        totalCount: parsed.total_count,
+        results: parsed.results.map((page) => new models_1.Page(page)),
+        nextCursor: parsed.next_cursor,
+        hasMore: parsed.has_more,
+        requestStatus: parsed.request_status,
+    };
+}
+/**
+ * Views API client for working with Notion views.
+ *
+ * Views control how a database/data source's rows are displayed (table, board,
+ * calendar, etc.). Requires API version 2025-09-03 or later.
+ */
+class ViewsAPI extends base_api_1.BaseAPI {
+    constructor(client) {
+        super(client);
+        this.client = client;
+        this.config = {
+            schema: schemas_1.viewSchema,
+            ModelClass: models_1.View,
+            listType: 'view',
+        };
+        /**
+         * Sub-resource for querying a view's rows. View queries are non-standard: they
+         * return a `total_count` and `expires_at`, and the query result itself expires
+         * roughly 15 minutes after creation.
+         */
+        this.queries = {
+            /**
+             * Create a new query against a view.
+             *
+             * @see https://developers.notion.com/guides/data-apis/working-with-views
+             */
+            create: async (viewId, options) => {
+                const body = {};
+                if (options?.filter) {
+                    body.filter = options.filter;
+                }
+                if (options?.sorts) {
+                    body.sorts = options.sorts;
+                }
+                Object.assign(body, this.buildPaginationBody(options));
+                const response = await this.client.request({
+                    method: 'POST',
+                    path: `/views/${viewId}/queries`,
+                    body: Object.keys(body).length > 0 ? body : undefined,
+                });
+                return toViewQueryResult(response);
+            },
+            /**
+             * Retrieve the results of a previously created view query.
+             *
+             * @see https://developers.notion.com/guides/data-apis/working-with-views
+             */
+            get: async (viewId, queryId) => {
+                const response = await this.client.request({
+                    method: 'GET',
+                    path: `/views/${viewId}/queries/${queryId}`,
+                });
+                return toViewQueryResult(response);
+            },
+            /**
+             * Delete a view query.
+             *
+             * @see https://developers.notion.com/guides/data-apis/working-with-views
+             */
+            delete: async (viewId, queryId) => {
+                await this.client.request({
+                    method: 'DELETE',
+                    path: `/views/${viewId}/queries/${queryId}`,
+                });
+            },
+        };
+    }
+    /**
+     * List the views for a database or data source.
+     *
+     * @param options - Exactly one of `database_id`/`data_source_id`, plus pagination
+     * @returns Paginated list of views
+     *
+     * @throws {NotionValidationError} If neither or both of `database_id`/`data_source_id` are provided
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async list(options) {
+        if (Boolean(options.database_id) === Boolean(options.data_source_id)) {
+            throw new validation_1.NotionValidationError('Exactly one of database_id or data_source_id must be provided');
+        }
+        const query = {
+            ...(options.database_id ? { database_id: options.database_id } : {}),
+            ...(options.data_source_id ? { data_source_id: options.data_source_id } : {}),
+            ...this.buildPaginationQuery(options),
+        };
+        return this.listResources('/views', query);
+    }
+    /**
+     * Retrieve a view by ID.
+     *
+     * @param viewId - The ID of the view to retrieve
+     * @returns The view wrapped in a View model
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async retrieve(viewId) {
+        return this.retrieveResource(`/views/${viewId}`);
+    }
+    /**
+     * Create a new view.
+     *
+     * @param options - Options for creating the view
+     * @returns The created view wrapped in a View model
+     *
+     * @throws {NotionValidationError} If not exactly one of `database_id`/`view_id`/`create_database` is provided
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async create(options) {
+        const selectorCount = [options.database_id, options.view_id, options.create_database].filter((value) => value !== undefined).length;
+        if (selectorCount !== 1) {
+            throw new validation_1.NotionValidationError('Exactly one of database_id, view_id, or create_database must be provided');
+        }
+        return this.createResource('/views', options);
+    }
+    /**
+     * Update a view's name, filter, sorts, quick filters, or configuration.
+     *
+     * @param viewId - The ID of the view to update
+     * @param options - Options for updating the view
+     * @returns The updated view wrapped in a View model
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async update(viewId, options) {
+        return this.updateResource(`/views/${viewId}`, options);
+    }
+    /**
+     * Delete a view.
+     *
+     * Note: unlike other delete methods, Notion's delete-view response only includes
+     * `object`/`id`/`parent`/`type` (not the full view shape), so this returns the raw
+     * parsed result rather than a full {@link View} model.
+     *
+     * @param viewId - The ID of the view to delete
+     * @returns The partial view object returned by the API
+     *
+     * @see https://developers.notion.com/guides/data-apis/working-with-views
+     */
+    async delete(viewId) {
+        const response = await this.client.request({
+            method: 'DELETE',
+            path: `/views/${viewId}`,
+        });
+        return schemas_1.viewDeleteResponseSchema.parse(response);
+    }
+}
+exports.ViewsAPI = ViewsAPI;

package/dist/client.js

@@ -29,10 +29,10 @@ class NotionClient {
                 return await this.makeRequest(options);
             }
             catch (error) {
-                // Only retry on rate limit errors if retry is enabled
+                // Retry rate-limited requests (if enabled) and service-overload (529)
+                // responses, which the API recommends always retrying.
                 if (error instanceof errors_1.NotionAPIError &&
-                    error.isRateLimited() &&
-                    this.retryOnRateLimit &&
+                    ((error.isRateLimited() && this.retryOnRateLimit) || error.isServiceOverloaded()) &&
                     attempt < this.maxRetries) {
                     // Prefer the server-supplied Retry-After value; fall back to
                     // exponential backoff when the header is absent.

package/dist/errors.d.ts

@@ -1,7 +1,7 @@
 /**
  * Notion API error codes based on official documentation.
  */
-export type NotionErrorCode = 'invalid_json' | 'invalid_request_url' | 'invalid_request' | 'validation_error' | 'missing_version' | 'unauthorized' | 'restricted_resource' | 'object_not_found' | 'conflict_error' | 'rate_limited' | 'internal_server_error' | 'service_unavailable' | 'database_connection_unavailable' | 'gateway_timeout';
+export type NotionErrorCode = 'invalid_json' | 'invalid_request_url' | 'invalid_request' | 'validation_error' | 'missing_version' | 'unauthorized' | 'restricted_resource' | 'object_not_found' | 'conflict_error' | 'rate_limited' | 'internal_server_error' | 'service_unavailable' | 'service_overload' | 'database_connection_unavailable' | 'gateway_timeout';
 /**
  * Notion API error response structure.
  */
@@ -24,6 +24,10 @@ export declare class NotionAPIError extends Error {
      * Check if the error is a rate limit error.
      */
     isRateLimited(): boolean;
+    /**
+     * Check if the error is a service overload error (HTTP 529).
+     */
+    isServiceOverloaded(): boolean;
     /**
      * Check if the error is an authentication error.
      */

package/dist/errors.js

@@ -23,6 +23,12 @@ class NotionAPIError extends Error {
     isRateLimited() {
         return this.code === 'rate_limited';
     }
+    /**
+     * Check if the error is a service overload error (HTTP 529).
+     */
+    isServiceOverloaded() {
+        return this.code === 'service_overload';
+    }
     /**
      * Check if the error is an authentication error.
      */

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

@@ -16,6 +16,11 @@ interface BlockObject {
     type: string;
     [key: string]: unknown;
 }
+/** Options for paragraph blocks. */
+interface ParagraphOptions extends TextBlockOptions {
+    /** Icon shown alongside the paragraph. Only meaningful for paragraphs used as tab items. */
+    icon?: unknown;
+}
 /**
  * Create a paragraph block.
  *
@@ -25,7 +30,7 @@ interface BlockObject {
  * block.paragraph(richText('Hello').bold(), { color: 'blue' })
  * ```
  */
-declare function paragraph(text: RichTextInput, options?: TextBlockOptions): BlockObject;
+declare function paragraph(text: RichTextInput, options?: ParagraphOptions): BlockObject;
 /** Options for heading blocks. */
 interface HeadingOptions {
     color?: NotionColor;
@@ -35,6 +40,7 @@ interface HeadingOptions {
 declare function heading1(text: RichTextInput, options?: HeadingOptions): BlockObject;
 declare function heading2(text: RichTextInput, options?: HeadingOptions): BlockObject;
 declare function heading3(text: RichTextInput, options?: HeadingOptions): BlockObject;
+declare function heading4(text: RichTextInput, options?: HeadingOptions): BlockObject;
 declare function bulletedListItem(text: RichTextInput, options?: TextBlockOptions): BlockObject;
 /** Options for numbered list items. */
 interface NumberedListOptions extends TextBlockOptions {
@@ -65,6 +71,14 @@ declare function callout(text: RichTextInput, options?: CalloutOptions): BlockOb
 declare function template(text: RichTextInput, options?: {
     children?: unknown[];
 }): BlockObject;
+/**
+ * @deprecated Meeting-notes blocks are server-managed -- their real shape (`title`,
+ * `status`, and child block IDs for the summary/notes/transcript) is populated by
+ * Notion, not hand-constructed by clients. This helper's `rich_text`-based output no
+ * longer matches `blockSchema`'s `meeting_notes` shape and is not a valid way to
+ * create a meeting-notes block. Kept only to avoid an abrupt removal from the helper
+ * surface; do not use for new code.
+ */
 declare function meetingNotes(text: RichTextInput, options?: {
     children?: unknown[];
 }): BlockObject;
@@ -115,6 +129,27 @@ declare function table(width: number, options?: TableOptions): BlockObject;
 declare function tableRow(cells: RichTextInput[]): BlockObject;
 declare function columnList(columns: unknown[][]): BlockObject;
 declare function column(children: unknown[]): BlockObject;
+/** A single tab: its label becomes the tab's paragraph rich text, `children` its content. */
+interface TabItem {
+    label: RichTextInput;
+    icon?: unknown;
+    color?: NotionColor;
+    children?: unknown[];
+}
+/**
+ * Create a tab block. Only `paragraph` blocks may be direct children of a tab block --
+ * each tab is modeled as one paragraph, whose rich text is the tab label and whose
+ * `children` hold the tab's content.
+ *
+ * @example
+ * ```ts
+ * block.tab([
+ *   { label: 'Overview', children: [block.paragraph('Intro text')] },
+ *   { label: 'Details', icon: icon.emoji('📋'), children: [block.paragraph('More info')] },
+ * ])
+ * ```
+ */
+declare function tab(tabs: TabItem[]): BlockObject;
 /**
  * Create a synced block.
  *
@@ -160,6 +195,7 @@ export declare const block: {
     heading1: typeof heading1;
     heading2: typeof heading2;
     heading3: typeof heading3;
+    heading4: typeof heading4;
     bulletedListItem: typeof bulletedListItem;
     numberedListItem: typeof numberedListItem;
     toDo: typeof toDo;
@@ -185,6 +221,7 @@ export declare const block: {
     tableRow: typeof tableRow;
     columnList: typeof columnList;
     column: typeof column;
+    tab: typeof tab;
     syncedBlock: typeof syncedBlock;
 };
 export {};