@wavyx/pdcli 0.1.0

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@wavyx/pdcli",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Command-line interface for Pipedrive",
+  "type": "module",
+  "license": "MIT",
+  "author": "Eric Rodriguez",
+  "homepage": "https://github.com/wavyx/pdcli",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wavyx/pdcli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wavyx/pdcli/issues"
+  },
+  "bin": {
+    "pdcli": "./bin/run.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "oclif.manifest.json",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "pipedrive",
+    "crm",
+    "cli",
+    "oclif",
+    "sales",
+    "pipeline",
+    "automation"
+  ],
+  "oclif": {
+    "bin": "pdcli",
+    "dirname": "pdcli",
+    "commands": {
+      "strategy": "pattern",
+      "target": "./src/commands",
+      "globPatterns": [
+        "**/*.js",
+        "!**/*.test.js"
+      ]
+    },
+    "topicSeparator": " ",
+    "topics": {
+      "auth": {
+        "description": "Authentication management"
+      },
+      "deal": {
+        "description": "Deals"
+      },
+      "person": {
+        "description": "Persons (contacts)"
+      },
+      "org": {
+        "description": "Organizations"
+      },
+      "activity": {
+        "description": "Activities (calls, meetings, tasks)"
+      },
+      "field": {
+        "description": "Custom-field discovery and name/key resolution"
+      },
+      "user": {
+        "description": "Users"
+      },
+      "profile": {
+        "description": "Profile management"
+      },
+      "config": {
+        "description": "Configuration"
+      }
+    },
+    "hooks": {
+      "init": "./src/hooks/init",
+      "prerun": "./src/hooks/prerun",
+      "command_not_found": "./src/hooks/command-not-found"
+    },
+    "plugins": [
+      "@oclif/plugin-help",
+      "@oclif/plugin-plugins",
+      "@oclif/plugin-autocomplete"
+    ]
+  },
+  "dependencies": {
+    "@inquirer/prompts": "8.5.0",
+    "@napi-rs/keyring": "1.3.0",
+    "@oclif/core": "4.11.4",
+    "@oclif/plugin-autocomplete": "3.2.50",
+    "@oclif/plugin-help": "6.2.49",
+    "@oclif/plugin-plugins": "5.4.69",
+    "chalk": "5.6.2",
+    "cli-table3": "0.6.5",
+    "conf": "15.1.0",
+    "debug": "4.4.3",
+    "ora": "9.4.0",
+    "undici": "8.3.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@oclif/test": "4.1.18",
+    "@vitest/coverage-v8": "4.1.7",
+    "eslint": "10.4.0",
+    "globals": "17.6.0",
+    "nock": "14.0.15",
+    "oclif": "4.23.8",
+    "prettier": "3.8.3",
+    "vitest": "4.1.7"
+  },
+  "scripts": {
+    "build": "oclif manifest",
+    "docs:commands": "node scripts/gen-commands.mjs",
+    "lint": "eslint . && prettier --check .",
+    "lint:fix": "eslint --fix . && prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "npm run build",
+    "postpack": "rm -f oclif.manifest.json"
+  }
+}

package/src/base-command.js

