@stamhoofd/backend 2.138.2 → 2.140.0

package/src/sql-filters/payment-settlement.test.ts

@@ -0,0 +1,68 @@
+import { compileToSQLFilter } from '@stamhoofd/sql';
+import { PaymentMethod, PaymentProvider, PaymentStatus, Settlement } from '@stamhoofd/structures';
+import { toBalanceItemFilter } from '@stamhoofd/structures/breakdown/breakdownFilters.js';
+import type { SettleablePayment } from '@stamhoofd/structures/PaymentSettlement.js';
+import { ACCOUNT_DEDUCTIONS_ID, FAILED_PAYMENT_ID, getPaymentSettlement, PENDING_PAYMENT_ID } from '@stamhoofd/structures/PaymentSettlement.js';
+import { balanceItemFilterCompilers } from './balance-items.js';
+import { paymentFilterCompilers } from './payments.js';
+
+describe('paymentSettlementFilterCompilers', () => {
+    const settlement = Settlement.create({
+        id: 'settlement-1',
+        reference: 'ST-2026-01',
+        settledAt: new Date(2026, 0, 15),
+        amount: 100_00,
+    });
+
+    /**
+     * At least one payment for every group getPaymentSettlement can hand out, so a group that gets a new
+     * field in its filter is covered here.
+     */
+    const payments: SettleablePayment[] = [
+        // Money that never arrived
+        { method: PaymentMethod.Bancontact, provider: PaymentProvider.Stripe, settlement: null, status: PaymentStatus.Pending },
+        { method: PaymentMethod.Bancontact, provider: PaymentProvider.Stripe, settlement: null, status: PaymentStatus.Failed },
+        // Paid out, and waiting to be paid out
+        { method: PaymentMethod.Bancontact, provider: PaymentProvider.Stripe, settlement, status: PaymentStatus.Succeeded },
+        { method: PaymentMethod.Bancontact, provider: PaymentProvider.Stripe, settlement: null, status: PaymentStatus.Succeeded },
+        // Online, but from a provider that tells us nothing about its payouts
+        { method: PaymentMethod.Payconiq, provider: PaymentProvider.Payconiq, settlement: null, status: PaymentStatus.Succeeded },
+        { method: PaymentMethod.CreditCard, provider: null, settlement: null, status: PaymentStatus.Succeeded },
+        // Never online
+        { method: PaymentMethod.Transfer, provider: null, settlement: null, status: PaymentStatus.Succeeded },
+        { method: PaymentMethod.PointOfSale, provider: null, settlement: null, status: PaymentStatus.Succeeded },
+        { method: PaymentMethod.AccountDeductions, provider: null, settlement: null, status: PaymentStatus.Succeeded },
+    ];
+
+    const groups = payments.map(payment => getPaymentSettlement(payment));
+
+    test('every payout group can be compiled against the payments table', async () => {
+        for (const group of groups) {
+            await expect(compileToSQLFilter(group.filter, paymentFilterCompilers)).resolves.toBeDefined();
+        }
+    });
+
+    test('every payout group survives being asked about the balance items it paid for', async () => {
+        // A balance item doesn't carry how it was paid, so the payout tab of a balance item breakdown
+        // selects the items through their payments. A field that only the payments table knows about
+        // would only break there, at runtime.
+        for (const group of groups) {
+            await expect(compileToSQLFilter(toBalanceItemFilter(group.filter), balanceItemFilterCompilers)).resolves.toBeDefined();
+        }
+    });
+
+    test('covers every kind of payout group', () => {
+        // Guards the fixtures above: a new kind of group has to be added here before it is covered
+        expect([...new Set(groups.map(group => group.id))].sort()).toEqual([
+            ACCOUNT_DEDUCTIONS_ID,
+            FAILED_PAYMENT_ID,
+            'no-payout-info-none',
+            'no-payout-info-' + PaymentProvider.Payconiq,
+            'not-settled',
+            // Every method that brings money in outside a provider shares one group
+            'offline',
+            PENDING_PAYMENT_ID,
+            'settlement-' + PaymentProvider.Stripe + '-' + settlement.reference + '-' + settlement.settledAt.getTime(),
+        ].sort());
+    });
+});

package/src/sql-filters/payment-settlement.ts

