@stamhoofd/backend 2.138.2 → 2.139.0

package/src/helpers/breakdownRelations.ts

@@ -0,0 +1,48 @@
+import { BalanceItem, Order } from '@stamhoofd/models';
+import type { OrderData } from '@stamhoofd/structures';
+import { BalanceItemPaymentWithPrivatePayment, PrivatePayment } from '@stamhoofd/structures';
+import { Formatter } from '@stamhoofd/utility';
+
+/**
+ * A webshop order is charged as one balance item, so the articles that were ordered are only visible
+ * inside the order itself.
+ */
+export async function loadOrdersForBreakdown(orderIds: (string | null)[]): Promise<Map<string, OrderData>> {
+    const ids = Formatter.uniqueArray(orderIds.flatMap(id => id ? [id] : []));
+
+    if (ids.length === 0) {
+        return new Map();
+    }
+
+    const orders = await Order.getByIDs(...ids);
+    return new Map(orders.map(order => [order.id, order.data]));
+}
+
+/**
+ * The payments that paid for these balance items, per balance item id. A balance item doesn't know how
+ * it was paid, so the payouts it was part of are only visible through its payments (see
+ * PaymentSettlementGroup).
+ */
+export async function loadPaymentsForBreakdown(balanceItemIds: string[]): Promise<Map<string, BalanceItemPaymentWithPrivatePayment[]>> {
+    if (balanceItemIds.length === 0) {
+        return new Map();
+    }
+
+    const { payments, balanceItemPayments } = await BalanceItem.loadPayments(balanceItemIds.map(id => ({ id })));
+    const paymentsById = new Map(payments.map(payment => [payment.id, PrivatePayment.create(payment)]));
+    const result = new Map<string, BalanceItemPaymentWithPrivatePayment[]>();
+
+    for (const balanceItemPayment of balanceItemPayments) {
+        const payment = paymentsById.get(balanceItemPayment.paymentId);
+
+        if (!payment) {
+            continue;
+        }
+
+        const list = result.get(balanceItemPayment.balanceItemId) ?? [];
+        list.push(BalanceItemPaymentWithPrivatePayment.create({ ...balanceItemPayment, payment }));
+        result.set(balanceItemPayment.balanceItemId, list);
+    }
+
+    return result;
+}

package/src/helpers/getNextPageRequest.ts

@@ -0,0 +1,24 @@
+import type { SQLSortDefinitions } from '@stamhoofd/sql';
+import { getSortFilter, LimitedFilteredRequest } from '@stamhoofd/structures';
+
+/**
+ * The request that reads the page after this one, or undefined when this was the last page.
+ *
+ * Pages are walked with a cursor built from the last object of the page instead of an offset, so a page
+ * is never skipped or read twice while the list changes underneath. A cursor that doesn't move past the
+ * one it came from would read the same page forever, so it ends the list instead.
+ */
+export function getNextPageRequest<T>(objects: T[], requestQuery: LimitedFilteredRequest, sorters: SQLSortDefinitions<T>): LimitedFilteredRequest | undefined {
+    if (objects.length < requestQuery.limit) {
+        return undefined;
+    }
+
+    const nextFilter = getSortFilter(objects[objects.length - 1], sorters, requestQuery.sort);
+
+    if (JSON.stringify(nextFilter) === JSON.stringify(requestQuery.pageFilter)) {
+        console.error('Found infinite loading loop for', requestQuery);
+        return undefined;
+    }
+
+    return new LimitedFilteredRequest({ ...requestQuery, pageFilter: nextFilter });
+}

package/src/helpers/streamForBreakdown.test.ts

