@verbatims/cli 0.1.16 → 0.1.18

package/README.md

@@ -23,9 +23,17 @@ verbatims quotes list --language fr --limit 10
 verbatims quotes list --reference 42
 verbatims quotes get 123 --format json
 
+# Manage provenance (moderator/admin API key)
+verbatims quotes attributions list 123
+verbatims quotes attributions create 123 --author-id 1 --reference-id 2 --status manually_verified --primary
+verbatims quotes sources list 123
+verbatims quotes sources create 123 --source-type book --source-url https://example.com/edition --status externally_verified
+
 # Create a quote with a source
 verbatims quotes create --source-type book --source-url https://example.com/edition
 
+The quote-level `--author-id`, `--reference-id`, `--source-type`, and `--source-url` options are deprecated compatibility options. New integrations should use the SDK `provenance` payload; the dedicated `quotes attributions` and `quotes sources` commands manage secondary provenance.
+
 # Browse interactively
 verbatims quotes browse
 

package/package.json

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

package/src/commands/quotes.ts

@@ -10,6 +10,13 @@ function getFormat(program: Command): Format {
   return (program.opts().format ?? 'table') as Format
 }
 
+function warnLegacyQuoteOptions(options: Record<string, unknown>): void {
+  const fields = ['authorId', 'referenceId', 'sourceType', 'sourceUrl']
+  if (fields.some(field => options[field] !== undefined)) {
+    console.error(chalk.yellow('Warning: quote provenance options are deprecated; use the provenance API fields instead.'))
+  }
+}
+
 export function registerQuotesCommand(program: Command) {
   const quotes = program.command('quotes').description('Manage quotes')
 
@@ -66,13 +73,14 @@ export function registerQuotesCommand(program: Command) {
     .description('Create a quote')
     .option('--name <text>', 'Quote text')
     .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')
+    .option('--author-id <id>', 'Author ID (deprecated)')
+    .option('--reference-id <id>', 'Reference ID (deprecated)')
+    .option('--source-type <type>', 'Source type (deprecated)')
+    .option('--source-url <url>', 'Source URL (deprecated)')
     .action(async (options: Record<string, string>) => {
       const client = await getClient()
       const format = getFormat(program)
+      warnLegacyQuoteOptions(options)
 
       const name = options.name ?? await text({ message: 'Quote text', validate: (v) => !v ? 'Required' : undefined })
       if (isCancel(name)) cancel('Cancelled')
@@ -84,7 +92,16 @@ 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, source_type: options.sourceType, source_url: options.sourceUrl }),
+        client.quotes.create({
+          content: name as string,
+          name: name as string,
+          language: language as string,
+          provenance: {
+            author_id: authorId,
+            reference_id: referenceId,
+            source: options.sourceType ? { source_type: options.sourceType, source_url: options.sourceUrl } : undefined,
+          },
+        }),
         format,
       )
       console.log(chalk.green(' Quote created'))
@@ -96,21 +113,26 @@ export function registerQuotesCommand(program: Command) {
     .description('Update a quote')
     .option('--name <text>', 'Quote text')
     .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')
+    .option('--author-id <id>', 'Author ID (deprecated)')
+    .option('--reference-id <id>', 'Reference ID (deprecated)')
+    .option('--source-type <type>', 'Source type (deprecated)')
+    .option('--source-url <url>', 'Source URL (deprecated)')
     .action(async (id: string, options: Record<string, string>) => {
       const client = await getClient()
       const format = getFormat(program)
+      warnLegacyQuoteOptions(options)
 
       const data_: Record<string, unknown> = {}
       if (options.name) { data_.name = options.name; data_.content = options.name }
       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
+      if (options.authorId !== undefined) data_.provenance = { ...(data_.provenance as object), author_id: options.authorId === 'null' ? null : Number(options.authorId) }
+      if (options.referenceId !== undefined) data_.provenance = { ...(data_.provenance as object), reference_id: options.referenceId === 'null' ? null : Number(options.referenceId) }
+      if (options.sourceType !== undefined || options.sourceUrl !== undefined) {
+        data_.provenance = {
+          ...(data_.provenance as object),
+          source: { source_type: options.sourceType ?? 'manual', 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'))
@@ -206,6 +228,123 @@ export function registerQuotesCommand(program: Command) {
       )
     })
 
+  quotes
+    .command('attributions <action> <quoteId> [attributionId]')
+    .description('Manage quote attributions (moderator/admin API key required)')
+    .option('--author-id <id>', 'Author ID')
+    .option('--reference-id <id>', 'Reference ID')
+    .option('--status <status>', 'Verification status')
+    .option('--notes <text>', 'Internal notes')
+    .option('--primary', 'Set as primary attribution')
+    .option('--yes', 'Skip confirmation')
+    .action(async (action: string, quoteId: string, attributionId: string | undefined, options: Record<string, any>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const id = Number(quoteId)
+
+      if (action === 'list') {
+        const { data } = await withSpinner('Fetching attributions', () => client.quotes.listAttributions(id), format)
+        output(data, format)
+        return
+      }
+      if (action === 'create') {
+        const { data } = await withSpinner('Creating attribution', () => client.quotes.createAttribution(id, {
+          author_id: options.authorId ? Number(options.authorId) : null,
+          reference_id: options.referenceId ? Number(options.referenceId) : null,
+          status: options.status,
+          notes: options.notes,
+          is_primary: options.primary,
+        }), format)
+        output(data, format)
+        return
+      }
+      if (!attributionId) throw new Error('Attribution ID is required')
+      const attribution = Number(attributionId)
+      if (action === 'update') {
+        const data_: Record<string, unknown> = {}
+        if (options.authorId !== undefined) data_.author_id = Number(options.authorId)
+        if (options.referenceId !== undefined) data_.reference_id = Number(options.referenceId)
+        if (options.status !== undefined) data_.status = options.status
+        if (options.notes !== undefined) data_.notes = options.notes
+        if (options.primary !== undefined) data_.is_primary = options.primary
+        const { data } = await withSpinner('Updating attribution', () => client.quotes.updateAttribution(id, attribution, data_), format)
+        output(data, format)
+        return
+      }
+      if (action === 'delete') {
+        if (!options.yes) {
+          const confirmed = await confirm({ message: `Delete attribution #${attribution} from quote #${id}?` })
+          if (isCancel(confirmed) || !confirmed) cancel('Cancelled')
+        }
+        await withSpinner('Deleting attribution', () => client.quotes.deleteAttribution(id, attribution), format)
+        console.log(chalk.green(' Attribution deleted'))
+        return
+      }
+      throw new Error('Action must be list, create, update, or delete')
+    })
+
+  quotes
+    .command('sources <action> <quoteId> [sourceId]')
+    .description('Manage quote sources (moderator/admin API key required)')
+    .option('--attribution-id <id>', 'Attribution ID')
+    .option('--source-type <type>', 'Source type')
+    .option('--source-url <url>', 'Source URL')
+    .option('--label <label>', 'Source label')
+    .option('--status <status>', 'Verification status')
+    .option('--notes <text>', 'Internal notes')
+    .option('--primary', 'Set as primary source')
+    .option('--yes', 'Skip confirmation')
+    .action(async (action: string, quoteId: string, sourceId: string | undefined, options: Record<string, any>) => {
+      const client = await getClient()
+      const format = getFormat(program)
+      const id = Number(quoteId)
+
+      if (action === 'list') {
+        const { data } = await withSpinner('Fetching sources', () => client.quotes.listSources(id), format)
+        output(data, format)
+        return
+      }
+      if (action === 'create') {
+        if (!options.sourceType) throw new Error('--source-type is required')
+        const { data } = await withSpinner('Creating source', () => client.quotes.createSource(id, {
+          attribution_id: options.attributionId ? Number(options.attributionId) : null,
+          source_type: options.sourceType,
+          source_url: options.sourceUrl,
+          label: options.label,
+          verification_status: options.status,
+          notes: options.notes,
+          is_primary: options.primary,
+        }), format)
+        output(data, format)
+        return
+      }
+      if (!sourceId) throw new Error('Source ID is required')
+      const source = Number(sourceId)
+      if (action === 'update') {
+        const data_: Record<string, unknown> = {}
+        if (options.attributionId !== undefined) data_.attribution_id = Number(options.attributionId)
+        if (options.sourceType !== undefined) data_.source_type = options.sourceType
+        if (options.sourceUrl !== undefined) data_.source_url = options.sourceUrl
+        if (options.label !== undefined) data_.label = options.label
+        if (options.status !== undefined) data_.verification_status = options.status
+        if (options.notes !== undefined) data_.notes = options.notes
+        if (options.primary !== undefined) data_.is_primary = options.primary
+        const { data } = await withSpinner('Updating source', () => client.quotes.updateSource(id, source, data_), format)
+        output(data, format)
+        return
+      }
+      if (action === 'delete') {
+        if (!options.yes) {
+          const confirmed = await confirm({ message: `Delete source #${source} from quote #${id}?` })
+          if (isCancel(confirmed) || !confirmed) cancel('Cancelled')
+        }
+        await withSpinner('Deleting source', () => client.quotes.deleteSource(id, source), format)
+        console.log(chalk.green(' Source deleted'))
+        return
+      }
+      throw new Error('Action must be list, create, update, or delete')
+    })
+
   const tags = quotes.command('tags').description('Manage quote tags')
 
   tags