@stamhoofd/backend 2.143.0 → 2.144.0

package/src/services/SettlementService.ts

@@ -6,7 +6,8 @@ import { ApplicationFee } from '@stamhoofd/models/models/ApplicationFee.js';
 import { PaymentSettlement } from '@stamhoofd/models/models/PaymentSettlement.js';
 import { Settlement } from '@stamhoofd/models/models/Settlement.js';
 import { SettlementCharge } from '@stamhoofd/models/models/SettlementCharge.js';
-import { AbortSignal, QueueHandler } from '@stamhoofd/queues';
+import type { AbortSignal } from '@stamhoofd/queues';
+import { QueueHandler } from '@stamhoofd/queues';
 import { SQL } from '@stamhoofd/sql';
 import type { PaymentProvider } from '@stamhoofd/structures';
 import { PaymentMethod, SettlementReference } from '@stamhoofd/structures';
@@ -67,44 +68,6 @@ const CHARGE_UPDATE_BATCH_SIZE = 500;
  */
 const FEE_BATCH_SIZE = 500;
 
-/**
- * Collects which rows the provider still reports in a settlement while a sync walks it. A stored
- * row of the settlement that is not in here after the walk has moved or disappeared at the
- * provider, and gets swept.
- */
-export class ReportedRows {
-    readonly paymentLineExternalIds = new Set<string>();
-    readonly chargeExternalIds = new Set<string>();
-    readonly applicationFeeIds = new Set<string>();
-
-    paymentLine(line: PaymentSettlement) {
-        if (line.externalId === null) {
-            return;
-        }
-        this.paymentLineExternalIds.add(line.externalId);
-    }
-
-    charge(charge: SettlementCharge) {
-        this.chargeExternalIds.add(charge.externalId);
-    }
-
-    charges(charges: SettlementCharge[]) {
-        for (const charge of charges) {
-            this.charge(charge);
-        }
-    }
-
-    applicationFee(fee: ApplicationFee) {
-        this.applicationFeeIds.add(fee.id);
-    }
-
-    applicationFees(fees: ApplicationFee[]) {
-        for (const fee of fees) {
-            this.applicationFee(fee);
-        }
-    }
-}
-
 /**
  * All writes to the settlements tables go through this service. Every write is an upsert on the
  * deterministic unique key of its table, so re-running a sync can never duplicate rows.
@@ -317,77 +280,6 @@ export class SettlementService {
         }
     }
 
-    /**
-     * After a complete walk of a settlement: remove rows the provider no longer reports in this
-     * settlement (a transaction can move to another payout). Rows that only exist because of the
-     * payout are deleted; rows that outlive the payout link are only unlinked: derived fee lines
-     * (owned by updatePaymentSettlementsForAccountDeductionPayment), deduction charges referenced
-     * by an application fee, and the application fee rows themselves.
-     *
-     * Returns the fees unlinked from this settlement, so the caller can refresh the derived lines
-     * of their fee payments.
-     */
-    static async sweepSettlement(settlement: Settlement, reported: ReportedRows): Promise<{ unlinkedFees: ApplicationFee[] }> {
-        const lines = await PaymentSettlement.select()
-            .where('settlementId', settlement.id)
-            .fetch();
-
-        const sweptPaymentIds = new Set<string>();
-        for (const line of lines) {
-            if (line.externalId === null) {
-                continue;
-            }
-            if (!reported.paymentLineExternalIds.has(line.externalId)) {
-                await line.delete();
-                sweptPaymentIds.add(line.paymentId);
-            }
-        }
-
-        // The legacy blob points at one of the lines, so a payment that lost one has to be
-        // repointed at what is left
-        if (sweptPaymentIds.size > 0) {
-            const payments = await PaymentModel.getByIDs(...sweptPaymentIds);
-            for (const payment of payments) {
-                await this.updateLegacySettlementReference(payment);
-            }
-        }
-
-        const charges = await SettlementCharge.select()
-            .where('settlementId', settlement.id)
-            .fetch();
-
-        const unreportedCharges = charges.filter(charge => !reported.chargeExternalIds.has(charge.externalId));
-        const referencedChargeIds = unreportedCharges.length > 0
-            ? new Set((await ApplicationFee.select()
-                    .where('settlementChargeId', unreportedCharges.map(c => c.id))
-                    .fetch()).map(fee => fee.settlementChargeId))
-            : new Set<string>();
-
-        for (const charge of unreportedCharges) {
-            if (referencedChargeIds.has(charge.id)) {
-                charge.settlementId = null;
-                await charge.save();
-            } else {
-                await charge.delete();
-            }
-        }
-
-        const fees = await ApplicationFee.select()
-            .where('settlementId', settlement.id)
-            .fetch();
-
-        const unlinkedFees: ApplicationFee[] = [];
-        for (const fee of fees) {
-            if (!reported.applicationFeeIds.has(fee.id)) {
-                fee.settlementId = null;
-                await fee.save();
-                unlinkedFees.push(fee);
-            }
-        }
-
-        return { unlinkedFees };
-    }
-
     /**
      * Recomputes the cached reconciliation columns from the stored rows: `unexplainedAmount` should
      * be 0 — a non-zero value is a real question to answer — and `pendingFees` holds what is
@@ -500,7 +392,7 @@ export class SettlementService {
      * payout that contains fees billed by this payment, amount = the sum of those fees. When the
      * total of the lines matches the payment's price, the payment is completely paid out.
      */
