keep-markdown 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# keep-markdown
+
+CLI for [keep.md](https://keep.md) — search and retrieve saved web content as Markdown.
+
+## Setup
+
+1. Sign up for an account at https://keep.md
+2. Create an API token at https://keep.md/dashboard
+3. Save your token:
+
+```
+npm i -g keep-markdown
+keep key <your-token>
+```
+
+Alternatively set the `KEEP_API_KEY` environment variable.
+
+## Usage
+
+```
+keep list --since 7d
+keep search "react hooks"
+keep get <id>
+keep content <id>
+keep me
+keep stats
+```
+
+Run `keep help` for the full list of commands and options.

package/bin/keep.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const DEFAULT_BASE_URL = 'https://keep.md'
+
+const usage = () => `
+keep <command> [options]
+
+Commands:
+  key <token>            Save API key for future use
+  list                   List items
+  search <query>         Search items (shortcut for list --query)
+  get <id>               Get item metadata
+  content <id>           Get Markdown content
+  archive <id>           Archive an item (hide from default list)
+  me                     Show account info
+  stats                  Get usage stats
+
+Global options:
+  --base <url>           Base API URL (env KEEP_API_BASE_URL)
+  --key <token>          API key (env KEEP_API_KEY or KEEP_API_TOKEN)
+  --json                 Output raw JSON
+
+List options:
+  --since <value>        e.g. 7d, 24h, 2024-01-01
+  --until <value>
+  --status <list>        comma-separated
+  --limit <n>
+  --offset <n>
+  --content              Include markdown in list
+  --query <text>         Filter by title, URL, notes, or tags
+`
+
+const parseArgs = (argv) => {
+  const flags = {}
+  const positionals = []
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+      const next = argv[i + 1]
+      if (next && !next.startsWith('--')) {
+        flags[key] = next
+        i += 1
+      } else {
+        flags[key] = true
+      }
+      continue
+    }
+    positionals.push(arg)
+  }
+  return { flags, positionals }
+}
+
+const configDir = join(homedir(), '.config', 'keep')
+const configFile = join(configDir, 'config.json')
+const legacyConfigFile = join(
+  homedir(),
+  '.config',
+  'keep-markdown',
+  'config.json',
+)
+
+const loadConfig = async () => {
+  try {
+    return JSON.parse(await readFile(configFile, 'utf8'))
+  } catch {
+    try {
+      // Backwards compatibility: earlier builds stored config under keep-markdown.
+      return JSON.parse(await readFile(legacyConfigFile, 'utf8'))
+    } catch {
+      return {}
+    }
+  }
+}
+
+const saveConfig = async (data) => {
+  await mkdir(configDir, { recursive: true })
+  await writeFile(configFile, JSON.stringify(data, null, 2) + '\n')
+}
+
+const requireAuth = async (flags) => {
+  const config = await loadConfig()
+  const baseUrl =
+    flags.base ||
+    process.env.KEEP_API_BASE_URL ||
+    config.baseUrl ||
+    DEFAULT_BASE_URL
+  const apiKey =
+    flags.key ||
+    process.env.KEEP_API_KEY ||
+    process.env.KEEP_API_TOKEN ||
+    config.apiKey
+  if (!apiKey) {
+    console.error('No API key found. Run: keep key <your-api-key>')
+    process.exit(1)
+  }
+  return { baseUrl: baseUrl.replace(/\/+$/, ''), apiKey }
+}
+
+const parseTimeInput = (value) => {
+  if (!value) return undefined
+  if (/^\d+$/.test(value)) return value
+  const match = value.match(/^(\d+)([smhd])$/i)
+  if (match) {
+    const amount = Number(match[1])
+    const unit = match[2].toLowerCase()
+    const multiplier =
+      unit === 's'
+        ? 1000
+        : unit === 'm'
+          ? 60_000
+          : unit === 'h'
+            ? 3_600_000
+            : 86_400_000
+    return String(Date.now() - amount * multiplier)
+  }
+  const parsed = Date.parse(value)
+  if (Number.isFinite(parsed)) return String(parsed)
+  return value
+}
+
+const apiFetch = async (baseUrl, apiKey, path, options = {}) => {
+  const headers = {
+    authorization: `Bearer ${apiKey}`,
+    ...(options.headers || {}),
+  }
+  const res = await fetch(`${baseUrl}${path}`, { ...options, headers })
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    throw new Error(`Request failed (${res.status}): ${body}`)
+  }
+  return res
+}
+
+const output = async (res, jsonOutput) => {
+  if (jsonOutput) {
+    const data = await res.json()
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`)
+    return
+  }
+  const text = await res.text()
+  process.stdout.write(text.endsWith('\n') ? text : `${text}\n`)
+}
+
+const printItems = (data) => {
+  const items = Array.isArray(data?.items) ? data.items : []
+  for (const item of items) {
+    const id = item?.id ?? ''
+    const url = item?.url ?? ''
+    const title = item?.title ?? ''
+    // Stable, script-friendly single-line output.
+    process.stdout.write(`${id}\t${url}\t${title}\n`)
+  }
+}
+
+const listItems = async (flags) => {
+  const { baseUrl, apiKey } = await requireAuth(flags)
+  const params = new URLSearchParams()
+  const since = parseTimeInput(flags.since)
+  const until = parseTimeInput(flags.until)
+  if (since) params.set('since', since)
+  if (until) params.set('until', until)
+  if (flags.status) params.set('status', flags.status)
+  if (flags.limit) params.set('limit', flags.limit)
+  if (flags.offset) params.set('offset', flags.offset)
+  if (flags.content) params.set('content', '1')
+  if (flags.query) params.set('q', flags.query)
+  const res = await apiFetch(
+    baseUrl,
+    apiKey,
+    `/api/items${params.toString() ? `?${params}` : ''}`,
+  )
+  if (flags.json) {
+    await output(res, true)
+    return
+  }
+  const data = await res.json()
+  printItems(data)
+}
+
+const getItem = async (id, flags) => {
+  const { baseUrl, apiKey } = await requireAuth(flags)
+  const params = new URLSearchParams()
+  if (flags.content) params.set('content', '1')
+  const res = await apiFetch(
+    baseUrl,
+    apiKey,
+    `/api/items/${id}${params.toString() ? `?${params}` : ''}`,
+  )
+  await output(res, true)
+}
+
+const getContent = async (id, flags) => {
+  const { baseUrl, apiKey } = await requireAuth(flags)
+  const res = await apiFetch(baseUrl, apiKey, `/api/items/${id}/content`)
+  await output(res, false)
+}
+
+const archiveItem = async (id, flags) => {
+  const { baseUrl, apiKey } = await requireAuth(flags)
+  const res = await apiFetch(baseUrl, apiKey, '/api/items/archive', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ ids: [id] }),
+  })
+  await output(res, true)
+}
+
+const getMe = async (flags) => {
+  const { baseUrl, apiKey } = await requireAuth(flags)
+  const res = await apiFetch(baseUrl, apiKey, '/api/me')
+  await output(res, true)
+}
+
+const getStats = async (flags) => {
+  const { baseUrl, apiKey } = await requireAuth(flags)
+  const params = new URLSearchParams()
+  const since = parseTimeInput(flags.since)
+  const until = parseTimeInput(flags.until)
+  if (since) params.set('since', since)
+  if (until) params.set('until', until)
+  const res = await apiFetch(
+    baseUrl,
+    apiKey,
+    `/api/stats${params.toString() ? `?${params}` : ''}`,
+  )
+  await output(res, Boolean(flags.json))
+}
+
+const main = async () => {
+  const [command, ...rest] = process.argv.slice(2)
+  if (!command || command === 'help' || command === '--help') {
+    process.stdout.write(usage())
+    return
+  }
+  const { flags, positionals } = parseArgs(rest)
+
+  if (command === 'key') {
+    const token = positionals[0]
+    if (!token)
+      throw new Error('Missing API key. Usage: keep key <your-api-key>')
+    const config = await loadConfig()
+    config.apiKey = token
+    await saveConfig(config)
+    process.stdout.write('API key saved.\n')
+    return
+  }
+
+  if (command === 'list') {
+    await listItems(flags)
+    return
+  }
+
+  if (command === 'search') {
+    const query = positionals[0]
+    if (!query) throw new Error('Missing search query.')
+    flags.query = query
+    await listItems(flags)
+    return
+  }
+
+  if (command === 'get') {
+    const id = positionals[0]
+    if (!id) throw new Error('Missing item id.')
+    await getItem(id, flags)
+    return
+  }
+
+  if (command === 'content') {
+    const id = positionals[0]
+    if (!id) throw new Error('Missing item id.')
+    await getContent(id, flags)
+    return
+  }
+
+  if (command === 'archive') {
+    const id = positionals[0]
+    if (!id) throw new Error('Missing item id.')
+    await archiveItem(id, flags)
+    return
+  }
+
+  if (command === 'me') {
+    await getMe(flags)
+    return
+  }
+
+  if (command === 'stats') {
+    await getStats(flags)
+    return
+  }
+
+  throw new Error(`Unknown command: ${command}`)
+}
+
+main().catch((error) => {
+  console.error(error?.message || error)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "keep-markdown",
+  "version": "0.1.0",
+  "description": "CLI for keep.md — search and retrieve saved web content as Markdown",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://keep.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iannuttall/keep.git",
+    "directory": "packages/cli"
+  },
+  "author": "Ian Nuttall",
+  "keywords": [
+    "keep",
+    "markdown",
+    "cli",
+    "bookmarks",
+    "web-content"
+  ],
+  "bin": {
+    "keep": "bin/keep.js",
+    "keep-markdown": "bin/keep.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}