@wavyx/pdcli 0.1.0

package/src/hooks/prerun.js

@@ -0,0 +1,7 @@
+import createDebug from 'debug'
+
+const debug = createDebug('pd:prerun')
+
+export default async function prerun(options) {
+  debug('prerun: %s', options.Command?.id)
+}

package/src/lib/auth.js

@@ -0,0 +1,95 @@
+import createDebug from 'debug'
+import { getToken } from './keychain.js'
+import { getProfileConfig } from './config.js'
+import { AuthRequiredError, ConfigError } from './errors.js'
+
+const debug = createDebug('pd:auth')
+
+/**
+ * Normalize user input ("acme", "acme.pipedrive.com",
+ * "https://acme.pipedrive.com/") to the bare company subdomain.
+ * @param {string} input
+ * @returns {string}
+ */
+export function normalizeCompanyDomain(input) {
+  return input
+    .trim()
+    .replace(/^https?:\/\//, '')
+    .replace(/\.pipedrive\.com\/?.*$/, '')
+}
+
+/**
+ * @param {string} companyDomain
+ * @returns {string}
+ */
+export function companyDomainToBaseOrigin(companyDomain) {
+  return `https://${companyDomain}.pipedrive.com`
+}
+
+/**
+ * @typedef {object} ResolvedCredentials
+ * @property {string} companyDomain
+ * @property {string} token
+ * @property {'flags' | 'env' | 'profile'} source Where the token came from.
+ */
+
+/**
+ * Resolve company domain and API token independently, each with
+ * flags → env → profile-config/keychain precedence.
+ * @param {object} options
+ * @param {object} [options.flags]
+ * @param {string} [options.flags.company]
+ * @param {string} [options.flags."api-token"]
+ * @param {string} [options.profile]
+ * @returns {Promise<ResolvedCredentials>}
+ */
+export async function resolveCredentials({ flags, profile } = {}) {
+  let companyDomain
+  if (flags?.company) {
+    companyDomain = flags.company
+  } else if (process.env.PDCLI_COMPANY_DOMAIN) {
+    companyDomain = process.env.PDCLI_COMPANY_DOMAIN
+  } else if (profile) {
+    companyDomain = getProfileConfig(profile, 'company_domain')
+  }
+
+  if (!companyDomain) {
+    throw new ConfigError(
+      'No company domain configured. Run: pdcli auth login ' +
+        '(or set PDCLI_COMPANY_DOMAIN)',
+    )
+  }
+  companyDomain = normalizeCompanyDomain(companyDomain)
+
+  let token
+  let source
+  if (flags?.['api-token']) {
+    token = flags['api-token']
+    source = 'flags'
+  } else if (process.env.PDCLI_API_TOKEN) {
+    token = process.env.PDCLI_API_TOKEN
+    source = 'env'
+  } else if (profile) {
+    token = await getToken(profile)
+    source = 'profile'
+  }
+
+  if (!token) {
+    throw new AuthRequiredError()
+  }
+
+  debug('resolved credentials for %s (token from %s)', companyDomain, source)
+  return { companyDomain, token, source }
+}
+
+/**
+ * Validate a token by fetching the authenticated user.
+ * Note: the Users API has no v2 equivalent (June 2026) — /api/v2/users/me
+ * 404s into the web app's HTML page, so this must stay on v1.
+ * @param {{ get: (path: string) => Promise<{data: object}> }} client
+ * @returns {Promise<object>} the Pipedrive user object
+ */
+export async function validateToken(client) {
+  const body = await client.get('/api/v1/users/me')
+  return body.data
+}

package/src/lib/body.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs'
+import { CliError } from './errors.js'
+
+/**
+ * @param {object} flags
+ * @param {string} [flags.body]
+ * @returns {Promise<string>}
+ */
+export async function resolveBody(flags) {
+  if (flags.body) {
+    if (flags.body.startsWith('@')) {
+      return readFileSync(flags.body.slice(1), 'utf8')
+    }
+    return flags.body
+  }
+
+  if (!process.stdin.isTTY) {
+    const chunks = []
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk)
+    }
+    return Buffer.concat(chunks).toString('utf8').trim()
+  }
+
+  throw new CliError('--body is required', { exitCode: 2 })
+}

