From 27ba25e3b6c778f9e838a2426a4812894e5d1111 Mon Sep 17 00:00:00 2001 From: ivanmilevtues Date: Thu, 22 Oct 2026 15:31:15 +0200 Subject: [PATCH] feat: add instant refunds through a new ledger service --- app.js | 12 +++++---- apps/storefront/account-page.js | 6 ++--- services/checkout/checkout-api.js | 4 +-- services/ledger/account-repository.js | 10 +++++++ services/ledger/balance-reader.js | 9 +++++++ services/ledger/create-ledger.js | 13 +++++++++ services/ledger/entry-repository.js | 14 ++++++++++ services/ledger/ledger-service.js | 33 +++++++++++++++++++++++ services/ledger/outbox.js | 11 ++++++++ services/payments/payment-service.js | 6 ++++- services/refunds/refund-service.js | 8 +++--- tests/ledger.test.js | 38 +++++++++++++++++++++++++++ tests/refunds.test.js | 7 +++-- 13 files changed, 152 insertions(+), 19 deletions(-) create mode 100644 services/ledger/account-repository.js create mode 100644 services/ledger/balance-reader.js create mode 100644 services/ledger/create-ledger.js create mode 100644 services/ledger/entry-repository.js create mode 100644 services/ledger/ledger-service.js create mode 100644 services/ledger/outbox.js create mode 100644 tests/ledger.test.js diff --git a/app.js b/app.js index 1f88a6e..0515a2f 100644 --- a/app.js +++ b/app.js @@ -8,16 +8,18 @@ import { CheckoutApi } from './services/checkout/checkout-api.js'; import { StorefrontAccount } from './apps/storefront/account-page.js'; import { SupportConsole } from './apps/support/refund-console.js'; import { FinanceExport } from './apps/finance/reconciliation.js'; +import { createLedger } from './services/ledger/create-ledger.js'; export function createCommerce() { const orders = new OrderRepository(); const cardGateway = new CardGateway(); - const payments = new PaymentService(cardGateway); + const ledger = createLedger(); + const payments = new PaymentService(cardGateway, ledger); const notifications = new NotificationService(); - const refunds = new RefundService(orders, payments, new RefundPolicy(), notifications); - const checkout = new CheckoutApi(orders, refunds, payments); - const storefront = new StorefrontAccount(checkout); + const refunds = new RefundService(orders, ledger, new RefundPolicy(), notifications); + const checkout = new CheckoutApi(orders, refunds, payments, ledger); + const storefront = new StorefrontAccount(checkout, ledger); const support = new SupportConsole(refunds); const finance = new FinanceExport(orders, payments); - return { orders, cardGateway, payments, notifications, refunds, checkout, storefront, support, finance }; + return { orders, cardGateway, payments, notifications, refunds, checkout, storefront, support, finance, ledger }; } diff --git a/apps/storefront/account-page.js b/apps/storefront/account-page.js index 42b046c..1418d98 100644 --- a/apps/storefront/account-page.js +++ b/apps/storefront/account-page.js @@ -2,14 +2,14 @@ import { formatMoney } from '../../packages/money/money.js'; /** Account view model consumed by the storefront UI. */ export class StorefrontAccount { - constructor(checkout) { this.checkout = checkout; } + constructor(checkout, ledger) { Object.assign(this, { checkout, ledger }); } refundOrder(customerId, orderId, amount, requestId) { return this.checkout.requestRefund(customerId, { orderId, amount, requestId }); } renderBalance(customerId, currency = 'EUR') { - const summary = this.checkout.accountSummary(customerId); - return `Store credit: ${formatMoney(summary.storeCredit, currency)}`; + const availableCredit = this.ledger.balance(customerId, currency); + return `Store credit: ${formatMoney(availableCredit, currency)}`; } } diff --git a/services/checkout/checkout-api.js b/services/checkout/checkout-api.js index 10c14a2..0e8f85e 100644 --- a/services/checkout/checkout-api.js +++ b/services/checkout/checkout-api.js @@ -1,5 +1,5 @@ export class CheckoutApi { - constructor(orders, refunds, payments) { Object.assign(this, { orders, refunds, payments }); } + constructor(orders, refunds, payments, ledger) { Object.assign(this, { orders, refunds, payments, ledger }); } requestRefund(customerId, request) { const order = this.orders.get(request.orderId); @@ -10,6 +10,6 @@ export class CheckoutApi { accountSummary(customerId) { const orders = this.orders.list().filter(order => order.customerId === customerId); const cardRefunds = orders.flatMap(order => this.payments.refundsForOrder(order)); - return { customerId, orders, cardRefunds, storeCredit: 0 }; + return { customerId, orders, cardRefunds, storeCredit: this.ledger.balance(customerId, 'EUR') }; } } diff --git a/services/ledger/account-repository.js b/services/ledger/account-repository.js new file mode 100644 index 0000000..b9e8c2d --- /dev/null +++ b/services/ledger/account-repository.js @@ -0,0 +1,10 @@ +export class LedgerAccountRepository { + #accounts = new Map(); + + forCustomer(customerId, currency) { + if (!customerId) throw new Error('Customer ID required'); + const key = `${customerId}:${currency}`; + if (!this.#accounts.has(key)) this.#accounts.set(key, { id: key, customerId, currency }); + return { ...this.#accounts.get(key) }; + } +} diff --git a/services/ledger/balance-reader.js b/services/ledger/balance-reader.js new file mode 100644 index 0000000..041ac69 --- /dev/null +++ b/services/ledger/balance-reader.js @@ -0,0 +1,9 @@ +export class LedgerBalanceReader { + constructor(entries) { this.entries = entries; } + + availableCredit(accountId) { + return this.entries.forAccount(accountId) + .filter(entry => entry.kind === 'refund-credit') + .reduce((total, entry) => total + entry.amount, 0); + } +} diff --git a/services/ledger/create-ledger.js b/services/ledger/create-ledger.js new file mode 100644 index 0000000..a9bf97a --- /dev/null +++ b/services/ledger/create-ledger.js @@ -0,0 +1,13 @@ +import { LedgerAccountRepository } from './account-repository.js'; +import { LedgerEntryRepository } from './entry-repository.js'; +import { LedgerBalanceReader } from './balance-reader.js'; +import { LedgerOutbox } from './outbox.js'; +import { LedgerService } from './ledger-service.js'; + +export function createLedger() { + const accounts = new LedgerAccountRepository(); + const entries = new LedgerEntryRepository(); + const balances = new LedgerBalanceReader(entries); + const outbox = new LedgerOutbox(); + return new LedgerService(accounts, entries, balances, outbox); +} diff --git a/services/ledger/entry-repository.js b/services/ledger/entry-repository.js new file mode 100644 index 0000000..922acb9 --- /dev/null +++ b/services/ledger/entry-repository.js @@ -0,0 +1,14 @@ +export class LedgerEntryRepository { + #entries = new Map(); + + insert(entry) { + const existing = this.#entries.get(entry.id); + if (existing && JSON.stringify(existing) !== JSON.stringify(entry)) throw new Error('Entry ID conflict'); + this.#entries.set(entry.id, { ...entry }); + return { ...entry }; + } + + forAccount(accountId) { + return [...this.#entries.values()].filter(entry => entry.accountId === accountId).map(entry => ({ ...entry })); + } +} diff --git a/services/ledger/ledger-service.js b/services/ledger/ledger-service.js new file mode 100644 index 0000000..e462762 --- /dev/null +++ b/services/ledger/ledger-service.js @@ -0,0 +1,33 @@ +import { assertAmount } from '../../packages/money/money.js'; + +/** Posts commerce money events and exposes customers' available store credit. */ +export class LedgerService { + constructor(accounts, entries, balances, outbox) { Object.assign(this, { accounts, entries, balances, outbox }); } + + creditRefund(order, amount, requestId) { + assertAmount(amount, order.currency); + const account = this.accounts.forCustomer(order.customerId, order.currency); + const entry = this.entries.insert({ + id: `ledger-${requestId}`, accountId: account.id, amount, currency: order.currency, + kind: 'refund-credit', orderId: order.id, destination: 'store-credit', + }); + this.outbox.enqueue(entry); + return entry; + } + + recordSettlement(order, requestId) { + assertAmount(order.paidAmount, order.currency); + const account = this.accounts.forCustomer(order.customerId, order.currency); + const entry = this.entries.insert({ + id: `settlement-${requestId}`, accountId: account.id, amount: order.paidAmount, + currency: order.currency, kind: 'card-settlement', orderId: order.id, + }); + this.outbox.enqueue(entry); + return entry; + } + + balance(customerId, currency) { + const account = this.accounts.forCustomer(customerId, currency); + return this.balances.availableCredit(account.id); + } +} diff --git a/services/ledger/outbox.js b/services/ledger/outbox.js new file mode 100644 index 0000000..b2449d3 --- /dev/null +++ b/services/ledger/outbox.js @@ -0,0 +1,11 @@ +export class LedgerOutbox { + #events = new Map(); + + enqueue(entry) { + const event = { id: `event-${entry.id}`, kind: 'ledger.entry.posted', entryId: entry.id, accountId: entry.accountId }; + this.#events.set(event.id, event); + return { ...event }; + } + + pending() { return [...this.#events.values()].map(event => ({ ...event })); } +} diff --git a/services/payments/payment-service.js b/services/payments/payment-service.js index d00d369..e155e7c 100644 --- a/services/payments/payment-service.js +++ b/services/payments/payment-service.js @@ -1,5 +1,9 @@ export class PaymentService { - constructor(cardGateway) { this.cardGateway = cardGateway; } + constructor(cardGateway, ledger) { Object.assign(this, { cardGateway, ledger }); } + + recordSettlement(order, requestId) { + return this.ledger.recordSettlement(order, requestId); + } refundOriginalPayment(order, amount, requestId) { return this.cardGateway.reverseCharge({ paymentId: order.paymentId, amount, currency: order.currency, requestId }); diff --git a/services/refunds/refund-service.js b/services/refunds/refund-service.js index 757b95e..2a1629f 100644 --- a/services/refunds/refund-service.js +++ b/services/refunds/refund-service.js @@ -1,8 +1,8 @@ export class RefundService { #requests = new Map(); - constructor(orders, payments, policy, notifications) { - Object.assign(this, { orders, payments, policy, notifications }); + constructor(orders, ledger, policy, notifications) { + Object.assign(this, { orders, ledger, policy, notifications }); } issueRefund({ orderId, amount, requestId }) { @@ -14,8 +14,8 @@ export class RefundService { } const order = this.orders.get(orderId); this.policy.validate(order, amount); - const paymentRefund = this.payments.refundOriginalPayment(order, amount, requestId); - const refund = { ...paymentRefund, orderId, customerId: order.customerId, status: 'completed' }; + const ledgerEntry = this.ledger.creditRefund(order, amount, requestId); + const refund = { ...ledgerEntry, orderId, customerId: order.customerId, status: 'completed' }; this.orders.recordRefund(orderId, refund); this.notifications.sendRefundReceipt(refund); this.#requests.set(requestId, refund); diff --git a/tests/ledger.test.js b/tests/ledger.test.js new file mode 100644 index 0000000..e54d1ae --- /dev/null +++ b/tests/ledger.test.js @@ -0,0 +1,38 @@ +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { createLedger } from '../services/ledger/create-ledger.js'; + +const order = { id: 'order-1042', customerId: 'customer-demo', paidAmount: 12900, currency: 'EUR' }; + +test('a posted refund is immediately available as store credit', () => { + const ledger = createLedger(); + ledger.creditRefund(order, 4900, 'r-1'); + assert.equal(ledger.balance(order.customerId, 'EUR'), 4900); +}); + +test('reposting the same refund does not double the balance', () => { + const ledger = createLedger(); + ledger.creditRefund(order, 4900, 'r-1'); + ledger.creditRefund(order, 4900, 'r-1'); + assert.equal(ledger.balance(order.customerId, 'EUR'), 4900); + assert.equal(ledger.outbox.pending().length, 1); +}); + +test('settlements do not become spendable customer credit', () => { + const ledger = createLedger(); + ledger.recordSettlement(order, 's-1'); + assert.equal(ledger.balance(order.customerId, 'EUR'), 0); +}); + +test('credit is isolated by customer and currency', () => { + const ledger = createLedger(); + ledger.creditRefund(order, 4900, 'r-1'); + assert.equal(ledger.balance('another-customer', 'EUR'), 0); + assert.equal(ledger.balance(order.customerId, 'CHF'), 0); +}); + +test('conflicting ledger entry IDs are rejected', () => { + const ledger = createLedger(); + ledger.creditRefund(order, 4900, 'r-1'); + assert.throws(() => ledger.creditRefund(order, 5100, 'r-1'), /conflict/); +}); diff --git a/tests/refunds.test.js b/tests/refunds.test.js index 9346836..7b79ae5 100644 --- a/tests/refunds.test.js +++ b/tests/refunds.test.js @@ -8,12 +8,11 @@ function fixture() { return app; } -test('a refund returns money to the original card', () => { +test('an instant refund updates the account balance', () => { const app = fixture(); const result = app.storefront.refundOrder('customer-demo', 'order-1042', 4900, 'refund-demo'); - assert.equal(result.destination, 'original-card'); - assert.equal(app.cardGateway.listReversals()[0].amount, 4900); - assert.equal(app.finance.reconcile()[0].discrepancy, 0); + assert.equal(result.status, 'completed'); + assert.equal(app.ledger.balance('customer-demo', 'EUR'), 4900); }); test('a retry does not refund the card twice', () => {