@@ -0,0 +1,43 @@
+import type { SQLFilterDefinitions } from '@stamhoofd/sql';
+import { baseSQLFilterCompilers, createColumnFilter, SQL, SQLValueType } from '@stamhoofd/sql';
+
+/**
+ * How a payment is selected by the payout it was part of (see PaymentSettlementGroup).
+ *
+ * Shared by the payments filters and by the balance items filters, which reach the same columns through
+ * the payments that paid for them, so both select exactly the same payments.
+ *
+ * All expressions are qualified with the payments table so they keep working in a subquery that joins
+ * payments (see balance-items.ts).
+ */
+export const paymentSettlementFilterCompilers: SQLFilterDefinitions = {
+    ...baseSQLFilterCompilers,
+    method: createColumnFilter({
+        expression: SQL.column('payments', 'method'),
+        type: SQLValueType.String,
+        nullable: false,
+    }),
+    provider: createColumnFilter({
+        expression: SQL.column('payments', 'provider'),
+        type: SQLValueType.String,
+        nullable: true,
+    }),
+    status: createColumnFilter({
+        expression: SQL.column('payments', 'status'),
+        type: SQLValueType.String,
+        nullable: false,
+    }),
+    settlement: {
+        ...baseSQLFilterCompilers,
+        reference: createColumnFilter({
+            expression: SQL.jsonExtract(SQL.column('payments', 'settlement'), '$.value.reference'),
+            type: SQLValueType.JSONString,
+            nullable: true,
+        }),
+        settledAt: createColumnFilter({
+            expression: SQL.jsonExtract(SQL.column('payments', 'settlement'), '$.value.settledAt'),
+            type: SQLValueType.JSONDate,
+            nullable: true,
+        }),
+    },
+};

package/src/sql-filters/payments.ts

@@ -1,41 +1,39 @@
 import { Payment } from '@stamhoofd/models';
 import type { SQLFilterDefinitions } from '@stamhoofd/sql';
 import { baseSQLFilterCompilers, createColumnFilter, createExistsFilter, createJoinedRelationFilter, SQL, SQLCast, SQLConcat, SQLJsonUnquote, SQLScalar, SQLValueType } from '@stamhoofd/sql';
+import type { StamhoofdFilter } from '@stamhoofd/structures';
+import { TransferSettings } from '@stamhoofd/structures';
 import { balanceItemPaymentsCompilers } from './balance-item-payments.js';
 import { organizationFilterCompilers } from './organizations.js';
+import { paymentSettlementFilterCompilers } from './payment-settlement.js';
 
 /**
  * Defines how to filter payments in the database from StamhoofdFilter objects
+ *
+ * All expressions are qualified with the payments table so they keep working when payments is joined
+ * into another query instead of being selected from (see balance-item-payments-root.ts).
  */
 export const paymentFilterCompilers: SQLFilterDefinitions = {
     ...baseSQLFilterCompilers,
+    // method, provider, status and settlement
+    ...paymentSettlementFilterCompilers,
     id: createColumnFilter({
-        expression: SQL.column('id'),
-        type: SQLValueType.String,
-        nullable: false,
-    }),
-    method: createColumnFilter({
-        expression: SQL.column(Payment.table, 'method'),
+        expression: SQL.column(Payment.table, 'id'),
         type: SQLValueType.String,
         nullable: false,
     }),
     type: createColumnFilter({
-        expression: SQL.column('type'),
-        type: SQLValueType.String,
-        nullable: false,
-    }),
-    status: createColumnFilter({
-        expression: SQL.column(Payment.table, 'status'),
+        expression: SQL.column(Payment.table, 'type'),
         type: SQLValueType.String,
         nullable: false,
     }),
     organizationId: createColumnFilter({
-        expression: SQL.column('organizationId'),
+        expression: SQL.column(Payment.table, 'organizationId'),
         type: SQLValueType.String,
         nullable: true,
     }),
     payingOrganizationId: createColumnFilter({
-        expression: SQL.column('payingOrganizationId'),
+        expression: SQL.column(Payment.table, 'payingOrganizationId'),
         type: SQLValueType.String,
         nullable: true,
     }),
@@ -44,22 +42,22 @@ export const paymentFilterCompilers: SQLFilterDefinitions = {
         organizationFilterCompilers,
     ),
     invoiceId: createColumnFilter({
-        expression: SQL.column('invoiceId'),
+        expression: SQL.column(Payment.table, 'invoiceId'),
         type: SQLValueType.String,
         nullable: true,
     }),
     createdAt: createColumnFilter({
-        expression: SQL.column('createdAt'),
+        expression: SQL.column(Payment.table, 'createdAt'),
         type: SQLValueType.Datetime,
         nullable: false,
     }),
     updatedAt: createColumnFilter({
-        expression: SQL.column('updatedAt'),
+        expression: SQL.column(Payment.table, 'updatedAt'),
         type: SQLValueType.Datetime,
         nullable: false,
     }),
     paidAt: createColumnFilter({
-        expression: SQL.column('paidAt'),
+        expression: SQL.column(Payment.table, 'paidAt'),
         type: SQLValueType.Datetime,
         nullable: true,
     }),
@@ -68,44 +66,73 @@ export const paymentFilterCompilers: SQLFilterDefinitions = {
         type: SQLValueType.Number,
         nullable: false,
     }),