@@ -0,0 +1,107 @@
+import type { StamhoofdFilter } from '@stamhoofd/structures';
+import { LimitedFilteredRequest } from '@stamhoofd/structures';
+import { v4 as uuidv4 } from 'uuid';
+import { MAX_BREAKDOWN_OBJECTS, streamForBreakdown } from './streamForBreakdown.js';
+
+describe('streamForBreakdown', () => {
+    /**
+     * Hands out pages of numbers, the way an endpoint hands out pages of objects: where to continue is
+     * carried by the request itself, so a page is only skipped or read twice when the caller loses it.
+     */
+    const createFetcher = (totalObjects: number) => {
+        const requests: LimitedFilteredRequest[] = [];
+
+        const fetch = (request: LimitedFilteredRequest) => {
+            requests.push(request);
+
+            const start = (request.pageFilter as { id: { $gt: number } } | null)?.id.$gt ?? 0;
+            const results = Array.from({ length: Math.min(request.limit, Math.max(0, totalObjects - start)) }, (_, index) => start + index);
+            const end = start + results.length;
+
+            return Promise.resolve({
+                results,
+                next: end < totalObjects
+                    ? new LimitedFilteredRequest({
+                            filter: request.filter,
+                            search: request.search,
+                            sort: request.sort,
+                            limit: request.limit,
+                            pageFilter: { id: { $gt: end } },
+                        })
+                    : undefined,
+            });
+        };
+
+        return { fetch, requests };
+    };
+
+    const stream = async (totalObjects: number, selection: { filter?: StamhoofdFilter; search?: string | null } = {}) => {
+        const { fetch, requests } = createFetcher(totalObjects);
+        const handled: number[] = [];
+        const countRequests: { filter: StamhoofdFilter; search: string | null }[] = [];
+
+        await streamForBreakdown<number>({
+            userId: uuidv4(),
+            filter: selection.filter ?? null,
+            search: selection.search ?? null,
+            count: (request) => {
+                countRequests.push({ filter: request.filter, search: request.search });
+                return Promise.resolve(totalObjects);
+            },
+            fetch,
+            handle: (results) => {
+                handled.push(...results);
+            },
+        });
+
+        return { handled, requests, countRequests };
+    };
+
+    test('every object is handed over once, page by page', async () => {
+        const { handled, requests } = await stream(250);
+
+        // No object is read twice or skipped, whatever the pages look like
+        expect(handled).toEqual(Array.from({ length: 250 }, (_, index) => index));
+
+        // Read in pages, sorted so the pages line up
+        expect(requests.length).toBeGreaterThan(1);
+        expect(requests[0].sort.map(s => s.key)).toEqual(['id']);
+    });
+
+    test('the selection is read exactly as it was asked for', async () => {
+        const filter = { status: 'Succeeded' };
+        const { requests, countRequests } = await stream(250, { filter, search: 'Peeters' });
+
+        // Every page reads the same selection, so a page never holds objects the breakdown did not count
+        for (const request of requests) {
+            expect(request.filter).toEqual(filter);
+            expect(request.search).toBe('Peeters');
+        }
+
+        expect(countRequests).toEqual([{ filter, search: 'Peeters' }]);
+    });
+
+    test('an empty selection hands over nothing', async () => {
+        const { handled } = await stream(0);
+        expect(handled).toHaveLength(0);
+    });
+
+    test('a selection that is too large to break down asks the user to narrow it down', async () => {
+        await expect(stream(MAX_BREAKDOWN_OBJECTS + 1)).rejects.toThrow('Too many objects to break down');
+    });
+
+    test('a selection that is too large is refused before it is read', async () => {
+        const { fetch, requests } = createFetcher(MAX_BREAKDOWN_OBJECTS + 1);
+
+        await expect(streamForBreakdown<number>({
+            userId: uuidv4(),
+            filter: null,
+            search: null,
+            count: () => Promise.resolve(MAX_BREAKDOWN_OBJECTS + 1),
+            fetch,
+            handle: () => {},
+        })).rejects.toThrow('Too many objects to break down');
+
+        expect(requests).toHaveLength(0);
+    });
+});

package/src/helpers/streamForBreakdown.ts

