@wavyx/pdcli 0.3.0 → 0.5.0

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,
+    }
+  })
+}

package/src/lib/audit.js

@@ -0,0 +1,228 @@
+const DAY_MS = 86_400_000
+const STALE_DAYS = 14
+const ANCIENT_FALLBACK_DAYS = 168 // ~2× the median B2B cycle
+const ANCIENT_CYCLE_MULTIPLIER = 2
+
+function openDeals(data) {
+  return data.deals.filter((d) => d.status === 'open')
+}
+
+function today(now) {
+  return now.toISOString().slice(0, 10)
+}
+
+/**
+ * Data-quality checks. Each returns flagged items; detection rules follow
+ * common RevOps hygiene practice (see docs for thresholds).
+ * @type {{ name: string, severity: 'must' | 'should', title: string, run: (data: object, ctx: { now: Date }) => object[] }[]}
+ */
+export const AUDIT_CHECKS = [
+  {
+    name: 'stale-deals',
+    severity: 'must',
+    title: `Open deals untouched for >${STALE_DAYS} days`,
+    run: (data, { now }) =>
+      openDeals(data)
+        .filter((d) => now - new Date(d.update_time) > STALE_DAYS * DAY_MS)
+        .map((d) => ({
+          id: d.id,
+          title: d.title,
+          days: Math.floor((now - new Date(d.update_time)) / DAY_MS),
+        })),
+  },
+  {
+    name: 'no-next-activity',
+    severity: 'must',
+    title: 'Open deals with no future activity scheduled',
+    run: (data, { now }) => {
+      const withFuture = new Set(
+        data.activities
+          .filter(
+            (a) => !a.done && a.due_date >= today(now) && a.deal_id != null,
+          )
+          .map((a) => a.deal_id),
+      )
+      return openDeals(data)
+        .filter((d) => !withFuture.has(d.id))
+        .map((d) => ({ id: d.id, title: d.title }))
+    },
+  },
+  {
+    name: 'past-close-date',
+    severity: 'must',
+    title: 'Open deals past their expected close date',
+    run: (data, { now }) =>
+      openDeals(data)
+        .filter(
+          (d) =>
+            d.expected_close_date != null && d.expected_close_date < today(now),
+        )
+        .map((d) => ({
+          id: d.id,
+          title: d.title,
+          expected_close_date: d.expected_close_date,
+        })),
+  },
+  {
+    name: 'missing-fields',
+    severity: 'must',
+    title: 'Open deals missing owner, person/org, value, or currency',
+    run: (data) =>
+      openDeals(data)
+        .map((d) => {
+          const missing = []
+          if (d.owner_id == null) missing.push('owner')
+          if (d.person_id == null && d.org_id == null)
+            missing.push('person/org')
+          if (d.value == null || d.value <= 0) missing.push('value')
+          else if (!d.currency) missing.push('currency')
+          return { id: d.id, title: d.title, missing }
+        })
+        .filter((item) => item.missing.length > 0),
+  },
+  {
+    name: 'ancient-deals',
+    severity: 'must',
+    title: 'Open deals far older than the typical won cycle',
+    run: (data, { now }) => {
+      const cycles = data.deals
+        .filter((d) => d.status === 'won' && d.won_time && d.add_time)
+        .map((d) => (new Date(d.won_time) - new Date(d.add_time)) / DAY_MS)
+      const avgCycle =
+        cycles.length > 0
+          ? cycles.reduce((a, b) => a + b, 0) / cycles.length
+          : null
+      const thresholdDays =
+        avgCycle != null
+          ? avgCycle * ANCIENT_CYCLE_MULTIPLIER
+          : ANCIENT_FALLBACK_DAYS
+      return openDeals(data)
+        .filter((d) => now - new Date(d.add_time) > thresholdDays * DAY_MS)
+        .map((d) => ({
+          id: d.id,
+          title: d.title,
+          ageDays: Math.floor((now - new Date(d.add_time)) / DAY_MS),
+          thresholdDays: Math.round(thresholdDays),
+        }))
+    },
+  },
+  {
+    name: 'missing-close-time',
+    severity: 'should',
+    title: 'Closed deals missing their close timestamp',
+    run: (data) =>
+      data.deals
+        .filter(
+          (d) =>
+            (d.status === 'won' && d.won_time == null) ||
+            (d.status === 'lost' && d.lost_time == null),
+        )
+        .map((d) => ({ id: d.id, title: d.title, status: d.status })),
+  },
+  {
+    name: 'duplicate-persons',
+    severity: 'must',
+    title: 'Persons sharing the same email',
+    run: (data) => {
+      const byEmail = new Map()
+      for (const person of data.persons) {
+        for (const entry of person.emails ?? []) {
+          const email = entry.value?.trim().toLowerCase()
+          if (!email) continue
+          byEmail.set(email, [...(byEmail.get(email) ?? []), person.id])
+        }
+      }
+      return [...byEmail.entries()]
+        .filter(([, ids]) => new Set(ids).size > 1)
+        .map(([email, ids]) => ({ email, ids: [...new Set(ids)] }))
+    },
+  },
+  {
+    name: 'uncontactable-persons',
+    severity: 'must',
+    title: 'Persons with neither email nor phone',
+    run: (data) =>
+      data.persons
+        .filter(
+          (p) =>
+            !(p.emails ?? []).some((e) => e.value) &&
+            !(p.phones ?? []).some((ph) => ph.value),
+        )
+        .map((p) => ({ id: p.id, name: p.name })),
+  },
+  {
+    name: 'duplicate-orgs',
+    severity: 'should',
+    title: 'Organizations with the same normalized name',
+    run: (data) => {
+      const byName = new Map()
+      for (const org of data.organizations) {
+        const key = normalizeOrgName(org.name)
+        if (!key) continue
+        byName.set(key, [...(byName.get(key) ?? []), org.id])
+      }
+      return [...byName.entries()]
+        .filter(([, ids]) => ids.length > 1)
+        .map(([name, ids]) => ({ name, ids }))
+    },
+  },
+  {
+    name: 'overdue-activities',
+    severity: 'should',
+    title: 'Overdue open activities piling up per owner',
+    run: (data, { now }) => {
+      const byOwner = new Map()
+      for (const activity of data.activities) {
+        if (activity.done || activity.due_date >= today(now)) continue
+        byOwner.set(
+          activity.owner_id,
+          (byOwner.get(activity.owner_id) ?? 0) + 1,
+        )
+      }
+      return [...byOwner.entries()].map(([owner_id, overdue]) => ({
+        owner_id,
+        overdue,
+      }))
+    },
+  },
+  {
+    name: 'currency-missing',
+    severity: 'should',
+    title: 'Deals with a value but no currency',
+    run: (data) =>
+      openDeals(data)
+        .filter((d) => d.value != null && d.value > 0 && !d.currency)
+        .map((d) => ({ id: d.id, title: d.title, value: d.value })),
+  },
+]
+
+function normalizeOrgName(name) {
+  return (name ?? '')
+    .toLowerCase()
+    .replace(/\b(inc|ltd|llc|gmbh|sa|sarl|bv|corp|co)\b\.?/g, '')
+    .replace(/[^a-z0-9]/g, '')
+}
+
+/**
+ * Run all (or a subset of) hygiene checks over pre-fetched account data.
+ * @param {{ deals: object[], persons: object[], organizations: object[], activities: object[] }} data
+ * @param {{ now: Date, only?: string[] }} options
+ * @returns {{ name: string, severity: string, title: string, count: number, items: object[] }[]}
+ */
+export function runChecks(data, { now, only } = {}) {
+  return AUDIT_CHECKS.filter((check) => !only || only.includes(check.name)).map(
+    (check) => {
+      const overdueTotal = check.name === 'overdue-activities'
+      const items = check.run(data, { now })
+      return {
+        name: check.name,
+        severity: check.severity,
+        title: check.title,
+        count: overdueTotal
+          ? items.reduce((sum, i) => sum + i.overdue, 0)
+          : items.length,
+        items,
+      }
+    },
+  )
+}