-    static async updatePaymentSettlementsForAccountDeductionPayment(payment: Payment): Promise<void> {
+    static async updatePaymentSettlementsForApplicationFeePayment(payment: Payment): Promise<void> {
         if (payment.method !== PaymentMethod.AccountDeductions) {
             return;
         }
@@ -567,7 +459,7 @@ export class SettlementService {
      * Refreshes the derived lines of every fee payment that billed one of these balance items:
      * called after a walk linked or unlinked invoiced fees, so the lines follow the fees.
      */
-    static async updatePaymentSettlementsForAccountDeductionBalanceItems(balanceItemIds: string[]): Promise<void> {
+    static async updatePaymentSettlementsForApplicationFeeBalanceItems(balanceItemIds: string[]): Promise<void> {
         if (balanceItemIds.length === 0) {
             return;
         }
@@ -582,7 +474,7 @@ export class SettlementService {
 
         const payments = await PaymentModel.getByIDs(...paymentIds);
         for (const payment of payments) {
-            await this.updatePaymentSettlementsForAccountDeductionPayment(payment);
+            await this.updatePaymentSettlementsForApplicationFeePayment(payment);
         }
     }
 

package/src/sql-filters/balance-items.ts

@@ -99,6 +99,16 @@ export const balanceItemFilterCompilers: SQLFilterDefinitions = {
         type: SQLValueType.String,
         nullable: true,
     }),
+    orderId: createColumnFilter({
+        expression: SQL.column('balance_items', 'orderId'),
+        type: SQLValueType.String,
+        nullable: true,
+    }),
+    registrationId: createColumnFilter({
+        expression: SQL.column('balance_items', 'registrationId'),
+        type: SQLValueType.String,
+        nullable: true,
+    }),
     type: createColumnFilter({
         expression: SQL.column('balance_items', 'type'),
         type: SQLValueType.String,

package/tests/helpers/MollieMocker.ts

@@ -53,13 +53,6 @@ export type MollieMockRefund = {
     metadata: Record<string, unknown> | null;
 };
 
-export type MollieMockSettlementCost = {
-    description: string;
-    method: string | null;
-    amountNet: { currency: string; value: string };
-    amountVat: { currency: string; value: string } | null;
-};
-
 export type MollieMockSettlement = {
     id: string;
     reference: string;
@@ -68,10 +61,6 @@ export type MollieMockSettlement = {
     createdAt: string;
     /** null for the still-open settlement, a date once it has been paid out */
     settledAt: string | null;
-    /** id of the invoice Mollie created for the settlement costs, null until it exists */
-    invoiceId: string | null;
-    /** Mollie's own costs per period, keyed year → month */
-    periods: Record<string, Record<string, { costs: MollieMockSettlementCost[]; invoiceId?: string | null }>>;
     /** Mollie payment ids (tr_...) settled in this settlement */
     paymentIds: string[];
     /** Mollie refund ids (re_...) settled in this settlement */
@@ -80,6 +69,15 @@ export type MollieMockSettlement = {
     chargebackIds: string[];
 };
 
+export type MollieMockBalanceTransaction = {
+    id: string;
+    type: string;
+    createdAt: string;
+    deductions: { currency: string; value: string } | null;
+    deductionDetails: { fees?: { currency: string; value: string } } | null;
+    context: Record<string, string> | null;
+};
+
 const MOLLIE_CHECKOUT_URL = 'https://molliecheckout/';
 
 /**
@@ -104,6 +102,7 @@ export class MollieMocker {
     chargebacks: MollieMockChargeback[] = [];
     refunds: MollieMockRefund[] = [];
     settlements: MollieMockSettlement[] = [];
+    balanceTransactions: MollieMockBalanceTransaction[] = [];
 
     /**
      * Cap the settlements list page size below the requested limit, to exercise pagination
@@ -111,6 +110,11 @@ export class MollieMocker {
      */
     settlementsPageSize: number | null = null;
 
+    /**
+     * Same, for the balance transactions list.
+     */
+    balanceTransactionsPageSize: number | null = null;
+
     #forceFailure = false;
 
     reset() {
@@ -120,7 +124,9 @@ export class MollieMocker {
         this.chargebacks = [];
         this.refunds = [];
         this.settlements = [];
+        this.balanceTransactions = [];
         this.settlementsPageSize = null;
+        this.balanceTransactionsPageSize = null;
         this.#forceFailure = false;
     }
 
@@ -242,6 +248,11 @@ export class MollieMocker {
             return this.#listResource('chargebacks', this.chargebacks.map(c => this.#chargebackResource(c)));
         }
 
+        // balance transactions (drives the transaction fee part of the settlements sync)
+        if (parts[0] === 'balances' && method === 'GET' && parts.length === 3 && parts[2] === 'transactions') {
+            return this.#listBalanceTransactions(uri);
+        }
+
         // settlements + nested payments/refunds (drives the settlements sync)
         if (parts[0] === 'settlements' && method === 'GET') {
             if (parts.length === 1) {
@@ -574,7 +585,7 @@ export class MollieMocker {
      * Register a settled (paid out) settlement that groups the given payments and refunds.
      * Used to drive the MollieSettlementSync walk.
      */
-    createSettlement(options: { payments?: MollieMockPayment[]; refunds?: MollieMockRefund[]; chargebacks?: MollieMockChargeback[]; value?: string; settledAt?: Date; invoiceId?: string | null; periods?: Record<string, Record<string, { costs: MollieMockSettlementCost[]; invoiceId?: string | null }>> } = {}): MollieMockSettlement {
+    createSettlement(options: { payments?: MollieMockPayment[]; refunds?: MollieMockRefund[]; chargebacks?: MollieMockChargeback[]; value?: string; settledAt?: Date } = {}): MollieMockSettlement {
         const settlement: MollieMockSettlement = {
             id: this.createId('stl'),
             reference: '1234567.' + (this.settlements.length + 1).toString().padStart(4, '0') + '.01',
@@ -582,8 +593,6 @@ export class MollieMocker {
             amount: { currency: 'EUR', value: options.value ?? '0.00' },
             createdAt: new Date().toISOString(),
             settledAt: (options.settledAt ?? new Date()).toISOString(),
-            invoiceId: options.invoiceId ?? null,
-            periods: options.periods ?? {},
             paymentIds: (options.payments ?? []).map(p => p.id),
             refundIds: (options.refunds ?? []).map(r => r.id),
             chargebackIds: (options.chargebacks ?? []).map(c => c.id),
@@ -637,12 +646,76 @@ export class MollieMocker {
             amount: settlement.amount,
             createdAt: settlement.createdAt,
             settledAt: settlement.settledAt ?? null,
-            invoiceId: settlement.invoiceId,
-            periods: settlement.periods,
             _links: { self: { href: 'https://api.mollie.com/v2/settlements/' + settlement.id, type: 'application/hal+json' } },
         };
     }
 
+    // ---- Balance transactions ---------------------------------------------
+
+    /**
+     * Register the balance transaction of a payment, refund or chargeback, carrying the fee Mollie
+     * deducted for it. `fee` and `deductions` are positive euro values, stored negated like Mollie
+     * reports them. Pass only `deductions` for a transaction without the deductionDetails breakdown.
+     */
+    createBalanceTransaction(options: {
+        type: 'payment' | 'refund' | 'chargeback';
+        entryId: string;
+        fee?: string;
+        deductions?: string;
+        createdAt?: Date;
+    }): MollieMockBalanceTransaction {
+        const contextKey = options.type === 'payment' ? 'paymentId' : options.type === 'refund' ? 'refundId' : 'chargebackId';
+        const deductions = options.deductions ?? options.fee;
+
+        const transaction: MollieMockBalanceTransaction = {
+            id: this.createId('baltr'),
+            type: options.type,
+            createdAt: (options.createdAt ?? new Date()).toISOString(),
+            deductions: deductions ? { currency: 'EUR', value: '-' + deductions } : null,
+            deductionDetails: options.fee ? { fees: { currency: 'EUR', value: '-' + options.fee } } : null,
+            context: { [contextKey]: options.entryId },
+        };
+        this.balanceTransactions.push(transaction);
+        return transaction;
+    }
+
+    /**
+     * Mollie lists balance transactions newest-first, paginated like the settlements list.
+     */
+    #listBalanceTransactions(uri: string): [number, unknown] {
+        const query = new URLSearchParams(uri.split('?')[1] ?? '');
+
+        const sorted = this.balanceTransactions.slice().sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+
+        const requestedLimit = parseInt(query.get('limit') ?? '250');
+        const limit = Math.min(requestedLimit, this.balanceTransactionsPageSize ?? requestedLimit);
+
+        const from = query.get('from');
+        const startIndex = from ? sorted.findIndex(t => t.id === from) : 0;
+        if (startIndex === -1) {
+            return [404, { status: 404, title: 'Not Found', detail: 'No balance transaction exists with token ' + from }];
+        }
+
+        const page = sorted.slice(startIndex, startIndex + limit);
+        const nextItem = sorted[startIndex + limit];
+
+        return this.#listResource('balance_transactions', page.map(t => this.#balanceTransactionResource(t)), {
+            next: nextItem ? 'https://api.mollie.com/v2/balances/primary/transactions?limit=' + requestedLimit + '&from=' + nextItem.id : null,
+        });
+    }
+
+    #balanceTransactionResource(transaction: MollieMockBalanceTransaction) {
+        return {
+            resource: 'balance-transaction',
+            id: transaction.id,
+            type: transaction.type,
+            createdAt: transaction.createdAt,
+            deductions: transaction.deductions,
+            deductionDetails: transaction.deductionDetails,
+            context: transaction.context,
+        };
+    }
+
     // ---- List helper ------------------------------------------------------
 
     #listResource(binderName: string, items: unknown[], options: { next?: string | null } = {}): [number, unknown] {