@wavyx/pdcli 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavyx/pdcli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "publishConfig": {
     "access": "public"
   },
@@ -68,6 +68,9 @@
       "field": {
         "description": "Custom-field discovery and name/key resolution"
       },
+      "metrics": {
+        "description": "Sales metrics and KPIs"
+      },
       "user": {
         "description": "Users"
       },
@@ -76,6 +79,9 @@
       },
       "config": {
         "description": "Configuration"
+      },
+      "alias": {
+        "description": "Command shortcuts (alias set/list/unset)"
       }
     },
     "hooks": {
@@ -120,6 +126,7 @@
   "scripts": {
     "build": "oclif manifest",
     "docs:commands": "node scripts/gen-commands.mjs",
+    "docs:demo": "node scripts/gen-demo.mjs",
     "lint": "eslint . && prettier --check .",
     "lint:fix": "eslint --fix . && prettier --write .",
     "test": "vitest run",

package/src/base-command.js

@@ -22,6 +22,12 @@ export default class BaseCommand extends Command {
       description: 'Comma-separated fields to display',
       helpGroup: 'GLOBAL',
     }),
+    'resolve-fields': Flags.boolean({
+      description:
+        'Resolve custom-field hash keys to names (and option ids to labels) in json/yaml/csv output of get and core list commands',
+      helpGroup: 'GLOBAL',
+      default: false,
+    }),
     profile: Flags.string({
       description: 'Named auth profile to use',
       helpGroup: 'GLOBAL',
@@ -118,9 +124,13 @@ export default class BaseCommand extends Command {
     })
   }
 
-  /** The profile's `default_output` config value, when valid. */
+  /**
+   * The profile's `default_output` config value, when valid. Safe to call
+   * before parsing completes (handleError runs for parse failures too,
+   * when `this.flags` is still undefined).
+   */
   storedDefaultOutput() {
-    const stored = loadConfig(this.flags.profile).default_output
+    const stored = loadConfig(this.flags?.profile).default_output
     return ['table', 'json', 'yaml', 'csv'].includes(stored)
       ? stored
       : undefined
@@ -141,12 +151,31 @@ export default class BaseCommand extends Command {
   /**
    * @param {object | object[]} data
    * @param {Record<string, import('./lib/output/table.js').Column>} columns
+   * @param {{ entity?: string }} [options] entity context enables
+   *   --resolve-fields custom-field resolution on machine-format lists
    */
-  async outputResults(data, columns) {
+  async outputResults(data, columns, { entity } = {}) {
+    if (
+      entity &&
+      this.flags['resolve-fields'] &&
+      this.resolveFormat() !== 'table' &&
+      Array.isArray(data) &&
+      data.some((row) => row?.custom_fields)
+    ) {
+      const { getFields, makeResolver } = await import('./lib/fields.js')
+      // getFields is memoized per run — one defs fetch covers the whole list.
+      const resolver = makeResolver(await getFields(this.apiClient, entity))
+      data = data.map((row) =>
+        row?.custom_fields ? resolver.resolveCustomFields(row) : row,
+      )
+    }
+
     if (this.flags.jq) {
       // node-jq ships a native binary — load it only when actually used.
+      // Single records pass UNWRAPPED: `--jq .id` works on a get without
+      // the historical `.[0]` indirection (changed in 0.9.0).
       const { run } = await import('node-jq')
-      const input = JSON.stringify(Array.isArray(data) ? data : [data])
+      const input = JSON.stringify(data)
       const result = await run(this.flags.jq, input, {
         input: 'string',
         output: 'pretty',

package/src/commands/activity/list.js

@@ -56,6 +56,6 @@ export default class ActivityListCommand extends BaseCommand {
       this.apiClient.pageV2('/api/v2/activities', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'activity' })
   }
 }

package/src/commands/alias/list.js

@@ -0,0 +1,31 @@
+import BaseCommand from '../../base-command.js'
+import { getAliases } from '../../lib/aliases.js'
+
+const columns = {
+  name: { header: 'Alias' },
+  command: { header: 'Command' },
+}
+
+export default class AliasListCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'List all configured aliases'
+
+  static examples = ['<%= config.bin %> alias list']
+
+  async run() {
+    const aliases = getAliases()
+    const entries = Object.entries(aliases).map(([name, command]) => ({
+      name,
+      command,
+    }))
+
+    if (entries.length === 0) {
+      this.log('No aliases configured.')
+      this.log('Create one: pdcli alias set <name> "<command>"')
+      return
+    }
+
+    await this.outputResults(entries, columns)
+  }
+}

package/src/commands/alias/set.js

@@ -0,0 +1,97 @@
+import { Args } from '@oclif/core'
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { setAlias, getAliases } from '../../lib/aliases.js'
+import { CliError } from '../../lib/errors.js'
+
+const MAX_ALIAS_HOPS = 10
+
+export default class AliasSetCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Create or update an alias'
+
+  static examples = [
+    '<%= config.bin %> alias set wd "deal list --status won"',
+    '<%= config.bin %> alias set open "deal list --status open --limit 50"',
+  ]
+
+  static args = {
+    name: Args.string({ required: true, description: 'Alias name' }),
+    command: Args.string({ required: true, description: 'Command to alias' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(AliasSetCommand)
+    const name = args.name
+
+    // A dotted name corrupts conf's dotted-path store/read (the value would
+    // be written nested and never round-trip back as a flat alias key).
+    if (name.includes('.')) {
+      throw new CliError(
+        `Cannot create alias ${chalk.cyan(name)}: alias names may not contain '.' (dots).`,
+        { exitCode: 64 },
+      )
+    }
+
+    if (this.config.findCommand(name)) {
+      throw new CliError(
+        `Cannot create alias ${chalk.cyan(name)}: it shadows an existing pdcli command.`,
+        { exitCode: 64 },
+      )
+    }
+
+    // A name matching a topic (e.g. `deal`) is reachable by oclif's dispatcher
+    // before command-not-found fires, so the alias would never run.
+    if (this.config.findTopic(name)) {
+      throw new CliError(
+        `Cannot create alias ${chalk.cyan(name)}: it shadows an existing pdcli topic.`,
+        { exitCode: 64 },
+      )
+    }
+
+    const firstToken = args.command.split(/\s+/).filter(Boolean)[0]
+
+    // Direct self-reference: `alias set x "x ..."` loops immediately.
+    if (firstToken === name) {
+      throw new CliError(
+        `Cannot create alias ${chalk.cyan(name)}: the command refers to itself.`,
+        { exitCode: 64 },
+      )
+    }
+
+    // Transitive cycle: walk the existing alias graph from firstToken. If it
+    // leads back to `name` within MAX_ALIAS_HOPS, expanding this alias would
+    // re-enter forever.
+    const aliases = getAliases() ?? {}
+    const seen = new Set([name])
+    let token = firstToken
+    for (let hop = 0; hop < MAX_ALIAS_HOPS; hop++) {
+      if (token === name) {
+        const cycle = [...seen, name].join(' -> ')
+        throw new CliError(
+          `Cannot create alias ${chalk.cyan(name)}: it forms a cycle (${cycle}).`,
+          { exitCode: 64 },
+        )
+      }
+      const next = aliases[token]
+      if (!next) break // token is not an alias — chain terminates safely
+      if (seen.has(token)) break // pre-existing cycle not involving `name`
+      seen.add(token)
+      token = next.split(/\s+/).filter(Boolean)[0]
+    }
+
+    // Aliases run with full credentials — flag ones that hide destructive
+    // operations so a shared config can't smuggle in a silent delete.
+    if (/\b(DELETE|delete|merge)\b/.test(args.command)) {
+      process.stderr.write(
+        `${chalk.yellow('Warning:')} this alias wraps a destructive command — ` +
+          `it will run without additional confirmation prompts beyond the ` +
+          `command's own.\n`,
+      )
+    }
+
+    setAlias(name, args.command)
+    this.log(chalk.green(`Alias set: ${chalk.cyan(name)} → ${args.command}`))
+  }
+}

package/src/commands/alias/unset.js

@@ -0,0 +1,26 @@
+import { Args } from '@oclif/core'
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { getAlias, unsetAlias } from '../../lib/aliases.js'
+
+export default class AliasUnsetCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Remove an alias'
+
+  static examples = ['<%= config.bin %> alias unset wd']
+
+  static args = {
+    name: Args.string({ required: true, description: 'Alias name' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(AliasUnsetCommand)
+    if (!getAlias(args.name)) {
+      this.log(chalk.yellow(`Alias not found: ${args.name}`))
+      return
+    }
+    unsetAlias(args.name)
+    this.log(chalk.green(`Alias removed: ${args.name}`))
+  }
+}

package/src/commands/config/set.js

@@ -2,6 +2,12 @@ import { Args } from '@oclif/core'
 import chalk from 'chalk'
 import BaseCommand from '../../base-command.js'
 import { setProfileConfig } from '../../lib/config.js'
+import { CliError } from '../../lib/errors.js'
+
+/** Allowed values for keys pdcli itself consumes; others are free-form. */
+const VALIDATED_KEYS = {
+  default_output: ['table', 'json', 'yaml', 'csv'],
+}
 
 export default class ConfigSetCommand extends BaseCommand {
   static skipAuth = true
@@ -21,6 +27,14 @@ export default class ConfigSetCommand extends BaseCommand {
   async run() {
     const { args } = await this.parse(ConfigSetCommand)
 
+    const allowed = VALIDATED_KEYS[args.key]
+    if (allowed && !allowed.includes(args.value)) {
+      throw new CliError(
+        `Invalid value "${args.value}" for ${args.key} — expected one of: ${allowed.join(', ')}`,
+        { exitCode: 64 },
+      )
+    }
+
     setProfileConfig(this.activeProfile, args.key, args.value)
     this.log(
       `Set ${chalk.cyan(args.key)} = ${chalk.green(args.value)} for profile ${chalk.cyan(this.activeProfile)}`,

package/src/commands/config/unset.js

@@ -0,0 +1,32 @@
+import { Args } from '@oclif/core'
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { getProfileConfig, deleteProfileConfig } from '../../lib/config.js'
+
+export default class ConfigUnsetCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Remove a config key from the active profile'
+
+  static examples = ['<%= config.bin %> config unset default_output']
+
+  static args = {
+    key: Args.string({ required: true, description: 'Config key to remove' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(ConfigUnsetCommand)
+
+    if (getProfileConfig(this.activeProfile, args.key) === undefined) {
+      this.log(
+        `${chalk.cyan(args.key)} is not set for profile ${chalk.cyan(this.activeProfile)}`,
+      )
+      return
+    }
+
+    deleteProfileConfig(this.activeProfile, args.key)
+    this.log(
+      `Removed ${chalk.cyan(args.key)} from profile ${chalk.cyan(this.activeProfile)}`,
+    )
+  }
+}

package/src/commands/deal/list.js

@@ -57,6 +57,6 @@ export default class DealListCommand extends BaseCommand {
       this.apiClient.pageV2('/api/v2/deals', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'deal' })
   }
 }

package/src/commands/file/remote-link.js

@@ -0,0 +1,56 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { outputRecord } from '../../lib/entity-view.js'
+import { CliError } from '../../lib/errors.js'
+
+export default class FileRemoteLinkCommand extends BaseCommand {
+  static description = 'Link an existing remote file (Google Drive) to an item'
+
+  static examples = [
+    '<%= config.bin %> file remote-link --deal 42 --remote-id 1AbC',
+    '<%= config.bin %> file remote-link --person 9 --remote-id 1AbC --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    deal: Flags.integer({ description: 'Link to a deal ID' }),
+    org: Flags.integer({ description: 'Link to an organization ID' }),
+    person: Flags.integer({ description: 'Link to a person ID' }),
+    'remote-id': Flags.string({
+      required: true,
+      description: 'ID of the remote file (e.g. Google Drive file ID)',
+    }),
+    'remote-location': Flags.string({
+      description: 'Remote storage location',
+      options: ['googledrive'],
+      default: 'googledrive',
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(FileRemoteLinkCommand)
+
+    const items = [
+      ['deal', flags.deal],
+      ['organization', flags.org],
+      ['person', flags.person],
+    ].filter(([, id]) => id != null)
+
+    if (items.length !== 1) {
+      throw new CliError('Pass exactly one of --deal, --org, or --person', {
+        exitCode: 64,
+      })
+    }
+
+    const [item_type, item_id] = items[0]
+
+    const res = await this.apiClient.postForm('/api/v1/files/remoteLink', {
+      item_type,
+      item_id,
+      remote_id: flags['remote-id'],
+      remote_location: flags['remote-location'],
+    })
+
+    await outputRecord(this, res.data)
+  }
+}

package/src/commands/funnel.js

@@ -2,8 +2,13 @@ import { Flags } from '@oclif/core'
 import BaseCommand from '../base-command.js'
 import { collectPages } from '../lib/pagination.js'
 import { parsePeriod, formatApiDatetime } from '../lib/period.js'
-import { computeFunnel } from '../lib/analytics.js'
-import { CliError } from '../lib/errors.js'
+import { computeFunnel, computeExactFunnel } from '../lib/analytics.js'
+import { CliError, ApiError } from '../lib/errors.js'
+
+/** Token cost of one GET /deals/{id}/changelog request (rate-limit budget). */
+const CHANGELOG_COST = 20
+/** Above this deal count, mining gets expensive — warn before proceeding. */
+const MINE_WARN_THRESHOLD = 100
 
 export default class FunnelCommand extends BaseCommand {
   static description =
@@ -23,6 +28,14 @@ export default class FunnelCommand extends BaseCommand {
     pipeline: Flags.integer({
       description: 'Pipeline ID (required when the account has several)',
     }),
+    exact: Flags.boolean({
+      description:
+        'Mine real stage transitions from each deal’s changelog instead ' +
+        'of approximating from the final stage (one request per deal). ' +
+        '--period scopes only closed (won/lost) deals; open deals are ' +
+        'always included.',
+      default: false,
+    }),
   }
 
   async run() {
@@ -71,6 +84,36 @@ export default class FunnelCommand extends BaseCommand {
       ),
     ])
 
+    if (flags.exact) {
+      const exact = await this.mineExactFunnel(
+        [...open, ...won, ...lost],
+        stages,
+        pipelineId,
+      )
+      const columns = {
+        stage: { header: 'Stage' },
+        entered: { header: 'Entered (observed)' },
+        conversionFromPrev: {
+          // Not funnel conversion — exact entries are non-monotonic so this
+          // ratio can exceed 100%. Labelled to avoid that misreading.
+          header: 'Entered vs prev',
+          get: (row) =>
+            row.conversionFromPrev == null
+              ? ''
+              : `${(row.conversionFromPrev * 100).toFixed(0)}%`,
+        },
+      }
+      // `won` is a single total: tables report it once under the rows;
+      // machine formats carry it as a top-level field next to the rows.
+      if (this.resolveFormat() === 'table') {
+        await this.outputResults(exact.rows, columns)
+        this.log(`Won: ${exact.won}`)
+      } else {
+        await this.outputResults(exact, columns)
+      }
+      return
+    }
+
     const funnel = computeFunnel([...won, ...lost], open, stages, {
       pipelineId,
     })
@@ -89,4 +132,56 @@ export default class FunnelCommand extends BaseCommand {
       openValue: { header: 'Open value' },
     })
   }
+
+  /**
+   * Mine real stage transitions from each deal's v1 changelog. The changelog
+   * uses a flat v2-style cursor (additional_data.next_cursor on a v1 path), so
+   * the v2 pager works directly. Warns on stderr before mining a large set —
+   * each request costs 20 tokens — then lets the client's rate limiter pace it.
+   * @param {object[]} deals deals to mine (current stage_id needed per deal)
+   * @param {object[]} stages
+   * @param {number} pipelineId
+   */
+  async mineExactFunnel(deals, stages, pipelineId) {
+    if (deals.length > MINE_WARN_THRESHOLD) {
+      process.stderr.write(
+        `Mining stage history for ${deals.length} deals ` +
+          `(~${deals.length} requests, ${CHANGELOG_COST} tokens each); ` +
+          `rate limiting may slow this down.\n`,
+      )
+    }
+
+    const transitionsByDeal = []
+    let skipped = 0
+    for (const deal of deals) {
+      try {
+        const rows = await collectPages(
+          this.apiClient.pageV2(`/api/v1/deals/${deal.id}/changelog`, {
+            limit: 500,
+          }),
+        )
+        transitionsByDeal.push({
+          dealId: deal.id,
+          stageId: deal.stage_id,
+          rows,
+        })
+      } catch (err) {
+        // One bad changelog request must not abort the whole mine: skip the
+        // deal, count it, and warn once after mining completes.
+        if (err instanceof ApiError) {
+          skipped++
+          continue
+        }
+        throw err
+      }
+    }
+
+    if (skipped > 0) {
+      process.stderr.write(
+        `skipped ${skipped} deal(s) whose changelog could not be fetched\n`,
+      )
+    }
+
+    return computeExactFunnel(transitionsByDeal, stages, { pipelineId })
+  }
 }

package/src/commands/lead/label/list.js

@@ -0,0 +1,27 @@
+import BaseCommand from '../../../base-command.js'
+
+const columns = {
+  id: { header: 'ID' },
+  name: { header: 'Name' },
+  color: { header: 'Color' },
+}
+
+export default class LeadLabelListCommand extends BaseCommand {
+  static description = 'List lead labels'
+
+  static examples = [
+    '<%= config.bin %> lead label list',
+    '<%= config.bin %> lead label list --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    await this.parse(LeadLabelListCommand)
+    // leadLabels has no pagination — all labels are always returned.
+    const body = await this.apiClient.get('/api/v1/leadLabels')
+    await this.outputResults(body.data, columns)
+  }
+}