@delopay/sdk 0.165.0 → 0.167.0

package/README.md

@@ -403,6 +403,8 @@ try {
 
 Network timeouts throw `DelopayError` with `code: 'TIMEOUT'`. Network failures throw with `code: 'NETWORK'`.
 
+An export (`delopay.export.*`, `disputes.workspaceExport`) is held to the record count the server announces in `X-Delopay-Record-Count`: a file that arrives with a different number of records — or ends part-way through a line or a JSON document — throws with `code: 'EXPORT_INCOMPLETE'` (`err.data` is `{ expected_records, received_records }`) instead of resolving to a file that is missing rows. Pass `onProgress` in an export's options to follow the download, and `signal` to cancel it.
+
 **Structured error context (`err.data`):** populated for a small set of codes that benefit from a machine-readable hint. Currently:
 
 | `err.code` | `err.data` shape               | Meaning                                                                    |

package/dist/{chunk-CP5M5WR6.js → chunk-RWCROWXW.js}

@@ -938,6 +938,289 @@ var Customers = class {
   }
 };
 
+// src/recordCounter.ts
+var LF = 10;
+var CR = 13;
+var QUOTE = 34;
+var BACKSLASH = 92;
+var OPEN_BRACE = 123;
+var CLOSE_BRACE = 125;
+var OPEN_BRACKET = 91;
+var CLOSE_BRACKET = 93;
+var CsvRecordCounter = class {
+  constructor() {
+    this.inQuotes = false;
+    this.newlines = 0;
+    /** Whether anything but a line break has arrived since the last newline. */
+    this.lineHasContent = false;
+  }
+  push(chunk) {
+    let inQuotes = this.inQuotes;
+    let newlines = this.newlines;
+    let lineHasContent = this.lineHasContent;
+    for (const byte of chunk) {
+      if (byte === QUOTE) {
+        inQuotes = !inQuotes;
+        lineHasContent = true;
+      } else if (inQuotes) {
+        lineHasContent = true;
+      } else if (byte === LF) {
+        newlines++;
+        lineHasContent = false;
+      } else if (byte !== CR) {
+        lineHasContent = true;
+      }
+    }
+    this.inQuotes = inQuotes;
+    this.newlines = newlines;
+    this.lineHasContent = lineHasContent;
+  }
+  get records() {
+    return Math.max(0, this.newlines - 1);
+  }
+  /**
+   * The export writer ends every line — the header and each record — with a
+   * newline, so a whole body ends on one, outside quotes. RFC 4180 lets a
+   * final line break be omitted, but these bodies never omit it, and without
+   * that rule a file cut part-way through its last unquoted field
+   * (`pay_1,12` of `pay_1,123`) would count as one more whole record and
+   * match the figure it was announced with.
+   */
+  get complete() {
+    return this.newlines >= 1 && !this.inQuotes && !this.lineHasContent;
+  }
+  /**
+   * The records that ended. An unterminated tail is not one of them — see
+   * {@link complete}.
+   */
+  finish() {
+    return this.records;
+  }
+};
+var SEEKING = 0;
+var COUNTING = 1;
+var CLOSED = 2;
+var JsonArrayRecordCounter = class {
+  constructor() {
+    this.depth = 0;
+    this.inString = false;
+    this.escaped = false;
+    this.topIsObject = false;
+    this.state = SEEKING;
+    this.count = 0;
+  }
+  push(chunk) {
+    if (this.state === CLOSED) return;
+    let { depth, inString, escaped, topIsObject, count } = this;
+    let state = this.state;
+    for (const byte of chunk) {
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (byte === BACKSLASH) escaped = true;
+        else if (byte === QUOTE) inString = false;
+        continue;
+      }
+      if (byte === QUOTE) {
+        inString = true;
+      } else if (byte === OPEN_BRACE || byte === OPEN_BRACKET) {
+        if (depth === 0 && byte === OPEN_BRACE) topIsObject = true;
+        if (byte === OPEN_BRACKET && depth === 1 && topIsObject && state === SEEKING) {
+          state = COUNTING;
+        }
+        depth++;
+      } else if (byte === CLOSE_BRACE || byte === CLOSE_BRACKET) {
+        depth--;
+        if (state === COUNTING) {
+          if (depth === 2) count++;
+          else if (depth === 1) {
+            state = CLOSED;
+            break;
+          }
+        }
+      }
+    }
+    this.depth = depth;
+    this.inString = inString;
+    this.escaped = escaped;
+    this.topIsObject = topIsObject;
+    this.state = state;
+    this.count = count;
+  }
+  get records() {
+    return this.count;
+  }
+  /**
+   * Whether the rows array has closed. What follows it is checked by parsing
+   * the whole document, which a cut-off body fails.
+   */
+  get complete() {
+    return this.state === CLOSED;
+  }
+  finish() {
+    return this.count;
+  }
+};
+
+// src/exportDownload.ts
+var RECORD_COUNT_HEADER = "x-delopay-record-count";
+var LIST_ENVELOPE = { rows: "records", count: "record_count" };
+var WORKSPACE_ENVELOPE = { rows: "data", count: "total_count" };
+function parseRecordCount(header) {
+  if (header === null) return null;
+  const trimmed = header.trim();
+  if (!/^\d+$/.test(trimmed)) return null;
+  const value = Number(trimmed);
+  return Number.isSafeInteger(value) ? value : null;
+}
+function counterFor(format) {
+  if (format === "csv") return new CsvRecordCounter();
+  if (format === "json") return new JsonArrayRecordCounter();
+  return null;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function announced(expected) {
+  return expected === null ? "" : ` of the ${expected} announced`;
+}
+function incomplete(message, expected, received, requestId) {
+  return new DelopayError(message, {
+    status: 0,
+    code: "EXPORT_INCOMPLETE",
+    type: "export_incomplete",
+    ...requestId !== void 0 ? { requestId } : {},
+    data: { expected_records: expected, received_records: received }
+  });
+}
+async function downloadExport(request, call, options) {
+  const { format } = call;
+  const envelope = call.envelope ?? LIST_ENVELOPE;
+  const onProgress = options?.onProgress;
+  let latest = {
+    phase: "preparing",
+    receivedBytes: 0,
+    totalBytes: null,
+    receivedRecords: 0,
+    expectedRecords: null
+  };
+  const seen = { attempt: -1, counter: null, expected: null, requestId: void 0, listenerError: null };
+  const report = (progress) => {
+    latest = progress;
+    if (!onProgress) return;
+    try {
+      onProgress({ ...progress });
+    } catch (error) {
+      seen.listenerError = { error };
+      throw error;
+    }
+  };
+  report(latest);
+  const onDownloadProgress = (event) => {
+    if (event.attempt !== seen.attempt) {
+      seen.attempt = event.attempt;
+      seen.counter = counterFor(format);
+      seen.expected = format === "pdf" ? null : parseRecordCount(event.headers.get(RECORD_COUNT_HEADER));
+      seen.requestId = event.headers.get("x-request-id") ?? event.headers.get("x-trace-id") ?? void 0;
+    }
+    if (event.chunk.byteLength > 0) seen.counter?.push(event.chunk);
+    report({
+      phase: "receiving",
+      receivedBytes: event.loaded,
+      totalBytes: event.total,
+      receivedRecords: seen.counter?.records ?? 0,
+      expectedRecords: seen.expected
+    });
+  };
+  let result;
+  try {
+    result = await request(call.method, call.path, {
+      ...call.request,
+      ...options?.signal !== void 0 ? { signal: options.signal } : {},
+      ...options?.timeout !== void 0 ? { timeout: options.timeout } : {},
+      onDownloadProgress
+    });
+  } catch (err) {
+    if (seen.listenerError !== null && err === seen.listenerError.error) throw err;
+    if (format === "json" && seen.attempt >= 0 && err instanceof SyntaxError) {
+      const received2 = seen.counter?.records ?? 0;
+      throw incomplete(
+        seen.expected === null ? `Export incomplete: the body ended part-way through the JSON document, after ${received2} records` : `Export incomplete: the server announced ${seen.expected} records, and the body ended part-way through the JSON document after ${received2}`,
+        seen.expected,
+        received2,
+        seen.requestId
+      );
+    }
+    throw err;
+  }
+  const { expected, requestId } = seen;
+  let received = 0;
+  if (format === "json") {
+    const rows = isRecord(result) ? result[envelope.rows] : void 0;
+    if (!Array.isArray(rows)) {
+      throw incomplete(
+        `Export incomplete: the body is not an export envelope with a "${envelope.rows}" array, so it carries 0 records${announced(expected)}`,
+        expected,
+        0,
+        requestId
+      );
+    }
+    received = rows.length;
+    const declared = isRecord(result) ? result[envelope.count] : void 0;
+    if (typeof declared === "number" && declared !== rows.length) {
+      throw incomplete(
+        `Export incomplete: the file's ${envelope.count} is ${declared}, but it carries ${rows.length} records`,
+        declared,
+        rows.length,
+        requestId
+      );
+    }
+  } else if (format === "csv") {
+    const counter = seen.counter;
+    received = counter?.finish() ?? 0;
+    if (!counter?.complete) {
+      throw incomplete(
+        `Export incomplete: the CSV body ended part-way through a line, after ${received} complete records${announced(expected)}`,
+        expected,
+        received,
+        requestId
+      );
+    }
+  }
+  if (expected !== null && received !== expected) {
+    throw incomplete(
+      `Export incomplete: the server announced ${expected} records, and the body carried ${received}`,
+      expected,
+      received,
+      requestId
+    );
+  }
+  report({
+    phase: "done",
+    receivedBytes: latest.receivedBytes,
+    totalBytes: latest.totalBytes,
+    receivedRecords: received,
+    expectedRecords: expected
+  });
+  return result;
+}
+var ACCEPT = {
+  csv: "text/csv",
+  json: "application/json",
+  pdf: "application/pdf"
+};
+function negotiated(options, format) {
+  const headers = { ...options.headers, Accept: ACCEPT[format] };
+  return format === "json" ? { ...options, headers } : { ...options, headers, responseType: "blob" };
+}
+function runExport(request, method, path, base, options) {
+  const format = options?.format ?? "json";
+  return downloadExport(
+    request,
+    { method, path, request: negotiated(base, format), format },
+    options
+  );
+}
+
 // src/resources/disputes.ts
 function workspaceQuery(params) {
   if (!params) return void 0;
@@ -966,9 +1249,28 @@ var Disputes = class {
   async workspaceAggregate(params) {
     return this.request("GET", "/disputes/workspace/aggregate", { query: workspaceQuery(params) });
   }
-  /** Export the complete filtered set, or throw on the server's explicit export-limit refusal. */
-  async workspaceExport(params) {
-    return this.request("GET", "/disputes/workspace/export", { query: workspaceQuery(params) });
+  /**
+   * Export the complete filtered set, or throw on the server's explicit
+   * export-limit refusal. `GET /disputes/workspace/export`
+   *
+   * The body is streamed, and held to the `X-Delopay-Record-Count` the server
+   * announces and to its own `total_count`: a set that arrives short rejects
+   * with `EXPORT_INCOMPLETE` rather than resolving. `options` reports the
+   * download's progress and takes a signal and an idle timeout — see
+   * {@link ExportTransferOptions}.
+   */
+  async workspaceExport(params, options) {
+    return downloadExport(
+      this.request,
+      {
+        method: "GET",
+        path: "/disputes/workspace/export",
+        request: { query: workspaceQuery(params) },
+        format: "json",
+        envelope: WORKSPACE_ENVELOPE
+      },
+      options
+    );
   }
   /**
    * Retrieve a dispute by its ID.
@@ -4125,77 +4427,68 @@ var Export = class {
     this.request = request;
   }
   async transactions(params, options) {
-    return this.request(
-      "POST",
-      "/export/transactions",
-      transactionBody(params, options)
-    );
+    return runExport(this.request, "POST", "/export/transactions", { body: params ?? {} }, options);
   }
   async transactionsForProfile(params, options) {
-    return this.request(
+    return runExport(
+      this.request,
       "POST",
       "/export/profile/transactions",
-      transactionBody(params, options)
+      { body: params ?? {} },
+      options
     );
   }
   async refunds(params, options) {
-    return this.request("POST", "/refunds/list/export", bodied(params ?? {}, options));
+    return runExport(this.request, "POST", "/refunds/list/export", { body: params ?? {} }, options);
   }
   async refundsForProfile(params, options) {
-    return this.request(
+    return runExport(
+      this.request,
       "POST",
       "/refunds/profile/list/export",
-      bodied(params ?? {}, options)
+      { body: params ?? {} },
+      options
     );
   }
   async disputes(params, options) {
-    return this.request("GET", "/disputes/list/export", queried(params, options));
+    return runExport(this.request, "GET", "/disputes/list/export", queried(params), options);
   }
   async disputesForProfile(params, options) {
-    return this.request(
+    return runExport(
+      this.request,
       "GET",
       "/disputes/profile/list/export",
-      queried(params, options)
+      queried(params),
+      options
     );
   }
   async payouts(params, options) {
-    return this.request("POST", "/payouts/list/export", bodied(params, options));
+    return runExport(this.request, "POST", "/payouts/list/export", { body: params }, options);
   }
   async payoutsForProfile(params, options) {
-    return this.request("POST", "/payouts/profile/list/export", bodied(params, options));
+    return runExport(
+      this.request,
+      "POST",
+      "/payouts/profile/list/export",
+      { body: params },
+      options
+    );
   }
   async subscriptions(profileId, params, options) {
-    return this.request(
+    return runExport(
+      this.request,
       "GET",
       "/subscriptions/list/export",
-      queried(params, options, { "X-Profile-Id": profileId })
+      queried(params, { "X-Profile-Id": profileId }),
+      options
     );
   }
   async auditLog(params, options) {
-    return this.request("GET", "/audit/export", queried(params, options));
+    return runExport(this.request, "GET", "/audit/export", queried(params), options);
   }
 };
-var ACCEPT = {
-  csv: "text/csv",
-  json: "application/json",
-  pdf: "application/pdf"
-};
-function negotiated(options, format) {
-  const headers = { ...options.headers, Accept: ACCEPT[format] };
-  return format === "json" ? { ...options, headers } : { ...options, headers, responseType: "blob" };
-}
-function transactionBody(params, options) {
-  const format = options?.format ?? "json";
-  return negotiated({ body: { ...params, format } }, format);
-}
-function bodied(body, options) {
-  return negotiated({ body }, options?.format ?? "json");
-}
-function queried(params, options, headers) {
-  return negotiated(
-    { query: params ?? {}, ...headers ? { headers } : {} },
-    options?.format ?? "json"
-  );
+function queried(params, headers) {
+  return { query: params ?? {}, ...headers ? { headers } : {} };
 }
 
 // src/resources/featureMatrix.ts
@@ -4479,6 +4772,24 @@ var ExternalRecords = class {
   async create(params) {
     return this.request("POST", "/external-records", { body: params });
   }
+  /**
+   * What this deployment will accept, per kind.
+   * `GET /external-records/capabilities`
+   *
+   * Read it before offering the operator a form. Every kind is listed, so an
+   * entry that is not served is distinguishable from a kind this release does
+   * not know at all — and `create` says *why* it is not served: a gap
+   * (`not_implemented`) or a rule (`not_applicable`). Treating those as the
+   * same thing is how a caller ends up waiting for something that will never
+   * be built.
+   *
+   * The answer describes the binary rather than anything a merchant owns, so
+   * it is the same for every caller of one deployment and is safe to cache for
+   * the life of a dashboard session.
+   */
+  async capabilities() {
+    return this.request("GET", "/external-records/capabilities");
+  }
 };
 
 // src/resources/products.ts
@@ -5568,6 +5879,112 @@ function findIdempotencyKey(headers) {
 }
 function noop() {
 }
+var ListenerFailure = class {
+  constructor(cause) {
+    this.cause = cause;
+  }
+};
+var BodyStreamFailure = class {
+  constructor(cause) {
+    this.cause = cause;
+  }
+};
+function abortError() {
+  const error = new Error("The operation was aborted");
+  error.name = "AbortError";
+  return error;
+}
+function parseContentLength(header) {
+  if (header === null || !/^\s*\d+\s*$/.test(header)) return null;
+  const value = Number(header);
+  return Number.isSafeInteger(value) ? value : null;
+}
+function readChunk(reader, signal) {
+  if (signal.aborted) return Promise.reject(abortError());
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError());
+    signal.addEventListener("abort", onAbort, { once: true });
+    reader.read().then(
+      (result) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(result);
+      },
+      (cause) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(signal.aborted ? abortError() : new BodyStreamFailure(cause));
+      }
+    );
+  });
+}
+function concatChunks(chunks, length) {
+  const out = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out.buffer;
+}
+async function receiveWithProgress(response, responseType, listener, attempt, signal, onActivity) {
+  const headers = response.headers ?? new Headers();
+  const total = parseContentLength(headers.get("content-length"));
+  let loaded = 0;
+  const notify = (chunk) => {
+    try {
+      listener({ loaded, total, chunk: chunk.slice(), headers, attempt });
+    } catch (cause) {
+      throw new ListenerFailure(cause);
+    }
+  };
+  onActivity();
+  notify(new Uint8Array(0));
+  const body = response.body;
+  if (!body || typeof body.getReader !== "function") {
+    if (responseType === "blob") {
+      const blob = await response.blob();
+      const bytes3 = new Uint8Array(await blob.arrayBuffer());
+      loaded = bytes3.byteLength;
+      if (loaded > 0) notify(bytes3);
+      return blob;
+    }
+    if (responseType === "arraybuffer") {
+      const buffer = await response.arrayBuffer();
+      loaded = buffer.byteLength;
+      if (loaded > 0) notify(new Uint8Array(buffer));
+      return buffer;
+    }
+    const text2 = await response.text();
+    const bytes2 = new TextEncoder().encode(text2);
+    loaded = bytes2.byteLength;
+    if (loaded > 0) notify(bytes2);
+    return text2 ? JSON.parse(text2) : void 0;
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  try {
+    for (; ; ) {
+      const { done, value } = await readChunk(reader, signal);
+      if (done) break;
+      if (!value || value.byteLength === 0) continue;
+      chunks.push(value);
+      loaded += value.byteLength;
+      onActivity();
+      notify(value);
+    }
+  } catch (err) {
+    reader.cancel().catch(noop);
+    throw err;
+  }
+  const bytes = concatChunks(chunks, loaded);
+  if (responseType === "blob") {
+    return new Blob([bytes], { type: headers.get("content-type") ?? "" });
+  }
+  if (responseType === "arraybuffer") {
+    return bytes;
+  }
+  const text = new TextDecoder().decode(bytes);
+  return text ? JSON.parse(text) : void 0;
+}
 function combineSignals(signals) {
   const controller = new AbortController();
   const listeners = [];
@@ -5849,7 +6266,12 @@ var Delopay = class {
         emit("retry", { attempt, maxRetries: this.maxRetries, method, path });
       }
       const timeoutCtrl = new AbortController();
-      const timeoutId = setTimeout(() => timeoutCtrl.abort(), timeoutMs);
+      let timeoutId = setTimeout(() => timeoutCtrl.abort(), timeoutMs);
+      const restartIdleTimer = () => {
+        if (timeoutCtrl.signal.aborted) return;
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => timeoutCtrl.abort(), timeoutMs);
+      };
       const combined = combineSignals(
         callerSignal ? [timeoutCtrl.signal, callerSignal] : [timeoutCtrl.signal]
       );
@@ -5907,6 +6329,16 @@ var Delopay = class {
           }
           throw error;
         }
