npm - @stamhoofd/backend - Versions diffs - 2.140.0 → 2.142.0 - Mend

@stamhoofd/backend 2.140.0 → 2.142.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (65) hide show

package/src/endpoints/organization/dashboard/settlements/SettlementsSyncEndpoint.ts ADDED Viewed

@@ -0,0 +1,104 @@
+import type { Decoder } from '@simonbackx/simple-encoding';
+import { ArrayDecoder, AutoEncoder, BooleanDecoder, DateDecoder, EnumDecoder, field } from '@simonbackx/simple-encoding';
+import type { DecodedRequest, Request } from '@simonbackx/simple-endpoints';
+import { Endpoint, Response } from '@simonbackx/simple-endpoints';
+import { SimpleError } from '@simonbackx/simple-errors';
+import { Platform } from '@stamhoofd/models';
+import { QueueHandler } from '@stamhoofd/queues';
+import { PaymentProvider } from '@stamhoofd/structures';
+import { SettlementsSyncStatus } from '@stamhoofd/structures/settlements/SettlementsSyncStatus.js';
+import { Context } from '../../../../helpers/Context.js';
+import { SettlementSyncRunner } from '../../../../helpers/SettlementSyncRunner.js';
+type Params = Record<string, never>;
+class Body extends AutoEncoder {
+    @field({ decoder: DateDecoder, optional: true })
+    start: Date = new Date(2025, 0, 1);
+    @field({ decoder: DateDecoder, nullable: true, optional: true })
+    end: Date | null = null;
+    @field({ decoder: new ArrayDecoder(new EnumDecoder(PaymentProvider)), nullable: true, optional: true })
+    providers: PaymentProvider[] | null = null;
+    @field({ decoder: BooleanDecoder, optional: true })
+    force = false;
+}
+type Query = undefined;
+type ResponseBody = undefined;
+/**
+ * Manually run the settlement sync (backfill) over a period. Everything is an upsert and
+ * already-synced settlements are skipped unless force, so re-running is cheap.
+ */
+export class SettlementsSyncEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    bodyDecoder = Body as Decoder<Body>;
+    static queue: SettlementsSyncStatus[] = [];
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'POST') {
+            return [false];
+        }
+        const params = Endpoint.parseParameters(request.url, '/settlements/sync', {});
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+    /**
+     * A sync covers the provider accounts of the whole platform: only platform admins, and only
+     * scoped to the platform membership organization (the owner of the platform's own payouts).
+     */
+    static async authenticate() {
+        const organization = await Context.setOrganizationScope();
+        const { user } = await Context.authenticate();
+        if (!Context.auth.hasPlatformFullAccess()) {
+            throw Context.auth.error();
+        }
+        const platform = await Platform.getShared();
+        if (!platform.membershipOrganizationId || platform.membershipOrganizationId !== organization.id) {
+            throw new SimpleError({
+                code: 'not_available',
+                message: 'Settlement syncs are only available for the platform membership organization',
+                statusCode: 400,
+            });
+        }
+        return { organization, user };
+    }
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        await SettlementsSyncEndpoint.authenticate();
+        const { start, end, providers, force } = request.body;
+        const item = SettlementsSyncStatus.create({
+            start,
+            end,
+            force,
+        });
+        SettlementsSyncEndpoint.queue.push(item);
+        QueueHandler.schedule('settlement-sync', async () => {
+            try {
+                const runner = new SettlementSyncRunner();
+                runner.callback = (summary) => {
+                    item.count = summary.synced + summary.skipped + summary.failed;
+                    item.failed = summary.failed + summary.failedFeeMonths;
+                };
+                await runner.run({ start, end, providers, stripe: { force } });
+            } finally {
+                SettlementsSyncEndpoint.queue.splice(SettlementsSyncEndpoint.queue.indexOf(item), 1);
+            }
+        }).catch(console.error);
+        return new Response(undefined);
+    }
+}

package/src/excel-loaders/payments.ts CHANGED Viewed

