@stamhoofd/backend 2.130.0 → 2.132.0

package/src/helpers/CheckSettlements.ts

@@ -16,7 +16,11 @@ type MollieSettlement = {
     };
 };
 
-type MolliePaymentJSON = {
+/**
+ * Both payments (tr_...) and refunds (re_...) settled in a settlement are matched to a local
+ * payment through the mollieId of their MolliePayment link, so we only need their id here.
+ */
+type MollieSettlementEntryJSON = {
     id: string;
 };
 
@@ -146,64 +150,88 @@ export async function checkMollieSettlementsFor(token: string, checkAll = false)
     }
 }
 
-async function updateSettlement(token: string, settlement: MollieSettlement, fromPaymentId?: string) {
+async function updateSettlement(token: string, settlement: MollieSettlement) {
+    // Regular payments settled in this settlement
+    await updateSettlementResource(token, settlement, 'payments');
+
+    // Refunds settled in this settlement. These are negative entries linked to a refund payment
+    // (created by the mollie-refunds cron), so we can set their settlement metadata too.
+    await updateSettlementResource(token, settlement, 'refunds');
+
+    // Chargebacks settled in this settlement. Like refunds, these are negative entries linked to a
+    // chargeback payment (created by the mollie-chargebacks cron).
+    await updateSettlementResource(token, settlement, 'chargebacks');
+}
+
+/**
+ * Loop over all entries (payments, refunds or chargebacks) that are part of a settlement and set the
+ * settlement metadata on the matching local payment. Every resource exposes its entries under
+ * `_embedded[resource]` and uses the same pagination, so they share this logic.
+ */
+async function updateSettlementResource(token: string, settlement: MollieSettlement, resource: 'payments' | 'refunds' | 'chargebacks', fromId?: string) {
     const limit = 250;
 
-    // Loop all payments of this settlement
-    const request = await axios.get('https://api.mollie.com/v2/settlements/' + settlement.id + '/payments?limit=' + limit + (fromPaymentId ? ('&from=' + encodeURIComponent(fromPaymentId)) : ''), {
+    const request = await axios.get('https://api.mollie.com/v2/settlements/' + settlement.id + '/' + resource + '?limit=' + limit + (fromId ? ('&from=' + encodeURIComponent(fromId)) : ''), {
         headers: {
             Authorization: 'Bearer ' + token,
         },
     });
 
     if (request.status === 200) {
-        const molliePayments = request.data._embedded.payments as MolliePaymentJSON[];
-
-        for (const mollie of molliePayments) {
-            // Search payment
-            const mps = await MolliePayment.where({ mollieId: mollie.id });
-            if (mps.length == 1) {
-                const mp = mps[0];
-                const payment = await Payment.getByID(mp.paymentId);
-                if (payment) {
-                    payment.settlement = Settlement.create({
-                        id: settlement.id,
-                        reference: settlement.reference,
-                        settledAt: new Date(settlement.settledAt),
-                        amount: Math.round(parseFloat(settlement.amount.value) * 100) * 100,
-                    });
-                    const saved = await payment.save();
-
-                    if (saved) {
-                        // Mark order as 'updated', or the frontend won't pull in the updates
-                        const order = await Order.getForPayment(null, payment.id);
-                        if (order) {
-                            order.updatedAt = new Date();
-                            order.forceSaveProperty('updatedAt');
-                            await order.save();
-                        }
-
-                        // TODO: Mark registrations as 'saved'
-                    }
+        const entries = request.data._embedded[resource] as MollieSettlementEntryJSON[];
 
-                    if (STAMHOOFD.environment === 'development') {
-                        console.log('Updated settlement of payment ' + payment.id);
-                        console.log(payment.settlement);
-                    }
-                } else {
-                    console.log('Missing payment ' + mp.paymentId);
-                }
-            } else {
-                // Probably a payment in a different system/platform
-                // console.log("No mollie payment found for id "+mollie.id)
-            }
+        for (const entry of entries) {
+            await applySettlementToPayment(settlement, entry.id);
         }
 
         // Check next page
-        if (request.data._links.next) {
-            await updateSettlement(token, settlement, molliePayments[molliePayments.length - 1].id);
+        if (request.data._links.next && entries.length > 0) {
+            await updateSettlementResource(token, settlement, resource, entries[entries.length - 1].id);
         }
     } else {
         console.error(request.data);
     }
 }
+
+/**
+ * Find the local payment linked to a Mollie payment or refund id and store the settlement metadata.
+ */
+async function applySettlementToPayment(settlement: MollieSettlement, mollieId: string) {
+    // Search payment
+    const mps = await MolliePayment.where({ mollieId });
+    if (mps.length === 1) {
+        const mp = mps[0];
+        const payment = await Payment.getByID(mp.paymentId);
+        if (payment) {
+            payment.settlement = Settlement.create({
+                id: settlement.id,
+                reference: settlement.reference,
+                settledAt: new Date(settlement.settledAt),
+                amount: Math.round(parseFloat(settlement.amount.value) * 100) * 100,
+            });
+            const saved = await payment.save();
+
+            if (saved) {
+                // Mark order as 'updated', or the frontend won't pull in the updates
+                const order = await Order.getForPayment(null, payment.id);
+                if (order) {
+                    order.updatedAt = new Date();
+                    order.forceSaveProperty('updatedAt');
+                    await order.save();
+                }
+
+                // TODO: Mark registrations as 'saved'
+            }
+
+            if (STAMHOOFD.environment === 'development') {
+                console.log('Updated settlement of payment ' + payment.id);
+                console.log(payment.settlement);
+            }
+        } else {
+            console.log('Missing payment ' + mp.paymentId);
+        }
+    } else {
+        // Probably a payment in a different system/platform
+        // console.log("No mollie payment found for id "+mollieId)
+    }
+}

package/src/helpers/MembershipCharger.ts

@@ -1,5 +1,5 @@
 import { SimpleError } from '@simonbackx/simple-errors';
-import { BalanceItem, Member, MemberPlatformMembership, Platform } from '@stamhoofd/models';
+import { BalanceItem, Member, MemberPlatformMembership, Platform, RegistrationPeriod } from '@stamhoofd/models';
 import { SQL, SQLOrderBy, SQLWhereSign } from '@stamhoofd/sql';
 import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, TranslatedString } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
@@ -25,6 +25,25 @@ export const MembershipCharger = {
             return platform.config.membershipTypes.find(t => t.id === id);
         }
 
+        // Cache the registration period relation per periodId, so we only load each period once.
+        const periodRelationCache = new Map<string, BalanceItemRelation | null>();
+        async function getPeriodRelation(periodId: string): Promise<BalanceItemRelation | null> {
+            if (periodRelationCache.has(periodId)) {
+                return periodRelationCache.get(periodId)!;
+            }
+
+            const period = await RegistrationPeriod.getByID(periodId);
+            const relation = period
+                ? BalanceItemRelation.create({
+                        id: period.id,
+                        name: new TranslatedString(period.getBaseStructure().name),
+                    })
+                : null;
+
+            periodRelationCache.set(periodId, relation);
+            return relation;
+        }
+
         let createdCount = 0;
         let createdPrice = 0;
         const chunkSize = 100;
@@ -114,6 +133,12 @@ export const MembershipCharger = {
                     ],
                 ]);
 
+                // Add the registration period (working year) relation so it is visible in the item description.
+                const periodRelation = await getPeriodRelation(membership.periodId);
+                if (periodRelation) {
+                    balanceItem.relations.set(BalanceItemRelationType.RegistrationPeriod, periodRelation);
+                }
+
                 balanceItem.type = BalanceItemType.PlatformMembership;
                 balanceItem.organizationId = chargeVia;
                 balanceItem.payingOrganizationId = membership.organizationId;

package/src/helpers/RegistrationPeriodRelationBackfiller.test.ts

@@ -0,0 +1,111 @@
+import type { RegistrationPeriod } from '@stamhoofd/models';
+import { BalanceItem, BalanceItemFactory, GroupFactory, MemberFactory, MemberPlatformMembership, OrganizationFactory, OrganizationRegistrationPeriodFactory, RegistrationFactory, RegistrationPeriodFactory } from '@stamhoofd/models';
+import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, TranslatedString } from '@stamhoofd/structures';
+import { TestUtils } from '@stamhoofd/test-utils';
+import { v4 as uuidv4 } from 'uuid';
+import { backfillRegistrationPeriodRelations } from './RegistrationPeriodRelationBackfiller.js';
+
+describe('helper.RegistrationPeriodRelationBackfiller', () => {
+    let period: RegistrationPeriod;
+
+    beforeAll(async () => {
+        period = await new RegistrationPeriodFactory({
+            startDate: new Date(2024, 0, 1),
+            endDate: new Date(2025, 11, 31),
+        }).create();
+
+        // A deterministic name so we can assert on it.
+        period.customName = 'Werkjaar 2024-2025';
+        await period.save();
+    });
+
+    beforeEach(() => {
+        TestUtils.setEnvironment('userMode', 'platform');
+    });
+
+    it('fills the registration period relation for registration balance items', async () => {
+        const organization = await new OrganizationFactory({ period }).create();
+        await new OrganizationRegistrationPeriodFactory({ organization, period }).create();
+
+        const member = await new MemberFactory({ organization }).create();
+        const group = await new GroupFactory({ organization, period }).create();
+        const registration = await new RegistrationFactory({ member, group }).create();
+
+        const balanceItem = await new BalanceItemFactory({
+            organizationId: organization.id,
+            memberId: member.id,
+            registrationId: registration.id,
+            type: BalanceItemType.Registration,
+            amount: 1,
+            unitPrice: 25_00,
+        }).create();
+
+        expect(balanceItem.relations.has(BalanceItemRelationType.RegistrationPeriod)).toBe(false);
+
+        await backfillRegistrationPeriodRelations();
+
+        const updated = await BalanceItem.getByID(balanceItem.id);
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)).toMatchObject({ id: period.id });
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)?.name.toString()).toBe('Werkjaar 2024-2025');
+    });
+
+    it('fills the registration period relation for platform membership balance items', async () => {
+        const organization = await new OrganizationFactory({ period }).create();
+        const member = await new MemberFactory({ organization }).create();
+
+        const balanceItem = await new BalanceItemFactory({
+            organizationId: organization.id,
+            memberId: member.id,
+            type: BalanceItemType.PlatformMembership,
+            amount: 1,
+            unitPrice: 15_00,
+        }).create();
+
+        const membership = new MemberPlatformMembership();
+        membership.memberId = member.id;
+        membership.membershipTypeId = uuidv4();
+        membership.organizationId = organization.id;
+        membership.periodId = period.id;
+        membership.startDate = new Date(2024, 0, 1);
+        membership.endDate = new Date(2025, 11, 31);
+        membership.balanceItemId = balanceItem.id;
+        await membership.save();
+
+        await backfillRegistrationPeriodRelations();
+
+        const updated = await BalanceItem.getByID(balanceItem.id);
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)).toMatchObject({ id: period.id });
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)?.name.toString()).toBe('Werkjaar 2024-2025');
+    });
+
+    it('does not overwrite an existing registration period relation', async () => {
+        const organization = await new OrganizationFactory({ period }).create();
+        await new OrganizationRegistrationPeriodFactory({ organization, period }).create();
+
+        const member = await new MemberFactory({ organization }).create();
+        const group = await new GroupFactory({ organization, period }).create();
+        const registration = await new RegistrationFactory({ member, group }).create();
+
+        const existingRelations = new Map([
+            [
+                BalanceItemRelationType.RegistrationPeriod,
+                BalanceItemRelation.create({ id: period.id, name: new TranslatedString('Custom period name') }),
+            ],
+        ]);
+
+        const balanceItem = await new BalanceItemFactory({
+            organizationId: organization.id,
+            memberId: member.id,
+            registrationId: registration.id,
+            type: BalanceItemType.Registration,
+            amount: 1,
+            unitPrice: 25_00,
+            relations: existingRelations,
+        }).create();
+
+        await backfillRegistrationPeriodRelations();
+
+        const updated = await BalanceItem.getByID(balanceItem.id);
+        expect(updated?.relations.get(BalanceItemRelationType.RegistrationPeriod)?.name.toString()).toBe('Custom period name');
+    });
+});

