npm - @stamhoofd/backend - Versions diffs - 2.129.3 → 2.131.0 - Mend

@stamhoofd/backend 2.129.3 → 2.131.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 (43) hide show

package/src/endpoints/organization/dashboard/stripe/StripePayoutsExportEndpoint.ts ADDED Viewed

@@ -0,0 +1,125 @@
+import type { Decoder } from '@simonbackx/simple-encoding';
+import { AutoEncoder, DateDecoder, field, IntegerDecoder } 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 { Context } from '../../../../helpers/Context.js';
+import { StripePayoutReporter } from '../../../../helpers/StripePayoutReporter.js';
+export class PayoutExportStatus extends AutoEncoder {
+    @field({ decoder: DateDecoder })
+    start: Date;
+    @field({ decoder: DateDecoder })
+    end: Date;
+    @field({ decoder: IntegerDecoder })
+    count = 0;
+}
+type Params = Record<string, never>;
+class Body extends AutoEncoder {
+    @field({ decoder: DateDecoder })
+    start: Date;
+    @field({ decoder: DateDecoder })
+    end: Date;
+}
+type Query = undefined;
+type ResponseBody = undefined;
+/**
+ * Manually build a Stripe payout report for a given period and email it (to check whether
+ * everything we charged via Stripe application fees was invoiced correctly).
+ */
+export class StripePayoutsExportEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    bodyDecoder = Body as Decoder<Body>;
+    static queue: PayoutExportStatus[] = [];
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'POST') {
+            return [false];
+        }
+        const params = Endpoint.parseParameters(request.url, '/stripe/payouts', {});
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+    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: 'Stripe payout exports are only available for the platform membership organization',
+                statusCode: 400,
+            });
+        }
+        return { organization, user };
+    }
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        const { organization, user } = await StripePayoutsExportEndpoint.authenticate();
+        if (!STAMHOOFD.STRIPE_SECRET_KEY) {
+            throw new SimpleError({
+                code: 'not_configured',
+                message: 'Stripe is not configured',
+                statusCode: 400,
+            });
+        }
+        const secretKey = STAMHOOFD.STRIPE_SECRET_KEY;
+        const start = request.body.start;
+        const end = request.body.end;
+        const item = PayoutExportStatus.create({
+            start,
+            end,
+            count: 0,
+        });
+        StripePayoutsExportEndpoint.queue.push(item);
+        // Schedule
+        QueueHandler.schedule('stripe-payout-export', async () => {
+            try {
+                const reporter = new StripePayoutReporter({
+                    secretKey,
+                    sellingOrganization: organization,
+                });
+                let count = 0;
+                reporter.callback = () => {
+                    count++;
+                    item.count = count;
+                };
+                await reporter.build(start, end);
+                // Send the report to the user that requested it
+                await reporter.sendEmail({
+                    to: [{ email: user.email, name: user.name }],
+                });
+            } finally {
+                // Remove from queue
+                StripePayoutsExportEndpoint.queue.splice(StripePayoutsExportEndpoint.queue.indexOf(item), 1);
+            }
+        }).catch(console.error);
+        return new Response(undefined);
+    }
+}

package/src/helpers/AuthenticatedStructures.ts CHANGED Viewed

@@ -514,6 +514,9 @@ export class AuthenticatedStructures {
         }
         for (const member of members) {
+            if (member.organizationId) {
+                organizationIds.push(member.organizationId);
+            }
             for (const registration of member.registrations) {
                 organizationIds.push(registration.organizationId);
             }
@@ -620,14 +623,8 @@ export class AuthenticatedStructures {
                 group: Group;
             })[] = [];
             const userManager = Context.auth.isUserManager(member);
             for (const registration of member.registrations) {
-                if (includeContextOrganization || registration.organizationId !== Context.auth.organization?.id) {
-                    const found = organizations.get(registration.id);
-                    if (!found) {
-                        const organization = await Context.auth.getOrganization(registration.organizationId);
-                        organizations.set(organization.id, organization);
-                    }
-                }
                 if (organizations.get(registration.organizationId)?.active || (Context.auth.organization && Context.auth.organization.active && registration.organizationId === Context.auth.organization.id) || await Context.auth.hasFullAccess(registration.organizationId)) {
                     if (
                         !!options?.forAdminCartCalculation
@@ -639,6 +636,7 @@ export class AuthenticatedStructures {
                     }
                 }
             }
             member.registrations = filtered;
             const balancesPermission = (!!options?.forAdminCartCalculation) || await Context.auth.hasFinancialMemberAccess(member, PermissionLevel.Read, Context.organization?.id);

package/src/helpers/MembershipCharger.ts CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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;
+    }
+}