@wavyx/pdcli 0.2.0 → 0.3.0

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

@@ -195,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/entity-view.js

@@ -6,11 +6,16 @@ import { flattenRecord } from './output/record.js'
  * 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
+ * @param {string} [entity] deal | person | org | activity | product — omit
+ *   for entities without resolvable custom fields (notes, files, webhooks, …)
  */
 export async function outputRecord(cmd, record, entity) {
   if (cmd.resolveFormat() === 'table') {
-    if (record.custom_fields && Object.keys(record.custom_fields).length) {
+    if (
+      entity &&
+      record.custom_fields &&
+      Object.keys(record.custom_fields).length
+    ) {
       const defs = await getFields(cmd.apiClient, entity)
       record = makeResolver(defs).resolveCustomFields(record)
     }

package/src/lib/output/csv.js

@@ -0,0 +1,26 @@
+/**
+ * @param {object[]} data
+ * @param {Record<string, import('./table.js').Column>} columns
+ * @returns {string}
+ */
+export function formatCsv(data, columns) {
+  if (!data || data.length === 0) return ''
+  const entries = Object.entries(columns)
+  const header = entries.map(([, col]) => col.header).join(',')
+  const rows = data.map((row) =>
+    entries
+      .map(([key, col]) => {
+        const val = col.get ? col.get(row) : row[col.key ?? key]
+        return csvEscape(val != null ? String(val) : '')
+      })
+      .join(','),
+  )
+  return [header, ...rows].join('\n')
+}
+
+function csvEscape(val) {
+  if (val.includes(',') || val.includes('"') || val.includes('\n')) {
+    return '"' + val.replace(/"/g, '""') + '"'
+  }
+  return val
+}

package/src/lib/output/index.js

@@ -1,10 +1,12 @@
 import { formatTable } from './table.js'
 import { formatJson } from './json.js'
+import { formatYaml } from './yaml.js'
+import { formatCsv } from './csv.js'
 
 /**
  * @param {object | object[]} data
  * @param {Record<string, import('./table.js').Column>} columns
- * @param {'table' | 'json'} format
+ * @param {'table' | 'json' | 'yaml' | 'csv'} format
  * @param {import('@oclif/core').Command} cmd
  */
 export function formatOutput(data, columns, format, cmd) {
@@ -14,6 +16,12 @@ export function formatOutput(data, columns, format, cmd) {
     case 'json':
       cmd.log(formatJson(data))
       break
+    case 'yaml':
+      cmd.log(formatYaml(data))
+      break
+    case 'csv':
+      cmd.log(formatCsv(items, columns))
+      break
     case 'table':
     default:
       cmd.log(formatTable(items, columns))

package/src/lib/output/yaml.js

@@ -0,0 +1,9 @@
+import yaml from 'js-yaml'
+
+/**
+ * @param {unknown} data
+ * @returns {string}
+ */
+export function formatYaml(data) {
+  return yaml.dump(data, { lineWidth: -1 }).trimEnd()
+}