package/src/helpers/RegistrationPeriodRelationBackfiller.ts

@@ -0,0 +1,125 @@
+import { BalanceItem, MemberPlatformMembership, Registration, RegistrationPeriod } from '@stamhoofd/models';
+import { BalanceItemRelation, BalanceItemRelationType, BalanceItemType, TranslatedString } from '@stamhoofd/structures';
+import { Formatter } from '@stamhoofd/utility';
+import { SeedTools } from './SeedTools.js';
+
+/**
+ * Backfills the `RegistrationPeriod` relation on existing balance items.
+ *
+ * The relation contains the name of the registration period (working year) connected to a registration
+ * (or its options / bundle discount) and to a platform membership. It was added after these balance items
+ * were created, so we reconstruct it from the linked registration or membership.
+ *
+ * Only balance items that don't have the relation yet are touched, so the migration is idempotent and never
+ * overwrites relations that were already set by the current flows.
+ */
+
+/**
+ * Loads the registration period relation once per periodId.
+ */
+class PeriodRelationCache {
+    private cache = new Map<string, BalanceItemRelation | null>();
+
+    async get(periodId: string): Promise<BalanceItemRelation | null> {
+        if (this.cache.has(periodId)) {
+            return this.cache.get(periodId)!;
+        }
+
+        const period = await RegistrationPeriod.getByID(periodId);
+        const relation = period
+            ? BalanceItemRelation.create({
+                    id: period.id,
+                    name: new TranslatedString(period.getBaseStructure().name),
+                })
+            : null;
+
+        this.cache.set(periodId, relation);
+        return relation;
+    }
+}
+
+async function backfillRegistrationBalanceItems(cache: PeriodRelationCache): Promise<number> {
+    let updated = 0;
+
+    await SeedTools.loopBatched({
+        batchSize: 100,
+        query: BalanceItem.select().whereNot('registrationId', null),
+        batchAction: async (items: BalanceItem[]) => {
+            const registrationIds = Formatter.uniqueArray(items.map(i => i.registrationId!).filter(id => !!id));
+            const registrations = await Registration.getByIDs(...registrationIds);
+            const registrationMap = new Map(registrations.map(r => [r.id, r]));
+
+            for (const item of items) {
+                // Never overwrite a relation that is already set.
+                if (item.relations.has(BalanceItemRelationType.RegistrationPeriod)) {
+                    continue;
+                }
+
+                const registration = registrationMap.get(item.registrationId!);
+                if (!registration) {
+                    continue;
+                }
+
+                const relation = await cache.get(registration.periodId);
+                if (!relation) {
+                    continue;
+                }
+
+                item.relations.set(BalanceItemRelationType.RegistrationPeriod, relation);
+                await item.save();
+                updated += 1;
+            }
+        },
+    });
+
+    return updated;
+}
+
+async function backfillPlatformMembershipBalanceItems(cache: PeriodRelationCache): Promise<number> {
+    let updated = 0;
+
+    await SeedTools.loopBatched({
+        batchSize: 100,
+        query: BalanceItem.select().where('type', BalanceItemType.PlatformMembership),
+        batchAction: async (items: BalanceItem[]) => {
+            const balanceItemIds = items.map(i => i.id);
+            const memberships = await MemberPlatformMembership.select()
+                .where('balanceItemId', balanceItemIds)
+                .limit(balanceItemIds.length)
+                .fetch();
+            const membershipByBalanceItemId = new Map(memberships.filter(m => m.balanceItemId).map(m => [m.balanceItemId!, m]));
+
+            for (const item of items) {
+                if (item.relations.has(BalanceItemRelationType.RegistrationPeriod)) {
+                    continue;
+                }
+
+                const membership = membershipByBalanceItemId.get(item.id);
+                if (!membership) {
+                    continue;
+                }
+
+                const relation = await cache.get(membership.periodId);
+                if (!relation) {
+                    continue;
+                }
+
+                item.relations.set(BalanceItemRelationType.RegistrationPeriod, relation);
+                await item.save();
+                updated += 1;
+            }
+        },
+    });
+
+    return updated;
+}
+
+export async function backfillRegistrationPeriodRelations(): Promise<{ registrations: number; memberships: number }> {
+    const cache = new PeriodRelationCache();
+    const registrations = await backfillRegistrationBalanceItems(cache);
+    const memberships = await backfillPlatformMembershipBalanceItems(cache);
+
+    console.log(`[RegistrationPeriodRelationBackfiller] Updated ${registrations} registration balance items and ${memberships} platform membership balance items`);
+
+    return { registrations, memberships };
+}

