@wavyx/pdcli 0.1.0 → 0.2.0

package/src/commands/product/update.js

@@ -0,0 +1,77 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { buildWriteBody } from '../../lib/input.js'
+import { defsForFields, outputRecord } from '../../lib/entity-view.js'
+import { CliError } from '../../lib/errors.js'
+
+export default class ProductUpdateCommand extends BaseCommand {
+  static description =
+    'Update a product (v2 PATCH — only provided fields change)'
+
+  static examples = [
+    '<%= config.bin %> product update 7 --name "New name"',
+    '<%= config.bin %> product update 7 --price 12.50 --currency USD',
+    '<%= config.bin %> product update 7 --field "Material=Steel"',
+  ]
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Product ID' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    name: Flags.string({ description: 'Product name' }),
+    code: Flags.string({ description: 'Product code (SKU)' }),
+    unit: Flags.string({ description: 'Unit of measure' }),
+    description: Flags.string({ description: 'Product description' }),
+    owner: Flags.integer({ description: 'Owner (user) ID' }),
+    price: Flags.string({
+      description: 'Unit price (requires --currency)',
+      dependsOn: ['currency'],
+    }),
+    currency: Flags.string({
+      description: 'Price currency (requires --price)',
+      dependsOn: ['price'],
+    }),
+    field: Flags.string({
+      multiple: true,
+      description: 'Custom/standard field as "Name=Value" (repeatable)',
+    }),
+    body: Flags.string({ description: 'Raw JSON body to merge (flags win)' }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(ProductUpdateCommand)
+
+    const prices =
+      flags.price !== undefined && flags.currency !== undefined
+        ? [{ price: Number(flags.price), currency: flags.currency }]
+        : undefined
+
+    const body = buildWriteBody({
+      typed: {
+        name: flags.name,
+        code: flags.code,
+        unit: flags.unit,
+        description: flags.description,
+        owner_id: flags.owner,
+        prices,
+      },
+      fields: flags.field,
+      rawBody: flags.body,
+      defs: await defsForFields(this, 'product', flags.field),
+    })
+
+    if (Object.keys(body).length === 0) {
+      throw new CliError(
+        'Nothing to update — pass at least one field flag, --field, or --body',
+        { exitCode: 64 },
+      )
+    }
+
+    const res = await this.apiClient.patch(`/api/v2/products/${args.id}`, {
+      body,
+    })
+    await outputRecord(this, res.data, 'product')
+  }
+}

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/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) {

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 })
+}

package/src/lib/entity-view.js

@@ -0,0 +1,37 @@
+import { getFields, makeResolver } from './fields.js'
+import { flattenRecord } from './output/record.js'
+
+/**
+ * Output a single entity record: raw JSON for scripting, or a transposed
+ * field/value table with custom-field hash keys and option IDs resolved.
+ * @param {import('../base-command.js').default} cmd
+ * @param {object} record
+ * @param {string} entity deal | person | org | activity | product
+ */
+export async function outputRecord(cmd, record, entity) {
+  if (cmd.resolveFormat() === 'table') {
+    if (record.custom_fields && Object.keys(record.custom_fields).length) {
+      const defs = await getFields(cmd.apiClient, entity)
+      record = makeResolver(defs).resolveCustomFields(record)
+    }
+    await cmd.outputResults(flattenRecord(record), {
+      field: { header: 'Field' },
+      value: { header: 'Value' },
+    })
+    return
+  }
+
+  await cmd.outputResults(record, {})
+}
+
+/**
+ * Fetch field definitions only when --field entries are present.
+ * @param {import('../base-command.js').default} cmd
+ * @param {string} entity
+ * @param {string[]} [fieldFlags]
+ * @returns {Promise<object[] | undefined>}
+ */
+export async function defsForFields(cmd, entity, fieldFlags) {
+  if (!fieldFlags?.length) return undefined
+  return getFields(cmd.apiClient, entity)
+}

package/src/lib/input.js

