@stamhoofd/backend 2.139.0 → 2.141.0

package/tests/helpers/MollieMocker.ts

@@ -53,6 +53,13 @@ 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;
@@ -61,6 +68,10 @@ 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 */
@@ -94,6 +105,12 @@ export class MollieMocker {
     refunds: MollieMockRefund[] = [];
     settlements: MollieMockSettlement[] = [];
 
+    /**
+     * Cap the settlements list page size below the requested limit, to exercise pagination
+     * without creating hundreds of settlements.
+     */
+    settlementsPageSize: number | null = null;
+
     #forceFailure = false;
 
     reset() {
@@ -103,6 +120,7 @@ export class MollieMocker {
         this.chargebacks = [];
         this.refunds = [];
         this.settlements = [];
+        this.settlementsPageSize = null;
         this.#forceFailure = false;
     }
 
@@ -224,10 +242,10 @@ export class MollieMocker {
             return this.#listResource('chargebacks', this.chargebacks.map(c => this.#chargebackResource(c)));
         }
 
-        // settlements + nested payments/refunds (drives the settlements cron)
+        // settlements + nested payments/refunds (drives the settlements sync)
         if (parts[0] === 'settlements' && method === 'GET') {
             if (parts.length === 1) {
-                return this.#listResource('settlements', this.settlements.map(s => this.#settlementResource(s)));
+                return this.#listSettlements(uri);
             }
             const settlement = this.settlements.find(s => s.id === parts[1]);
             if (settlement && parts.length === 3 && parts[2] === 'payments') {
@@ -554,9 +572,9 @@ export class MollieMocker {
 
     /**
      * Register a settled (paid out) settlement that groups the given payments and refunds.
-     * Used to drive the settlements cron (CheckSettlements).
+     * Used to drive the MollieSettlementSync walk.
      */
-    createSettlement(options: { payments?: MollieMockPayment[]; refunds?: MollieMockRefund[]; chargebacks?: MollieMockChargeback[]; value?: string; settledAt?: Date } = {}): MollieMockSettlement {
+    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 {
         const settlement: MollieMockSettlement = {
             id: this.createId('stl'),
             reference: '1234567.' + (this.settlements.length + 1).toString().padStart(4, '0') + '.01',
@@ -564,6 +582,8 @@ 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),
@@ -572,6 +592,42 @@ export class MollieMocker {
         return settlement;
     }
 
+    /**
+     * Mollie lists settlements newest-first, with the open settlement (settledAt null) on top;
+     * the sync relies on this to stop at the first settlement before its window. Pagination works
+     * like Mollie's: `from` is the id of the first settlement of the page, and the `next` link
+     * points at the first settlement of the following page.
+     */
+    #listSettlements(uri: string): [number, unknown] {
+        const query = new URLSearchParams(uri.split('?')[1] ?? '');
+
+        const sorted = this.settlements.slice().sort((a, b) => {
+            if (a.settledAt === null || b.settledAt === null) {
+                if (a.settledAt === b.settledAt) {
+                    return 0;
+                }
+                return a.settledAt === null ? -1 : 1;
+            }
+            return new Date(b.settledAt).getTime() - new Date(a.settledAt).getTime();
+        });
+
+        const requestedLimit = parseInt(query.get('limit') ?? '250');
+        const limit = Math.min(requestedLimit, this.settlementsPageSize ?? requestedLimit);
+
+        const from = query.get('from');
+        const startIndex = from ? sorted.findIndex(s => s.id === from) : 0;
+        if (startIndex === -1) {
+            return [404, { status: 404, title: 'Not Found', detail: 'No settlement exists with token ' + from }];
+        }
+
+        const page = sorted.slice(startIndex, startIndex + limit);
+        const nextItem = sorted[startIndex + limit];
+
+        return this.#listResource('settlements', page.map(s => this.#settlementResource(s)), {
+            next: nextItem ? 'https://api.mollie.com/v2/settlements?limit=' + requestedLimit + '&from=' + nextItem.id : null,
+        });
+    }
+
     #settlementResource(settlement: MollieMockSettlement) {
         return {
             resource: 'settlement',
@@ -581,20 +637,22 @@ 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' } },
         };
     }
 
     // ---- List helper ------------------------------------------------------
 
-    #listResource(binderName: string, items: unknown[]): [number, unknown] {
+    #listResource(binderName: string, items: unknown[], options: { next?: string | null } = {}): [number, unknown] {
         return [200, {
             count: items.length,
             _embedded: { [binderName]: items },
             _links: {
                 self: { href: 'https://api.mollie.com/v2/' + binderName, type: 'application/hal+json' },
                 documentation: { href: 'https://docs.mollie.com', type: 'text/html' },
-                next: null,
+                next: options.next ? { href: options.next, type: 'application/hal+json' } : null,
                 previous: null,
             },
         }];

package/tests/helpers/StripeMocker.ts

@@ -10,14 +10,27 @@ import { testServer } from './TestServer.js';
 import { resetNock } from './resetNock.js';
 
 export type PaymentIntent = { id: string; return_url?: string };
+
+/**
+ * Loose Stripe API object: the mocker serves back exactly what a test built, so only the id is
+ * mandatory.
+ */
+export type StripeObject = { id: string } & Record<string, any>;
+
 export class StripeMocker {
     paymentIntents: PaymentIntent[] = [];
-    charges: { id: string }[] = [];
+    charges: StripeObject[] = [];
+    payouts: StripeObject[] = [];
+    balanceTransactions: StripeObject[] = [];
+    checkoutSessions: StripeObject[] = [];
     #forceFailure = false;
 
     reset() {
         this.paymentIntents = [];
         this.charges = [];
+        this.payouts = [];
+        this.balanceTransactions = [];
+        this.checkoutSessions = [];
         this.#forceFailure = false;
     }
 
@@ -30,25 +43,15 @@ export class StripeMocker {
             throw new Error('Invalid STRIPE_SECRET_KEY. Even in test mode it should start with sk_test_');
         }
 
+        const mocker = this;
         nock('https://api.stripe.com')
             .persist()
             .get(/v1\/.*/)
-            .reply((uri, body) => {
-                const [match, resource, id] = uri.match(/\/?v1\/(\w+)(?:\/(\w+)){0,2}/) || [null];
-
-                if (!match) {
-                    return [500];
-                }
-
-                if (resource === 'payment_intents') {
-                    return this.#getPaymentIntent(id);
-                }
-
-                if (resource === 'charges') {
-                    return this.#getCharge(id);
-                }
-
-                return [500];
+            // A regular function: nock exposes the intercepted request (and its Stripe-Account
+            // header) on `this`
+            .reply(function (uri) {
+                const stripeAccount = (this.req.headers['stripe-account'] as string | undefined) ?? null;
+                return mocker.#handleGet(uri, stripeAccount);
             });
 
         nock('https://api.stripe.com')
@@ -84,12 +87,201 @@ export class StripeMocker {
     clear() {
         this.paymentIntents = [];
         this.charges = [];
+        this.payouts = [];
+        this.balanceTransactions = [];
+        this.checkoutSessions = [];
     }
 
     createId(prefix: string) {
         return prefix + '_' + uuidv4().replaceAll('-', '');
     }
 
+    #handleGet(uri: string, stripeAccount: string | null) {
+        const [match, resource, id] = uri.match(/\/?v1\/(\w+)(?:\/(\w+)){0,2}/) || [null];
+
+        if (!match) {
+            return [500];
+        }
+
+        const query = this.decodeBody(uri.split('?')[1] ?? '') as Record<string, any>;
+
+        if (resource === 'payment_intents') {
+            return this.#getPaymentIntent(id);
+        }
+
+        if (resource === 'charges') {
+            return this.#getCharge(id);
+        }
+
+        if (resource === 'payouts') {
+            return this.#listPayouts(id, query, stripeAccount);
+        }
+
+        if (resource === 'balance_transactions') {
+            return this.#listBalanceTransactions(query, stripeAccount);
+        }
+
+        if (resource === 'checkout' && id === 'sessions') {
+            return this.#listCheckoutSessions(query);
+        }
+
+        return [500];
+    }
+
+    /**
+     * Pages like the real API does, so the SDK's auto-pagination is actually exercised: a payout
+     * with more transactions than one page is the normal case in production.
+     */
+    #list(data: StripeObject[], url: string, query: Record<string, any> = {}) {
+        let page = data;
+
+        if (query.starting_after) {
+            const index = page.findIndex(item => item.id === query.starting_after);
+            page = index === -1 ? [] : page.slice(index + 1);
+        }
+
+        const limit = query.limit ? parseInt(String(query.limit)) : 10;
+        const hasMore = page.length > limit;
+
+        return [200, { object: 'list', data: page.slice(0, limit), has_more: hasMore, url }];
+    }
+
+    #listPayouts(id: string | undefined, query: Record<string, any>, stripeAccount: string | null) {
+        let data = this.payouts.filter(p => (p.stripeAccount ?? null) === stripeAccount);
+
+        if (id) {
+            const payout = data.find(p => p.id === id);
+            return payout ? [200, payout] : [404];
+        }
+
+        if (query.status) {
+            data = data.filter(p => p.status === query.status);
+        }
+        if (query.arrival_date?.gte !== undefined) {
+            data = data.filter(p => p.arrival_date >= query.arrival_date.gte);
+        }
+        if (query.arrival_date?.lte !== undefined) {
+            data = data.filter(p => p.arrival_date <= query.arrival_date.lte);
+        }
+        return this.#list(data, '/v1/payouts', query);
+    }
+
+    #listBalanceTransactions(query: Record<string, any>, stripeAccount: string | null) {
+        let data = this.balanceTransactions.filter(t => (t.stripeAccount ?? null) === stripeAccount);
+
+        if (query.payout) {
+            data = data.filter(t => t.payout === query.payout);
+        }
+        if (query.type) {
+            data = data.filter(t => t.type === query.type);
+        }
+        if (query.created?.gte !== undefined) {
+            data = data.filter(t => t.created >= query.created.gte);
+        }
+        if (query.created?.lte !== undefined) {
+            data = data.filter(t => t.created <= query.created.lte);
+        }
+        return this.#list(data, '/v1/balance_transactions', query);
+    }
+
+    #listCheckoutSessions(query: Record<string, any>) {
+        let data = this.checkoutSessions;
+
+        if (query.payment_intent) {
+            data = data.filter(s => s.payment_intent === query.payment_intent);
+        }
+        return this.#list(data, '/v1/checkout/sessions', query);
+    }
+
+    /**
+     * Amounts are in Stripe cents, like the real API.
+     */
+    createPayout(data: { amount: number; arrivalDate: Date; status?: string; statementDescriptor?: string; stripeAccount?: string | null } & Record<string, any>): StripeObject {
+        const { arrivalDate, statementDescriptor, stripeAccount, ...rest } = data;
+        const payout: StripeObject = {
+            id: this.createId('po'),
+            object: 'payout',
+            status: 'paid',
+            // Stripe only reports the transactions of a payout it finished reconciling, and never
+            // for manual payouts
+            reconciliation_status: 'completed',
+            automatic: true,
+            currency: 'eur',
+            arrival_date: Math.floor(arrivalDate.getTime() / 1000),
+            statement_descriptor: statementDescriptor ?? 'STAMHOOFD',
+            stripeAccount: stripeAccount ?? null,
+            ...rest,
+        };
+        this.payouts.push(payout);
+        return payout;
+    }
+
+    /**
+     * The `payout` field links the transaction to a payout, `stripeAccount` scopes it to a
+     * connected account (null = platform account). Sources are served exactly as passed, so tests
+     * control the expansions.
+     */
+    createBalanceTransaction(data: { type: string; amount: number; created: Date; payout?: string | null; stripeAccount?: string | null; fee?: number; source?: unknown } & Record<string, any>): StripeObject {
+        const { created, payout, stripeAccount, ...rest } = data;
+        const feeDetails = (rest.fee_details ?? []) as { amount: number }[];
+
+        const transaction: StripeObject = {
+            id: this.createId('txn'),
+            object: 'balance_transaction',
+            currency: 'eur',
+            fee_details: [],
+            created: Math.floor(created.getTime() / 1000),
+            payout: payout ?? null,
+            stripeAccount: stripeAccount ?? null,
+            ...rest,
+            // Stripe guarantees these: fee is the sum of its details, net is what the balance
+            // actually moved. Deriving them keeps fixtures from describing impossible transactions
+            fee: feeDetails.reduce((total, detail) => total + detail.amount, 0),
+            net: data.amount - feeDetails.reduce((total, detail) => total + detail.amount, 0),
+        };
+        this.balanceTransactions.push(transaction);
+        return transaction;
+    }
+
+    /**
+     * An expanded ApplicationFee object, used as the source of application_fee transactions and as
+     * charge.application_fee expansions.
+     */
+    createApplicationFee(data: { amount: number; account: string; originatingTransaction?: StripeObject | null; charge?: StripeObject | null } & Record<string, any>): StripeObject {
+        const { account, originatingTransaction, charge, ...rest } = data;
+        return {
+            id: this.createId('fee'),
+            object: 'application_fee',
+            account,
+            originating_transaction: originatingTransaction ?? null,
+            charge: charge ?? null,
+            ...rest,
+        };
+    }
+
+    createChargeObject(data: Record<string, any> = {}): StripeObject {
+        const charge: StripeObject = {
+            id: this.createId('ch'),
+            object: 'charge',
+            metadata: {},
+            ...data,
+        };
+        this.charges.push(charge);
+        return charge;
+    }
+
+    createCheckoutSession(data: { paymentIntent: string } & Record<string, any>): StripeObject {
+        const { paymentIntent, ...rest } = data;
+        const session: StripeObject = {
+            id: this.createId('cs'),
+            object: 'checkout.session',
+            payment_intent: paymentIntent,
+            ...rest,
+        };
+        this.checkoutSessions.push(session);
+        return session;
+    }
+
     #getPaymentIntent(id: string) {
         const intent = this.paymentIntents.find(i => i.id === id);
         if (!intent) {

package/src/crons/stripe-payout-reports.ts

@@ -1,69 +0,0 @@
-import { registerCron } from '@stamhoofd/crons';
-import { Organization, Platform } from '@stamhoofd/models';
-import { Formatter } from '@stamhoofd/utility';
-import { StripePayoutReporter } from '../helpers/StripePayoutReporter.js';
-
-registerCron('stripe-payout-reports', createStripePayoutReports);
-
-let lastStripeReport: Date | null = null;
-
-/**
- * Sends a monthly report of all Stripe payouts of the previous month, so we can check
- * whether everything we charged via Stripe application fees was invoiced correctly.
- */
-async function createStripePayoutReports() {
-    if (STAMHOOFD.environment !== 'production') {
-        return;
-    }
-
-    if (STAMHOOFD.userMode === 'platform') {
-        return;
-    }
-
-    if (STAMHOOFD.STRIPE_CONNECT_METHOD === 'standard') {
-        return;
-    }
-
-    if (new Date().getHours() > 5 || new Date().getHours() < 2) {
-        // Fix for sending emails after deployments
-        return;
-    }
-
-    // Send the report on the 6th day of the month, once
-    const today = new Date();
-    if (today.getDate() !== 6 || (lastStripeReport && Formatter.dateWithoutDay(lastStripeReport) === Formatter.dateWithoutDay(today))) {
-        return;
-    }
-
-    if (!STAMHOOFD.STRIPE_SECRET_KEY) {
-        console.log('No stripe key set');
-        return;
-    }
-
-    const membershipOrganizationId = (await Platform.getShared()).membershipOrganizationId;
-    if (!membershipOrganizationId) {
-        return;
-    }
-
-    const membershipOrganization = await Organization.getByID(membershipOrganizationId, true);
-
-    console.log('Creating Stripe payout report...');
-
-    // Previous month
-    const previousMonthStart = new Date(today.getFullYear(), today.getMonth() - 1, 1);
-    const end = new Date(new Date(today.getFullYear(), today.getMonth(), 1).getTime() - 1000);
-
-    const reporter = new StripePayoutReporter({
-        secretKey: STAMHOOFD.STRIPE_SECRET_KEY,
-        sellingOrganization: membershipOrganization,
-    });
-
-    await reporter.build(previousMonthStart, end);
-    await reporter.sendEmail({
-        to: [{ email: 'simon@stamhoofd.be' }],
-        // Only send the report to the extra (accounting) recipients when it is complete and valid
-        extraRecipientsWhenValid: (STAMHOOFD.STRIPE_PAYOUT_REPORT_EMAILS ?? []).map(email => ({ email })),
-    });
-
-    lastStripeReport = new Date();
-}

package/src/endpoints/organization/dashboard/stripe/StripePayoutsExportEndpoint.test.ts

@@ -1,103 +0,0 @@
-import { Request } from '@simonbackx/simple-endpoints';
-import { EmailMocker } from '@stamhoofd/email';
-import type { Organization, Token, User } from '@stamhoofd/models';
-import { OrganizationFactory, UserFactory } from '@stamhoofd/models';
-import { Token as TokenModel } from '@stamhoofd/models';
-import { QueueHandler } from '@stamhoofd/queues';
-import { Company } from '@stamhoofd/structures';
-import { STExpect } from '@stamhoofd/test-utils';
-import nock from 'nock';
-
-import { resetNock } from '../../../../../tests/helpers/resetNock.js';
-import { testServer } from '../../../../../tests/helpers/TestServer.js';
-import { initMembershipOrganization } from '../../../../../tests/init/initMembershipOrganization.js';
-import { initPlatformAdmin } from '../../../../../tests/init/initPlatformAdmin.js';
-import { GetStripePayoutsExportStatusEndpoint } from './GetStripePayoutsExportStatusEndpoint.js';
-import { StripePayoutsExportEndpoint } from './StripePayoutsExportEndpoint.js';
-
-describe('Endpoint.StripePayoutsExport', () => {
-    const endpoint = new StripePayoutsExportEndpoint();
-    const statusEndpoint = new GetStripePayoutsExportStatusEndpoint();
-
-    let membershipOrganization: Organization;
-    let admin: User;
-    let adminToken: Token;
-
-    beforeAll(async () => {
-        membershipOrganization = await initMembershipOrganization();
-        membershipOrganization.meta.companies = [
-            Company.create({
-                name: 'Platform BV',
-                companyNumber: '0700000000',
-                VATNumber: 'BE0700000000',
-            }),
-        ];
-        await membershipOrganization.save();
-
-        ({ admin, adminToken } = await initPlatformAdmin());
-    });
-
-    afterEach(() => {
-        resetNock();
-    });
-
-    const post = async (organization: Organization, token: Token) => {
-        const request = Request.buildJson('POST', '/stripe/payouts', organization.getApiHost(), {
-            start: new Date(2026, 2, 1).getTime(),
-            end: new Date(2026, 3, 1).getTime() - 1000,
-        });
-        request.headers.authorization = 'Bearer ' + token.accessToken;
-        return await testServer.test(endpoint, request);
-    };
-
-    const getStatus = async (organization: Organization, token: Token) => {
-        const request = Request.buildJson('GET', '/stripe/payouts/status', organization.getApiHost());
-        request.headers.authorization = 'Bearer ' + token.accessToken;
-        return await testServer.test(statusEndpoint, request);
-    };
-
-    test('A platform admin can export payout reports for the membership organization', async () => {
-        nock('https://api.stripe.com')
-            .get('/v1/payouts')
-            .query(true)
-            .reply(200, { object: 'list', data: [], has_more: false, url: '/v1/payouts' });
-
-        const response = await post(membershipOrganization, adminToken);
-        expect(response.status).toBe(200);
-
-        // Wait for the scheduled report to complete
-        await QueueHandler.awaitAll();
-
-        const emails = await EmailMocker.transactional.getSucceededEmails();
-        const reportEmail = emails.find(e => e.subject.startsWith('Stripe Uitbetalingen'));
-        expect(reportEmail).toBeDefined();
-        expect(reportEmail!.attachments).toHaveLength(1);
-
-        // The report is sent to the user that requested it
-        expect(reportEmail!.to).toContain(admin.email);
-
-        // The queue is empty again
-        const statusResponse = await getStatus(membershipOrganization, adminToken);
-        expect(statusResponse.body).toEqual([]);
-    });
-
-    test('A user without platform full access cannot export payout reports', async () => {
-        const user = await new UserFactory({ organization: membershipOrganization }).create();
-        const token = await TokenModel.createToken(user);
-
-        await expect(post(membershipOrganization, token)).rejects.toThrow(
-            STExpect.simpleError({ code: 'permission_denied' }),
-        );
-        await expect(getStatus(membershipOrganization, token)).rejects.toThrow(
-            STExpect.simpleError({ code: 'permission_denied' }),
-        );
-    });
-
-    test('Payout reports are not available for other organizations', async () => {
-        const otherOrganization = await new OrganizationFactory({}).create();
-
-        await expect(post(otherOrganization, adminToken)).rejects.toThrow(
-            STExpect.simpleError({ code: 'not_available' }),
-        );
-    });
-});