@@ -0,0 +1,104 @@
+import { SimpleError } from '@simonbackx/simple-errors';
+import { RateLimiter } from '@stamhoofd/models';
+import { QueueHandler } from '@stamhoofd/queues';
+import type { CountFilteredRequest, IPaginatedResponse, StamhoofdFilter } from '@stamhoofd/structures';
+import { LimitedFilteredRequest, SortItemDirection } from '@stamhoofd/structures';
+import { Formatter } from '@stamhoofd/utility';
+import { fetchToAsyncIterator } from './fetchToAsyncIterator.js';
+
+/**
+ * A breakdown groups the objects one by one instead of in SQL, so the grouping rules are the same ones
+ * the rest of the app uses. That means every object has to be read, which is the same work an Excel
+ * export does.
+ *
+ * They are read page by page and added up right away, so they are never all in memory at once. Above
+ * this many objects a breakdown takes too long to wait for, so we ask the user to narrow down instead.
+ */
+export const MAX_BREAKDOWN_OBJECTS = 10000;
+
+const PAGE_SIZE = 100;
+
+/**
+ * Breakdowns are read-only, but they read a lot. They are protected the same way exports are: a limit
+ * per user, one at a time per user and a maximum number running at the same time.
+ */
+export const breakdownLimiter = new RateLimiter({
+    limits: [
+        {
+            limit: 100,
+            duration: 5 * 60 * 1000,
+        },
+        {
+            limit: 1000,
+            duration: 60 * 1000 * 60 * 24,
+        },
+    ],
+});
+
+/**
+ * Reads every object matching the filter, page by page, and hands each page over to be added up.
+ */
+export async function streamForBreakdown<T>(options: {
+    userId: string;
+    filter: StamhoofdFilter;
+    search: string | null;
+    count: (request: CountFilteredRequest) => Promise<number>;
+    fetch: (request: LimitedFilteredRequest) => Promise<IPaginatedResponse<T[], LimitedFilteredRequest>>;
+    handle: (results: T[]) => Promise<void> | void;
+}): Promise<void> {
+    // Clicking through the tabs of a breakdown would otherwise stack up requests that each block a
+    // connection until the one before it is done
+    if (QueueHandler.isRunning('breakdown-' + options.userId)) {
+        throw new SimpleError({
+            code: 'breakdown_pending',
+            message: 'A breakdown is already running for this user',
+            human: $t('Er worden al statistieken berekend, probeer het zo opnieuw.'),
+            statusCode: 429,
+        });
+    }
+
+    breakdownLimiter.track(options.userId, 1);
+
+    // One breakdown per user at a time, and never more than 5 for all users together
+    await QueueHandler.schedule('breakdown-' + options.userId, async () => {
+        await QueueHandler.schedule('breakdown', async () => {
+            const request = new LimitedFilteredRequest({
+                filter: options.filter,
+                search: options.search,
+                limit: PAGE_SIZE,
+                sort: [
+                    { key: 'id', order: SortItemDirection.ASC },
+                ],
+            });
+
+            // Asked up front so a selection that is too big costs one query instead of reading it all
+            assertBreakdownSize(await options.count(request));
+
+            let count = 0;
+
+            for await (const results of fetchToAsyncIterator(request, { fetch: options.fetch })) {
+                count += results.length;
+
+                // The selection can still have grown since it was counted
+                assertBreakdownSize(count);
+
+                await options.handle(results);
+            }
+        }, 5);
+    });
+}
+
+function assertBreakdownSize(count: number) {
+    if (count <= MAX_BREAKDOWN_OBJECTS) {
+        return;
+    }
+
+    throw new SimpleError({
+        code: 'too_many_objects',
+        message: 'Too many objects to break down',
+        human: $t('Deze selectie bevat meer dan {limit} items, dat zijn er te veel om statistieken van te maken. Kies een kortere periode of verfijn je selectie.', {
+            limit: Formatter.integer(MAX_BREAKDOWN_OBJECTS),
+        }),
+        statusCode: 400,
+    });
+}

package/src/services/PasswordForgotService.ts

@@ -1,7 +1,9 @@
 import type { I18n } from '@stamhoofd/backend-i18n';
 import type { Organization } from '@stamhoofd/models';
 import { PasswordToken, Platform, User } from '@stamhoofd/models';