@@ -0,0 +1,110 @@
+import { CliError } from './errors.js'
+
+const NUMERIC_TYPES = new Set(['double', 'monetary', 'int'])
+
+/**
+ * Build a write-request body from typed flags, repeatable --field entries,
+ * and a raw --body JSON string. Precedence: raw body < typed flags/fields.
+ *
+ * --field entries are "Name=Value" where Name is a field's human name, its
+ * field_code, or a 40-char custom-field hash. Enum labels resolve to option
+ * IDs; set values are comma-separated labels; numeric field types coerce to
+ * Number. Custom-field values nest under custom_fields (v2 shape).
+ *
+ * @param {object} options
+ * @param {Record<string, unknown>} [options.typed] API-named values from typed flags
+ * @param {string[]} [options.fields] repeatable --field "Name=Value" entries
+ * @param {string} [options.rawBody] raw JSON string from --body
+ * @param {object[]} [options.defs] field definitions (required when fields given)
+ * @returns {object} request body
+ */
+export function buildWriteBody({
+  typed = {},
+  fields = [],
+  rawBody,
+  defs,
+} = {}) {
+  let body = {}
+
+  if (rawBody) {
+    try {
+      body = JSON.parse(rawBody)
+    } catch (err) {
+      throw new CliError(`--body is not valid JSON: ${err.message}`, {
+        exitCode: 65,
+      })
+    }
+  }
+
+  for (const [key, value] of Object.entries(typed)) {
+    if (value !== undefined) body[key] = value
+  }
+
+  for (const entry of fields) {
+    const eq = entry.indexOf('=')
+    if (eq === -1) {
+      throw new CliError(`Invalid --field "${entry}". Expected Name=Value`, {
+        exitCode: 64,
+      })
+    }
+    const name = entry.slice(0, eq).trim()
+    const rawValue = entry.slice(eq + 1)
+
+    const def = findField(defs ?? [], name)
+    if (!def) {
+      throw new CliError(
+        `Unknown field "${name}". Run: pdcli field list <entity>`,
+        { exitCode: 65 },
+      )
+    }
+
+    const value = coerceValue(def, rawValue)
+
+    if (def.is_custom_field ?? isHashKey(def.field_code)) {
+      body.custom_fields ??= {}
+      body.custom_fields[def.field_code] = value
+    } else {
+      body[def.field_code] = value
+    }
+  }
+
+  return body
+}
+
+function isHashKey(s) {
+  return /^[a-f0-9]{40}$/.test(s)
+}
+
+function findField(defs, name) {
+  const lower = name.toLowerCase()
+  return defs.find(
+    (d) => d.field_name.toLowerCase() === lower || d.field_code === name,
+  )
+}
+
+function coerceValue(def, rawValue) {
+  if (def.field_type === 'enum') {
+    return resolveOption(def, rawValue)
+  }
+  if (def.field_type === 'set') {
+    return rawValue.split(',').map((label) => resolveOption(def, label.trim()))
+  }
+  if (NUMERIC_TYPES.has(def.field_type)) {
+    return Number(rawValue)
+  }
+  return rawValue
+}
+
+function resolveOption(def, label) {
+  const option = def.options?.find(
+    (o) => o.label.toLowerCase() === label.toLowerCase(),
+  )
+  if (!option) {
+    const valid = def.options?.map((o) => o.label).join(', ') ?? '(none)'
+    throw new CliError(
+      `Unknown option "${label}" for field "${def.field_name}". Valid: ${valid}`,
+      { exitCode: 65 },
+    )
+  }
+  return option.id
+}

package/src/lib/keychain.js

@@ -64,6 +64,53 @@ export async function deleteToken(profile) {
   }
 }
 
+/**
+ * @typedef {object} OAuthTokens
+ * @property {string} accessToken
+ * @property {string} refreshToken
+ * @property {number} expiresAt epoch ms
+ * @property {string} apiDomain e.g. https://acme.pipedrive.com
+ * @property {string} clientId
+ * @property {string} clientSecret kept in the keychain, never in config
+ */
+
+/**
+ * @param {string} profile
+ * @returns {Promise<OAuthTokens | null>}
+ */
+export async function getOAuthTokens(profile) {
+  if (!Entry) return null
+  const account = `${profile}/oauth`
+  try {
+    const raw = getEntry(account).getPassword()
+    return raw ? JSON.parse(raw) : null
+  } catch (err) {
+    debug('getOAuthTokens error: %s', err.message)
+    return null
+  }
+}
+
+/**
+ * @param {string} profile
+ * @param {OAuthTokens} tokens
+ */
+export async function setOAuthTokens(profile, tokens) {
+  if (!Entry) keychainRequired()
+  const account = `${profile}/oauth`
+  getEntry(account).setPassword(JSON.stringify(tokens))
+}
+
+/** @param {string} profile */
+export async function deleteOAuthTokens(profile) {
+  if (!Entry) return
+  const account = `${profile}/oauth`
+  try {
+    getEntry(account).deletePassword()
+  } catch (err) {
+    debug('deleteOAuthTokens error: %s', err.message)
+  }
+}
+
 export function isKeychainAvailable() {
   return Entry !== null
 }