@@ -0,0 +1,99 @@
+import { Command, Flags } from '@oclif/core'
+import { formatOutput } from './lib/output/index.js'
+import { loadConfig } from './lib/config.js'
+import { resolveCredentials } from './lib/auth.js'
+import { createClient } from './lib/client.js'
+import { handleError } from './lib/errors.js'
+
+export default class BaseCommand extends Command {
+  static baseFlags = {
+    output: Flags.string({
+      char: 'o',
+      description: 'Output format',
+      helpGroup: 'GLOBAL',
+      options: ['table', 'json'],
+    }),
+    profile: Flags.string({
+      description: 'Named auth profile to use',
+      helpGroup: 'GLOBAL',
+      env: 'PDCLI_PROFILE',
+    }),
+    'no-color': Flags.boolean({
+      description: 'Disable color output',
+      helpGroup: 'GLOBAL',
+    }),
+    verbose: Flags.boolean({
+      description: 'Show detailed API request/response on errors',
+      helpGroup: 'GLOBAL',
+      default: false,
+    }),
+    'no-retry': Flags.boolean({
+      description: 'Disable automatic retry on rate limits and 5xx errors',
+      helpGroup: 'GLOBAL',
+      default: false,
+    }),
+    timeout: Flags.integer({
+      description: 'Request timeout in milliseconds',
+      helpGroup: 'GLOBAL',
+    }),
+    limit: Flags.integer({
+      description: 'Maximum number of items to return (lists)',
+      helpGroup: 'GLOBAL',
+    }),
+  }
+
+  /** @type {string} */
+  activeProfile
+  /** @type {ReturnType<import('./lib/client.js').createClient>} */
+  apiClient
+
+  async init() {
+    await super.init()
+    const { flags } = await this.parse(/** @type {any} */ (this.constructor))
+    this.flags = flags
+
+    if (flags['no-color'] || process.env.NO_COLOR) {
+      process.env.FORCE_COLOR = '0'
+    }
+
+    if (flags.verbose) {
+      process.env.DEBUG = process.env.DEBUG
+        ? `${process.env.DEBUG},pd:*`
+        : 'pd:*'
+    }
+
+    const config = loadConfig(flags.profile)
+    this.activeProfile = config.activeProfile
+
+    if (this.constructor.skipAuth) return
+
+    const { companyDomain, token } = await resolveCredentials({
+      flags,
+      profile: this.activeProfile,
+    })
+    this.apiClient = createClient({
+      companyDomain,
+      token,
+      retry: !flags['no-retry'],
+      timeout: flags.timeout,
+      userAgent: `pdcli/${this.config.version}`,
+    })
+  }
+
+  /** Effective output format: explicit flag, else table in a TTY, json piped. */
+  resolveFormat() {
+    return this.flags.output ?? (process.stdout.isTTY ? 'table' : 'json')
+  }
+
+  /**
+   * @param {object | object[]} data
+   * @param {Record<string, import('./lib/output/table.js').Column>} columns
+   */
+  async outputResults(data, columns) {
+    formatOutput(data, columns, this.resolveFormat(), this)
+  }
+
+  async catch(err) {
+    handleError(err, this)
+  }
+}

package/src/commands/activity/get.js

@@ -0,0 +1,41 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { getFields, makeResolver } from '../../lib/fields.js'
+import { flattenRecord } from '../../lib/output/record.js'
+
+export default class ActivityGetCommand extends BaseCommand {
+  static description = 'Get an activity by ID'
+
+  static examples = [
+    '<%= config.bin %> activity get 9',
+    '<%= config.bin %> activity get 9 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Activity ID' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(ActivityGetCommand)
+    const body = await this.apiClient.get(`/api/v2/activities/${args.id}`)
+    let record = body.data
+
+    if (this.resolveFormat() === 'table') {
+      if (record.custom_fields && Object.keys(record.custom_fields).length) {
+        const defs = await getFields(this.apiClient, 'activity')
+        record = makeResolver(defs).resolveCustomFields(record)
+      }
+      await this.outputResults(flattenRecord(record), {
+        field: { header: 'Field' },
+        value: { header: 'Value' },
+      })
+      return
+    }
+
+    await this.outputResults(record, {})
+  }
+}

package/src/commands/activity/list.js

