@wavyx/pdcli 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavyx/pdcli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },

package/src/commands/audit.js

@@ -0,0 +1,137 @@
+import { Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import BaseCommand from '../base-command.js'
+import { collectPages } from '../lib/pagination.js'
+import { runChecks, AUDIT_CHECKS } from '../lib/audit.js'
+import { CliError } from '../lib/errors.js'
+
+export default class AuditCommand extends BaseCommand {
+  static description =
+    'Data-quality audit: stale deals, missing fields, duplicates, overdue pileups'
+
+  static examples = [
+    '<%= config.bin %> audit',
+    '<%= config.bin %> audit --checks stale-deals,duplicate-persons --verbose',
+    '<%= config.bin %> audit --strict   # exit 1 on must-severity findings (CI)',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    checks: Flags.string({
+      description: `Comma-separated subset of checks (${AUDIT_CHECKS.map((c) => c.name).join(', ')})`,
+    }),
+    strict: Flags.boolean({
+      description: 'Exit 1 when any must-severity check has findings',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(AuditCommand)
+    const now = new Date()
+
+    const only = flags.checks?.split(',').map((c) => c.trim())
+    if (only) {
+      const known = new Set(AUDIT_CHECKS.map((c) => c.name))
+      const bad = only.filter((c) => !known.has(c))
+      if (bad.length > 0) {
+        throw new CliError(
+          `Unknown check${bad.length > 1 ? 's' : ''}: ${bad.join(', ')}. ` +
+            `Valid: ${[...known].join(', ')}`,
+          { exitCode: 64 },
+        )
+      }
+    }
+
+    const spinner = ora('Fetching account data...').start()
+    let data
+    try {
+      // v2 has no all_not_deleted status — fetch the three states separately.
+      const [open, won, lost, persons, organizations, activities] =
+        await Promise.all([
+          collectPages(
+            this.apiClient.pageV2('/api/v2/deals', {
+              status: 'open',
+              limit: 500,
+            }),
+          ),
+          collectPages(
+            this.apiClient.pageV2('/api/v2/deals', {
+              status: 'won',
+              limit: 500,
+            }),
+          ),
+          collectPages(
+            this.apiClient.pageV2('/api/v2/deals', {
+              status: 'lost',
+              limit: 500,
+            }),
+          ),
+          collectPages(
+            this.apiClient.pageV2('/api/v2/persons', { limit: 500 }),
+          ),
+          collectPages(
+            this.apiClient.pageV2('/api/v2/organizations', { limit: 500 }),
+          ),
+          collectPages(
+            this.apiClient.pageV2('/api/v2/activities', { limit: 500 }),
+          ),
+        ])
+      data = {
+        deals: [...open, ...won, ...lost],
+        persons,
+        organizations,
+        activities,
+      }
+    } finally {
+      spinner.stop()
+    }
+
+    const results = runChecks(data, { now, only })
+
+    if (this.resolveFormat() === 'table') {
+      await this.outputResults(results, {
+        severity: {
+          header: 'Sev',
+          get: (row) => (row.severity === 'must' ? '●' : '○'),
+        },
+        title: { header: 'Check' },
+        count: {
+          header: 'Findings',
+          get: (row) =>
+            row.count === 0
+              ? chalk.green('0')
+              : chalk.yellow(String(row.count)),
+        },
+      })
+      if (this.flags.verbose) {
+        for (const result of results.filter((r) => r.count > 0)) {
+          this.log('')
+          this.log(chalk.bold(result.title))
+          for (const item of result.items.slice(0, 25)) {
+            this.log(`  ${JSON.stringify(item)}`)
+          }
+          if (result.items.length > 25) {
+            this.log(chalk.dim(`  … ${result.items.length - 25} more`))
+          }
+        }
+      }
+    } else {
+      await this.outputResults(results, {})
+    }
+
+    if (flags.strict) {
+      const mustHits = results.filter(
+        (r) => r.severity === 'must' && r.count > 0,
+      )
+      if (mustHits.length > 0) {
+        throw new CliError(
+          `${mustHits.length} must-severity check${mustHits.length > 1 ? 's' : ''} ` +
+            `found issues: ${mustHits.map((r) => r.name).join(', ')}`,
+          { exitCode: 1 },
+        )
+      }
+    }
+  }
+}

package/src/commands/deal/bulk-update.js

@@ -0,0 +1,131 @@
+import { Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import BaseCommand from '../../base-command.js'
+import { resolveTargets, bulkRun } from '../../lib/bulk.js'
+import { buildWriteBody } from '../../lib/input.js'
+import { defsForFields } from '../../lib/entity-view.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { CliError } from '../../lib/errors.js'
+
+export default class DealBulkUpdateCommand extends BaseCommand {
+  static description =
+    'Update many deals at once (by --ids, a saved --filter, or ids piped on stdin)'
+
+  static examples = [
+    '<%= config.bin %> deal bulk-update --ids 1,2,3 --stage 5',
+    '<%= config.bin %> deal bulk-update --filter 9 --status won',
+    "<%= config.bin %> deal list --status open --jq '.[].id' | <%= config.bin %> deal bulk-update --owner 42",
+    '<%= config.bin %> deal bulk-update --filter 9 --stage 5 --dry-run',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    ids: Flags.string({
+      description: 'Comma-separated deal IDs',
+      exclusive: ['filter'],
+    }),
+    filter: Flags.integer({
+      description: 'Pipedrive saved filter ID to select deals',
+      exclusive: ['ids'],
+    }),
+    stage: Flags.integer({ description: 'Move to stage ID' }),
+    pipeline: Flags.integer({ description: 'Move to pipeline ID' }),
+    status: Flags.string({
+      description: 'Set status',
+      options: ['open', 'won', 'lost'],
+    }),
+    owner: Flags.integer({ description: 'Assign owner (user) ID' }),
+    field: Flags.string({
+      multiple: true,
+      description: 'Custom/standard field as "Name=Value" (repeatable)',
+    }),
+    body: Flags.string({ description: 'Raw JSON body to merge (flags win)' }),
+    'dry-run': Flags.boolean({
+      description: 'List the targets without updating anything',
+      default: false,
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(DealBulkUpdateCommand)
+
+    const body = buildWriteBody({
+      typed: {
+        stage_id: flags.stage,
+        pipeline_id: flags.pipeline,
+        status: flags.status,
+        owner_id: flags.owner,
+      },
+      fields: flags.field,
+      rawBody: flags.body,
+      defs: await defsForFields(this, 'deal', flags.field),
+    })
+
+    if (Object.keys(body).length === 0) {
+      throw new CliError(
+        'Nothing to update — pass at least one change flag, --field, or --body',
+        { exitCode: 64 },
+      )
+    }
+
+    const targets = await resolveTargets(
+      { ids: flags.ids, filter: flags.filter },
+      this.apiClient,
+      '/api/v2/deals',
+    )
+
+    if (flags['dry-run']) {
+      this.log(
+        `Would update ${chalk.bold(targets.length)} deals: ${targets.join(', ')}`,
+      )
+      this.log(chalk.dim(`Change: ${JSON.stringify(body)}`))
+      return
+    }
+
+    const ok = await confirmAction(
+      `Update ${targets.length} deals with ${JSON.stringify(body)}?`,
+      flags.yes,
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    const spinner = ora(`Updating ${targets.length} deals...`).start()
+    let summary
+    try {
+      summary = await bulkRun(
+        targets,
+        (id) => this.apiClient.patch(`/api/v2/deals/${id}`, { body }),
+        {
+          onProgress: (done, total) => {
+            spinner.text = `Updating deals ${done}/${total}`
+          },
+        },
+      )
+    } finally {
+      spinner.stop()
+    }
+
+    this.log(
+      chalk.green(
+        `Updated ${summary.succeeded.length}/${targets.length} deals`,
+      ),
+    )
+
+    if (summary.failed.length > 0) {
+      for (const { item, error } of summary.failed) {
+        this.log(chalk.red(`  ✘ deal ${item}: ${error}`))
+      }
+      throw new CliError(
+        `${summary.failed.length} of ${targets.length} updates failed`,
+        { exitCode: 1 },
+      )
+    }
+  }
+}

package/src/commands/funnel.js

@@ -0,0 +1,92 @@
+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'
+
+export default class FunnelCommand extends BaseCommand {
+  static description =
+    'Stage-to-stage conversion approximated from closed deals (final stage reached)'
+
+  static examples = [
+    '<%= config.bin %> funnel',
+    '<%= config.bin %> funnel --pipeline 1 --period 180d',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    period: Flags.string({
+      description: 'Trailing window for closed deals (Nd or Nm)',
+      default: '90d',
+    }),
+    pipeline: Flags.integer({
+      description: 'Pipeline ID (required when the account has several)',
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(FunnelCommand)
+    const now = new Date()
+    const since = parsePeriod(flags.period, now)
+
+    let pipelineId = flags.pipeline
+    if (pipelineId == null) {
+      const body = await this.apiClient.get('/api/v2/pipelines')
+      const pipelines = body.data ?? []
+      if (pipelines.length > 1) {
+        throw new CliError(
+          `Account has ${pipelines.length} pipelines — pass --pipeline <id> ` +
+            `(${pipelines.map((p) => `${p.id}=${p.name}`).join(', ')})`,
+          { exitCode: 64 },
+        )
+      }
+      pipelineId = pipelines[0]?.id
+    }
+
+    const base = { pipeline_id: pipelineId, limit: 500 }
+    const [stages, open, won, lost] = await Promise.all([
+      collectPages(
+        this.apiClient.pageV2('/api/v2/stages', {
+          pipeline_id: pipelineId,
+          limit: 500,
+        }),
+      ),
+      collectPages(
+        this.apiClient.pageV2('/api/v2/deals', { ...base, status: 'open' }),
+      ),
+      collectPages(
+        this.apiClient.pageV2('/api/v2/deals', {
+          ...base,
+          status: 'won',
+          updated_since: formatApiDatetime(since),
+        }),
+      ),
+      collectPages(
+        this.apiClient.pageV2('/api/v2/deals', {
+          ...base,
+          status: 'lost',
+          updated_since: formatApiDatetime(since),
+        }),
+      ),
+    ])
+
+    const funnel = computeFunnel([...won, ...lost], open, stages, {
+      pipelineId,
+    })
+
+    await this.outputResults(funnel, {
+      stage: { header: 'Stage' },
+      reached: { header: `Reached (closed, ${flags.period})` },
+      conversionFromPrev: {
+        header: 'Conv. from prev',
+        get: (row) =>
+          row.conversionFromPrev == null
+            ? ''
+            : `${(row.conversionFromPrev * 100).toFixed(0)}%`,
+      },
+      openCount: { header: 'Open now' },
+      openValue: { header: 'Open value' },
+    })
+  }
+}

package/src/commands/metrics/velocity.js

@@ -0,0 +1,81 @@
+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 { computeVelocity } from '../../lib/analytics.js'
+
+export default class MetricsVelocityCommand extends BaseCommand {
+  static description =
+    'Sales Velocity Equation: (open × win rate × avg won value) / cycle days'
+
+  static examples = [
+    '<%= config.bin %> metrics velocity',
+    '<%= config.bin %> metrics velocity --period 30d --pipeline 1',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    period: Flags.string({
+      description: 'Trailing window for closed deals (Nd or Nm)',
+      default: '90d',
+    }),
+    pipeline: Flags.integer({ description: 'Restrict to a pipeline ID' }),
+    owner: Flags.integer({ description: 'Restrict to an owner (user) ID' }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(MetricsVelocityCommand)
+    const now = new Date()
+    const since = parsePeriod(flags.period, now)
+
+    const base = {
+      pipeline_id: flags.pipeline,
+      owner_id: flags.owner,
+      limit: 500,
+    }
+    const [open, won, lost] = await Promise.all([
+      collectPages(
+        this.apiClient.pageV2('/api/v2/deals', { ...base, status: 'open' }),
+      ),
+      collectPages(
+        this.apiClient.pageV2('/api/v2/deals', {
+          ...base,
+          status: 'won',
+          updated_since: formatApiDatetime(since),
+        }),
+      ),
+      collectPages(
+        this.apiClient.pageV2('/api/v2/deals', {
+          ...base,
+          status: 'lost',
+          updated_since: formatApiDatetime(since),
+        }),
+      ),
+    ])
+
+    const velocity = computeVelocity([...open, ...won, ...lost], { since, now })
+
+    if (this.resolveFormat() === 'table') {
+      const fmt = (v, digits = 1) => (v == null ? 'n/a' : v.toFixed(digits))
+      await this.outputResults(
+        [
+          { metric: 'Open opportunities', value: String(velocity.openCount) },
+          {
+            metric: `Win rate (${flags.period})`,
+            value:
+              velocity.winRate == null
+                ? 'n/a'
+                : `${(velocity.winRate * 100).toFixed(1)}% (${velocity.wonCount}W/${velocity.lostCount}L)`,
+          },
+          { metric: 'Avg won value', value: fmt(velocity.avgWonValue, 0) },
+          { metric: 'Avg cycle (days)', value: fmt(velocity.avgCycleDays) },
+          { metric: 'Velocity / day', value: fmt(velocity.velocityPerDay, 0) },
+        ],
+        { metric: { header: 'Metric' }, value: { header: 'Value' } },
+      )
+      return
+    }
+
+    await this.outputResults(velocity, {})
+  }
+}

package/src/commands/org/import.js

@@ -0,0 +1,109 @@
+import { readFileSync } from 'node:fs'
+import { Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import BaseCommand from '../../base-command.js'
+import { parseCsv } from '../../lib/csv-parse.js'
+import { prepareImportBodies } from '../../lib/import.js'
+import { bulkRun } from '../../lib/bulk.js'
+import { getFields } from '../../lib/fields.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { CliError } from '../../lib/errors.js'
+
+const SPECIAL_COLUMNS = {
+  name: (typed, value) => {
+    typed.name = value
+  },
+  owner_id: (typed, value) => {
+    typed.owner_id = Number(value)
+  },
+}
+
+export default class OrgImportCommand extends BaseCommand {
+  static description =
+    'Bulk-create organizations from a CSV (headers map to fields, custom fields by name)'
+
+  static examples = [
+    '<%= config.bin %> org import orgs.csv',
+    '<%= config.bin %> org import orgs.csv --dry-run',
+  ]
+
+  static args = {
+    file: Args.string({ required: true, description: 'CSV file path' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    'dry-run': Flags.boolean({
+      description: 'Validate every row without creating anything',
+      default: false,
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(OrgImportCommand)
+
+    const { headers, rows } = parseCsv(readFileSync(args.file, 'utf8'))
+    if (!headers.some((h) => h.toLowerCase() === 'name')) {
+      throw new CliError('CSV must include a "name" column', { exitCode: 64 })
+    }
+
+    const needsDefs = headers.some((h) => !(h.toLowerCase() in SPECIAL_COLUMNS))
+    const bodies = prepareImportBodies({
+      headers,
+      rows,
+      specialColumns: SPECIAL_COLUMNS,
+      defs: needsDefs ? await getFields(this.apiClient, 'org') : [],
+    })
+
+    if (flags['dry-run']) {
+      this.log(chalk.green(`${bodies.length} rows valid — nothing created`))
+      return
+    }
+
+    const ok = await confirmAction(
+      `Create ${bodies.length} organizations from ${args.file}?`,
+      flags.yes,
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    const spinner = ora(`Importing ${bodies.length} organizations...`).start()
+    let summary
+    try {
+      summary = await bulkRun(
+        bodies,
+        (body) => this.apiClient.post('/api/v2/organizations', { body }),
+        {
+          onProgress: (done, total) => {
+            spinner.text = `Importing organizations ${done}/${total}`
+          },
+        },
+      )
+    } finally {
+      spinner.stop()
+    }
+
+    this.log(
+      chalk.green(
+        `Imported ${summary.succeeded.length}/${bodies.length} organizations`,
+      ),
+    )
+
+    if (summary.failed.length > 0) {
+      for (const { item, error } of summary.failed) {
+        this.log(chalk.red(`  ✘ ${item.name ?? '(unnamed)'}: ${error}`))
+      }
+      throw new CliError(
+        `${summary.failed.length} of ${bodies.length} rows failed`,
+        { exitCode: 1 },
+      )
+    }
+  }
+}

package/src/commands/person/import.js

@@ -0,0 +1,118 @@
+import { readFileSync } from 'node:fs'
+import { Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import ora from 'ora'
+import BaseCommand from '../../base-command.js'
+import { parseCsv } from '../../lib/csv-parse.js'
+import { prepareImportBodies } from '../../lib/import.js'
+import { bulkRun } from '../../lib/bulk.js'
+import { getFields } from '../../lib/fields.js'
+import { confirmAction } from '../../lib/confirm.js'
+import { CliError } from '../../lib/errors.js'
+
+const SPECIAL_COLUMNS = {
+  name: (typed, value) => {
+    typed.name = value
+  },
+  email: (typed, value) => {
+    typed.emails = [{ value, primary: true }]
+  },
+  phone: (typed, value) => {
+    typed.phones = [{ value, primary: true }]
+  },
+  org_id: (typed, value) => {
+    typed.org_id = Number(value)
+  },
+  owner_id: (typed, value) => {
+    typed.owner_id = Number(value)
+  },
+}
+
+export default class PersonImportCommand extends BaseCommand {
+  static description =
+    'Bulk-create persons from a CSV (headers map to fields, custom fields by name)'
+
+  static examples = [
+    '<%= config.bin %> person import people.csv',
+    '<%= config.bin %> person import people.csv --dry-run',
+  ]
+
+  static args = {
+    file: Args.string({ required: true, description: 'CSV file path' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    'dry-run': Flags.boolean({
+      description: 'Validate every row without creating anything',
+      default: false,
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(PersonImportCommand)
+
+    const { headers, rows } = parseCsv(readFileSync(args.file, 'utf8'))
+    if (!headers.some((h) => h.toLowerCase() === 'name')) {
+      throw new CliError('CSV must include a "name" column', { exitCode: 64 })
+    }
+
+    const needsDefs = headers.some((h) => !(h.toLowerCase() in SPECIAL_COLUMNS))
+    const bodies = prepareImportBodies({
+      headers,
+      rows,
+      specialColumns: SPECIAL_COLUMNS,
+      defs: needsDefs ? await getFields(this.apiClient, 'person') : [],
+    })
+
+    if (flags['dry-run']) {
+      this.log(chalk.green(`${bodies.length} rows valid — nothing created`))
+      return
+    }
+
+    const ok = await confirmAction(
+      `Create ${bodies.length} persons from ${args.file}?`,
+      flags.yes,
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    const spinner = ora(`Importing ${bodies.length} persons...`).start()
+    let summary
+    try {
+      summary = await bulkRun(
+        bodies,
+        (body) => this.apiClient.post('/api/v2/persons', { body }),
+        {
+          onProgress: (done, total) => {
+            spinner.text = `Importing persons ${done}/${total}`
+          },
+        },
+      )
+    } finally {
+      spinner.stop()
+    }
+
+    this.log(
+      chalk.green(
+        `Imported ${summary.succeeded.length}/${bodies.length} persons`,
+      ),
+    )
+
+    if (summary.failed.length > 0) {
+      for (const { item, error } of summary.failed) {
+        this.log(chalk.red(`  ✘ ${item.name ?? '(unnamed)'}: ${error}`))
+      }
+      throw new CliError(
+        `${summary.failed.length} of ${bodies.length} rows failed`,
+        { exitCode: 1 },
+      )
+    }
+  }
+}