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

package/README.md

@@ -19,7 +19,7 @@ A type-safe TypeScript SDK for the Notion API with Zod validation, OOP models, a
 - **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+)
+- **Zero bloat** Single runtime dependency (`zod`); uses built-in `fetch` (Node 22+)
 
 ## Installation
 
@@ -29,7 +29,7 @@ npm install @visus-io/notion-sdk-ts
 bun add @visus-io/notion-sdk-ts
 ```
 
-**Requirements:** Node.js 18+ or Bun 1.3.10+ (uses native `fetch`)
+**Requirements:** Node.js 22+ or Bun 1.4.0+ (uses native `fetch`)
 
 ## Quick Start
 
@@ -118,7 +118,7 @@ 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+.
+> **Note:** While this project uses Bun for development, the published package works with both Node.js 22+ and Bun 1.4.0+.
 
 See [**ARCHITECTURE.md**](./ARCHITECTURE.md) for project structure and architecture.
 

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

@@ -917,6 +917,11 @@ export declare class DataSourcesAPI extends BaseAPI<NotionDataSource, DataSource
             public_url: import("zod").ZodUnion<readonly [import("zod").ZodURL, import("zod").ZodNull]>;
             is_inline: import("zod").ZodBoolean;
             in_trash: import("zod").ZodBoolean;
+            database_type: import("zod").ZodOptional<import("zod").ZodEnum<{
+                tasks: "tasks";
+                projects: "projects";
+                skills: "skills";
+            }>>;
         }, import("zod/v4/core").$strip>;
         ModelClass: typeof DataSource;
         listType: "data_source";

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

@@ -1,5 +1,5 @@
 import type { NotionClient } from '../client';
-import { type NotionDatabase, type PaginatedList, type PaginationParameters } from '../schemas';
+import { type DatabaseType, type NotionDatabase, type PaginatedList, type PaginationParameters } from '../schemas';
 import { Database, Page } from '../models';
 import { BaseAPI } from './base.api';
 /**
@@ -52,7 +52,9 @@ export type CreateDatabaseParent = {
 };
 /**
  * Initial data source configuration for creating a database.
- * As of API version 2025-09-03, databases are created with an initial data source.
+ * Provide this to create a database with a custom properties schema. To create a database
+ * from one of Notion's canonical schemas instead, use `database_type` on
+ * {@link CreateDatabaseOptions}.
  */
 export interface InitialDataSource {
     /** Data source properties schema */
@@ -62,14 +64,17 @@ export interface InitialDataSource {
 }
 /**
  * Options for creating a database.
- * As of API version 2025-09-03, databases require an `initial_data_source` object.
- * This object holds the properties schema. It replaces top-level properties.
+ * Provide exactly one of `database_type` or `initial_data_source`. `database_type` builds
+ * the database from one of Notion's canonical schemas. `initial_data_source` holds a custom
+ * properties schema. It replaces top-level properties.
  */
 export interface CreateDatabaseOptions {
     /** The parent object (page or workspace) */
     parent: CreateDatabaseParent;
+    /** Build the database from a canonical Notion schema instead of a custom one */
+    database_type?: DatabaseType;
     /** Initial data source configuration (contains properties schema) */
-    initial_data_source: InitialDataSource;
+    initial_data_source?: InitialDataSource;
     /** Database title as rich text array */
     title?: unknown[];
     /** Database icon (emoji, file, or external) */
@@ -621,6 +626,11 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
             is_inline: import("zod").ZodBoolean;
             is_locked: import("zod").ZodOptional<import("zod").ZodBoolean>;
             public_url: import("zod").ZodNullable<import("zod").ZodURL>;
+            database_type: import("zod").ZodOptional<import("zod").ZodEnum<{
+                tasks: "tasks";
+                projects: "projects";
+                skills: "skills";
+            }>>;
         }, import("zod/v4/core").$strip>;
         ModelClass: typeof Database;
         listType: "database";
@@ -652,6 +662,7 @@ export declare class DatabasesAPI extends BaseAPI<NotionDatabase, Database> {
      *
      * @param options - Options for creating the database
      * @returns The created database wrapped in a Database model
+     * @throws {NotionValidationError} If not exactly one of `database_type`/`initial_data_source` is provided
      *
      * @see https://developers.notion.com/reference/create-a-database
      */

package/dist/api/databases.api.js

@@ -74,19 +74,20 @@ class DatabasesAPI extends base_api_1.BaseAPI {
      *
      * @param options - Options for creating the database
      * @returns The created database wrapped in a Database model
+     * @throws {NotionValidationError} If not exactly one of `database_type`/`initial_data_source` is provided
      *
      * @see https://developers.notion.com/reference/create-a-database
      */
     async create(options) {
+        if (Boolean(options.database_type) === Boolean(options.initial_data_source)) {
+            throw new validation_1.NotionValidationError('Exactly one of database_type or initial_data_source must be provided');
+        }
         if (options.title) {
             (0, validation_1.validateArrayLength)(options.title, validation_1.LIMITS.ARRAY_ELEMENTS, 'title');
         }
         if (options.initial_data_source?.title) {
             (0, validation_1.validateArrayLength)(options.initial_data_source.title, validation_1.LIMITS.ARRAY_ELEMENTS, 'initial_data_source.title');
         }
-        if (options.initial_data_source.title) {
-            (0, validation_1.validateArrayLength)(options.initial_data_source.title, validation_1.LIMITS.ARRAY_ELEMENTS, 'initial_data_source.title');
-        }
         return this.createResource('/databases', options);
     }
     /**

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

@@ -380,6 +380,9 @@ export declare class PagesAPI extends BaseAPI<NotionPage, Page> {
                 }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                     type: import("zod").ZodLiteral<"string">;
                     string: import("zod").ZodNullable<import("zod").ZodString>;
+                }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+                    type: import("zod").ZodLiteral<"unsupported">;
+                    unsupported: import("zod").ZodObject<{}, import("zod/v4/core").$strip>;
                 }, import("zod/v4/core").$strip>], "type">;
             }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
                 id: import("zod").ZodString;

package/dist/errors.d.ts

@@ -14,6 +14,8 @@ export interface NotionErrorResponse {
     status: number;
     code: NotionErrorCode;
     message: string;
+    /** Extra machine-readable context for some error codes, for example `restricted_resource`. */
+    additional_data?: Record<string, unknown>;
 }
 /**
  * Thrown when the Notion API returns an error response.
@@ -42,6 +44,11 @@ export declare class NotionAPIError extends Error {
      * Check if the API could not find the requested object.
      */
     isNotFound(): boolean;
+    /**
+     * Check if a workspace restriction blocked the request.
+     * The Free workspace block limit is one example.
+     */
+    isRestrictedResource(): boolean;
     /**
      * Check if the error is a validation error.
      */

package/dist/errors.js

@@ -43,6 +43,13 @@ class NotionAPIError extends Error {
     isNotFound() {
         return this.code === 'object_not_found';
     }
+    /**
+     * Check if a workspace restriction blocked the request.
+     * The Free workspace block limit is one example.
+     */
+    isRestrictedResource() {
+        return this.code === 'restricted_resource';
+    }
     /**
      * Check if the error is a validation error.
      */

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

@@ -1,5 +1,5 @@
 import { BaseModel, type TRUSTED } from './base.model';
-import { type NotionDataSource, type NotionFile, type NotionIcon, type NotionParent, type NotionPropertiesObject, type NotionPropertyObject, type NotionRichText, type NotionUser } from '../schemas';
+import { type DatabaseType, type NotionDataSource, type NotionFile, type NotionIcon, type NotionParent, type NotionPropertiesObject, type NotionPropertyObject, type NotionRichText, type NotionUser } from '../schemas';
 /**
  * Data Source model class with helper methods.
  *
@@ -77,6 +77,11 @@ export declare class DataSource extends BaseModel<NotionDataSource> {
      * Returns whether the data source is in trash.
      */
     get inTrash(): boolean;
+    /**
+     * Returns the canonical database type this data source's parent database was built from,
+     * if any.
+     */
+    get databaseType(): DatabaseType | undefined;
     /**
      * Extracts the plain text title from the data source.
      */

package/dist/models/dataSource.model.js

@@ -116,6 +116,13 @@ class DataSource extends base_model_1.BaseModel {
     get inTrash() {
         return this.data.in_trash;
     }
+    /**
+     * Returns the canonical database type this data source's parent database was built from,
+     * if any.
+     */
+    get databaseType() {
+        return this.data.database_type;
+    }
     /**
      * Extracts the plain text title from the data source.
      */

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

@@ -1,5 +1,5 @@
 import { BaseModel, type TRUSTED } from './base.model';
-import { type DataSourceRef, type NotionDatabase, type NotionFile, type NotionIcon, type NotionParent, type NotionRichText, type NotionUser } from '../schemas';
+import { type DatabaseType, type DataSourceRef, type NotionDatabase, type NotionFile, type NotionIcon, type NotionParent, type NotionRichText, type NotionUser } from '../schemas';
 /**
  * Database model class with helper methods.
  *
@@ -77,6 +77,10 @@ export declare class Database extends BaseModel<NotionDatabase> {
      * Returns the public URL if published, otherwise null.
      */
     get publicUrl(): string | null;
+    /**
+     * Returns the canonical database type this database was built from, if any.
+     */
+    get databaseType(): DatabaseType | undefined;
     /**
      * Extracts the plain text title from the database.
      */

package/dist/models/database.model.js

@@ -116,6 +116,12 @@ class Database extends base_model_1.BaseModel {
     get publicUrl() {
         return this.data.public_url;
     }
+    /**
+     * Returns the canonical database type this database was built from, if any.
+     */
+    get databaseType() {
+        return this.data.database_type;
+    }
     /**
      * Extracts the plain text title from the database.
      */

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

@@ -28,6 +28,11 @@ export declare class User extends BaseModel<NotionUser> {
      * Get email if this is a person user.
      */
     getEmail(): string | undefined;
+    /**
+     * Get the person's email verification status.
+     * Returns `undefined` when the user is not a person.
+     */
+    getEmailVerified(): boolean | undefined;
     /**
      * Get bot information if this is a bot user.
      */

package/dist/models/user.model.js

@@ -48,6 +48,16 @@ class User extends base_model_1.BaseModel {
         }
         return undefined;
     }
+    /**
+     * Get the person's email verification status.
+     * Returns `undefined` when the user is not a person.
+     */
+    getEmailVerified() {
+        if (this.isPerson()) {
+            return this.data.person.email_verified;
+        }
+        return undefined;
+    }
     /**
      * Get bot information if this is a bot user.
      */

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

@@ -822,6 +822,11 @@ export declare const dataSourceSchema: z.ZodObject<{
     public_url: z.ZodUnion<readonly [z.ZodURL, z.ZodNull]>;
     is_inline: z.ZodBoolean;
     in_trash: z.ZodBoolean;
+    database_type: z.ZodOptional<z.ZodEnum<{
+        tasks: "tasks";
+        projects: "projects";
+        skills: "skills";
+    }>>;
 }, z.core.$strip>;
 /**
  * @category Databases & Data Sources

package/dist/schemas/dataSource.schema.js

@@ -42,6 +42,7 @@ const richText_schema_1 = require("./richText.schema");
 const shared_schema_1 = require("./shared.schema");
 const user_schema_1 = require("./user.schema");
 const propertyObjects_schema_1 = require("./propertyObjects.schema");
+const database_schema_1 = require("./database.schema");
 /**
  * Notion data source object schema.
  *
@@ -88,6 +89,8 @@ exports.dataSourceSchema = z.object({
     is_inline: z.boolean(),
     /** Whether the data source is in the trash */
     in_trash: z.boolean(),
+    /** Canonical database type this data source's parent database was built from, if any */
+    database_type: z.enum(database_schema_1.DATABASE_TYPES).optional(),
 });
 /**
  * A single data source template reference. The List data source templates endpoint

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

@@ -20,6 +20,19 @@ export declare const dataSourceRefSchema: z.ZodObject<{
  * @category Databases & Data Sources
  */
 export type DataSourceRef = z.infer<typeof dataSourceRefSchema>;
+/**
+ * A canonical database type.
+ *
+ * Pass one of these values as `database_type` when you create a database. Notion builds the
+ * database from its schema for that type, not a custom schema.
+ *
+ * @category Databases & Data Sources
+ */
+export declare const DATABASE_TYPES: readonly ["tasks", "projects", "skills"];
+/**
+ * @category Databases & Data Sources
+ */
+export type DatabaseType = (typeof DATABASE_TYPES)[number];
 /**
  * @category Databases & Data Sources
  */
@@ -536,6 +549,11 @@ export declare const databaseSchema: z.ZodObject<{
     is_inline: z.ZodBoolean;
     is_locked: z.ZodOptional<z.ZodBoolean>;
     public_url: z.ZodNullable<z.ZodURL>;
+    database_type: z.ZodOptional<z.ZodEnum<{
+        tasks: "tasks";
+        projects: "projects";
+        skills: "skills";
+    }>>;
 }, z.core.$strip>;
 /**
  * @category Databases & Data Sources

package/dist/schemas/database.schema.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.databaseSchema = exports.dataSourceRefSchema = void 0;
+exports.databaseSchema = exports.DATABASE_TYPES = exports.dataSourceRefSchema = void 0;
 const z = __importStar(require("zod"));
 const file_schema_1 = require("./file.schema");
 const icon_schema_1 = require("./icon.schema");
@@ -58,6 +58,15 @@ exports.dataSourceRefSchema = z.object({
     id: z.uuid(),
     name: z.string().trim(),
 });
+/**
+ * A canonical database type.
+ *
+ * Pass one of these values as `database_type` when you create a database. Notion builds the
+ * database from its schema for that type, not a custom schema.
+ *
+ * @category Databases & Data Sources
+ */
+exports.DATABASE_TYPES = ['tasks', 'projects', 'skills'];
 /**
  * @category Databases & Data Sources
  */
@@ -79,4 +88,5 @@ exports.databaseSchema = z.object({
     is_inline: z.boolean(),
     is_locked: z.boolean().optional(),
     public_url: z.nullable(z.url()),
+    database_type: z.enum(exports.DATABASE_TYPES).optional(),
 });

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

@@ -241,6 +241,9 @@ export declare const pageSchema: z.ZodObject<{
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"string">;
             string: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"unsupported">;
+            unsupported: z.ZodObject<{}, z.core.$strip>;
         }, z.core.$strip>], "type">;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodString;

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

@@ -118,6 +118,9 @@ declare const formulaPropertySchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"string">;
         string: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"unsupported">;
+        unsupported: z.ZodObject<{}, z.core.$strip>;
     }, z.core.$strip>], "type">;
 }, z.core.$strip>;
 /** Last edited by property. */
@@ -885,6 +888,9 @@ export declare const pagePropertiesSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"string">;
         string: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"unsupported">;
+        unsupported: z.ZodObject<{}, z.core.$strip>;
     }, z.core.$strip>], "type">;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;

package/dist/schemas/pageProperties.schema.js

@@ -113,6 +113,7 @@ const formulaPropertySchema = z.object({
         }),
         z.object({ type: z.literal('number'), number: z.number().nullable() }),
         z.object({ type: z.literal('string'), string: z.string().trim().nullable() }),
+        z.object({ type: z.literal('unsupported'), unsupported: z.object({}) }),
     ]),
 });
 /** Last edited by property. */

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

@@ -435,6 +435,9 @@ export declare const viewQueryResponseSchema: z.ZodObject<{
             }, z.core.$strip>, z.ZodObject<{
                 type: z.ZodLiteral<"string">;
                 string: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"unsupported">;
+                unsupported: z.ZodObject<{}, z.core.$strip>;
             }, z.core.$strip>], "type">;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visus-io/notion-sdk-ts",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "private": false,
   "description": "TypeScript SDK for the Notion API",
   "keywords": [
@@ -63,26 +63,27 @@
     ]
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.0.0",
-    "@commitlint/config-conventional": "^21.0.0",
-    "@types/node": "^25.2.1",
-    "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^10.0.0",
-    "eslint-plugin-zod": "4.9.0",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@types/bun": "^1.4.0",
+    "@types/node": "^25.9.5",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.9.0",
+    "eslint-plugin-zod": "4.12.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.2.7",
+    "lint-staged": "^16.4.0",
     "msw": "2.15.0",
-    "prettier": "^3.8.1",
-    "prettier-plugin-packagejson": "^3.0.0",
+    "prettier": "^3.9.6",
+    "prettier-plugin-packagejson": "^3.0.2",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.54.0",
-    "vitest": "^4.0.18"
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.11"
   },
   "engines": {
-    "bun": ">=1.3.10",
-    "node": ">=18.0.0"
+    "bun": ">=1.4.0",
+    "node": ">=22.0.0"
   }
 }