-    provider: createColumnFilter({
-        expression: SQL.column('provider'),
+
+    stripeAccountId: createColumnFilter({
+        expression: SQL.column(Payment.table, 'stripeAccountId'),
         type: SQLValueType.String,
         nullable: true,
     }),
+
+    /**
+     * What a payment rounded away, which belongs to the payment as a whole instead of to one of the
+     * things it paid for (see PaymentBreakdownBuilder.addRounding).
+     */
+    roundingAmount: createColumnFilter({
+        expression: SQL.column(Payment.table, 'roundingAmount'),
+        type: SQLValueType.Number,
+        nullable: false,
+    }),
+
+    /**
+     * The account a transfer was made to. Used to narrow a breakdown down to the money that arrived on
+     * one account (see PaymentBreakdown).
+     */
+    transferSettings: {
+        ...baseSQLFilterCompilers,
+        iban: createColumnFilter({
+            expression: SQL.jsonExtract(SQL.column(Payment.table, 'transferSettings'), '$.value.iban'),
+            type: SQLValueType.JSONString,
+            nullable: true,
+        }),
+        creditor: createColumnFilter({
+            expression: SQL.jsonExtract(SQL.column(Payment.table, 'transferSettings'), '$.value.creditor'),
+            type: SQLValueType.JSONString,
+            nullable: true,
+        }),
+    },
     transferDescription: createColumnFilter({
         expression: SQL.column(Payment.table, 'transferDescription'),
         type: SQLValueType.String,
         nullable: true,
     }),
     hasInvoice: createColumnFilter({
-        expression: SQL.isNull(SQL.column('invoiceId')),
+        expression: SQL.isNull(SQL.column(Payment.table, 'invoiceId')),
         type: SQLValueType.Boolean,
         nullable: false,
     }),
     customer: {
         ...baseSQLFilterCompilers,
         email: createColumnFilter({
-            expression: SQL.jsonExtract(SQL.column('customer'), '$.value.email'),
+            expression: SQL.jsonExtract(SQL.column(Payment.table, 'customer'), '$.value.email'),
             type: SQLValueType.JSONString,
             nullable: true,
         }),
         firstName: createColumnFilter({
-            expression: SQL.jsonExtract(SQL.column('customer'), '$.value.firstName'),
+            expression: SQL.jsonExtract(SQL.column(Payment.table, 'customer'), '$.value.firstName'),
             type: SQLValueType.JSONString,
             nullable: true,
         }),
         lastName: createColumnFilter({
-            expression: SQL.jsonExtract(SQL.column('customer'), '$.value.lastName'),
+            expression: SQL.jsonExtract(SQL.column(Payment.table, 'customer'), '$.value.lastName'),
             type: SQLValueType.JSONString,
             nullable: true,
         }),
         name: createColumnFilter({
             expression: new SQLCast(
                 new SQLConcat(
-                    new SQLJsonUnquote(SQL.jsonExtract(SQL.column('customer'), '$.value.firstName')),
+                    new SQLJsonUnquote(SQL.jsonExtract(SQL.column(Payment.table, 'customer'), '$.value.firstName')),
                     new SQLScalar(' '),
-                    new SQLJsonUnquote(SQL.jsonExtract(SQL.column('customer'), '$.value.lastName')),
+                    new SQLJsonUnquote(SQL.jsonExtract(SQL.column(Payment.table, 'customer'), '$.value.lastName')),
                 ),
                 'CHAR',
             ),
@@ -115,22 +142,22 @@ export const paymentFilterCompilers: SQLFilterDefinitions = {
         company: {
             ...baseSQLFilterCompilers,
             name: createColumnFilter({
-                expression: SQL.jsonExtract(SQL.column('customer'), '$.value.company.name'),
+                expression: SQL.jsonExtract(SQL.column(Payment.table, 'customer'), '$.value.company.name'),
                 type: SQLValueType.JSONString,
                 nullable: true,
             }),
             VATNumber: createColumnFilter({
-                expression: SQL.jsonExtract(SQL.column('customer'), '$.value.company.VATNumber'),
+                expression: SQL.jsonExtract(SQL.column(Payment.table, 'customer'), '$.value.company.VATNumber'),
                 type: SQLValueType.JSONString,
                 nullable: true,
             }),
             companyNumber: createColumnFilter({
-                expression: SQL.jsonExtract(SQL.column('customer'), '$.value.company.companyNumber'),
+                expression: SQL.jsonExtract(SQL.column(Payment.table, 'customer'), '$.value.company.companyNumber'),
                 type: SQLValueType.JSONString,
                 nullable: true,
             }),
             administrationEmail: createColumnFilter({
-                expression: SQL.jsonExtract(SQL.column('customer'), '$.value.company.administrationEmail'),
+                expression: SQL.jsonExtract(SQL.column(Payment.table, 'customer'), '$.value.company.administrationEmail'),
                 type: SQLValueType.JSONString,
                 nullable: true,
             }),
@@ -148,9 +175,44 @@ export const paymentFilterCompilers: SQLFilterDefinitions = {
                     SQL.column('balance_item_payments', 'balanceItemId'),
                 ),
             ).where(
-                SQL.column('paymentId'),
+                SQL.column('balance_item_payments', 'paymentId'),
                 SQL.column('payments', 'id'),
             ),
         balanceItemPaymentsCompilers,
     ),
 };
+
+/**
+ * What a search term typed in a list of payments selects, as a filter on the payments table.
+ *
+ * Shared by everything that lists or exports payments, so a search always selects the same payments no
+ * matter which of those it went through.
+ */
+export function getPaymentSearchFilter(search: string): StamhoofdFilter {
+    const transferDescription = search.replaceAll('+', '').replaceAll('/', '');
+
+    if (transferDescription.length === '562100153542'.length && !isNaN(parseInt(transferDescription))) {
+        // A structured transfer reference is only ever meant to find that one payment
+        return {
+            transferDescription: TransferSettings.structureOGM(transferDescription),
+        };
+    }
+
+    if (search.includes('@')) {
+        return {
+            $or: [
+                { customer: { email: { $contains: search } } },
+                { customer: { company: { administrationEmail: { $contains: search } } } },
+            ],
+        };
+    }
+
+    return {
+        $or: [
+            { customer: { name: { $contains: search } } },
+            { customer: { company: { name: { $contains: search } } } },
+            { balanceItemPayments: { $elemMatch: { balanceItem: { description: { $contains: search } } } } },
+            { transferDescription: { $contains: search } },
+        ],
+    };
+}

package/src/sql-sorters/balance-item-payments.ts

@@ -0,0 +1,32 @@
+import type { BalanceItemPayment } from '@stamhoofd/models';
+import type { SQLOrderByDirection, SQLSortDefinitions } from '@stamhoofd/sql';
+import { SQL, SQLOrderBy } from '@stamhoofd/sql';
+import { Formatter } from '@stamhoofd/utility';
+
+export const balanceItemPaymentSorters: SQLSortDefinitions<BalanceItemPayment> = {
+    // WARNING! TEST NEW SORTERS THOROUGHLY! See balanceItemSorters for why sorting on anything that is
+    // not 1:1 with a column breaks pagination.
+
+    id: {
+        getValue(a) {
+            return a.id;
+        },
+        toSQL: (direction: SQLOrderByDirection): SQLOrderBy => {
+            return new SQLOrderBy({
+                column: SQL.column('balance_item_payments', 'id'),
+                direction,
+            });
+        },
+    },
+    createdAt: {
+        getValue(a) {
+            return Formatter.dateTimeIso(a.createdAt, 'UTC');
+        },
+        toSQL: (direction: SQLOrderByDirection): SQLOrderBy => {
+            return new SQLOrderBy({
+                column: SQL.column('balance_item_payments', 'createdAt'),
+                direction,
+            });
+        },
+    },
+};