@verbatims/cli 1.0.2 → 1.0.4

package/README.md

@@ -42,6 +42,19 @@ verbatims quotes browse
 # Search
 verbatims search "love" --type quotes
 
+# Manage collections
+verbatims collections list --limit 20
+verbatims collections get 12 --page 1 --limit 20
+verbatims collections create --name "Favorite quotes" --public
+verbatims collections update 12 --name "Reading notes" --private
+verbatims collections add 12 123
+verbatims collections remove 12 123
+verbatims collections delete 12 --yes
+
+# Apply a reproducible theme manifest (safe to preview first)
+verbatims themes apply ./theme.json --dry-run
+verbatims themes apply ./theme.json
+
 # List social platforms with queue stats
 verbatims social platforms
 
@@ -58,6 +71,8 @@ verbatims social queue run-now --platform bluesky
 verbatims --help
 ```
 
+Theme manifests use `schema_version: 1`, a stable `slug`, a `name`, and an explicit `filters` array. Optional translations (including homepage copy), language, priority, description, and config are validated before a write. Applying the same manifest reconciles filters by type/value, retaining IDs for unchanged filters; translations reconcile by language, and omitted homepage copy is preserved. Activation and default status are left unchanged. Keep manifests in version control to review theme changes before applying them. See [`examples/themes/quiet-courage.json`](examples/themes/quiet-courage.json).
+
 ### Social commands
 
 ```bash

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@verbatims/cli",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "CLI for the Verbatims quotes API",
   "type": "module",
+  "engines": {
+    "node": "^22 || ^24"
+  },
   "bin": {
     "verbatims": "./bin/verbatims.js"
   },
@@ -16,7 +19,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@verbatims/sdk": "^2.0.2",
+    "@verbatims/sdk": "^2.0.3",
     "@clack/prompts": "^0.10.1",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",

package/src/commands/collections.ts

@@ -1,5 +1,5 @@
 import type { Command } from 'commander'
-import { text, isCancel, cancel } from '@clack/prompts'
+import { text, isCancel, cancel, confirm } from '@clack/prompts'
 import chalk from 'chalk'
 import { getClient } from '../utils/client.js'
 import { output, type Format } from '../utils/format.js'
@@ -12,6 +12,39 @@ function getFormat(program: Command): Format {
 export function registerCollectionsCommand(program: Command) {
   const collections = program.command('collections').description('Manage collections')
 
+  collections
+    .command('list')
+    .description('List collections')
+    .option('--page <n>', 'Page number', '1')
+    .option('--limit <n>', 'Number of results', '20')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data, pagination } = await withSpinner('Fetching collections', () =>
+        client.collections.list({ page: Number(options.page), limit: Number(options.limit) }),
+        format,
+      )
+      output(data, format)
+      if (pagination && format !== 'json') {
+        console.log(chalk.dim(`\nPage ${pagination.page}/${pagination.totalPages} — ${pagination.total} total`))
+      }
+    })
+
+  collections
+    .command('get <id>')
+    .description('Get a collection and its quotes')
+    .option('--page <n>', 'Quote page number', '1')
+    .option('--limit <n>', 'Quotes per page', '20')
+    .action(async (id: string, options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data } = await withSpinner('Fetching collection', () =>
+        client.collections.get(Number(id), { page: Number(options.page), limit: Number(options.limit) }),
+        format,
+      )
+      output(data, format)
+    })
+
   collections
     .command('create')
     .description('Create a collection')
@@ -33,6 +66,51 @@ export function registerCollectionsCommand(program: Command) {
       output(data, format)
     })
 