package/src/lib/client.js

@@ -0,0 +1,184 @@
+import createDebug from 'debug'
+import {
+  ApiError,
+  CliError,
+  RateLimitError,
+  ServiceUnavailableError,
+} from './errors.js'
+import { companyDomainToBaseOrigin } from './auth.js'
+
+const debug = createDebug('pd:client')
+
+/** Pipedrive caps list/search page sizes at 500. */
+const MAX_PAGE_LIMIT = 500
+/** Default seconds to wait on a 429 without rate-limit headers (2s burst window). */
+const DEFAULT_RETRY_AFTER_S = 2
+
+function jitter() {
+  return Math.floor(Math.random() * 1000)
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function clampLimit(query) {
+  if (query?.limit && Number(query.limit) > MAX_PAGE_LIMIT) {
+    return { ...query, limit: MAX_PAGE_LIMIT }
+  }
+  return query
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.companyDomain Bare subdomain ("acme") — forms and
+ *   locks the base origin https://acme.pipedrive.com.
+ * @param {string} options.token Personal API token (sent as x-api-token).
+ * @param {number} [options.timeout]
+ * @param {boolean} [options.retry]
+ * @param {string} [options.userAgent]
+ */
+export function createClient({
+  companyDomain,
+  token,
+  timeout = 30_000,
+  retry = true,
+  userAgent = 'pdcli',
+}) {
+  const baseOrigin = companyDomainToBaseOrigin(companyDomain)
+
+  async function request(method, path, { body, query } = {}) {
+    const url = new URL(path, baseOrigin)
+    if (url.origin !== baseOrigin) {
+      throw new CliError(
+        `Refusing to send request outside your Pipedrive company host ` +
+          `(${baseOrigin}): ${url.origin}`,
+        { exitCode: 78 },
+      )
+    }
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v == null) continue
+        if (Array.isArray(v)) {
+          url.searchParams.set(k, v.join(','))
+        } else {
+          url.searchParams.set(k, String(v))
+        }
+      }
+    }
+
+    const maxAttempts = retry ? 3 : 1
+    let attempts = 0
+    let sawRateLimit = false
+
+    while (attempts < maxAttempts) {
+      attempts++
+
+      const headers = {
+        'x-api-token': token,
+        'content-type': 'application/json',
+        'user-agent': userAgent,
+      }
+
+      const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(timeout),
+      })
+
+      debug('%s %s → %d', method, path, res.status)
+
+      if (res.status === 429) {
+        const wait = Number(
+          res.headers.get('x-ratelimit-reset') ||
+            res.headers.get('retry-after') ||
+            DEFAULT_RETRY_AFTER_S,
+        )
+        if (!retry) throw new RateLimitError(wait)
+        sawRateLimit = true
+        debug('rate limited, waiting %ds', wait)
+        await sleep(wait * 1000)
+        continue
+      }
+
+      // Pipedrive escalates persistent rate-limit abuse from 429 to 403 —
+      // treat that as a hard stop, never retry into it.
+      if (res.status === 403 && sawRateLimit) {
+        const text = await res.text()
+        const err = ApiError.fromResponse(res.status, text, path)
+        err.message += ' (403 after 429: rate-limit escalation — stopping)'
+        throw err
+      }
+
+      if (res.status >= 500 && attempts < maxAttempts) {
+        const delay = Math.min(1000 * 2 ** attempts, 30_000) + jitter()
+        debug('server error %d, retrying in %dms', res.status, delay)
+        await sleep(delay)
+        continue
+      }
+
+      if (res.status === 204) return null
+
+      const text = await res.text()
+
+      if (!res.ok) {
+        throw ApiError.fromResponse(res.status, text, path)
+      }
+
+      return text ? JSON.parse(text) : null
+    }
+
+    throw new ServiceUnavailableError()
+  }
+
+  /**
+   * v2 cursor pagination: cursor/limit → additional_data.next_cursor.
+   * @param {string} path
+   * @param {object} [query]
+   * @returns {AsyncGenerator<object>}
+   */
+  async function* pageV2(path, query = {}) {
+    let cursor
+    const baseQuery = clampLimit(query)
+    while (true) {
+      const envelope = await request('GET', path, {
+        query: cursor ? { ...baseQuery, cursor } : baseQuery,
+      })
+      yield* envelope?.data ?? []
+      cursor = envelope?.additional_data?.next_cursor
+      if (!cursor) break
+    }
+  }
+
+  /**
+   * v1 offset pagination: start/limit →
+   * additional_data.pagination.{more_items_in_collection,next_start}.
+   * @param {string} path
+   * @param {object} [query]
+   * @returns {AsyncGenerator<object>}
+   */
+  async function* pageV1(path, query = {}) {
+    let start
+    const baseQuery = clampLimit(query)
+    while (true) {
+      const envelope = await request('GET', path, {
+        query: start != null ? { ...baseQuery, start } : baseQuery,
+      })
+      yield* envelope?.data ?? []
+      const pagination = envelope?.additional_data?.pagination
+      if (!pagination?.more_items_in_collection) break
+      start = pagination.next_start
+    }
+  }
+
+  return {
+    get: (path, opts) => request('GET', path, opts),
+    post: (path, opts) => request('POST', path, opts),
+    put: (path, opts) => request('PUT', path, opts),
+    patch: (path, opts) => request('PATCH', path, opts),
+    del: (path, opts) => request('DELETE', path, opts),
+    pageV1,
+    pageV2,
+  }
+}