-import { getAppHost } from '@stamhoofd/structures';
+import { EmailTemplateType, getAppHost, Recipient, Replacement } from '@stamhoofd/structures';
+
+import { sendEmailTemplate } from '../helpers/EmailBuilder.js';
 
 /**
  * Builds the password recovery links. Which app the link points to depends on whether the user is an
@@ -17,6 +19,34 @@ export class PasswordForgotService {
         return await this.getPasswordRecoveryUrlForToken(token, organization, i18n, user);
     }
 
+    /**
+     * Create a new password token and email the recovery link to the user. Always sent to the
+     * stored address, never to whatever the request asked for.
+     */
+    static async sendPasswordRecoveryEmail(user: User, organization: Organization | null, i18n: I18n) {
+        const recoveryUrl = await this.getPasswordRecoveryUrl(user, organization, i18n);
+
+        await sendEmailTemplate(organization, {
+            recipients: [
+                Recipient.create({
+                    firstName: user.firstName,
+                    lastName: user.lastName,
+                    email: user.email,
+                    replacements: [
+                        Replacement.create({
+                            token: 'resetUrl',
+                            value: recoveryUrl,
+                        }),
+                    ],
+                }),
+            ],
+            template: {
+                type: EmailTemplateType.ForgotPassword,
+            },
+            type: 'transactional',
+        });
+    }
+
     /**
      * Build the recovery url for an already created password token.
      * Pass the user to avoid an extra query when it is already loaded.

package/src/services/PaymentService.ts

@@ -1349,7 +1349,7 @@ export class PaymentService {
                 const balanceItemPayment = new BalanceItemPayment();
                 balanceItemPayment.balanceItemId = balanceItem.id;
                 balanceItemPayment.paymentId = payment.id;
-                balanceItemPayment.organizationId = organization.id;
+                balanceItemPayment.organizationId = payment.organizationId;
                 balanceItemPayment.price = price;
 
                 await balanceItemPayment.save();

package/src/services/SSOService.ts

@@ -707,7 +707,7 @@ export class SSOServiceWithSession {
                     // enrollment endpoints check this themselves.
                     redirectUri.searchParams.set('oid_mfa_passkeys', user.canUsePasskeys() ? '1' : '0');
                     redirectUri.searchParams.set('s', session.spaState);
-                } else {
+                } else if (requirement.type === 'none') {
                     const token = await Token.createExpiredToken(user);
 
                     if (!token) {
@@ -722,6 +722,19 @@ export class SSOServiceWithSession {
                     const st = new TokenStruct(token);
                     redirectUri.searchParams.set('oid_rt', st.refreshToken);
                     redirectUri.searchParams.set('s', session.spaState);
+                } else if (requirement.type === 'confirm-email') {
+                    // Only password logins reach this: an SSO login is not the credential
+                    // that has to be confirmed. Fail closed rather than fall through to a
+                    // session, which would make this redirect an enrollment bypass.
+                    throw new SimpleError({
+                        code: 'error',
+                        message: 'Email confirmation is not supported for SSO logins',
+                        statusCode: 500,
+                    });
+                } else {
+                    // Compile error when a requirement is added without handling it here.
+                    const unsupported: never = requirement;
+                    throw new Error('Unsupported second factor requirement: ' + JSON.stringify(unsupported));
                 }
             } else if (this.session.reauthenticateAccessToken) {
                 // The provider confirmed the identity of the user that is already signed in,

package/src/sql-filters/balance-item-payments-root.ts

@@ -0,0 +1,48 @@
+import type { SQLFilterDefinitions } from '@stamhoofd/sql';
+import { baseSQLFilterCompilers, createColumnFilter, SQL, SQLValueType } from '@stamhoofd/sql';
+import { balanceItemPaymentsCompilers } from './balance-item-payments.js';
+import { paymentFilterCompilers } from './payments.js';
+
+/**
+ * How a balance item payment is selected when it is queried directly, instead of through the payment or
+ * the balance item it belongs to.
+ *
+ * This is the level at which money that is spread over several payments, or that paid for several
+ * things at once, can be selected exactly: one row is one payment paying one part of one balance item.
+ *
+ * Lives in its own file because it reaches both parents, while balance-item-payments.ts is used inside
+ * a subquery that only joins the balance items.
+ */
+export const balanceItemPaymentRootFilterCompilers: SQLFilterDefinitions = {
+    ...baseSQLFilterCompilers,
+    // id, price and the balance item filters
+    ...balanceItemPaymentsCompilers,
+
+    organizationId: createColumnFilter({
+        expression: SQL.column('balance_item_payments', 'organizationId'),
+        type: SQLValueType.String,
+        nullable: false,
+    }),
+
+    paymentId: createColumnFilter({
+        expression: SQL.column('balance_item_payments', 'paymentId'),
+        type: SQLValueType.String,
+        nullable: false,
+    }),
+
+    balanceItemId: createColumnFilter({
+        expression: SQL.column('balance_item_payments', 'balanceItemId'),
+        type: SQLValueType.String,
+        nullable: false,
+    }),
+
+    createdAt: createColumnFilter({
+        expression: SQL.column('balance_item_payments', 'createdAt'),
+        type: SQLValueType.Datetime,
+        nullable: false,
+    }),
+
+    // The same compilers the payments use, which are qualified with the payments table so they keep
+    // working here: this query joins it instead of selecting from it
+    payment: paymentFilterCompilers,
+};

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

