@wavyx/pdcli 0.8.0 → 0.10.0

package/src/lib/client.js

@@ -79,6 +79,87 @@ export function createClient({
       }
     }
 
+    return transport(method, url, {
+      path,
+      makeBody: body ? () => JSON.stringify(body) : undefined,
+      extraHeaders: { 'content-type': 'application/json' },
+    })
+  }
+
+  /**
+   * 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
+    }
+  }
+
+  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 }
+  }
+
+  /**
+   * Shared transport: EVERY HTTP path (JSON, form, multipart, binary) goes
+   * through the same 429 backoff (x-ratelimit-reset → Retry-After → default),
+   * 429→403 escalation hard stop, 5xx retry, OAuth refresh-once, and error
+   * mapping. `makeBody` is invoked per attempt — FormData and friends are
+   * rebuilt rather than reused across retries.
+   * @param {string} method
+   * @param {URL} url
+   * @param {{ path: string, makeBody?: () => any,
+   *   extraHeaders?: Record<string, string>, binary?: boolean }} options
+   */
+  async function transport(
+    method,
+    url,
+    { path, makeBody, extraHeaders = {}, binary = false },
+  ) {
     const maxAttempts = retry ? 3 : 1
     let attempts = 0
     let sawRateLimit = false
@@ -86,26 +167,31 @@ export function createClient({
     while (attempts < maxAttempts) {
       attempts++
 
-      const headers = {
-        '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,
-        headers,
-        body: body ? JSON.stringify(body) : undefined,
+        headers: { ...authHeaders(), ...extraHeaders },
+        body: makeBody ? makeBody() : undefined,
         signal: AbortSignal.timeout(timeout),
       })
 
       debug('%s %s → %d', method, path, res.status)
 
       if (res.status === 429) {
+        // Daily-budget exhaustion has no useful reset window — backoff would
+        // stall until the daily reset. Fail fast with an actionable message.
+        // The live API reports the token budget as
+        // x-daily-ratelimit-token-remaining (verified on the sandbox);
+        // x-daily-requests-left is the older POST/PUT fair-use header.
+        const dailyRemaining =
+          res.headers.get('x-daily-ratelimit-token-remaining') ??
+          res.headers.get('x-daily-requests-left')
+        if (dailyRemaining === '0') {
+          const err = new RateLimitError(0)
+          err.message =
+            'Daily API token budget exhausted — resets at midnight server ' +
+            'time (UTC-based; may differ from your local timezone)'
+          throw err
+        }
         const wait = Number(
           res.headers.get('x-ratelimit-reset') ||
             res.headers.get('retry-after') ||
@@ -118,6 +204,16 @@ export function createClient({
         continue
       }
 
+      // Surface the remaining daily budget under --verbose (DEBUG=pd:*).
+      const dailyLeft = res.headers.get('x-daily-ratelimit-token-remaining')
+      if (dailyLeft != null) {
+        debug(
+          'daily token budget: %s remaining of %s',
+          dailyLeft,
+          res.headers.get('x-daily-ratelimit-token-limit') ?? '?',
+        )
+      }
+
       // OAuth access tokens expire (~1h) — refresh once and retry.
       if (res.status === 401 && onRefresh && attempts === 1) {
         debug('401, attempting OAuth token refresh')
@@ -141,97 +237,38 @@ export function createClient({
         continue
       }
 
+      // Binary callers always get the {buffer, contentType} shape — a 204
+      // yields an empty buffer rather than null (pre-unification parity;
+      // file/download destructures the result).
+      if (binary) {
+        if (!res.ok) {
+          throw ApiError.fromResponse(res.status, await res.text(), path)
+        }
+        return {
+          buffer: await res.arrayBuffer(),
+          contentType: res.headers.get('content-type'),
+        }
+      }
+
       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
-    }
-  }
-
-  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'),
-    }
+    return transport('GET', lockedUrl(path), { path, binary: true })
   }
 
   /**
@@ -240,24 +277,16 @@ export function createClient({
    * @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)
+    // fetch sets the multipart boundary itself — no content-type override.
+    const makeBody = () => {
+      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))
+      }
+      return form
     }
-    return text ? JSON.parse(text) : null
+    return transport('POST', lockedUrl(path), { path, makeBody })
   }
 
   /**
@@ -267,26 +296,15 @@ export function createClient({
    * @param {Record<string, unknown>} fields Null/undefined values are omitted.
    */
   async function postForm(path, fields = {}) {
-    const url = lockedUrl(path)
     const params = new URLSearchParams()
     for (const [k, v] of Object.entries(fields)) {
       if (v != null) params.set(k, String(v))
     }
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: {
-        ...authHeaders(),
-        'content-type': 'application/x-www-form-urlencoded',
-      },
-      body: params.toString(),
-      signal: AbortSignal.timeout(timeout),
+    return transport('POST', lockedUrl(path), {
+      path,
+      makeBody: () => params.toString(),
+      extraHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
     })
-    debug('POST (form) %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 {