@wavyx/pdcli 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavyx/pdcli",
-  "version": "0.10.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"
@@ -85,6 +91,27 @@
       },
       "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/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/list.js

@@ -29,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'],
@@ -91,10 +95,9 @@ export default class DealListCommand extends BaseCommand {
       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)
+  }
+}

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

@@ -0,0 +1,53 @@
+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 DealParticipantRemoveCommand extends BaseCommand {
+  static description = 'Remove a participant from a deal'
+
+  static examples = [
+    '<%= config.bin %> deal participant remove 42 --participant 3',
+    '<%= config.bin %> deal participant remove 42 --participant 3 --yes',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    participant: Flags.integer({
+      required: true,
+      description: 'Deal-participant ID',
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealParticipantRemoveCommand)
+
+    const ok = await confirmAction(
+      `Remove participant ${flags.participant} from deal ${args.id}?`,
+      flags.yes,
+      { default: false },
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    await this.apiClient.del(
+      `/api/v1/deals/${args.id}/participants/${flags.participant}`,
+    )
+    this.log(
+      chalk.green(
+        `Removed participant ${flags.participant} from deal ${args.id}`,
+      ),
+    )
+  }
+}

package/src/commands/deal/summary.js

@@ -0,0 +1,69 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+
+const columns = {
+  currency: { header: 'Currency' },
+  total: { header: 'Total' },
+  weighted: { header: 'Weighted' },
+  count: { header: 'Count' },
+}
+
+export default class DealSummaryCommand extends BaseCommand {
+  static description = 'Summary of open/won/lost deals, totalled per currency'
+
+  static examples = [
+    '<%= config.bin %> deal summary',
+    '<%= config.bin %> deal summary --status open --pipeline 1',
+    '<%= config.bin %> deal summary --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    status: Flags.string({
+      description: 'Filter by status',
+      options: ['open', 'won', 'lost'],
+    }),
+    pipeline: Flags.integer({ description: 'Filter by pipeline ID' }),
+    stage: Flags.integer({ description: 'Filter by stage ID' }),
+    filter: Flags.integer({ description: 'Filter by saved filter ID' }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(DealSummaryCommand)
+
+    // Summary lives on v1; the v2 wrapper does not exist. Cost: 40 tokens.
+    const body = await this.apiClient.get('/api/v1/deals/summary', {
+      query: {
+        status: flags.status,
+        pipeline_id: flags.pipeline,
+        stage_id: flags.stage,
+        filter_id: flags.filter,
+      },
+    })
+
+    const data = body.data ?? {}
+
+    // Non-table formats stay raw for scriptability: emit the data object as-is
+    // (per-currency totals, grand totals, counts).
+    if (this.resolveFormat() !== 'table') {
+      await this.outputResults(data, columns)
+      return
+    }
+
+    // Table view: one row per deal currency. Totals come pre-formatted from the
+    // API (`value_formatted`, e.g. "€10") — render those rather than re-deriving
+    // currency symbols. Weighted totals are keyed by the same currency code.
+    const values = data.values_total ?? {}
+    const weighted = data.weighted_values_total ?? {}
+    // `get` returning undefined renders as an empty cell, so no `?? ''` tail.
+    const rows = Object.entries(values).map(([currency, totals]) => ({
+      currency,
+      total: totals.value_formatted ?? totals.value,
+      weighted:
+        weighted[currency]?.value_formatted ?? weighted[currency]?.value,
+      count: totals.count,
+    }))
+
+    await this.outputResults(rows, columns)
+  }
+}

package/src/commands/field/create.js

@@ -0,0 +1,72 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { clearFieldsCache, entityToFieldsPath } from '../../lib/fields.js'
+import { CliError } from '../../lib/errors.js'
+
+/** Option-bearing field types that require --options on creation. */
+const OPTION_TYPES = new Set(['enum', 'set'])
+
+export default class FieldCreateCommand extends BaseCommand {
+  static description = 'Create a custom field on an entity'
+
+  static examples = [
+    '<%= config.bin %> field create deal --name "Budget" --type double',
+    '<%= config.bin %> field create person --name "Tier" --type enum --options "Gold,Silver,Bronze"',
+  ]
+
+  static args = {
+    entity: Args.string({
+      required: true,
+      description: 'Entity type',
+      // Custom fields are writable on core v2 entities only — activity fields
+      // are read-only, and lead/note have no v2 write path.
+      options: ['deal', 'person', 'org', 'organization', 'product'],
+    }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    name: Flags.string({ required: true, description: 'Field name (label)' }),
+    type: Flags.string({
+      required: true,
+      description: 'Field type (e.g. varchar, double, monetary, enum, set)',
+    }),
+    options: Flags.string({
+      description: 'Comma-separated option labels (required for enum/set)',
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(FieldCreateCommand)
+
+    const isOptionType = OPTION_TYPES.has(flags.type)
+    if (isOptionType && !flags.options) {
+      throw new CliError(
+        `Field type "${flags.type}" requires --options "A,B,C"`,
+        { exitCode: 64 },
+      )
+    }
+
+    const body = { field_name: flags.name, field_type: flags.type }
+    if (isOptionType) {
+      body.options = flags.options
+        .split(',')
+        .map((label) => ({ label: label.trim() }))
+    }
+
+    const path = entityToFieldsPath(args.entity)
+    const res = await this.apiClient.post(path, { body })
+
+    clearFieldsCache()
+
+    await this.outputResults(res.data, {
+      field_code: { header: 'Key' },
+      field_name: { header: 'Name' },
+      field_type: { header: 'Type' },
+      options: {
+        header: 'Options',
+        get: (row) => row.options?.map((o) => `${o.id}=${o.label}`).join(', '),
+      },
+    })
+  }
+}

package/src/commands/field/delete.js

@@ -0,0 +1,56 @@
+import { Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { clearFieldsCache, entityToFieldsPath } from '../../lib/fields.js'
+import { CliError } from '../../lib/errors.js'
+
+export default class FieldDeleteCommand extends BaseCommand {
+  static description = 'Delete a custom field (data stored on records is lost)'
+
+  static examples = [
+    '<%= config.bin %> field delete deal dcf558aac1ae4e8c4f849ba5e668430d8df9be12',
+    '<%= config.bin %> field delete deal dcf558aac1ae4e8c4f849ba5e668430d8df9be12 --yes',
+  ]
+
+  static args = {
+    entity: Args.string({
+      required: true,
+      description: 'Entity type',
+      options: ['deal', 'person', 'org', 'organization', 'product'],
+    }),
+    field: Args.string({
+      required: true,
+      description: 'Field code (hashed key)',
+    }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(FieldDeleteCommand)
+
+    const ok = await confirmAction(
+      `Delete field ${args.field} on ${args.entity}? ` +
+        `All data stored in this field on existing records is lost.`,
+      flags.yes,
+      { default: false },
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    await this.apiClient.del(`${entityToFieldsPath(args.entity)}/${args.field}`)
+
+    clearFieldsCache()
+
+    this.log(chalk.green(`Deleted field ${args.field} on ${args.entity}`))
+  }
+}