@bitefoundry/notion 0.1.3 → 0.2.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 BiteFoundry
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,134 +1,139 @@
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
- [![npm version](https://img.shields.io/npm/v/%40bitefoundry%2Fnotion?style=flat-square&color=191919)](https://www.npmjs.com/package/@bitefoundry/notion)
8
- [![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-24292F?style=flat-square)](docs/NPM.md)
9
- [![Rust & Ratatui](https://img.shields.io/badge/built%20with-Rust%20%2B%20Ratatui-DEA584?style=flat-square&logo=rust)](Cargo.toml)
10
- [![License: MIT](https://img.shields.io/badge/license-MIT-00875A?style=flat-square)](package.json)
11
-
12
- <br />
13
-
14
- ![Notion TUI Demo](assets/demo.gif)
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`, **18 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 append "Q4 Launch Plan" "/todo Tag v1.0 release"
78
- notion pages export "Q4 Launch Plan" --out launch-plan.md
79
- notion blocks toggle <block-id>
80
-
81
- # Query & create Notion database items
82
- notion db list --json
83
- notion db query "Q4 Roadmap" --json
84
- notion db create-item "Q4 Roadmap" --title "Ship v1.0" --status "In Progress"
85
- notion comments add "Q4 Launch Plan" "Green light for launch!"
86
- notion download <url-or-block-id> --json
87
-
88
- # Multi-workspace profiles & background sync daemon
89
- notion workspaces list
90
- notion workspaces add work --token ntn_...
91
- notion workspaces use work
92
- notion daemon start
93
- ```
94
-
95
- ### Local HTTP JSON API (`notion serve`)
96
-
97
- ```bash
98
- notion serve --bind 127.0.0.1 --port 8791 --token "$API_TOKEN"
99
- curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8791/search?q=Roadmap"
100
- ```
101
-
102
- Full endpoint catalog and OpenAPI schema: **[docs/API.md](docs/API.md)** · **[docs/openapi.yaml](docs/openapi.yaml)**.
103
-
104
- ### MCP Server (`notion mcp` — 18 Tools)
105
-
106
- ```json
107
- {
108
- "mcpServers": {
109
- "notion": {
110
- "command": "notion",
111
- "args": ["mcp"]
112
- }
113
- }
114
- }
115
- ```
116
-
117
- Full tool catalog and argument schemas: **[docs/MCP.md](docs/MCP.md)** · npm packaging details: **[docs/NPM.md](docs/NPM.md)**.
118
-
119
- ---
120
-
121
- ## `@bitefoundry` Enterprise Terminal Suite
122
-
123
- | Package | Commands | Workspace | Interfaces |
124
- | :--- | :--- | :--- | :--- |
125
- | [`@bitefoundry/teams`](https://www.npmjs.com/package/@bitefoundry/teams) | `teams` | Microsoft Teams (Chats, Channels, Meetings & Threads) | TUI · CLI · HTTP · MCP |
126
- | [`@bitefoundry/outlook`](https://www.npmjs.com/package/@bitefoundry/outlook) | `outlook`, `ol` | Microsoft Outlook (Mail, Calendar & Contacts) | TUI · CLI · HTTP · MCP |
127
- | [`@bitefoundry/onenote`](https://www.npmjs.com/package/@bitefoundry/onenote) | `onenote`, `on` | Microsoft OneNote (Notebooks, Sections & Pages) | TUI · CLI · HTTP · MCP |
128
- | [`@bitefoundry/sharepoint`](https://www.npmjs.com/package/@bitefoundry/sharepoint) | `sharepoint`, `sp` | Microsoft SharePoint & OneDrive (Sites, Libraries & Lists) | TUI · CLI · HTTP · MCP |
129
- | [`@bitefoundry/atlassian`](https://www.npmjs.com/package/@bitefoundry/atlassian) | `atlassian`, `jira`, `confluence`, `conf` | Atlassian Jira (Kanban, Sprints, JQL) & Confluence Wiki | TUI · CLI · HTTP · MCP |
130
- | **`@bitefoundry/notion`** | `notion`, `nt` | Notion (Editorial Pages, Interactive Blocks & Databases) | TUI · CLI · HTTP · MCP |
131
-
132
- ---
133
-
134
- > **Disclaimer:** Unofficial terminal client for Notion. Not affiliated with, endorsed by, or sponsored by Notion Labs, Inc.
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
+ [![npm version](https://img.shields.io/npm/v/%40bitefoundry%2Fnotion?style=flat-square&color=191919)](https://www.npmjs.com/package/@bitefoundry/notion)
8
+ [![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-24292F?style=flat-square)](docs/NPM.md)
9
+ [![Rust & Ratatui](https://img.shields.io/badge/built%20with-Rust%20%2B%20Ratatui-DEA584?style=flat-square&logo=rust)](https://github.com/BiteFoundry/notion/blob/master/Cargo.toml)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-00875A?style=flat-square)](package.json)
11
+
12
+ <br />
13
+
14
+ ![Notion TUI Demo](https://raw.githubusercontent.com/BiteFoundry/notion/master/assets/demo.gif)
15
+
16
+ </div>
17
+
18
+ ---
19
+
20
+ ## Highlights
21
+
22
+ | Pillar | Capabilities |
23
+ | :--- | :--- |
24
+ | **Minimal-Chrome TUI** | Authentic Notion editorial aesthetic (`notion`): 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
+ Upgrading from 0.1.x? Change `nt` to `notion` in shell scripts and set the MCP server’s `command` to `notion`.
34
+
35
+ ```bash
36
+ # 1. Install globally (installs the native `notion` command)
37
+ npm i -g @bitefoundry/notion
38
+
39
+ # 2. Authenticate — Internal Integration Token (30-second setup) or Public OAuth 2.0
40
+ notion login --token ntn_...
41
+ # Or Public OAuth 2.0 loopback:
42
+ notion login --oauth --client-id "$NOTION_CLIENT_ID" --client-secret "$NOTION_CLIENT_SECRET"
43
+
44
+ # 3. Sync your workspace & launch the Notion-native TUI
45
+ notion sync
46
+ notion
47
+ ```
48
+
49
+ ---
50
+
51
+ ## Keybindings Cheat Sheet
52
+
53
+ | Key | Action | Context |
54
+ | :--- | :--- | :--- |
55
+ | `[` / `Ctrl+B` | Toggle collapsible Workspace Sidebar | Global |
56
+ | `Tab` / `Shift+Tab` | Cycle focus across Sidebar, Canvas, and Comments Drawer | Global |
57
+ | `j` `k` / `↑` `↓` | Move across sidebar tree, page blocks, or database rows | Global |
58
+ | `Space` / `x` | Check/uncheck live `to_do` block or expand/collapse `toggle` block | Page Canvas |
59
+ | `w` / `f` / `y` | Toggle Centered vs Full Width / Favorite star / Copy code block | Page Canvas |
60
+ | `a` / `n` / `e` | Slash Quick Append (`/h1`, `/todo`, `/callout`) / New Page / `$EDITOR` | Page / Database |
61
+ | `C` | Toggle right-split Comments Peek Drawer & reply inline | Page Canvas |
62
+ | `1` / `2` / `3` | Switch Database views: **Table** / **Board (Kanban)** / **List** | Database |
63
+ | `f` / `s` / `m` | Filter rows / Cycle sort / Move Kanban card to another Status column | Database |
64
+ | `Ctrl+K` / `Ctrl+P` | Quick Find & Command Palette (FTS5 search + workspace commands) | Global |
65
+ | `u` / `Ctrl+F` / `v` | Link Extractor / File Picker (`z` zoxide) / HD Image Preview | Global |
66
+ | `Ctrl+S` / `Ctrl+,` / `?` | Switch Workspace / Settings & Palettes / Keyboard Shortcuts Help | Global |
67
+
68
+ ---
69
+
70
+ ## CLI, HTTP API & MCP
71
+
72
+ ### CLI (`--json` ready)
73
+
74
+ ```bash
75
+ # Search, read, append & export Notion pages
76
+ notion search "Q4 Roadmap" --json
77
+ notion pages list --json
78
+ notion pages get "Q4 Launch Plan"
79
+ notion pages get "Q4 Launch Plan" --json --compact
80
+ notion pages edit "Q4 Launch Plan" --editor
81
+ notion pages append "Q4 Launch Plan" "/todo Tag v1.0 release"
82
+ notion pages export "Q4 Launch Plan" --out launch-plan.md
83
+ notion blocks edit <block-id> --text "Release **verified**" --json
84
+ notion blocks toggle <block-id>
85
+
86
+ # Query & create Notion database items
87
+ notion db list --json
88
+ notion db query "Q4 Roadmap" --json
89
+ notion db create-item "Q4 Roadmap" --title "Ship v1.0" --status "In Progress"
90
+ notion comments add "Q4 Launch Plan" "Green light for launch!"
91
+ notion download <url-or-block-id> --json
92
+
93
+ # Multi-workspace profiles & background sync daemon
94
+ notion workspaces list
95
+ notion workspaces add work --token ntn_...
96
+ notion workspaces use work
97
+ notion daemon start
98
+ ```
99
+
100
+ ### Local HTTP JSON API (`notion serve`)
101
+
102
+ ```bash
103
+ notion serve --host 127.0.0.1 --port 8791 --api-key "$API_TOKEN"
104
+ curl -H "Authorization: Bearer $API_TOKEN" "http://127.0.0.1:8791/api/v1/search?q=Roadmap"
105
+ ```
106
+
107
+ Full endpoint catalog and OpenAPI schema: **[docs/API.md](docs/API.md)** · **[docs/openapi.yaml](docs/openapi.yaml)**.
108
+
109
+ ### MCP Server (`notion mcp` — 19 Tools)
110
+
111
+ ```json
112
+ {
113
+ "mcpServers": {
114
+ "notion": {
115
+ "command": "notion",
116
+ "args": ["mcp"]
117
+ }
118
+ }
119
+ }
120
+ ```
121
+
122
+ Full tool catalog and argument schemas: **[docs/MCP.md](docs/MCP.md)** · npm packaging details: **[docs/NPM.md](docs/NPM.md)**.
123
+
124
+ ---
125
+
126
+ ## `@bitefoundry` Enterprise Terminal Suite
127
+
128
+ | Package | Commands | Workspace | Interfaces |
129
+ | :--- | :--- | :--- | :--- |
130
+ | [`@bitefoundry/teams`](https://www.npmjs.com/package/@bitefoundry/teams) | `teams` | Microsoft Teams (Chats, Channels, Meetings & Threads) | TUI · CLI · HTTP · MCP |
131
+ | [`@bitefoundry/outlook`](https://www.npmjs.com/package/@bitefoundry/outlook) | `outlook` | Microsoft Outlook (Mail, Calendar & Contacts) | TUI · CLI · HTTP · MCP |
132
+ | [`@bitefoundry/onenote`](https://www.npmjs.com/package/@bitefoundry/onenote) | `onenote` | Microsoft OneNote (Notebooks, Sections & Pages) | TUI · CLI · HTTP · MCP |
133
+ | [`@bitefoundry/sharepoint`](https://www.npmjs.com/package/@bitefoundry/sharepoint) | `sharepoint`, `bitefoundry-onedrive` | Microsoft SharePoint & OneDrive (Sites, Libraries & Lists) | TUI · CLI · HTTP · MCP |
134
+ | [`@bitefoundry/atlassian`](https://www.npmjs.com/package/@bitefoundry/atlassian) | `atlassian`, `confluence`, `conf` | Atlassian Jira (Kanban, Sprints, JQL) & Confluence Wiki | TUI · CLI · HTTP · MCP |
135
+ | **`@bitefoundry/notion`** | `notion` | Notion (Editorial Pages, Interactive Blocks & Databases) | TUI · CLI · HTTP · MCP |
136
+
137
+ ---
138
+
139
+ > **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 the `notion` command 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` 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,50 @@
1
- {
2
- "name": "@bitefoundry/notion",
3
- "version": "0.1.3",
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
- "README.md"
20
- ],
21
- "engines": {
22
- "node": ">=18"
23
- },
24
- "keywords": [
25
- "notion",
26
- "notion-cli",
27
- "notion-tui",
28
- "nt",
29
- "knowledge-base",
30
- "kanban",
31
- "database",
32
- "markdown",
33
- "cli",
34
- "tui",
35
- "mcp"
36
- ],
37
- "scripts": {
38
- "postinstall": "node scripts/postinstall.mjs",
39
- "sync-version": "node scripts/sync-version.mjs",
40
- "build:npm": "node scripts/build-npm.mjs"
41
- },
42
- "optionalDependencies": {
43
- "@bitefoundry/notion-win32-x64": "0.1.3",
44
- "@bitefoundry/notion-win32-arm64": "0.1.3",
45
- "@bitefoundry/notion-darwin-x64": "0.1.3",
46
- "@bitefoundry/notion-darwin-arm64": "0.1.3",
47
- "@bitefoundry/notion-linux-x64": "0.1.3",
48
- "@bitefoundry/notion-linux-arm64": "0.1.3"
49
- }
50
- }
1
+ {
2
+ "name": "@bitefoundry/notion",
3
+ "version": "0.2.0",
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
+ },
13
+ "files": [
14
+ "bin/notion.js",
15
+ "scripts/postinstall.mjs",
16
+ "docs/NPM.md",
17
+ "docs/API.md",
18
+ "docs/MCP.md",
19
+ "docs/openapi.yaml",
20
+ "README.md"
21
+ ],
22
+ "engines": {
23
+ "node": ">=18"
24
+ },
25
+ "keywords": [
26
+ "notion",
27
+ "notion-cli",
28
+ "notion-tui",
29
+ "knowledge-base",
30
+ "kanban",
31
+ "database",
32
+ "markdown",
33
+ "cli",
34
+ "tui",
35
+ "mcp"
36
+ ],
37
+ "scripts": {
38
+ "postinstall": "node scripts/postinstall.mjs",
39
+ "sync-version": "node scripts/sync-version.mjs",
40
+ "build:npm": "node scripts/build-npm.mjs"
41
+ },
42
+ "optionalDependencies": {
43
+ "@bitefoundry/notion-win32-x64": "0.2.0",
44
+ "@bitefoundry/notion-win32-arm64": "0.2.0",
45
+ "@bitefoundry/notion-darwin-x64": "0.2.0",
46
+ "@bitefoundry/notion-darwin-arm64": "0.2.0",
47
+ "@bitefoundry/notion-linux-x64": "0.2.0",
48
+ "@bitefoundry/notion-linux-arm64": "0.2.0"
49
+ }
50
+ }
@@ -1,12 +1,12 @@
1
1
  #!/usr/bin/env node
2
2
  // Zero-Node-Process npm native binary linker.
3
3
  //
4
- // On Unix (linux/darwin): replaces installed `bin/notion.js` and `bin/nt.js` with
4
+ // On Unix (linux/darwin): replaces installed `bin/notion.js` with
5
5
  // hardlinks/symlinks directly to `@bitefoundry/notion-<platform>-<arch>/bin/notion` so npm's
6
6
  // bin symlink execve's the native Rust binary directly (0ms Node startup, 0MB Node RSS).
7
7
  //
8
- // On Windows (win32): creates NTFS hardlinks (fallback copy) `bin/notion.exe` & `bin/nt.exe`
9
- // and rewrites npm's `.bin/{notion,nt}[.cmd|.ps1]` shims when present to invoke
8
+ // On Windows (win32): creates NTFS hardlinks (fallback copy) `bin/notion.exe`
9
+ // and rewrites npm's `.bin/notion[.cmd|.ps1]` shims when present to invoke
10
10
  // the native executable directly without spawning `node.exe`.
11
11
 
12
12
  import fs from 'node:fs';
@@ -14,7 +14,7 @@ import path from 'node:path';
14
14
  import { createRequire } from 'node:module';
15
15
  import { fileURLToPath } from 'node:url';
16
16
 
17
- const BIN_NAMES = ['notion', 'nt'];
17
+ const BIN_NAMES = ['notion'];
18
18
  const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
19
19
 
20
20
  function linkOrCopyFile(source, destination) {
package/bin/nt.js DELETED
@@ -1,4 +0,0 @@
1
- #!/usr/bin/env node
2
- 'use strict';
3
-
4
- require('./notion.js');