@wavyx/pdcli 0.1.0 → 0.3.0

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/auth.js

@@ -1,10 +1,18 @@
+import { createServer } from 'node:http'
+import { randomBytes } from 'node:crypto'
 import createDebug from 'debug'
-import { getToken } from './keychain.js'
+import open from 'open'
+import { getToken, getOAuthTokens, setOAuthTokens } from './keychain.js'
 import { getProfileConfig } from './config.js'
-import { AuthRequiredError, ConfigError } from './errors.js'
+import { ApiError, AuthRequiredError, CliError, ConfigError } from './errors.js'
 
 const debug = createDebug('pd:auth')
 
+const AUTH_URL = 'https://oauth.pipedrive.com/oauth/authorize'
+const TOKEN_URL = 'https://oauth.pipedrive.com/oauth/token'
+const REFRESH_BUFFER_MS = 5 * 60 * 1000
+const REDIRECT_PORT = 9999
+
 /**
  * Normalize user input ("acme", "acme.pipedrive.com",
  * "https://acme.pipedrive.com/") to the bare company subdomain.
@@ -44,6 +52,26 @@ export function companyDomainToBaseOrigin(companyDomain) {
  * @returns {Promise<ResolvedCredentials>}
  */
 export async function resolveCredentials({ flags, profile } = {}) {
+  // Explicit token via flags/env always wins. Otherwise a profile in OAuth
+  // mode resolves to its (auto-refreshed) access token + api_domain.
+  const explicitToken = flags?.['api-token'] || process.env.PDCLI_API_TOKEN
+  if (
+    !explicitToken &&
+    profile &&
+    getProfileConfig(profile, 'auth_mode') === 'oauth'
+  ) {
+    const access = await getValidOAuthAccess(profile)
+    if (!access) throw new AuthRequiredError()
+    debug('resolved OAuth credentials for %s', access.apiDomain)
+    return {
+      mode: 'oauth',
+      apiDomain: access.apiDomain,
+      token: access.accessToken,
+      oauth: access,
+      source: 'profile',
+    }
+  }
+
   let companyDomain
   if (flags?.company) {
     companyDomain = flags.company
@@ -79,7 +107,203 @@ export async function resolveCredentials({ flags, profile } = {}) {
   }
 
   debug('resolved credentials for %s (token from %s)', companyDomain, source)
-  return { companyDomain, token, source }
+  return { mode: 'token', companyDomain, token, source }
+}
+
+/**
+ * Exchange an authorization code for tokens. Pipedrive authenticates the
+ * token endpoint with HTTP Basic (client_id:client_secret) and returns the
+ * account's api_domain, which becomes the API base URL.
+ * @param {{ code: string, clientId: string, clientSecret: string, redirectUri: string }} options
+ */
+export async function exchangeCode({
+  code,
+  clientId,
+  clientSecret,
+  redirectUri,
+}) {
+  return tokenRequest(
+    { grant_type: 'authorization_code', code, redirect_uri: redirectUri },
+    { clientId, clientSecret },
+  )
+}
+
+/**
+ * @param {{ refreshToken: string, clientId: string, clientSecret: string }} options
+ */
+export async function refreshAccessToken({
+  refreshToken,
+  clientId,
+  clientSecret,
+}) {
+  debug('refreshing access token')
+  return tokenRequest(
+    { grant_type: 'refresh_token', refresh_token: refreshToken },
+    { clientId, clientSecret },
+  )
+}
+
+async function tokenRequest(params, { clientId, clientSecret }) {
+  const basic = Buffer.from(`${clientId}:${clientSecret}`).toString('base64')
+  const res = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: {
+      authorization: `Basic ${basic}`,
+      'content-type': 'application/x-www-form-urlencoded',
+    },
+    body: new URLSearchParams(params),
+  })
+
+  const body = await res.json()
+  if (!res.ok) {
+    throw ApiError.fromResponse(res.status, JSON.stringify(body), TOKEN_URL)
+  }
+
+  return {
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token,
+    expiresIn: body.expires_in,
+    apiDomain: body.api_domain,
+  }
+}
+
+/**
+ * Browser-based OAuth authorization-code flow via a local loopback server.
+ * @param {object} options
+ * @param {string} options.clientId
+ * @param {string} options.clientSecret
+ * @param {number} [options.timeout]
+ * @param {number} [options.port] Loopback callback port (must match the
+ *   callback URL registered in the Pipedrive Developer Hub app). Default 9999.
+ * @returns {Promise<{accessToken: string, refreshToken: string, expiresIn: number, apiDomain: string}>}
+ */
+export function authorizationCodeFlow({
+  clientId,
+  clientSecret,
+  timeout = 120_000,
+  port = REDIRECT_PORT,
+}) {
+  return new Promise((resolve, reject) => {
+    const state = randomBytes(16).toString('hex')
+    let timer
+
+    const server = createServer(async (req, res) => {
+      const url = new URL(req.url, `http://${req.headers.host}`)
+      if (url.pathname !== '/callback') {
+        res.writeHead(404)
+        res.end()
+        return
+      }
+
+      const code = url.searchParams.get('code')
+      const returnedState = url.searchParams.get('state')
+
+      if (returnedState !== state) {
+        res.writeHead(400, { 'content-type': 'text/html' })
+        res.end(
+          '<h2>Authentication failed: state mismatch (possible CSRF attack)</h2>',
+        )
+        clearTimeout(timer)
+        server.close()
+        reject(
+          new CliError('OAuth state mismatch — possible CSRF attack', {
+            exitCode: 77,
+          }),
+        )
+        return
+      }
+
+      if (!code) {
+        res.writeHead(400, { 'content-type': 'text/html' })
+        res.end(
+          '<h2>Authentication failed: no authorization code received</h2>',
+        )
+        clearTimeout(timer)
+        server.close()
+        reject(new CliError('No authorization code received', { exitCode: 77 }))
+        return
+      }
+
+      try {
+        const tokens = await exchangeCode({
+          code,
+          clientId,
+          clientSecret,
+          redirectUri: `http://127.0.0.1:${server.address().port}/callback`,
+        })
+        res.writeHead(200, { 'content-type': 'text/html' })
+        res.end('<h2>Authenticated! You can close this window.</h2>')
+        clearTimeout(timer)
+        server.close()
+        resolve(tokens)
+      } catch (err) {
+        res.writeHead(500, { 'content-type': 'text/html' })
+        res.end(`<h2>Authentication failed: ${err.message}</h2>`)
+        clearTimeout(timer)
+        server.close()
+        reject(err)
+      }
+    })
+
+    server.on('error', (err) => {
+      clearTimeout(timer)
+      reject(
+        new CliError(
+          `Cannot start the local callback server on port ${port}: ${err.message}. ` +
+            'If the port is in use, close whatever is using it and run `pdcli auth login --oauth` again.',
+          { exitCode: 78 },
+        ),
+      )
+    })
+
+    server.listen(port, '127.0.0.1', () => {
+      const boundPort = server.address().port
+      const redirectUri = `http://127.0.0.1:${boundPort}/callback`
+      const authUrl = `${AUTH_URL}?client_id=${encodeURIComponent(clientId)}&state=${state}&redirect_uri=${encodeURIComponent(redirectUri)}`
+      debug('opening browser for auth: %s', authUrl)
+      open(authUrl)
+    })
+
+    timer = setTimeout(() => {
+      server.close()
+      reject(
+        new CliError(
+          `Authentication timed out after ${timeout / 1000}s. Try again.`,
+          { exitCode: 77 },
+        ),
+      )
+    }, timeout)
+  })
+}
+
+/**
+ * Return a valid OAuth access token for the profile, transparently
+ * refreshing (and persisting) when within the expiry buffer.
+ * @param {string} profile
+ * @returns {Promise<import('./keychain.js').OAuthTokens | null>}
+ */
+export async function getValidOAuthAccess(profile) {
+  const tokens = await getOAuthTokens(profile)
+  if (!tokens) return null
+
+  const now = Date.now()
+  if (tokens.expiresAt - now > REFRESH_BUFFER_MS) {
+    return tokens
+  }
+
+  const refreshed = await refreshAccessToken({
+    refreshToken: tokens.refreshToken,
+    clientId: tokens.clientId,
+    clientSecret: tokens.clientSecret,
+  })
+  const updated = {
+    ...tokens,
+    accessToken: refreshed.accessToken,
+    refreshToken: refreshed.refreshToken,
+    expiresAt: now + refreshed.expiresIn * 1000,
+  }
+  await setOAuthTokens(profile, updated)
+  return updated
 }
 
 /**

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/client.js

@@ -31,21 +31,33 @@ function clampLimit(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 {string} [options.companyDomain] Bare subdomain ("acme") — forms and
+ *   locks the base origin https://acme.pipedrive.com (token mode).
+ * @param {string} [options.apiDomain] Full origin from the OAuth token
+ *   response (e.g. https://acme.pipedrive.com) — used and locked in OAuth mode.
+ * @param {string} options.token Personal API token (x-api-token header) or
+ *   OAuth access token (Authorization: Bearer) depending on authMode.
+ * @param {'token' | 'oauth'} [options.authMode]
+ * @param {() => Promise<string>} [options.onRefresh] OAuth-mode callback
+ *   invoked once on a 401; returns a fresh access token to retry with.
  * @param {number} [options.timeout]
  * @param {boolean} [options.retry]
  * @param {string} [options.userAgent]
  */
 export function createClient({
   companyDomain,
-  token,
+  apiDomain,
+  token: initialToken,
+  authMode = 'token',
+  onRefresh,
   timeout = 30_000,
   retry = true,
   userAgent = 'pdcli',
 }) {
-  const baseOrigin = companyDomainToBaseOrigin(companyDomain)
+  const baseOrigin = apiDomain
+    ? new URL(apiDomain).origin
+    : companyDomainToBaseOrigin(companyDomain)
+  let token = initialToken
 
   async function request(method, path, { body, query } = {}) {
     const url = new URL(path, baseOrigin)
@@ -75,10 +87,14 @@ export function createClient({
       attempts++
 
       const headers = {
-        'x-api-token': token,
         'content-type': 'application/json',
         'user-agent': userAgent,
       }
+      if (authMode === 'oauth') {
+        headers.authorization = `Bearer ${token}`
+      } else {
+        headers['x-api-token'] = token
+      }
 
       const res = await fetch(url, {
         method,
@@ -102,6 +118,13 @@ export function createClient({
         continue
       }
 
+      // OAuth access tokens expire (~1h) — refresh once and retry.
+      if (res.status === 401 && onRefresh && attempts === 1) {
+        debug('401, attempting OAuth token refresh')
+        token = await onRefresh()
+        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) {
@@ -172,12 +195,79 @@ export function createClient({
     }
   }
 
+  function lockedUrl(path) {
+    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 },
+      )
+    }
+    return url
+  }
+
+  function authHeaders() {
+    return authMode === 'oauth'
+      ? { authorization: `Bearer ${token}`, 'user-agent': userAgent }
+      : { 'x-api-token': token, 'user-agent': userAgent }
+  }
+
+  /**
+   * Download a binary resource (e.g. /api/v1/files/:id/download).
+   * @param {string} path
+   * @returns {Promise<{buffer: ArrayBuffer, contentType: string | null}>}
+   */
+  async function download(path) {
+    const url = lockedUrl(path)
+    const res = await fetch(url, {
+      headers: authHeaders(),
+      signal: AbortSignal.timeout(timeout),
+    })
+    debug('GET (binary) %s → %d', path, res.status)
+    if (!res.ok) {
+      throw ApiError.fromResponse(res.status, await res.text(), path)
+    }
+    return {
+      buffer: await res.arrayBuffer(),
+      contentType: res.headers.get('content-type'),
+    }
+  }
+
+  /**
+   * POST multipart/form-data (file uploads — v1 files API).
+   * @param {string} path
+   * @param {{ file: { name: string, data: Buffer | Uint8Array }, fields?: Record<string, unknown> }} options
+   */
+  async function postMultipart(path, { file, fields = {} }) {
+    const url = lockedUrl(path)
+    const form = new FormData()
+    form.set('file', new Blob([file.data]), file.name)
+    for (const [k, v] of Object.entries(fields)) {
+      if (v != null) form.set(k, String(v))
+    }
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: authHeaders(), // fetch sets the multipart boundary itself
+      body: form,
+      signal: AbortSignal.timeout(timeout),
+    })
+    debug('POST (multipart) %s → %d', path, res.status)
+    const text = await res.text()
+    if (!res.ok) {
+      throw ApiError.fromResponse(res.status, text, path)
+    }
+    return text ? JSON.parse(text) : null
+  }
+
   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),
+    download,
+    postMultipart,
     pageV1,
     pageV2,
   }

package/src/lib/confirm.js

@@ -0,0 +1,10 @@
+/**
+ * @param {string} message
+ * @param {boolean} skipConfirm
+ * @returns {Promise<boolean>}
+ */
+export async function confirmAction(message, skipConfirm) {
+  if (skipConfirm) return true
+  const { confirm } = await import('@inquirer/prompts')
+  return confirm({ message })
+}