notion-sdk

# Notion SDK Skill

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

## 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