notion-sdk-ts

Key Features

Type-safe

Zod v4 runtime validation on every API response, plus full TypeScript declarations.

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 eliminate verbose JSON.

OOP models

Page, Block, Database, DataSource, User, Comment, FileUpload, RichText, AsyncTask, CustomEmoji, View with convenience methods.

Automatic pagination

paginate(), paginateIterator(), and paginateWithMetadata() helpers automatically fetch all pages for you.

Zero bloat

Single runtime dependency (zod); uses the built-in fetch (Node.js 18+).

Installation

npm install @visus-io/notion-sdk-ts

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

Quick Example

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

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

Need Help?

Common Use Cases

Practical examples and workflows — see the Common Use Cases guide.

API Reference

Full generated reference for every class and method — browse the API Reference.

Error Handling

Troubleshooting tips — see the Error Handling guide.

Migration Guide

Upgrading from an older version? See the Migration Guide.

Contributing

We welcome contributions! See CONTRIBUTING.md for how to get started, and ARCHITECTURE.md for project structure and architecture.