Support multi-value ID parsing

.husky/.gitignore

@@ -0,0 +1 @@
+_/

.husky/pre-push

@@ -0,0 +1 @@
+npm test

README.md

@@ -75,7 +75,7 @@ $ ppls config get hostname
 * [`ppls document-types update ID`](#ppls-document-types-update-id)
 * [`ppls documents add [PATH]`](#ppls-documents-add-path)
 * [`ppls documents delete ID`](#ppls-documents-delete-id)
-* [`ppls documents download ID`](#ppls-documents-download-id)
+* [`ppls documents download [ID]`](#ppls-documents-download-id)
 * [`ppls documents list`](#ppls-documents-list)
 * [`ppls documents show ID`](#ppls-documents-show-id)
 * [`ppls documents update ID`](#ppls-documents-update-id)
@@ -280,11 +280,11 @@ List correspondents
 ```
 USAGE
   $ ppls correspondents list [--date-format <value>] [--header <value>...] [--hostname <value>] [--plain | --json |
-    --table] [--token <value>] [--id-in <value> | --name-contains <value>] [--page <value> --page-size <value>] [--sort
-    <value>]
+    --table] [--token <value>] [--id-in <value>... | --name-contains <value>] [--page <value> --page-size <value>]
+    [--sort <value>]
 
 FLAGS
-  --id-in=<value>          Filter by id list (comma-separated)
+  --id-in=<value>...       Filter by id list (repeatable or comma-separated)
   --name-contains=<value>  Filter by name substring
   --page=<value>           Page number to fetch
   --page-size=<value>      [default: disable pagination, all results] Number of results per page
@@ -457,11 +457,11 @@ List custom fields
 ```
 USAGE
   $ ppls custom-fields list [--date-format <value>] [--header <value>...] [--hostname <value>] [--plain | --json |
-    --table] [--token <value>] [--id-in <value> | --name-contains <value>] [--page <value> --page-size <value>] [--sort
-    <value>]
+    --table] [--token <value>] [--id-in <value>... | --name-contains <value>] [--page <value> --page-size <value>]
+    [--sort <value>]
 
 FLAGS
-  --id-in=<value>          Filter by id list (comma-separated)
+  --id-in=<value>...       Filter by id list (repeatable or comma-separated)
   --name-contains=<value>  Filter by name substring
   --page=<value>           Page number to fetch
   --page-size=<value>      [default: disable pagination, all results] Number of results per page
@@ -632,11 +632,11 @@ List document types
 ```
 USAGE
   $ ppls document-types list [--date-format <value>] [--header <value>...] [--hostname <value>] [--plain | --json |
-    --table] [--token <value>] [--id-in <value> | --name-contains <value>] [--page <value> --page-size <value>] [--sort
-    <value>]
+    --table] [--token <value>] [--id-in <value>... | --name-contains <value>] [--page <value> --page-size <value>]
+    [--sort <value>]
 
 FLAGS
-  --id-in=<value>          Filter by id list (comma-separated)
+  --id-in=<value>...       Filter by id list (repeatable or comma-separated)
   --name-contains=<value>  Filter by name substring
   --page=<value>           Page number to fetch
   --page-size=<value>      [default: disable pagination, all results] Number of results per page
@@ -806,17 +806,17 @@ EXAMPLES
 
 _See code: [src/commands/documents/delete.ts](https://github.com/nickchristensen/ppls/blob/v1.1.0/src/commands/documents/delete.ts)_
 
-## `ppls documents download ID`
+## `ppls documents download [ID]`
 
 Download one or more documents
 
 ```
 USAGE
-  $ ppls documents download ID [--date-format <value>] [--header <value>...] [--hostname <value>] [--plain | --json |
-    --table] [--token <value>] [--original] [-o <value> | --output-dir <value>]
+  $ ppls documents download [ID...] [--date-format <value>] [--header <value>...] [--hostname <value>] [--plain | --json
+    | --table] [--token <value>] [--original] [-o <value> | --output-dir <value>]
 
 ARGUMENTS
-  ID  Document id or comma-separated list of ids
+  [ID...]  Document id (repeatable or comma-separated)
 
 FLAGS
   -o, --output=<value>      Output file path (single document)
@@ -838,9 +838,11 @@ DESCRIPTION
   Download one or more documents
 
 EXAMPLES
-  $ ppls documents download 123 --output document.pdf
+  $ ppls documents download --output document.pdf 123
 
-  $ ppls documents download 123,124 --output-dir ./downloads
+  $ ppls documents download --output-dir ./downloads 123 456
+
+  $ ppls documents download --output-dir ./downloads 123,456
 ```
 
 _See code: [src/commands/documents/download.ts](https://github.com/nickchristensen/ppls/blob/v1.1.0/src/commands/documents/download.ts)_
@@ -852,11 +854,11 @@ List documents
 ```
 USAGE
   $ ppls documents list [--date-format <value>] [--header <value>...] [--hostname <value>] [--plain | --json |
-    --table] [--token <value>] [--id-in <value> | --name-contains <value>] [--page <value> --page-size <value>] [--sort
-    <value>]
+    --table] [--token <value>] [--id-in <value>... | --name-contains <value>] [--page <value> --page-size <value>]
+    [--sort <value>]
 
 FLAGS
-  --id-in=<value>          Filter by id list (comma-separated)
+  --id-in=<value>...       Filter by id list (repeatable or comma-separated)
   --name-contains=<value>  Filter by name substring
   --page=<value>           Page number to fetch
   --page-size=<value>      [default: disable pagination, all results] Number of results per page
@@ -1088,11 +1090,11 @@ List tags
 ```
 USAGE
   $ ppls tags list [--date-format <value>] [--header <value>...] [--hostname <value>] [--plain | --json |
-    --table] [--token <value>] [--id-in <value> | --name-contains <value>] [--page <value> --page-size <value>] [--sort
-    <value>]
+    --table] [--token <value>] [--id-in <value>... | --name-contains <value>] [--page <value> --page-size <value>]
+    [--sort <value>]
 
 FLAGS
-  --id-in=<value>          Filter by id list (comma-separated)
+  --id-in=<value>...       Filter by id list (repeatable or comma-separated)
   --name-contains=<value>  Filter by name substring
   --page=<value>           Page number to fetch
   --page-size=<value>      [default: disable pagination, all results] Number of results per page

package.json

@@ -25,6 +25,7 @@
     "eslint": "^9",
     "eslint-config-oclif": "^6",
     "eslint-config-prettier": "^10",
+    "husky": "^9.1.7",
     "mocha": "^10",
     "oclif": "^4",
     "shx": "^0.3.3",
@@ -80,6 +81,7 @@
     "lint": "eslint",
     "postpack": "shx rm -f oclif.manifest.json",
     "posttest": "npm run lint",
+    "prepare": "husky install",
     "prepack": "npm run build",
     "postbuild": "oclif manifest && oclif readme --no-aliases",
     "test": "mocha --forbid-only \"test/**/*.test.ts\"",

src/base-command.ts

@@ -10,6 +10,8 @@ export type ApiFlags = {
   token: string
 }
 
+type QueryParams = Record<string, number | string | string[] | undefined>
+
 type ResolvedGlobalFlags = ApiFlags & {
   dateFormat: string
 }
@@ -64,7 +66,7 @@ export abstract class BaseCommand extends Command {
   protected buildApiUrl(
     hostnameValue: string,
     path: string,
-    params: Record<string, number | string | undefined> = {},
+    params: QueryParams = {},
   ): URL {
     let url: URL
 
@@ -86,7 +88,7 @@ export abstract class BaseCommand extends Command {
   protected buildApiUrlFromFlags(
     flags: ApiFlags,
     path: string,
-    params: Record<string, number | string | undefined> = {},
+    params: QueryParams = {},
   ): URL {
     return this.buildApiUrl(flags.hostname, path, params)
   }
@@ -124,7 +126,7 @@ export abstract class BaseCommand extends Command {
   protected async fetchApiBinary(
     flags: ApiFlags,
     path: string,
-    params: Record<string, number | string | undefined> = {},
+    params: QueryParams = {},
   ): Promise<{data: Uint8Array; headers: Headers}> {
     const url = this.buildApiUrlFromFlags(flags, path, params)
     const requestHeaders: Record<string, string> = {
@@ -149,7 +151,7 @@ export abstract class BaseCommand extends Command {
   protected async fetchApiJson<T>(
     flags: ApiFlags,
     path: string,
-    params: Record<string, number | string | undefined> = {},
+    params: QueryParams = {},
   ): Promise<T> {
     const url = this.buildApiUrlFromFlags(flags, path, params)
     return this.fetchJson<T>(url, flags.token, flags.headers)

src/commands/documents/download.ts

@@ -4,10 +4,6 @@ import path from 'node:path'
 
 import {BaseCommand} from '../../base-command.js'
 
-type DocumentsDownloadArgs = {
-  id: string
-}
-
 type DocumentsDownloadFlags = {
   original?: boolean
   output?: string
@@ -84,14 +80,30 @@ const resolveOutputPath = async (output: string | undefined, filename: string):
   return resolved
 }
 
+const splitDelimitedValues = (input: string, delimiter: string): string[] => {
+  const splitRegex = new RegExp(`(?<!\\\\)${delimiter}`)
+
+  return input
+    .split(splitRegex)
+    .map((value) => value.trim())
+    .map((value) =>
+      value
+        .replaceAll(new RegExp(`\\\\${delimiter}`, 'g'), delimiter)
+        .replace(/^"(.*)"$/, '$1')
+        .replace(/^'(.*)'$/, '$1'),
+    )
+    .filter((value) => value.length > 0)
+}
+
 export default class DocumentsDownload extends BaseCommand {
   static override args = {
-    id: Args.string({description: 'Document id or comma-separated list of ids', required: true}),
+    id: Args.string({description: 'Document id (repeatable or comma-separated)'}),
   }
   static override description = 'Download one or more documents'
   static override examples = [
-    '<%= config.bin %> <%= command.id %> 123 --output document.pdf',
-    '<%= config.bin %> <%= command.id %> 123,124 --output-dir ./downloads',
+    '<%= config.bin %> <%= command.id %> --output document.pdf 123',
+    '<%= config.bin %> <%= command.id %> --output-dir ./downloads 123 456',
+    '<%= config.bin %> <%= command.id %> --output-dir ./downloads 123,456',
   ]
   static override flags = {
     original: Flags.boolean({description: 'Download original file'}),
@@ -106,6 +118,7 @@ export default class DocumentsDownload extends BaseCommand {
       exists: true,
     }),
   }
+  static override strict = false
 
   protected async downloadDocument(options: DownloadDocumentOptions): Promise<DownloadResult> {
     const {apiFlags, id, original, output, outputDir} = options
@@ -155,32 +168,25 @@ export default class DocumentsDownload extends BaseCommand {
     return results
   }
 
-  protected parseIds(raw: string): number[] {
-    const values = raw
-      .split(',')
-      .map((value) => value.trim())
-      .filter((value) => value.length > 0)
+  public async run(): Promise<DownloadResult | DownloadResult[]> {
+    const {flags, metadata, raw} = await this.parse()
+    const {headers: apiHeaders, hostname, token} = await this.resolveGlobalFlags(flags, metadata)
+    const apiFlags = {headers: apiHeaders, hostname, token}
+    const typedFlags = flags as DocumentsDownloadFlags
+    const rawArgs = raw.filter((token) => token.type === 'arg').map((token) => token.input)
+    const values = rawArgs.flatMap((value) => splitDelimitedValues(value, ','))
 
     if (values.length === 0) {
       this.error('Provide at least one document id.')
     }
 
-    return values.map((value) => {
+    const ids = values.map((value) => {
       if (!/^-?\d+$/.test(value)) {
         this.error(`Invalid document id: ${value}`)
       }
 
       return Number.parseInt(value, 10)
     })
-  }
-
-  public async run(): Promise<DownloadResult | DownloadResult[]> {
-    const {args, flags, metadata} = await this.parse()
-    const {headers: apiHeaders, hostname, token} = await this.resolveGlobalFlags(flags, metadata)
-    const apiFlags = {headers: apiHeaders, hostname, token}
-    const typedArgs = args as DocumentsDownloadArgs
-    const typedFlags = flags as DocumentsDownloadFlags
-    const ids = this.parseIds(typedArgs.id)
     let outputDir = typedFlags['output-dir']
 
     if (ids.length > 1) {

src/commands/documents/list.ts

@@ -10,7 +10,7 @@ export default class DocumentsList extends ListCommand<Document> {
 
   protected override listParams(
     flags: Parameters<ListCommand['listParams']>[0],
-  ): Record<string, number | string | undefined> {
+  ): Record<string, number | string | string[] | undefined> {
     const params = super.listParams(flags)
 
     delete params.name__icontains

src/list-command.ts

@@ -6,7 +6,7 @@ import {BaseCommand} from './base-command.js'
 import {createValueFormatter, type TableColumn, type TableRow} from './helpers/table.js'
 
 type ListCommandFlags = ApiFlags & {
-  'id-in'?: string
+  'id-in'?: string[]
   'name-contains'?: string
   page?: number
   'page-size': number
@@ -32,8 +32,10 @@ export abstract class ListCommand<
   static baseFlags = {
     ...BaseCommand.baseFlags,
     'id-in': Flags.string({
-      description: 'Filter by id list (comma-separated)',
+      delimiter: ',',
+      description: 'Filter by id list (repeatable or comma-separated)',
       exclusive: ['name-contains'],
+      multiple: true,
     }),
     'name-contains': Flags.string({
       description: 'Filter by name substring',
@@ -57,7 +59,7 @@ export abstract class ListCommand<
 
   protected async fetchListResults<T>(options: {
     flags: ListCommandFlags
-    params?: Record<string, number | string | undefined>
+    params?: Record<string, number | string | string[] | undefined>
     path: string
   }): Promise<T[]> {
     const {flags, params = {}, path} = options
@@ -79,7 +81,7 @@ export abstract class ListCommand<
     }
   }
 
-  protected listParams(flags: ListCommandFlags): Record<string, number | string | undefined> {
+  protected listParams(flags: ListCommandFlags): Record<string, number | string | string[] | undefined> {
     return {
       'id__in': flags['id-in'],
       'name__icontains': flags['name-contains'],
@@ -161,7 +163,7 @@ export abstract class ListCommand<
 
   private buildListUrl(options: {
     flags: ListCommandFlags
-    params?: Record<string, number | string | undefined>
+    params?: Record<string, number | string | string[] | undefined>
     path: string
   }): URL {
     const {flags, params = {}, path} = options