@dime-technology/dime-js-sdk 1.0.0 → 1.3.0

package/README.md

@@ -46,13 +46,15 @@ import { Client, Config } from '@dime-technology/dime-js-sdk'
 const dime = new Client('your-api-token', 'https://staging.dimepayments.com')
 
 // Full control
-const dime = new Client(new Config({
-  token: 'your-api-token',
-  baseUrl: 'https://app.dimepayments.com',
-  timeout: 30,        // seconds
-  maxRetries: 2,      // retries 429 / 5xx / network errors with backoff
-  retryBaseDelay: 0.5,
-}))
+const dime = new Client(
+  new Config({
+    token: 'your-api-token',
+    baseUrl: 'https://app.dimepayments.com',
+    timeout: 30, // seconds
+    maxRetries: 2, // retries 429 / 5xx / network errors with backoff
+    retryBaseDelay: 0.5,
+  }),
+)
 ```
 
 The SDK sends `Authorization: Bearer <token>` and JSON headers on every request. Transient
@@ -65,15 +67,17 @@ Every resource hangs off the client as a property. The merchant `sid` is always
 explicitly; remaining fields go in an attributes object (and lookups, where the API expects
 them, in a `filters` object). All amounts are returned as strings to avoid float rounding.
 
-| Property                     | Endpoints                                                        |
-| ---------------------------- | ---------------------------------------------------------------- |
-| `dime.transactions`          | chargeCard, chargeAch, tokenizeCard, refund, void, show, list    |
-| `dime.customers`             | list, show, create, update, delete                               |
-| `dime.paymentMethods`        | list, show, create, update, delete                               |
-| `dime.merchants`             | list, show, create, update, getFormLink                          |
-| `dime.addresses`             | list, show, create, update, delete                               |
-| `dime.deposits`              | list, listWithTransactions, show                                 |
-| `dime.recurringPayments`     | list, show, create, edit, pause, cancel, activate, delete        |
+| Property                 | Endpoints                                                                                                                                             |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dime.transactions`      | chargeCard, chargeAch, tokenizeCard, refund, void, show, list                                                                                         |
+| `dime.customers`         | list, show, create, update, delete                                                                                                                    |
+| `dime.paymentMethods`    | list, show, create, update, delete                                                                                                                    |
+| `dime.merchants`         | list, show, create, update, getFormLink                                                                                                               |
+| `dime.addresses`         | list, show, create, update, delete                                                                                                                    |
+| `dime.deposits`          | list, listWithTransactions, show                                                                                                                      |
+| `dime.recurringPayments` | list, show, create, edit, pause, cancel, activate, delete                                                                                             |
+| `dime.invoices`          | list, show, create, update, delete, send, markSent, void, duplicate, pay, getLink, addLineItem, updateLineItem, deleteLineItem, listItems, createItem |
+| `dime.recurringInvoices` | list, show, create, cancel                                                                                                                            |
 
 ### Transactions
 
