@wavyx/pdcli 0.7.0 → 0.9.0

package/src/lib/analytics.js

@@ -96,6 +96,90 @@ export function computeFunnel(closedDeals, openDeals, stages, options = {}) {
   })
 }
 
+/**
+ * EXACT stage funnel mined from per-deal changelog history, rather than the
+ * final-stage approximation in computeFunnel. A deal "enters" a stage when it
+ * is observed there: every `new_value` of a stage_id transition, plus the
+ * deal's starting stage (the first transition's `old_value`, or the deal's
+ * current stage when it has no stage transitions — i.e. it was created
+ * directly in that stage). Skipped stages are NOT counted (the whole point):
+ * a deal that jumps 1→3 enters 1 and 3 only, never 2. Entries are de-duped per
+ * deal, so re-entering a stage still counts once. `won` counts deals whose
+ * changelog has a status transition to "won".
+ *
+ * @param {{ dealId: number, stageId: number, rows: object[] }[]} transitionsByDeal
+ *   one entry per mined deal: its current stage_id and raw changelog rows
+ *   (each row: { field_key, old_value, new_value } — values stringified).
+ * @param {object[]} stages v2 stages (order_nr, pipeline_id)
+ * @param {{ pipelineId?: number }} [options]
+ */
+export function computeExactFunnel(transitionsByDeal, 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 validStageId = new Set(ordered.map((s) => s.id))
+  // distinct deals entered per stage id
+  const enteredByStage = new Map(ordered.map((s) => [s.id, new Set()]))
+  let won = 0
+
+  for (const { dealId, stageId, rows } of transitionsByDeal) {
+    const stageRows = rows.filter((r) => r.field_key === 'stage_id')
+    const entered = new Set()
+
+    // Starting stage: derived from the transition graph — the source stage
+    // that never appears as a destination. Order-independent, so it is
+    // immune to the changelog's newest-first ordering AND to two hops
+    // sharing the same one-second timestamp. Falls back to the oldest row's
+    // source (time sort) for degenerate cycles, else the current stage.
+    const destinations = new Set(stageRows.map((r) => String(r.new_value)))
+    const startSources = stageRows
+      .map((r) => String(r.old_value))
+      .filter((v) => !destinations.has(v))
+    let startStage
+    if (startSources.length > 0) {
+      startStage = Number(startSources[0])
+    } else if (stageRows.length > 0) {
+      const oldest = [...stageRows].sort((a, b) =>
+        String(a.time ?? '').localeCompare(String(b.time ?? '')),
+      )[0]
+      startStage = Number(oldest.old_value)
+    } else {
+      startStage = stageId
+    }
+    entered.add(startStage)
+    for (const r of stageRows) entered.add(Number(r.new_value))
+
+    for (const id of entered) {
+      if (validStageId.has(id)) enteredByStage.get(id).add(dealId)
+    }
+
+    if (rows.some((r) => r.field_key === 'status' && r.new_value === 'won')) {
+      won++
+    }
+  }
+
+  const resultRows = ordered.map((stage, index) => {
+    const entered = enteredByStage.get(stage.id).size
+    const prevEntered =
+      index > 0 ? enteredByStage.get(ordered[index - 1].id).size : null
+
+    return {
+      stage: stage.name,
+      stageId: stage.id,
+      entered,
+      conversionFromPrev:
+        index > 0 && prevEntered > 0 ? entered / prevEntered : null,
+    }
+  })
+
+  // `won` is a single account-wide total — returned once, not repeated on
+  // every row, so JSON consumers don't misread it as a per-stage figure.
+  return { rows: resultRows, won }
+}
+
 const STALE_DAYS = 14
 
 /**
@@ -152,3 +236,61 @@ export function computeHealth(deals, stages, activities, { now }) {
     }
   })
 }
+
+/** Rule-of-thumb pipeline-coverage thresholds (raw open ÷ remaining gap). */
+const COVERAGE_HEALTHY = 3
+const COVERAGE_BORDERLINE = 2
+
+/**
+ * Pipeline coverage against a revenue quota. The classic 3x rule of thumb is
+ * defined on RAW pipeline value — weighting it by win probability first would
+ * double-discount risk — so `coverage` = openValue ÷ remaining and drives the
+ * verdict; `weightedCoverage` = weightedOpen ÷ remaining is reported as the
+ * risk-adjusted secondary view. remaining = max(target − progress, 0).
+ *
+ * When progress already meets/exceeds the target the gap clamps to 0 — there
+ * is nothing left to cover, so the ratios are `null` (not Infinity, which is
+ * not JSON-serializable) with verdict `'covered'`.
+ * @param {{ openValue: number, weightedOpen: number, goalTarget: number,
+ *   progress?: number }} input
+ */
+export function computeCoverage({
+  openValue,
+  weightedOpen,
+  goalTarget,
+  progress = 0,
+}) {
+  const remaining = Math.max(goalTarget - progress, 0)
+
+  if (remaining === 0) {
+    return {
+      openValue,
+      weightedOpen,
+      goalTarget,
+      progress,
+      remaining,
+      coverage: null,
+      weightedCoverage: null,
+      verdict: 'covered',
+    }
+  }
+
+  const coverage = openValue / remaining
+  const verdict =
+    coverage >= COVERAGE_HEALTHY
+      ? 'healthy'
+      : coverage >= COVERAGE_BORDERLINE
+        ? 'borderline'
+        : 'low'
+
+  return {
+    openValue,
+    weightedOpen,
+    goalTarget,
+    progress,
+    remaining,
+    coverage,
+    weightedCoverage: weightedOpen / remaining,
+    verdict,
+  }
+}