package/src/lib/config.js

@@ -0,0 +1,71 @@
+import Conf from 'conf'
+
+const schema = {
+  activeProfile: { type: 'string', default: 'default' },
+  profiles: {
+    type: 'object',
+    default: {},
+  },
+}
+
+/** @type {Conf | undefined} */
+let _conf
+
+export function getConf() {
+  _conf ??= new Conf({ projectName: 'pdcli', schema })
+  return _conf
+}
+
+/**
+ * @param {string} [profileFlag]
+ * @returns {{ activeProfile: string, [key: string]: unknown }}
+ */
+export function loadConfig(profileFlag) {
+  const conf = getConf()
+  const activeProfile = profileFlag ?? conf.get('activeProfile')
+  const profileData = conf.get(`profiles.${activeProfile}`) ?? {}
+  return { activeProfile, ...profileData }
+}
+
+export function getActiveProfile() {
+  return getConf().get('activeProfile')
+}
+
+/** @param {string} name */
+export function setActiveProfile(name) {
+  getConf().set('activeProfile', name)
+}
+
+/**
+ * @param {string} profile
+ * @param {string} key
+ */
+export function getProfileConfig(profile, key) {
+  return getConf().get(`profiles.${profile}.${key}`)
+}
+
+/**
+ * @param {string} profile
+ * @param {string} key
+ * @param {unknown} value
+ */
+export function setProfileConfig(profile, key, value) {
+  getConf().set(`profiles.${profile}.${key}`, value)
+}
+
+/** @param {string} profile */
+export function getProfileData(profile) {
+  return getConf().get(`profiles.${profile}`) ?? {}
+}
+
+export function getAllProfiles() {
+  return getConf().get('profiles')
+}
+
+/**
+ * @param {string} profile
+ * @param {string} key
+ */
+export function deleteProfileConfig(profile, key) {
+  getConf().delete(`profiles.${profile}.${key}`)
+}

package/src/lib/errors.js

