npm package: @openpets/notion
Description: Full-featured Notion integration for managing databases, pages, blocks, and comments through the official Notion API
Latest version: 1.0.2

# Notion Plugin

Full-featured Notion integration for OpenCode, providing comprehensive access to databases, pages, blocks, users, and comments through the official Notion API.

## Features

- **Search**: Search across all accessible pages and databases
- **Databases**: List, query, and get schema information
- **Pages**: Create, read, update, archive, and restore pages
- **Blocks**: Read page content, append blocks, delete blocks
- **Users**: List workspace users and get user details
- **Comments**: Read and add comments to pages

## Setup

### 1. Create a Notion Integration

1. Go to [https://www.notion.so/my-integrations](https://www.notion.so/my-integrations)
2. Click **New integration**
3. Give it a name (e.g., "OpenCode Integration")
4. Select your workspace
5. Under **Capabilities**, ensure you have:
   - Read content
   - Update content
   - Insert content
   - Read comments
   - Insert comments
   - Read user information
6. Click **Submit**
7. Copy the **Internal Integration Token** (starts with `secret_`)

### 2. Configure Environment

Add to your `.env` file:

```bash
NOTION_INTERNAL_INTEGRATION_SECRET=secret_your_token_here
```

### 3. Share Pages/Databases with Your Integration

**Important**: Your integration can only access pages and databases explicitly shared with it.

1. Open a page or database in Notion
2. Click the **...** menu in the top right
3. Select **Connections** (or **Add connections**)
4. Find and add your integration

## Available Tools

### Connection & Search
| Tool | Description |
|------|-------------|
| `notion-test-connection` | Test connection and get workspace info |
| `notion-search` | Search across all pages and databases |

### Databases
| Tool | Description |
|------|-------------|
| `notion-list-databases` | List all accessible databases |
| `notion-get-database` | Get database schema and properties |
| `notion-query-database` | Query database with filters and sorting |

### Pages
| Tool | Description |
|------|-------------|
| `notion-get-page` | Get page properties and metadata |
| `notion-get-page-content` | Get all blocks (content) from a page |
| `notion-create-page` | Create a new page in a database or as child |
| `notion-update-page` | Update page properties |
| `notion-archive-page` | Archive (soft delete) a page |
| `notion-restore-page` | Restore an archived page |

### Blocks
| Tool | Description |
|------|-------------|
| `notion-get-block-children` | Get child blocks of a block |
| `notion-append-blocks` | Add content blocks to a page |
| `notion-delete-block` | Delete a block |

### Users
| Tool | Description |
|------|-------------|
| `notion-list-users` | List all workspace users |
| `notion-get-user` | Get user details |

### Comments
| Tool | Description |
|------|-------------|
| `notion-get-comments` | Get comments on a page or block |
| `notion-add-comment` | Add a comment to a page |

## Usage Examples

### Search for Pages

```
Search for all pages containing "meeting notes"
```

### Query a Database

```
Query my tasks database and show items where Status is "In Progress"
```

The filter follows Notion's filter format:
```json
{"property": "Status", "status": {"equals": "In Progress"}}
```

### Create a Page in a Database

```
Create a new task called "Review PRs" in my tasks database with status "To Do"
```

### Add Content to a Page

```
Add a paragraph "Project kickoff meeting scheduled for Monday" to page abc123
```

Block types supported:
- `paragraph` - Regular text
- `heading_1`, `heading_2`, `heading_3` - Headers
- `bulleted_list_item`, `numbered_list_item` - Lists
- `to_do` - Checkboxes with `checked` property
- `quote` - Blockquotes
- `callout` - Callout boxes with `icon` property
- `code` - Code blocks with `language` property
- `divider` - Horizontal lines
- `toggle` - Collapsible sections

### Get Page Content

```
Show me the contents of page abc123
```

## Filter Examples for Database Queries

### Status Filter
```json
{"property": "Status", "status": {"equals": "Done"}}
```

### Text Contains
```json
{"property": "Name", "rich_text": {"contains": "project"}}
```

### Checkbox
```json
{"property": "Completed", "checkbox": {"equals": true}}
```

### Date Filter
```json
{"property": "Due Date", "date": {"on_or_before": "2024-12-31"}}
```

### Compound Filters (AND)
```json
{
  "and": [
    {"property": "Status", "status": {"equals": "In Progress"}},
    {"property": "Priority", "select": {"equals": "High"}}
  ]
}
```

### Compound Filters (OR)
```json
{
  "or": [
    {"property": "Status", "status": {"equals": "Done"}},
    {"property": "Status", "status": {"equals": "Archived"}}
  ]
}
```

## Property Update Examples

### Update Status
```json
{"Status": {"status": {"name": "Done"}}}
```

### Update Text
```json
{"Description": {"rich_text": [{"text": {"content": "Updated description"}}]}}
```

### Update Checkbox
```json
{"Completed": {"checkbox": true}}
```

### Update Select
```json
{"Priority": {"select": {"name": "High"}}}
```

### Update Multi-Select
```json
{"Tags": {"multi_select": [{"name": "urgent"}, {"name": "bug"}]}}
```

### Update Date
```json
{"Due Date": {"date": {"start": "2024-12-31"}}}
```

### Update Number
```json
{"Score": {"number": 95}}
```

## Troubleshooting

### "Object not found" Error
- Make sure the page/database is shared with your integration
- Verify the ID is correct (copy from Notion URL or use search)

### "Unauthorized" Error
- Check your `NOTION_INTERNAL_INTEGRATION_SECRET` is set correctly
- Ensure the token hasn't been revoked

### Can't See Pages/Databases
- You must explicitly share each page/database with your integration
- Child pages inherit parent permissions, but databases must be shared individually

### Filter Not Working
- Use `notion-get-database` to see available property names and types
- Property names are case-sensitive
- Check the filter syntax matches the property type

## Links

- [Notion API Documentation](https://developers.notion.com/)
- [Notion SDK for JavaScript](https://github.com/makenotion/notion-sdk-js)
- [Filter Documentation](https://developers.notion.com/reference/post-database-query-filter)