@wavyx/pdcli 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavyx/pdcli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "publishConfig": {
     "access": "public"
   },
@@ -65,8 +65,14 @@
       "activity": {
         "description": "Activities (calls, meetings, tasks)"
       },
+      "activity:type": {
+        "description": "Activity types (key_string is what activity --type takes)"
+      },
+      "task": {
+        "description": "Tasks (project action items)"
+      },
       "field": {
-        "description": "Custom-field discovery and name/key resolution"
+        "description": "Custom-field management: discovery, name/key resolution, create/update/delete"
       },
       "metrics": {
         "description": "Sales metrics and KPIs"
@@ -82,6 +88,30 @@
       },
       "alias": {
         "description": "Command shortcuts (alias set/list/unset)"
+      },
+      "deal:product": {
+        "description": "Manage products (line items) on a deal"
+      },
+      "deal:participant": {
+        "description": "Manage extra people on a deal (buying committee)"
+      },
+      "deal:follower": {
+        "description": "Manage deal followers"
+      },
+      "person:follower": {
+        "description": "Manage person followers"
+      },
+      "org:follower": {
+        "description": "Manage organization followers"
+      },
+      "org:relationship": {
+        "description": "Manage parent/related links between organizations"
+      },
+      "field:option": {
+        "description": "Manage enum/set field options"
+      },
+      "note:comment": {
+        "description": "Manage comments on a note"
       }
     },
     "hooks": {

package/src/commands/activity/list.js

@@ -1,6 +1,7 @@
 import { Flags } from '@oclif/core'
 import BaseCommand from '../../base-command.js'
 import { collectPages } from '../../lib/pagination.js'
+import { CliError } from '../../lib/errors.js'
 
 const columns = {
   id: { header: 'ID' },
@@ -27,7 +28,9 @@ export default class ActivityListCommand extends BaseCommand {
     deal: Flags.integer({ description: 'Filter by deal ID' }),
     person: Flags.integer({ description: 'Filter by person ID' }),
     org: Flags.integer({ description: 'Filter by organization ID' }),
-    type: Flags.string({ description: 'Filter by activity type key' }),
+    type: Flags.string({
+      description: 'Filter by activity type key (applied client-side)',
+    }),
     done: Flags.boolean({
       description: 'Only completed activities',
       exclusive: ['todo'],
@@ -36,26 +39,65 @@ export default class ActivityListCommand extends BaseCommand {
       description: 'Only open (not done) activities',
       exclusive: ['done'],
     }),
+    filter: Flags.integer({ description: 'Filter by saved filter ID' }),
+    ids: Flags.string({
+      description: 'Comma-separated IDs to fetch (max 100)',
+      // The API silently drops `ids` when filter_id is present — refuse
+      // the combination instead (matches deal bulk-update).
+      exclusive: ['filter'],
+    }),
+    'sort-by': Flags.string({
+      description: 'Sort field',
+      options: ['id', 'update_time', 'add_time', 'due_date'],
+    }),
+    'sort-direction': Flags.string({
+      description: 'Sort direction',
+      options: ['asc', 'desc'],
+    }),
+    'updated-since': Flags.string({
+      description:
+        'Only items updated at/after this RFC3339 time (no fractional seconds)',
+    }),
+    'updated-until': Flags.string({
+      description:
+        'Only items updated before this RFC3339 time (no fractional seconds)',
+    }),
   }
 
   async run() {
     const { flags } = await this.parse(ActivityListCommand)
-    const limit = flags.limit ?? 100
+    const limit = flags.limit ?? 500
+
+    const idList = flags.ids
+      ?.split(',')
+      .map((v) => v.trim())
+      .filter(Boolean)
+    if (idList && idList.length > 100) {
+      throw new CliError('--ids accepts at most 100 IDs', { exitCode: 64 })
+    }
 
     const query = {
       owner_id: flags.owner,
       deal_id: flags.deal,
       person_id: flags.person,
       org_id: flags.org,
-      type: flags.type,
       done: flags.done ? true : flags.todo ? false : undefined,
-      limit: Math.min(limit, 100),
+      filter_id: flags.filter,
+      ids: idList?.join(','),
+      sort_by: flags['sort-by'],
+      sort_direction: flags['sort-direction'],
+      updated_since: flags['updated-since'],
+      updated_until: flags['updated-until'],
+      limit: Math.min(limit, 500),
     }
 
-    const items = await collectPages(
+    let items = await collectPages(
       this.apiClient.pageV2('/api/v2/activities', query),
       limit,
     )
+    // The v2 activities endpoint has no `type` query param (it rejects
+    // unknown params with a 400) — filter client-side instead.
+    if (flags.type) items = items.filter((a) => a.type === flags.type)
     await this.outputResults(items, columns, { entity: 'activity' })
   }
 }

package/src/commands/activity/type/list.js

@@ -0,0 +1,36 @@
+import BaseCommand from '../../../base-command.js'
+
+const columns = {
+  id: { header: 'ID' },
+  key_string: { header: 'Key' },
+  name: { header: 'Name' },
+  active: {
+    header: 'Active',
+    get: (row) => (row.active_flag ? 'yes' : 'no'),
+  },
+}
+
+export default class ActivityTypeListCommand extends BaseCommand {
+  static description =
+    'List activity types. The Key (key_string) is what `activity --type` takes.'
+
+  static examples = [
+    '<%= config.bin %> activity type list',
+    '<%= config.bin %> activity type list --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    const { flags } = await this.parse(ActivityTypeListCommand)
+
+    // Activity types are v1-only and returned in one unpaginated array.
+    const body = await this.apiClient.get('/api/v1/activityTypes')
+    let types = body.data ?? []
+    if (flags.limit != null) types = types.slice(0, flags.limit)
+
+    await this.outputResults(types, columns)
+  }
+}

package/src/commands/deal/convert.js

@@ -0,0 +1,112 @@
+import { Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { CliError } from '../../lib/errors.js'
+
+const POLL_INTERVAL_MS = 2000
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+export default class DealConvertCommand extends BaseCommand {
+  static description =
+    'Convert a deal to a lead. The conversion runs as an async job; ' +
+    'use --wait to poll until it finishes. WARNING: on success the source ' +
+    'deal is deleted.'
+
+  static examples = [
+    '<%= config.bin %> deal convert 42',
+    '<%= config.bin %> deal convert 42 --yes',
+    '<%= config.bin %> deal convert 42 --wait',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    wait: Flags.boolean({
+      description: 'Poll the conversion status until it finishes',
+      default: false,
+    }),
+    'timeout-secs': Flags.integer({
+      description: 'Max seconds to poll when --wait is set',
+      default: 30,
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  /** Overridable in tests so polling never waits in real time. */
+  static sleepFn = defaultSleep
+
+  async run() {
+    const { args, flags } = await this.parse(DealConvertCommand)
+
+    const ok = await confirmAction(
+      `Convert deal ${args.id} to a lead? Deal ${args.id} will be DELETED on success.`,
+      flags.yes,
+      { default: false },
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    const res = await this.apiClient.post(
+      `/api/v2/deals/${args.id}/convert/lead`,
+      // The endpoint takes no parameters, but the client sets a JSON
+      // content-type — the API 400s on an empty body, so send {}.
+      { body: {} },
+    )
+    const conversionId = res.data?.conversion_id
+
+    if (!flags.wait) {
+      this.log(chalk.green(`Conversion started: ${conversionId}`))
+      this.log(
+        `Check status: ${this.config.bin} api GET ` +
+          `/api/v2/deals/${args.id}/convert/status/${conversionId}`,
+      )
+      return
+    }
+
+    const timeoutMs = flags['timeout-secs'] * 1000
+    const sleep = DealConvertCommand.sleepFn
+    let elapsed = 0
+    while (true) {
+      const status = await this.apiClient.get(
+        `/api/v2/deals/${args.id}/convert/status/${conversionId}`,
+      )
+      const state = status.data?.status
+      if (state === 'completed') {
+        this.log(
+          chalk.green(
+            `Conversion completed: deal ${args.id} → lead ${status.data?.lead_id}`,
+          ),
+        )
+        return
+      }
+      if (state === 'failed' || state === 'rejected') {
+        throw new CliError(`Conversion ${state} for deal ${args.id}`, {
+          exitCode: 70,
+        })
+      }
+      if (elapsed + POLL_INTERVAL_MS > timeoutMs) {
+        throw new CliError(
+          `Timed out after ${flags['timeout-secs']}s waiting for conversion ` +
+            `${conversionId} (last status: ${state}). ` +
+            `Check status: ${this.config.bin} api GET ` +
+            `/api/v2/deals/${args.id}/convert/status/${conversionId}`,
+          { exitCode: 1 },
+        )
+      }
+      await sleep(POLL_INTERVAL_MS)
+      elapsed += POLL_INTERVAL_MS
+    }
+  }
+}

package/src/commands/deal/follower/add.js

@@ -0,0 +1,31 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../../base-command.js'
+import { outputRecord } from '../../../lib/entity-view.js'
+
+export default class DealFollowerAddCommand extends BaseCommand {
+  static description = 'Add a follower (user) to a deal'
+
+  static examples = [
+    '<%= config.bin %> deal follower add 42 --user 5',
+    '<%= config.bin %> deal follower add 42 --user 5 --output json',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    user: Flags.integer({ required: true, description: 'User ID' }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealFollowerAddCommand)
+
+    const res = await this.apiClient.post(
+      `/api/v2/deals/${args.id}/followers`,
+      { body: { user_id: flags.user } },
+    )
+    await outputRecord(this, res.data)
+  }
+}

package/src/commands/deal/follower/list.js

@@ -0,0 +1,38 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../../base-command.js'
+import { collectPages } from '../../../lib/pagination.js'
+
+const columns = {
+  user_id: { header: 'User' },
+  add_time: { header: 'Added' },
+}
+
+export default class DealFollowerListCommand extends BaseCommand {
+  static description = 'List followers of a deal'
+
+  static examples = [
+    '<%= config.bin %> deal follower list 42',
+    '<%= config.bin %> deal follower list 42 --output json',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealFollowerListCommand)
+    const limit = flags.limit ?? 500
+
+    const query = { limit: Math.min(limit, 500) }
+
+    const items = await collectPages(
+      this.apiClient.pageV2(`/api/v2/deals/${args.id}/followers`, query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/deal/follower/remove.js

@@ -0,0 +1,44 @@
+import { Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import BaseCommand from '../../../base-command.js'
+import { confirmAction } from '../../../lib/confirm.js'
+import { CliError } from '../../../lib/errors.js'
+
+export default class DealFollowerRemoveCommand extends BaseCommand {
+  static description = 'Remove a follower from a deal'
+
+  static examples = [
+    '<%= config.bin %> deal follower remove 42 --user 5',
+    '<%= config.bin %> deal follower remove 42 --user 5 --yes',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    user: Flags.integer({ required: true, description: 'User ID' }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealFollowerRemoveCommand)
+
+    const ok = await confirmAction(
+      `Remove follower ${flags.user} from deal ${args.id}?`,
+      flags.yes,
+      { default: false },
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    await this.apiClient.del(`/api/v2/deals/${args.id}/followers/${flags.user}`)
+    this.log(chalk.green(`Removed follower ${flags.user} from deal ${args.id}`))
+  }
+}

package/src/commands/deal/history.js

@@ -0,0 +1,73 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { fetchChangelog } from '../../lib/changelog.js'
+import { getFields, makeResolver } from '../../lib/fields.js'
+
+const columns = {
+  time: { header: 'Time' },
+  field_key: { header: 'Field' },
+  old_value: { header: 'Old' },
+  new_value: { header: 'New' },
+  actor_user_id: { header: 'Actor' },
+}
+
+export default class DealHistoryCommand extends BaseCommand {
+  static description =
+    'Field-change history for a deal, newest-first (the API’s native order)'
+
+  static examples = [
+    '<%= config.bin %> deal history 42',
+    '<%= config.bin %> deal history 42 --field stage_id',
+    '<%= config.bin %> deal history 42 --limit 20 --resolve-fields',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    field: Flags.string({
+      description: 'Show only changes to this field key (e.g. stage_id)',
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealHistoryCommand)
+
+    // A field filter drops rows client-side, so the fetch can't be bounded
+    // by --limit in that case; otherwise cap the API page directly.
+    const fetchLimit = flags.field ? undefined : flags.limit
+    let rows = await fetchChangelog(this.apiClient, args.id, {
+      limit: fetchLimit,
+    })
+
+    if (flags.field) {
+      rows = rows.filter((r) => r.field_key === flags.field)
+    }
+    if (flags.limit != null) {
+      rows = rows.slice(0, flags.limit)
+    }
+
+    // The Field column is the one place hash keys appear as DATA — resolve
+    // them (and enum/set option ids) to names under --resolve-fields.
+    if (flags['resolve-fields'] && rows.length > 0) {
+      const resolver = makeResolver(await getFields(this.apiClient, 'deal'))
+      // changelog values are stringified — option ids resolve numerically
+      const label = (key, value) =>
+        resolver.optionIdToLabel(key, Number(value)) ?? value
+      rows = rows.map((r) => {
+        const name = resolver.keyToName(r.field_key)
+        if (!name) return r
+        return {
+          ...r,
+          field_key: name,
+          old_value: label(r.field_key, r.old_value),
+          new_value: label(r.field_key, r.new_value),
+        }
+      })
+    }
+
+    await this.outputResults(rows, columns)
+  }
+}

package/src/commands/deal/list.js

@@ -1,6 +1,7 @@
 import { Flags } from '@oclif/core'
 import BaseCommand from '../../base-command.js'
 import { collectPages } from '../../lib/pagination.js'
+import { CliError } from '../../lib/errors.js'
 
 const columns = {
   id: { header: 'ID' },
@@ -28,6 +29,10 @@ export default class DealListCommand extends BaseCommand {
 
   static flags = {
     ...BaseCommand.baseFlags,
+    archived: Flags.boolean({
+      description: 'List archived deals instead of active ones',
+      default: false,
+    }),
     status: Flags.string({
       description: 'Filter by status',
       options: ['open', 'won', 'lost', 'deleted'],
@@ -37,11 +42,42 @@ export default class DealListCommand extends BaseCommand {
     owner: Flags.integer({ description: 'Filter by owner (user) ID' }),
     person: Flags.integer({ description: 'Filter by person ID' }),
     org: Flags.integer({ description: 'Filter by organization ID' }),
+    filter: Flags.integer({ description: 'Filter by saved filter ID' }),
+    ids: Flags.string({
+      description: 'Comma-separated IDs to fetch (max 100)',
+      // The API silently drops `ids` when filter_id is present — refuse
+      // the combination instead (matches deal bulk-update).
+      exclusive: ['filter'],
+    }),
+    'sort-by': Flags.string({
+      description: 'Sort field',
+      options: ['id', 'update_time', 'add_time'],
+    }),
+    'sort-direction': Flags.string({
+      description: 'Sort direction',
+      options: ['asc', 'desc'],
+    }),
+    'updated-since': Flags.string({
+      description:
+        'Only items updated at/after this RFC3339 time (no fractional seconds)',
+    }),
+    'updated-until': Flags.string({
+      description:
+        'Only items updated before this RFC3339 time (no fractional seconds)',
+    }),
   }
 
   async run() {
     const { flags } = await this.parse(DealListCommand)
-    const limit = flags.limit ?? 100
+    const limit = flags.limit ?? 500
+
+    const idList = flags.ids
+      ?.split(',')
+      .map((v) => v.trim())
+      .filter(Boolean)
+    if (idList && idList.length > 100) {
+      throw new CliError('--ids accepts at most 100 IDs', { exitCode: 64 })
+    }
 
     const query = {
       status: flags.status,
@@ -50,13 +86,18 @@ export default class DealListCommand extends BaseCommand {
       owner_id: flags.owner,
       person_id: flags.person,
       org_id: flags.org,
-      limit: Math.min(limit, 100),
+      filter_id: flags.filter,
+      ids: idList?.join(','),
+      sort_by: flags['sort-by'],
+      sort_direction: flags['sort-direction'],
+      updated_since: flags['updated-since'],
+      updated_until: flags['updated-until'],
+      limit: Math.min(limit, 500),
     }
 
-    const items = await collectPages(
-      this.apiClient.pageV2('/api/v2/deals', query),
-      limit,
-    )
+    // Archived deals share the same params and cursor pager as active deals.
+    const path = flags.archived ? '/api/v2/deals/archived' : '/api/v2/deals'
+    const items = await collectPages(this.apiClient.pageV2(path, query), limit)
     await this.outputResults(items, columns, { entity: 'deal' })
   }
 }

package/src/commands/deal/participant/add.js

@@ -0,0 +1,31 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../../base-command.js'
+import { outputRecord } from '../../../lib/entity-view.js'
+
+export default class DealParticipantAddCommand extends BaseCommand {
+  static description = 'Add a participant (person) to a deal'
+
+  static examples = [
+    '<%= config.bin %> deal participant add 42 --person 10',
+    '<%= config.bin %> deal participant add 42 --person 10 --output json',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    person: Flags.integer({ required: true, description: 'Person ID' }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealParticipantAddCommand)
+
+    const res = await this.apiClient.post(
+      `/api/v1/deals/${args.id}/participants`,
+      { body: { person_id: flags.person } },
+    )
+    await outputRecord(this, res.data)
+  }
+}

package/src/commands/deal/participant/list.js

@@ -0,0 +1,46 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../../base-command.js'
+import { collectPages } from '../../../lib/pagination.js'
+
+const columns = {
+  id: { header: 'ID' },
+  person_id: {
+    header: 'Person',
+    get: (row) => row.person_id?.value ?? '',
+  },
+  name: {
+    header: 'Name',
+    get: (row) => row.person_id?.name ?? '',
+  },
+  add_time: { header: 'Added' },
+}
+
+export default class DealParticipantListCommand extends BaseCommand {
+  static description = 'List participants of a deal'
+
+  static examples = [
+    '<%= config.bin %> deal participant list 42',
+    '<%= config.bin %> deal participant list 42 --output json',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealParticipantListCommand)
+    const limit = flags.limit ?? 100
+
+    const query = { limit: Math.min(limit, 500) }
+
+    const items = await collectPages(
+      this.apiClient.pageV1(`/api/v1/deals/${args.id}/participants`, query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}