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

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

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

@@ -0,0 +1,72 @@
+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.
+ *
+ * @category Async Tasks
+ */
+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.
+     * Wait at least `poll_after_seconds` between each poll, per the API's guidance.
+     * This value comes from the response body, not a header.
+     *
+     * @param taskId - The ID of the async task to poll
+     * @param options - Polling options
+     * @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,70 @@
+"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.
+ *
+ * @category Async Tasks
+ */
+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.
+     * Wait at least `poll_after_seconds` between each poll, per the API's guidance.
+     * This value comes from the response body, not a header.
+     *
+     * @param taskId - The ID of the async task to poll
+     * @param options - Polling options
+     * @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

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

package/dist/api/base.api.js

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