@visus-io/notion-sdk-ts

A type-safe TypeScript SDK for the Notion API with Zod validation, OOP models, and ergonomic helpers.

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
• 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+)

Installation

npm install @visus-io/notion-sdk-ts
# or
bun add @visus-io/notion-sdk-ts

Requirements: Node.js 18+ or Bun 1.3.10+ (uses native fetch)

Quick Start

import { Notion, block, richText, filter, sort, prop, parent } from '@visus-io/notion-sdk-ts';

const notion = new Notion({ auth: process.env.NOTION_TOKEN });

// Retrieve a page
const page = await notion.pages.retrieve('page-id');
console.log(page.getTitle());

// Create a page in a database
const database = await notion.databases.retrieve('database-id');
const dataSourceId = database.dataSources[0].id;

await notion.pages.create({
  parent: parent.dataSource(dataSourceId, database.id),
  properties: {
    Name: prop.title('New Task'),
    Status: prop.status('In Progress'),
    Priority: prop.select('High'),
  },
});

// Append blocks to a page
await notion.blocks.children.append('page-id', {
  children: [
    block.heading2('Meeting Notes'),
    block.paragraph('Discussed the roadmap for Q2.'),
    block.toDo('Follow up with design', { checked: false }),
  ],
});

// Query a database with filters
const results = await notion.databases.query('database-id', {
  filter: filter.and(
    filter.status('Status').equals('In Progress'),
    filter.select('Priority').equals('High'),
  ),
  sorts: [sort.property('Due Date').ascending()],
});

Documentation

Comprehensive documentation is available in the GitHub Wiki:

Getting Started

• Getting Started - Installation, quick start, and basic configuration
• Migration Guide - Migrating to API version 2025-09-03
• Common Use Cases - Practical examples and workflows

Core Concepts

• Helpers - Rich Text, Block Builder, Properties, Filters, Sorting
• Models - Page, Block, Database, DataSource, User, Comment, FileUpload
• API Reference - Complete API endpoint documentation

Configuration & Advanced Topics

• Configuration & Features - Client options, rate limiting, retries
• Error Handling - Error types, codes, and handling patterns
• Pagination - Automatic pagination helpers
• Request Size Limits - Notion API size limits

Development

• TypeScript Support - Types, schemas, and type safety
• Development & Contributing - Project structure and architecture

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.

Key Changes

• 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

// OLD (2022-06-28)
await notion.pages.create({
  parent: parent.database('database-id'),
  properties: { Name: prop.title('Task') },
});

// NEW (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') },
});

See the Migration Guide for complete details.

Development

This project uses Bun as its package manager for faster dependency installation and script execution.

Prerequisites

Install Bun if you haven't already:

curl -fsSL https://bun.sh/install | bash

Development Commands

bun install              # Install dependencies
bun run build            # Compile TypeScript

bun run test                 # Run tests
bun run test:watch       # Watch mode
bun run test:coverage    # Coverage report

bun run lint             # ESLint
bun run lint:fix         # Auto-fix
bun run format           # Prettier

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 for more details.

Links

• Documentation Wiki
• GitHub Repository
• npm Package
• Notion API Documentation
• Notion API Changelog