notion-sdk

What this skill does

# Notion SDK Skill

Control Notion programmatically using the official `notion-client` Python SDK. See [PyPI](https://pypi.org/project/notion-client/) for current version.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use This Skill

Use this skill when:

- Creating pages or databases in Notion via API
- Querying Notion databases programmatically
- Adding blocks (text, code, headings) to Notion pages
- Automating Notion workflows with Python
- Integrating external data sources with Notion

## Preflight: Token Collection

Before any Notion API operation, collect the integration token:

```
AskUserQuestion(questions=[{
    "question": "Please provide your Notion Integration Token (starts with ntn_ or secret_)",
    "header": "Notion Token",
    "options": [
        {"label": "I have a token ready", "description": "Token from notion.so/my-integrations"},
        {"label": "Need to create one", "description": "Go to notion.so/my-integrations → New integration"}
    ],
    "multiSelect": false
}])
```

After user provides token:

1. Validate format (must start with `ntn_` or `secret_`)
2. Test with `validate_token()` from `scripts/notion_wrapper.py`
3. Remind user: **Each page/database must be shared with the integration**

## Quick Start

### 1. Create a Page in Database

```python
from notion_client import Client
from scripts.create_page import (
    create_database_page,
    title_property,
    status_property,
    date_property,
)

client = Client(auth="ntn_...")
page = create_database_page(
    client,
    data_source_id="abc123...",  # Database ID
    properties={
        "Name": title_property("My New Task"),
        "Status": status_property("In Progress"),
        "Due Date": date_property("2025-12-31"),
    }
)
print(f"Created: {page['url']}")
```

### 2. Add Content Blocks

```python
from scripts.add_blocks import (
    append_blocks,
    heading,
    paragraph,
    bullet,
    code_block,
    callout,
)

blocks = [
    heading("Overview", level=2),
    paragraph("This page was created via the Notion API."),
    callout("Remember to share the page with your integration!", emoji="⚠️"),
    heading("Tasks", level=3),
    bullet("First task"),
    bullet("Second task"),
    code_block("print('Hello, Notion!')", language="python"),
]
append_blocks(client, page["id"], blocks)
```

### 3. Query Database

```python
from scripts.query_database import (
    query_data_source,
    checkbox_filter,
    status_filter,
    and_filter,
    sort_by_property,
)

# Find incomplete high-priority items
results = query_data_source(
    client,
    data_source_id="abc123...",
    filter_obj=and_filter(
        checkbox_filter("Done", False),
        status_filter("Priority", "High")
    ),
    sorts=[sort_by_property("Due Date", "ascending")]
)
for page in results:
    title = page["properties"]["Name"]["title"][0]["plain_text"]
    print(f"- {title}")
```

## Available Scripts

| Script              | Purpose                                       |
| ------------------- | --------------------------------------------- |
| `notion_wrapper.py` | Client setup, token validation, retry wrapper |
| `create_page.py`    | Create pages, property builders               |
| `add_blocks.py`     | Append blocks, block type builders            |
| `query_database.py` | Query, filter, sort, search                   |

## References

- [Property Types](./references/property-types.md) - All 24 property types with examples
- [Block Types](./references/block-types.md) - All block types with structures
- [Rich Text](./references/rich-text.md) - Formatting, links, mentions
- [Pagination](./references/pagination.md) - Handling large result sets

## Important Constraints

### Rate Limits

- **3 requests/second** average (burst tolerated briefly)
- Use `api_call_with_retry()` for automatic rate limit handling
- 429 responses include `Retry-After` header

### Authentication Model

- **Page-level sharing** required (not workspace-wide)
- User must explicitly add integration to each page/database:
  - Page → ... menu → Connections → Add connection → Select integration

### API Version (v2.6.0+)

- Uses `data_source_id` instead of `database_id` for multi-source databases
- Legacy `database_id` still works for simple databases
- Scripts handle both patterns automatically

### Operations NOT Supported

- Workspace settings modification
- User permissions management
- Template creation/management
- Billing/subscription access

## API Behavior Patterns

Insights discovered through integration testing (test citations for verification).

### Rate Limiting & Retry Logic

`api_call_with_retry()` handles transient failures automatically:

| Error Type       | Behavior          | Wait Strategy                            |
| ---------------- | ----------------- | ---------------------------------------- |
| 429 Rate Limited | Retries           | Respects Retry-After header (default 1s) |
| 500 Server Error | Retries           | Exponential backoff: 1s, 2s, 4s          |
| Auth/Validation  | Fails immediately | No retry                                 |

_Citation: `test_client.py::TestRetryLogic` (lines 146-193)_

### Read-After-Write Consistency

Newly created blocks may not be immediately queryable. Add 0.5s minimum delay:

```python
append_blocks(client, page_id, blocks)
time.sleep(0.5)  # Eventual consistency delay
children = client.blocks.children.list(page_id)
```

_Citation: `test_integration.py::TestBlockAppend::test_retrieve_appended_blocks` (line 298)_

### v2.6.0 API Migration

| Old Pattern                     | New Pattern (v2.6.0+)              |
| ------------------------------- | ---------------------------------- |
| `client.databases.query()`      | `client.data_sources.query()`      |
| `filter: {"value": "database"}` | `filter: {"value": "data_source"}` |

_Citation: `test_integration.py::TestDatabaseQuery` (line 110)_

### Archive-Only Deletion

Pages cannot be permanently deleted via API - only archived (moved to trash):

```python
client.pages.update(page_id, archived=True)  # Trash, not delete
```

_Citation: `test_integration.py` cleanup fixture (lines 72-76)_

## Edge Cases & Validation

### Property Builder Edge Cases

| Input             | Behavior                      | Valid? |
| ----------------- | ----------------------------- | ------ |
| Empty string `""` | Creates empty content         | Yes    |
| Empty array `[]`  | Clears multi-select/relations | Yes    |
| `None` for number | Clears property value         | Yes    |
| Zero `0`          | Valid number (not falsy)      | Yes    |
| Negative `-42`    | Valid number                  | Yes    |
| Unicode/emoji     | Fully preserved               | Yes    |

_Citation: `test_property_builders.py::TestPropertyBuildersEdgeCases` (lines 302-341)_

### Input Validation Responsibility

Builders are intentionally permissive - validation happens at API level:

| Property | Builder Accepts | API Validates    |
| -------- | --------------- | ---------------- |
| Date     | Any string      | ISO 8601 only    |
| URL      | Any string      | Valid URL format |
| Checkbox | Truthy values   | Boolean expected |

**Best Practice**: Validate in your application before building properties.

_Citation: `test_property_builders.py::TestPropertyBuildersInvalidInputs` (lines 347-376)_

### Token Validation

- Case-sensitive: Only lowercase `ntn_` and `secret_` valid
- Format check happens before API call (saves unnecessary requests)
- Empty/whitespace tokens rejected immediately

_Citation: `test_client.py::TestClientEdgeCases` (lines 196-224)_

## Query & Filter Patterns

### Compound Filter Composition

```python
# Empty compound (matches all)
and_filter()  # {"and": []}

# Deep nesting supported
and_filter(
    or_filter(filter_a, filter_b),
    and_fil