@@ -3,7 +3,7 @@ import type { XlsxTransformerColumn, XlsxTransformerConcreteColumn } from '@stam
 import { XlsxBuiltInNumberFormat } from '@stamhoofd/excel-writer';
 import { Order, StripeAccount } from '@stamhoofd/models';
 import type { OrderData } from '@stamhoofd/structures';
-import { BalanceItem, BalanceItemPaymentDetailed, BalanceItemRelationType, BalanceItemType, ExcelExportType, getBalanceItemRelationTypeName, getBalanceItemTypeName, PaginatedResponse, PaymentGeneral, PaymentMethodHelper, PaymentStatusHelper, StripeAccount as StripeAccountStruct } from '@stamhoofd/structures';
+import { BalanceItem, BalanceItemPaymentDetailed, BalanceItemRelationType, BalanceItemType, ExcelExportType, getBalanceItemRelationTypeName, getBalanceItemTypeName, PaginatedResponse, PaymentGeneral, PaymentMethod, PaymentMethodHelper, PaymentStatusHelper, StripeAccount as StripeAccountStruct } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
 import { ExportToExcelEndpoint } from '../endpoints/global/files/ExportToExcelEndpoint.js';
 import { GetPaymentsEndpoint } from '../endpoints/organization/dashboard/payments/GetPaymentsEndpoint.js';
@@ -594,6 +594,23 @@ function getSettlementColumns(): XlsxTransformerColumn<PaymentGeneral>[] {
                 };
             },
         },
+        {
+            id: 'settlement.check',
+            name: $t('%ZkA'),
+            width: 24,
+            getValue: (object: PaymentGeneralWithStripeAccount) => {
+                // Only meaningful for fee payments: their payout lines are derived from the
+                // application fees they bill, so a matching sum means completely paid out. Other
+                // methods either don't pay out or always match
+                if (object.method !== PaymentMethod.AccountDeductions) {
+                    return { value: '' };
+                }
+                const settled = object.settlements.reduce((total, line) => total + line.amount, 0);
+                return {
+                    value: settled === object.price ? '✓' : $t('%Zk0'),
+                };
+            },
+        },
     ];
 }

package/src/helpers/ApplicationFeeDetails.ts ADDED Viewed

@@ -0,0 +1,66 @@
+import type Stripe from 'stripe';
+/**
+ * The service/transfer split of one or more application fees. `fromStripe` is the single source of
+ * the split rule: the serviceFee metadata on the originating charge (in cents) is the service part,
+ * the remainder of the fee is the transfer part.
+ */
+export class ApplicationFeeDetails {
+    transferFee = 0;
+    serviceFee = 0;
+    count = 0;
+    minimumDate: Date | null = null;
+    maximumDate: Date | null = null;
+    constructor(details: { count?: number; transferFee: number; serviceFee: number; minimumDate: Date | null; maximumDate: Date | null }) {
+        this.count = details.count ?? 0;
+        this.transferFee = details.transferFee;
+        this.serviceFee = details.serviceFee;
+        this.minimumDate = details.minimumDate;
+        this.maximumDate = details.maximumDate;
+    }
+    get amount() {
+        return this.transferFee + this.serviceFee;
+    }
+    static fromStripe(transaction: Pick<Stripe.BalanceTransaction, 'source' | 'amount' | 'created'>) {
+        const source = transaction.source as Stripe.ApplicationFee;
+        // Only a destination charge has an originating transaction on our own account. A direct
+        // charge (Standard accounts) keeps it on the connected account, where this walk can't read
+        // the metadata that splits the fee
+        const originatingTransaction = source.originating_transaction;
+        if (!originatingTransaction || typeof originatingTransaction === 'string') {
+            throw new Error('Application fee ' + source.id + ' has no expanded originating transaction, which is not supported for direct charges');
+        }
+        const metadata = (originatingTransaction as Stripe.Charge).metadata;
+        const serviceFeeStr = metadata.serviceFee as unknown;
+        if (serviceFeeStr === undefined || typeof serviceFeeStr !== 'string') {
+            throw new Error('Missing serviceFee metadata');
+        }
+        const parsed = parseInt(serviceFeeStr);
+        if (isNaN(parsed) || !isFinite(parsed)) {
+            throw new Error('Invalid serviceFee metadata');
+        }
+        const serviceFee = parsed * 100; // in cents
+        const transferFee = transaction.amount * 100 - serviceFee;
+        // Both parts are billed as their own balance item, so a negative one would invent a credit
+        // out of wrong metadata instead of failing
+        if (serviceFee < 0 || transferFee < 0) {
+            throw new Error('Application fee of ' + transaction.amount * 100 + ' does not cover its serviceFee of ' + serviceFee);
+        }
+        return new ApplicationFeeDetails({
+            count: 1,
+            serviceFee,
+            transferFee,
+            minimumDate: new Date(transaction.created * 1000),
+            maximumDate: new Date(transaction.created * 1000),
+        });
+    }
+}

