@wavyx/pdcli 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wavyx/pdcli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -82,6 +82,9 @@
       },
       "alias": {
         "description": "Command shortcuts (alias set/list/unset)"
+      },
+      "deal:product": {
+        "description": "Manage products (line items) on a deal"
       }
     },
     "hooks": {

package/src/base-command.js

@@ -24,7 +24,7 @@ export default class BaseCommand extends Command {
     }),
     'resolve-fields': Flags.boolean({
       description:
-        'Resolve custom-field hash keys to names (and option ids to labels) in json/yaml/csv output of single-record get commands',
+        'Resolve custom-field hash keys to names (and option ids to labels) in json/yaml/csv output of get and core list commands',
       helpGroup: 'GLOBAL',
       default: false,
     }),
@@ -151,12 +151,31 @@ export default class BaseCommand extends Command {
   /**
    * @param {object | object[]} data
    * @param {Record<string, import('./lib/output/table.js').Column>} columns
+   * @param {{ entity?: string }} [options] entity context enables
+   *   --resolve-fields custom-field resolution on machine-format lists
    */
-  async outputResults(data, columns) {
+  async outputResults(data, columns, { entity } = {}) {
+    if (
+      entity &&
+      this.flags['resolve-fields'] &&
+      this.resolveFormat() !== 'table' &&
+      Array.isArray(data) &&
+      data.some((row) => row?.custom_fields)
+    ) {
+      const { getFields, makeResolver } = await import('./lib/fields.js')
+      // getFields is memoized per run — one defs fetch covers the whole list.
+      const resolver = makeResolver(await getFields(this.apiClient, entity))
+      data = data.map((row) =>
+        row?.custom_fields ? resolver.resolveCustomFields(row) : row,
+      )
+    }
+
     if (this.flags.jq) {
       // node-jq ships a native binary — load it only when actually used.
+      // Single records pass UNWRAPPED: `--jq .id` works on a get without
+      // the historical `.[0]` indirection (changed in 0.9.0).
       const { run } = await import('node-jq')
-      const input = JSON.stringify(Array.isArray(data) ? data : [data])
+      const input = JSON.stringify(data)
       const result = await run(this.flags.jq, input, {
         input: 'string',
         output: 'pretty',

package/src/commands/activity/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' },
@@ -27,7 +28,9 @@ export default class ActivityListCommand extends BaseCommand {
     deal: Flags.integer({ description: 'Filter by deal ID' }),
     person: Flags.integer({ description: 'Filter by person ID' }),
     org: Flags.integer({ description: 'Filter by organization ID' }),
-    type: Flags.string({ description: 'Filter by activity type key' }),
+    type: Flags.string({
+      description: 'Filter by activity type key (applied client-side)',
+    }),
     done: Flags.boolean({
       description: 'Only completed activities',
       exclusive: ['todo'],
@@ -36,26 +39,65 @@ export default class ActivityListCommand extends BaseCommand {
       description: 'Only open (not done) activities',
       exclusive: ['done'],
     }),
+    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', 'due_date'],
+    }),
+    '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(ActivityListCommand)
-    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,
       deal_id: flags.deal,
       person_id: flags.person,
       org_id: flags.org,
-      type: flags.type,
       done: flags.done ? true : flags.todo ? false : undefined,
-      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(
+    let items = await collectPages(
       this.apiClient.pageV2('/api/v2/activities', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    // The v2 activities endpoint has no `type` query param (it rejects
+    // unknown params with a 400) — filter client-side instead.
+    if (flags.type) items = items.filter((a) => a.type === flags.type)
+    await this.outputResults(items, columns, { entity: 'activity' })
   }
 }

package/src/commands/deal/history.js

@@ -0,0 +1,73 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { fetchChangelog } from '../../lib/changelog.js'
+import { getFields, makeResolver } from '../../lib/fields.js'
+
+const columns = {
+  time: { header: 'Time' },
+  field_key: { header: 'Field' },
+  old_value: { header: 'Old' },
+  new_value: { header: 'New' },
+  actor_user_id: { header: 'Actor' },
+}
+
+export default class DealHistoryCommand extends BaseCommand {
+  static description =
+    'Field-change history for a deal, newest-first (the API’s native order)'
+
+  static examples = [
+    '<%= config.bin %> deal history 42',
+    '<%= config.bin %> deal history 42 --field stage_id',
+    '<%= config.bin %> deal history 42 --limit 20 --resolve-fields',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    field: Flags.string({
+      description: 'Show only changes to this field key (e.g. stage_id)',
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealHistoryCommand)
+
+    // A field filter drops rows client-side, so the fetch can't be bounded
+    // by --limit in that case; otherwise cap the API page directly.
+    const fetchLimit = flags.field ? undefined : flags.limit
+    let rows = await fetchChangelog(this.apiClient, args.id, {
+      limit: fetchLimit,
+    })
+
+    if (flags.field) {
+      rows = rows.filter((r) => r.field_key === flags.field)
+    }
+    if (flags.limit != null) {
+      rows = rows.slice(0, flags.limit)
+    }
+
+    // The Field column is the one place hash keys appear as DATA — resolve
+    // them (and enum/set option ids) to names under --resolve-fields.
+    if (flags['resolve-fields'] && rows.length > 0) {
+      const resolver = makeResolver(await getFields(this.apiClient, 'deal'))
+      // changelog values are stringified — option ids resolve numerically
+      const label = (key, value) =>
+        resolver.optionIdToLabel(key, Number(value)) ?? value
+      rows = rows.map((r) => {
+        const name = resolver.keyToName(r.field_key)
+        if (!name) return r
+        return {
+          ...r,
+          field_key: name,
+          old_value: label(r.field_key, r.old_value),
+          new_value: label(r.field_key, r.new_value),
+        }
+      })
+    }
+
+    await this.outputResults(rows, columns)
+  }
+}

package/src/commands/deal/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' },
@@ -37,11 +38,42 @@ export default class DealListCommand extends BaseCommand {
     owner: Flags.integer({ description: 'Filter by owner (user) ID' }),
     person: Flags.integer({ description: 'Filter by person 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(DealListCommand)
-    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 = {
       status: flags.status,
@@ -50,13 +82,19 @@ export default class DealListCommand extends BaseCommand {
       owner_id: flags.owner,
       person_id: flags.person,
       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/deals', query),
       limit,
     )
-    await this.outputResults(items, columns)
+    await this.outputResults(items, columns, { entity: 'deal' })
   }
 }

package/src/commands/deal/product/add.js

@@ -0,0 +1,69 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../../base-command.js'
+import { CliError } from '../../../lib/errors.js'
+import { buildWriteBody } from '../../../lib/input.js'
+import { outputRecord } from '../../../lib/entity-view.js'
+
+/** Coerce a numeric flag, failing with a clean input error on garbage. */
+function num(name, value) {
+  if (value === undefined) return undefined
+  const n = Number(value)
+  if (!Number.isFinite(n)) {
+    throw new CliError(`Invalid number for --${name}: "${value}"`, {
+      exitCode: 64,
+    })
+  }
+  return n
+}
+
+export default class DealProductAddCommand extends BaseCommand {
+  static description = 'Attach a product to a deal'
+
+  static examples = [
+    '<%= config.bin %> deal product add 42 --product 10 --price 90',
+    '<%= config.bin %> deal product add 42 --product 10 --price 90 --quantity 3',
+    '<%= config.bin %> deal product add 42 --product 10 --price 90 --discount 10 --discount-type percentage',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    product: Flags.integer({ required: true, description: 'Product ID' }),
+    price: Flags.string({
+      required: true,
+      description: 'Item price (per unit)',
+    }),
+    quantity: Flags.string({ description: 'Quantity', default: '1' }),
+    discount: Flags.string({ description: 'Discount value' }),
+    'discount-type': Flags.string({
+      description: 'Discount type',
+      options: ['percentage', 'amount'],
+    }),
+    tax: Flags.string({ description: 'Product tax percentage' }),
+    comments: Flags.string({ description: 'Comments' }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealProductAddCommand)
+
+    const body = buildWriteBody({
+      typed: {
+        product_id: flags.product,
+        item_price: num('price', flags.price),
+        quantity: num('quantity', flags.quantity),
+        discount: num('discount', flags.discount),
+        discount_type: flags['discount-type'],
+        tax: num('tax', flags.tax),
+        comments: flags.comments,
+      },
+    })
+
+    const res = await this.apiClient.post(`/api/v2/deals/${args.id}/products`, {
+      body,
+    })
+    await outputRecord(this, res.data)
+  }
+}

package/src/commands/deal/product/list.js

@@ -0,0 +1,56 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../../base-command.js'
+import { collectPages } from '../../../lib/pagination.js'
+
+const columns = {
+  id: { header: 'ID' },
+  product_id: { header: 'Product' },
+  name: { header: 'Name' },
+  item_price: { header: 'Item price' },
+  quantity: { header: 'Qty' },
+  discount: { header: 'Discount' },
+  sum: { header: 'Sum' },
+}
+
+export default class DealProductListCommand extends BaseCommand {
+  static description = 'List products attached to a deal'
+
+  static examples = [
+    '<%= config.bin %> deal product list 42',
+    '<%= config.bin %> deal product list 42 --sort-by add_time --sort-direction desc',
+    '<%= config.bin %> deal product list 42 --output json',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    'sort-by': Flags.string({
+      description: 'Field to sort by',
+      options: ['id', 'add_time', 'update_time', 'order_nr'],
+    }),
+    'sort-direction': Flags.string({
+      description: 'Sort direction',
+      options: ['asc', 'desc'],
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealProductListCommand)
+    const limit = flags.limit ?? 500
+
+    const query = {
+      sort_by: flags['sort-by'],
+      sort_direction: flags['sort-direction'],
+      limit: Math.min(limit, 500),
+    }
+
+    const items = await collectPages(
+      this.apiClient.pageV2(`/api/v2/deals/${args.id}/products`, query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/deal/product/remove.js

@@ -0,0 +1,52 @@
+import { Args, Flags } from '@oclif/core'
+import chalk from 'chalk'
+import BaseCommand from '../../../base-command.js'
+import { confirmAction } from '../../../lib/confirm.js'
+import { CliError } from '../../../lib/errors.js'
+
+export default class DealProductRemoveCommand extends BaseCommand {
+  static description = 'Remove a product attached to a deal'
+
+  static examples = [
+    '<%= config.bin %> deal product remove 42 --attachment 3',
+    '<%= config.bin %> deal product remove 42 --attachment 3 --yes',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    attachment: Flags.integer({
+      required: true,
+      description: 'Deal-product (attachment) ID',
+    }),
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealProductRemoveCommand)
+
+    const ok = await confirmAction(
+      `Remove product attachment ${flags.attachment} from deal ${args.id}?`,
+      flags.yes,
+    )
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    await this.apiClient.del(
+      `/api/v2/deals/${args.id}/products/${flags.attachment}`,
+    )
+    this.log(
+      chalk.green(
+        `Removed product attachment ${flags.attachment} from deal ${args.id}`,
+      ),
+    )
+  }
+}

package/src/commands/deal/product/update.js

@@ -0,0 +1,78 @@
+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'
+
+/** Coerce a numeric flag, failing with a clean input error on garbage. */
+function num(name, value) {
+  if (value === undefined) return undefined
+  const n = Number(value)
+  if (!Number.isFinite(n)) {
+    throw new CliError(`Invalid number for --${name}: "${value}"`, {
+      exitCode: 64,
+    })
+  }
+  return n
+}
+
+export default class DealProductUpdateCommand extends BaseCommand {
+  static description =
+    'Update a product attached to a deal (v2 PATCH — only provided fields change)'
+
+  static examples = [
+    '<%= config.bin %> deal product update 42 --attachment 3 --quantity 5',
+    '<%= config.bin %> deal product update 42 --attachment 3 --price 120',
+    '<%= config.bin %> deal product update 42 --attachment 3 --discount 15 --discount-type amount',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    attachment: Flags.integer({
+      required: true,
+      description: 'Deal-product (attachment) ID',
+    }),
+    product: Flags.integer({ description: 'Product ID' }),
+    price: Flags.string({ description: 'Item price (per unit)' }),
+    quantity: Flags.string({ description: 'Quantity' }),
+    discount: Flags.string({ description: 'Discount value' }),
+    'discount-type': Flags.string({
+      description: 'Discount type',
+      options: ['percentage', 'amount'],
+    }),
+    tax: Flags.string({ description: 'Product tax percentage' }),
+    comments: Flags.string({ description: 'Comments' }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(DealProductUpdateCommand)
+
+    const body = buildWriteBody({
+      typed: {
+        product_id: flags.product,
+        item_price: num('price', flags.price),
+        quantity: num('quantity', flags.quantity),
+        discount: num('discount', flags.discount),
+        discount_type: flags['discount-type'],
+        tax: num('tax', flags.tax),
+        comments: flags.comments,
+      },
+    })
+
+    if (Object.keys(body).length === 0) {
+      throw new CliError('Nothing to update — pass at least one field flag', {
+        exitCode: 64,
+      })
+    }
+
+    const res = await this.apiClient.patch(
+      `/api/v2/deals/${args.id}/products/${flags.attachment}`,
+      { body },
+    )
+    await outputRecord(this, res.data)
+  }
+}

package/src/commands/funnel.js

@@ -3,12 +3,8 @@ import BaseCommand from '../base-command.js'
 import { collectPages } from '../lib/pagination.js'
 import { parsePeriod, formatApiDatetime } from '../lib/period.js'
 import { computeFunnel, computeExactFunnel } from '../lib/analytics.js'
-import { CliError, ApiError } from '../lib/errors.js'
-
-/** Token cost of one GET /deals/{id}/changelog request (rate-limit budget). */
-const CHANGELOG_COST = 20
-/** Above this deal count, mining gets expensive — warn before proceeding. */
-const MINE_WARN_THRESHOLD = 100
+import { mineMany } from '../lib/changelog.js'
+import { CliError } from '../lib/errors.js'
 
 export default class FunnelCommand extends BaseCommand {
   static description =
@@ -134,54 +130,16 @@ export default class FunnelCommand extends BaseCommand {
   }
 
   /**
-   * Mine real stage transitions from each deal's v1 changelog. The changelog
-   * uses a flat v2-style cursor (additional_data.next_cursor on a v1 path), so
-   * the v2 pager works directly. Warns on stderr before mining a large set —
-   * each request costs 20 tokens — then lets the client's rate limiter pace it.
+   * Mine real stage transitions from each deal's v1 changelog (one request per
+   * deal, paced by the rate limiter), then compute the exact funnel. Mining,
+   * the large-set warning, and the skip-on-ApiError behavior live in the
+   * shared changelog lib so this command and `deal history` stay in step.
    * @param {object[]} deals deals to mine (current stage_id needed per deal)
    * @param {object[]} stages
    * @param {number} pipelineId
    */
   async mineExactFunnel(deals, stages, pipelineId) {
-    if (deals.length > MINE_WARN_THRESHOLD) {
-      process.stderr.write(
-        `Mining stage history for ${deals.length} deals ` +
-          `(~${deals.length} requests, ${CHANGELOG_COST} tokens each); ` +
-          `rate limiting may slow this down.\n`,
-      )
-    }
-
-    const transitionsByDeal = []
-    let skipped = 0
-    for (const deal of deals) {
-      try {
-        const rows = await collectPages(
-          this.apiClient.pageV2(`/api/v1/deals/${deal.id}/changelog`, {
-            limit: 500,
-          }),
-        )
-        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`,
-      )
-    }
-
+    const transitionsByDeal = await mineMany(this.apiClient, deals)
     return computeExactFunnel(transitionsByDeal, stages, { pipelineId })
   }
 }