@verbatims/cli 0.1.14 → 0.1.16

package/README.md

@@ -19,12 +19,51 @@ verbatims config
 # List quotes
 verbatims quotes list --language fr --limit 10
 
+# Filter quotes by reference and inspect provenance
+verbatims quotes list --reference 42
+verbatims quotes get 123 --format json
+
+# Create a quote with a source
+verbatims quotes create --source-type book --source-url https://example.com/edition
+
 # Browse interactively
 verbatims quotes browse
 
 # Search
 verbatims search "love" --type quotes
 
+# List social platforms with queue stats
+verbatims social platforms
+
+# List the social queue (defaults to platform x)
+verbatims social queue list --platform bluesky --status queued
+
+# Add approved quotes to the queue
+verbatims social queue add 42 57 --platform bluesky
+
+# Publish the next eligible queued item immediately
+verbatims social queue run-now --platform bluesky
+
 # See all commands
 verbatims --help
 ```
+
+### Social commands
+
+```bash
+verbatims social platforms                                # list platforms + queue stats
+verbatims social posts [--platform <p>] [--status <s>]    # audit trail of published posts
+verbatims social queue list [--platform <p>] [--status <s>] [--search <q>] [--limit <n>]
+verbatims social queue get <id>                           # single queue item
+verbatims social queue add <ids...> [--platform <p>] [--scheduled-for <iso>]
+verbatims social queue random [--platform <p>] [--count <n>] [--language <lang>]
+verbatims social queue remove <id> [--yes]
+verbatims social queue requeue <id>                       # reset a failed item to queued
+verbatims social queue reorder <id> [--direction up|down] [--before <id>]
+verbatims social queue clear [--platform <p>] [--scope all|finished] [--yes]
+verbatims social queue run-now [--platform <p>]           # publish immediately (1/min)
+```
+
+Platforms: `x`, `bluesky`, `instagram`, `threads`, `facebook`, `pinterest`.
+Queue statuses: `queued`, `processing`, `posted`, `failed`, `active`.
+Requires an API key with the `social:read` / `social:write` permissions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verbatims/cli",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "CLI for the Verbatims quotes API",
   "type": "module",
   "bin": {

package/src/commands/index.ts

@@ -7,6 +7,7 @@ import { registerCollectionsCommand } from './collections.js'
 import { registerSearchCommand } from './search.js'
 import { registerConfigCommand } from './config.js'
 import { registerThemesCommand } from './themes.js'
+import { registerSocialCommand } from './social.js'
 
 export function registerCommands(program: Command) {
   registerQuotesCommand(program)
@@ -17,4 +18,5 @@ export function registerCommands(program: Command) {
   registerSearchCommand(program)
   registerConfigCommand(program)
   registerThemesCommand(program)
+  registerSocialCommand(program)
 }

package/src/commands/quotes.ts

@@ -19,6 +19,7 @@ export function registerQuotesCommand(program: Command) {
     .option('--language <lang>', 'Filter by language')
     .option('--limit <n>', 'Number of results', '20')
     .option('--author <id>', 'Filter by author ID')
+    .option('--reference <id>', 'Filter by reference ID')
     .option('--tag <name>', 'Filter by tag')
     .option('--search <q>', 'Search in quote text')
     .option('--status <status>', 'Filter by status (draft|pending|approved|rejected)')
@@ -33,6 +34,7 @@ export function registerQuotesCommand(program: Command) {
           language: options.language,
           limit: Number(options.limit),
           author_id: options.author ? Number(options.author) : undefined,
+          reference_id: options.reference ? Number(options.reference) : undefined,
           tag: options.tag,
           search: options.search,
           q: options.search,
@@ -66,6 +68,8 @@ export function registerQuotesCommand(program: Command) {
     .option('--language <lang>', 'Language')
     .option('--author-id <id>', 'Author ID')
     .option('--reference-id <id>', 'Reference ID')
+    .option('--source-type <type>', 'Source type')
+    .option('--source-url <url>', 'Source URL')
     .action(async (options: Record<string, string>) => {
       const client = await getClient()
       const format = getFormat(program)
@@ -80,7 +84,7 @@ export function registerQuotesCommand(program: Command) {
       const referenceId = options.referenceId ? Number(options.referenceId) : undefined
 
       const { data } = await withSpinner('Creating quote', () =>
-        client.quotes.create({ content: name as string, name: name as string, language: language as string, author_id: authorId, reference_id: referenceId }),
+        client.quotes.create({ content: name as string, name: name as string, language: language as string, author_id: authorId, reference_id: referenceId, source_type: options.sourceType, source_url: options.sourceUrl }),
         format,
       )
       console.log(chalk.green(' Quote created'))
@@ -94,6 +98,8 @@ export function registerQuotesCommand(program: Command) {
     .option('--language <lang>', 'Language')
     .option('--author-id <id>', 'Author ID')
     .option('--reference-id <id>', 'Reference ID')
+    .option('--source-type <type>', 'Source type')
+    .option('--source-url <url>', 'Source URL')
     .action(async (id: string, options: Record<string, string>) => {
       const client = await getClient()
       const format = getFormat(program)
@@ -103,6 +109,8 @@ export function registerQuotesCommand(program: Command) {
       if (options.language) data_.language = options.language
       if (options.authorId !== undefined) data_.author_id = options.authorId === 'null' ? null : Number(options.authorId)
       if (options.referenceId !== undefined) data_.reference_id = options.referenceId === 'null' ? null : Number(options.referenceId)
+      if (options.sourceType !== undefined) data_.source_type = options.sourceType
+      if (options.sourceUrl !== undefined) data_.source_url = options.sourceUrl
 
       const { data } = await withSpinner('Updating quote', () => client.quotes.update(Number(id), data_ as any), format)
       console.log(chalk.green(' Quote updated'))
@@ -172,6 +180,7 @@ export function registerQuotesCommand(program: Command) {
     .description('Browse quotes interactively')
     .option('--language <lang>', 'Filter by language')
     .option('--author <id>', 'Filter by author ID')
+    .option('--reference <id>', 'Filter by reference ID')
     .option('--tag <name>', 'Filter by tag')
     .option('--search <q>', 'Search in quote text')
     .option('--status <status>', 'Filter by status (draft|pending|approved|rejected)')
@@ -185,6 +194,7 @@ export function registerQuotesCommand(program: Command) {
           page,
           language: options.language,
           author_id: options.author ? Number(options.author) : undefined,
+          reference_id: options.reference ? Number(options.reference) : undefined,
           tag: options.tag,
           search: options.search,
           q: options.search,

package/src/commands/social.ts

@@ -0,0 +1,247 @@
+import type { Command } from 'commander'
+import { text, isCancel, cancel, confirm, select } from '@clack/prompts'
+import chalk from 'chalk'
+import { getClient } from '../utils/client.js'
+import { output, type Format } from '../utils/format.js'
+import { withSpinner } from '../utils/spinner.js'
+
+function getFormat(program: Command): Format {
+  return (program.opts().format ?? 'table') as Format
+}
+
+const PLATFORM_CHOICES = ['x', 'bluesky', 'instagram', 'threads', 'facebook', 'pinterest']
+
+export function registerSocialCommand(program: Command) {
+  const social = program.command('social').description('Manage the social auto-post queue')
+
+  social
+    .command('platforms')
+    .description('List social platforms with their queue stats')
+    .action(async () => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data } = await withSpinner('Fetching platforms', () => client.social.listPlatforms(), format)
+      output(data, format)
+    })
+
+  social
+    .command('posts')
+    .description('List published social posts (audit trail)')
+    .option('--platform <platform>', 'Filter by platform')
+    .option('--status <status>', 'Filter by status (success|failed)')
+    .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 posts', () =>
+        client.social.listPosts({
+          platform: options.platform as any,
+          status: options.status as any,
+          limit: Number(options.limit),
+        }),
+        format,
+      )
+      if (data) output(data.posts, format)
+      if (pagination && format !== 'json') {
+        console.log(chalk.dim(`\nPage ${pagination.page}/${pagination.totalPages} — ${pagination.total} total`))
+      }
+    })
+
+  const queue = social.command('queue').description('Manage the social queue')
+
+  queue
+    .command('list')
+    .description('List the social queue for a platform')
+    .option('--platform <platform>', 'Platform (default: x)')
+    .option('--status <status>', 'Filter by status (queued|processing|posted|failed|active)')
+    .option('--search <q>', 'Search by quote text, author, reference, or source')
+    .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 queue', () =>
+        client.social.listQueue({
+          platform: options.platform as any,
+          status: options.status as any,
+          search: options.search,
+          limit: Number(options.limit),
+        }),
+        format,
+      )
+      if (data) {
+        if (format !== 'json') {
+          const stats = data.stats
+          console.log(chalk.dim(
+            `Queued: ${stats.queued} · Processing: ${stats.processing} · Posted: ${stats.posted} · Failed: ${stats.failed}`,
+          ))
+        }
+        output(data.queue, format)
+      }
+      if (pagination && format !== 'json') {
+        console.log(chalk.dim(`\nPage ${pagination.page}/${pagination.totalPages} — ${pagination.total} total`))
+      }
+    })
+
+  queue
+    .command('get <id>')
+    .description('Get a single queue item')
+    .action(async (id: string) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data } = await withSpinner('Fetching queue item', () => client.social.getQueueItem(Number(id)), format)
+      output(data, format)
+    })
+
+  queue
+    .command('add <ids...>')
+    .description('Add approved quotes to the queue')
+    .option('--platform <platform>', 'Platform (default: x)')
+    .option('--scheduled-for <iso>', 'Optional future publish time (ISO 8601)')
+    .action(async (ids: string[], options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const quoteIds = ids.map(Number).filter((n) => Number.isInteger(n) && n > 0)
+      if (!quoteIds.length) {
+        console.log(chalk.red(' Provide at least one quote ID'))
+        process.exit(1)
+      }
+
+      const { data, count } = await withSpinner('Adding quotes to queue', () =>
+        client.social.addToQueue({
+          quote_ids: quoteIds,
+          platform: options.platform as any,
+          scheduled_for: options.scheduledFor || null,
+        }),
+        format,
+      )
+      console.log(chalk.green(` ${count ?? data?.length ?? 0} quote(s) queued`))
+      output(data, format)
+    })
+
+  queue
+    .command('random')
+    .description('Enqueue N random approved quotes')
+    .option('--platform <platform>', 'Platform (default: x)')
+    .option('--count <n>', 'Number of quotes (default: 5, max 100)', '5')
+    .option('--language <lang>', 'Filter by quote language')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data, count } = await withSpinner('Enqueueing random quotes', () =>
+        client.social.addRandomToQueue({
+          platform: options.platform as any,
+          count: Number(options.count),
+          language: options.language,
+        }),
+        format,
+      )
+      console.log(chalk.green(` ${count ?? data?.length ?? 0} quote(s) queued`))
+      output(data, format)
+    })
+
+  queue
+    .command('remove <id>')
+    .description('Remove a queue item')
+    .option('--yes', 'Skip confirmation')
+    .action(async (id: string, options: Record<string, unknown>) => {
+      if (!options.yes) {
+        const confirmed = await confirm({ message: `Remove queue item #${id}?` })
+        if (isCancel(confirmed) || !confirmed) cancel('Cancelled')
+      }
+
+      const client = await getClient()
+      await withSpinner('Removing queue item', () => client.social.removeQueueItem(Number(id)))
+      console.log(chalk.green(` Queue item #${id} removed`))
+    })
+
+  queue
+    .command('requeue <id>')
+    .description('Reset a failed queue item back to queued')
+    .action(async (id: string) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data } = await withSpinner('Requeueing item', () => client.social.requeueQueueItem(Number(id)), format)
+      console.log(chalk.green(` Queue item #${id} requeued`))
+      output(data, format)
+    })
+
+  queue
+    .command('reorder <id>')
+    .description('Reorder a queued item (relative to another item or up/down)')
+    .option('--direction <dir>', 'Move direction (up|down)')
+    .option('--before <id>', 'Place before this queue item ID (or "end" to move to the end)')
+    .action(async (id: string, options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+
+      let beforeId: number | null | undefined
+      if (options.before !== undefined) {
+        beforeId = options.before === 'end' ? null : Number(options.before)
+      }
+
+      const direction = (options.direction ?? '') as 'up' | 'down' | ''
+      if (beforeId === undefined && direction !== 'up' && direction !== 'down') {
+        console.log(chalk.red(' Provide --direction up|down or --before <id>'))
+        process.exit(1)
+      }
+
+      const { data } = await withSpinner('Reordering queue item', () =>
+        client.social.reorderQueueItem({
+          id: Number(id),
+          direction: direction || undefined,
+          before_id: beforeId,
+        }),
+        format,
+      )
+      if (!data?.moved) {
+        console.log(chalk.dim(' Item did not move'))
+        return
+      }
+      console.log(chalk.green(` Queue item #${id} moved to position ${data.position}`))
+    })
+
+  queue
+    .command('clear')
+    .description('Clear the queue for a platform')
+    .option('--platform <platform>', 'Platform', 'x')
+    .option('--scope <scope>', 'Scope: all or finished (posted/failed)', 'all')
+    .option('--yes', 'Skip confirmation')
+    .action(async (options: Record<string, string>) => {
+      const platform = options.platform ?? await select({
+        message: 'Platform',
+        options: PLATFORM_CHOICES.map((p) => ({ value: p, label: p })),
+      })
+      if (isCancel(platform)) cancel('Cancelled')
+
+      const scope = (options.scope ?? 'all') as 'all' | 'finished'
+      const label = scope === 'finished' ? 'finished items (posted/failed)' : 'entire queue'
+
+      if (!options.yes) {
+        const confirmed = await confirm({ message: `Clear the ${label} for ${String(platform)}? This cannot be undone.` })
+        if (isCancel(confirmed) || !confirmed) cancel('Cancelled')
+      }
+
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data } = await withSpinner('Clearing queue', () =>
+        client.social.clearQueue({ platform: platform as string as any, confirm: true, scope }),
+        format,
+      )
+      console.log(chalk.green(` ${data?.deletedCount ?? 0} item(s) cleared from ${data?.platform ?? String(platform)}`))
+      output(data, format)
+    })
+
+  queue
+    .command('run-now')
+    .description('Immediately run the social autopost (throttled to 1 per minute)')
+    .option('--platform <platform>', 'Target platform (all enabled if omitted)')
+    .action(async (options: Record<string, string>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const { data } = await withSpinner('Running autopost', () =>
+        client.social.runNow({ platform: options.platform as any }),
+        format,
+      )
+      output(data, format)
+    })
+}

