@wavyx/pdcli 0.4.0 → 0.5.0

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/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/pipeline/health.js

@@ -0,0 +1,78 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { collectPages } from '../../lib/pagination.js'
+import { computeHealth } from '../../lib/analytics.js'
+import { CliError } from '../../lib/errors.js'
+
+export default class PipelineHealthCommand extends BaseCommand {
+  static description =
+    'Per-stage pipeline health: value, weighted value, stale deals, missing next steps'
+
+  static examples = [
+    '<%= config.bin %> pipeline health',
+    '<%= config.bin %> pipeline health --pipeline 1',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    pipeline: Flags.integer({
+      description: 'Pipeline ID (required when the account has several)',
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(PipelineHealthCommand)
+    const now = new Date()
+
+    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 [stages, open, activities] = await Promise.all([
+      collectPages(
+        this.apiClient.pageV2('/api/v2/stages', {
+          pipeline_id: pipelineId,
+          limit: 500,
+        }),
+      ),
+      collectPages(
+        this.apiClient.pageV2('/api/v2/deals', {
+          pipeline_id: pipelineId,
+          status: 'open',
+          limit: 500,
+        }),
+      ),
+      collectPages(
+        this.apiClient.pageV2('/api/v2/activities', {
+          done: false,
+          limit: 500,
+        }),
+      ),
+    ])
+
+    const rows = computeHealth(open, stages, activities, { now })
+
+    await this.outputResults(rows, {
+      stage: { header: 'Stage' },
+      openCount: { header: 'Open' },
+      openValue: { header: 'Value' },
+      weightedValue: {
+        header: 'Weighted',
+        get: (row) => String(Math.round(row.weightedValue)),
+      },
+      staleCount: { header: 'Stale >14d' },
+      noNextActivityCount: { header: 'No next step' },
+      pastCloseCount: { header: 'Past close' },
+    })
+  }
+}

package/src/lib/analytics.js

@@ -0,0 +1,154 @@
+const DAY_MS = 86_400_000
+
+/**
+ * Sales Velocity Equation over a trailing window:
+ * (open opportunities × win rate × avg won value) / avg cycle days.
+ * Win rate uses the decided-deals variant: won / (won + lost) closed in
+ * the window, keyed on won_time/lost_time. Cycle = won_time − add_time.
+ * @param {object[]} deals open + closed deals (closed filtered to window here)
+ * @param {{ since: Date, now: Date }} window
+ */
+export function computeVelocity(deals, { since }) {
+  const open = deals.filter((d) => d.status === 'open')
+  const wonInPeriod = deals.filter(
+    (d) => d.status === 'won' && inWindow(d.won_time, since),
+  )
+  const lostInPeriod = deals.filter(
+    (d) => d.status === 'lost' && inWindow(d.lost_time, since),
+  )
+
+  const decided = wonInPeriod.length + lostInPeriod.length
+  const winRate = decided > 0 ? wonInPeriod.length / decided : null
+
+  const wonValues = wonInPeriod.map((d) => d.value ?? 0)
+  const avgWonValue =
+    wonInPeriod.length > 0
+      ? wonValues.reduce((a, b) => a + b, 0) / wonInPeriod.length
+      : null
+
+  const cycles = wonInPeriod.map(
+    (d) => (new Date(d.won_time) - new Date(d.add_time)) / DAY_MS,
+  )
+  const avgCycleDays =
+    cycles.length > 0 ? cycles.reduce((a, b) => a + b, 0) / cycles.length : null
+
+  const velocityPerDay =
+    winRate != null && avgWonValue != null && avgCycleDays > 0
+      ? (open.length * winRate * avgWonValue) / avgCycleDays
+      : null
+
+  return {
+    openCount: open.length,
+    wonCount: wonInPeriod.length,
+    lostCount: lostInPeriod.length,
+    winRate,
+    avgWonValue,
+    avgCycleDays,
+    velocityPerDay,
+  }
+}
+
+function inWindow(time, since) {
+  return time != null && new Date(time) >= since
+}
+
+/**
+ * Stage-reach funnel approximated from closed deals' final stages: a deal
+ * counts as having reached every stage up to (and including) its final one;
+ * won deals count for every stage. Accurate per-stage history would need
+ * per-deal flow mining (v1) — this stays one cheap list call.
+ * @param {object[]} closedDeals won/lost deals (already window-filtered)
+ * @param {object[]} openDeals current open deals
+ * @param {object[]} stages v2 stages (order_nr, pipeline_id)
+ * @param {{ pipelineId?: number }} [options]
+ */
+export function computeFunnel(closedDeals, openDeals, stages, options = {}) {
+  const ordered = stages
+    .filter(
+      (s) => options.pipelineId == null || s.pipeline_id === options.pipelineId,
+    )
+    .sort((a, b) => a.order_nr - b.order_nr)
+
+  const orderByStageId = new Map(ordered.map((s, i) => [s.id, i]))
+
+  function finalIndex(deal) {
+    if (deal.status === 'won') return ordered.length - 1
+    return orderByStageId.get(deal.stage_id) ?? -1
+  }
+
+  return ordered.map((stage, index) => {
+    const reached = closedDeals.filter((d) => finalIndex(d) >= index).length
+    const openHere = openDeals.filter((d) => d.stage_id === stage.id)
+    const prevReached =
+      index > 0
+        ? closedDeals.filter((d) => finalIndex(d) >= index - 1).length
+        : null
+
+    return {
+      stage: stage.name,
+      stageId: stage.id,
+      reached,
+      conversionFromPrev:
+        index > 0 && prevReached > 0 ? reached / prevReached : null,
+      openCount: openHere.length,
+      openValue: openHere.reduce((sum, d) => sum + (d.value ?? 0), 0),
+    }
+  })
+}
+
+const STALE_DAYS = 14
+
+/**
+ * Per-stage pipeline health snapshot: open count/value, probability-weighted
+ * value (deal probability wins over stage default), stale deals (>14 days
+ * without update), deals without a future open activity, and deals past
+ * their expected close date.
+ * @param {object[]} deals open deals
+ * @param {object[]} stages
+ * @param {object[]} activities open+done activities for those deals
+ * @param {{ now: Date }} options
+ */
+export function computeHealth(deals, stages, activities, { now }) {
+  const open = deals.filter((d) => d.status === 'open')
+  const today = now.toISOString().slice(0, 10)
+
+  const dealsWithFutureActivity = new Set(
+    activities
+      .filter((a) => !a.done && a.due_date >= today && a.deal_id != null)
+      .map((a) => a.deal_id),
+  )
+
+  const ordered = [...stages].sort((a, b) => a.order_nr - b.order_nr)
+
+  return ordered.map((stage) => {
+    const inStage = open.filter((d) => d.stage_id === stage.id)
+
+    const weightedValue = inStage.reduce((sum, d) => {
+      const probability = d.probability ?? stage.deal_probability ?? 100
+      return sum + ((d.value ?? 0) * probability) / 100
+    }, 0)
+
+    const staleCount = inStage.filter(
+      (d) => now - new Date(d.update_time) > STALE_DAYS * DAY_MS,
+    ).length
+
+    const noNextActivityCount = inStage.filter(
+      (d) => !dealsWithFutureActivity.has(d.id),
+    ).length
+
+    const pastCloseCount = inStage.filter(
+      (d) => d.expected_close_date != null && d.expected_close_date < today,
+    ).length
+
+    return {
+      stage: stage.name,
+      stageId: stage.id,
+      openCount: inStage.length,
+      openValue: inStage.reduce((sum, d) => sum + (d.value ?? 0), 0),
+      weightedValue,
+      staleCount,
+      noNextActivityCount,
+      pastCloseCount,
+    }
+  })
+}