+  collections
+    .command('update <id>')
+    .description('Update a collection')
+    .option('--name <name>', 'Collection name')
+    .option('--description <text>', 'Description (use an empty value to clear)')
+    .option('--public', 'Make collection public')
+    .option('--private', 'Make collection private')
+    .action(async (id: string, options: Record<string, string | boolean>) => {
+      if (options.public && options.private) {
+        throw new Error('Choose either --public or --private')
+      }
+      const data: { name?: string; description?: string | null; is_public?: boolean } = {}
+      if (options.name) data.name = options.name as string
+      if (options.description !== undefined) data.description = options.description ? options.description as string : null
+      if (options.public) data.is_public = true
+      if (options.private) data.is_public = false
+      if (Object.keys(data).length === 0) {
+        throw new Error('Provide at least one field to update')
+      }
+
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data: updated } = await withSpinner('Updating collection', () =>
+        client.collections.update(Number(id), data),
+        format,
+      )
+      console.log(chalk.green(' Collection updated'))
+      output(updated, format)
+    })
+
+  collections
+    .command('delete <id>')
+    .description('Delete a collection')
+    .option('--yes', 'Skip confirmation')
+    .action(async (id: string, options: { yes?: boolean }) => {
+      if (!options.yes) {
+        const confirmed = await confirm({ message: `Delete collection #${id}?` })
+        if (isCancel(confirmed) || !confirmed) cancel('Cancelled')
+      }
+      const client = await getClient()
+      const format = getFormat(program)
+      await withSpinner('Deleting collection', () => client.collections.delete(Number(id)), format)
+      console.log(chalk.green(` Collection #${id} deleted`))
+    })
+
   collections
     .command('add <collection-id> <quote-id>')
     .description('Add a quote to a collection')

package/src/commands/quotes.ts

@@ -95,12 +95,13 @@ export function registerQuotesCommand(program: Command) {
         }),
         format,
       )
-      if (options.sourceType && data) {
+      const sourceType = options.sourceType
+      if (sourceType && data) {
         const primary = data.attributions?.find(attribution => attribution.is_primary)
         if (!primary) throw new Error('The created quote has no primary attribution')
         await withSpinner('Creating source', () => client.quotes.createSource(data.id, {
           attribution_id: primary.id,
-          source_type: options.sourceType,
+          source_type: sourceType,
           source_url: options.sourceUrl,
           is_primary: true,
         }), format)

package/src/commands/themes.ts

@@ -1,4 +1,6 @@
 import type { Command } from 'commander'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
 import { text, isCancel, cancel, confirm } from '@clack/prompts'
 import chalk from 'chalk'
 import { getClient } from '../utils/client.js'
@@ -47,6 +49,44 @@ export function registerThemesCommand(program: Command) {
       output(data, format)
     })
 
+  themes
+    .command('apply <file>')
+    .description('Create or reconcile a theme from a versioned JSON manifest')
+    .option('--dry-run', 'Validate and show the planned operation without changing data')
+    .action(async (file: string, options: { dryRun?: boolean }) => {
+      const sdk = await import('@verbatims/sdk')
+      if (!('parseThemeManifest' in sdk) || typeof sdk.parseThemeManifest !== 'function') {
+        throw new Error('Theme manifests require a newer @verbatims/sdk. Update the SDK and try again.')
+      }
+      const parseThemeManifest = sdk.parseThemeManifest
+      const manifest = parseThemeManifest(JSON.parse(await readFile(resolve(file), 'utf8')))
+      const client = await getClient()
+      if (typeof client.themes.apply !== 'function') {
+        throw new Error('Theme manifests require a newer @verbatims/sdk. Update the SDK and try again.')
+      }
+      const format = getFormat(program)
+
+      if (options.dryRun) {
+        const { data } = await withSpinner('Checking existing themes', () =>
+          client.themes.list({ search: manifest.slug, limit: 100 }), format)
+        const existing = data?.find(theme => theme.slug === manifest.slug)
+        output({
+          operation: existing ? 'update' : 'create',
+          slug: manifest.slug,
+          name: manifest.name,
+          filters: manifest.filters?.length ?? 0,
+          translations: manifest.translations?.length ?? 'unchanged',
+          activation: 'unchanged',
+          defaultStatus: 'unchanged',
+        }, format)
+        return
+      }
+
+      const result = await withSpinner('Applying theme manifest', () => client.themes.apply(manifest), format)
+      console.log(chalk.green(` Theme ${result.operation}`))
+      output(result.data, format)
+    })
+
   themes
     .command('create')
     .description('Create a theme')