@jordancoin/notioncli 1.0.0

package/lib/helpers.js

@@ -0,0 +1,291 @@
+// lib/helpers.js — Pure functions extracted from bin/notion.js for testability
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Config file system ────────────────────────────────────────────────────────
+
+function getConfigPaths(overrideDir) {
+  const configDir = overrideDir || path.join(
+    process.env.XDG_CONFIG_HOME || path.join(require('os').homedir(), '.config'),
+    'notioncli'
+  );
+  return {
+    CONFIG_DIR: configDir,
+    CONFIG_PATH: path.join(configDir, 'config.json'),
+  };
+}
+
+function loadConfig(configPath) {
+  try {
+    if (fs.existsSync(configPath)) {
+      return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    }
+  } catch (err) {
+    // Corrupted config — start fresh
+  }
+  return { aliases: {} };
+}
+
+function saveConfig(config, configDir, configPath) {
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Extract plain text from rich_text array */
+function richTextToPlain(rt) {
+  if (!rt) return '';
+  if (Array.isArray(rt)) return rt.map(r => r.plain_text || '').join('');
+  return '';
+}
+
+/** Extract a readable value from a Notion property */
+function propValue(prop) {
+  if (!prop) return '';
+  switch (prop.type) {
+    case 'title':
+      return richTextToPlain(prop.title);
+    case 'rich_text':
+      return richTextToPlain(prop.rich_text);
+    case 'number':
+      return prop.number != null ? String(prop.number) : '';
+    case 'select':
+      return prop.select ? prop.select.name : '';
+    case 'multi_select':
+      return (prop.multi_select || []).map(s => s.name).join(', ');
+    case 'date':
+      if (!prop.date) return '';
+      return prop.date.end ? `${prop.date.start} → ${prop.date.end}` : prop.date.start;
+    case 'checkbox':
+      return prop.checkbox ? '✓' : '✗';
+    case 'url':
+      return prop.url || '';
+    case 'email':
+      return prop.email || '';
+    case 'phone_number':
+      return prop.phone_number || '';
+    case 'status':
+      return prop.status ? prop.status.name : '';
+    case 'formula':
+      if (prop.formula) {
+        const f = prop.formula;
+        return f.string || f.number?.toString() || f.boolean?.toString() || f.date?.start || '';
+      }
+      return '';
+    case 'relation':
+      return (prop.relation || []).map(r => r.id).join(', ');
+    case 'rollup':
+      return JSON.stringify(prop.rollup);
+    case 'people':
+      return (prop.people || []).map(p => p.name || p.id).join(', ');
+    case 'files':
+      return (prop.files || []).map(f => f.name || f.external?.url || '').join(', ');
+    case 'created_time':
+      return prop.created_time || '';
+    case 'last_edited_time':
+      return prop.last_edited_time || '';
+    case 'created_by':
+      return prop.created_by?.name || prop.created_by?.id || '';
+    case 'last_edited_by':
+      return prop.last_edited_by?.name || prop.last_edited_by?.id || '';
+    default:
+      return JSON.stringify(prop[prop.type] ?? '');
+  }
+}
+
+/** Build property value for Notion API based on schema type */
+function buildPropValue(type, value) {
+  switch (type) {
+    case 'title':
+      return { title: [{ text: { content: value } }] };
+    case 'rich_text':
+      return { rich_text: [{ text: { content: value } }] };
+    case 'number':
+      return { number: Number(value) };
+    case 'select':
+      return { select: { name: value } };
+    case 'multi_select':
+      return { multi_select: value.split(',').map(v => ({ name: v.trim() })) };
+    case 'date':
+      return { date: { start: value } };
+    case 'checkbox':
+      return { checkbox: value === 'true' || value === '1' || value === 'yes' };
+    case 'url':
+      return { url: value };
+    case 'email':
+      return { email: value };
+    case 'phone_number':
+      return { phone_number: value };
+    case 'status':
+      return { status: { name: value } };
+    default:
+      return { [type]: value };
+  }
+}
+
+/** Simple table formatter */
+function printTable(rows, columns) {
+  if (!rows || rows.length === 0) {
+    console.log('(no results)');
+    return;
+  }
+
+  const widths = {};
+  for (const col of columns) {
+    widths[col] = col.length;
+  }
+  for (const row of rows) {
+    for (const col of columns) {
+      const val = String(row[col] ?? '');
+      widths[col] = Math.max(widths[col], val.length);
+    }
+  }
+  for (const col of columns) {
+    widths[col] = Math.min(widths[col], 50);
+  }
+
+  const header = columns.map(c => c.padEnd(widths[c])).join(' │ ');
+  const separator = columns.map(c => '─'.repeat(widths[c])).join('─┼─');
+  console.log(header);
+  console.log(separator);
+
+  for (const row of rows) {
+    const line = columns.map(c => {
+      let val = String(row[c] ?? '');
+      if (val.length > 50) val = val.slice(0, 47) + '...';
+      return val.padEnd(widths[c]);
+    }).join(' │ ');
+    console.log(line);
+  }
+
+  console.log(`\n${rows.length} result${rows.length !== 1 ? 's' : ''}`);
+}
+
+/** Convert pages to table rows */
+function pagesToRows(pages) {
+  return pages.map(page => {
+    const row = { id: page.id };
+    if (page.properties) {
+      for (const [key, prop] of Object.entries(page.properties)) {
+        row[key] = propValue(prop);
+      }
+    }
+    return row;
+  });
+}
+
+/** Format rows as CSV string */
+function formatCsv(rows, columns) {
+  if (!rows || rows.length === 0) return '(no results)';
+  const escape = (val) => {
+    const s = String(val ?? '');
+    if (s.includes(',') || s.includes('"') || s.includes('\n')) {
+      return '"' + s.replace(/"/g, '""') + '"';
+    }
+    return s;
+  };
+  const lines = [columns.map(escape).join(',')];
+  for (const row of rows) {
+    lines.push(columns.map(c => escape(row[c])).join(','));
+  }
+  return lines.join('\n');
+}
+
+/** Format rows as YAML string */
+function formatYaml(rows, columns) {
+  if (!rows || rows.length === 0) return '(no results)';
+  const lines = [];
+  for (let i = 0; i < rows.length; i++) {
+    if (i > 0) lines.push('');
+    lines.push(`- # result ${i + 1}`);
+    for (const col of columns) {
+      const val = String(rows[i][col] ?? '');
+      const needsQuote = val.includes(':') || val.includes('#') || val.includes('"') || val.includes("'") || val.includes('\n') || val === '';
+      lines.push(`  ${col}: ${needsQuote ? '"' + val.replace(/"/g, '\\"') + '"' : val}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** Output rows in the specified format */
+function outputFormatted(rows, columns, format) {
+  switch (format) {
+    case 'csv':
+      console.log(formatCsv(rows, columns));
+      break;
+    case 'yaml':
+      console.log(formatYaml(rows, columns));
+      break;
+    case 'json':
+      console.log(JSON.stringify(rows, null, 2));
+      break;
+    case 'table':
+    default:
+      printTable(rows, columns);
+      break;
+  }
+}
+
+/** UUID regex pattern used for validation */
+const UUID_REGEX = /^[0-9a-f-]{32,36}$/i;
+
+/**
+ * Build a Notion filter object from a schema entry and key=value string.
+ * Pure logic portion — does not call the API (schema must be provided).
+ */
+function buildFilterFromSchema(schema, filterStr) {
+  const eqIdx = filterStr.indexOf('=');
+  if (eqIdx === -1) {
+    return { error: `Invalid filter format: ${filterStr} (expected key=value)` };
+  }
+  const key = filterStr.slice(0, eqIdx);
+  const value = filterStr.slice(eqIdx + 1);
+  const schemaEntry = schema[key.toLowerCase()];
+  if (!schemaEntry) {
+    return {
+      error: `Filter property "${key}" not found in database schema.`,
+      available: Object.values(schema).map(s => s.name),
+    };
+  }
+
+  const propName = schemaEntry.name;
+  const type = schemaEntry.type;
+
+  switch (type) {
+    case 'title':
+    case 'rich_text':
+      return { filter: { property: propName, [type]: { contains: value } } };
+    case 'select':
+      return { filter: { property: propName, select: { equals: value } } };
+    case 'multi_select':
+      return { filter: { property: propName, multi_select: { contains: value } } };
+    case 'number':
+      return { filter: { property: propName, number: { equals: Number(value) } } };
+    case 'checkbox':
+      return { filter: { property: propName, checkbox: { equals: value === 'true' || value === '1' } } };
+    case 'date':
+      return { filter: { property: propName, date: { equals: value } } };
+    case 'status':
+      return { filter: { property: propName, status: { equals: value } } };
+    default:
+      return { filter: { property: propName, [type]: { equals: value } } };
+  }
+}
+
+module.exports = {
+  getConfigPaths,
+  loadConfig,
+  saveConfig,
+  richTextToPlain,
+  propValue,
+  buildPropValue,
+  printTable,
+  pagesToRows,
+  formatCsv,
+  formatYaml,
+  outputFormatted,
+  buildFilterFromSchema,
+  UUID_REGEX,
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@jordancoin/notioncli",
+  "version": "1.0.0",
+  "description": "A powerful CLI for the Notion API — query databases, manage pages, and automate your workspace from the terminal.",
+  "main": "bin/notion.js",
+  "bin": {
+    "notion": "./bin/notion.js"
+  },
+  "scripts": {
+    "test": "node --test test/unit.test.js test/mock.test.js",
+    "test:coverage": "c8 --reporter=lcov --reporter=text node --test test/unit.test.js test/mock.test.js",
+    "test:live": "node --test test/integration.test.js",
+    "test:all": "node --test test/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JordanCoin/notioncli.git"
+  },
+  "keywords": [
+    "notion",
+    "cli",
+    "api",
+    "database",
+    "productivity",
+    "workspace",
+    "automation"
+  ],
+  "author": "JordanCoin",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/JordanCoin/notioncli/issues"
+  },
+  "homepage": "https://github.com/JordanCoin/notioncli#readme",
+  "devDependencies": {
+    "c8": "^10.1.3"
+  },
+  "dependencies": {
+    "@notionhq/client": "^5.9.0",
+    "commander": "^14.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: notion
+description: Notion API for creating and managing pages, databases, and blocks via the notioncli CLI tool.
+homepage: https://github.com/JordanCoin/notioncli
+metadata:
+  openclaw:
+    emoji: "📝"
+    requires:
+      env: ["NOTION_API_KEY"]
+    primaryEnv: NOTION_API_KEY
+    install: "npm install -g notioncli"
+---
+
+# notioncli — Notion API Skill
+
+A powerful CLI for the Notion API. Query databases, manage pages, add comments, and automate your workspace from the terminal. Built for AI agents and humans alike.
+
+## Setup
+
+```bash
+npm install -g notioncli
+notion init --key $NOTION_API_KEY
+```
+
+The `init` command saves your API key and **auto-discovers all databases** shared with your integration. Each database gets an alias (a short slug derived from the database title) so you never need to type raw UUIDs.
+
+> **Tip:** In Notion, you must share each database with your integration first: open the database → ••• menu → Connections → Add your integration.
+
+## Auto-Aliases
+
+When you run `notion init`, every shared database is automatically assigned a slug alias:
+
+```
+Found 3 databases:
+
+  ✅ projects                   → Projects
+  ✅ tasks                      → Tasks  
+  ✅ reading-list               → Reading List
+```
+
+You can then use `projects` instead of `a1b2c3d4-e5f6-...` everywhere. Manage aliases manually with:
+
+```bash
+notion alias list                  # Show all aliases
+notion alias add mydb <db-id>     # Add a custom alias
+notion alias rename old new        # Rename an alias
+notion alias remove mydb           # Remove an alias
+```
+
+## Commands Reference
+
+### Database Discovery
+
+```bash
+notion dbs                         # List all databases shared with your integration
+notion alias list                  # Show configured aliases with IDs
+```
+
+### Querying Data
+
+```bash
+notion query tasks                                     # Query all rows
+notion query tasks --filter Status=Active              # Filter by property
+notion query tasks --sort Date:desc                    # Sort results
+notion query tasks --filter Status=Active --limit 10   # Combine options
+notion query tasks --output csv                        # CSV output
+notion query tasks --output yaml                       # YAML output
+notion query tasks --output json                       # JSON output
+notion --json query tasks                              # JSON (shorthand)
+```
+
+**Output formats:**
+- `table` — formatted ASCII table (default)
+- `csv` — header row + comma-separated values
+- `json` — full API response as JSON
+- `yaml` — simple key/value YAML format
+
+### Creating Pages
+
+```bash
+notion add tasks --prop "Name=Buy groceries" --prop "Status=Todo"
+notion add projects --prop "Name=New Feature" --prop "Priority=High" --prop "Due=2026-03-01"
+```
+
+Multiple `--prop` flags for multiple properties. Property names are case-insensitive and matched against the database schema.
+
+### Updating Pages
+
+By page ID:
+```bash
+notion update <page-id> --prop "Status=Done"
+notion update <page-id> --prop "Priority=Low" --prop "Notes=Updated by CLI"
+```
+
+By alias + filter (zero UUIDs):
+```bash
+notion update tasks --filter "Name=Ship feature" --prop "Status=Done"
+notion update workouts --filter "Name=LEGS #5" --prop "Notes=Great session"
+```
+
+### Reading Pages & Content
+
+By page ID:
+```bash
+notion get <page-id>               # Page properties
+notion blocks <page-id>            # Page content (headings, text, lists, etc.)
+```
+
+By alias + filter:
+```bash
+notion get tasks --filter "Name=Ship feature"
+notion blocks tasks --filter "Name=Ship feature"
+```
+
+### Deleting (Archiving) Pages
+
+```bash
+notion delete <page-id>                              # By page ID
+notion delete tasks --filter "Name=Old task"         # By alias + filter
+notion delete workouts --filter "Date=2026-02-09"    # By alias + filter
+```
+
+### Appending Content
+
+```bash
+notion append <page-id> "Meeting notes: discussed Q2 roadmap"
+notion append tasks "Status update: phase 1 complete" --filter "Name=Ship feature"
+```
+
+Appends a paragraph block to the page.
+
+### Users
+
+```bash
+notion users                       # List all workspace users
+notion user <user-id>              # Get details for a specific user
+```
+
+### Comments
+
+```bash
+notion comments <page-id>                                      # By page ID
+notion comments tasks --filter "Name=Ship feature"             # By alias + filter
+notion comment <page-id> "Looks good, shipping this!"          # By page ID
+notion comment tasks "AI review complete ✅" --filter "Name=Ship feature"  # By alias + filter
+```
+
+### Search
+
+```bash
+notion search "quarterly report"   # Search across all pages and databases
+```
+
+### JSON Output
+
+Add `--json` before any command to get the raw Notion API response:
+
+```bash
+notion --json query tasks
+notion --json get <page-id>
+notion --json users
+notion --json comments <page-id>
+```
+
+## Common Patterns for AI Agents
+
+### 1. Discover available databases
+
+```bash
+notion dbs
+notion alias list
+```
+
+### 2. Query and filter data
+
+```bash
+notion query tasks --filter Status=Active --sort Date:desc
+notion --json query tasks --filter Status=Active    # Parse JSON programmatically
+notion query tasks --output csv                     # CSV for spreadsheet tools
+```
+
+### 3. Create a new entry
+
+```bash
+notion add tasks --prop "Name=Review PR #42" --prop "Status=Todo" --prop "Priority=High"
+```
+
+### 4. Update an existing entry (zero UUIDs)
+
+```bash
+# By alias + filter — no page ID needed
+notion update tasks --filter "Name=Review PR #42" --prop "Status=Done"
+
+# Or by page ID if you already have it
+notion update <page-id> --prop "Status=Done"
+```
+
+### 5. Read page content (zero UUIDs)
+
+```bash
+# By alias + filter
+notion get tasks --filter "Name=Review PR #42"
+notion blocks tasks --filter "Name=Review PR #42"
+
+# Or by page ID
+notion get <page-id>
+notion blocks <page-id>
+```
+
+### 6. Append notes to a page
+
+```bash
+notion append tasks "Status update: completed phase 1" --filter "Name=Review PR #42"
+notion append <page-id> "Status update: completed phase 1"
+```
+
+### 7. Collaborate with comments
+
+```bash
+notion comments tasks --filter "Name=Review PR #42"              # Check existing
+notion comment tasks "AI review complete ✅" --filter "Name=Review PR #42"  # Add comment
+
+# Or by page ID
+notion comments <page-id>
+notion comment <page-id> "AI review complete ✅"
+```
+
+### 8. Delete by alias + filter
+
+```bash
+notion delete tasks --filter "Name=Old task"
+notion delete workouts --filter "Date=2026-02-09"
+```
+
+## Property Type Reference
+
+When using `--prop key=value`, the CLI auto-detects the property type from the database schema:
+
+| Type | Example Value | Notes |
+|------|-------------|-------|
+| `title` | `Name=Hello World` | Main title property |
+| `rich_text` | `Notes=Some text` | Plain text content |
+| `number` | `Amount=42.5` | Numeric values |
+| `select` | `Status=Active` | Single select option |
+| `multi_select` | `Tags=bug,urgent` | Comma-separated options |
+| `date` | `Due=2026-03-01` | ISO 8601 date string |
+| `checkbox` | `Done=true` | `true`, `1`, or `yes` |
+| `url` | `Link=https://example.com` | Full URL |
+| `email` | `Contact=user@example.com` | Email address |
+| `phone_number` | `Phone=+1234567890` | Phone number string |
+| `status` | `Status=In Progress` | Status property |
+
+## Notion API 2025 — Dual IDs
+
+The Notion API (2025-09-03) uses dual IDs for databases: a `database_id` and a `data_source_id`. notioncli handles this automatically — when you run `notion init` or `notion alias add`, both IDs are discovered and stored. You never need to think about it.
+
+## Troubleshooting
+
+- **"No Notion API key found"** — Run `notion init --key ntn_...` or `export NOTION_API_KEY=ntn_...`
+- **"Unknown database alias"** — Run `notion alias list` to see available aliases, or `notion init` to rediscover
+- **"Not found" errors** — Make sure the database/page is shared with your integration in Notion
+- **Filter/sort property not found** — Property names are case-insensitive; run `notion --json query <alias> --limit 1` to see available properties

package/skill/install.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+# Install notioncli globally
+npm install -g notioncli
+echo "✅ notioncli installed. Run: notion init --key \$NOTION_API_KEY"