Migrate to v5 of the notion SDK and switch from databases to data sources (#694)

* wip

* wip

* migrate to new version of the notion api

* update claude-md

Author: zamiang

.claude/settings.local.json

@@ -20,7 +20,14 @@
       "Bash(npm ls:*)",
       "Bash(npm install)",
       "Bash(git add package.json)",
-      "Bash(git add package-lock.json)"
+      "Bash(git add package-lock.json)",
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "Bash(npm test)",
+      "Bash(npm run typecheck:*)",
+      "WebFetch(domain:developers.notion.com)",
+      "Bash(node:*)",
+      "Bash(npm run build:*)"
     ],
     "deny": [],
     "ask": []

CLAUDE.md

@@ -0,0 +1,78 @@
+# Claude Code Memory Bank
+
+## Project Information
+
+- **Project**: Personal homepage/blog built with Next.js and Notion as CMS
+- **Tech Stack**: Next.js 15.5.4, TypeScript, @notionhq/client 5.1.0, notion-to-md, Tailwind CSS
+- **Testing**: Vitest with 71 tests
+- **Node Version**: 22.x
+
+## Recent Updates
+
+### @notion/client Migration (v4.0.2 → v5.1.0) - Completed
+
+**Date**: 2025-09-28
+
+Successfully migrated from @notion/client v4.0.2 to v5.1.0 without breaking functionality.
+
+**Key Changes Made**:
+
+1. **API Method Change**: `notion.databases.query()` → `notion.dataSources.query()`
+2. **Parameter Change**: `database_id` → `data_source_id`
+3. **Import Path Fix**: `ImageBlockObjectResponse` now imported from main module
+4. **API Version**: Using default API version (2025-09-03) - older versions had compatibility issues
+5. **Test Updates**: Updated mocks to use `dataSources` instead of `databases`
+
+**Important Notes**:
+
+- Switched to use notion data source ids instead of Database IDs
+
+**Files Modified**:
+
+- `src/lib/notion.ts` - Core Notion API interactions
+- `scripts/cache-posts.ts` - Post caching script
+- `__tests__/lib/notion.test.ts` - Unit tests
+
+**Verification**:
+
+- ✅ All 71 tests pass
+- ✅ TypeScript compilation successful
+- ✅ Build completes without errors
+- ✅ Static generation works correctly
+
+## Commands to Remember
+
+### Development
+
+- `npm run dev` - Start development server
+- `npm run build` - Production build
+- `npm test` - Run all tests
+- `npm run typecheck` - TypeScript validation
+- `npm run lint` - ESLint
+- `npm run cache:posts` - Cache posts from Notion
+
+### Testing
+
+- `npm run test:watch` - Watch mode testing
+- `npm run test:coverage` - Coverage report
+- `npm run test:ui` - Vitest UI
+
+## Architecture Notes
+
+### Notion Integration
+
+- Uses Notion as headless CMS for blog posts and photos
+- Posts cached locally in `posts-cache.json` and `photos-cache.json`
+- Supports two sections: "All" (general posts) and "VBC" (Value-Based Care posts)
+- Image handling with local download and optimization
+
+### File Structure
+
+- `src/lib/notion.ts` - Main Notion API wrapper
+- `scripts/cache-posts.ts` - Caching script for posts and photos
+- `__tests__/` - Test files using Vitest
+- Posts cached as JSON files in project root
+
+### API Compatibility
+
+- Database queries work with both posts and photos databases

README.md