@@ -164,6 +168,132 @@ await dime.recurringPayments.activate('000010', rp.id!)
 await dime.recurringPayments.cancel('000010', rp.id!)
 ```
 
+### Invoices
+
+Invoices are scoped to a merchant `sid` and built from line items that each reference a merchant
+item (a fund/designation). Draft invoices can be edited; once sent they are locked. Amounts are
+returned as strings.
+
+Identify the customer with `customer_uuid` — the same uuid every other resource uses, and the only
+identifier the customer endpoints return. `customer_id` is still accepted for older integrations.
+
+```ts
+// Look up (or create) the items a line can reference
+const items = await dime.invoices.listItems('000010')
+const item = await dime.invoices.createItem('000010', {
+  name: 'Consulting',
+  price: 125,
+  tax_deductible: false,
+})
+
+// Create a draft invoice with one or more line items
+const invoice = await dime.invoices.create('000010', {
+  customer_uuid: customer.uuid,
+  customer_name: 'Jane Doe',
+  customer_email: 'jane@example.com',
+  payment_terms: 'net_15', // due_on_receipt | net_15 | net_30 | net_60
+  lines: [
+    { item_id: item.id, name: 'Consulting', description: '2 hours', quantity: 2, unit_price: 125 },
+  ],
+})
+
+// Tweak the draft's line items (each returns the refreshed invoice)
+await dime.invoices.addLineItem('000010', invoice.id!, {
+  item_id: item.id!,
+  name: 'Setup',
+  quantity: 1,
+  unit_price: 50,
+})
+await dime.invoices.updateLineItem('000010', invoice.id!, invoice.items[0]!.id!, { quantity: 3 })
+await dime.invoices.deleteLineItem('000010', invoice.id!, invoice.items[0]!.id!)
+
+// Email it to the customer, or activate the pay link without emailing
+await dime.invoices.send('000010', invoice.id!)
+await dime.invoices.markSent('000010', invoice.id!)
+
+// Share the public pay link
+const { publicUrl } = await dime.invoices.getLink('000010', invoice.id!)
+
+// Take a merchant-initiated (MOTO) payment against an open invoice
+await dime.invoices.pay('000010', invoice.id!, {
+  payment_type: 'cc', // cc | ach
+  token: 'tok_abc123',
+  amount: 100, // optional partial amount when the invoice allows it
+})
+
+// Duplicate, void, delete
+const copy = await dime.invoices.duplicate('000010', invoice.id!)
+await dime.invoices.void('000010', invoice.id!)
+await dime.invoices.delete('000010', copy.id!) // drafts only
+
+// List, optionally filtered by status
+const page = await dime.invoices.list('000010', { status: 'sent' })
+```
+
+#### 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. `cover_fee_required` is copied
+onto every invoice a template generates.
+
+```ts
+const template = await dime.recurringInvoices.create('000010', {
+  customer_uuid: customer.uuid,
+  payment_terms: 'net_15',
+  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 }],
+})
+
+const detail = await dime.recurringInvoices.show('000010', template.id!)
+detail.upcomingRunDates // ['2026-08-01', '2026-09-01', ...]
+
+await dime.recurringInvoices.cancel('000010', template.id!)
+
+const page = await dime.recurringInvoices.list('000010', { status: 'Active' })
+```
+
 ## Pagination
 
 List endpoints return a `CursorPage`. Iterate one page, walk pages manually, or stream every
@@ -206,28 +336,28 @@ try {
   await dime.transactions.chargeCard('000010', { amount: '0' })
 } catch (e) {
   if (e instanceof ValidationException) {
-    e.getErrors()   // { 'data.amount': ['must be greater than 0'] }
+    e.getErrors() // { 'data.amount': ['must be greater than 0'] }
     e.firstError()
   } else if (e instanceof RateLimitException) {
     const wait = e.getRetryAfter() ?? 1
-    await new Promise(r => setTimeout(r, wait * 1000))
+    await new Promise((r) => setTimeout(r, wait * 1000))
   } else if (e instanceof DimeException) {
-    e.getStatusCode()    // HTTP status
-    e.getResponseBody()  // decoded API body
+    e.getStatusCode() // HTTP status
+    e.getResponseBody() // decoded API body
   }
 }
 ```
 
-| Exception                    | When                                                         |
-| ---------------------------- | ------------------------------------------------------------ |
-| `ValidationException`        | HTTP 400/422 with field errors                               |
-| `AuthenticationException`    | HTTP 401 (missing/invalid token)                             |
-| `PermissionDeniedException`  | HTTP 403 (belongs-to-company guard)                          |
-| `NotFoundException`          | HTTP 404                                                     |
-| `RateLimitException`         | HTTP 429 (carries `Retry-After`)                             |
-| `ServerException`            | HTTP 5xx                                                     |
-| `ConnectionException`        | No HTTP response (DNS, timeout, network error)               |
-| `ApiException`               | Any other non-2xx                                            |
+| Exception                   | When                                           |
+| --------------------------- | ---------------------------------------------- |
+| `ValidationException`       | HTTP 400/422 with field errors                 |
+| `AuthenticationException`   | HTTP 401 (missing/invalid token)               |
+| `PermissionDeniedException` | HTTP 403 (belongs-to-company guard)            |
+| `NotFoundException`         | HTTP 404                                       |
+| `RateLimitException`        | HTTP 429 (carries `Retry-After`)               |
+| `ServerException`           | HTTP 5xx                                       |
+| `ConnectionException`       | No HTTP response (DNS, timeout, network error) |
+| `ApiException`              | Any other non-2xx                              |
 
 ## Notes