@wavyx/pdcli 0.9.0 → 0.10.0

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,16 +29,53 @@ 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(

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,15 +26,47 @@ 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(

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/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
+}

package/src/lib/client.js

@@ -177,6 +177,21 @@ export function createClient({
       debug('%s %s → %d', method, path, res.status)
 
       if (res.status === 429) {
+        // Daily-budget exhaustion has no useful reset window — backoff would
+        // stall until the daily reset. Fail fast with an actionable message.
+        // The live API reports the token budget as
+        // x-daily-ratelimit-token-remaining (verified on the sandbox);
+        // x-daily-requests-left is the older POST/PUT fair-use header.
+        const dailyRemaining =
+          res.headers.get('x-daily-ratelimit-token-remaining') ??
+          res.headers.get('x-daily-requests-left')
+        if (dailyRemaining === '0') {
+          const err = new RateLimitError(0)
+          err.message =
+            'Daily API token budget exhausted — resets at midnight server ' +
+            'time (UTC-based; may differ from your local timezone)'
+          throw err
+        }
         const wait = Number(
           res.headers.get('x-ratelimit-reset') ||
             res.headers.get('retry-after') ||
@@ -189,6 +204,16 @@ export function createClient({
         continue
       }
 
+      // Surface the remaining daily budget under --verbose (DEBUG=pd:*).
+      const dailyLeft = res.headers.get('x-daily-ratelimit-token-remaining')
+      if (dailyLeft != null) {
+        debug(
+          'daily token budget: %s remaining of %s',
+          dailyLeft,
+          res.headers.get('x-daily-ratelimit-token-limit') ?? '?',
+        )
+      }
+
       // OAuth access tokens expire (~1h) — refresh once and retry.
       if (res.status === 401 && onRefresh && attempts === 1) {
         debug('401, attempting OAuth token refresh')