package/src/helpers/ApplicationFeeInvoicer.test.ts ADDED Viewed

@@ -0,0 +1,346 @@
+import { EmailMocker } from '@stamhoofd/email';
+import type { StripeAccount } from '@stamhoofd/models';
+import { BalanceItem, BalanceItemPayment, Organization, OrganizationFactory, Payment } from '@stamhoofd/models';
+import { ApplicationFee } from '@stamhoofd/models/models/ApplicationFee.js';
+import { PaymentSettlement } from '@stamhoofd/models/models/PaymentSettlement.js';
+import type { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { SettlementCharge } from '@stamhoofd/models/models/SettlementCharge.js';
+import { Address, BalanceItemType, Company, PaymentMethod, PaymentProvider, PaymentStatus } from '@stamhoofd/structures';
+import { ApplicationFeeType } from '@stamhoofd/structures/settlements/ApplicationFeeType.js';
+import { SettlementChargeType } from '@stamhoofd/structures/settlements/SettlementChargeType.js';
+import { Country } from '@stamhoofd/types/Country';
+import { v4 as uuidv4 } from 'uuid';
+import { StripeMocker } from '../../tests/helpers/StripeMocker.js';
+import { initMembershipOrganization } from '../../tests/init/initMembershipOrganization.js';
+import { ApplicationFeeService, LEGACY_FEE_PAYMENT_REFERENCE_PREFIX } from '../services/ApplicationFeeService.js';
+import { SettlementService } from '../services/SettlementService.js';
+import { ApplicationFeeInvoicer } from './ApplicationFeeInvoicer.js';
+import { WebmasterReport } from './WebmasterReport.js';
+describe('ApplicationFeeInvoicer', () => {
+    const stripeMocker = new StripeMocker();
+    let membershipOrganization: Organization;
+    // A month in the past that no other test writes fee rows in
+    const month = new Date(2024, 6, 1);
+    const occurredAt = new Date(2024, 6, 10);
+    const reference = 'application-fees-2024-07-01';
+    const belgianAddress = () => Address.create({
+        street: 'Teststraat',
+        number: '1',
+        postalCode: '9000',
+        city: 'Gent',
+        country: Country.Belgium,
+    });
+    beforeAll(async () => {
+        stripeMocker.start();
+        membershipOrganization = await initMembershipOrganization();
+        membershipOrganization.meta.companies = [
+            Company.create({
+                name: 'Platform BV',
+                companyNumber: '0700000000',
+                VATNumber: 'BE0700000000',
+                address: belgianAddress(),
+            }),
+        ];
+        await membershipOrganization.save();
+    });
+    afterAll(() => {
+        stripeMocker.stop();
+    });
+    beforeEach(async () => {
+        stripeMocker.clear();
+        ApplicationFeeService.resetWarnings();
+        // The test database persists across runs: leftover fees of this month would be billed again
+        await ApplicationFee.delete()
+            .where('occurredAt', '>=', month)
+            .where('occurredAt', '<', new Date(2024, 7, 1));
+    });
+    const init = async () => {
+        const organization = await new OrganizationFactory({}).create();
+        organization.meta.companies = [
+            Company.create({
+                name: 'Testvereniging VZW ' + organization.id,
+                companyNumber: '0500000000',
+                VATNumber: 'BE0500000000',
+                address: belgianAddress(),
+            }),
+        ];
+        await organization.save();
+        const stripeAccount = await stripeMocker.createStripeAccount(organization.id);
+        return { organization, stripeAccount };
+    };
+    const createFee = async (organization: Organization, stripeAccount: StripeAccount, { type = ApplicationFeeType.Service, amount = 30_00, settlement = null as Settlement | null, when = occurredAt } = {}) => {
+        const externalId = 'fee_' + uuidv4();
+        const charge = await SettlementService.upsertCharge({
+            type: type === ApplicationFeeType.Service ? SettlementChargeType.ApplicationFeeService : SettlementChargeType.ApplicationFeeTransfer,
+            externalId: externalId + ':' + type,
+            amount: -amount,
+            applicationFeeId: externalId,
+            organizationId: organization.id,
+            stripeAccountId: stripeAccount.id,
+            occurredAt: when,
+        });
+        return await ApplicationFeeService.upsertFee({
+            externalId,
+            type,
+            amount,
+            organizationId: membershipOrganization.id,
+            payingOrganizationId: organization.id,
+            payingStripeAccountId: stripeAccount.id,
+            settlementChargeId: charge.id,
+            settlementId: settlement?.id ?? null,
+            occurredAt: when,
+        });
+    };
+    const getFeePayments = async (organization: Organization) => {
+        return await Payment.select()
+            .where('payingOrganizationId', organization.id)
+            .where('reference', reference)
+            .where('method', PaymentMethod.AccountDeductions)
+            .fetch();
+    };
+    const createInvoicer = () => new ApplicationFeeInvoicer({ secretKey: STAMHOOFD.STRIPE_SECRET_KEY! });
+    /**
+     * Bills the month as if the run started a second from now: fees stored in the current second
+     * are deliberately left for the next run, and a test stores them right before billing.
+     */
+    const invoiceMonth = async () => {
+        await createInvoicer().generateInvoicesForMonth(membershipOrganization, month, new Date(Date.now() + 1000));
+    };
+    test('a month is billed per paying account, and every fee carries its balance item', async () => {
+        const { organization, stripeAccount } = await init();
+        const serviceFee = await createFee(organization, stripeAccount, { type: ApplicationFeeType.Service, amount: 30_00 });
+        const transferFee = await createFee(organization, stripeAccount, { type: ApplicationFeeType.Transfer, amount: 2_20_00 });
+        await invoiceMonth();
+        const payments = await getFeePayments(organization);
+        expect(payments).toHaveLength(1);
+        expect(payments[0]).toMatchObject({
+            price: 2_50_00,
+            status: PaymentStatus.Succeeded,
+            provider: PaymentProvider.Stripe,
+            organizationId: membershipOrganization.id,
+            stripeAccountId: stripeAccount.id,
+        });
+        const balanceItemPayments = await BalanceItemPayment.select().where('paymentId', payments[0].id).fetch();
+        const balanceItems = await BalanceItem.select().where('id', balanceItemPayments.map(b => b.balanceItemId)).fetch();
+        const serviceItem = balanceItems.find(i => i.type === BalanceItemType.ServiceFee)!;
+        const transferItem = balanceItems.find(i => i.type === BalanceItemType.TransferFee)!;
+        expect(serviceItem.unitPrice).toBe(30_00);
+        expect(transferItem.unitPrice).toBe(2_20_00);
+        expect(serviceItem.organizationId).toBe(membershipOrganization.id);
+        expect(serviceItem.payingOrganizationId).toBe(organization.id);
+        expect((await ApplicationFee.getByID(serviceFee.id))!.balanceItemId).toBe(serviceItem.id);
+        expect((await ApplicationFee.getByID(transferFee.id))!.balanceItemId).toBe(transferItem.id);
+    });
+    test('fees of different accounts are billed separately', async () => {
+        const { organization, stripeAccount } = await init();
+        const second = await stripeMocker.createStripeAccount(organization.id);
+        await createFee(organization, stripeAccount, { amount: 30_00 });
+        await createFee(organization, second, { amount: 40_00 });
+        await invoiceMonth();
+        const payments = await getFeePayments(organization);
+        expect(payments).toHaveLength(2);
+        expect(payments.map(p => p.price).sort((a, b) => a - b)).toEqual([30_00, 40_00]);
+        expect(payments.map(p => p.stripeAccountId).sort()).toEqual([stripeAccount.id, second.id].sort());
+    });
+    test('re-running bills nothing more', async () => {
+        const { organization, stripeAccount } = await init();
+        await createFee(organization, stripeAccount);
+        await invoiceMonth();
+        await invoiceMonth();
+        expect(await getFeePayments(organization)).toHaveLength(1);
+    });
+    test('a fee that arrives after its month was billed lands in an extra payment', async () => {
+        const { organization, stripeAccount } = await init();
+        await createFee(organization, stripeAccount, { amount: 30_00 });
+        await invoiceMonth();
+        const late = await createFee(organization, stripeAccount, { amount: 5_00 });
+        await invoiceMonth();
+        const payments = await getFeePayments(organization);
+        expect(payments).toHaveLength(2);
+        expect(payments.map(p => p.price).sort((a, b) => a - b)).toEqual([5_00, 30_00]);
+        expect((await ApplicationFee.getByID(late.id))!.balanceItemId).not.toBeNull();
+    });
+    test('the fee payment is settled by the payouts that contained its fees', async () => {
+        const { organization, stripeAccount } = await init();
+        const payout = await SettlementService.upsertSettlement({
+            provider: PaymentProvider.Stripe,
+            externalId: 'po_' + uuidv4(),
+            stripeAccountId: null,
+            organizationId: membershipOrganization.id,
+            amount: 30_00,
+            settledAt: new Date(2024, 6, 20),
+        });
+        await createFee(organization, stripeAccount, { amount: 30_00, settlement: payout });
+        await invoiceMonth();
+        const payment = (await getFeePayments(organization))[0];
+        const lines = await PaymentSettlement.select().where('paymentId', payment.id).fetch();
+        expect(lines).toHaveLength(1);
+        expect(lines[0]).toMatchObject({ settlementId: payout.id, amount: 30_00 });
+        // Completely paid out: the lines add up to the payment
+        expect(lines.reduce((total, line) => total + line.amount, 0)).toBe(payment.price);
+    });
+    test('a month the legacy invoicer billed is never billed again', async () => {
+        const { organization, stripeAccount } = await init();
+        // A legacy payment without balance items: the inline linking can't reach it, so the fee
+        // stays uninvoiced and the invoicer may not bill it either
+        const legacy = new Payment();
+        legacy.organizationId = membershipOrganization.id;
+        legacy.payingOrganizationId = organization.id;
+        legacy.stripeAccountId = stripeAccount.id;
+        legacy.method = PaymentMethod.AccountDeductions;
+        legacy.provider = PaymentProvider.Stripe;
+        legacy.status = PaymentStatus.Succeeded;
+        legacy.reference = LEGACY_FEE_PAYMENT_REFERENCE_PREFIX + '2024-07-01';
+        legacy.price = 30_00;
+        legacy.paidAt = occurredAt;
+        await legacy.save();
+        const fee = await createFee(organization, stripeAccount, { amount: 30_00 });
+        expect(fee.balanceItemId).toBeNull();
+        await invoiceMonth();
+        expect(await getFeePayments(organization)).toHaveLength(0);
+        expect((await ApplicationFee.getByID(fee.id))!.balanceItemId).toBeNull();
+    });
+    test('fees of the current month are not billed yet', async () => {
+        const { organization, stripeAccount } = await init();
+        const now = new Date();
+        await createFee(organization, stripeAccount, { when: new Date(now.getFullYear(), now.getMonth(), 1, 12) });
+        await createInvoicer().generateInvoices(membershipOrganization);
+        const payments = await Payment.select()
+            .where('payingOrganizationId', organization.id)
+            .where('method', PaymentMethod.AccountDeductions)
+            .fetch();
+        expect(payments).toHaveLength(0);
+    });
+    test('a broken account does not block the other accounts', async () => {
+        const { organization, stripeAccount } = await init();
+        const broken = await stripeMocker.createStripeAccount(organization.id);
+        await createFee(organization, stripeAccount, { amount: 30_00 });
+        await createFee(organization, broken, { amount: 40_00 });
+        // A month the legacy invoicer billed may never be billed again: that group throws
+        const legacy = new Payment();
+        legacy.organizationId = membershipOrganization.id;
+        legacy.payingOrganizationId = organization.id;
+        legacy.stripeAccountId = broken.id;
+        legacy.method = PaymentMethod.AccountDeductions;
+        legacy.provider = PaymentProvider.Stripe;
+        legacy.status = PaymentStatus.Succeeded;
+        legacy.reference = LEGACY_FEE_PAYMENT_REFERENCE_PREFIX + '2024-07-01';
+        legacy.price = 40_00;
+        legacy.paidAt = occurredAt;
+        await legacy.save();
+        await invoiceMonth();
+        const payments = await getFeePayments(organization);
+        expect(payments).toHaveLength(1);
+        expect(payments[0].price).toBe(30_00);
+    });
+    test('fees without the Stripe account they were deducted from are skipped, not retried forever', async () => {
+        const { organization, stripeAccount } = await init();
+        const removed = await stripeMocker.createStripeAccount(organization.id);
+        await createFee(organization, stripeAccount, { amount: 30_00 });
+        const orphaned = await createFee(organization, removed, { amount: 40_00 });
+        // Deleting the account row clears payingStripeAccountId: that fee can no longer be checked
+        // against what the legacy invoicer billed per account, so it is not billed at all
+        await removed.delete();
+        await WebmasterReport.group('Overslaan applicatiekosten', async () => {
+            await invoiceMonth();
+        });
+        const payments = await getFeePayments(organization);
+        expect(payments).toHaveLength(1);
+        expect(payments[0].price).toBe(30_00);
+        expect((await ApplicationFee.getByID(orphaned.id))!.balanceItemId).toBeNull();
+        // Skipping is silent here: the sync that stored the fee already reported it, and this run
+        // repeats every night
+        const emails = (await EmailMocker.transactional.getSucceededEmails()).filter(e => e.subject.startsWith('Overslaan applicatiekosten'));
+        expect(emails).toHaveLength(0);
+    });
+    test('charges of a billed fee keep pointing at the deduction row', async () => {
+        const { organization, stripeAccount } = await init();
+        const fee = await createFee(organization, stripeAccount);
+        await invoiceMonth();
+        const charge = await SettlementCharge.getByID(fee.settlementChargeId!);
+        expect(charge).toBeDefined();
+        expect(charge!.amount).toBe(-30_00);
+    });
+    test('fees of a deleted organization are never billed, and do not block the other accounts', async () => {
+        const { organization, stripeAccount } = await init();
+        const { organization: other, stripeAccount: otherAccount } = await init();
+        const orphaned = await createFee(organization, stripeAccount, { amount: 30_00 });
+        await createFee(other, otherAccount, { amount: 40_00 });
+        // Takes the Stripe account and the deduction charge with it, but not our income
+        await organization.delete();
+        await invoiceMonth();
+        const payments = await getFeePayments(other);
+        expect(payments).toHaveLength(1);
+        expect(payments[0].price).toBe(40_00);
+        const stored = await ApplicationFee.getByID(orphaned.id);
+        expect(stored).toBeDefined();
+        expect(stored!.payingOrganizationId).toBeNull();
+        expect(stored!.settlementChargeId).toBeNull();
+        expect(stored!.balanceItemId).toBeNull();
+    });
+});