@wavyx/pdcli 0.8.0 → 0.10.0

package/src/commands/org/list.js

@@ -1,6 +1,7 @@
 import { Flags } from '@oclif/core'
 import BaseCommand from '../../base-command.js'
 import { collectPages } from '../../lib/pagination.js'
+import { CliError } from '../../lib/errors.js'
 
 const columns = {
   id: { header: 'ID' },
@@ -20,21 +21,58 @@ export default class OrgListCommand extends BaseCommand {
   static flags = {
     ...BaseCommand.baseFlags,
     owner: Flags.integer({ description: 'Filter by owner (user) ID' }),
+    filter: Flags.integer({ description: 'Filter by saved filter ID' }),
+    ids: Flags.string({
+      description: 'Comma-separated IDs to fetch (max 100)',
+      // The API silently drops `ids` when filter_id is present — refuse
+      // the combination instead (matches deal bulk-update).
+      exclusive: ['filter'],
+    }),
+    'sort-by': Flags.string({
+      description: 'Sort field',
+      options: ['id', 'update_time', 'add_time'],
+    }),
+    'sort-direction': Flags.string({
+      description: 'Sort direction',
+      options: ['asc', 'desc'],
+    }),
+    'updated-since': Flags.string({
+      description:
+        'Only items updated at/after this RFC3339 time (no fractional seconds)',
+    }),
+    'updated-until': Flags.string({
+      description:
+        'Only items updated before this RFC3339 time (no fractional seconds)',
+    }),
   }
 
   async run() {
     const { flags } = await this.parse(OrgListCommand)
-    const limit = flags.limit ?? 100
+    const limit = flags.limit ?? 500
+
+    const idList = flags.ids
+      ?.split(',')
+      .map((v) => v.trim())
+      .filter(Boolean)
+    if (idList && idList.length > 100) {
+      throw new CliError('--ids accepts at most 100 IDs', { exitCode: 64 })
+    }
 
     const query = {
       owner_id: flags.owner,
-      limit: Math.min(limit, 100),
+      filter_id: flags.filter,
+      ids: idList?.join(','),
+      sort_by: flags['sort-by'],
+      sort_direction: flags['sort-direction'],
+      updated_since: flags['updated-since'],
+      updated_until: flags['updated-until'],
+      limit: Math.min(limit, 500),
     }
 
     const items = await collectPages(
       this.apiClient.pageV2('/api/v2/organizations', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'org' })
   }
 }

package/src/commands/person/list.js

@@ -1,6 +1,7 @@
 import { Flags } from '@oclif/core'
 import BaseCommand from '../../base-command.js'
 import { collectPages } from '../../lib/pagination.js'
+import { CliError } from '../../lib/errors.js'
 
 function primary(list) {
   if (!Array.isArray(list) || list.length === 0) return ''
@@ -28,22 +29,59 @@ export default class PersonListCommand extends BaseCommand {
     ...BaseCommand.baseFlags,
     owner: Flags.integer({ description: 'Filter by owner (user) ID' }),
     org: Flags.integer({ description: 'Filter by organization ID' }),
+    filter: Flags.integer({ description: 'Filter by saved filter ID' }),
+    ids: Flags.string({
+      description: 'Comma-separated IDs to fetch (max 100)',
+      // The API silently drops `ids` when filter_id is present — refuse
+      // the combination instead (matches deal bulk-update).
+      exclusive: ['filter'],
+    }),
+    'sort-by': Flags.string({
+      description: 'Sort field',
+      options: ['id', 'update_time', 'add_time'],
+    }),
+    'sort-direction': Flags.string({
+      description: 'Sort direction',
+      options: ['asc', 'desc'],
+    }),
+    'updated-since': Flags.string({
+      description:
+        'Only items updated at/after this RFC3339 time (no fractional seconds)',
+    }),
+    'updated-until': Flags.string({
+      description:
+        'Only items updated before this RFC3339 time (no fractional seconds)',
+    }),
   }
 
   async run() {
     const { flags } = await this.parse(PersonListCommand)
-    const limit = flags.limit ?? 100
+    const limit = flags.limit ?? 500
+
+    const idList = flags.ids
+      ?.split(',')
+      .map((v) => v.trim())
+      .filter(Boolean)
+    if (idList && idList.length > 100) {
+      throw new CliError('--ids accepts at most 100 IDs', { exitCode: 64 })
+    }
 
     const query = {
       owner_id: flags.owner,
       org_id: flags.org,
-      limit: Math.min(limit, 100),
+      filter_id: flags.filter,
+      ids: idList?.join(','),
+      sort_by: flags['sort-by'],
+      sort_direction: flags['sort-direction'],
+      updated_since: flags['updated-since'],
+      updated_until: flags['updated-until'],
+      limit: Math.min(limit, 500),
     }
 
     const items = await collectPages(
       this.apiClient.pageV2('/api/v2/persons', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'person' })
   }
 }

package/src/commands/product/list.js

@@ -1,6 +1,7 @@
 import { Flags } from '@oclif/core'
 import BaseCommand from '../../base-command.js'
 import { collectPages } from '../../lib/pagination.js'
+import { CliError } from '../../lib/errors.js'
 
 const columns = {
   id: { header: 'ID' },
@@ -25,21 +26,53 @@ export default class ProductListCommand extends BaseCommand {
   static flags = {
     ...BaseCommand.baseFlags,
     owner: Flags.integer({ description: 'Filter by owner (user) ID' }),
+    filter: Flags.integer({ description: 'Filter by saved filter ID' }),
+    ids: Flags.string({
+      description: 'Comma-separated IDs to fetch (max 100)',
+      // The API silently drops `ids` when filter_id is present — refuse
+      // the combination instead (matches deal bulk-update).
+      exclusive: ['filter'],
+    }),
+    'sort-by': Flags.string({
+      description: 'Sort field',
+      options: ['id', 'name', 'add_time', 'update_time'],
+    }),
+    'sort-direction': Flags.string({
+      description: 'Sort direction',
+      options: ['asc', 'desc'],
+    }),
+    'updated-since': Flags.string({
+      description:
+        'Only items updated at/after this RFC3339 time (no fractional seconds)',
+    }),
   }
 
   async run() {
     const { flags } = await this.parse(ProductListCommand)
-    const limit = flags.limit ?? 100
+    const limit = flags.limit ?? 500
+
+    const idList = flags.ids
+      ?.split(',')
+      .map((v) => v.trim())
+      .filter(Boolean)
+    if (idList && idList.length > 100) {
+      throw new CliError('--ids accepts at most 100 IDs', { exitCode: 64 })
+    }
 
     const query = {
       owner_id: flags.owner,
-      limit: Math.min(limit, 100),
+      filter_id: flags.filter,
+      ids: idList?.join(','),
+      sort_by: flags['sort-by'],
+      sort_direction: flags['sort-direction'],
+      updated_since: flags['updated-since'],
+      limit: Math.min(limit, 500),
     }
 
     const items = await collectPages(
       this.apiClient.pageV2('/api/v2/products', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'product' })
   }
 }

package/src/commands/user/find.js

@@ -0,0 +1,50 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+
+const columns = {
+  id: { header: 'ID' },
+  name: { header: 'Name' },
+  email: { header: 'Email' },
+  active_flag: {
+    header: 'Active',
+    get: (row) => (row.active_flag ? 'yes' : 'no'),
+  },
+  is_admin: { header: 'Admin', get: (row) => (row.is_admin ? 'yes' : 'no') },
+}
+
+export default class UserFindCommand extends BaseCommand {
+  static description = 'Find users by name'
+
+  static examples = [
+    '<%= config.bin %> user find "jane"',
+    '<%= config.bin %> user find "jane@acme.com" --by-email --output json',
+  ]
+
+  static args = {
+    term: Args.string({ required: true, description: 'Search term' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    'by-email': Flags.boolean({
+      description: 'Match the term against email addresses only',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(UserFindCommand)
+
+    // Users API is v1-only; /users/find returns one unpaginated array.
+    const body = await this.apiClient.get('/api/v1/users/find', {
+      query: {
+        term: args.term,
+        search_by_email: flags['by-email'] ? 1 : undefined,
+      },
+    })
+    let users = body.data ?? []
+    if (flags.limit) users = users.slice(0, flags.limit)
+
+    await this.outputResults(users, columns)
+  }
+}

package/src/commands/user/list.js

@@ -0,0 +1,36 @@
+import BaseCommand from '../../base-command.js'
+
+const columns = {
+  id: { header: 'ID' },
+  name: { header: 'Name' },
+  email: { header: 'Email' },
+  active_flag: {
+    header: 'Active',
+    get: (row) => (row.active_flag ? 'yes' : 'no'),
+  },
+  is_admin: { header: 'Admin', get: (row) => (row.is_admin ? 'yes' : 'no') },
+}
+
+export default class UserListCommand extends BaseCommand {
+  static description = 'List all users'
+
+  static examples = [
+    '<%= config.bin %> user list',
+    '<%= config.bin %> user list --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    const { flags } = await this.parse(UserListCommand)
+
+    // Users API is v1-only and returns every user in one unpaginated array.
+    const body = await this.apiClient.get('/api/v1/users')
+    let users = body.data ?? []
+    if (flags.limit) users = users.slice(0, flags.limit)
+
+    await this.outputResults(users, columns)
+  }
+}

package/src/commands/webhook/create.js

@@ -27,15 +27,21 @@ export default class WebhookCreateCommand extends BaseCommand {
       description: 'Event object to subscribe to',
       options: [
         'activity',
+        'board',
         'deal',
+        'deal_installment',
+        'deal_product',
         'lead',
         'note',
         'organization',
         'person',
-        'product',
-        'user',
+        'phase',
         'pipeline',
+        'product',
+        'project',
         'stage',
+        'task',
+        'user',
         '*',
       ],
     }),

package/src/lib/aliases.js

@@ -1,4 +1,78 @@
+import fs from 'node:fs'
 import { getConf } from './config.js'
+import { CliError } from './errors.js'
+
+const LOCK_STALE_MS = 5000
+const LOCK_RETRIES = 8
+const LOCK_RETRY_MS = 50
+
+/** Synchronous sleep for the short lock-retry loop (no event-loop yield needed). */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/**
+ * Release the lock. Never throws: the mutation already persisted, so a
+ * failed release must not convert success into a reported failure (a
+ * leftover dir goes stale in 5s and is reaped by the next writer).
+ */
+function releaseLock(lockDir) {
+  try {
+    fs.rmdirSync(lockDir)
+  } catch {
+    /* benign: stale-broken concurrently, or unremovable — reaped later */
+  }
+}
+
+/**
+ * Advisory lock around alias mutations: a lock DIRECTORY next to the conf
+ * file (mkdir is atomic on every platform we support). Protects concurrent
+ * pdcli processes from clobbering each other's read-modify-write of the
+ * aliases object — advisory only; other writers aren't covered. A lock left
+ * behind by a crashed process goes stale after 5s and is broken.
+ * @param {() => void} fn the mutation to run while holding the lock
+ */
+function withAliasLock(fn) {
+  const lockDir = `${getConf().path}.aliases.lock`
+
+  for (let attempt = 0; attempt <= LOCK_RETRIES; attempt++) {
+    try {
+      fs.mkdirSync(lockDir)
+      try {
+        fn()
+        return
+      } finally {
+        releaseLock(lockDir)
+      }
+    } catch (err) {
+      if (err?.code !== 'EEXIST') {
+        // Not contention — the config dir itself is unusable. Name the real
+        // problem instead of leaking the lock implementation detail.
+        throw new CliError(
+          `Cannot update aliases: the config directory is not writable (${err?.code ?? err?.message})`,
+          { exitCode: 78 },
+        )
+      }
+      // Held by someone else — break it if stale, otherwise wait and retry.
+      let stale
+      try {
+        stale = Date.now() - fs.statSync(lockDir).mtimeMs > LOCK_STALE_MS
+      } catch {
+        continue // lock vanished between mkdir and stat — retry immediately
+      }
+      if (stale) {
+        fs.rmdirSync(lockDir) // a real failure here must surface, not retry
+        continue
+      }
+      if (attempt < LOCK_RETRIES) sleepSync(LOCK_RETRY_MS)
+    }
+  }
+
+  throw new CliError(
+    'another pdcli process is updating aliases — retry in a moment',
+    { exitCode: 75 },
+  )
+}
 
 export function getAliases() {
   return getConf().get('aliases') ?? {}
@@ -17,19 +91,25 @@ export function getAlias(name) {
  * dotted-path write. conf splits `set('aliases.<name>', …)` on every '.', so a
  * dotted-path write would corrupt any name containing a dot (store/read
  * mismatch). Mutating the object and writing it whole keeps odd names flat.
+ * The read-modify-write runs under an advisory lock so concurrent pdcli
+ * processes can't clobber each other.
  * @param {string} name
  * @param {string} command
  */
 export function setAlias(name, command) {
-  const aliases = { ...getAliases(), [name]: command }
-  getConf().set('aliases', aliases)
+  withAliasLock(() => {
+    const aliases = { ...getAliases(), [name]: command }
+    getConf().set('aliases', aliases)
+  })
 }
 
 /**
  * @param {string} name
  */
 export function unsetAlias(name) {
-  const aliases = { ...getAliases() }
-  delete aliases[name]
-  getConf().set('aliases', aliases)
+  withAliasLock(() => {
+    const aliases = { ...getAliases() }
+    delete aliases[name]
+    getConf().set('aliases', aliases)
+  })
 }

package/src/lib/changelog.js

@@ -0,0 +1,85 @@
+import { collectPages } from './pagination.js'
+import { ApiError } from './errors.js'
+
+/** Token cost of one GET /deals/{id}/changelog request (rate-limit budget). */
+export const CHANGELOG_COST = 20
+/** Above this deal count, mining gets expensive — warn before proceeding. */
+export const MINE_WARN_THRESHOLD = 100
+/** Pipedrive caps list page sizes at 500; the changelog uses the same cap. */
+const MAX_PAGE_LIMIT = 500
+
+/**
+ * Fetch a single deal's field-change history. The deal changelog lives on a v1
+ * path but pages with a flat v2-style cursor (additional_data.next_cursor), so
+ * the v2 pager works directly. Rows arrive newest-first (the API's native order)
+ * and carry { field_key, old_value, new_value, actor_user_id, time, ... }.
+ * @param {ReturnType<import('./client.js').createClient>} client
+ * @param {number} dealId
+ * @param {{ limit?: number }} [options]
+ * @returns {Promise<object[]>}
+ */
+export async function fetchChangelog(client, dealId, { limit } = {}) {
+  return collectPages(
+    client.pageV2(`/api/v1/deals/${dealId}/changelog`, {
+      limit: limit ?? MAX_PAGE_LIMIT,
+    }),
+  )
+}
+
+/**
+ * Mine the changelog of many deals, one request each. Warns on stderr before
+ * mining a large set — each request costs tokens — then lets the client's rate
+ * limiter pace it. A single bad changelog request must not abort the whole mine:
+ * deals whose fetch throws an ApiError are skipped, counted, and reported once
+ * after mining completes. Non-ApiError failures (e.g. socket hangups) rethrow.
+ * @param {ReturnType<import('./client.js').createClient>} client
+ * @param {object[]} deals deals to mine (id + current stage_id needed per deal)
+ * @param {{ limit?: number, warnThreshold?: number, costPerRequest?: number }} [options]
+ * @returns {Promise<{ dealId: number, stageId: number, rows: object[] }[]>}
+ */
+export async function mineMany(
+  client,
+  deals,
+  {
+    limit,
+    warnThreshold = MINE_WARN_THRESHOLD,
+    costPerRequest = CHANGELOG_COST,
+  } = {},
+) {
+  if (deals.length > warnThreshold) {
+    process.stderr.write(
+      `Mining stage history for ${deals.length} deals ` +
+        `(~${deals.length} requests, ${costPerRequest} tokens each); ` +
+        `rate limiting may slow this down.\n`,
+    )
+  }
+
+  const transitionsByDeal = []
+  let skipped = 0
+  for (const deal of deals) {
+    try {
+      const rows = await fetchChangelog(client, deal.id, { limit })
+      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 transitionsByDeal
+}