@delopay/sdk 0.163.0 → 0.164.0

package/dist/index.cjs

@@ -1986,6 +1986,16 @@ var Payments = class {
    * Not the hosted-shop settlement API under `settlement.*`, which is host →
    * shop owner and manual; this is acquirer → merchant bank, per payment.
    *
+   * Each attempt also carries what the rail itself took for it —
+   * `processor_cost_amount` with its own `processor_cost_currency` and
+   * `processor_cost_exponent`, the `processor_cost_source` that says how the
+   * figure was obtained, the `processor_cost_basis` behind an estimate, and
+   * the `connector_method_code` it was priced under. Recorded for **every**
+   * merchant, not only those that host shops. Never present an `estimated`
+   * cost as an observation, and read an absent `processor_cost_source` as
+   * "nothing was ever written", which is not the `unavailable` the rail
+   * answers with.
+   *
    * `GET /payments/{paymentId}/settlement`
    *
    * @param paymentId - The payment intent ID.
@@ -2004,6 +2014,9 @@ var Payments = class {
    *   if (attempt.status === 'paid_out') {
    *     console.log(attempt.paid_out_at, attempt.payout_reference);
    *   }
+   *   if (attempt.processor_cost_source === 'estimated') {
+   *     // Label it an estimate — it was derived from a cost schedule.
+   *   }
    * }
    * ```
    */
@@ -5239,6 +5252,65 @@ var Settlement = class {
       ...options
     });
   }
+  /**
+   * What a period's payments cost at the rails, grouped by shop, connector
+   * and payment method. Answers for **every** merchant, including one that
+   * hosts nobody — it reads the per-attempt settlement record rather than the
+   * settlement lines, which exist only where hosting fees are configured.
+   *
+   * A sibling of {@link Settlement.cost} rather than a widening of it. That
+   * endpoint is a profit statement whose revenue term is hosting income, and
+   * a merchant who hosts nobody has none. This publishes cost and never
+   * margin.
+   *
+   * Send `year` and `month` together to report one UTC calendar month, or
+   * neither for the running month so far.
+   *
+   * **The response carries no period total, and a caller must not compute
+   * one here.** Every figure keeps the unit the rail reported it in, and the
+   * unit is part of each bucket's key, so adding two buckets is not addition.
+   * Convert caller-side if you need one number, and say which rates you used.
+   * The counts are totalled, because a count has no unit.
+   *
+   * Two distinctions not to flatten when rendering a bucket:
+   * `cost_amount` covers `reported_count + estimated_count` attempts out of
+   * `attempt_count` and is a lower bound whenever those disagree; and
+   * `unavailable_count` (the rail says it has no figure) means something
+   * different from `unwritten_count` (a gap in our own recording).
+   *
+   * **Merchant scope.** A token scoped to a single shop, a role narrowed to
+   * specific connector accounts, or a role without the settlement-read
+   * permission group is refused `403`: what a rail charged is the merchant's
+   * own cost base, and here it is the whole response, so there is nothing
+   * coherent to redact down to. Gate the surface on the caller's scope rather
+   * than calling it and handling the failure.
+   *
+   * `GET /settlement/processor-cost`
+   *
+   * @example
+   * ```typescript
+   * const period = await delopay.settlement.processorCost({
+   *   test_mode: false,
+   *   year: 2026,
+   *   month: 7,
+   * });
+   * for (const bucket of period.buckets) {
+   *   // Each bucket is its own unit — render per bucket, never a sum.
+   *   console.log(bucket.connector, bucket.cost_amount, bucket.cost_currency);
+   * }
+   * ```
+   */
+  async processorCost(params, options) {
+    return this.request("GET", "/settlement/processor-cost", {
+      query: {
+        profile_id: params?.profile_id,
+        test_mode: params?.test_mode,
+        year: params?.year,
+        month: params?.month
+      },
+      ...options
+    });
+  }
   /**
    * List generated settlement statements, newest first.
    *