@stamhoofd/backend 2.140.0 → 2.142.0

package/src/helpers/StripeSettlementSyncRunner.test.ts

@@ -0,0 +1,66 @@
+import type { Organization } from '@stamhoofd/models';
+import { OrganizationFactory } from '@stamhoofd/models';
+import { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { PaymentProvider } from '@stamhoofd/structures';
+import { v4 as uuidv4 } from 'uuid';
+
+import { StripeMocker } from '../../tests/helpers/StripeMocker.js';
+import { SettlementService } from '../services/SettlementService.js';
+import { StripeSettlementSyncRunner } from './StripeSettlementSyncRunner.js';
+
+describe('Helper.StripeSettlementSyncRunner', () => {
+    const stripeMocker = new StripeMocker();
+    let organization: Organization;
+
+    beforeAll(async () => {
+        stripeMocker.start();
+        organization = await new OrganizationFactory({}).create();
+    });
+
+    afterAll(() => {
+        stripeMocker.stop();
+    });
+
+    // Old dates that no other test uses, so the settledAt window only selects this test's rows
+    const settledAt = new Date(1990, 0, 5);
+    const windowStart = new Date(1990, 1, 1);
+
+    const createUnsyncedSettlement = async (failureCount: number) => {
+        const settlement = await SettlementService.upsertSettlement({
+            provider: PaymentProvider.Stripe,
+            externalId: 'po_' + uuidv4(),
+            organizationId: organization.id,
+            amount: 100_00_00,
+            settledAt,
+        });
+        for (let i = 0; i < failureCount; i++) {
+            await SettlementService.markSyncFailed(settlement);
+        }
+        return settlement;
+    };
+
+    const retry = async () => {
+        const runner = new StripeSettlementSyncRunner({ secretKey: STAMHOOFD.STRIPE_SECRET_KEY! });
+        await runner.retryUnsyncedSettlements({ windowStart });
+    };
+
+    test('a retry that cannot retrieve the payout anymore still counts towards the cap', async () => {
+        const settlement = await createUnsyncedSettlement(1);
+
+        // The mocker has no payout with this id: the retrieve fails with a 404
+        await retry();
+
+        const fresh = await Settlement.getByID(settlement.id);
+        expect(fresh!.syncFailureCount).toBe(2);
+        expect(fresh!.syncedAt).toBeNull();
+    });
+
+    test('a settlement at the failure cap is not retried anymore', async () => {
+        const settlement = await createUnsyncedSettlement(5);
+
+        await retry();
+
+        const fresh = await Settlement.getByID(settlement.id);
+        expect(fresh!.syncFailureCount).toBe(5);
+    });
+});

package/src/helpers/StripeSettlementSyncRunner.ts

@@ -0,0 +1,160 @@
+import { StripeAccount } from '@stamhoofd/models';
+import { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { PaymentProvider } from '@stamhoofd/structures';
+import { SettlementStatus } from '@stamhoofd/structures/settlements/SettlementStatus.js';
+
+import { SettlementService } from '../services/SettlementService.js';
+import type { ProviderSettlementSyncRunner, ProviderSyncRunOptions } from './ProviderSettlementSyncRunner.js';
+import { StripeSettlementSync } from './StripeSettlementSync.js';
+import { WebmasterReport } from './WebmasterReport.js';
+
+/**
+ * A settlement that keeps failing needs a human: stop retrying after this many attempts.
+ */
+const MAXIMUM_FAILURE_COUNT = 5;
+
+/**
+ * Stripe-specific knobs; owned here, opaque to the SettlementSyncRunner orchestrator (it forwards
+ * them verbatim).
+ */
+export type StripeSyncOptions = {
+    /**
+     * Re-sync payouts that are already synced.
+     */
+    force?: boolean;
+
+    /**
+     * After the window walk, force-retry stuck settlements older than the window.
+     */
+    retryUnsynced?: boolean;
+};
+
+export class StripeSettlementSyncRunner implements ProviderSettlementSyncRunner {
+    readonly #secretKey: string;
+    readonly #force: boolean;
+    readonly #retryUnsynced: boolean;
+
+    constructor({ secretKey, force = false, retryUnsynced = false }: { secretKey: string } & StripeSyncOptions) {
+        this.#secretKey = secretKey;
+        this.#force = force;
+        this.#retryUnsynced = retryUnsynced;
+    }
+
+    /**
+     * Walks the window month by month: fees first, then our platform payouts, then the connected
+     * accounts.
+     */
+    async run({ start, end, summary, onProgress }: ProviderSyncRunOptions): Promise<void> {
+        const platformSync = new StripeSettlementSync({ secretKey: this.#secretKey });
+
+        let currentMonth = new Date(start.getFullYear(), start.getMonth(), 1);
+
+        while (true) {
+            const { start: monthStartUnix, end: monthEndUnix } = SettlementService.getMonthUnixStartEnd(currentMonth);
+            if (monthStartUnix * 1000 > end.getTime()) {
+                break;
+            }
+
+            const windowStart = new Date(Math.max(monthStartUnix * 1000, start.getTime()));
+            const windowEnd = new Date(Math.min(monthEndUnix * 1000, end.getTime()));
+
+            try {
+                await platformSync.syncFees({ start: windowStart, end: windowEnd });
+                summary.feeMonths += 1;
+            } catch (e) {
+                // syncFees already emailed nothing: it throws an aggregate, the month is retried by
+                // the next run and the month is not invoiced until it completes
+                console.error('Fee sync failed for month ' + currentMonth.toISOString(), e);
+                summary.failedFeeMonths += 1;
+            }
+
+            const platformResult = await platformSync.syncPayouts({ start: windowStart, end: windowEnd, force: this.#force });
+            summary.synced += platformResult.synced;
+            summary.skipped += platformResult.skipped;
+            summary.failed += platformResult.failed;
+
+            const connectedResult = await this.syncConnectedPayouts({ start: windowStart, end: windowEnd });
+            summary.synced += connectedResult.synced;
+            summary.skipped += connectedResult.skipped;
+            summary.failed += connectedResult.failed;
+
+            onProgress?.();
+            currentMonth = new Date(currentMonth.getFullYear(), currentMonth.getMonth() + 1, 1);
+        }
+
+        if (this.#retryUnsynced) {
+            await this.retryUnsyncedSettlements({ windowStart: start });
+        }
+    }
+
+    /**
+     * Walks the payouts of every active connected account.
+     */
+    async syncConnectedPayouts({ start, end }: { start: Date; end?: Date }): Promise<{ synced: number; skipped: number; failed: number }> {
+        const totals = { synced: 0, skipped: 0, failed: 0 };
+
+        const accounts = await StripeAccount.select().where('status', 'active').fetch();
+
+        for (const account of accounts) {
+            try {
+                const sync = new StripeSettlementSync({ secretKey: this.#secretKey, stripeAccount: account });
+                const result = await sync.syncPayouts({ start, end, force: this.#force });
+                totals.synced += result.synced;
+                totals.skipped += result.skipped;
+                totals.failed += result.failed;
+            } catch (e) {
+                if (e !== null && typeof e === 'object' && 'type' in e && e.type === 'StripePermissionError' && e.message.includes(account.accountId) && e.message.includes('does not have access to account')) {
+                    // Stripe account no longer in active use
+                    console.error(e, 'marking stripe account', account.id, account.accountId, 'as inaccessible because we do not seem to have access to it any longer');
+                    account.status = 'inaccessible';
+                    await account.save();
+                    totals.skipped += 1;
+                    continue;
+                }
+                console.error('Failed to sync payouts of Stripe account ' + account.accountId, e);
+                totals.failed += 1;
+
+                WebmasterReport.report('Synchroniseren Stripe uitbetalingen van account ' + account.accountId + ' mislukt', e);
+            }
+        }
+
+        return totals;
+    }
+
+    /**
+     * Settlements outside the window that never completed a sync (syncedAt IS NULL is the whole
+     * error queue). Every failed retry bumps syncFailureCount, so a broken payout stops retrying
+     * after MAXIMUM_FAILURE_COUNT attempts and waits in the problem report instead. Always forced,
+     * regardless of the force configuration.
+     */
+    async retryUnsyncedSettlements({ windowStart }: { windowStart: Date }): Promise<void> {
+        const settlements = await Settlement.select()
+            .where('provider', PaymentProvider.Stripe)
+            .where('syncedAt', null)
+            // Only money that actually arrived holds transactions to walk
+            .where('status', SettlementStatus.Paid)
+            .where('syncFailureCount', '<', MAXIMUM_FAILURE_COUNT)
+            // The window walk already attempted (and counted) recent payouts
+            .where('settledAt', '<', windowStart)
+            .limit(50)
+            .fetch();
+
+        for (const settlement of settlements) {
+            const failureCountBefore = settlement.syncFailureCount;
+            try {
+                const stripeAccount = settlement.stripeAccountId ? await StripeAccount.getByID(settlement.stripeAccountId) : null;
+                const sync = new StripeSettlementSync({ secretKey: this.#secretKey, stripeAccount: stripeAccount ?? null });
+                await sync.syncPayoutById(settlement.externalId, { force: true });
+            } catch (e) {
+                console.error('Retry of settlement ' + settlement.externalId + ' failed', e);
+
+                // Errors before the walk (e.g. the payout can't be retrieved anymore) don't pass
+                // markSyncFailed: count them here or the retry cap never triggers
+                const fresh = await Settlement.getByID(settlement.id);
+                if (fresh && fresh.syncFailureCount === failureCountBefore) {
+                    await SettlementService.markSyncFailed(fresh);
+                }
+            }
+        }
+    }
+}

package/src/helpers/WebmasterReport.test.ts

@@ -0,0 +1,109 @@
+import { EmailMocker } from '@stamhoofd/email';
+import { QueueHandler } from '@stamhoofd/queues';
+
+import { WebmasterReport } from './WebmasterReport.js';
+
+describe('WebmasterReport', () => {
+    // Emails of other tests can still be in the queue when this one runs: match on the subject
+    const getEmails = async (subjectPrefix = 'Synchroniseren uitbetalingen') => {
+        return (await EmailMocker.transactional.getSucceededEmails()).filter(e => e.subject.startsWith(subjectPrefix));
+    };
+
+    test('problems reported inside a group are sent as one email', async () => {
+        await WebmasterReport.group('Synchroniseren uitbetalingen', async () => {
+            WebmasterReport.report('Uitbetaling po_1 mislukt', new Error('Boom'));
+            WebmasterReport.report('Uitbetaling po_2 mislukt', 'Geen betaling gevonden');
+        });
+
+        const emails = await getEmails();
+        expect(emails).toHaveLength(1);
+        expect(emails[0].subject).toBe('Synchroniseren uitbetalingen: 2 problemen');
+        expect(emails[0].html).toContain('Uitbetaling po_1 mislukt');
+        expect(emails[0].html).toContain('Error: Boom');
+        expect(emails[0].html).toContain('Uitbetaling po_2 mislukt');
+        expect(emails[0].html).toContain('Geen betaling gevonden');
+    });
+
+    test('a group without problems sends nothing', async () => {
+        await WebmasterReport.group('Synchroniseren uitbetalingen', async () => {
+            // Nothing to report
+        });
+
+        expect(await getEmails()).toHaveLength(0);
+    });
+
+    test('problems are still reported when the group throws', async () => {
+        await expect(WebmasterReport.group('Synchroniseren uitbetalingen', async () => {
+            WebmasterReport.report('Uitbetaling po_1 mislukt');
+            throw new Error('Boom');
+        })).rejects.toThrow('Boom');
+
+        const emails = await getEmails();
+        expect(emails).toHaveLength(1);
+        expect(emails[0].subject).toBe('Synchroniseren uitbetalingen: 1 probleem');
+    });
+
+    test('only the first problems are listed, the rest is counted', async () => {
+        await WebmasterReport.group('Synchroniseren uitbetalingen', async () => {
+            for (let index = 0; index < 100; index++) {
+                WebmasterReport.report('Uitbetaling po_' + index + ' mislukt');
+            }
+        });
+
+        const emails = await getEmails();
+        expect(emails).toHaveLength(1);
+        expect(emails[0].subject).toBe('Synchroniseren uitbetalingen: 100 problemen');
+        expect(emails[0].html).toContain('Uitbetaling po_19 mislukt');
+        expect(emails[0].html).not.toContain('Uitbetaling po_20 mislukt');
+        expect(emails[0].html).toContain('En nog 80 andere problemen');
+    });
+
+    test('problems reported in queued work land in the surrounding group', async () => {
+        await WebmasterReport.group('Synchroniseren uitbetalingen', async () => {
+            await QueueHandler.schedule('webmaster-report-test', async () => {
+                WebmasterReport.report('Uitbetaling po_1 mislukt');
+            });
+        });
+
+        const emails = await getEmails();
+        expect(emails).toHaveLength(1);
+        expect(emails[0].subject).toBe('Synchroniseren uitbetalingen: 1 probleem');
+    });
+
+    test('titles and details are escaped', async () => {
+        await WebmasterReport.group('Synchroniseren uitbetalingen', async () => {
+            WebmasterReport.report('Uitbetaling van <b>Chiro & Co</b> mislukt', new Error('Regel 1\nRegel 2'));
+        });
+
+        const [email] = await getEmails();
+        expect(email.html).toContain('Uitbetaling van &lt;b&gt;Chiro &amp; Co&lt;/b&gt; mislukt');
+        expect(email.html).toContain('Regel 1<br>Regel 2');
+    });
+
+    test('a problem reported outside a group is sent on its own', async () => {
+        WebmasterReport.report('Uitbetaling po_1 mislukt', new Error('Boom'));
+
+        const emails = await getEmails('Uitbetaling po_1 mislukt');
+        expect(emails).toHaveLength(1);
+        expect(emails[0].html).toContain('Error: Boom');
+    });
+
+    test('groups only collect the problems reported inside them', async () => {
+        await Promise.all([
+            WebmasterReport.group('Synchroniseren uitbetalingen', async () => {
+                await Promise.resolve();
+                WebmasterReport.report('Uitbetaling po_1 mislukt');
+            }),
+            WebmasterReport.group('Aanrekenen applicatiekosten', async () => {
+                WebmasterReport.report('Maand 2026-01 overgeslagen');
+            }),
+        ]);
+
+        const [sync] = await getEmails();
+        const [invoicing] = await getEmails('Aanrekenen applicatiekosten');
+        expect(sync.subject).toBe('Synchroniseren uitbetalingen: 1 probleem');
+        expect(sync.html).toContain('Uitbetaling po_1 mislukt');
+        expect(invoicing.subject).toBe('Aanrekenen applicatiekosten: 1 probleem');
+        expect(invoicing.html).toContain('Maand 2026-01 overgeslagen');
+    });
+});

package/src/helpers/WebmasterReport.ts

@@ -0,0 +1,115 @@
+import { Email } from '@stamhoofd/email';
+import { Formatter } from '@stamhoofd/utility';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Problems above this are only counted: a flood is one cause repeated per item, so listing them
+ * all adds nothing.
+ */
+const MAXIMUM_LISTED_PROBLEMS = 20;
+
+/**
+ * Collects the problems of one run (a settlement sync, an invoicing round) into a single webmaster
+ * email instead of one email per failing item.
+ *
+ * Reporting outside a `group` still sends its own email right away: a caller that forgets to group
+ * mails too much, never too little.
+ */
+export class WebmasterReport {
+    static #current = new AsyncLocalStorage<WebmasterReport>();
+
+    readonly #subject: string;
+    readonly #problems: string[] = [];
+    #count = 0;
+    #sent = false;
+
+    private constructor(subject: string) {
+        this.#subject = subject;
+    }
+
+    /**
+     * Emails everything the handler reported after it finished, also when it throws.
+     */
+    static async group<T>(subject: string, handler: () => Promise<T>): Promise<T> {
+        const report = new WebmasterReport(subject);
+        try {
+            return await this.#current.run(report, handler);
+        } finally {
+            report.#send();
+        }
+    }
+
+    static report(title: string, detail?: unknown) {
+        if (this.#current.getStore()?.collect(title, detail)) {
+            return;
+        }
+
+        Email.sendWebmaster({
+            subject: title,
+            html: describeProblem(title, detail),
+        });
+    }
+
+    /**
+     * Returns false when this report was already sent, so the problem still gets its own email.
+     */
+    collect(title: string, detail?: unknown): boolean {
+        if (this.#sent) {
+            return false;
+        }
+
+        this.#count += 1;
+        if (this.#problems.length < MAXIMUM_LISTED_PROBLEMS) {
+            this.#problems.push(describeProblem(title, detail));
+        }
+        return true;
+    }
+
+    #send() {
+        this.#sent = true;
+
+        if (this.#count === 0) {
+            return;
+        }
+
+        const notListed = this.#count - this.#problems.length;
+
+        Email.sendWebmaster({
+            subject: this.#subject + ': ' + this.#count + (this.#count === 1 ? ' probleem' : ' problemen'),
+            html: this.#problems.join('<br><br>')
+                + (notListed > 0
+                    ? '<br><br>' + (notListed === 1
+                        ? 'En nog 1 ander probleem dat niet in deze mail past.'
+                        : 'En nog ' + notListed + ' andere problemen die niet in deze mail passen.')
+                    : ''),
+        });
+    }
+}
+
+function describeProblem(title: string, detail: unknown): string {
+    const description = describe(detail);
+    return '<strong>' + escapeLines(title) + '</strong>' + (description ? '<br>' + description : '');
+}
+
+function describe(detail: unknown): string | null {
+    if (detail === undefined || detail === null) {
+        return null;
+    }
+    if (typeof detail === 'string') {
+        return escapeLines(detail);
+    }
+    if (detail instanceof Error) {
+        // Aggregates (SimpleErrors) put one message per line
+        return escapeLines(detail.toString());
+    }
+    try {
+        return escapeLines(JSON.stringify(detail) ?? 'Onbekend probleem');
+    } catch {
+        // Circular structures, BigInt, ...: never fail the error boundary that reports the problem
+        return 'Onbekend probleem';
+    }
+}
+
+function escapeLines(text: string): string {
+    return Formatter.escapeHtml(text).replace(/\n/g, '<br>');
+}

package/src/helpers/getPaymentIdForStripeCharge.test.ts

@@ -0,0 +1,91 @@
+import { StripeCheckoutSession, StripePaymentIntent } from '@stamhoofd/models';
+import Stripe from 'stripe';
+import { v4 as uuidv4 } from 'uuid';
+
+import { StripeMocker } from '../../tests/helpers/StripeMocker.js';
+import { passthroughFetch } from './passthroughFetch.js';
+import { getPaymentIdForStripeCharge } from './getPaymentIdForStripeCharge.js';
+
+describe('getPaymentIdForStripeCharge', () => {
+    const stripeMocker = new StripeMocker();
+    let stripePlatform: Stripe;
+
+    beforeAll(() => {
+        stripeMocker.start();
+        stripePlatform = new Stripe(STAMHOOFD.STRIPE_SECRET_KEY!, {
+            apiVersion: '2024-06-20',
+            typescript: true,
+            maxNetworkRetries: 0,
+            timeout: 10000,
+            httpClient: Stripe.createFetchHttpClient(passthroughFetch),
+        });
+    });
+
+    afterAll(() => {
+        stripeMocker.stop();
+    });
+
+    beforeEach(() => {
+        stripeMocker.clear();
+    });
+
+    const asCharge = (data: Record<string, unknown>): Stripe.Charge => {
+        return { id: stripeMocker.createId('ch'), object: 'charge', metadata: {}, ...data } as unknown as Stripe.Charge;
+    };
+
+    test('the payment metadata on the charge wins', async () => {
+        const paymentId = uuidv4();
+        const charge = asCharge({ metadata: { payment: paymentId } });
+
+        expect(await getPaymentIdForStripeCharge(charge, { stripePlatform })).toBe(paymentId);
+    });
+
+    test('falls back to the metadata of the application fee originating transaction', async () => {
+        const paymentId = uuidv4();
+        const originating = asCharge({ metadata: { payment: paymentId } });
+        const charge = asCharge({
+            application_fee: stripeMocker.createApplicationFee({
+                amount: 250,
+                account: 'acct_1',
+                originatingTransaction: originating,
+            }),
+        });
+
+        expect(await getPaymentIdForStripeCharge(charge, { stripePlatform })).toBe(paymentId);
+    });
+
+    test('falls back to a stored StripePaymentIntent', async () => {
+        const paymentId = uuidv4();
+        const intentId = stripeMocker.createId('pi');
+
+        const intent = new StripePaymentIntent();
+        intent.paymentId = paymentId;
+        intent.stripeIntentId = intentId;
+        await intent.save();
+
+        const charge = asCharge({ payment_intent: intentId });
+
+        expect(await getPaymentIdForStripeCharge(charge, { stripePlatform })).toBe(paymentId);
+    });
+
+    test('falls back to the checkout session of the payment intent', async () => {
+        const paymentId = uuidv4();
+        const intentId = stripeMocker.createId('pi');
+        const mockedSession = stripeMocker.createCheckoutSession({ paymentIntent: intentId });
+
+        const session = new StripeCheckoutSession();
+        session.paymentId = paymentId;
+        session.stripeSessionId = mockedSession.id;
+        await session.save();
+
+        const charge = asCharge({ payment_intent: intentId });
+
+        expect(await getPaymentIdForStripeCharge(charge, { stripePlatform })).toBe(paymentId);
+    });
+
+    test('returns null when nothing matches', async () => {
+        const charge = asCharge({ payment_intent: stripeMocker.createId('pi') });
+
+        expect(await getPaymentIdForStripeCharge(charge, { stripePlatform })).toBe(null);
+    });
+});

package/src/helpers/getPaymentIdForStripeCharge.ts

@@ -0,0 +1,71 @@
+import { StripeCheckoutSession, StripePaymentIntent } from '@stamhoofd/models';
+import type Stripe from 'stripe';
+
+/**
+ * Find the local payment behind a Stripe charge: charge metadata → application fee's originating
+ * transaction metadata → StripePaymentIntent → StripeCheckoutSession. Returns null when nothing
+ * matches: the caller decides whether that is an error.
+ *
+ * The `stripePlatform` client must not be account-scoped: checkout sessions live on the platform
+ * account.
+ */
+export async function getPaymentIdForStripeCharge(charge: Stripe.Charge, { stripePlatform }: { stripePlatform: Stripe }): Promise<string | null> {
+    // A destination charge shows up twice: as the platform charge (the application fee's
+    // originating transaction) and as the charge on the connected account. Both point to the same
+    // payment, so both are usable candidates.
+    const candidates: Stripe.Charge[] = [charge];
+
+    if (charge.application_fee && typeof charge.application_fee !== 'string') {
+        const originatingTransaction = charge.application_fee.originating_transaction;
+        if (originatingTransaction && typeof originatingTransaction !== 'string') {
+            candidates.push(originatingTransaction as Stripe.Charge);
+        }
+    }
+
+    for (const candidate of candidates) {
+        const paymentId = candidate.metadata?.payment;
+        if (paymentId) {
+            return paymentId;
+        }
+    }
+
+    // Historical bug where we didn't save payment in metadata: try to look it up by payment intent
+    for (const candidate of candidates) {
+        if (!candidate.payment_intent) {
+            continue;
+        }
+        const paymentIntentId = typeof candidate.payment_intent === 'string' ? candidate.payment_intent : candidate.payment_intent.id;
+
+        const stripePayments = await StripePaymentIntent.where({
+            stripeIntentId: paymentIntentId,
+        }, { limit: 1 });
+
+        if (stripePayments.length === 1) {
+            console.log('Found missing payment metadata for payment intent', paymentIntentId, stripePayments[0].paymentId);
+            return stripePayments[0].paymentId;
+        }
+
+        // Probably a card payment: search for the checkout session
+        const checkoutSessions = await stripePlatform.checkout.sessions.list({
+            payment_intent: paymentIntentId,
+        });
+
+        if (checkoutSessions.data.length !== 1) {
+            console.log('No Stripe Checkout Sessions found for payment intent ' + paymentIntentId);
+            continue;
+        }
+
+        const stripeCheckoutSessions = await StripeCheckoutSession.where({
+            stripeSessionId: checkoutSessions.data[0].id,
+        }, { limit: 1 });
+
+        if (stripeCheckoutSessions.length === 1) {
+            console.log('Found missing payment metadata for payment intent', paymentIntentId, stripeCheckoutSessions[0].paymentId);
+            return stripeCheckoutSessions[0].paymentId;
+        }
+
+        console.log('No payment found for checkout session ' + checkoutSessions.data[0].id);
+    }
+
+    return null;
+}