@dime-technology/dime-js-sdk 1.2.0 → 1.3.1

package/README.md

@@ -230,9 +230,55 @@ await dime.invoices.delete('000010', copy.id!) // drafts only
 const page = await dime.invoices.list('000010', { status: 'sent' })
 ```
 
+**Statuses.** `invoice.status` is one of `draft`, `sent`, `viewed`, `partially_paid`, `paid`, `void` or
+`refunded`. `paid` is not always final: if the customer's bank returns an ACH payment, the invoice is
+reopened (back to `partially_paid`, `viewed` or `sent`, with `amountPaid` and `balance` updated) and an
+`invoice_payment_returned` webhook fires. Re-read the invoice rather than caching a `paid` status forever.
+
+#### Making the customer cover processing fees
+
+Set `cover_fee_required` and the customer must pay the processing fee — it is not an optional
+checkbox at checkout. The fee is **not** a line item and is **not** part of `total`: the merchant is
+still owed `total`, and the fee is added on top of whatever the customer pays.
+
+Card and ACH rates differ, so the charge depends on how the customer pays. `coverFeeQuote` gives you
+both, quoted against the outstanding balance:
+
+```ts
+const invoice = await dime.invoices.create('000010', {
+  customer_uuid: customer.uuid,
+  customer_name: 'Jane Doe',
+  customer_email: 'jane@example.com',
+  payment_terms: 'net_15',
+  cover_fee_required: true, // omit to inherit the merchant's invoice setting
+  lines: [{ item_id: 5, name: 'Consulting', quantity: 1, unit_price: 100 }],
+})
+
+invoice.total // '100.00' — what the merchant is owed
+invoice.coverFeeQuote?.ccTotal // '104.32' — charged if they pay by card
+invoice.coverFeeQuote?.achTotal // '101.26' — charged if they pay by bank
+```
+
+The card figure is the higher of the two and is what the invoice and its emails lead with. A partial
+payment re-quotes the fee against the partial amount, so treat the quote as "settling in full today"
+rather than a fixed charge. `coverFeeQuote` is `undefined` when no fee is required.
+
+To reconcile a payment, `amount` was credited to the invoice and `coverFee` was charged on top:
+
+```ts
+const payment = invoice.payments[0]!
+payment.amount // '100.00' — applied to the balance
+payment.coverFee // '4.32'  — the fee the customer also paid
+// The customer was charged amount + coverFee.
+```
+
+`pay()` behaves the same way: the fee for the `payment_type` you pass is added to `amount`, so the
+card or bank account is debited more than the invoice is credited.
+
 ### Recurring invoices
 
-Recurring-invoice templates generate and send invoices on a schedule.
+Recurring-invoice templates generate and send invoices on a schedule. `cover_fee_required` is copied
+onto every invoice a template generates.
 
 ```ts
 const template = await dime.recurringInvoices.create('000010', {
@@ -241,6 +287,7 @@ const template = await dime.recurringInvoices.create('000010', {
   recurring_frequency: 'Monthly', // Weekly | Biweekly | FirstFifteenth | Monthly | Yearly
   recurring_start_date: '2026-08-01',
   recurring_end_date: '2027-08-01', // optional
+  cover_fee_required: true, // optional
   lines: [{ item_id: 5, name: 'Monthly retainer', quantity: 1, unit_price: 500 }],
 })
 

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
   Client: () => Client,
   Config: () => Config,
   ConnectionException: () => ConnectionException,
+  CoverFeeQuote: () => CoverFeeQuote,
   CursorPage: () => CursorPage,
   Customer: () => Customer,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
@@ -61,7 +62,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/config.ts
 var DEFAULT_BASE_URL = "https://app.dimepayments.com";
-var VERSION = "1.2.0";
+var VERSION = "1.3.1";
 var Config = class {
   token;
   baseUrl;
@@ -838,6 +839,36 @@ var Deposits = class extends AbstractResource {
   }
 };
 
+// src/data-objects/cover-fee-quote.ts
+var CoverFeeQuote = class _CoverFeeQuote {
+  constructor(basis, base, ccFee, ccTotal, achFee, achTotal) {
+    this.basis = basis;
+    this.base = base;
+    this.ccFee = ccFee;
+    this.ccTotal = ccTotal;
+    this.achFee = achFee;
+    this.achTotal = achTotal;
+  }
+  basis;
+  base;
+  ccFee;
+  ccTotal;
+  achFee;
+  achTotal;
+  static fromRaw(data) {
+    const cc = arrObjectFrom(data, ["cc"]);
+    const ach = arrObjectFrom(data, ["ach"]);
+    return new _CoverFeeQuote(
+      arrString(data, "basis"),
+      arrString(data, "base"),
+      arrString(cc, "fee"),
+      arrString(cc, "total"),
+      arrString(ach, "fee"),
+      arrString(ach, "total")
+    );
+  }
+};
+
 // src/data-objects/invoice-customer.ts
 var InvoiceCustomer = class _InvoiceCustomer {
   constructor(id, name, email) {
@@ -912,29 +943,32 @@ var InvoiceLineItem = class _InvoiceLineItem {
 
 // src/data-objects/invoice-payment.ts
 var InvoicePayment = class _InvoicePayment {
-  constructor(amount, paidAt, method, transactionId) {
+  constructor(amount, paidAt, method, transactionId, coverFee) {
     this.amount = amount;
     this.paidAt = paidAt;
     this.method = method;
     this.transactionId = transactionId;
+    this.coverFee = coverFee;
   }
   amount;
   paidAt;
   method;
   transactionId;
+  coverFee;
   static fromRaw(data) {
     return new _InvoicePayment(
       arrString(data, "amount"),
       arrString(data, "paid_at"),
       arrString(data, "method"),
-      arrString(data, "transaction_id")
+      arrString(data, "transaction_id"),
+      arrString(data, "cover_fee")
     );
   }
 };
 
 // src/data-objects/invoice.ts
 var Invoice = class _Invoice {
-  constructor(id, invoiceNumber, status, token, paymentTerms, issueDate, dueDate, isOverdue = false, subtotal, total, amountPaid, balance, allowPartialPayment = false, thankYouNote, customerName, customerEmail, publicUrl, customer = new InvoiceCustomer(), items = [], payments = [], events = []) {
+  constructor(id, invoiceNumber, status, token, paymentTerms, issueDate, dueDate, isOverdue = false, subtotal, total, amountPaid, balance, allowPartialPayment = false, thankYouNote, customerName, customerEmail, publicUrl, customer = new InvoiceCustomer(), items = [], payments = [], events = [], coverFeeRequired = false, coverFeeQuote) {
     this.id = id;
     this.invoiceNumber = invoiceNumber;
     this.status = status;
@@ -956,6 +990,8 @@ var Invoice = class _Invoice {
     this.items = items;
     this.payments = payments;
     this.events = events;
+    this.coverFeeRequired = coverFeeRequired;
+    this.coverFeeQuote = coverFeeQuote;
   }
   id;
   invoiceNumber;
@@ -978,6 +1014,8 @@ var Invoice = class _Invoice {
   items;
   payments;
   events;
+  coverFeeRequired;
+  coverFeeQuote;
   static fromRaw(data) {
     return new _Invoice(
       arrInt(data, "id"),
@@ -1000,7 +1038,9 @@ var Invoice = class _Invoice {
       InvoiceCustomer.fromRaw(arrObjectFrom(data, ["customer"])),
       arrArrayFrom(data, "items").map(InvoiceLineItem.fromRaw),
       arrArrayFrom(data, "payments").map(InvoicePayment.fromRaw),
-      arrArrayFrom(data, "events").map(InvoiceEvent.fromRaw)
+      arrArrayFrom(data, "events").map(InvoiceEvent.fromRaw),
+      arrBool(data, "cover_fee_required"),
+      data["cover_fee_quote"] && typeof data["cover_fee_quote"] === "object" ? CoverFeeQuote.fromRaw(data["cover_fee_quote"]) : void 0
     );
   }
 };
@@ -1048,7 +1088,7 @@ var Invoices = class extends AbstractResource {
   /**
    * List invoices for a merchant.
    *
-   * @param filters `status` — draft | sent | paid | partial | void | overdue
+   * @param filters `status` — draft | sent | viewed | partially_paid | paid | void | refunded | overdue | all
    */
   async list(sid, filters = {}) {
     return this.paginate("GET", "invoices", this.envelope({ sid }, filters), Invoice.fromRaw);
@@ -1072,7 +1112,13 @@ var Invoices = class extends AbstractResource {
    *   `unit_price` and optional `description`. Optional: `invoice_number`,
    *   `issue_date` (Y-m-d, defaults to today — `due_date` is derived from
    *   `payment_terms`), `thank_you_note`, `allow_partial_payment`,
-   *   `reminder_settings`.
+   *   `cover_fee_required`, `reminder_settings`.
+   *
+   *   Set `cover_fee_required` to make the customer pay the processing fee. The
+   *   fee is added on top of the invoice at payment time rather than becoming a
+   *   line item, so `total` stays the amount owed to the merchant — read
+   *   `invoice.coverFeeQuote` for what the customer will actually be charged.
+   *   Omitting the field inherits the merchant's invoice setting.
    */
   async create(sid, attributes) {
     const raw = await this.transport.request(
@@ -1150,6 +1196,12 @@ var Invoices = class extends AbstractResource {
    *   `account_type` (Checking | Savings) / `account_name`. Omit `amount` to pay
    *   the full balance — partial amounts require the invoice to allow them.
    *   Optional: `memo`, `billing_address`.
+   *
+   *   On a cover-fee invoice the processing fee for `payment_type` is charged on
+   *   top of `amount`, so the card or bank account is debited more than the
+   *   invoice is credited. The fee lands as `coverFee` on the matching entry in
+   *   `invoice.payments`. Card and ACH rates differ, so the same `amount` settles
+   *   differently per `payment_type`.
    */
   async pay(sid, invoiceId, attributes) {
     const raw = await this.transport.request(
@@ -1475,7 +1527,7 @@ var PaymentMethods = class extends AbstractResource {
 
 // src/data-objects/recurring-invoice.ts
 var RecurringInvoice = class _RecurringInvoice {
-  constructor(id, status, recurrenceSchedule, paymentTerms, startDate, endDate, nextRunDate, lastRunDate, customerName, thankYouNote, customer = new InvoiceCustomer(), items = [], upcomingRunDates = [], invoices = []) {
+  constructor(id, status, recurrenceSchedule, paymentTerms, startDate, endDate, nextRunDate, lastRunDate, customerName, thankYouNote, customer = new InvoiceCustomer(), items = [], upcomingRunDates = [], invoices = [], coverFeeRequired = false) {
     this.id = id;
     this.status = status;
     this.recurrenceSchedule = recurrenceSchedule;
@@ -1490,6 +1542,7 @@ var RecurringInvoice = class _RecurringInvoice {
     this.items = items;
     this.upcomingRunDates = upcomingRunDates;
     this.invoices = invoices;
+    this.coverFeeRequired = coverFeeRequired;
   }
   id;
   status;
@@ -1505,6 +1558,7 @@ var RecurringInvoice = class _RecurringInvoice {
   items;
   upcomingRunDates;
   invoices;
+  coverFeeRequired;
   static fromRaw(data) {
     const runDates = data["upcoming_run_dates"];
     return new _RecurringInvoice(
@@ -1521,7 +1575,8 @@ var RecurringInvoice = class _RecurringInvoice {
       InvoiceCustomer.fromRaw(arrObjectFrom(data, ["customer"])),
       arrArrayFrom(data, "items").map(InvoiceLineItem.fromRaw),
       Array.isArray(runDates) ? runDates.map((d) => String(d)) : [],
-      arrArrayFrom(data, "invoices").map(Invoice.fromRaw)
+      arrArrayFrom(data, "invoices").map(Invoice.fromRaw),
+      arrBool(data, "cover_fee_required")
     );
   }
 };
@@ -1560,6 +1615,9 @@ var RecurringInvoices = class extends AbstractResource {
    *   `recurring_start_date` (Y-m-d) and `lines` are required. Optional:
    *   `recurring_end_date` (Y-m-d, on or after the start date),
    *   `thank_you_note`.
+   *
+   *   `cover_fee_required` makes the customer cover the processing fee on every
+   *   invoice this template generates.
    */
   async create(sid, attributes) {
     const raw = await this.transport.request(
@@ -1875,6 +1933,7 @@ var Client = class {
   Client,
   Config,
   ConnectionException,
+  CoverFeeQuote,
   CursorPage,
   Customer,
   DEFAULT_BASE_URL,