@@ -0,0 +1,118 @@
+export class CliError extends Error {
+  /** @param {string} message @param {{exitCode?: number, cause?: Error}} [options] */
+  constructor(message, { exitCode = 1, cause } = {}) {
+    super(message, { cause })
+    this.exitCode = exitCode
+  }
+}
+
+export class AuthRequiredError extends CliError {
+  constructor() {
+    super('Not authenticated. Run: pdcli auth login', { exitCode: 77 })
+  }
+}
+
+export class ConfigError extends CliError {
+  /** @param {string} message */
+  constructor(message) {
+    super(message, { exitCode: 78 })
+  }
+}
+
+export class RateLimitError extends CliError {
+  /** @param {number} retryAfter */
+  constructor(retryAfter) {
+    super(`Rate limited. Retry after ${retryAfter}s`, { exitCode: 75 })
+    this.retryAfter = retryAfter
+  }
+}
+
+export class ServiceUnavailableError extends CliError {
+  constructor() {
+    super('Pipedrive API is unavailable', { exitCode: 69 })
+  }
+}
+
+/** Exit-code ladder per spec §9 (sysexits). */
+function exitCodeForStatus(statusCode) {
+  if (statusCode === 400 || statusCode === 422) return 65
+  if (statusCode === 401 || statusCode === 403) return 77
+  if (statusCode === 402) return 78
+  if (statusCode === 429) return 75
+  if (statusCode >= 500) return 69
+  return 1
+}
+
+export class ApiError extends CliError {
+  /**
+   * @param {number} statusCode
+   * @param {object} body Pipedrive error envelope { success, error, error_info }
+   * @param {string} path
+   */
+  constructor(statusCode, body, path) {
+    const message = body?.error || body?.message || `API error ${statusCode}`
+
+    super(`Pipedrive API ${statusCode}: ${message}`, {
+      exitCode: exitCodeForStatus(statusCode),
+    })
+    this.statusCode = statusCode
+    this.path = path
+    this.body = body
+    this.errorInfo = body?.error_info
+  }
+
+  /**
+   * @param {number} statusCode
+   * @param {string} text
+   * @param {string} path
+   */
+  static fromResponse(statusCode, text, path) {
+    let body
+    try {
+      body = JSON.parse(text)
+    } catch {
+      // Non-JSON bodies (e.g. HTML error pages) can be huge — truncate.
+      const truncated = text.length > 200 ? `${text.slice(0, 200)}…` : text
+      body = { message: truncated }
+    }
+    return new ApiError(statusCode, body, path)
+  }
+}
+
+/**
+ * @param {Error} err
+ * @param {import('@oclif/core').Command} cmd
+ */
+export function handleError(err, cmd) {
+  const exitCode = err.exitCode ?? 70
+  const flags = cmd.flags ?? {}
+
+  if (flags.output === 'json') {
+    const payload = {
+      error: err.constructor.name,
+      message: err.message,
+      exitCode,
+    }
+    if (err instanceof ApiError) {
+      payload.statusCode = err.statusCode
+      payload.path = err.path
+      if (err.errorInfo) payload.errorInfo = err.errorInfo
+      if (flags.verbose) payload.body = err.body
+    }
+    process.stderr.write(JSON.stringify(payload, null, 2) + '\n')
+    cmd.exit(exitCode)
+  }
+
+  if (flags.verbose && err instanceof ApiError) {
+    process.stderr.write(`\nRequest path: ${err.path}\n`)
+    process.stderr.write(`Status code:  ${err.statusCode}\n`)
+    if (err.errorInfo) process.stderr.write(`Error info:   ${err.errorInfo}\n`)
+    if (err.body) {
+      process.stderr.write(
+        `Response body:\n${JSON.stringify(err.body, null, 2)}\n`,
+      )
+    }
+  }
+
+  cmd.error(err.message, { exit: exitCode })
+}

package/src/lib/fields.js