package/src/utils/browse.ts

@@ -32,7 +32,7 @@ export async function browse(fetchPage: PageFetcher, format: Format): Promise<vo
     }
 
     const allKeys = Object.keys(items[0] as Record<string, unknown>)
-    const keyOrder = ['id', 'content', 'name', 'language', 'type', 'author', 'reference', 'quotes_count']
+    const keyOrder = ['id', 'content', 'name', 'language', 'type', 'author', 'reference', 'source', 'attributions', 'sources', 'quotes_count']
     const columns = keyOrder
       .filter((k) => allKeys.includes(k))
       .map((k) => ({ key: k, label: k }))

package/src/utils/format.ts

@@ -137,7 +137,7 @@ export function output(data: unknown, format: Format): void {
     }
 
     const allKeys = Object.keys(data[0] as Record<string, unknown>)
-    const keyOrder = ['id', 'content', 'name', 'language', 'type', 'author', 'reference', 'quotes_count']
+    const keyOrder = ['id', 'content', 'name', 'language', 'type', 'author', 'reference', 'source', 'attributions', 'sources', 'quotes_count', 'platform', 'label', 'enabled', 'status', 'position', 'quote_text', 'quote_language', 'author_name', 'reference_name', 'post_text', 'post_url', 'posted_at', 'error_message']
     const columns = keyOrder
       .filter((k) => allKeys.includes(k))
       .map((k) => ({ key: k, label: k }))