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

package/README.md

@@ -13,10 +13,10 @@ A type-safe TypeScript SDK for the Notion API with Zod validation, OOP models, a
 ## Features
 
 - **Type-safe** Zod v4 runtime validation on every API response; full TypeScript declarations
-- **Complete API coverage** Pages, Blocks, Databases, Data Sources, Comments, Search, Users, File Uploads
-- **Ergonomic helpers** `block`, `richText`, `filter`, `sort`, `prop`, `parent`, `icon`, `cover`, `paginate` factories eliminate verbose JSON
-- **OOP models** `Page`, `Block`, `Database`, `User`, `Comment`, `DataSource`, `FileUpload`, `RichText` with convenience methods
-- **Automatic pagination** `paginate()` and `paginateIterator()` helpers automatically fetch all pages
+- **Complete API coverage** Pages, Blocks, Databases, Data Sources, Comments, Search, Users, File Uploads, Async Tasks, Custom Emojis, Views
+- **Ergonomic helpers** `block`, `richText`, `filter`, `sort`, `prop`, `parent`, `icon`, `cover`, `paginate` factories and a `webhook` signature-verification helper eliminate verbose JSON and boilerplate
+- **OOP models** `Page`, `Block`, `Database`, `User`, `Comment`, `DataSource`, `FileUpload`, `RichText`, `AsyncTask`, `CustomEmoji`, `View` with convenience methods
+- **Automatic pagination** `paginate()`, `paginateIterator()`, and `paginateWithMetadata()` helpers automatically fetch all pages, plus `iterateAllDataSourceRows()`/`collectAllDataSourceRows()` to work around the 10,000-result query cap
 - **Automatic rate limiting** Respects `Retry-After` header with exponential backoff fallback (configurable)
 - **Client-side size validation** Enforces Notion API size limits before sending requests
 - **Zero bloat** Single runtime dependency (`zod`); uses built-in `fetch` (Node 18+)