package/src/helpers/StripePayoutExportData.ts

@@ -0,0 +1,195 @@
+import type { Invoice, Payment } from '@stamhoofd/models';
+
+export enum StripePayoutItemType {
+    Invoice = 'Invoice',
+    StripeFees = 'StripeFees',
+    StripeReserved = 'StripeReserved',
+}
+
+export class StripePayoutItemData {
+    name = '';
+    type = StripePayoutItemType.Invoice;
+
+    /**
+     * In platform price units (1/100 cent)
+     */
+    amount = 0;
+    description = '';
+
+    /**
+     * Stripe account id + payment reference: only set for Invoice items, used to group the same
+     * account/month combination across multiple payouts.
+     */
+    accountId: string | null = null;
+    reference: string | null = null;
+
+    /**
+     * Payments created in the database for these application fees (can be uninvoiced)
+     */
+    payments: Payment[] = [];
+
+    /**
+     * Invoices connected to those payments (only invoices with a number)
+     */
+    invoices: Invoice[] = [];
+
+    constructor(data: Partial<StripePayoutItemData>) {
+        Object.assign(this, data);
+    }
+
+    get paymentsTotal() {
+        return this.payments.reduce((total, payment) => total + payment.price, 0);
+    }
+
+    get hasUninvoicedPayments() {
+        return this.payments.some(p => p.invoiceId === null);
+    }
+}
+
+export class StripePayoutData {
+    id: string;
+    amount: number; // in platform price units (1/100 cent)
+    arrivalDate: Date;
+    statementDescriptor: string;
+
+    constructor(data: { id: string; amount: number; arrivalDate: Date; statementDescriptor: string }) {
+        this.id = data.id;
+        this.amount = data.amount;
+        this.arrivalDate = data.arrivalDate;
+        this.statementDescriptor = data.statementDescriptor;
+    }
+}
+
+export class StripePayoutBreakdownData {
+    payout: StripePayoutData;
+    items: StripePayoutItemData[] = [];
+
+    constructor(data: { payout: StripePayoutData; items?: StripePayoutItemData[] }) {
+        this.payout = data.payout;
+        this.items = data.items ?? [];
+    }
+
+    /**
+     * Whether the payout amount matches the sum of the items
+     */
+    get isValid() {
+        return this.payout.amount === this.items.reduce((total, item) => total + item.amount, 0);
+    }
+
+    isComplete(payoutExport: StripePayoutExportData) {
+        for (const item of this.items) {
+            if (item.type !== StripePayoutItemType.Invoice) {
+                continue;
+            }
+
+            if (!payoutExport.isItemComplete(item)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+
+export class StripePayoutExportData {
+    /**
+     * All fetched payouts (we need to fetch more payouts than requested in order to complete all information,
+     * because the fees of a given month might have been paid out in other payouts than the requested ones)
+     */
+    payouts: StripePayoutBreakdownData[] = [];
+
+    start: Date;
+    end: Date;
+
+    constructor(data: { start: Date; end: Date }) {
+        this.start = data.start;
+        this.end = data.end;
+    }
+
+    get includedPayouts() {
+        return this.payouts.filter(p => p.payout.arrivalDate >= this.start && p.payout.arrivalDate <= this.end);
+    }
+
+    /**
+     * All payouts for which all application fees have a matching payment that has been invoiced
+     */
+    get completePayouts() {
+        return this.includedPayouts.filter(p => p.isComplete(this));
+    }
+
+    /**
+     * An item is complete if all application fees for the account + month are covered by
+     * created payments, and all of those payments have been invoiced.
+     */
+    isItemComplete(item: StripePayoutItemData) {
+        if (item.type !== StripePayoutItemType.Invoice) {
+            return true;
+        }
+
+        if (item.payments.length === 0) {
+            return false;
+        }
+
+        if (item.hasUninvoicedPayments || item.invoices.length === 0) {
+            return false;
+        }
+
+        // The sum of the application fees across all fetched payouts should equal the total amount
+        // of the created payments for this account + month
+        const totalAcrossPayouts = this.payouts
+            .flatMap(p => p.items)
+            .filter(i => i.accountId === item.accountId && i.reference === item.reference)
+            .reduce((total, i) => total + i.amount, 0);
+
+        return totalAcrossPayouts === item.paymentsTotal;
+    }
+
+    get totalPaidOut() {
+        return this.completePayouts.reduce((total, payout) => total + payout.payout.amount, 0);
+    }
+
+    get totalStripeFees() {
+        return this.completePayouts.reduce((total, payout) => total + payout.items.filter(i => i.type === StripePayoutItemType.StripeFees).reduce((total, item) => total - item.amount, 0), 0);
+    }
+
+    get totalStripeReserved() {
+        return this.completePayouts.reduce((total, payout) => total + payout.items.filter(i => i.type === StripePayoutItemType.StripeReserved).reduce((total, item) => total - item.amount, 0), 0);
+    }
+
+    get totalInvoices() {
+        return this.completePayouts.reduce((total, payout) => total + payout.items.filter(i => i.type === StripePayoutItemType.Invoice).reduce((total, item) => total + item.amount, 0), 0);
+    }
+
+    get totalVAT() {
+        let VAT = 0;
+        for (const payout of this.completePayouts) {
+            for (const item of payout.items) {
+                if (item.type !== StripePayoutItemType.Invoice) {
+                    continue;
+                }
+
+                const invoiceVAT = item.invoices.reduce((total, invoice) => total + invoice.VATTotalAmount, 0);
+                const invoiceTotal = item.invoices.reduce((total, invoice) => total + invoice.totalWithVAT, 0);
+
+                if (invoiceTotal === 0) {
+                    continue;
+                }
+
+                // Estimate applicable VAT based on the VAT rate of the connected invoices
+                // (an invoice can contain more than only these fees, so we apply the rate, not the absolute amount)
+                VAT += invoiceVAT / invoiceTotal * item.amount;
+            }
+        }
+        return Math.round(VAT);
+    }
+
+    get net() {
+        return this.totalPaidOut - this.totalVAT;
+    }
+
+    get isValid() {
+        return this.totalPaidOut === this.totalInvoices - this.totalStripeFees - this.totalStripeReserved
+            // Aggregate totals can mask payout-level mismatches that cancel each other out
+            && this.includedPayouts.every(p => p.isValid)
+            && this.completePayouts.length === this.includedPayouts.length;
+    }
+}