@@ -0,0 +1,120 @@
+import createDebug from 'debug'
+import { CliError } from './errors.js'
+
+const debug = createDebug('pd:fields')
+
+/** Entity (and aliases) → v2 fields endpoint. */
+const ENTITY_FIELDS = {
+  deal: 'dealFields',
+  person: 'personFields',
+  org: 'organizationFields',
+  organization: 'organizationFields',
+  product: 'productFields',
+  activity: 'activityFields',
+}
+
+/**
+ * @param {string} entity deal | person | org(anization) | product | activity
+ * @returns {string} v2 fields endpoint path
+ */
+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}`
+}
+
+/** @type {Map<string, object[]>} per-run field-definition cache */
+const cache = new Map()
+
+export function clearFieldsCache() {
+  cache.clear()
+}
+
+/**
+ * Fetch (and memoize for this run) all field definitions for an entity.
+ * @param {{ pageV2: (path: string) => AsyncGenerator<object> }} client
+ * @param {string} entity
+ * @returns {Promise<object[]>}
+ */
+export async function getFields(client, entity) {
+  const path = entityToFieldsPath(entity)
+  if (cache.has(path)) return cache.get(path)
+
+  debug('fetching field definitions: %s', path)
+  const defs = []
+  for await (const def of client.pageV2(path)) {
+    defs.push(def)
+  }
+  cache.set(path, defs)
+  return defs
+}
+
+/**
+ * Build a resolver for name⇄key and option label⇄ID lookups.
+ * @param {object[]} defs v2 field definitions
+ *   ({ field_code, field_name, field_type, options })
+ */
+export function makeResolver(defs) {
+  const byName = new Map()
+  const byKey = new Map()
+  for (const def of defs) {
+    byName.set(def.field_name.toLowerCase(), def)
+    byKey.set(def.field_code, def)
+  }
+
+  function optionsOf(fieldKey) {
+    return byKey.get(fieldKey)?.options
+  }
+
+  return {
+    /** @param {string} name @returns {string | undefined} hashed key */
+    nameToKey(name) {
+      return byName.get(name.toLowerCase())?.field_code
+    },
+
+    /** @param {string} key @returns {string | undefined} human name */
+    keyToName(key) {
+      return byKey.get(key)?.field_name
+    },
+
+    /** @param {string} fieldKey @param {string} label @returns {number | undefined} */
+    labelToOptionId(fieldKey, label) {
+      return optionsOf(fieldKey)?.find(
+        (o) => o.label.toLowerCase() === label.toLowerCase(),
+      )?.id
+    },
+
+    /** @param {string} fieldKey @param {number} id @returns {string | undefined} */
+    optionIdToLabel(fieldKey, id) {
+      return optionsOf(fieldKey)?.find((o) => o.id === id)?.label
+    },
+
+    /**
+     * Return a copy of the record with custom_fields hash keys replaced by
+     * human names and option IDs by labels (for table display; JSON output
+     * stays raw).
+     * @param {object} record
+     */
+    resolveCustomFields(record) {
+      if (!record?.custom_fields) return record
+
+      const resolved = {}
+      for (const [key, value] of Object.entries(record.custom_fields)) {
+        const name = this.keyToName(key) ?? key
+        let displayValue = value
+        if (Array.isArray(value)) {
+          displayValue = value.map((v) => this.optionIdToLabel(key, v) ?? v)
+        } else if (value != null) {
+          displayValue = this.optionIdToLabel(key, value) ?? value
+        }
+        resolved[name] = displayValue
+      }
+      return { ...record, custom_fields: resolved }
+    },
+  }
+}

package/src/lib/keychain.js

@@ -0,0 +1,69 @@
+import createDebug from 'debug'
+import { CliError } from './errors.js'
+
+const debug = createDebug('pd:keychain')
+const SERVICE = 'pdcli'
+
+/** @type {typeof import('@napi-rs/keyring').Entry | null} */
+let Entry = null
+
+try {
+  const mod = await import('@napi-rs/keyring')
+  Entry = mod.Entry
+  debug('using OS keychain via @napi-rs/keyring')
+} catch {
+  debug('OS keychain unavailable')
+}
+
+function getEntry(account) {
+  return new Entry(SERVICE, account)
+}
+
+function keychainRequired() {
+  throw new CliError(
+    'OS keychain unavailable. pdcli stores credentials in your operating system ' +
+      'keychain (macOS Keychain, Windows Credential Manager, or libsecret on Linux) ' +
+      'and refuses to write them to disk in plaintext. Enable a system keychain and retry.',
+    { exitCode: 78 },
+  )
+}
+
+/**
+ * @param {string} profile
+ * @returns {Promise<string | null>}
+ */
+export async function getToken(profile) {
+  if (!Entry) return null
+  const account = `${profile}/token`
+  try {
+    return getEntry(account).getPassword() || null
+  } catch (err) {
+    debug('getToken error: %s', err.message)
+    return null
+  }
+}
+
+/**
+ * @param {string} profile
+ * @param {string} token
+ */
+export async function setToken(profile, token) {
+  if (!Entry) keychainRequired()
+  const account = `${profile}/token`
+  getEntry(account).setPassword(token)
+}
+
+/** @param {string} profile */
+export async function deleteToken(profile) {
+  if (!Entry) return
+  const account = `${profile}/token`
+  try {
+    getEntry(account).deletePassword()
+  } catch (err) {
+    debug('deleteToken error: %s', err.message)
+  }
+}
+
+export function isKeychainAvailable() {
+  return Entry !== null
+}