@wavyx/pdcli 0.9.0 → 0.11.0

package/src/commands/task/get.js

@@ -0,0 +1,26 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { outputRecord } from '../../lib/entity-view.js'
+
+export default class TaskGetCommand extends BaseCommand {
+  static description = 'Get a task by ID'
+
+  static examples = [
+    '<%= config.bin %> task get 9',
+    '<%= config.bin %> task get 9 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Task ID' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(TaskGetCommand)
+    const body = await this.apiClient.get(`/api/v2/tasks/${args.id}`)
+    await outputRecord(this, body.data)
+  }
+}

package/src/commands/task/list.js

@@ -0,0 +1,60 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { collectPages } from '../../lib/pagination.js'
+
+const columns = {
+  id: { header: 'ID' },
+  title: { header: 'Title' },
+  project_id: { header: 'Project' },
+  assignee_id: {
+    header: 'Assignee',
+    // v2 returns assignee_ids (array); surface the first for the column.
+    get: (row) => row.assignee_ids?.[0] ?? '',
+  },
+  due_date: { header: 'Due' },
+  done: { header: 'Done', get: (row) => (row.is_done ? 'yes' : 'no') },
+}
+
+export default class TaskListCommand extends BaseCommand {
+  static description = 'List tasks'
+
+  static examples = [
+    '<%= config.bin %> task list',
+    '<%= config.bin %> task list --project 3 --todo',
+    '<%= config.bin %> task list --assignee 7 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    project: Flags.integer({ description: 'Filter by project ID' }),
+    assignee: Flags.integer({ description: 'Filter by assignee (user) ID' }),
+    parent: Flags.integer({ description: 'Filter by parent task ID' }),
+    done: Flags.boolean({
+      description: 'Only completed tasks',
+      exclusive: ['todo'],
+    }),
+    todo: Flags.boolean({
+      description: 'Only open (not done) tasks',
+      exclusive: ['done'],
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(TaskListCommand)
+    const limit = flags.limit ?? 500
+
+    const query = {
+      project_id: flags.project,
+      assignee_id: flags.assignee,
+      parent_task_id: flags.parent,
+      is_done: flags.done ? true : flags.todo ? false : undefined,
+      limit: Math.min(limit, 500),
+    }
+
+    const items = await collectPages(
+      this.apiClient.pageV2('/api/v2/tasks', query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/task/update.js

@@ -0,0 +1,72 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { buildWriteBody } from '../../lib/input.js'
+import { outputRecord } from '../../lib/entity-view.js'
+import { CliError } from '../../lib/errors.js'
+
+export default class TaskUpdateCommand extends BaseCommand {
+  static description = 'Update a task (v2 PATCH — only provided fields change)'
+
+  static examples = [
+    '<%= config.bin %> task update 7 --title "Renamed"',
+    '<%= config.bin %> task update 7 --done',
+    '<%= config.bin %> task update 7 --assignee 9',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Task ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    title: Flags.string({ description: 'Task title' }),
+    project: Flags.integer({ description: 'Project ID' }),
+    description: Flags.string({ description: 'Task description' }),
+    assignee: Flags.integer({ description: 'Assignee (user) ID' }),
+    'due-date': Flags.string({ description: 'Due date (YYYY-MM-DD)' }),
+    parent: Flags.integer({ description: 'Parent task ID' }),
+    done: Flags.boolean({
+      description: 'Mark the task as done',
+      exclusive: ['undone'],
+    }),
+    undone: Flags.boolean({
+      description: 'Mark the task as not done',
+      exclusive: ['done'],
+    }),
+    body: Flags.string({ description: 'Raw JSON body to merge (flags win)' }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(TaskUpdateCommand)
+
+    // The v2 task body takes `done` as an integer enum (0 = not done, 1 = done).
+    let done
+    if (flags.done) done = 1
+    else if (flags.undone) done = 0
+
+    const body = buildWriteBody({
+      typed: {
+        title: flags.title,
+        project_id: flags.project,
+        description: flags.description,
+        assignee_id: flags.assignee,
+        due_date: flags['due-date'],
+        parent_task_id: flags.parent,
+        done,
+      },
+      rawBody: flags.body,
+    })
+
+    if (Object.keys(body).length === 0) {
+      throw new CliError(
+        'Nothing to update — pass at least one field flag or --body',
+        { exitCode: 64 },
+      )
+    }
+
+    const res = await this.apiClient.patch(`/api/v2/tasks/${args.id}`, {
+      body,
+    })
+    await outputRecord(this, res.data)
+  }
+}

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')
@@ -282,6 +307,24 @@ export function createClient({
     })
   }
 
+  /**
+   * PUT application/x-www-form-urlencoded (v1 form endpoints, e.g.
+   * /api/v1/files/:id — JSON is not accepted there).
+   * @param {string} path
+   * @param {Record<string, unknown>} fields Null/undefined values are omitted.
+   */
+  async function putForm(path, fields = {}) {
+    const params = new URLSearchParams()
+    for (const [k, v] of Object.entries(fields)) {
+      if (v != null) params.set(k, String(v))
+    }
+    return transport('PUT', lockedUrl(path), {
+      path,
+      makeBody: () => params.toString(),
+      extraHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
+    })
+  }
+
   return {
     get: (path, opts) => request('GET', path, opts),
     post: (path, opts) => request('POST', path, opts),
@@ -291,6 +334,7 @@ export function createClient({
     download,
     postMultipart,
     postForm,
+    putForm,
     pageV1,
     pageV2,
   }

package/src/lib/fields.js

@@ -13,19 +13,35 @@ const ENTITY_FIELDS = {
   activity: 'activityFields',
 }
 
+/**
+ * Entities whose fields live ONLY on v1 — offset-paginated and returning the
+ * legacy key/name shape that getFields normalizes to field_code/field_name.
+ */
+const V1_ENTITY_FIELDS = {
+  lead: 'leadFields',
+  note: 'noteFields',
+}
+
 /**
  * @param {string} entity deal | person | org(anization) | product | activity
- * @returns {string} v2 fields endpoint path
+ *   | lead | note
+ * @returns {string} fields endpoint path (v2 for core entities, v1 for
+ *   lead/note)
  */
 export function entityToFieldsPath(entity) {
-  const resource = ENTITY_FIELDS[entity]
-  if (!resource) {
-    throw new CliError(
-      `Unknown entity "${entity}". Use one of: ${Object.keys(ENTITY_FIELDS).join(', ')}`,
-      { exitCode: 64 },
-    )
-  }
-  return `/api/v2/${resource}`
+  const v2 = ENTITY_FIELDS[entity]
+  if (v2) return `/api/v2/${v2}`
+
+  const v1 = V1_ENTITY_FIELDS[entity]
+  if (v1) return `/api/v1/${v1}`
+
+  throw new CliError(
+    `Unknown entity "${entity}". Use one of: ${[
+      ...Object.keys(ENTITY_FIELDS),
+      ...Object.keys(V1_ENTITY_FIELDS),
+    ].join(', ')}`,
+    { exitCode: 64 },
+  )
 }
 
 /** @type {Map<string, object[]>} per-run field-definition cache */
@@ -35,9 +51,22 @@ export function clearFieldsCache() {
   cache.clear()
 }
 
+/**
+ * Normalize a v1 field definition (key/name) to the v2 shape
+ * (field_code/field_name) so callers can treat both alike.
+ * @param {object} def
+ */
+function normalizeV1Field(def) {
+  const { key, name, ...rest } = def
+  return { ...rest, field_code: key, field_name: name }
+}
+
 /**
  * Fetch (and memoize for this run) all field definitions for an entity.
- * @param {{ pageV2: (path: string) => AsyncGenerator<object> }} client
+ * Core entities use the v2 cursor pager; lead/note use the v1 offset pager
+ * and are normalized to the v2 field_code/field_name shape.
+ * @param {{ pageV2: (path: string) => AsyncGenerator<object>,
+ *   pageV1: (path: string) => AsyncGenerator<object> }} client
  * @param {string} entity
  * @returns {Promise<object[]>}
  */
@@ -45,10 +74,12 @@ export async function getFields(client, entity) {
   const path = entityToFieldsPath(entity)
   if (cache.has(path)) return cache.get(path)
 
+  const isV1 = path.startsWith('/api/v1/')
   debug('fetching field definitions: %s', path)
   const defs = []
-  for await (const def of client.pageV2(path)) {
-    defs.push(def)
+  const pager = isV1 ? client.pageV1(path) : client.pageV2(path)
+  for await (const def of pager) {
+    defs.push(isV1 ? normalizeV1Field(def) : def)
   }
   cache.set(path, defs)
   return defs