@@ -0,0 +1,61 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { collectPages } from '../../lib/pagination.js'
+
+const columns = {
+  id: { header: 'ID' },
+  subject: { header: 'Subject' },
+  type: { header: 'Type' },
+  due_date: { header: 'Due' },
+  done: { header: 'Done' },
+  deal_id: { header: 'Deal' },
+  owner_id: { header: 'Owner' },
+}
+
+export default class ActivityListCommand extends BaseCommand {
+  static description = 'List activities'
+
+  static examples = [
+    '<%= config.bin %> activity list',
+    '<%= config.bin %> activity list --todo --deal 42',
+    '<%= config.bin %> activity list --type call --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    owner: Flags.integer({ description: 'Filter by owner (user) ID' }),
+    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' }),
+    done: Flags.boolean({
+      description: 'Only completed activities',
+      exclusive: ['todo'],
+    }),
+    todo: Flags.boolean({
+      description: 'Only open (not done) activities',
+      exclusive: ['done'],
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(ActivityListCommand)
+    const limit = flags.limit ?? 100
+
+    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),
+    }
+
+    const items = await collectPages(
+      this.apiClient.pageV2('/api/v2/activities', query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/api.js

@@ -0,0 +1,60 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../base-command.js'
+import { resolveBody } from '../lib/body.js'
+
+export default class ApiCommand extends BaseCommand {
+  static description =
+    'Make a raw API request (host-locked to your Pipedrive company domain)'
+
+  static examples = [
+    '<%= config.bin %> api GET /api/v2/deals',
+    '<%= config.bin %> api GET /api/v1/currencies',
+    '<%= config.bin %> api POST /api/v2/deals --body \'{"title":"New deal"}\'',
+    '<%= config.bin %> api DELETE /api/v1/webhooks/1',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    body: Flags.string({
+      description: 'Request body (JSON string, @file, or pipe stdin)',
+    }),
+  }
+
+  static args = {
+    method: Args.string({
+      required: true,
+      description: 'HTTP method',
+      options: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+    }),
+    path: Args.string({
+      required: true,
+      description: 'API path (e.g. /api/v2/deals — v1 and v2 both work)',
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(ApiCommand)
+
+    const methodMap = {
+      GET: 'get',
+      POST: 'post',
+      PUT: 'put',
+      PATCH: 'patch',
+      DELETE: 'del',
+    }
+
+    const method = methodMap[args.method]
+    const opts = {}
+
+    if (flags.body && !['GET', 'DELETE'].includes(args.method)) {
+      const bodyText = await resolveBody(flags)
+      opts.body = JSON.parse(bodyText)
+    }
+
+    const data = await this.apiClient[method](args.path, opts)
+
+    if (data !== null) {
+      this.log(JSON.stringify(data, null, 2))
+    }
+  }
+}

package/src/commands/auth/login.js

@@ -0,0 +1,79 @@
+import { Flags } from '@oclif/core'
+import { input, password } from '@inquirer/prompts'
+import chalk from 'chalk'
+import ora from 'ora'
+import BaseCommand from '../../base-command.js'
+import { normalizeCompanyDomain, validateToken } from '../../lib/auth.js'
+import { createClient } from '../../lib/client.js'
+import { setToken } from '../../lib/keychain.js'
+import { setProfileConfig } from '../../lib/config.js'
+
+export default class LoginCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description =
+    'Authenticate with Pipedrive using your personal API token'
+
+  static examples = [
+    '<%= config.bin %> auth login',
+    '<%= config.bin %> auth login --company acme --api-token <token>',
+    '<%= config.bin %> auth login --profile work',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    company: Flags.string({
+      description:
+        'Company domain ("acme" from acme.pipedrive.com — full URL accepted)',
+    }),
+    'api-token': Flags.string({
+      description:
+        'Personal API token (app.pipedrive.com/settings/api). Prefer the prompt or env so the token stays out of shell history',
+    }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(LoginCommand)
+
+    const rawDomain =
+      flags.company ??
+      (await input({
+        message: 'Company domain (e.g. "acme" from acme.pipedrive.com):',
+      }))
+    const companyDomain = normalizeCompanyDomain(rawDomain)
+
+    const token =
+      flags['api-token'] ??
+      (await password({
+        message: 'API token (app.pipedrive.com/settings/api):',
+        mask: true,
+      }))
+
+    const spinner = ora('Validating token...').start()
+    let user
+    try {
+      const client = createClient({
+        companyDomain,
+        token,
+        userAgent: `pdcli/${this.config.version}`,
+      })
+      user = await validateToken(client)
+      spinner.stop()
+    } catch (err) {
+      spinner.stop()
+      throw err
+    }
+
+    // Token only ever goes to the OS keychain; the domain lives in config.
+    await setToken(this.activeProfile, token)
+    setProfileConfig(this.activeProfile, 'company_domain', companyDomain)
+
+    this.log(
+      chalk.green(
+        `Logged in to ${chalk.cyan(`${companyDomain}.pipedrive.com`)} ` +
+          `as ${chalk.bold(user.name)} (${user.email})`,
+      ),
+    )
+    this.log(chalk.dim(`Profile: ${this.activeProfile} — token in keychain`))
+  }
+}

package/src/commands/auth/logout.js

@@ -0,0 +1,24 @@
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { deleteToken } from '../../lib/keychain.js'
+
+export default class LogoutCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Log out and remove the stored API token'
+
+  static examples = ['<%= config.bin %> auth logout']
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    await this.parse(LogoutCommand)
+
+    await deleteToken(this.activeProfile)
+    this.log(
+      chalk.green(`Logged out of profile ${chalk.cyan(this.activeProfile)}`),
+    )
+  }
+}

package/src/commands/auth/status.js

@@ -0,0 +1,62 @@
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { getToken, isKeychainAvailable } from '../../lib/keychain.js'
+import { getProfileConfig } from '../../lib/config.js'
+import { companyDomainToBaseOrigin, validateToken } from '../../lib/auth.js'
+import { createClient } from '../../lib/client.js'
+
+export default class StatusCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Show current authentication status'
+
+  static examples = ['<%= config.bin %> auth status']
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    await this.parse(StatusCommand)
+
+    const domain = getProfileConfig(this.activeProfile, 'company_domain')
+    const token = await getToken(this.activeProfile)
+    const keychainType = isKeychainAvailable() ? 'OS keychain' : 'unavailable'
+
+    this.log(chalk.bold('Auth Status'))
+    this.log('')
+    this.log(`  Profile:    ${chalk.cyan(this.activeProfile)}`)
+    this.log(`  Keychain:   ${keychainType}`)
+    this.log(
+      `  API host:   ${domain ? companyDomainToBaseOrigin(domain) : chalk.dim('(not set)')}`,
+    )
+
+    if (!token) {
+      this.log(`  Status:     ${chalk.red('Not authenticated')}`)
+      this.log('')
+      this.log(`Run ${chalk.cyan('pdcli auth login')} to authenticate.`)
+      return
+    }
+
+    this.log(`  Token:      ${chalk.green('present')} (keychain)`)
+
+    // Best-effort identity check — network errors are not fatal here.
+    if (domain) {
+      try {
+        const client = createClient({
+          companyDomain: domain,
+          token,
+          retry: false,
+          userAgent: `pdcli/${this.config.version}`,
+        })
+        const user = await validateToken(client)
+        this.log('')
+        this.log(chalk.bold('  Authenticated User'))
+        if (user.name) this.log(`  Name:       ${user.name}`)
+        if (user.email) this.log(`  Email:      ${user.email}`)
+      } catch {
+        // Silently ignore — identity display is best-effort
+      }
+    }
+  }
+}

package/src/commands/config/get.js

@@ -0,0 +1,30 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { getProfileConfig } from '../../lib/config.js'
+
+export default class ConfigGetCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Get a config value for the active profile'
+
+  static examples = [
+    '<%= config.bin %> config get company_domain',
+    '<%= config.bin %> config get default_output',
+  ]
+
+  static args = {
+    key: Args.string({ required: true, description: 'Config key to read' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(ConfigGetCommand)
+
+    const value = getProfileConfig(this.activeProfile, args.key)
+
+    if (value === undefined) {
+      this.log('not set')
+    } else {
+      this.log(String(value))
+    }
+  }
+}

package/src/commands/config/list.js

@@ -0,0 +1,25 @@
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { getProfileData } from '../../lib/config.js'
+
+export default class ConfigListCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'List all config for the active profile'
+
+  static examples = ['<%= config.bin %> config list']
+
+  async run() {
+    const data = getProfileData(this.activeProfile)
+    const entries = Object.entries(data)
+
+    if (entries.length === 0) {
+      this.log(`No config set for profile ${chalk.cyan(this.activeProfile)}`)
+      return
+    }
+
+    for (const [key, value] of entries) {
+      this.log(`${key}=${value}`)
+    }
+  }
+}

package/src/commands/config/set.js

@@ -0,0 +1,29 @@
+import { Args } from '@oclif/core'
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { setProfileConfig } from '../../lib/config.js'
+
+export default class ConfigSetCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Set a config value for the active profile'
+
+  static examples = [
+    '<%= config.bin %> config set company_domain acme',
+    '<%= config.bin %> config set default_output json',
+  ]
+
+  static args = {
+    key: Args.string({ required: true, description: 'Config key to set' }),
+    value: Args.string({ required: true, description: 'Value to assign' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(ConfigSetCommand)
+
+    setProfileConfig(this.activeProfile, args.key, args.value)
+    this.log(
+      `Set ${chalk.cyan(args.key)} = ${chalk.green(args.value)} for profile ${chalk.cyan(this.activeProfile)}`,
+    )
+  }
+}

package/src/commands/deal/get.js

@@ -0,0 +1,43 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { getFields, makeResolver } from '../../lib/fields.js'
+import { flattenRecord } from '../../lib/output/record.js'
+
+export default class DealGetCommand extends BaseCommand {
+  static description = 'Get a deal by ID'
+
+  static examples = [
+    '<%= config.bin %> deal get 42',
+    '<%= config.bin %> deal get 42 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Deal ID' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(DealGetCommand)
+    const body = await this.apiClient.get(`/api/v2/deals/${args.id}`)
+    let record = body.data
+
+    if (this.resolveFormat() === 'table') {
+      // Table view resolves custom-field hash keys to names and option IDs
+      // to labels; JSON output stays raw for scripting.
+      if (record.custom_fields && Object.keys(record.custom_fields).length) {
+        const defs = await getFields(this.apiClient, 'deal')
+        record = makeResolver(defs).resolveCustomFields(record)
+      }
+      await this.outputResults(flattenRecord(record), {
+        field: { header: 'Field' },
+        value: { header: 'Value' },
+      })
+      return
+    }
+
+    await this.outputResults(record, {})
+  }
+}