@@ -110,7 +110,7 @@ Comprehensive documentation is available in the [**GitHub Wiki**](https://github
 
 - **`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
+- **`transcription` → `meeting_notes`**: Block type and helper renamed (`block.meetingNotes()` is itself now deprecated — meeting-notes blocks are server-managed, not client-constructed)
 - **`notionVersion` removed**: Use the exported `NOTION_VERSION` constant to inspect the target version
 
 ### Quick Migration Example (v2.x → v3.x)
@@ -131,7 +131,8 @@ 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');
+// Meeting notes are server-managed — read them instead of constructing them:
+await notion.blocks.meetingNotes.query();
 ```
 
 ### Key Changes (v2.x — 2025-09-03)

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

@@ -0,0 +1,70 @@
+import type { NotionClient } from '../client';
+import { AsyncTask } from '../models';
+import { type NotionAsyncTask } from '../schemas';
+import { BaseAPI } from './base.api';
+/**
+ * Options for polling an async task until completion.
+ */
+export interface PollAsyncTaskOptions {
+    /** Maximum time to wait for the task to complete, in milliseconds (default: 300000 / 5 minutes) */
+    timeoutMs?: number;
+}
+/**
+ * Async Tasks API client for polling long-running Notion operations.
+ */
+export declare class AsyncTasksAPI extends BaseAPI<NotionAsyncTask, AsyncTask> {
+    protected readonly client: NotionClient;
+    protected config: {
+        schema: import("zod").ZodObject<{
+            object: import("zod").ZodLiteral<"async_task">;
+            id: import("zod").ZodUUID;
+            status: import("zod").ZodEnum<{
+                queued: "queued";
+                running: "running";
+                retrying: "retrying";
+                succeeded: "succeeded";
+                failed: "failed";
+            }>;
+            status_url: import("zod").ZodURL;
+            created_time: import("zod").ZodUnion<readonly [import("zod").ZodISODateTime, import("zod").ZodISODate]>;
+            operation: import("zod").ZodObject<{
+                surface: import("zod").ZodEnum<{
+                    rest: "rest";
+                    mcp: "mcp";
+                }>;
+                name: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>;
+            poll_after_seconds: import("zod").ZodOptional<import("zod").ZodNumber>;
+            result: import("zod").ZodOptional<import("zod").ZodUnknown>;
+            error: import("zod").ZodOptional<import("zod").ZodObject<{
+                object: import("zod").ZodLiteral<"error">;
+                status: import("zod").ZodNumber;
+                code: import("zod").ZodString;
+                message: import("zod").ZodString;
+            }, import("zod/v4/core").$strip>>;
+        }, import("zod/v4/core").$strip>;
+        ModelClass: typeof AsyncTask;
+    };
+    constructor(client: NotionClient);
+    /**
+     * Retrieve the current status of an async task.
+     *
+     * @param taskId - The ID of the async task to retrieve
+     * @returns The task wrapped in an AsyncTask model
+     *
+     * @see https://developers.notion.com/reference/retrieve-async-task
+     */
+    retrieve(taskId: string): Promise<AsyncTask>;
+    /**
+     * Poll an async task until it reaches a terminal status (succeeded or failed),
+     * waiting at least `poll_after_seconds` (from the response body, not a header)
+     * between polls, per the API's guidance.
+     *
+     * @param taskId - The ID of the async task to poll
+     * @param options - Polling options
+     * @returns The task wrapped in an AsyncTask model, once it reaches a terminal status
+     *
+     * @throws {NotionRequestTimeoutError} If the task doesn't complete within `timeoutMs`
+     */
+    poll(taskId: string, options?: PollAsyncTaskOptions): Promise<AsyncTask>;
+}

package/dist/api/asyncTasks.api.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncTasksAPI = void 0;
+const errors_1 = require("../errors");
+const models_1 = require("../models");
+const schemas_1 = require("../schemas");
+const base_api_1 = require("./base.api");
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Async Tasks API client for polling long-running Notion operations.
+ */
+class AsyncTasksAPI extends base_api_1.BaseAPI {
+    constructor(client) {
+        super(client);
+        this.client = client;
+        this.config = {
+            schema: schemas_1.asyncTaskSchema,
+            ModelClass: models_1.AsyncTask,
+        };
+    }
+    /**
+     * Retrieve the current status of an async task.
+     *
+     * @param taskId - The ID of the async task to retrieve
+     * @returns The task wrapped in an AsyncTask model
+     *
+     * @see https://developers.notion.com/reference/retrieve-async-task
+     */
+    async retrieve(taskId) {
+        return this.retrieveResource(`/async_tasks/${taskId}`);
+    }
+    /**
+     * Poll an async task until it reaches a terminal status (succeeded or failed),
+     * waiting at least `poll_after_seconds` (from the response body, not a header)
+     * between polls, per the API's guidance.
+     *
+     * @param taskId - The ID of the async task to poll
+     * @param options - Polling options
+     * @returns The task wrapped in an AsyncTask model, once it reaches a terminal status
+     *
+     * @throws {NotionRequestTimeoutError} If the task doesn't complete within `timeoutMs`
+     */
+    async poll(taskId, options) {
+        const deadline = Date.now() + (options?.timeoutMs ?? 300_000);
+        for (;;) {
+            const task = await this.retrieve(taskId);
+            if (task.isTerminal()) {
+                return task;
+            }
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0) {
+                throw new errors_1.NotionRequestTimeoutError(`Task ${taskId} did not complete within timeout`);
+            }
+            const desiredSleepMs = Math.max((task.pollAfterSeconds ?? 1) * 1000, 250);
+            if (desiredSleepMs >= remainingMs) {
+                // Sleeping the full poll_after_seconds would overshoot the deadline -- cap the
+                // sleep to what's left and time out immediately after, instead of sleeping the
+                // full interval and only detecting the timeout on the next loop iteration.
+                await sleep(remainingMs);
+                throw new errors_1.NotionRequestTimeoutError(`Task ${taskId} did not complete within timeout`);
+            }
+            await sleep(desiredSleepMs);
+        }
+    }
+}
+exports.AsyncTasksAPI = AsyncTasksAPI;

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;
     }
@@ -222,6 +206,7 @@ class BaseAPI {
             next_cursor: parsed.next_cursor,
             has_more: parsed.has_more,
             type: this.config.listType || 'unknown',
+            request_status: parsed.request_status,
         };
     }
 }