|
| 1 | +#CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +##Repository Overview |
| 6 | + |
| 7 | +Official Notion SDK for JavaScript - a TypeScript client library providing type-safe access to the Notion API. |
| 8 | + |
| 9 | +-**Package**:`@notionhq/client` |
| 10 | +-**Target Runtime**: Node.js ≥ 18 |
| 11 | +-**TypeScript**: ≥ 5.9 |
| 12 | +-**Build System**: TypeScript compiler (tsc) |
| 13 | +-**Test Framework**: Jest with ts-jest |
| 14 | + |
| 15 | +##Development Commands |
| 16 | + |
| 17 | +###Building |
| 18 | + |
| 19 | +```bash |
| 20 | +npm run build# Runs: npm run clean && tsc |
| 21 | +npm run clean# Remove build/ directory |
| 22 | +``` |
| 23 | + |
| 24 | +###Testing |
| 25 | + |
| 26 | +```bash |
| 27 | +npmtest# Run all tests in test/ |
| 28 | +``` |
| 29 | + |
| 30 | +To run a single test file: |
| 31 | + |
| 32 | +```bash |
| 33 | +npx jest test/helpers.test.ts |
| 34 | +``` |
| 35 | + |
| 36 | +###Linting and Formatting |
| 37 | + |
| 38 | +```bash |
| 39 | +npm run lint# Runs prettier, eslint, and cspell |
| 40 | +npm run prettier# Format code with prettier |
| 41 | +``` |
| 42 | + |
| 43 | +###Examples |
| 44 | + |
| 45 | +```bash |
| 46 | +npm run install:examples# Install dependencies for all example projects |
| 47 | +npm run examples:typecheck# Type-check all examples |
| 48 | +``` |
| 49 | + |
| 50 | +##Code Architecture |
| 51 | + |
| 52 | +###Client Structure |
| 53 | + |
| 54 | +The SDK is organized around a central`Client` class (src/Client.ts) that exposes namespaced endpoints: |
| 55 | + |
| 56 | +-`client.blocks` - Block CRUD operations and children management |
| 57 | +-`client.databases` - Database CRUD operations |
| 58 | +-`client.dataSources` - Data source operations and querying |
| 59 | +-`client.pages` - Page CRUD operations and property retrieval |
| 60 | +-`client.users` - User listing and retrieval |
| 61 | +-`client.comments` - Comment CRUD operations |
| 62 | +-`client.fileUploads` - File upload lifecycle (create, send, complete, list) |
| 63 | +-`client.oauth` - OAuth token, introspect, and revoke operations |
| 64 | +-`client.search()` - Search across workspace |
| 65 | + |
| 66 | +Each endpoint namespace contains methods like`retrieve`,`create`,`update`,`delete`, and`list` as appropriate. Child resources use nested objects (e.g.,`client.blocks.children.list()`). |
| 67 | + |
| 68 | +###Request Flow |
| 69 | + |
| 70 | +All API calls flow through`Client.request()` which: |
| 71 | + |
| 72 | +1. Constructs the full URL from`baseUrl` +`path` |
| 73 | +2. Adds authentication headers (from client-level`auth` or request-level override) |
| 74 | +3. Sets`Notion-Version` header (defaults to "2025-09-03") |
| 75 | +4. Handles request timeout (default 60s) |
| 76 | +5. Processes response or throws typed errors |
| 77 | + |
| 78 | +###Type System |
| 79 | + |
| 80 | +**Generated Types** (`src/api-endpoints.ts`): |
| 81 | + |
| 82 | +-**DO NOT EDIT** - This file is auto-generated from the Notion API specification |
| 83 | +- Contains all request/response types and endpoint definitions |
| 84 | +- Each endpoint exports:`Parameters`,`Response` types, and a descriptor with`path`,`method`,`queryParams`,`bodyParams` |
| 85 | + |
| 86 | +**Type Guards** (`src/type-utils.ts` and`src/helpers.ts`): |
| 87 | + |
| 88 | +-`isFullPage()`,`isFullBlock()`,`isFullDataSource()`,`isFullUser()`,`isFullComment()` |
| 89 | +-`isFullPageOrDataSource()` - handles union types |
| 90 | +-`isNotionClientError()` - for error handling |
| 91 | + |
| 92 | +**ID Extraction** (`src/helpers.ts`): |
| 93 | + |
| 94 | +-`extractNotionId()`,`extractPageId()`,`extractDatabaseId()`,`extractBlockId()` |
| 95 | +- Extract IDs from Notion URLs or format raw IDs |
| 96 | + |
| 97 | +###Error Handling |
| 98 | + |
| 99 | +Three error types (all in`src/errors.ts`): |
| 100 | + |
| 101 | +-`APIResponseError` - HTTP errors from Notion API with error codes from`APIErrorCode` |
| 102 | +-`RequestTimeoutError` - Request exceeded timeout |
| 103 | +-`UnknownHTTPResponseError` - Unexpected HTTP responses |
| 104 | + |
| 105 | +Error codes are in two enums: |
| 106 | + |
| 107 | +-`APIErrorCode` - Server-side errors (unauthorized, rate_limited, object_not_found, etc.) |
| 108 | +-`ClientErrorCode` - Client-side errors (request_timeout, response_error) |
| 109 | + |
| 110 | +###Pagination |
| 111 | + |
| 112 | +Two utilities in`src/helpers.ts`: |
| 113 | + |
| 114 | +-`iteratePaginatedAPI()` - Async iterator for memory-efficient pagination |
| 115 | +-`collectPaginatedAPI()` - Collects all results into array (use for small datasets) |
| 116 | + |
| 117 | +Both accept a list function and parameters, automatically handling`start_cursor`/`next_cursor`. |
| 118 | + |
| 119 | +###Logging |
| 120 | + |
| 121 | +Configurable logging system (`src/logging.ts`): |
| 122 | + |
| 123 | +- Four levels: DEBUG, INFO, WARN, ERROR (via`LogLevel` enum) |
| 124 | +- Default: WARN level to console |
| 125 | +- Custom loggers via`logger` option (receives level, message, extraInfo) |
| 126 | +- Debug mode logs full request/response bodies |
| 127 | + |
| 128 | +##Important Constraints |
| 129 | + |
| 130 | +###DO NOT EDIT |
| 131 | + |
| 132 | +-`src/api-endpoints.ts` - Auto-generated from API spec (see file header) |
| 133 | +-`build/` directory - Compiled output |
| 134 | + |
| 135 | +###Code Style |
| 136 | + |
| 137 | +-**NO semicolons** (enforced by Prettier) |
| 138 | +-**NO redundant comments** - Only add comments explaining "why", not "what" |
| 139 | +-**NO`as any`** - Use type guards from`src/type-utils.ts` |
| 140 | +- Comment length: max 80 characters per line |
| 141 | +- Use CommonJS (`require`/`module.exports`) not ES6 imports |
| 142 | + |
| 143 | +###Testing Requirements |
| 144 | + |
| 145 | +- Always run`npm run build && npm test` before committing |
| 146 | +- Add tests for new functionality in`test/` |
| 147 | +- CI validates on Node.js 18, 19, 20, 22 |
| 148 | + |
| 149 | +###Publishing Workflow |
| 150 | + |
| 151 | +```bash |
| 152 | +npm run prepublishOnly# Runs: checkLoggedIn && lint && test |
| 153 | +``` |
| 154 | + |
| 155 | +##Key Files |
| 156 | + |
| 157 | +-`src/Client.ts` - Main client implementation with all endpoint namespaces |
| 158 | +-`src/index.ts` - Public API surface (all exports) |
| 159 | +-`src/api-endpoints.ts` - Generated API types and endpoint descriptors |
| 160 | +-`src/errors.ts` - Error types and error handling utilities |
| 161 | +-`src/helpers.ts` - Pagination utilities and type guards |
| 162 | +-`src/type-utils.ts` - TypeScript type guards and utilities |
| 163 | +-`src/logging.ts` - Logging system |
| 164 | +-`src/utils.ts` - Internal utilities (pick, isObject) |
| 165 | +-`src/fetch-types.ts` - Fetch API type definitions |
| 166 | + |
| 167 | +##Making Changes |
| 168 | + |
| 169 | +###Adding New Functionality |
| 170 | + |
| 171 | +1. Implement in appropriate source file |
| 172 | +2. Add exports to`src/index.ts` |
| 173 | +3. Add tests in`test/` |
| 174 | +4. Run`npm run build && npm test` |
| 175 | +5. Run`npm run lint` to validate formatting and spelling |
| 176 | + |
| 177 | +###Working with API Endpoints |
| 178 | + |
| 179 | +- API endpoint changes must come from upstream (api-endpoints.ts is generated) |
| 180 | +- New endpoint types are automatically available once api-endpoints.ts is regenerated |
| 181 | +- Wire up new endpoints in Client.ts following existing patterns |
| 182 | + |
| 183 | +###Type Guards |
| 184 | + |
| 185 | +If adding response type discriminators, add type guard functions to`src/helpers.ts` following the`isFullX()` pattern and export from`src/index.ts`. |