[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M793P33B4WN8PTR59N0DMB6R":3,"skill-same:01M793P33B4WN8PTR59N0DMB6R":56},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":33,"commitSha":34,"skillDirectory":35,"forksCount":36,"repositoryHtmlUrl":37,"repositoryHomepageUrl":6,"ownerHtmlUrl":38,"ownerBlogUrl":39,"ownerDescription":40,"updatedAt":41,"install":42,"resources":55},"01M793P33B4WN8PTR59N0DMB6R","notion-upgrade-migration",null,"Upgrade @notionhq\u002Fclient SDK versions and migrate between Notion API versions.\nUse when updating SDK packages, handling breaking changes between API versions,\nadopting new SDK features like comments API or status properties, or migrating Python notion-client.\nTrigger with phrases like \"upgrade notion SDK\", \"notion migration\", \"notion breaking changes\",\n\"update notionhq client\", \"notion API version upgrade\", \"notion deprecation\".","jukeyman\u002Fjukeyman-skills","jukeyman","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F142960420?v=4","01M78FR4Y3DHMMCBCC0GXXNB3F","RICK JEFFERSON","01M78FR4Z8RVQRAD31Y5J7V6EB",1,"MIT","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsaas-packs--notion-pack--notion-upgrade-migration\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: notion-upgrade-migration\ndescription: |\n  Upgrade @notionhq\u002Fclient SDK versions and migrate between Notion API versions.\n  Use when updating SDK packages, handling breaking changes between API versions,\n  adopting new SDK features like comments API or status properties, or migrating Python notion-client.\n  Trigger with phrases like \"upgrade notion SDK\", \"notion migration\", \"notion breaking changes\",\n  \"update notionhq client\", \"notion API version upgrade\", \"notion deprecation\".\nallowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(git:*), Glob, Grep\nversion: 1.0.0\nlicense: MIT\nauthor: Jeremy Longshore \u003Cjeremy@intentsolutions.io>\ntags: [saas, productivity, notion]\ncompatible-with: claude-code\n---\n\n# Notion Upgrade & Migration\n\n## Overview\n\nStep-by-step guide for upgrading `@notionhq\u002Fclient` (Node.js) and `notion-client` (Python) SDK versions, migrating between Notion API versions, handling breaking changes, and adopting newly released features. Covers the current stable API version `2022-06-28` and the SDK feature timeline through v2.x.\n\n## Prerequisites\n\n- Existing project with `@notionhq\u002Fclient` or `notion-client` installed\n- Git repository with clean working tree (no uncommitted changes)\n- Test suite covering Notion API calls (or willingness to add verification tests)\n- `NOTION_TOKEN` environment variable configured\n\n## Instructions\n\n### Step 1: Audit Current Versions and API Surface\n\nDetermine what you are running today before changing anything.\n\n```bash\n# Node.js — check installed SDK version\nnpm ls @notionhq\u002Fclient\n\n# Node.js — check latest available\nnpm view @notionhq\u002Fclient version\n\n# Python — check installed SDK version\npip show notion-client 2>\u002Fdev\u002Fnull | grep Version\n\n# Python — check latest available\npip index versions notion-client 2>\u002Fdev\u002Fnull | head -1\n\n# Find which API version your code specifies\ngrep -rn \"notionVersion\\|Notion-Version\\|notion_version\" src\u002F lib\u002F app\u002F 2>\u002Fdev\u002Fnull\n```\n\nRecord the current SDK version and API version before proceeding. If no `notionVersion` is set explicitly, the SDK uses its built-in default (typically `2022-06-28` for current releases).\n\n**SDK version history — key milestones:**\n\n| SDK Version | Notable Additions |\n|-------------|-------------------|\n| `2.2.0` | Comments API support (`notion.comments.create`, `notion.comments.list`) |\n| `2.2.3` | Status property type in database schemas |\n| `2.2.4` | Unique ID property, verification property |\n| `2.2.13` | Improved TypeScript discriminated unions for block types |\n| `2.2.15` | Current stable — bug fixes, dependency updates |\n\n**API version timeline:**\n\n| API Version | Key Changes |\n|-------------|-------------|\n| `2022-02-22` | Rich text standardization, consistent pagination |\n| `2022-06-28` | **Current stable** — most tutorials and production apps use this |\n\n### Step 2: Perform the Upgrade\n\nCreate an isolated branch, upgrade the package, and address breaking changes before merging.\n\n**Node.js upgrade:**\n```bash\n# Create upgrade branch\ngit checkout -b upgrade\u002Fnotionhq-client-$(npm view @notionhq\u002Fclient version)\n\n# Upgrade to latest\nnpm install @notionhq\u002Fclient@latest\n\n# Review what changed\nnpm ls @notionhq\u002Fclient\ngit diff package.json package-lock.json\n```\n\n**Python upgrade:**\n```bash\ngit checkout -b upgrade\u002Fnotion-client-$(pip show notion-client 2>\u002Fdev\u002Fnull | grep Version | awk '{print $2}')\n\npip install --upgrade notion-client\n\n# Verify\npip show notion-client | grep Version\n```\n\n**Breaking changes to check after any major version bump:**\n\n```typescript\n\u002F\u002F 1. Import paths — endpoint types moved in some releases\n\u002F\u002F OLD (pre-2.2.x):\nimport type { QueryDatabaseResponse } from '@notionhq\u002Fclient\u002Fbuild\u002Fsrc\u002Fapi-endpoints';\n\u002F\u002F CURRENT (2.2.x):\nimport type {\n  PageObjectResponse,\n  DatabaseObjectResponse,\n  BlockObjectResponse,\n  QueryDatabaseResponse,\n} from '@notionhq\u002Fclient\u002Fbuild\u002Fsrc\u002Fapi-endpoints';\n\n\u002F\u002F 2. Error handling imports are stable across all 2.x versions\nimport { Client, isNotionClientError, APIErrorCode, ClientErrorCode } from '@notionhq\u002Fclient';\n\n\u002F\u002F 3. New property types — code must handle unknown types gracefully\nfunction extractProperty(prop: any): string {\n  switch (prop.type) {\n    case 'title': return prop.title.map((t: any) => t.plain_text).join('');\n    case 'rich_text': return prop.rich_text.map((t: any) => t.plain_text).join('');\n    case 'status': return prop.status?.name ?? '';       \u002F\u002F Added in 2.2.3\n    case 'unique_id': return String(prop.unique_id?.number ?? ''); \u002F\u002F Added in 2.2.4\n    default: return `[unhandled: ${prop.type}]`;\n  }\n}\n\n\u002F\u002F 4. Pin API version explicitly for reproducible behavior\nconst notion = new Client({\n  auth: process.env.NOTION_TOKEN,\n  notionVersion: '2022-06-28',  \u002F\u002F Always pin — do not rely on SDK default\n});\n```\n\n**Python breaking changes:**\n```python\nfrom notion_client import Client, APIResponseError\n\n# Pin API version explicitly\nnotion = Client(\n    auth=os.environ[\"NOTION_TOKEN\"],\n    notion_version=\"2022-06-28\",  # Explicit pin\n)\n\n# New in recent versions: comments API\ncomments = notion.comments.list(block_id=page_id)\n\n# Status property (requires SDK that supports it)\n# Returns: {\"type\": \"status\", \"status\": {\"name\": \"In Progress\", \"color\": \"blue\"}}\n```\n\n### Step 3: Verify and Test the Upgrade\n\nRun targeted verification tests to confirm nothing broke. Test each API surface your application uses.\n\n```typescript\nimport { Client } from '@notionhq\u002Fclient';\n\nconst notion = new Client({\n  auth: process.env.NOTION_TOKEN,\n  notionVersion: '2022-06-28',\n});\n\n\u002F\u002F Test 1: Authentication and user listing\nasync function verifyAuth(): Promise\u003Cvoid> {\n  const { results } = await notion.users.list({});\n  console.log(`Auth OK — ${results.length} users found`);\n}\n\n\u002F\u002F Test 2: Database query (most common operation)\nasync function verifyDatabaseQuery(databaseId: string): Promise\u003Cvoid> {\n  const response = await notion.databases.query({\n    database_id: databaseId,\n    page_size: 5,\n  });\n  console.log(`Query OK — ${response.results.length} pages, has_more=${response.has_more}`);\n\n  \u002F\u002F Verify property types are still parsed correctly\n  for (const page of response.results) {\n    if ('properties' in page) {\n      const types = Object.values(page.properties).map(p => p.type);\n      console.log(`  Property types: ${[...new Set(types)].join(', ')}`);\n    }\n  }\n}\n\n\u002F\u002F Test 3: Page creation and archival (write path)\nasync function verifyPageLifecycle(databaseId: string): Promise\u003Cvoid> {\n  const page = await notion.pages.create({\n    parent: { database_id: databaseId },\n    properties: {\n      Name: { title: [{ text: { content: `Upgrade test ${Date.now()}` } }] },\n    },\n  });\n  console.log(`Create OK — page ${page.id}`);\n  await notion.pages.update({ page_id: page.id, archived: true });\n  console.log('Archive OK');\n}\n\n\u002F\u002F Test 4: Block operations (read + append)\nasync function verifyBlocks(pageId: string): Promise\u003Cvoid> {\n  const { results } = await notion.blocks.children.list({ block_id: pageId });\n  console.log(`Block list OK — ${results.length} blocks`);\n  await notion.blocks.children.append({\n    block_id: pageId,\n    children: [{\n      paragraph: { rich_text: [{ text: { content: 'Upgrade verification block' } }] },\n    }],\n  });\n  console.log('Block append OK');\n}\n\n\u002F\u002F Test 5: Comments API (available since SDK 2.2.0)\nasync function verifyComments(pageId: string): Promise\u003Cvoid> {\n  try {\n    const { results } = await notion.comments.list({ block_id: pageId });\n    console.log(`Comments OK — ${results.length} comments`);\n  } catch (err) {\n    console.log('Comments API not available in this SDK version');\n  }\n}\n\n\u002F\u002F Run all verification\nawait verifyAuth();\nawait verifyDatabaseQuery(process.env.TEST_DB_ID!);\nawait verifyPageLifecycle(process.env.TEST_DB_ID!);\nawait verifyBlocks(process.env.TEST_PAGE_ID!);\nawait verifyComments(process.env.TEST_PAGE_ID!);\n```\n\nAfter all tests pass, merge the upgrade branch:\n```bash\nnpm test                  # Run project test suite\ngit add -A\ngit commit -m \"chore: upgrade @notionhq\u002Fclient to $(npm ls @notionhq\u002Fclient --depth=0 | grep @notionhq)\"\ngit checkout main && git merge -\n```\n\n## Output\n\n- SDK upgraded to the latest stable release with exact version pinned in `package.json`\n- API version explicitly set in client initialization (not relying on SDK default)\n- New property types (status, unique_id) handled in extraction logic\n- All existing API calls verified — database queries, page CRUD, block operations\n- Upgrade branch merged with clean test run\n\n## Error Handling\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `TypeError: Cannot read properties of undefined` | New property type returned by API that code does not handle | Add a default case to property type switch — see Step 2 |\n| `APIResponseError: Could not find ...` | Stale page\u002Fdatabase ID after workspace migration | Re-share pages with the integration at notion.so\u002Fmy-integrations |\n| `notionVersion is not a valid API version` | Typo or unsupported version string | Use `2022-06-28` — confirm at developers.notion.com\u002Freference\u002Fversioning |\n| Type errors on `api-endpoints` imports | Import path changed between SDK major versions | Check `node_modules\u002F@notionhq\u002Fclient\u002Fbuild\u002Fsrc\u002Fapi-endpoints.d.ts` for current exports |\n| `ENOTFOUND api.notion.com` | Network or proxy blocking Notion API | Verify DNS, check corporate proxy, test with `curl https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fusers\u002Fme` |\n| `pip install` fails for `notion-client` | Python version incompatible | Requires Python 3.7+; use `pip install --upgrade pip` first |\n\n## Examples\n\n### Rollback After Failed Upgrade\n\n```bash\n# Revert to exact previous version\nnpm install @notionhq\u002Fclient@2.2.14 --save-exact\n\n# Restore any source changes\ngit checkout -- src\u002F\n\n# Verify rollback\nnpm test\nnpm ls @notionhq\u002Fclient\n```\n\n### Adopting Comments API After Upgrade\n\n```typescript\n\u002F\u002F Available since @notionhq\u002Fclient 2.2.0\n\u002F\u002F Add a comment to a page\nawait notion.comments.create({\n  parent: { page_id: pageId },\n  rich_text: [{ text: { content: 'Automated review comment from CI' } }],\n});\n\n\u002F\u002F List all comments on a page\nconst { results: comments } = await notion.comments.list({\n  block_id: pageId,\n});\nfor (const comment of comments) {\n  const text = comment.rich_text.map(rt => rt.plain_text).join('');\n  console.log(`${comment.created_by.id}: ${text}`);\n}\n```\n\n### Detecting New Property Types in Existing Databases\n\n```typescript\n\u002F\u002F After upgrade, scan databases for new property types your code may not handle\nasync function auditPropertyTypes(databaseId: string): Promise\u003Cvoid> {\n  const db = await notion.databases.retrieve({ database_id: databaseId });\n  const knownTypes = new Set([\n    'title', 'rich_text', 'number', 'select', 'multi_select',\n    'date', 'checkbox', 'url', 'email', 'phone_number',\n    'formula', 'relation', 'rollup', 'people', 'files',\n    'created_time', 'last_edited_time', 'created_by', 'last_edited_by',\n    'status', 'unique_id',  \u002F\u002F Newer types\n  ]);\n\n  for (const [name, prop] of Object.entries(db.properties)) {\n    if (!knownTypes.has(prop.type)) {\n      console.warn(`Unknown property type \"${prop.type}\" on \"${name}\" — add handler`);\n    }\n  }\n}\n```\n\n### Deprecation Monitoring Script\n\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\n# Check for known deprecated patterns in your codebase\necho \"=== Notion SDK Deprecation Audit ===\"\n\n# Check for deprecated header format\ngrep -rn \"Notion-Version\" --include=\"*.ts\" --include=\"*.js\" src\u002F 2>\u002Fdev\u002Fnull && \\\n  echo \"WARN: Raw Notion-Version header found — use client notionVersion option instead\"\n\n# Check for untyped page responses\ngrep -rn \"as any\" --include=\"*.ts\" src\u002F 2>\u002Fdev\u002Fnull | grep -i notion && \\\n  echo \"WARN: Type assertions on Notion responses — use PageObjectResponse type\"\n\n# Check SDK version against latest\nCURRENT=$(npm ls @notionhq\u002Fclient --depth=0 2>\u002Fdev\u002Fnull | grep @notionhq | sed 's\u002F.*@\u002F\u002F')\nLATEST=$(npm view @notionhq\u002Fclient version 2>\u002Fdev\u002Fnull)\nif [ \"$CURRENT\" != \"$LATEST\" ]; then\n  echo \"UPDATE: Running $CURRENT, latest is $LATEST\"\nelse\n  echo \"OK: Running latest ($CURRENT)\"\nfi\n```\n\n## Resources\n\n- [Notion SDK Releases](https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-sdk-js\u002Freleases) — changelog for every `@notionhq\u002Fclient` version\n- [API Versioning](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fversioning) — version lifecycle and header format\n- [API Changelog](https:\u002F\u002Fdevelopers.notion.com\u002Fchangelog) — new endpoints, properties, and breaking changes\n- [Python notion-client](https:\u002F\u002Fpypi.org\u002Fproject\u002Fnotion-client\u002F) — PyPI page with version history\n- [API Status](https:\u002F\u002Fstatus.notion.so\u002F) — check for ongoing incidents before debugging upgrade issues\n\n## Next Steps\n\nAfter upgrading, apply production patterns from `notion-sdk-patterns` and verify rate limit handling with `notion-rate-limits`.\n","# Notion Upgrade & Migration\n\n## Overview\n\nStep-by-step guide for upgrading `@notionhq\u002Fclient` (Node.js) and `notion-client` (Python) SDK versions, migrating between Notion API versions, handling breaking changes, and adopting newly released features. Covers the current stable API version `2022-06-28` and the SDK feature timeline through v2.x.\n\n## Prerequisites\n\n- Existing project with `@notionhq\u002Fclient` or `notion-client` installed\n- Git repository with clean working tree (no uncommitted changes)\n- Test suite covering Notion API calls (or willingness to add verification tests)\n- `NOTION_TOKEN` environment variable configured\n\n## Instructions\n\n### Step 1: Audit Current Versions and API Surface\n\nDetermine what you are running today before changing anything.\n\n```bash\n# Node.js — check installed SDK version\nnpm ls @notionhq\u002Fclient\n\n# Node.js — check latest available\nnpm view @notionhq\u002Fclient version\n\n# Python — check installed SDK version\npip show notion-client 2>\u002Fdev\u002Fnull | grep Version\n\n# Python — check latest available\npip index versions notion-client 2>\u002Fdev\u002Fnull | head -1\n\n# Find which API version your code specifies\ngrep -rn \"notionVersion\\|Notion-Version\\|notion_version\" src\u002F lib\u002F app\u002F 2>\u002Fdev\u002Fnull\n```\n\nRecord the current SDK version and API version before proceeding. If no `notionVersion` is set explicitly, the SDK uses its built-in default (typically `2022-06-28` for current releases).\n\n**SDK version history — key milestones:**\n\n| SDK Version | Notable Additions |\n|-------------|-------------------|\n| `2.2.0` | Comments API support (`notion.comments.create`, `notion.comments.list`) |\n| `2.2.3` | Status property type in database schemas |\n| `2.2.4` | Unique ID property, verification property |\n| `2.2.13` | Improved TypeScript discriminated unions for block types |\n| `2.2.15` | Current stable — bug fixes, dependency updates |\n\n**API version timeline:**\n\n| API Version | Key Changes |\n|-------------|-------------|\n| `2022-02-22` | Rich text standardization, consistent pagination |\n| `2022-06-28` | **Current stable** — most tutorials and production apps use this |\n\n### Step 2: Perform the Upgrade\n\nCreate an isolated branch, upgrade the package, and address breaking changes before merging.\n\n**Node.js upgrade:**\n```bash\n# Create upgrade branch\ngit checkout -b upgrade\u002Fnotionhq-client-$(npm view @notionhq\u002Fclient version)\n\n# Upgrade to latest\nnpm install @notionhq\u002Fclient@latest\n\n# Review what changed\nnpm ls @notionhq\u002Fclient\ngit diff package.json package-lock.json\n```\n\n**Python upgrade:**\n```bash\ngit checkout -b upgrade\u002Fnotion-client-$(pip show notion-client 2>\u002Fdev\u002Fnull | grep Version | awk '{print $2}')\n\npip install --upgrade notion-client\n\n# Verify\npip show notion-client | grep Version\n```\n\n**Breaking changes to check after any major version bump:**\n\n```typescript\n\u002F\u002F 1. Import paths — endpoint types moved in some releases\n\u002F\u002F OLD (pre-2.2.x):\nimport type { QueryDatabaseResponse } from '@notionhq\u002Fclient\u002Fbuild\u002Fsrc\u002Fapi-endpoints';\n\u002F\u002F CURRENT (2.2.x):\nimport type {\n  PageObjectResponse,\n  DatabaseObjectResponse,\n  BlockObjectResponse,\n  QueryDatabaseResponse,\n} from '@notionhq\u002Fclient\u002Fbuild\u002Fsrc\u002Fapi-endpoints';\n\n\u002F\u002F 2. Error handling imports are stable across all 2.x versions\nimport { Client, isNotionClientError, APIErrorCode, ClientErrorCode } from '@notionhq\u002Fclient';\n\n\u002F\u002F 3. New property types — code must handle unknown types gracefully\nfunction extractProperty(prop: any): string {\n  switch (prop.type) {\n    case 'title': return prop.title.map((t: any) => t.plain_text).join('');\n    case 'rich_text': return prop.rich_text.map((t: any) => t.plain_text).join('');\n    case 'status': return prop.status?.name ?? '';       \u002F\u002F Added in 2.2.3\n    case 'unique_id': return String(prop.unique_id?.number ?? ''); \u002F\u002F Added in 2.2.4\n    default: return `[unhandled: ${prop.type}]`;\n  }\n}\n\n\u002F\u002F 4. Pin API version explicitly for reproducible behavior\nconst notion = new Client({\n  auth: process.env.NOTION_TOKEN,\n  notionVersion: '2022-06-28',  \u002F\u002F Always pin — do not rely on SDK default\n});\n```\n\n**Python breaking changes:**\n```python\nfrom notion_client import Client, APIResponseError\n\n# Pin API version explicitly\nnotion = Client(\n    auth=os.environ[\"NOTION_TOKEN\"],\n    notion_version=\"2022-06-28\",  # Explicit pin\n)\n\n# New in recent versions: comments API\ncomments = notion.comments.list(block_id=page_id)\n\n# Status property (requires SDK that supports it)\n# Returns: {\"type\": \"status\", \"status\": {\"name\": \"In Progress\", \"color\": \"blue\"}}\n```\n\n### Step 3: Verify and Test the Upgrade\n\nRun targeted verification tests to confirm nothing broke. Test each API surface your application uses.\n\n```typescript\nimport { Client } from '@notionhq\u002Fclient';\n\nconst notion = new Client({\n  auth: process.env.NOTION_TOKEN,\n  notionVersion: '2022-06-28',\n});\n\n\u002F\u002F Test 1: Authentication and user listing\nasync function verifyAuth(): Promise\u003Cvoid> {\n  const { results } = await notion.users.list({});\n  console.log(`Auth OK — ${results.length} users found`);\n}\n\n\u002F\u002F Test 2: Database query (most common operation)\nasync function verifyDatabaseQuery(databaseId: string): Promise\u003Cvoid> {\n  const response = await notion.databases.query({\n    database_id: databaseId,\n    page_size: 5,\n  });\n  console.log(`Query OK — ${response.results.length} pages, has_more=${response.has_more}`);\n\n  \u002F\u002F Verify property types are still parsed correctly\n  for (const page of response.results) {\n    if ('properties' in page) {\n      const types = Object.values(page.properties).map(p => p.type);\n      console.log(`  Property types: ${[...new Set(types)].join(', ')}`);\n    }\n  }\n}\n\n\u002F\u002F Test 3: Page creation and archival (write path)\nasync function verifyPageLifecycle(databaseId: string): Promise\u003Cvoid> {\n  const page = await notion.pages.create({\n    parent: { database_id: databaseId },\n    properties: {\n      Name: { title: [{ text: { content: `Upgrade test ${Date.now()}` } }] },\n    },\n  });\n  console.log(`Create OK — page ${page.id}`);\n  await notion.pages.update({ page_id: page.id, archived: true });\n  console.log('Archive OK');\n}\n\n\u002F\u002F Test 4: Block operations (read + append)\nasync function verifyBlocks(pageId: string): Promise\u003Cvoid> {\n  const { results } = await notion.blocks.children.list({ block_id: pageId });\n  console.log(`Block list OK — ${results.length} blocks`);\n  await notion.blocks.children.append({\n    block_id: pageId,\n    children: [{\n      paragraph: { rich_text: [{ text: { content: 'Upgrade verification block' } }] },\n    }],\n  });\n  console.log('Block append OK');\n}\n\n\u002F\u002F Test 5: Comments API (available since SDK 2.2.0)\nasync function verifyComments(pageId: string): Promise\u003Cvoid> {\n  try {\n    const { results } = await notion.comments.list({ block_id: pageId });\n    console.log(`Comments OK — ${results.length} comments`);\n  } catch (err) {\n    console.log('Comments API not available in this SDK version');\n  }\n}\n\n\u002F\u002F Run all verification\nawait verifyAuth();\nawait verifyDatabaseQuery(process.env.TEST_DB_ID!);\nawait verifyPageLifecycle(process.env.TEST_DB_ID!);\nawait verifyBlocks(process.env.TEST_PAGE_ID!);\nawait verifyComments(process.env.TEST_PAGE_ID!);\n```\n\nAfter all tests pass, merge the upgrade branch:\n```bash\nnpm test                  # Run project test suite\ngit add -A\ngit commit -m \"chore: upgrade @notionhq\u002Fclient to $(npm ls @notionhq\u002Fclient --depth=0 | grep @notionhq)\"\ngit checkout main && git merge -\n```\n\n## Output\n\n- SDK upgraded to the latest stable release with exact version pinned in `package.json`\n- API version explicitly set in client initialization (not relying on SDK default)\n- New property types (status, unique_id) handled in extraction logic\n- All existing API calls verified — database queries, page CRUD, block operations\n- Upgrade branch merged with clean test run\n\n## Error Handling\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| `TypeError: Cannot read properties of undefined` | New property type returned by API that code does not handle | Add a default case to property type switch — see Step 2 |\n| `APIResponseError: Could not find ...` | Stale page\u002Fdatabase ID after workspace migration | Re-share pages with the integration at notion.so\u002Fmy-integrations |\n| `notionVersion is not a valid API version` | Typo or unsupported version string | Use `2022-06-28` — confirm at developers.notion.com\u002Freference\u002Fversioning |\n| Type errors on `api-endpoints` imports | Import path changed between SDK major versions | Check `node_modules\u002F@notionhq\u002Fclient\u002Fbuild\u002Fsrc\u002Fapi-endpoints.d.ts` for current exports |\n| `ENOTFOUND api.notion.com` | Network or proxy blocking Notion API | Verify DNS, check corporate proxy, test with `curl https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fusers\u002Fme` |\n| `pip install` fails for `notion-client` | Python version incompatible | Requires Python 3.7+; use `pip install --upgrade pip` first |\n\n## Examples\n\n### Rollback After Failed Upgrade\n\n```bash\n# Revert to exact previous version\nnpm install @notionhq\u002Fclient@2.2.14 --save-exact\n\n# Restore any source changes\ngit checkout -- src\u002F\n\n# Verify rollback\nnpm test\nnpm ls @notionhq\u002Fclient\n```\n\n### Adopting Comments API After Upgrade\n\n```typescript\n\u002F\u002F Available since @notionhq\u002Fclient 2.2.0\n\u002F\u002F Add a comment to a page\nawait notion.comments.create({\n  parent: { page_id: pageId },\n  rich_text: [{ text: { content: 'Automated review comment from CI' } }],\n});\n\n\u002F\u002F List all comments on a page\nconst { results: comments } = await notion.comments.list({\n  block_id: pageId,\n});\nfor (const comment of comments) {\n  const text = comment.rich_text.map(rt => rt.plain_text).join('');\n  console.log(`${comment.created_by.id}: ${text}`);\n}\n```\n\n### Detecting New Property Types in Existing Databases\n\n```typescript\n\u002F\u002F After upgrade, scan databases for new property types your code may not handle\nasync function auditPropertyTypes(databaseId: string): Promise\u003Cvoid> {\n  const db = await notion.databases.retrieve({ database_id: databaseId });\n  const knownTypes = new Set([\n    'title', 'rich_text', 'number', 'select', 'multi_select',\n    'date', 'checkbox', 'url', 'email', 'phone_number',\n    'formula', 'relation', 'rollup', 'people', 'files',\n    'created_time', 'last_edited_time', 'created_by', 'last_edited_by',\n    'status', 'unique_id',  \u002F\u002F Newer types\n  ]);\n\n  for (const [name, prop] of Object.entries(db.properties)) {\n    if (!knownTypes.has(prop.type)) {\n      console.warn(`Unknown property type \"${prop.type}\" on \"${name}\" — add handler`);\n    }\n  }\n}\n```\n\n### Deprecation Monitoring Script\n\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\n# Check for known deprecated patterns in your codebase\necho \"=== Notion SDK Deprecation Audit ===\"\n\n# Check for deprecated header format\ngrep -rn \"Notion-Version\" --include=\"*.ts\" --include=\"*.js\" src\u002F 2>\u002Fdev\u002Fnull && \\\n  echo \"WARN: Raw Notion-Version header found — use client notionVersion option instead\"\n\n# Check for untyped page responses\ngrep -rn \"as any\" --include=\"*.ts\" src\u002F 2>\u002Fdev\u002Fnull | grep -i notion && \\\n  echo \"WARN: Type assertions on Notion responses — use PageObjectResponse type\"\n\n# Check SDK version against latest\nCURRENT=$(npm ls @notionhq\u002Fclient --depth=0 2>\u002Fdev\u002Fnull | grep @notionhq | sed 's\u002F.*@\u002F\u002F')\nLATEST=$(npm view @notionhq\u002Fclient version 2>\u002Fdev\u002Fnull)\nif [ \"$CURRENT\" != \"$LATEST\" ]; then\n  echo \"UPDATE: Running $CURRENT, latest is $LATEST\"\nelse\n  echo \"OK: Running latest ($CURRENT)\"\nfi\n```\n\n## Resources\n\n- [Notion SDK Releases](https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-sdk-js\u002Freleases) — changelog for every `@notionhq\u002Fclient` version\n- [API Versioning](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fversioning) — version lifecycle and header format\n- [API Changelog](https:\u002F\u002Fdevelopers.notion.com\u002Fchangelog) — new endpoints, properties, and breaking changes\n- [Python notion-client](https:\u002F\u002Fpypi.org\u002Fproject\u002Fnotion-client\u002F) — PyPI page with version history\n- [API Status](https:\u002F\u002Fstatus.notion.so\u002F) — check for ongoing incidents before debugging upgrade issues\n\n## Next Steps\n\nAfter upgrading, apply production patterns from `notion-sdk-patterns` and verify rate limit handling with `notion-rate-limits`.\n",{"name":5,"tags":24,"author":28,"license":15,"version":29,"description":30,"allowed-tools":31,"compatible-with":32},[25,26,27],"saas","productivity","notion","Jeremy Longshore \u003Cjeremy@intentsolutions.io>","1.0.0","Upgrade @notionhq\u002Fclient SDK versions and migrate between Notion API versions.\nUse when updating SDK packages, handling breaking changes between API versions,\nadopting new SDK features like comments API or status properties, or migrating Python notion-client.\nTrigger with phrases like \"upgrade notion SDK\", \"notion migration\", \"notion breaking changes\",\n\"update notionhq client\", \"notion API version upgrade\", \"notion deprecation\".\n","Read, Write, Edit, Bash(npm:*), Bash(pip:*), Bash(git:*), Glob, Grep","claude-code","main","99825ad3f3bcc6597ddcc7294a14e6e922f2b67b","skills\u002Fsaas-packs--notion-pack--notion-upgrade-migration",0,"https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills","https:\u002F\u002Fgithub.com\u002Fjukeyman","https:\u002F\u002FRJBUSINESSSOLUTIONS.ORG","Credit and Finance Expert | Developer\r\n\r\nI'm Rick Jefferson, a seasoned credit and finance expert with over a decade of experience in financial literacy,","2026-07-13 07:03:29",{"source":8,"skillName":5,"commands":43,"prompt":53,"zipAvailable":54},[44,47,50],{"tool":45,"command":46},"npx","npx skills add jukeyman\u002Fjukeyman-skills --skill notion-upgrade-migration",{"tool":48,"command":49},"bunx","bunx skills add jukeyman\u002Fjukeyman-skills --skill notion-upgrade-migration",{"tool":51,"command":52},"pnpm","pnpm dlx skills add jukeyman\u002Fjukeyman-skills --skill notion-upgrade-migration","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsaas-packs--notion-pack--notion-upgrade-migration\u002FSKILL.md",true,[],[57,64,71,78,85,93],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M79ANS2SM329NEP5ZCX106RR","zustand-store-creator","Create zustand store creator operations. Auto-activating skill for Frontend Development.\nTriggers on: zustand store creator, zustand store creator\nPart of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like \"zustand store creator\", \"zustand creator\", \"zustand\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzustand-store-creator\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M79AMZKP4YDEZ7EHG1Y7PP74","zero-trust-config-helper","Configure with zero trust config helper operations. Auto-activating skill for Security Advanced.\nTriggers on: zero trust config helper, zero trust config helper\nPart of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like \"zero trust config helper\", \"zero helper\", \"zero\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzero-trust-config-helper\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M79AMJSBCEJQNBTYNAHYN5HM","zapier-integration-helper","Assist with zapier integration helper operations. Auto-activating skill for Business Automation.\nTriggers on: zapier integration helper, zapier integration helper\nPart of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like \"zapier integration helper\", \"zapier helper\", \"zapier\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzapier-integration-helper\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M79AHJZGVMARS13VFQYRR1MP","yaml-config-validator","Validate yaml config validator operations. Auto-activating skill for DevOps Basics.\nTriggers on: yaml config validator, yaml config validator\nPart of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like \"yaml config validator\", \"yaml validator\", \"yaml\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fyaml-config-validator\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":89,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M79AHGDZRN0020RDQSQDPAM8","xvary-stock-research","Thesis-driven equity analysis from public SEC EDGAR and market data; \u002Fanalyze, \u002Fscore, \u002Fcompare workflows with bundled Python tools (Claude Code, Cursor, Codex).","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxvary-stock-research\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxvary-stock-research\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":19},"01M79AHCYJ9FV9RMHQ24HDRN33","xss-vulnerability-scanner","Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals.\nTriggers on: xss vulnerability scanner, xss vulnerability scanner\nPart of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like \"xss vulnerability scanner\", \"xss scanner\", \"xss\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxss-vulnerability-scanner\u002FSKILL.md",[],[]]