@wavyx/pdcli 0.2.0 → 0.4.0

package/src/commands/project/delete.js

@@ -0,0 +1,39 @@
+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 ProjectDeleteCommand extends BaseCommand {
+  static description = 'Delete a project'
+
+  static examples = [
+    '<%= config.bin %> project delete 7',
+    '<%= config.bin %> project delete 7 --yes',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Project ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(ProjectDeleteCommand)
+
+    const ok = await confirmAction(`Delete project ${args.id}?`, flags.yes)
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    await this.apiClient.del(`/api/v2/projects/${args.id}`)
+    this.log(chalk.green(`Deleted project ${args.id}`))
+  }
+}

package/src/commands/project/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 ProjectGetCommand extends BaseCommand {
+  static description = 'Get a project by ID'
+
+  static examples = [
+    '<%= config.bin %> project get 3',
+    '<%= config.bin %> project get 3 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Project ID' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(ProjectGetCommand)
+    const body = await this.apiClient.get(`/api/v2/projects/${args.id}`)
+    await outputRecord(this, body.data)
+  }
+}

package/src/commands/project/list.js

@@ -0,0 +1,39 @@
+import BaseCommand from '../../base-command.js'
+import { collectPages } from '../../lib/pagination.js'
+
+const columns = {
+  id: { header: 'ID' },
+  title: { header: 'Title' },
+  status: { header: 'Status' },
+  owner_id: { header: 'Owner' },
+  start_date: { header: 'Start' },
+  end_date: { header: 'End' },
+}
+
+export default class ProjectListCommand extends BaseCommand {
+  static description = 'List projects'
+
+  static examples = [
+    '<%= config.bin %> project list',
+    '<%= config.bin %> project list --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    const { flags } = await this.parse(ProjectListCommand)
+    const limit = flags.limit ?? 100
+
+    const query = {
+      limit: Math.min(limit, 100),
+    }
+
+    const items = await collectPages(
+      this.apiClient.pageV2('/api/v2/projects', query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/project/update.js

@@ -0,0 +1,63 @@
+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 ProjectUpdateCommand extends BaseCommand {
+  static description =
+    'Update a project (v2 PATCH — only provided fields change)'
+
+  static examples = [
+    '<%= config.bin %> project update 7 --title "Relaunch"',
+    '<%= config.bin %> project update 7 --status closed',
+    '<%= config.bin %> project update 7 --owner 9',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Project ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    title: Flags.string({ description: 'Project title' }),
+    description: Flags.string({ description: 'Project description' }),
+    status: Flags.string({ description: 'Project status' }),
+    'start-date': Flags.string({ description: 'Start date (YYYY-MM-DD)' }),
+    'end-date': Flags.string({ description: 'End date (YYYY-MM-DD)' }),
+    owner: Flags.integer({ description: 'Owner (user) ID' }),
+    board: Flags.integer({ description: 'Board ID' }),
+    phase: Flags.integer({ description: 'Phase ID' }),
+    body: Flags.string({ description: 'Raw JSON body to merge (flags win)' }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(ProjectUpdateCommand)
+
+    const body = buildWriteBody({
+      typed: {
+        title: flags.title,
+        description: flags.description,
+        status: flags.status,
+        start_date: flags['start-date'],
+        end_date: flags['end-date'],
+        owner_id: flags.owner,
+        board_id: flags.board,
+        phase_id: flags.phase,
+      },
+      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/projects/${args.id}`, {
+      body,
+    })
+    await outputRecord(this, res.data)
+  }
+}

package/src/commands/stage/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 StageGetCommand extends BaseCommand {
+  static description = 'Get a stage by ID'
+
+  static examples = [
+    '<%= config.bin %> stage get 5',
+    '<%= config.bin %> stage get 5 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Stage ID' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(StageGetCommand)
+    const body = await this.apiClient.get(`/api/v2/stages/${args.id}`)
+    await outputRecord(this, body.data)
+  }
+}

package/src/commands/stage/list.js

@@ -0,0 +1,41 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { collectPages } from '../../lib/pagination.js'
+
+const columns = {
+  id: { header: 'ID' },
+  name: { header: 'Name' },
+  pipeline_id: { header: 'Pipeline' },
+  deal_probability: { header: 'Probability' },
+  order_nr: { header: 'Order' },
+}
+
+export default class StageListCommand extends BaseCommand {
+  static description = 'List stages'
+
+  static examples = [
+    '<%= config.bin %> stage list',
+    '<%= config.bin %> stage list --pipeline 1 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    pipeline: Flags.integer({ description: 'Filter by pipeline ID' }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(StageListCommand)
+    const limit = flags.limit ?? 100
+
+    const query = {
+      pipeline_id: flags.pipeline,
+      limit: Math.min(limit, 100),
+    }
+
+    const items = await collectPages(
+      this.apiClient.pageV2('/api/v2/stages', query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/webhook/create.js

@@ -0,0 +1,75 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { buildWriteBody } from '../../lib/input.js'
+import { outputRecord } from '../../lib/entity-view.js'
+
+export default class WebhookCreateCommand extends BaseCommand {
+  static description = 'Create a webhook'
+
+  static examples = [
+    '<%= config.bin %> webhook create --url https://example.com/hook --event-action change --event-object deal',
+    '<%= config.bin %> webhook create --url https://example.com/hook --event-action "*" --event-object "*"',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    url: Flags.string({
+      required: true,
+      description: 'Webhook subscription URL',
+    }),
+    'event-action': Flags.string({
+      required: true,
+      description: 'Event action to subscribe to',
+      options: ['create', 'change', 'delete', '*'],
+    }),
+    'event-object': Flags.string({
+      required: true,
+      description: 'Event object to subscribe to',
+      options: [
+        'activity',
+        'deal',
+        'lead',
+        'note',
+        'organization',
+        'person',
+        'product',
+        'user',
+        'pipeline',
+        'stage',
+        '*',
+      ],
+    }),
+    name: Flags.string({ description: 'Webhook name' }),
+    version: Flags.string({
+      description: 'Webhook payload version',
+      default: '2.0',
+    }),
+    'http-auth-user': Flags.string({
+      description: 'HTTP basic auth username for the endpoint',
+      dependsOn: ['http-auth-password'],
+    }),
+    'http-auth-password': Flags.string({
+      description: 'HTTP basic auth password for the endpoint',
+      dependsOn: ['http-auth-user'],
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(WebhookCreateCommand)
+
+    const body = buildWriteBody({
+      typed: {
+        subscription_url: flags.url,
+        event_action: flags['event-action'],
+        event_object: flags['event-object'],
+        version: flags.version,
+        name: flags.name,
+        http_auth_user: flags['http-auth-user'],
+        http_auth_password: flags['http-auth-password'],
+      },
+    })
+
+    const res = await this.apiClient.post('/api/v1/webhooks', { body })
+    await outputRecord(this, res.data)
+  }
+}

package/src/commands/webhook/delete.js

@@ -0,0 +1,39 @@
+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 WebhookDeleteCommand extends BaseCommand {
+  static description = 'Delete a webhook'
+
+  static examples = [
+    '<%= config.bin %> webhook delete 3',
+    '<%= config.bin %> webhook delete 3 --yes',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Webhook ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    yes: Flags.boolean({
+      char: 'y',
+      description: 'Skip the confirmation prompt',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(WebhookDeleteCommand)
+
+    const ok = await confirmAction(`Delete webhook ${args.id}?`, flags.yes)
+    if (!ok) {
+      throw new CliError('Aborted', { exitCode: 1 })
+    }
+
+    await this.apiClient.del(`/api/v1/webhooks/${args.id}`)
+    this.log(chalk.green(`Deleted webhook ${args.id}`))
+  }
+}

package/src/commands/webhook/list.js

@@ -0,0 +1,33 @@
+import BaseCommand from '../../base-command.js'
+
+const columns = {
+  id: { header: 'ID' },
+  subscription_url: { header: 'URL' },
+  event_action: { header: 'Action' },
+  event_object: { header: 'Object' },
+  version: { header: 'Version' },
+  is_active: {
+    header: 'Active',
+    get: (row) => row.is_active ?? row.active_flag ?? '',
+  },
+}
+
+export default class WebhookListCommand extends BaseCommand {
+  static description = 'List webhooks'
+
+  static examples = [
+    '<%= config.bin %> webhook list',
+    '<%= config.bin %> webhook list --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    await this.parse(WebhookListCommand)
+
+    const body = await this.apiClient.get('/api/v1/webhooks')
+    await this.outputResults(body.data, columns)
+  }
+}

package/src/lib/backup.js

@@ -0,0 +1,122 @@
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import createDebug from 'debug'
+
+const debug = createDebug('pd:backup')
+
+/**
+ * Everything a full-account export covers. Sequential fetching keeps the
+ * token budget predictable (each list page costs 20 tokens); the client's
+ * 429 backoff handles bursts.
+ * @type {{ name: string, path: string, pager: 'v1' | 'v2' | 'plain' }[]}
+ */
+export const BACKUP_RESOURCES = [
+  { name: 'deals', path: '/api/v2/deals', pager: 'v2' },
+  { name: 'persons', path: '/api/v2/persons', pager: 'v2' },
+  { name: 'organizations', path: '/api/v2/organizations', pager: 'v2' },
+  { name: 'activities', path: '/api/v2/activities', pager: 'v2' },
+  { name: 'products', path: '/api/v2/products', pager: 'v2' },
+  { name: 'pipelines', path: '/api/v2/pipelines', pager: 'v2' },
+  { name: 'stages', path: '/api/v2/stages', pager: 'v2' },
+  { name: 'dealFields', path: '/api/v2/dealFields', pager: 'v2' },
+  { name: 'personFields', path: '/api/v2/personFields', pager: 'v2' },
+  {
+    name: 'organizationFields',
+    path: '/api/v2/organizationFields',
+    pager: 'v2',
+  },
+  { name: 'productFields', path: '/api/v2/productFields', pager: 'v2' },
+  { name: 'activityFields', path: '/api/v2/activityFields', pager: 'v2' },
+  { name: 'leads', path: '/api/v1/leads', pager: 'v1' },
+  { name: 'notes', path: '/api/v1/notes', pager: 'v1' },
+  { name: 'users', path: '/api/v1/users', pager: 'plain' },
+  { name: 'filters', path: '/api/v1/filters', pager: 'plain' },
+  { name: 'webhooks', path: '/api/v1/webhooks', pager: 'plain' },
+  { name: 'currencies', path: '/api/v1/currencies', pager: 'plain' },
+]
+
+const MANIFEST = 'manifest.json'
+
+function readManifest(dir) {
+  const file = join(dir, MANIFEST)
+  if (!existsSync(file)) return { completed: [], counts: {} }
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    return { completed: [], counts: {} }
+  }
+}
+
+function writeManifest(dir, manifest) {
+  writeFileSync(join(dir, MANIFEST), JSON.stringify(manifest, null, 2))
+}
+
+async function fetchResource(client, resource) {
+  if (resource.pager === 'v2') {
+    const items = []
+    for await (const item of client.pageV2(resource.path, { limit: 500 })) {
+      items.push(item)
+    }
+    return items
+  }
+  if (resource.pager === 'v1') {
+    const items = []
+    for await (const item of client.pageV1(resource.path, { limit: 500 })) {
+      items.push(item)
+    }
+    return items
+  }
+  const body = await client.get(resource.path)
+  return body?.data ?? []
+}
+
+/**
+ * Export the whole account to a JSON tree, one file per resource, with a
+ * manifest checkpoint after each resource so interrupted runs can --resume.
+ * @param {ReturnType<import('./client.js').createClient>} client
+ * @param {string} dir target directory (created if missing)
+ * @param {object} [options]
+ * @param {boolean} [options.resume] skip resources already in the manifest
+ * @param {(resource: string, count: number) => void} [options.onProgress]
+ * @returns {Promise<{ total: number, exported: number, skipped: number, counts: Record<string, number> }>}
+ */
+export async function runBackup(client, dir, { resume, onProgress } = {}) {
+  mkdirSync(dir, { recursive: true })
+
+  const manifest = resume
+    ? readManifest(dir)
+    : { started_at: new Date().toISOString(), completed: [], counts: {} }
+
+  let exported = 0
+  let skipped = 0
+
+  for (const resource of BACKUP_RESOURCES) {
+    if (resume && manifest.completed.includes(resource.name)) {
+      debug('skip %s (already in manifest)', resource.name)
+      skipped++
+      continue
+    }
+
+    debug('exporting %s', resource.name)
+    const items = await fetchResource(client, resource)
+    writeFileSync(
+      join(dir, `${resource.name}.json`),
+      JSON.stringify(items, null, 2),
+    )
+
+    manifest.completed.push(resource.name)
+    manifest.counts[resource.name] = items.length
+    manifest.updated_at = new Date().toISOString()
+    writeManifest(dir, manifest)
+
+    exported++
+    onProgress?.(resource.name, items.length)
+  }
+
+  return {
+    total: BACKUP_RESOURCES.length,
+    exported,
+    skipped,
+    counts: manifest.counts,
+  }
+}

package/src/lib/bulk.js

@@ -0,0 +1,106 @@
+import createDebug from 'debug'
+import { CliError } from './errors.js'
+
+const debug = createDebug('pd:bulk')
+
+/**
+ * Resolve the target ids for a bulk operation from exactly one selector:
+ * --ids "1,2,3", a Pipedrive saved filter (--filter <id>), or piped stdin
+ * (newline-separated ids, a JSON array of ids, or JSON objects with an id).
+ * @param {object} selectors
+ * @param {string} [selectors.ids]
+ * @param {number} [selectors.filter]
+ * @param {NodeJS.ReadStream} [selectors.stdin] defaults to process.stdin
+ * @param {ReturnType<import('./client.js').createClient>} client
+ * @param {string} listPath v2 list endpoint supporting filter_id (e.g. /api/v2/deals)
+ * @returns {Promise<number[]>}
+ */
+export async function resolveTargets(
+  { ids, filter, stdin = process.stdin },
+  client,
+  listPath,
+) {
+  if (ids) {
+    return ids.split(',').map(parseId)
+  }
+
+  if (filter != null) {
+    debug('resolving targets from filter %d', filter)
+    const targets = []
+    for await (const item of client.pageV2(listPath, {
+      filter_id: filter,
+      limit: 500,
+    })) {
+      targets.push(item.id)
+    }
+    return targets
+  }
+
+  if (!stdin.isTTY) {
+    const chunks = []
+    for await (const chunk of stdin) chunks.push(chunk)
+    const text = Buffer.concat(chunks).toString('utf8').trim()
+    if (text.startsWith('[')) {
+      const parsed = JSON.parse(text)
+      return parsed.map((entry) =>
+        typeof entry === 'object' ? entry.id : parseId(String(entry)),
+      )
+    }
+    return text.split('\n').map(parseId)
+  }
+
+  throw new CliError(
+    'No targets — pass --ids, --filter, or pipe ids on stdin',
+    { exitCode: 64 },
+  )
+}
+
+function parseId(raw) {
+  const id = Number(raw.trim())
+  if (!Number.isInteger(id)) {
+    throw new CliError(`Invalid id "${raw.trim()}" — expected an integer`, {
+      exitCode: 64,
+    })
+  }
+  return id
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Run an async operation per item, sequentially with a pacing gap so bulk
+ * writes stay inside Pipedrive's 2-second burst window (writes cost 10
+ * tokens each; the client's 429 backoff covers anything that slips through).
+ * Per-item failures are collected, never thrown.
+ * @template T
+ * @param {T[]} items
+ * @param {(item: T) => Promise<unknown>} operation
+ * @param {object} [options]
+ * @param {number} [options.gapMs] delay between requests (default 200)
+ * @param {(done: number, total: number) => void} [options.onProgress]
+ * @returns {Promise<{ succeeded: { item: T, result: unknown }[], failed: { item: T, error: string }[] }>}
+ */
+export async function bulkRun(
+  items,
+  operation,
+  { gapMs = 200, onProgress } = {},
+) {
+  const succeeded = []
+  const failed = []
+
+  for (const [index, item] of items.entries()) {
+    if (index > 0 && gapMs > 0) await sleep(gapMs)
+    try {
+      const result = await operation(item)
+      succeeded.push({ item, result })
+    } catch (err) {
+      debug('bulk item %o failed: %s', item, err.message)
+      failed.push({ item, error: err.message })
+    }
+    onProgress?.(index + 1, items.length)
+  }
+
+  return { succeeded, failed }
+}