+        if (options?.onDownloadProgress) {
+          return await receiveWithProgress(
+            response,
+            options.responseType,
+            options.onDownloadProgress,
+            attempt,
+            combined.signal,
+            restartIdleTimer
+          );
+        }
         if (options?.responseType === "blob") {
           return await response.blob();
         }
@@ -5919,6 +6351,20 @@ var Delopay = class {
         if (err instanceof DelopayError || err instanceof DelopayAuthenticationError) {
           throw err;
         }
+        if (err instanceof ListenerFailure) {
+          throw err.cause;
+        }
+        if (err instanceof BodyStreamFailure) {
+          const cause = err.cause;
+          const detail = cause instanceof Error ? cause.message : String(cause ?? "body stream failed");
+          lastError = new DelopayError(`Network error: ${detail}`, {
+            status: 0,
+            code: "NETWORK",
+            type: "network_error"
+          });
+          if (isRetryable && attempt < this.maxRetries) continue;
+          throw lastError;
+        }
         if (err instanceof Error && err.name === "AbortError") {
           if (callerSignal?.aborted) {
             throw new DelopayError("Request aborted", {
@@ -9510,6 +9956,7 @@ var encodeNativePanes = encodePanes;
 export {
   DelopayError,
   DelopayAuthenticationError,
+  runExport,
   PaypalDisputes,
   Search,
   isSubscriptionLifecycleWebhook,
@@ -9725,4 +10172,4 @@ export {
   decodeNativePanes,
   encodeNativePanes
 };
-//# sourceMappingURL=chunk-CP5M5WR6.js.map
+//# sourceMappingURL=chunk-RWCROWXW.js.map