@stamhoofd/backend 2.142.0 → 2.143.0

package/src/helpers/MollieSettlementSyncRunner.ts

@@ -10,7 +10,7 @@ import type { ProviderSettlementSyncRunner, ProviderSyncRunOptions } from './Pro
  * (STAMHOOFD.MOLLIE_ORGANIZATION_TOKEN for the platform, a MollieToken row per organization).
  */
 export class MollieSettlementSyncRunner implements ProviderSettlementSyncRunner {
-    async run({ start, end, summary, onProgress }: ProviderSyncRunOptions): Promise<void> {
+    async run({ start, end, summary, onProgress, abort }: ProviderSyncRunOptions): Promise<void> {
         const accessToken = STAMHOOFD.MOLLIE_ORGANIZATION_TOKEN;
         if (!accessToken) {
             console.error('Missing mollie organization token');
@@ -24,8 +24,11 @@ export class MollieSettlementSyncRunner implements ProviderSettlementSyncRunner
                 // A plain access token without a refresh flow: the future expiry keeps
                 // refreshIfNeeded from attempting one
                 token.expiresOn = new Date(new Date().getTime() + 24 * 60 * 60 * 1000);
-                await new MollieSettlementSync({ token }).syncSettlements({ start, end, summary });
+                await new MollieSettlementSync({ token }).syncSettlements({ start, end, summary, abort });
             } catch (e) {
+                // An interrupted account is not a failing account
+                abort.throwIfAborted();
+
                 console.error(e);
                 summary.failed += 1;
             }
@@ -34,6 +37,8 @@ export class MollieSettlementSyncRunner implements ProviderSettlementSyncRunner
 
         const mollieTokens = await MollieToken.all();
         for (const token of mollieTokens) {
+            abort.throwIfAborted();
+
             // Tokens created before the settlements permission was added to the OAuth scope
             // cannot read settlements
             if (token.createdAt < new Date(2021, 8 /* september! */, 8)) {
@@ -42,8 +47,10 @@ export class MollieSettlementSyncRunner implements ProviderSettlementSyncRunner
             }
 
             try {
-                await new MollieSettlementSync({ token }).syncSettlements({ start, end, summary });
+                await new MollieSettlementSync({ token }).syncSettlements({ start, end, summary, abort });
             } catch (e) {
+                abort.throwIfAborted();
+
                 console.error(e);
                 summary.failed += 1;
             }

package/src/helpers/ProviderSettlementSyncRunner.ts

@@ -1,3 +1,5 @@
+import type { AbortSignal } from '@stamhoofd/queues';
+
 export type SettlementSyncSummary = {
     feeMonths: number;
     failedFeeMonths: number;
@@ -26,6 +28,12 @@ export type ProviderSyncRunOptions = {
      * Fired after each unit of work (a month for Stripe, an account for Mollie).
      */
     onProgress?: () => void;
+
+    /**
+     * Stops the walk at the next safe point (a restart). Aborting is not a sync failure: it leaves
+     * everything it touched retryable instead of counting or reporting it.
+     */
+    abort: AbortSignal;
 };
 
 /**

package/src/helpers/SettlementSyncRunner.test.ts

@@ -1,7 +1,9 @@
 import type { Organization } from '@stamhoofd/models';
 import { MolliePayment, OrganizationFactory, Payment } from '@stamhoofd/models';
 import { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { AbortSignal } from '@stamhoofd/queues';
 import { PaymentMethod, PaymentProvider, PaymentStatus } from '@stamhoofd/structures';
+import { STExpect } from '@stamhoofd/test-utils';
 import { v4 as uuidv4 } from 'uuid';
 import { vi } from 'vitest';
 
@@ -140,6 +142,57 @@ describe('Helper.SettlementSyncRunner', () => {
         expect(mollieRow.syncedAt).not.toBeNull();
     });
 
+    test('An aborted run walks nothing and does not report a failure', async () => {
+        const organization = await new OrganizationFactory({}).create();
+        const stripePayment = await createStripePayment(organization);
+
+        const payout = stripeMocker.createPayout({ amount: 10000, arrivalDate: new Date(2026, 0, 20) });
+        stripeMocker.createBalanceTransaction({
+            type: 'charge',
+            amount: 10000,
+            created: new Date(2026, 0, 15),
+            payout: payout.id,
+            source: stripeMocker.createChargeObject({ metadata: { payment: stripePayment.id } }),
+        });
+
+        const abort = new AbortSignal();
+        abort.abort();
+
+        // Throwing instead of returning a summary: a caller may not read an interrupted run as a
+        // completed one
+        await expect(new SettlementSyncRunner().run({
+            start: new Date(2026, 0, 1),
+            end: new Date(2026, 0, 31),
+            providers: [PaymentProvider.Stripe, PaymentProvider.Mollie],
+            abort,
+        })).rejects.toThrow(STExpect.simpleError({ code: 'queue-aborted' }));
+
+        expect(await Settlement.select().where('externalId', payout.id).first(false)).toBeNull();
+    });
+
+    test('An aborted run walks nothing of a provider Stripe never reached', async () => {
+        const mollieOrganization = await new OrganizationFactory({}).create();
+        await mollieMocker.setupToken(mollieOrganization);
+        const { mockPayment } = await createMolliePayment(mollieOrganization);
+        const mollieSettlement = mollieMocker.createSettlement({
+            payments: [mockPayment],
+            value: '50.00',
+            settledAt: new Date(2026, 0, 20),
+        });
+
+        const abort = new AbortSignal();
+        abort.abort();
+
+        await expect(new SettlementSyncRunner().run({
+            start: new Date(2026, 0, 1),
+            end: new Date(2026, 0, 31),
+            providers: [PaymentProvider.Mollie],
+            abort,
+        })).rejects.toThrow(STExpect.simpleError({ code: 'queue-aborted' }));
+
+        expect(await Settlement.select().where('externalId', mollieSettlement.id).first(false)).toBeNull();
+    });
+
     test('The stripe retryUnsynced option flows through the run', async () => {
         const organization = await new OrganizationFactory({}).create();
         const settlement = await SettlementService.upsertSettlement({

package/src/helpers/SettlementSyncRunner.ts

@@ -1,3 +1,4 @@
+import { AbortSignal } from '@stamhoofd/queues';
 import { PaymentProvider } from '@stamhoofd/structures';
 
 import { MollieSettlementSyncRunner } from './MollieSettlementSyncRunner.js';
@@ -19,11 +20,17 @@ export class SettlementSyncRunner {
      */
     callback: ((summary: SettlementSyncSummary) => void) | null = null;
 
-    async run({ start = new Date(2025, 0, 1), end, providers, stripe }: {
+    async run({ start = new Date(2025, 0, 1), end, providers, stripe, abort = new AbortSignal() }: {
         start?: Date;
         end?: Date | null;
         providers?: PaymentProvider[] | null;
         stripe?: StripeSyncOptions;
+
+        /**
+         * Stops the run at the next safe point, and throws what it was aborted with: a caller that
+         * treats a completed run as "done for today" may not mistake an interrupted one for it.
+         */
+        abort?: AbortSignal;
     } = {}): Promise<SettlementSyncSummary> {
         const summary: SettlementSyncSummary = { feeMonths: 0, failedFeeMonths: 0, synced: 0, skipped: 0, failed: 0 };
         const rangeEnd = end ?? new Date();
@@ -41,8 +48,12 @@ export class SettlementSyncRunner {
             if (includeStripe && STAMHOOFD.STRIPE_SECRET_KEY) {
                 const runner = new StripeSettlementSyncRunner({ secretKey: STAMHOOFD.STRIPE_SECRET_KEY, ...stripe });
                 try {
-                    await runner.run({ start, end: rangeEnd, summary, onProgress });
+                    await runner.run({ start, end: rangeEnd, summary, onProgress, abort });
                 } catch (e) {
+                    // An interrupted provider stops the whole run: it didn't fail, and the
+                    // providers after it would only be interrupted at their first step too
+                    abort.throwIfAborted();
+
                     console.error('Stripe settlement sync failed', e);
                     summary.failed += 1;
                 }
@@ -51,13 +62,19 @@ export class SettlementSyncRunner {
             if (includeMollie) {
                 const runner = new MollieSettlementSyncRunner();
                 try {
-                    await runner.run({ start, end: rangeEnd, summary, onProgress });
+                    await runner.run({ start, end: rangeEnd, summary, onProgress, abort });
                 } catch (e) {
+                    abort.throwIfAborted();
+
                     console.error('Mollie settlement sync failed', e);
                     summary.failed += 1;
                 }
             }
 
+            // A provider that ignores the signal (or a run without providers) may not hand back a
+            // summary that reads as a completed run
+            abort.throwIfAborted();
+
             return summary;
         });
     }

package/src/helpers/StripeSettlementSync.test.ts

@@ -2,17 +2,25 @@ import { EmailMocker } from '@stamhoofd/email';
 import type { Organization, StripeAccount } from '@stamhoofd/models';
 import { OrganizationFactory, Payment, Platform } from '@stamhoofd/models';
 import { ApplicationFee } from '@stamhoofd/models/models/ApplicationFee.js';
+import { BalanceItem } from '@stamhoofd/models/models/BalanceItem.js';
+import { BalanceItemPayment } from '@stamhoofd/models/models/BalanceItemPayment.js';
 import { PaymentSettlement } from '@stamhoofd/models/models/PaymentSettlement.js';
+import type { Settlement as SettlementModel } from '@stamhoofd/models/models/Settlement.js';
 import { Settlement } from '@stamhoofd/models/models/Settlement.js';
 import { SettlementCharge } from '@stamhoofd/models/models/SettlementCharge.js';
-import { PaymentMethod, PaymentProvider, PaymentStatus, PaymentType } from '@stamhoofd/structures';
+import { AbortSignal } from '@stamhoofd/queues';
+import { BalanceItemStatus, BalanceItemType, PaymentMethod, PaymentProvider, PaymentStatus, PaymentType } from '@stamhoofd/structures';
 import { ApplicationFeeType } from '@stamhoofd/structures/settlements/ApplicationFeeType.js';
 import { SettlementChargeType } from '@stamhoofd/structures/settlements/SettlementChargeType.js';
 import { SettlementStatus } from '@stamhoofd/structures/settlements/SettlementStatus.js';
+import { STExpect } from '@stamhoofd/test-utils';
 import { v4 as uuidv4 } from 'uuid';
+import { vi } from 'vitest';
 
 import { StripeMocker } from '../../tests/helpers/StripeMocker.js';
 import type { StripeObject } from '../../tests/helpers/StripeMocker.js';
+import { ApplicationFeeService } from '../services/ApplicationFeeService.js';
+import { SettlementService } from '../services/SettlementService.js';
 import { StripeSettlementSync } from './StripeSettlementSync.js';
 import { StripeSettlementSyncRunner } from './StripeSettlementSyncRunner.js';
 import { WebmasterReport } from './WebmasterReport.js';
@@ -71,6 +79,54 @@ describe('StripeSettlementSync', () => {
         return await Settlement.select().where('externalId', payout.id).first(true);
     };
 
+    /**
+     * A fee we already invoiced to the organization, like the ApplicationFeeInvoicer stores it: the
+     * membership organization bills it, the organization pays it. Every payout that contains such a
+     * fee needs a derived line on its fee payment.
+     */
+    const createInvoicedFee = async (externalId: string, amount: number, { settlement = null as SettlementModel | null } = {}) => {
+        const payment = new Payment();
+        payment.organizationId = membershipOrganization.id;
+        payment.payingOrganizationId = organization.id;
+        payment.stripeAccountId = stripeAccount.id;
+        payment.method = PaymentMethod.AccountDeductions;
+        payment.provider = PaymentProvider.Stripe;
+        payment.status = PaymentStatus.Succeeded;
+        payment.price = amount;
+        payment.paidAt = created;
+        await payment.save();
+
+        const balanceItem = new BalanceItem();
+        balanceItem.type = BalanceItemType.ServiceFee;
+        balanceItem.organizationId = membershipOrganization.id;
+        balanceItem.payingOrganizationId = organization.id;
+        balanceItem.unitPrice = amount;
+        balanceItem.quantity = 1;
+        balanceItem.status = BalanceItemStatus.Hidden;
+        await balanceItem.save();
+
+        const balanceItemPayment = new BalanceItemPayment();
+        balanceItemPayment.balanceItemId = balanceItem.id;
+        balanceItemPayment.paymentId = payment.id;
+        balanceItemPayment.organizationId = payment.organizationId;
+        balanceItemPayment.price = amount;
+        await balanceItemPayment.save();
+
+        const fee = new ApplicationFee();
+        fee.externalId = externalId;
+        fee.type = ApplicationFeeType.Service;
+        fee.amount = amount;
+        fee.organizationId = membershipOrganization.id;
+        fee.payingOrganizationId = organization.id;
+        fee.payingStripeAccountId = stripeAccount.id;
+        fee.balanceItemId = balanceItem.id;
+        fee.settlementId = settlement?.id ?? null;
+        fee.occurredAt = created;
+        await fee.save();
+
+        return { payment, fee };
+    };
+
     test('a full destination-charge payout reconciles to zero', async () => {
         const payment = await createPayment({ price: 100_00_00 });
         const payout = stripeMocker.createPayout({ amount: 225, arrivalDate });
@@ -359,6 +415,85 @@ describe('StripeSettlementSync', () => {
         expect(emails[0].html).toContain(second.id);
     });
 
+    test('a walk that fails still updates the fee payments of what it stored', async () => {
+        const payerPayment = await createPayment();
+        const stripeFee = stripeMocker.createApplicationFee({
+            amount: 250,
+            account: stripeAccount.accountId,
+            originatingTransaction: stripeMocker.createChargeObject({ metadata: { payment: payerPayment.id, serviceFee: '250' } }),
+        });
+        const { payment: feePayment } = await createInvoicedFee(stripeFee.id, 2_50_00);
+
+        const payout = stripeMocker.createPayout({ amount: 250, arrivalDate });
+        stripeMocker.createBalanceTransaction({ type: 'application_fee', amount: 250, created, payout: payout.id, source: stripeFee });
+
+        // Fails the walk after the fee was linked to the payout
+        stripeMocker.createBalanceTransaction({ type: 'issuing_authorization_hold', amount: 100, created, payout: payout.id, source: null });
+
+        expect(await createSync().syncPayouts({ start })).toEqual({ synced: 0, skipped: 0, failed: 1 });
+
+        // The walk linked the fee to this payout before it failed, so the fee payment gets its
+        // derived line: a fee may never sit in a payout that has no line for it
+        const settlement = await getSettlement(payout);
+        expect(settlement.syncedAt).toBeNull();
+
+        const derived = await PaymentSettlement.select().where('paymentId', feePayment.id).fetch();
+        expect(derived).toHaveLength(1);
+        expect(derived[0]).toMatchObject({
+            settlementId: settlement.id,
+            externalId: null,
+            amount: 2_50_00,
+        });
+    });
+
+    test('a fee walk updates the fee payments of the fees it stored before one failed', async () => {
+        const payerPayment = await createPayment();
+        const stripeFee = stripeMocker.createApplicationFee({
+            amount: 250,
+            account: stripeAccount.accountId,
+            // Both a service and a transfer part, so the fee is stored as two rows
+            originatingTransaction: stripeMocker.createChargeObject({ metadata: { payment: payerPayment.id, serviceFee: '30' } }),
+        });
+
+        // Already paid out and invoiced before this walk: the payout it sits in explains it through
+        // the derived line of its fee payment
+        const settlement = await SettlementService.upsertSettlement({
+            provider: PaymentProvider.Stripe,
+            externalId: 'po_' + uuidv4(),
+            organizationId: membershipOrganization.id,
+            amount: 30_00,
+            settledAt: arrivalDate,
+        });
+        const { payment: feePayment } = await createInvoicedFee(stripeFee.id, 30_00, { settlement });
+
+        stripeMocker.createBalanceTransaction({ type: 'application_fee', amount: 250, created, source: stripeFee });
+
+        // The service fee is stored, the transfer fee of the same transaction fails after it
+        const upsertFee = ApplicationFeeService.upsertFee.bind(ApplicationFeeService);
+        const spy = vi.spyOn(ApplicationFeeService, 'upsertFee').mockImplementation(async (data) => {
+            if (data.type === ApplicationFeeType.Transfer) {
+                throw new Error('Storing the transfer fee failed');
+            }
+            return await upsertFee(data);
+        });
+
+        try {
+            await expect(createSync().syncFees({ start, end: arrivalDate })).rejects.toThrow(
+                STExpect.simpleError({ code: 'stripe_fee_sync_failed' }),
+            );
+        } finally {
+            spy.mockRestore();
+        }
+
+        const derived = await PaymentSettlement.select().where('paymentId', feePayment.id).fetch();
+        expect(derived).toHaveLength(1);
+        expect(derived[0]).toMatchObject({
+            settlementId: settlement.id,
+            externalId: null,
+            amount: 30_00,
+        });
+    });
+
     test('a payout that failed after being paid keeps its status current', async () => {
         const payment = await createPayment();
         const payout = stripeMocker.createPayout({ amount: 10000, arrivalDate, stripeAccount: stripeAccount.accountId });
@@ -994,4 +1129,74 @@ describe('StripeSettlementSync', () => {
             expect(settlement.syncedAt).toBeNull();
         });
     });
+
+    describe('Aborting', () => {
+        /**
+         * Aborts the walk while it stores its first row, so the payout is interrupted halfway.
+         */
+        const abortDuringWalk = () => {
+            const abort = new AbortSignal();
+            const upsertCharge = SettlementService.upsertCharge.bind(SettlementService);
+
+            const spy = vi.spyOn(SettlementService, 'upsertCharge').mockImplementation(async (data) => {
+                abort.abort();
+                return await upsertCharge(data);
+            });
+
+            return { abort, restore: () => spy.mockRestore() };
+        };
+
+        test('an interrupted walk gives up its synced state without counting a failure', async () => {
+            const payout = stripeMocker.createPayout({ amount: 2000, arrivalDate });
+            for (let i = 0; i < 2; i++) {
+                stripeMocker.createBalanceTransaction({ type: 'stripe_fee', amount: 1000, created, payout: payout.id, source: null });
+            }
+
+            expect(await createSync().syncPayouts({ start })).toEqual({ synced: 1, skipped: 0, failed: 0 });
+            expect((await getSettlement(payout)).syncedAt).not.toBeNull();
+
+            const { abort, restore } = abortDuringWalk();
+            try {
+                await WebmasterReport.group('Onderbroken synchronisatie', async () => {
+                    await expect(createSync().syncPayouts({ start, force: true, abort })).rejects.toThrow(
+                        STExpect.simpleError({ code: 'queue-aborted' }),
+                    );
+                });
+            } finally {
+                restore();
+            }
+
+            // Only part of the payout was walked, so it may not keep claiming it is synced. A
+            // restart is not a failure of this payout: it doesn't count towards the retry cap
+            const settlement = await getSettlement(payout);
+            expect(settlement.syncedAt).toBeNull();
+            expect(settlement.syncFailureCount).toBe(0);
+
+            const emails = (await EmailMocker.transactional.getSucceededEmails()).filter(e => e.subject.startsWith('Onderbroken synchronisatie'));
+            expect(emails).toHaveLength(0);
+        });
+
+        test('the payouts after an interrupted one are left untouched', async () => {
+            const interrupted = stripeMocker.createPayout({ amount: 2000, arrivalDate });
+            for (let i = 0; i < 2; i++) {
+                stripeMocker.createBalanceTransaction({ type: 'stripe_fee', amount: 1000, created, payout: interrupted.id, source: null });
+            }
+
+            const untouched = stripeMocker.createPayout({ amount: 1000, arrivalDate });
+            stripeMocker.createBalanceTransaction({ type: 'stripe_fee', amount: 1000, created, payout: untouched.id, source: null });
+
+            const { abort, restore } = abortDuringWalk();
+            try {
+                await expect(createSync().syncPayouts({ start, abort })).rejects.toThrow(
+                    STExpect.simpleError({ code: 'queue-aborted' }),
+                );
+            } finally {
+                restore();
+            }
+
+            // The loop stopped at the payout it was walking: the other one was never started
+            expect((await getSettlement(interrupted)).syncedAt).toBeNull();
+            expect(await Settlement.select().where('externalId', untouched.id).count()).toBe(0);
+        });
+    });
 });