@jordancoin/notioncli 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm run test:coverage
+      - name: Upload coverage
+        if: matrix.node-version == 22
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage/lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JordanCoin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,353 @@
+# notioncli
+
+[![npm version](https://img.shields.io/npm/v/@jordancoin/notioncli.svg)](https://www.npmjs.com/package/@jordancoin/notioncli)
+[![CI](https://github.com/JordanCoin/notioncli/actions/workflows/ci.yml/badge.svg)](https://github.com/JordanCoin/notioncli/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/JordanCoin/notioncli/branch/main/graph/badge.svg)](https://codecov.io/gh/JordanCoin/notioncli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+
+A powerful CLI for the Notion API — query databases, manage pages, and automate your workspace from the terminal.
+
+**No more copy-pasting UUIDs.** Set up aliases once, then just type `notion query tasks` or `notion add projects --prop "Name=Ship it"`.
+
+```bash
+npm install -g @jordancoin/notioncli
+```
+
+## Quick Start
+
+```bash
+# 1. One command to set up
+notion init --key ntn_your_api_key_here
+
+# That's it. Aliases are created automatically:
+#   ✅ projects     → Project Tracker
+#   ✅ reading-list → Reading List
+#   ✅ meetings     → Meeting Notes
+
+# 2. Start using them immediately
+notion query projects
+notion add projects --prop "Name=Ship it" --prop "Status=Todo"
+```
+
+Zero UUIDs. One command. You're ready to go.
+
+---
+
+## Setup
+
+### 1. Create a Notion Integration
+
+1. Go to [notion.so/profile/integrations](https://www.notion.so/profile/integrations)
+2. Click **"New integration"**
+3. Give it a name (e.g. "My CLI")
+4. Copy the API key (starts with `ntn_`)
+
+### 2. Share Your Databases
+
+In Notion, open each database you want to access:
+- Click the **•••** menu → **Connections** → Add your integration
+
+### 3. Initialize
+
+```bash
+notion init --key ntn_your_api_key_here
+```
+
+This saves your key, discovers all shared databases, and **creates aliases automatically**:
+
+```
+✅ API key saved to ~/.config/notioncli/config.json
+
+Found 3 databases:
+
+  ✅ project-tracker        → Project Tracker
+  ✅ reading-list           → Reading List
+  ✅ meeting-notes          → Meeting Notes
+
+3 aliases saved automatically.
+
+Ready! Try:
+  notion query project-tracker
+  notion add project-tracker --prop "Name=Hello World"
+```
+
+That's it — no IDs, no extra steps. If you want shorter names:
+
+```bash
+notion alias rename project-tracker projects
+notion alias rename reading-list reads
+```
+
+> **Alternative:** Skip `init` and set an environment variable:
+> ```bash
+> export NOTION_API_KEY=ntn_your_api_key
+> ```
+
+---
+
+## Commands
+
+### `notion query` — Query a Database
+
+The command you'll use most. Filter, sort, and browse your data:
+
+```
+$ notion query projects
+Date       │ Name            │ Status │ Priority
+───────────┼─────────────────┼────────┼──────────
+2026-02-09 │ Launch CLI      │ Active │ High
+2026-02-08 │ Write Docs      │ Active │ Medium
+2026-02-07 │ Design Landing  │ Done   │ Low
+
+3 results
+```
+
+With filters and sorting:
+
+```
+$ notion query projects --filter Status=Active --sort Date:desc --limit 5
+Date       │ Name          │ Status │ Priority
+───────────┼───────────────┼────────┼─────────
+2026-02-09 │ Launch CLI    │ Active │ High
+2026-02-08 │ Write Docs    │ Active │ Medium
+
+2 results
+```
+
+### `notion add` — Add a Page
+
+```
+$ notion add projects --prop "Name=New Feature" --prop "Status=Todo" --prop "Date=2026-02-10"
+✅ Created page: a1b2c3d4-...
+   URL: https://www.notion.so/...
+```
+
+Properties are matched **case-insensitively** against the database schema. No need to memorize exact field names.
+
+**Supported types:** title, rich_text, number, select, multi_select, date, checkbox, url, email, phone_number, status.
+
+### `notion update` — Update a Page
+
+By page ID:
+```
+$ notion update a1b2c3d4-5678-90ab-cdef-1234567890ab --prop "Status=Done" --prop "Priority=Low"
+✅ Updated page: a1b2c3d4-...
+```
+
+By alias + filter (no UUIDs needed):
+```
+$ notion update workouts --filter "Name=LEGS #5" --prop "Notes=Great session"
+✅ Updated page: a1b2c3d4-...
+```
+
+### `notion delete` — Delete (Archive) a Page
+
+By page ID:
+```
+$ notion delete a1b2c3d4-5678-90ab-cdef-1234567890ab
+🗑️  Archived page: a1b2c3d4-...
+   (Restore it from the trash in Notion if needed)
+```
+
+By alias + filter:
+```
+$ notion delete workouts --filter "Date=2026-02-09"
+🗑️  Archived page: a1b2c3d4-...
+```
+
+### `notion get` — View Page Details
+
+By page ID:
+```
+$ notion get a1b2c3d4-5678-90ab-cdef-1234567890ab
+```
+
+By alias + filter:
+```
+$ notion get workouts --filter "Name=LEGS #5"
+Page: a1b2c3d4-5678-90ab-cdef-1234567890ab
+URL:  https://www.notion.so/New-Feature-a1b2c3d4...
+Created: 2026-02-10T14:30:00.000Z
+Updated: 2026-02-10T14:30:00.000Z
+
+Properties:
+  Name: New Feature
+  Status: Todo
+  Date: 2026-02-10
+  Priority: High
+```
+
+### `notion blocks` — View Page Content
+
+By page ID or alias + filter:
+```
+$ notion blocks projects --filter "Name=Project Overview"
+# Project Overview
+This is the main project page.
+• First task
+• Second task
+☑ Completed item
+☐ Pending item
+```
+
+### `notion dbs` — List All Databases
+
+```
+$ notion dbs
+id                                   │ title            │ url
+─────────────────────────────────────┼──────────────────┼──────────────
+a1b2c3d4-e5f6-7890-abcd-ef1234567890 │ Project Tracker  │ https://...
+f9e8d7c6-b5a4-3210-fedc-ba0987654321 │ Reading List     │ https://...
+
+2 results
+```
+
+### `notion search` — Search Everything
+
+```
+$ notion search "meeting"
+id                                   │ type        │ title          │ url
+─────────────────────────────────────┼─────────────┼────────────────┼──────────────
+a1b2c3d4-e5f6-7890-abcd-ef1234567890 │ page        │ Meeting Notes  │ https://...
+f9e8d7c6-b5a4-3210-fedc-ba0987654321 │ data_source │ Meetings DB    │ https://...
+
+2 results
+```
+
+### `notion alias` — Manage Aliases
+
+Aliases are created automatically by `notion init`, but you can manage them:
+
+```bash
+# See your aliases
+notion alias list
+
+# Rename one
+notion alias rename project-tracker projects
+
+# Add one manually (auto-discovers the right IDs)
+notion alias add tasks a1b2c3d4-e5f6-7890-abcd-ef1234567890
+
+# Remove one
+notion alias remove tasks
+```
+
+### `--json` — Raw JSON Output
+
+Add `--json` to any command for the raw Notion API response:
+
+```bash
+notion --json query projects --limit 1
+notion --json dbs
+notion --json get a1b2c3d4-...
+```
+
+Great for piping into `jq` or other tools.
+
+---
+
+## Use It With AI Agents
+
+notioncli is designed to be fast for both humans and LLMs. AI coding agents can:
+
+```bash
+# Discover what's available
+notion dbs
+notion alias list
+
+# Query and filter data
+notion query tasks --filter Status=Todo --sort Priority:desc
+
+# Create and update pages — zero UUIDs workflow
+notion add tasks --prop "Name=Fix bug #42" --prop "Status=In Progress"
+notion update tasks --filter "Name=Fix bug #42" --prop "Status=Done"
+
+# View, comment, and append — all by alias + filter
+notion get tasks --filter "Name=Fix bug #42"
+notion comment tasks "Shipped! 🚀" --filter "Name=Fix bug #42"
+notion append tasks "Deployed to production" --filter "Name=Fix bug #42"
+
+# Delete by alias + filter
+notion delete tasks --filter "Name=Fix bug #42"
+
+# Or use raw page IDs if you already have them
+notion update <page-id> --prop "Status=Done"
+
+# Get raw JSON for parsing
+notion --json query projects --limit 10
+```
+
+No API key management, no curl commands, no JSON formatting — just simple shell commands.
+
+### Zero-UUID Workflow
+
+Every page-targeted command (`update`, `delete`, `get`, `blocks`, `comments`, `comment`, `append`) now accepts a **database alias + `--filter`** as an alternative to a raw page ID:
+
+```bash
+# Instead of: notion update a1b2c3d4-5678-90ab-cdef-1234567890ab --prop "Status=Done"
+# Just use:   notion update projects --filter "Name=Ship it" --prop "Status=Done"
+```
+
+The filter queries the database and expects **exactly one match**. If zero or multiple pages match, you get a clear error with guidance.
+
+---
+
+## Configuration
+
+Config is stored at `~/.config/notioncli/config.json`:
+
+```json
+{
+  "apiKey": "ntn_...",
+  "aliases": {
+    "projects": {
+      "database_id": "a1b2c3d4-...",
+      "data_source_id": "a1b2c3d4-..."
+    }
+  }
+}
+```
+
+**API key resolution order:**
+1. `NOTION_API_KEY` environment variable
+2. Config file
+3. Error with setup instructions
+
+---
+
+## Technical Notes
+
+### Notion API 2025-09-03 — Dual IDs
+
+The latest Notion API introduced a dual-ID system for databases. Each database now has both a `database_id` and a `data_source_id`. **notioncli handles this automatically** — when you add an alias, both IDs are discovered and stored. When you pass a raw UUID, it resolves correctly.
+
+You don't need to think about this. It just works.
+
+### Built on the Official SDK
+
+notioncli uses [`@notionhq/client`](https://github.com/makenotion/notion-sdk-js) v5.x, Notion's official JavaScript SDK.
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -am 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
+
+### Development
+
+```bash
+git clone https://github.com/JordanCoin/notioncli.git
+cd notioncli
+npm install
+export NOTION_API_KEY=ntn_your_test_key
+node bin/notion.js --help
+```
+
+## License
+
+MIT © [JordanCoin](https://github.com/JordanCoin)