@bitefoundry/notion 0.1.3 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +137 -134
- package/docs/API.md +35 -0
- package/docs/MCP.md +48 -0
- package/docs/NPM.md +21 -21
- package/docs/openapi.yaml +171 -0
- package/package.json +53 -50
package/README.md
CHANGED
|
@@ -1,134 +1,137 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# `@bitefoundry/notion`
|
|
4
|
-
|
|
5
|
-
**Notion-native terminal workspace & AI agent toolkit — Editorial Pages, Interactive Blocks, Databases (Table/Board/List), CLI · TUI · HTTP API · MCP.**
|
|
6
|
-
|
|
7
|
-
[](https://www.npmjs.com/package/@bitefoundry/notion)
|
|
8
|
-
[](docs/NPM.md)
|
|
9
|
-
[](Cargo.toml)
|
|
10
|
-
[](package.json)
|
|
11
|
-
|
|
12
|
-
<br />
|
|
13
|
-
|
|
14
|
-

|
|
15
|
-
|
|
16
|
-
</div>
|
|
17
|
-
|
|
18
|
-
---
|
|
19
|
-
|
|
20
|
-
## Highlights
|
|
21
|
-
|
|
22
|
-
| Pillar | Capabilities |
|
|
23
|
-
| :--- | :--- |
|
|
24
|
-
| **Minimal-Chrome TUI** | Authentic Notion editorial aesthetic (`notion` / `nt`): 1-line **Breadcrumb Bar**, collapsible **Workspace Sidebar (`[`)** with Favorites & nested tree, **Centered (~88 col) / Full Width (`w`) Page Canvas**, 10 canonical Notion pill colors, live interactive **`to_do` checkboxes (`Space`/`x`)** & **`toggle` blocks**, **Database Table (`1`) / Board Kanban (`2`) / List (`3`) views**, **Comments Peek Drawer (`C`)**, **Quick Find (`Ctrl+K`)**, **Multi-Workspace Switcher (`Ctrl+S`)**, and **5 curated palettes** (`Clean Dark`, `Warm Paper`, `Tokyo Night`, `Catppuccin`, `Nord`). |
|
|
25
|
-
| **High-Res Terminal Images** | Native inline image previews for Notion-hosted & external media via **Kitty Graphics**, **iTerm2**, **Sixel**, and **24-bit Truecolor Half-Block (`▀`)** fallback (`v` HD modal & `notion download`). |
|
|
26
|
-
| **Local SQLite FTS5 + IPC Daemon** | Workspace-scoped SQLite WAL + FTS5 cache (`pages`, `databases`, `blocks`, `comments`, `pages_fts`) with automatic `<3`-char Korean/CJK `LIKE` fallback, plus single-instance background sync IPC daemon (`notion daemon start`). |
|
|
27
|
-
| **4-in-1 Agent Interface** | Same binary powers the **Interactive TUI**, scriptable **`--json` CLI**, local **HTTP JSON API** (`notion serve`, `:8791`), and **stdio MCP server** (`notion mcp`, **
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
## Quick Start
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
# 1. Install globally (links `notion` and `nt` native binaries)
|
|
35
|
-
npm i -g @bitefoundry/notion
|
|
36
|
-
|
|
37
|
-
# 2. Authenticate — Internal Integration Token (30-second setup) or Public OAuth 2.0
|
|
38
|
-
notion login --token ntn_...
|
|
39
|
-
# Or Public OAuth 2.0 loopback:
|
|
40
|
-
notion login --oauth --client-id "$NOTION_CLIENT_ID" --client-secret "$NOTION_CLIENT_SECRET"
|
|
41
|
-
|
|
42
|
-
# 3. Sync your workspace & launch the Notion-native TUI
|
|
43
|
-
notion sync
|
|
44
|
-
notion # alias: nt
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
---
|
|
48
|
-
|
|
49
|
-
## Keybindings Cheat Sheet
|
|
50
|
-
|
|
51
|
-
| Key | Action | Context |
|
|
52
|
-
| :--- | :--- | :--- |
|
|
53
|
-
| `[` / `Ctrl+B` | Toggle collapsible Workspace Sidebar | Global |
|
|
54
|
-
| `Tab` / `Shift+Tab` | Cycle focus across Sidebar, Canvas, and Comments Drawer | Global |
|
|
55
|
-
| `j` `k` / `↑` `↓` | Move across sidebar tree, page blocks, or database rows | Global |
|
|
56
|
-
| `Space` / `x` | Check/uncheck live `to_do` block or expand/collapse `toggle` block | Page Canvas |
|
|
57
|
-
| `w` / `f` / `y` | Toggle Centered vs Full Width / Favorite star / Copy code block | Page Canvas |
|
|
58
|
-
| `a` / `n` / `e` | Slash Quick Append (`/h1`, `/todo`, `/callout`) / New Page / `$EDITOR` | Page / Database |
|
|
59
|
-
| `C` | Toggle right-split Comments Peek Drawer & reply inline | Page Canvas |
|
|
60
|
-
| `1` / `2` / `3` | Switch Database views: **Table** / **Board (Kanban)** / **List** | Database |
|
|
61
|
-
| `f` / `s` / `m` | Filter rows / Cycle sort / Move Kanban card to another Status column | Database |
|
|
62
|
-
| `Ctrl+K` / `Ctrl+P` | Quick Find & Command Palette (FTS5 search + workspace commands) | Global |
|
|
63
|
-
| `u` / `Ctrl+F` / `v` | Link Extractor / File Picker (`z` zoxide) / HD Image Preview | Global |
|
|
64
|
-
| `Ctrl+S` / `Ctrl+,` / `?` | Switch Workspace / Settings & Palettes / Keyboard Shortcuts Help | Global |
|
|
65
|
-
|
|
66
|
-
---
|
|
67
|
-
|
|
68
|
-
## CLI, HTTP API & MCP
|
|
69
|
-
|
|
70
|
-
### CLI (`--json` ready)
|
|
71
|
-
|
|
72
|
-
```bash
|
|
73
|
-
# Search, read, append & export Notion pages
|
|
74
|
-
notion search "Q4 Roadmap" --json
|
|
75
|
-
notion pages list --json
|
|
76
|
-
notion pages get "Q4 Launch Plan"
|
|
77
|
-
notion pages
|
|
78
|
-
notion pages
|
|
79
|
-
notion
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
notion
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
notion
|
|
86
|
-
notion
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
notion
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
notion
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
| [`@bitefoundry/
|
|
129
|
-
| [`@bitefoundry/
|
|
130
|
-
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# `@bitefoundry/notion`
|
|
4
|
+
|
|
5
|
+
**Notion-native terminal workspace & AI agent toolkit — Editorial Pages, Interactive Blocks, Databases (Table/Board/List), CLI · TUI · HTTP API · MCP.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@bitefoundry/notion)
|
|
8
|
+
[](docs/NPM.md)
|
|
9
|
+
[](https://github.com/BiteFoundry/notion/blob/master/Cargo.toml)
|
|
10
|
+
[](package.json)
|
|
11
|
+
|
|
12
|
+
<br />
|
|
13
|
+
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Highlights
|
|
21
|
+
|
|
22
|
+
| Pillar | Capabilities |
|
|
23
|
+
| :--- | :--- |
|
|
24
|
+
| **Minimal-Chrome TUI** | Authentic Notion editorial aesthetic (`notion` / `nt`): 1-line **Breadcrumb Bar**, collapsible **Workspace Sidebar (`[`)** with Favorites & nested tree, **Centered (~88 col) / Full Width (`w`) Page Canvas**, 10 canonical Notion pill colors, live interactive **`to_do` checkboxes (`Space`/`x`)** & **`toggle` blocks**, **Database Table (`1`) / Board Kanban (`2`) / List (`3`) views**, **Comments Peek Drawer (`C`)**, **Quick Find (`Ctrl+K`)**, **Multi-Workspace Switcher (`Ctrl+S`)**, and **5 curated palettes** (`Clean Dark`, `Warm Paper`, `Tokyo Night`, `Catppuccin`, `Nord`). |
|
|
25
|
+
| **High-Res Terminal Images** | Native inline image previews for Notion-hosted & external media via **Kitty Graphics**, **iTerm2**, **Sixel**, and **24-bit Truecolor Half-Block (`▀`)** fallback (`v` HD modal & `notion download`). |
|
|
26
|
+
| **Local SQLite FTS5 + IPC Daemon** | Workspace-scoped SQLite WAL + FTS5 cache (`pages`, `databases`, `blocks`, `comments`, `pages_fts`) with automatic `<3`-char Korean/CJK `LIKE` fallback, plus single-instance background sync IPC daemon (`notion daemon start`). |
|
|
27
|
+
| **4-in-1 Agent Interface** | Same binary powers the **Interactive TUI**, scriptable **`--json` CLI**, local **HTTP JSON API** (`notion serve`, `:8791`), and **stdio MCP server** (`notion mcp`, **19 typed tools** with `confirm: true` archive guard). |
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# 1. Install globally (links `notion` and `nt` native binaries)
|
|
35
|
+
npm i -g @bitefoundry/notion
|
|
36
|
+
|
|
37
|
+
# 2. Authenticate — Internal Integration Token (30-second setup) or Public OAuth 2.0
|
|
38
|
+
notion login --token ntn_...
|
|
39
|
+
# Or Public OAuth 2.0 loopback:
|
|
40
|
+
notion login --oauth --client-id "$NOTION_CLIENT_ID" --client-secret "$NOTION_CLIENT_SECRET"
|
|
41
|
+
|
|
42
|
+
# 3. Sync your workspace & launch the Notion-native TUI
|
|
43
|
+
notion sync
|
|
44
|
+
notion # alias: nt
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Keybindings Cheat Sheet
|
|
50
|
+
|
|
51
|
+
| Key | Action | Context |
|
|
52
|
+
| :--- | :--- | :--- |
|
|
53
|
+
| `[` / `Ctrl+B` | Toggle collapsible Workspace Sidebar | Global |
|
|
54
|
+
| `Tab` / `Shift+Tab` | Cycle focus across Sidebar, Canvas, and Comments Drawer | Global |
|
|
55
|
+
| `j` `k` / `↑` `↓` | Move across sidebar tree, page blocks, or database rows | Global |
|
|
56
|
+
| `Space` / `x` | Check/uncheck live `to_do` block or expand/collapse `toggle` block | Page Canvas |
|
|
57
|
+
| `w` / `f` / `y` | Toggle Centered vs Full Width / Favorite star / Copy code block | Page Canvas |
|
|
58
|
+
| `a` / `n` / `e` | Slash Quick Append (`/h1`, `/todo`, `/callout`) / New Page / `$EDITOR` | Page / Database |
|
|
59
|
+
| `C` | Toggle right-split Comments Peek Drawer & reply inline | Page Canvas |
|
|
60
|
+
| `1` / `2` / `3` | Switch Database views: **Table** / **Board (Kanban)** / **List** | Database |
|
|
61
|
+
| `f` / `s` / `m` | Filter rows / Cycle sort / Move Kanban card to another Status column | Database |
|
|
62
|
+
| `Ctrl+K` / `Ctrl+P` | Quick Find & Command Palette (FTS5 search + workspace commands) | Global |
|
|
63
|
+
| `u` / `Ctrl+F` / `v` | Link Extractor / File Picker (`z` zoxide) / HD Image Preview | Global |
|
|
64
|
+
| `Ctrl+S` / `Ctrl+,` / `?` | Switch Workspace / Settings & Palettes / Keyboard Shortcuts Help | Global |
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## CLI, HTTP API & MCP
|
|
69
|
+
|
|
70
|
+
### CLI (`--json` ready)
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
# Search, read, append & export Notion pages
|
|
74
|
+
notion search "Q4 Roadmap" --json
|
|
75
|
+
notion pages list --json
|
|
76
|
+
notion pages get "Q4 Launch Plan"
|
|
77
|
+
notion pages get "Q4 Launch Plan" --json --compact
|
|
78
|
+
notion pages edit "Q4 Launch Plan" --editor
|
|
79
|
+
notion pages append "Q4 Launch Plan" "/todo Tag v1.0 release"
|
|
80
|
+
notion pages export "Q4 Launch Plan" --out launch-plan.md
|
|
81
|
+
notion blocks edit <block-id> --text "Release **verified**" --json
|
|
82
|
+
notion blocks toggle <block-id>
|
|
83
|
+
|
|
84
|
+
# Query & create Notion database items
|
|
85
|
+
notion db list --json
|
|
86
|
+
notion db query "Q4 Roadmap" --json
|
|
87
|
+
notion db create-item "Q4 Roadmap" --title "Ship v1.0" --status "In Progress"
|
|
88
|
+
notion comments add "Q4 Launch Plan" "Green light for launch!"
|
|
89
|
+
notion download <url-or-block-id> --json
|
|
90
|
+
|
|
91
|
+
# Multi-workspace profiles & background sync daemon
|
|
92
|
+
notion workspaces list
|
|
93
|
+
notion workspaces add work --token ntn_...
|
|
94
|
+
notion workspaces use work
|
|
95
|
+
notion daemon start
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Local HTTP JSON API (`notion serve`)
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
notion serve --host 127.0.0.1 --port 8791 --api-key "$API_TOKEN"
|
|
102
|
+
curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8791/api/v1/search?q=Roadmap"
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Full endpoint catalog and OpenAPI schema: **[docs/API.md](docs/API.md)** · **[docs/openapi.yaml](docs/openapi.yaml)**.
|
|
106
|
+
|
|
107
|
+
### MCP Server (`notion mcp` — 19 Tools)
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"mcpServers": {
|
|
112
|
+
"notion": {
|
|
113
|
+
"command": "notion",
|
|
114
|
+
"args": ["mcp"]
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Full tool catalog and argument schemas: **[docs/MCP.md](docs/MCP.md)** · npm packaging details: **[docs/NPM.md](docs/NPM.md)**.
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## `@bitefoundry` Enterprise Terminal Suite
|
|
125
|
+
|
|
126
|
+
| Package | Commands | Workspace | Interfaces |
|
|
127
|
+
| :--- | :--- | :--- | :--- |
|
|
128
|
+
| [`@bitefoundry/teams`](https://www.npmjs.com/package/@bitefoundry/teams) | `teams` | Microsoft Teams (Chats, Channels, Meetings & Threads) | TUI · CLI · HTTP · MCP |
|
|
129
|
+
| [`@bitefoundry/outlook`](https://www.npmjs.com/package/@bitefoundry/outlook) | `outlook` | Microsoft Outlook (Mail, Calendar & Contacts) | TUI · CLI · HTTP · MCP |
|
|
130
|
+
| [`@bitefoundry/onenote`](https://www.npmjs.com/package/@bitefoundry/onenote) | `onenote`, `note` | Microsoft OneNote (Notebooks, Sections & Pages) | TUI · CLI · HTTP · MCP |
|
|
131
|
+
| [`@bitefoundry/sharepoint`](https://www.npmjs.com/package/@bitefoundry/sharepoint) | `sharepoint`, `sp`, `onedrive`, `od` | Microsoft SharePoint & OneDrive (Sites, Libraries & Lists) | TUI · CLI · HTTP · MCP |
|
|
132
|
+
| [`@bitefoundry/atlassian`](https://www.npmjs.com/package/@bitefoundry/atlassian) | `atlassian`, `jira`, `confluence`, `conf` | Atlassian Jira (Kanban, Sprints, JQL) & Confluence Wiki | TUI · CLI · HTTP · MCP |
|
|
133
|
+
| **`@bitefoundry/notion`** | `notion`, `nt` | Notion (Editorial Pages, Interactive Blocks & Databases) | TUI · CLI · HTTP · MCP |
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
> **Disclaimer:** Unofficial terminal client for Notion. Not affiliated with, endorsed by, or sponsored by Notion Labs, Inc.
|
package/docs/API.md
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# `@bitefoundry/notion` Local HTTP API Reference
|
|
2
|
+
|
|
3
|
+
Start the local HTTP JSON API server (default `127.0.0.1:8791`):
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
notion serve --port 8791
|
|
7
|
+
# Optional API key protection (required when binding non-loopback hosts):
|
|
8
|
+
notion serve --host 0.0.0.0 --port 8791 --api-key "$NOTION_LOCAL_API_KEY"
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
When `--api-key` is configured, pass `x-api-key: <key>` or `Authorization: Bearer <key>` on all `/api/v1/*` routes.
|
|
12
|
+
|
|
13
|
+
## Endpoints
|
|
14
|
+
|
|
15
|
+
| Method | Path | Description |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `GET` | `/health` | Service health & version (`{ ok, service: "notion-cli", version }`) |
|
|
18
|
+
| `GET` | `/api/v1/whoami` | Authenticated Notion bot/user and active workspace metadata |
|
|
19
|
+
| `GET` | `/api/v1/workspaces` | List configured Notion workspace profiles |
|
|
20
|
+
| `GET` | `/api/v1/search?q=<query>&remote=false&offline=false&limit=30` | Local SQLite FTS5 + Korean `<3` char LIKE search (or remote Notion search) |
|
|
21
|
+
| `GET` | `/api/v1/pages?archived=false&refresh=false&offline=false` | List pages in active workspace |
|
|
22
|
+
| `POST` | `/api/v1/pages` | Create a new page (`{ parent_id, title, icon?, markdown?, parent_is_database?, properties? }`) |
|
|
23
|
+
| `GET` | `/api/v1/pages/{id}?offline=false` | Get full page detail (metadata, properties, block tree, comments, markdown, media refs) |
|
|
24
|
+
| `PATCH` | `/api/v1/pages/{id}` | Update page title, icon, properties, or archive/unarchive (`{ title?, icon?, archived?, properties? }`) |
|
|
25
|
+
| `GET` | `/api/v1/pages/{id}/blocks?offline=false` | Get a page or block's recursive children. Offline reads return HTTP 404 for an uncached list and HTTP 200 for a verified empty list. |
|
|
26
|
+
| `POST` | `/api/v1/pages/{id}/blocks` | Append Markdown or slash-style blocks (`{ markdown }`) |
|
|
27
|
+
| `PATCH` | `/api/v1/blocks/{id}` | Update block text or toggle `to_do.checked` (`{ block_type?, text?, checked? }`) |
|
|
28
|
+
| `GET` | `/api/v1/databases?refresh=false&offline=false` | List databases & schemas |
|
|
29
|
+
| `POST` | `/api/v1/databases/{id}/query` | Query database rows (`{ filter?, sorts?, limit?, offline? }`) |
|
|
30
|
+
| `POST` | `/api/v1/databases/{id}/items` | Create a new database item (`{ title, status?, properties?, body? }`) |
|
|
31
|
+
| `GET` | `/api/v1/pages/{id}/comments?offline=false` | List page comments |
|
|
32
|
+
| `POST` | `/api/v1/pages/{id}/comments` | Add a comment or discussion reply (`{ text, discussion_id? }`) |
|
|
33
|
+
| `POST` | `/api/v1/sync` | Synchronize workspace pages & databases into SQLite WAL + FTS5 immediately |
|
|
34
|
+
|
|
35
|
+
See [`docs/openapi.yaml`](openapi.yaml) for full schemas.
|
package/docs/MCP.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# `@bitefoundry/notion` MCP Server Reference (19 Tools)
|
|
2
|
+
|
|
3
|
+
Run the standalone stdio JSON-RPC 2.0 Model Context Protocol server:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
notion mcp
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
### Example MCP Client Configuration
|
|
10
|
+
|
|
11
|
+
```json
|
|
12
|
+
{
|
|
13
|
+
"mcpServers": {
|
|
14
|
+
"notion": {
|
|
15
|
+
"command": "notion",
|
|
16
|
+
"args": ["mcp"]
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Available Tools (19)
|
|
23
|
+
|
|
24
|
+
| # | Tool | Required Args | Description |
|
|
25
|
+
|---|---|---|---|
|
|
26
|
+
| 1 | `whoami` | — | Return the currently authenticated Notion user/bot and active workspace metadata. |
|
|
27
|
+
| 2 | `list_workspaces` | — | List all configured Notion workspace profiles and the currently active workspace. |
|
|
28
|
+
| 3 | `search_pages` | `query` | Search Notion pages and databases using local SQLite FTS5 (with Korean `<3` char LIKE fallback) or remote Notion Search API. |
|
|
29
|
+
| 4 | `get_page` | `page` | Fetch a page with its properties, recursive block tree, Markdown, comments, and media. Pass `compact: true` for just `id`, `title`, `last_edited_time`, and `markdown`. |
|
|
30
|
+
| 5 | `get_page_blocks` | `page` | List the recursive block tree for a Notion page or block ID. With `offline: true`, a cache miss is a tool error. A verified empty list returns `{"ok":true,"count":0,"blocks":[]}`. |
|
|
31
|
+
| 6 | `create_page` | `parent_id`, `title` | Create a new Notion page under a parent page or database from Markdown content. |
|
|
32
|
+
| 7 | `append_blocks` | `page`, `markdown` | Append Markdown or slash-style blocks (`/h1`, `/todo`, `/callout`, `/code`, `/quote`, `/toggle`) to a Notion page or block. |
|
|
33
|
+
| 8 | `update_block` | `block_id`, `text` | Edit one block's text using inline Markdown. Include the complete inline text so unchanged spans retain their formatting and mentions. Use `toggle_todo` for checkbox-only changes. |
|
|
34
|
+
| 9 | `toggle_todo` | `block_id` | Toggle or explicitly set a Notion `to_do` block's checkbox state. |
|
|
35
|
+
| 10 | `archive_page` | `page`, `confirm` | Archive (or unarchive) a Notion page. Destructive archive requires `confirm: true`. |
|
|
36
|
+
| 11 | `list_databases` | — | List accessible Notion databases with schemas. |
|
|
37
|
+
| 12 | `query_database` | `database` | Query rows of a Notion database with optional Notion API JSON filter and sorts. |
|
|
38
|
+
| 13 | `create_database_item` | `database`, `title` | Create a new row page inside a Notion database with title, optional status, custom properties, and Markdown body. |
|
|
39
|
+
| 14 | `update_database_item` | `page_id` | Update title, status, or arbitrary properties on a database row. `title` and `status` use the row's property names and types. Pass explicit `properties` to select a specific column. |
|
|
40
|
+
| 15 | `list_comments` | `page` | List comments on a Notion page. |
|
|
41
|
+
| 16 | `add_comment` | `page`, `text` | Add a comment to a Notion page or reply to an existing discussion thread. |
|
|
42
|
+
| 17 | `download_media` | `target` | Download a Notion-hosted or external media URL or image/file/pdf block ID to local disk. |
|
|
43
|
+
| 18 | `sync_now` | — | Synchronize Notion workspace pages and databases into the local SQLite WAL + FTS5 cache immediately. |
|
|
44
|
+
| 19 | `update_page` | `page`, plus `title` or `icon` | Set a title or emoji icon. Fields you omit keep their current values. Send `null` to clear either field. |
|
|
45
|
+
|
|
46
|
+
Full `get_page` replies include `comments_error` when comment retrieval fails. An offline reply may include previously cached comments alongside that error. A successful empty comment list has `comments: []`.
|
|
47
|
+
|
|
48
|
+
For `update_page`, `{"page":"Q4 Launch Plan","title":"Q4 Launch Checklist"}` changes the title. `{"page":"Q4 Launch Checklist","icon":null}` removes its icon. A title update reads the page's title property first, including custom title names on database rows. The Notion connection needs read access for that lookup and update access for the patch. [Notion Update page API](https://developers.notion.com/reference/patch-page)
|
package/docs/NPM.md
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
# `@bitefoundry/notion` 6-Platform npm Distribution
|
|
2
|
-
|
|
3
|
-
`@bitefoundry/notion` distributes prebuilt native Rust binaries via npm `optionalDependencies`, installing both `notion` and `nt` commands with zero Node.js runtime overhead after `postinstall` hardlinking.
|
|
4
|
-
|
|
5
|
-
## Platform Packages
|
|
6
|
-
|
|
7
|
-
| Platform Package | Rust Target | Binary |
|
|
8
|
-
|---|---|---|
|
|
9
|
-
| `@bitefoundry/notion-win32-x64` | `x86_64-pc-windows-msvc` | `bin/notion.exe` |
|
|
10
|
-
| `@bitefoundry/notion-win32-arm64` | `aarch64-pc-windows-msvc` | `bin/notion.exe` |
|
|
11
|
-
| `@bitefoundry/notion-darwin-x64` | `x86_64-apple-darwin` | `bin/notion` |
|
|
12
|
-
| `@bitefoundry/notion-darwin-arm64` | `aarch64-apple-darwin` | `bin/notion` |
|
|
13
|
-
| `@bitefoundry/notion-linux-x64` | `x86_64-unknown-linux-gnu.2.28` | `bin/notion` |
|
|
14
|
-
| `@bitefoundry/notion-linux-arm64` | `aarch64-unknown-linux-gnu.2.28` | `bin/notion` |
|
|
15
|
-
|
|
16
|
-
## Packaging Scripts
|
|
17
|
-
|
|
18
|
-
- `node scripts/sync-version.mjs --check`: verifies `Cargo.toml`, root `package.json`, and all 6 `npm/notion-*/package.json` manifests match version `0.1.0`.
|
|
19
|
-
- `node scripts/verify-glibc.mjs --self-test`: verifies the GLIBC <= 2.28 ELF symbol checker used in GitHub Actions Linux releases.
|
|
20
|
-
- `node scripts/build-npm.mjs [--target <triple>] [--all]`: stages Cargo release binaries into `npm/notion-*/bin/`.
|
|
21
|
-
- `scripts/postinstall.mjs`: links `notion` and `nt` directly to the native binary on Unix/Windows while guarding against mutating a git development checkout.
|
|
1
|
+
# `@bitefoundry/notion` 6-Platform npm Distribution
|
|
2
|
+
|
|
3
|
+
`@bitefoundry/notion` distributes prebuilt native Rust binaries via npm `optionalDependencies`, installing both `notion` and `nt` commands with zero Node.js runtime overhead after `postinstall` hardlinking.
|
|
4
|
+
|
|
5
|
+
## Platform Packages
|
|
6
|
+
|
|
7
|
+
| Platform Package | Rust Target | Binary |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `@bitefoundry/notion-win32-x64` | `x86_64-pc-windows-msvc` | `bin/notion.exe` |
|
|
10
|
+
| `@bitefoundry/notion-win32-arm64` | `aarch64-pc-windows-msvc` | `bin/notion.exe` |
|
|
11
|
+
| `@bitefoundry/notion-darwin-x64` | `x86_64-apple-darwin` | `bin/notion` |
|
|
12
|
+
| `@bitefoundry/notion-darwin-arm64` | `aarch64-apple-darwin` | `bin/notion` |
|
|
13
|
+
| `@bitefoundry/notion-linux-x64` | `x86_64-unknown-linux-gnu.2.28` | `bin/notion` |
|
|
14
|
+
| `@bitefoundry/notion-linux-arm64` | `aarch64-unknown-linux-gnu.2.28` | `bin/notion` |
|
|
15
|
+
|
|
16
|
+
## Packaging Scripts
|
|
17
|
+
|
|
18
|
+
- `node scripts/sync-version.mjs --check`: verifies `Cargo.toml`, root `package.json`, and all 6 `npm/notion-*/package.json` manifests match version `0.1.0`.
|
|
19
|
+
- `node scripts/verify-glibc.mjs --self-test`: verifies the GLIBC <= 2.28 ELF symbol checker used in GitHub Actions Linux releases.
|
|
20
|
+
- `node scripts/build-npm.mjs [--target <triple>] [--all]`: stages Cargo release binaries into `npm/notion-*/bin/`.
|
|
21
|
+
- `scripts/postinstall.mjs`: links `notion` and `nt` directly to the native binary on Unix/Windows while guarding against mutating a git development checkout.
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
openapi: 3.1.0
|
|
2
|
+
info:
|
|
3
|
+
title: "@bitefoundry/notion Local HTTP API"
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
description: Local HTTP JSON API exposed by `notion serve` (default `127.0.0.1:8791`).
|
|
6
|
+
servers:
|
|
7
|
+
- url: http://127.0.0.1:8791
|
|
8
|
+
paths:
|
|
9
|
+
/health:
|
|
10
|
+
get:
|
|
11
|
+
summary: Health check
|
|
12
|
+
responses:
|
|
13
|
+
"200":
|
|
14
|
+
description: Service status
|
|
15
|
+
/api/v1/whoami:
|
|
16
|
+
get:
|
|
17
|
+
summary: Current authenticated Notion bot/user & active workspace
|
|
18
|
+
responses:
|
|
19
|
+
"200":
|
|
20
|
+
description: User and workspace metadata
|
|
21
|
+
/api/v1/workspaces:
|
|
22
|
+
get:
|
|
23
|
+
summary: List configured Notion workspace profiles
|
|
24
|
+
responses:
|
|
25
|
+
"200":
|
|
26
|
+
description: Workspace profile registry
|
|
27
|
+
/api/v1/search:
|
|
28
|
+
get:
|
|
29
|
+
summary: Search Notion pages and databases (SQLite FTS5 + Korean <3 char LIKE or remote)
|
|
30
|
+
parameters:
|
|
31
|
+
- name: q
|
|
32
|
+
in: query
|
|
33
|
+
required: true
|
|
34
|
+
schema: { type: string }
|
|
35
|
+
- name: remote
|
|
36
|
+
in: query
|
|
37
|
+
schema: { type: boolean, default: false }
|
|
38
|
+
- name: offline
|
|
39
|
+
in: query
|
|
40
|
+
schema: { type: boolean, default: false }
|
|
41
|
+
- name: limit
|
|
42
|
+
in: query
|
|
43
|
+
schema: { type: integer, default: 50 }
|
|
44
|
+
responses:
|
|
45
|
+
"200":
|
|
46
|
+
description: Search hits
|
|
47
|
+
/api/v1/pages:
|
|
48
|
+
get:
|
|
49
|
+
summary: List workspace pages
|
|
50
|
+
responses:
|
|
51
|
+
"200":
|
|
52
|
+
description: Page list
|
|
53
|
+
post:
|
|
54
|
+
summary: Create a Notion page
|
|
55
|
+
responses:
|
|
56
|
+
"200":
|
|
57
|
+
description: Created page
|
|
58
|
+
/api/v1/pages/{id}:
|
|
59
|
+
get:
|
|
60
|
+
summary: Get full Notion page detail (metadata, blocks, comments, markdown, media)
|
|
61
|
+
parameters:
|
|
62
|
+
- name: id
|
|
63
|
+
in: path
|
|
64
|
+
required: true
|
|
65
|
+
schema: { type: string }
|
|
66
|
+
responses:
|
|
67
|
+
"200":
|
|
68
|
+
description: Page detail
|
|
69
|
+
patch:
|
|
70
|
+
summary: Update page metadata, properties, or archive state
|
|
71
|
+
parameters:
|
|
72
|
+
- name: id
|
|
73
|
+
in: path
|
|
74
|
+
required: true
|
|
75
|
+
schema: { type: string }
|
|
76
|
+
responses:
|
|
77
|
+
"200":
|
|
78
|
+
description: Updated page
|
|
79
|
+
/api/v1/pages/{id}/blocks:
|
|
80
|
+
get:
|
|
81
|
+
summary: Get recursive children of a page or block
|
|
82
|
+
parameters:
|
|
83
|
+
- name: id
|
|
84
|
+
in: path
|
|
85
|
+
required: true
|
|
86
|
+
schema: { type: string }
|
|
87
|
+
- name: offline
|
|
88
|
+
in: query
|
|
89
|
+
schema: { type: boolean, default: false }
|
|
90
|
+
description: Use locally cached children.
|
|
91
|
+
responses:
|
|
92
|
+
"200":
|
|
93
|
+
description: Block tree, including a verified empty list
|
|
94
|
+
"404":
|
|
95
|
+
description: Resource not found or children unavailable in the offline cache
|
|
96
|
+
post:
|
|
97
|
+
summary: Append Markdown or slash-style blocks to a page
|
|
98
|
+
parameters:
|
|
99
|
+
- name: id
|
|
100
|
+
in: path
|
|
101
|
+
required: true
|
|
102
|
+
schema: { type: string }
|
|
103
|
+
responses:
|
|
104
|
+
"200":
|
|
105
|
+
description: Appended blocks
|
|
106
|
+
/api/v1/blocks/{id}:
|
|
107
|
+
patch:
|
|
108
|
+
summary: Update block text or toggle to_do checkbox
|
|
109
|
+
parameters:
|
|
110
|
+
- name: id
|
|
111
|
+
in: path
|
|
112
|
+
required: true
|
|
113
|
+
schema: { type: string }
|
|
114
|
+
responses:
|
|
115
|
+
"200":
|
|
116
|
+
description: Updated block
|
|
117
|
+
/api/v1/databases:
|
|
118
|
+
get:
|
|
119
|
+
summary: List Notion databases
|
|
120
|
+
responses:
|
|
121
|
+
"200":
|
|
122
|
+
description: Database list
|
|
123
|
+
/api/v1/databases/{id}/query:
|
|
124
|
+
post:
|
|
125
|
+
summary: Query database rows
|
|
126
|
+
parameters:
|
|
127
|
+
- name: id
|
|
128
|
+
in: path
|
|
129
|
+
required: true
|
|
130
|
+
schema: { type: string }
|
|
131
|
+
responses:
|
|
132
|
+
"200":
|
|
133
|
+
description: Database rows
|
|
134
|
+
/api/v1/databases/{id}/items:
|
|
135
|
+
post:
|
|
136
|
+
summary: Create a new database item row
|
|
137
|
+
parameters:
|
|
138
|
+
- name: id
|
|
139
|
+
in: path
|
|
140
|
+
required: true
|
|
141
|
+
schema: { type: string }
|
|
142
|
+
responses:
|
|
143
|
+
"200":
|
|
144
|
+
description: Created item
|
|
145
|
+
/api/v1/pages/{id}/comments:
|
|
146
|
+
get:
|
|
147
|
+
summary: List comments on a page
|
|
148
|
+
parameters:
|
|
149
|
+
- name: id
|
|
150
|
+
in: path
|
|
151
|
+
required: true
|
|
152
|
+
schema: { type: string }
|
|
153
|
+
responses:
|
|
154
|
+
"200":
|
|
155
|
+
description: Comments list
|
|
156
|
+
post:
|
|
157
|
+
summary: Add a comment or discussion reply
|
|
158
|
+
parameters:
|
|
159
|
+
- name: id
|
|
160
|
+
in: path
|
|
161
|
+
required: true
|
|
162
|
+
schema: { type: string }
|
|
163
|
+
responses:
|
|
164
|
+
"200":
|
|
165
|
+
description: Created comment
|
|
166
|
+
/api/v1/sync:
|
|
167
|
+
post:
|
|
168
|
+
summary: Trigger immediate workspace sync into SQLite WAL + FTS5
|
|
169
|
+
responses:
|
|
170
|
+
"200":
|
|
171
|
+
description: Sync summary
|
package/package.json
CHANGED
|
@@ -1,50 +1,53 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@bitefoundry/notion",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Notion terminal client & AI agent toolkit — Pages, Blocks, Databases (Table/Board/List), Comments & Multi-Workspace (CLI, TUI, HTTP API, MCP)",
|
|
5
|
-
"repository": {
|
|
6
|
-
"type": "git",
|
|
7
|
-
"url": "git+https://github.com/BiteFoundry/notion.git"
|
|
8
|
-
},
|
|
9
|
-
"license": "MIT",
|
|
10
|
-
"bin": {
|
|
11
|
-
"notion": "bin/notion.js",
|
|
12
|
-
"nt": "bin/nt.js"
|
|
13
|
-
},
|
|
14
|
-
"files": [
|
|
15
|
-
"bin/notion.js",
|
|
16
|
-
"bin/nt.js",
|
|
17
|
-
"scripts/postinstall.mjs",
|
|
18
|
-
"docs/NPM.md",
|
|
19
|
-
"
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
"
|
|
23
|
-
|
|
24
|
-
"
|
|
25
|
-
"
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
"
|
|
31
|
-
"
|
|
32
|
-
"
|
|
33
|
-
"
|
|
34
|
-
"
|
|
35
|
-
"
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
"
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
"
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
"@bitefoundry/notion-
|
|
47
|
-
"@bitefoundry/notion-
|
|
48
|
-
"@bitefoundry/notion-
|
|
49
|
-
|
|
50
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@bitefoundry/notion",
|
|
3
|
+
"version": "0.1.4",
|
|
4
|
+
"description": "Notion terminal client & AI agent toolkit — Pages, Blocks, Databases (Table/Board/List), Comments & Multi-Workspace (CLI, TUI, HTTP API, MCP)",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git+https://github.com/BiteFoundry/notion.git"
|
|
8
|
+
},
|
|
9
|
+
"license": "MIT",
|
|
10
|
+
"bin": {
|
|
11
|
+
"notion": "bin/notion.js",
|
|
12
|
+
"nt": "bin/nt.js"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"bin/notion.js",
|
|
16
|
+
"bin/nt.js",
|
|
17
|
+
"scripts/postinstall.mjs",
|
|
18
|
+
"docs/NPM.md",
|
|
19
|
+
"docs/API.md",
|
|
20
|
+
"docs/MCP.md",
|
|
21
|
+
"docs/openapi.yaml",
|
|
22
|
+
"README.md"
|
|
23
|
+
],
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=18"
|
|
26
|
+
},
|
|
27
|
+
"keywords": [
|
|
28
|
+
"notion",
|
|
29
|
+
"notion-cli",
|
|
30
|
+
"notion-tui",
|
|
31
|
+
"nt",
|
|
32
|
+
"knowledge-base",
|
|
33
|
+
"kanban",
|
|
34
|
+
"database",
|
|
35
|
+
"markdown",
|
|
36
|
+
"cli",
|
|
37
|
+
"tui",
|
|
38
|
+
"mcp"
|
|
39
|
+
],
|
|
40
|
+
"scripts": {
|
|
41
|
+
"postinstall": "node scripts/postinstall.mjs",
|
|
42
|
+
"sync-version": "node scripts/sync-version.mjs",
|
|
43
|
+
"build:npm": "node scripts/build-npm.mjs"
|
|
44
|
+
},
|
|
45
|
+
"optionalDependencies": {
|
|
46
|
+
"@bitefoundry/notion-win32-x64": "0.1.4",
|
|
47
|
+
"@bitefoundry/notion-win32-arm64": "0.1.4",
|
|
48
|
+
"@bitefoundry/notion-darwin-x64": "0.1.4",
|
|
49
|
+
"@bitefoundry/notion-darwin-arm64": "0.1.4",
|
|
50
|
+
"@bitefoundry/notion-linux-x64": "0.1.4",
|
|
51
|
+
"@bitefoundry/notion-linux-arm64": "0.1.4"
|
|
52
|
+
}
|
|
53
|
+
}
|