package/src/lib/bulk.js

@@ -0,0 +1,106 @@
+import createDebug from 'debug'
+import { CliError } from './errors.js'
+
+const debug = createDebug('pd:bulk')
+
+/**
+ * Resolve the target ids for a bulk operation from exactly one selector:
+ * --ids "1,2,3", a Pipedrive saved filter (--filter <id>), or piped stdin
+ * (newline-separated ids, a JSON array of ids, or JSON objects with an id).
+ * @param {object} selectors
+ * @param {string} [selectors.ids]
+ * @param {number} [selectors.filter]
+ * @param {NodeJS.ReadStream} [selectors.stdin] defaults to process.stdin
+ * @param {ReturnType<import('./client.js').createClient>} client
+ * @param {string} listPath v2 list endpoint supporting filter_id (e.g. /api/v2/deals)
+ * @returns {Promise<number[]>}
+ */
+export async function resolveTargets(
+  { ids, filter, stdin = process.stdin },
+  client,
+  listPath,
+) {
+  if (ids) {
+    return ids.split(',').map(parseId)
+  }
+
+  if (filter != null) {
+    debug('resolving targets from filter %d', filter)
+    const targets = []
+    for await (const item of client.pageV2(listPath, {
+      filter_id: filter,
+      limit: 500,
+    })) {
+      targets.push(item.id)
+    }
+    return targets
+  }
+
+  if (!stdin.isTTY) {
+    const chunks = []
+    for await (const chunk of stdin) chunks.push(chunk)
+    const text = Buffer.concat(chunks).toString('utf8').trim()
+    if (text.startsWith('[')) {
+      const parsed = JSON.parse(text)
+      return parsed.map((entry) =>
+        typeof entry === 'object' ? entry.id : parseId(String(entry)),
+      )
+    }
+    return text.split('\n').map(parseId)
+  }
+
+  throw new CliError(
+    'No targets — pass --ids, --filter, or pipe ids on stdin',
+    { exitCode: 64 },
+  )
+}
+
+function parseId(raw) {
+  const id = Number(raw.trim())
+  if (!Number.isInteger(id)) {
+    throw new CliError(`Invalid id "${raw.trim()}" — expected an integer`, {
+      exitCode: 64,
+    })
+  }
+  return id
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Run an async operation per item, sequentially with a pacing gap so bulk
+ * writes stay inside Pipedrive's 2-second burst window (writes cost 10
+ * tokens each; the client's 429 backoff covers anything that slips through).
+ * Per-item failures are collected, never thrown.
+ * @template T
+ * @param {T[]} items
+ * @param {(item: T) => Promise<unknown>} operation
+ * @param {object} [options]
+ * @param {number} [options.gapMs] delay between requests (default 200)
+ * @param {(done: number, total: number) => void} [options.onProgress]
+ * @returns {Promise<{ succeeded: { item: T, result: unknown }[], failed: { item: T, error: string }[] }>}
+ */
+export async function bulkRun(
+  items,
+  operation,
+  { gapMs = 200, onProgress } = {},
+) {
+  const succeeded = []
+  const failed = []
+
+  for (const [index, item] of items.entries()) {
+    if (index > 0 && gapMs > 0) await sleep(gapMs)
+    try {
+      const result = await operation(item)
+      succeeded.push({ item, result })
+    } catch (err) {
+      debug('bulk item %o failed: %s', item, err.message)
+      failed.push({ item, error: err.message })
+    }
+    onProgress?.(index + 1, items.length)
+  }
+
+  return { succeeded, failed }
+}

package/src/lib/csv-parse.js

@@ -0,0 +1,88 @@
+import { CliError } from './errors.js'
+
+/**
+ * Minimal RFC 4180 CSV parser (quoted fields, escaped quotes, embedded
+ * commas/newlines, CRLF). First record is the header row.
+ * @param {string} text
+ * @returns {{ headers: string[], rows: string[][] }}
+ */
+export function parseCsv(text) {
+  const records = []
+  let record = []
+  let field = ''
+  let inQuotes = false
+  let i = 0
+
+  while (i < text.length) {
+    const char = text[i]
+
+    if (inQuotes) {
+      if (char === '"') {
+        if (text[i + 1] === '"') {
+          field += '"'
+          i += 2
+          continue
+        }
+        inQuotes = false
+        i++
+        continue
+      }
+      field += char
+      i++
+      continue
+    }
+
+    if (char === '"') {
+      inQuotes = true
+      i++
+      continue
+    }
+    if (char === ',') {
+      record.push(field)
+      field = ''
+      i++
+      continue
+    }
+    if (char === '\n' || char === '\r') {
+      if (char === '\r' && text[i + 1] === '\n') i++
+      record.push(field)
+      field = ''
+      if (record.length > 1 || record[0] !== '') records.push(record)
+      record = []
+      i++
+      continue
+    }
+    field += char
+    i++
+  }
+
+  if (inQuotes) {
+    throw new CliError('Unterminated quoted field in CSV', { exitCode: 65 })
+  }
+  if (field !== '' || record.length > 0) {
+    // A tail record only reaches here when non-empty (a bare trailing
+    // newline never starts a record), so push unconditionally.
+    record.push(field)
+    records.push(record)
+  }
+
+  if (records.length === 0) {
+    throw new CliError('CSV file is empty', { exitCode: 65 })
+  }
+
+  const [headers, ...rows] = records
+
+  return {
+    headers,
+    rows: rows.map((row, index) => {
+      if (row.length > headers.length) {
+        throw new CliError(
+          `CSV row ${index + 2} has ${row.length} cells but the header has ${headers.length}`,
+          { exitCode: 65 },
+        )
+      }
+      while (row.length < headers.length) row.push('')
+      return row
+    }),
+  }
+}

package/src/lib/import.js

@@ -0,0 +1,49 @@
+import { buildWriteBody } from './input.js'
+import { CliError } from './errors.js'
+
+/**
+ * Turn parsed CSV rows into write bodies. Special columns (matched
+ * case-insensitively) build typed values; every other header resolves
+ * through the entity's field definitions — names, hash keys, and option
+ * labels included. Empty cells are skipped.
+ * @param {object} options
+ * @param {string[]} options.headers
+ * @param {string[][]} options.rows
+ * @param {Record<string, (typed: object, value: string) => void>} [options.specialColumns]
+ * @param {object[]} [options.defs] field definitions for non-special headers
+ * @returns {object[]} one request body per row
+ */
+export function prepareImportBodies({
+  headers,
+  rows,
+  specialColumns = {},
+  defs,
+}) {
+  const specials = Object.fromEntries(
+    Object.entries(specialColumns).map(([k, v]) => [k.toLowerCase(), v]),
+  )
+
+  return rows.map((row, index) => {
+    const typed = {}
+    const fields = []
+
+    headers.forEach((header, i) => {
+      const value = row[i]
+      if (value === '') return
+      const special = specials[header.toLowerCase()]
+      if (special) {
+        special(typed, value)
+        return
+      }
+      fields.push(`${header}=${value}`)
+    })
+
+    try {
+      return buildWriteBody({ typed, fields, defs })
+    } catch (err) {
+      throw new CliError(`CSV row ${index + 2}: ${err.message}`, {
+        exitCode: 65,
+      })
+    }
+  })
+}