@@ -1,6 +1,7 @@
 import type { SQLFilterDefinitions } from '@stamhoofd/sql';
 import { baseSQLFilterCompilers, createColumnFilter, createExistsFilter, SQL, SQLValueType } from '@stamhoofd/sql';
 import { BalanceItemRelationType } from '@stamhoofd/structures';
+import { paymentSettlementFilterCompilers } from './payment-settlement.js';
 
 /**
  * Filters on the relations of a balance item (registration group, webshop order and membership type).
@@ -52,6 +53,29 @@ export const balanceItemRelationFilterCompilers: SQLFilterDefinitions = {
         type: SQLValueType.JSONString,
         nullable: true,
     }),
+
+    /**
+     * Filter on the id of any relation, e.g. { relations: { Group: { id: '...' } } }.
+     *
+     * Used to narrow down to one category of a breakdown (see PaymentBreakdown), so every kind of
+     * metadata a balance item carries is filterable without a dedicated compiler per relation.
+     */
+    relations: {
+        ...baseSQLFilterCompilers,
+        ...Object.fromEntries(
+            Object.values(BalanceItemRelationType).map(relationType => [
+                relationType,
+                {
+                    ...baseSQLFilterCompilers,
+                    id: createColumnFilter({
+                        expression: SQL.jsonExtract(SQL.column('balance_items', 'relations'), `$.value.${relationType}.id`),
+                        type: SQLValueType.JSONString,
+                        nullable: true,
+                    }),
+                },
+            ]),
+        ),
+    },
 };
 
 /**
@@ -113,4 +137,35 @@ export const balanceItemFilterCompilers: SQLFilterDefinitions = {
         type: SQLValueType.Number,
         nullable: false,
     }),
+
+    /**
+     * The payments that paid (a part of) this balance item, e.g.
+     * `{ payments: { $elemMatch: { payment: { settlement: { reference: '...' } } } } }`.
+     *
+     * Used to narrow a breakdown down to the balance items that were part of one payout (see
+     * PaymentSettlementGroup): a balance item doesn't know how it was paid, its payments do.
+     */
+    payments: createExistsFilter(
+        SQL.select()
+            .from(SQL.table('balance_item_payments'))
+            .join(
+                SQL.join(SQL.table('payments')).where(
+                    SQL.column('payments', 'id'),
+                    SQL.column('balance_item_payments', 'paymentId'),
+                ),
+            )
+            .where(
+                SQL.column('balance_item_payments', 'balanceItemId'),
+                SQL.column('balance_items', 'id'),
+            ),
+        {
+            ...baseSQLFilterCompilers,
+            price: createColumnFilter({
+                expression: SQL.column('balance_item_payments', 'price'),
+                type: SQLValueType.Number,
+                nullable: false,
+            }),
+            payment: paymentSettlementFilterCompilers,
+        },
+    ),
 };

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,
+        }),
+    },
+};