package/src/lib/audit.js

@@ -3,6 +3,11 @@ const STALE_DAYS = 14
 const ANCIENT_FALLBACK_DAYS = 168 // ~2× the median B2B cycle
 const ANCIENT_CYCLE_MULTIPLIER = 2
 
+/** Jaro-Winkler score at/above which two org names are treated as near-duplicates. */
+export const FUZZY_ORG_THRESHOLD = 0.92
+/** Skip the O(n²) fuzzy pass above this org count to bound the comparison cost. */
+export const FUZZY_ORG_MAX = 2000
+
 function openDeals(data) {
   return data.deals.filter((d) => d.status === 'open')
 }
@@ -159,11 +164,48 @@ export const AUDIT_CHECKS = [
       for (const org of data.organizations) {
         const key = normalizeOrgName(org.name)
         if (!key) continue
-        byName.set(key, [...(byName.get(key) ?? []), org.id])
+        const group = byName.get(key) ?? { ids: [], original: org.name }
+        group.ids.push(org.id)
+        byName.set(key, group)
+      }
+      const exact = [...byName.entries()]
+        .filter(([, group]) => group.ids.length > 1)
+        .map(([name, group]) => ({ kind: 'exact', name, ids: group.ids }))
+
+      // Normalized names that did NOT collide exactly are fuzzy candidates;
+      // exact-duplicate groups are already reported above, so skip them here.
+      const singles = [...byName.entries()].filter(
+        ([, group]) => group.ids.length === 1,
+      )
+
+      if (singles.length > FUZZY_ORG_MAX) {
+        return [
+          ...exact,
+          {
+            kind: 'note',
+            note: `Skipped fuzzy near-duplicate scan: ${singles.length} organizations exceed the ${FUZZY_ORG_MAX} cap.`,
+          },
+        ]
       }
-      return [...byName.entries()]
-        .filter(([, ids]) => ids.length > 1)
-        .map(([name, ids]) => ({ name, ids }))
+
+      const fuzzy = []
+      for (let i = 0; i < singles.length; i++) {
+        for (let j = i + 1; j < singles.length; j++) {
+          const [nameA, groupA] = singles[i]
+          const [nameB, groupB] = singles[j]
+          const score = jaroWinkler(nameA, nameB)
+          if (score >= FUZZY_ORG_THRESHOLD) {
+            fuzzy.push({
+              kind: 'fuzzy',
+              // Report original spellings so the orgs are findable in Pipedrive.
+              names: [groupA.original, groupB.original],
+              ids: [groupA.ids[0], groupB.ids[0]].sort((a, b) => a - b),
+              score: Math.round(score * 10000) / 10000,
+            })
+          }
+        }
+      }
+      return [...exact, ...fuzzy]
     },
   },
   {
@@ -203,6 +245,62 @@ function normalizeOrgName(name) {
     .replace(/[^a-z0-9]/g, '')
 }
 
+/**
+ * Jaro-Winkler string similarity in [0, 1] (1 = identical). Standard variant:
+ * Winkler prefix bonus with scale 0.1 over a max common prefix of 4.
+ * Pure and symmetric. Two empty strings score 1; one empty string scores 0.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function jaroWinkler(a, b) {
+  if (a === b) return 1
+  const lenA = a.length
+  const lenB = b.length
+  if (lenA === 0 || lenB === 0) return 0
+
+  const matchWindow = Math.max(0, Math.floor(Math.max(lenA, lenB) / 2) - 1)
+  const matchedA = new Array(lenA).fill(false)
+  const matchedB = new Array(lenB).fill(false)
+
+  let matches = 0
+  for (let i = 0; i < lenA; i++) {
+    const start = Math.max(0, i - matchWindow)
+    const end = Math.min(i + matchWindow + 1, lenB)
+    for (let j = start; j < end; j++) {
+      if (matchedB[j] || a[i] !== b[j]) continue
+      matchedA[i] = true
+      matchedB[j] = true
+      matches++
+      break
+    }
+  }
+  if (matches === 0) return 0
+
+  // Count transpositions: matched chars out of order between the two strings.
+  let transpositions = 0
+  let k = 0
+  for (let i = 0; i < lenA; i++) {
+    if (!matchedA[i]) continue
+    while (!matchedB[k]) k++
+    if (a[i] !== b[k]) transpositions++
+    k++
+  }
+  transpositions /= 2
+
+  const jaro =
+    (matches / lenA + matches / lenB + (matches - transpositions) / matches) / 3
+
+  // Winkler prefix bonus, capped at 4 shared leading characters.
+  let prefix = 0
+  const maxPrefix = Math.min(4, lenA, lenB)
+  for (let i = 0; i < maxPrefix; i++) {
+    if (a[i] !== b[i]) break
+    prefix++
+  }
+  return jaro + prefix * 0.1 * (1 - jaro)
+}
+
 /**
  * Run all (or a subset of) hygiene checks over pre-fetched account data.
  * @param {{ deals: object[], persons: object[], organizations: object[], activities: object[] }} data
@@ -214,13 +312,16 @@ export function runChecks(data, { now, only } = {}) {
     (check) => {
       const overdueTotal = check.name === 'overdue-activities'
       const items = check.run(data, { now })
+      // Informational rows (kind:'note') stay in items but are not findings,
+      // so they never contribute to the count consumers branch on.
+      const findings = items.filter((i) => i.kind !== 'note')
       return {
         name: check.name,
         severity: check.severity,
         title: check.title,
         count: overdueTotal
-          ? items.reduce((sum, i) => sum + i.overdue, 0)
-          : items.length,
+          ? findings.reduce((sum, i) => sum + i.overdue, 0)
+          : findings.length,
         items,
       }
     },

package/src/lib/client.js

@@ -79,6 +79,87 @@ export function createClient({
       }
     }
 
+    return transport(method, url, {
+      path,
+      makeBody: body ? () => JSON.stringify(body) : undefined,
+      extraHeaders: { 'content-type': 'application/json' },
+    })
+  }
+
+  /**
+   * v2 cursor pagination: cursor/limit → additional_data.next_cursor.
+   * @param {string} path
+   * @param {object} [query]
+   * @returns {AsyncGenerator<object>}
+   */
+  async function* pageV2(path, query = {}) {
+    let cursor
+    const baseQuery = clampLimit(query)
+    while (true) {
+      const envelope = await request('GET', path, {
+        query: cursor ? { ...baseQuery, cursor } : baseQuery,
+      })
+      yield* envelope?.data ?? []
+      cursor = envelope?.additional_data?.next_cursor
+      if (!cursor) break
+    }
+  }
+
+  /**
+   * v1 offset pagination: start/limit →
+   * additional_data.pagination.{more_items_in_collection,next_start}.
+   * @param {string} path
+   * @param {object} [query]
+   * @returns {AsyncGenerator<object>}
+   */
+  async function* pageV1(path, query = {}) {
+    let start
+    const baseQuery = clampLimit(query)
+    while (true) {
+      const envelope = await request('GET', path, {
+        query: start != null ? { ...baseQuery, start } : baseQuery,
+      })
+      yield* envelope?.data ?? []
+      const pagination = envelope?.additional_data?.pagination
+      if (!pagination?.more_items_in_collection) break
+      start = pagination.next_start
+    }
+  }
+
+  function lockedUrl(path) {
+    const url = new URL(path, baseOrigin)
+    if (url.origin !== baseOrigin) {
+      throw new CliError(
+        `Refusing to send request outside your Pipedrive company host ` +
+          `(${baseOrigin}): ${url.origin}`,
+        { exitCode: 78 },
+      )
+    }
+    return url
+  }
+
+  function authHeaders() {
+    return authMode === 'oauth'
+      ? { authorization: `Bearer ${token}`, 'user-agent': userAgent }
+      : { 'x-api-token': token, 'user-agent': userAgent }
+  }
+
+  /**
+   * Shared transport: EVERY HTTP path (JSON, form, multipart, binary) goes
+   * through the same 429 backoff (x-ratelimit-reset → Retry-After → default),
+   * 429→403 escalation hard stop, 5xx retry, OAuth refresh-once, and error
+   * mapping. `makeBody` is invoked per attempt — FormData and friends are
+   * rebuilt rather than reused across retries.
+   * @param {string} method
+   * @param {URL} url
+   * @param {{ path: string, makeBody?: () => any,
+   *   extraHeaders?: Record<string, string>, binary?: boolean }} options
+   */
+  async function transport(
+    method,
+    url,
+    { path, makeBody, extraHeaders = {}, binary = false },
+  ) {
     const maxAttempts = retry ? 3 : 1
     let attempts = 0
     let sawRateLimit = false
@@ -86,20 +167,10 @@ export function createClient({
     while (attempts < maxAttempts) {
       attempts++
 
-      const headers = {
-        'content-type': 'application/json',
-        'user-agent': userAgent,
-      }
-      if (authMode === 'oauth') {
-        headers.authorization = `Bearer ${token}`
-      } else {
-        headers['x-api-token'] = token
-      }
-
       const res = await fetch(url, {
         method,
-        headers,
-        body: body ? JSON.stringify(body) : undefined,
+        headers: { ...authHeaders(), ...extraHeaders },
+        body: makeBody ? makeBody() : undefined,
         signal: AbortSignal.timeout(timeout),
       })
 
@@ -141,97 +212,38 @@ export function createClient({
         continue
       }
 
+      // Binary callers always get the {buffer, contentType} shape — a 204
+      // yields an empty buffer rather than null (pre-unification parity;
+      // file/download destructures the result).
+      if (binary) {
+        if (!res.ok) {
+          throw ApiError.fromResponse(res.status, await res.text(), path)
+        }
+        return {
+          buffer: await res.arrayBuffer(),
+          contentType: res.headers.get('content-type'),
+        }
+      }
+
       if (res.status === 204) return null
 
       const text = await res.text()
-
       if (!res.ok) {
         throw ApiError.fromResponse(res.status, text, path)
       }
-
       return text ? JSON.parse(text) : null
     }
 
     throw new ServiceUnavailableError()
   }
 
-  /**
-   * v2 cursor pagination: cursor/limit → additional_data.next_cursor.
-   * @param {string} path
-   * @param {object} [query]
-   * @returns {AsyncGenerator<object>}
-   */
-  async function* pageV2(path, query = {}) {
-    let cursor
-    const baseQuery = clampLimit(query)
-    while (true) {
-      const envelope = await request('GET', path, {
-        query: cursor ? { ...baseQuery, cursor } : baseQuery,
-      })
-      yield* envelope?.data ?? []
-      cursor = envelope?.additional_data?.next_cursor
-      if (!cursor) break
-    }
-  }
-
-  /**
-   * v1 offset pagination: start/limit →
-   * additional_data.pagination.{more_items_in_collection,next_start}.
-   * @param {string} path
-   * @param {object} [query]
-   * @returns {AsyncGenerator<object>}
-   */
-  async function* pageV1(path, query = {}) {
-    let start
-    const baseQuery = clampLimit(query)
-    while (true) {
-      const envelope = await request('GET', path, {
-        query: start != null ? { ...baseQuery, start } : baseQuery,
-      })
-      yield* envelope?.data ?? []
-      const pagination = envelope?.additional_data?.pagination
-      if (!pagination?.more_items_in_collection) break
-      start = pagination.next_start
-    }
-  }
-
-  function lockedUrl(path) {
-    const url = new URL(path, baseOrigin)
-    if (url.origin !== baseOrigin) {
-      throw new CliError(
-        `Refusing to send request outside your Pipedrive company host ` +
-          `(${baseOrigin}): ${url.origin}`,
-        { exitCode: 78 },
-      )
-    }
-    return url
-  }
-
-  function authHeaders() {
-    return authMode === 'oauth'
-      ? { authorization: `Bearer ${token}`, 'user-agent': userAgent }
-      : { 'x-api-token': token, 'user-agent': userAgent }
-  }
-
   /**
    * Download a binary resource (e.g. /api/v1/files/:id/download).
    * @param {string} path
    * @returns {Promise<{buffer: ArrayBuffer, contentType: string | null}>}
    */
   async function download(path) {
-    const url = lockedUrl(path)
-    const res = await fetch(url, {
-      headers: authHeaders(),
-      signal: AbortSignal.timeout(timeout),
-    })
-    debug('GET (binary) %s → %d', path, res.status)
-    if (!res.ok) {
-      throw ApiError.fromResponse(res.status, await res.text(), path)
-    }
-    return {
-      buffer: await res.arrayBuffer(),
-      contentType: res.headers.get('content-type'),
-    }
+    return transport('GET', lockedUrl(path), { path, binary: true })
   }
 
   /**
@@ -240,24 +252,34 @@ export function createClient({
    * @param {{ file: { name: string, data: Buffer | Uint8Array }, fields?: Record<string, unknown> }} options
    */
   async function postMultipart(path, { file, fields = {} }) {
-    const url = lockedUrl(path)
-    const form = new FormData()
-    form.set('file', new Blob([file.data]), file.name)
+    // fetch sets the multipart boundary itself — no content-type override.
+    const makeBody = () => {
+      const form = new FormData()
+      form.set('file', new Blob([file.data]), file.name)
+      for (const [k, v] of Object.entries(fields)) {
+        if (v != null) form.set(k, String(v))
+      }
+      return form
+    }
+    return transport('POST', lockedUrl(path), { path, makeBody })
+  }
+
+  /**
+   * POST application/x-www-form-urlencoded (v1 form endpoints, e.g.
+   * /api/v1/files/remoteLink — JSON is not accepted there).
+   * @param {string} path
+   * @param {Record<string, unknown>} fields Null/undefined values are omitted.
+   */
+  async function postForm(path, fields = {}) {
+    const params = new URLSearchParams()
     for (const [k, v] of Object.entries(fields)) {
-      if (v != null) form.set(k, String(v))
+      if (v != null) params.set(k, String(v))
     }
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: authHeaders(), // fetch sets the multipart boundary itself
-      body: form,
-      signal: AbortSignal.timeout(timeout),
+    return transport('POST', lockedUrl(path), {
+      path,
+      makeBody: () => params.toString(),
+      extraHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
     })
-    debug('POST (multipart) %s → %d', path, res.status)
-    const text = await res.text()
-    if (!res.ok) {
-      throw ApiError.fromResponse(res.status, text, path)
-    }
-    return text ? JSON.parse(text) : null
   }
 
   return {
@@ -268,6 +290,7 @@ export function createClient({
     del: (path, opts) => request('DELETE', path, opts),
     download,
     postMultipart,
+    postForm,
     pageV1,
     pageV2,
   }

package/src/lib/confirm.js

@@ -1,10 +1,23 @@
 /**
  * @param {string} message
  * @param {boolean} skipConfirm
+ * @param {{ default?: boolean }} [options] Forwarded to the inquirer prompt.
+ *   Omit to preserve inquirer's native default (true).
  * @returns {Promise<boolean>}
  */
-export async function confirmAction(message, skipConfirm) {
+export async function confirmAction(message, skipConfirm, options) {
   if (skipConfirm) return true
   const { confirm } = await import('@inquirer/prompts')
-  return confirm({ message })
+  const promptOptions = { message }
+  if (options && Object.prototype.hasOwnProperty.call(options, 'default')) {
+    promptOptions.default = options.default
+  }
+  try {
+    return await confirm(promptOptions)
+  } catch (err) {
+    // Ctrl-C / closed stdin (CI, piping) force-closes the prompt — treat it
+    // as a "no" so callers abort cleanly instead of surfacing exit 70.
+    if (err?.name === 'ExitPromptError') return false
+    throw err
+  }
 }

package/src/lib/entity-view.js

@@ -10,15 +10,21 @@ import { flattenRecord } from './output/record.js'
  *   for entities without resolvable custom fields (notes, files, webhooks, …)
  */
 export async function outputRecord(cmd, record, entity) {
-  if (cmd.resolveFormat() === 'table') {
-    if (
-      entity &&
-      record.custom_fields &&
-      Object.keys(record.custom_fields).length
-    ) {
-      const defs = await getFields(cmd.apiClient, entity)
-      record = makeResolver(defs).resolveCustomFields(record)
-    }
+  const isTable = cmd.resolveFormat() === 'table'
+
+  // Table always resolves custom fields for readability; non-table formats
+  // stay raw for scriptability unless --resolve-fields opts in.
+  if (
+    (isTable || cmd.flags['resolve-fields']) &&
+    entity &&
+    record.custom_fields &&
+    Object.keys(record.custom_fields).length
+  ) {
+    const defs = await getFields(cmd.apiClient, entity)
+    record = makeResolver(defs).resolveCustomFields(record)
+  }
+
+  if (isTable) {
     await cmd.outputResults(flattenRecord(record), {
       field: { header: 'Field' },
       value: { header: 'Value' },

package/src/lib/fields.js

@@ -105,7 +105,10 @@ export function makeResolver(defs) {
 
       const resolved = {}
       for (const [key, value] of Object.entries(record.custom_fields)) {
-        const name = this.keyToName(key) ?? key
+        let name = this.keyToName(key) ?? key
+        // Duplicate field names exist in real accounts — disambiguate with
+        // a key fragment rather than silently clobbering the first value.
+        if (name in resolved) name = `${name} (${key.slice(0, 8)})`
         let displayValue = value
         if (Array.isArray(value)) {
           displayValue = value.map((v) => this.optionIdToLabel(key, v) ?? v)