@@ -56,15 +56,15 @@ This is a [Next.js](https://nextjs.org/) blog written in [TypeScript](https://ww
 Follow the [Notion API Getting Started Guide](https://developers.notion.com/docs/getting-started) to obtain:
 
 - `NOTION_TOKEN`: Your Notion integration token.
-- `NOTION_POSTS_DATABASE_ID`: The database ID for your blog posts.
-- `NOTION_PHOTOS_DATABASE_ID`: The database ID for your photo gallery.
+- `NOTION_POSTS_DATA_SOURCE_ID`: The data source ID for your blog posts.
+- `NOTION_PHOTOS_DATA_SOURCE_ID`: The data source ID for your photo gallery.
 
 Save these in a `.env.local` file:
 
 ```env
 NOTION_TOKEN=your-notion-token
-NOTION_POSTS_DATABASE_ID=your-posts-database-id
-NOTION_PHOTOS_DATABASE_ID=your-photos-database-id
+NOTION_POSTS_DATA_SOURCE_ID=your-posts-data-source-id
+NOTION_PHOTOS_DATA_SOURCE_ID=your-photos-data-source-id
 ```
 
 ### 2. **Install Dependencies**

__tests__/lib/notion.test.ts

@@ -243,18 +243,18 @@ describe('notion.ts - Unit Tests', () => {
   describe('fetchPublishedPosts', () => {
     it('should fetch published posts from Notion', async () => {
       const mockNotionClient = {
-        databases: {
+        dataSources: {
           query: vi.fn().mockResolvedValue({
             results: [{ id: '1' }, { id: '2' }],
           }),
         },
       };
 
-      const databaseId = 'test-database-id';
-      const posts = await fetchPublishedPosts(mockNotionClient as unknown as Client, databaseId);
+      const dataSourceID = 'test-database-id';
+      const posts = await fetchPublishedPosts(mockNotionClient as unknown as Client, dataSourceID);
 
-      expect(mockNotionClient.databases.query).toHaveBeenCalledWith({
-        database_id: databaseId,
+      expect(mockNotionClient.dataSources.query).toHaveBeenCalledWith({
+        data_source_id: dataSourceID,
         filter: {
           and: [
             {
@@ -278,7 +278,7 @@ describe('notion.ts - Unit Tests', () => {
 
     it('should handle Notion API errors', async () => {
       const mockNotionClient = {
-        databases: {
+        dataSources: {
           query: vi.fn().mockRejectedValue(new Error('Notion API error')),
         },
       };

__tests__/setup.ts

@@ -24,8 +24,8 @@ vi.mock('next/navigation', () => ({
 
 // Mock environment variables
 process.env.NOTION_TOKEN = 'test-notion-token';
-process.env.NOTION_DATABASE_ID = 'test-database-id';
-process.env.NOTION_PHOTOS_DATABASE_ID = 'test-photos-database-id';
+process.env.NOTION_DATA_SOURCE_ID = 'test-database-id';
+process.env.NOTION_PHOTOS_DATA_SOURCE_ID = 'test-photos-database-id';
 
 // Suppress console errors in tests
 global.console = {

package-lock.json

@@ -21,7 +21,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@notionhq/client": "4.0.2",
+    "@notionhq/client": "5.1.0",
     "@radix-ui/react-label": "2.1.7",
     "@radix-ui/react-slot": "1.2.3",
     "@types/react-syntax-highlighter": "15.5.13",

package.json

@@ -5,15 +5,15 @@ import path from 'path';
 import { fetchPublishedPosts, getPostFromNotion } from '../src/lib/notion';
 
 interface CacheConfig {
-  databaseId: string;
+  dataSourceID: string;
   cacheFileName: string;
   itemName: string;
 }
 
 const cacheItems = async (notion: Client, config: CacheConfig) => {
   try {
     console.log(`Fetching ${config.itemName} from Notion...`);
-    const posts = await fetchPublishedPosts(notion, config.databaseId);
+    const posts = await fetchPublishedPosts(notion, config.dataSourceID);
 
     const allPosts = [];
 
@@ -34,18 +34,20 @@ const cacheItems = async (notion: Client, config: CacheConfig) => {
   }
 };
 
-const notion = new Client({ auth: process.env.NOTION_TOKEN });
+const notion = new Client({
+  auth: process.env.NOTION_TOKEN,
+});
 
 // Cache posts and photos using the generic function
 (async () => {
   await Promise.all([
     cacheItems(notion, {
-      databaseId: process.env.NOTION_DATABASE_ID!,
+      dataSourceID: process.env.NOTION_DATA_SOURCE_ID!,
       cacheFileName: 'posts-cache.json',
       itemName: 'posts',
     }),
     cacheItems(notion, {
-      databaseId: process.env.NOTION_PHOTOS_DATABASE_ID!,
+      dataSourceID: process.env.NOTION_PHOTOS_DATA_SOURCE_ID!,
       cacheFileName: 'photos-cache.json',
       itemName: 'photos',
     }),

scripts/cache-posts.ts

@@ -1,6 +1,6 @@
 import { Client } from '@notionhq/client';
+import { ImageBlockObjectResponse } from '@notionhq/client';
 import { PageObjectResponse } from '@notionhq/client/';
-import { ImageBlockObjectResponse } from '@notionhq/client/build/src/api-endpoints';
 import dotenv from 'dotenv';
 import fs from 'fs';
 import { NotionToMarkdown } from 'notion-to-md';
@@ -66,10 +66,10 @@ export function getPhotosFromCache(): Post[] {
   return [];
 }
 
-export const fetchPublishedPosts = async (notion: Client, databaseID: string) => {
+export const fetchPublishedPosts = async (notion: Client, dataSourceID: string) => {
   // This function is now intended to be used only by the caching script.
-  const posts = await notion.databases.query({
-    database_id: databaseID!,
+  const posts = await notion.dataSources.query({
+    data_source_id: dataSourceID!,
     filter: {
       and: [
         {
@@ -99,7 +99,9 @@ export async function getPost(slug: string): Promise<Post | null> {
 
 export async function getPostFromNotion(pageId: string): Promise<Post | null> {
   try {
-    const notion = new Client({ auth: process.env.NOTION_TOKEN });
+    const notion = new Client({
+      auth: process.env.NOTION_TOKEN,
+    });
     const n2m = new NotionToMarkdown({ notionClient: notion });
 
     n2m.setCustomTransformer('image', async (block) => {