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

@stamhoofd/backend 2.140.0 → 2.141.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 (61) hide show

package/package.json +17 -17
package/src/crons/fake-settlements.test.ts +129 -8
package/src/crons/fake-settlements.ts +256 -9
package/src/crons/index.ts +1 -1
package/src/crons/invoices.ts +13 -8
package/src/crons/settlement-sync.test.ts +39 -0
package/src/crons/settlement-sync.ts +109 -0
package/src/crons/stripe-invoices.ts +19 -13
package/src/crons.ts +1 -5
package/src/endpoints/organization/dashboard/balance-items/GetBalanceItemBreakdownEndpoint.test.ts +4 -4
package/src/endpoints/organization/dashboard/mollie/ConnectMollieEndpoint.ts +2 -2
package/src/endpoints/organization/dashboard/organization/PatchOrganizationEndpoint.ts +1 -1
package/src/endpoints/organization/dashboard/payments/GetPaymentBreakdownEndpoint.test.ts +3 -3
package/src/endpoints/organization/dashboard/payments/GetPaymentsEndpoint.test.ts +150 -2
package/src/endpoints/organization/dashboard/{stripe/GetStripePayoutsExportStatusEndpoint.ts → settlements/GetSettlementsSyncStatusEndpoint.ts} +9 -7
package/src/endpoints/organization/dashboard/settlements/SettlementsExportEndpoint.test.ts +157 -0
package/src/endpoints/organization/dashboard/settlements/SettlementsExportEndpoint.ts +140 -0
package/src/endpoints/organization/dashboard/settlements/SettlementsSyncEndpoint.test.ts +110 -0
package/src/endpoints/organization/dashboard/settlements/SettlementsSyncEndpoint.ts +104 -0
package/src/excel-loaders/payments.ts +18 -1
package/src/helpers/ApplicationFeeDetails.ts +66 -0
package/src/helpers/ApplicationFeeInvoicer.test.ts +285 -0
package/src/helpers/ApplicationFeeInvoicer.ts +419 -0
package/src/helpers/AuthenticatedStructures.ts +14 -1
package/src/helpers/MollieSettlementSync.test.ts +361 -0
package/src/helpers/MollieSettlementSync.ts +323 -0
package/src/helpers/MollieSettlementSyncRunner.ts +53 -0
package/src/helpers/ProviderSettlementSyncRunner.ts +37 -0
package/src/helpers/SettlementExporter.test.ts +366 -0
package/src/helpers/SettlementExporter.ts +583 -0
package/src/helpers/SettlementSyncRunner.test.ts +165 -0
package/src/helpers/SettlementSyncRunner.ts +64 -0
package/src/helpers/StripeHelper.ts +2 -1
package/src/helpers/StripeSettlementSync.test.ts +828 -0
package/src/helpers/StripeSettlementSync.ts +947 -0
package/src/helpers/StripeSettlementSyncRunner.test.ts +66 -0
package/src/helpers/StripeSettlementSyncRunner.ts +152 -0
package/src/helpers/WebmasterReport.test.ts +109 -0
package/src/helpers/WebmasterReport.ts +115 -0
package/src/helpers/getPaymentIdForStripeCharge.test.ts +91 -0
package/src/helpers/getPaymentIdForStripeCharge.ts +71 -0
package/src/services/ApplicationFeeService.test.ts +256 -0
package/src/services/ApplicationFeeService.ts +283 -0
package/src/services/InvoiceService.ts +18 -1
package/src/services/SettlementService.test.ts +559 -0
package/src/services/SettlementService.ts +607 -0
package/src/sql-filters/payment-settlement.test.ts +2 -2
package/src/sql-filters/payments.ts +73 -0
package/tests/helpers/MollieMocker.ts +64 -6
package/tests/helpers/StripeMocker.ts +209 -17
package/src/crons/stripe-payout-reports.ts +0 -69
package/src/endpoints/organization/dashboard/stripe/StripePayoutsExportEndpoint.test.ts +0 -103
package/src/endpoints/organization/dashboard/stripe/StripePayoutsExportEndpoint.ts +0 -125
package/src/helpers/CheckSettlements.test.ts +0 -190
package/src/helpers/CheckSettlements.ts +0 -237
package/src/helpers/StripeInvoicer.ts +0 -419
package/src/helpers/StripePayoutChecker.ts +0 -193
package/src/helpers/StripePayoutExportData.ts +0 -195
package/src/helpers/StripePayoutExportExcel.ts +0 -280
package/src/helpers/StripePayoutReporter.test.ts +0 -419
package/src/helpers/StripePayoutReporter.ts +0 -585

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

@@ -0,0 +1,140 @@
+import type { Decoder } from '@simonbackx/simple-encoding';
+import { AutoEncoder, 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 { Email } from '@stamhoofd/email';
+import { Organization, Platform } from '@stamhoofd/models';
+import { QueueHandler } from '@stamhoofd/queues';
+import { PaymentProvider } from '@stamhoofd/structures';
+import { Formatter } from '@stamhoofd/utility';
+import { Context } from '../../../../helpers/Context.js';
+import { SettlementExporter } from '../../../../helpers/SettlementExporter.js';
+/**
+ * payment_settlements grows like payments, so an export can't span an unbounded range.
+ */
+const MAXIMUM_RANGE_MS = 1100 * 24 * 60 * 60 * 1000;
+type Params = Record<string, never>;
+class Body extends AutoEncoder {
+    @field({ decoder: DateDecoder })
+    start: Date;
+    @field({ decoder: DateDecoder })
+    end: Date;
+    @field({ decoder: new EnumDecoder(PaymentProvider), nullable: true, optional: true })
+    provider: PaymentProvider | null = null;
+}
+type Query = undefined;
+type ResponseBody = undefined;
+/**
+ * Build the settlements reconciliation report (from the stored tables only, no provider API calls)
+ * and email it to the requesting admin.
+ *
+ * An export always covers exactly the payouts of the organization in context, for any finance
+ * admin of that organization. The platform's own payouts belong to the membership organization, so
+ * platform admins export those by scoping to the membership organization like any other.
+ */
+export class SettlementsExportEndpoint extends Endpoint<Params, Query, Body, ResponseBody> {
+    bodyDecoder = Body as Decoder<Body>;
+    protected doesMatch(request: Request): [true, Params] | [false] {
+        if (request.method !== 'POST') {
+            return [false];
+        }
+        const params = Endpoint.parseParameters(request.url, '/settlements/export', {});
+        if (params) {
+            return [true, params as Params];
+        }
+        return [false];
+    }
+    static async authenticate() {
+        const organization = await Context.setOrganizationScope();
+        const { user } = await Context.authenticate();
+        if (!await Context.auth.canManageFinances(organization.id)) {
+            throw Context.auth.error();
+        }
+        const platform = await Platform.getSharedStruct();
+        const enabled = platform.config.featureFlags.includes('settlements')
+            || organization.privateMeta.featureFlags.includes('settlements');
+        if (!enabled) {
+            throw new SimpleError({
+                code: 'not_available',
+                message: 'Settlements are not enabled for this organization',
+                statusCode: 400,
+            });
+        }
+        return { organization, user, platform };
+    }
+    async handle(request: DecodedRequest<Params, Query, Body>) {
+        const { organization, user, platform } = await SettlementsExportEndpoint.authenticate();
+        const { start, end, provider } = request.body;
+        if (end.getTime() < start.getTime()) {
+            throw new SimpleError({
+                code: 'invalid_range',
+                message: 'The export ends before it starts',
+                statusCode: 400,
+            });
+        }
+        if (end.getTime() - start.getTime() > MAXIMUM_RANGE_MS) {
+            throw new SimpleError({
+                code: 'range_too_large',
+                message: 'The requested export range is too large',
+                statusCode: 400,
+            });
+        }
+        // The membership organization sells the platform's fee invoices
+        const membershipOrganization = platform.membershipOrganizationId ? await Organization.getByID(platform.membershipOrganizationId) : null;
+        if (!membershipOrganization) {
+            throw new SimpleError({
+                code: 'missing_membership_organization',
+                message: 'Platform has no membership organization configured',
+                statusCode: 400,
+            });
+        }
+        // Serialized so concurrent exports can't compete for memory; the result arrives by email
+        QueueHandler.schedule('settlements-export', async () => {
+            const exporter = new SettlementExporter({
+                start,
+                end,
+                provider,
+                organization,
+                sellingOrganization: membershipOrganization,
+            });
+            await exporter.sendEmail({
+                to: [{ email: user.email, name: user.name }],
+            });
+        }).catch((e) => {
+            // The request already returned: without this the export just never arrives
+            console.error('Settlements export failed', e);
+            Email.send({
+                from: Email.getWebmasterFromEmail(),
+                to: [{ email: user.email, name: user.name }],
+                subject: 'Uitbetalingen export mislukt',
+                text: 'Het maken van de export van ' + Formatter.dateTime(start) + ' tot ' + Formatter.dateTime(end) + ' is mislukt. Probeer een kortere periode of neem contact op.\n',
+                type: 'transactional',
+            });
+        });
+        return new Response(undefined);
+    }
+}

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

@@ -0,0 +1,110 @@
+import { Request } from '@simonbackx/simple-endpoints';
+import type { Organization, Token, User } from '@stamhoofd/models';
+import { OrganizationFactory, Payment, Token as TokenModel, UserFactory } from '@stamhoofd/models';
+import { Settlement } from '@stamhoofd/models/models/Settlement.js';
+import { QueueHandler } from '@stamhoofd/queues';
+import { PaymentMethod, PaymentProvider, PaymentStatus } from '@stamhoofd/structures';
+import { STExpect } from '@stamhoofd/test-utils';
+import { StripeMocker } from '../../../../../tests/helpers/StripeMocker.js';
+import { testServer } from '../../../../../tests/helpers/TestServer.js';
+import { initMembershipOrganization } from '../../../../../tests/init/initMembershipOrganization.js';
+import { initPlatformAdmin } from '../../../../../tests/init/initPlatformAdmin.js';
+import { GetSettlementsSyncStatusEndpoint } from './GetSettlementsSyncStatusEndpoint.js';
+import { SettlementsSyncEndpoint } from './SettlementsSyncEndpoint.js';
+describe('Endpoint.SettlementsSync', () => {
+    const endpoint = new SettlementsSyncEndpoint();
+    const statusEndpoint = new GetSettlementsSyncStatusEndpoint();
+    const stripeMocker = new StripeMocker();
+    let membershipOrganization: Organization;
+    let admin: User;
+    let adminToken: Token;
+    beforeAll(async () => {
+        membershipOrganization = await initMembershipOrganization();
+        ({ admin, adminToken } = await initPlatformAdmin());
+        stripeMocker.start();
+    });
+    afterAll(() => {
+        stripeMocker.stop();
+    });
+    beforeEach(() => {
+        stripeMocker.clear();
+    });
+    const post = async (organization: Organization, token: Token, body: Record<string, unknown> = {}) => {
+        const request = Request.buildJson('POST', '/settlements/sync', organization.getApiHost(), {
+            start: new Date(2026, 0, 1).getTime(),
+            end: new Date(2026, 0, 31).getTime(),
+            providers: [PaymentProvider.Stripe],
+            ...body,
+        });
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test(endpoint, request);
+    };
+    const getStatus = async (organization: Organization, token: Token) => {
+        const request = Request.buildJson('GET', '/settlements/sync/status', organization.getApiHost());
+        request.headers.authorization = 'Bearer ' + token.accessToken;
+        return await testServer.test(statusEndpoint, request);
+    };
+    test('A platform admin can run the sync, which stores the payouts', async () => {
+        // A payment on our own platform account: a connected organization's payment only passes
+        // through our balance and is settled by its own payout
+        const payment = new Payment();
+        payment.organizationId = membershipOrganization.id;
+        payment.method = PaymentMethod.Bancontact;
+        payment.provider = PaymentProvider.Stripe;
+        payment.status = PaymentStatus.Succeeded;
+        payment.price = 100_00_00;
+        payment.paidAt = new Date(2026, 0, 15);
+        await payment.save();
+        const payout = stripeMocker.createPayout({ amount: 10000, arrivalDate: new Date(2026, 0, 20) });
+        stripeMocker.createBalanceTransaction({
+            type: 'charge',
+            amount: 10000,
+            created: new Date(2026, 0, 15),
+            payout: payout.id,
+            source: stripeMocker.createChargeObject({ metadata: { payment: payment.id } }),
+        });
+        const response = await post(membershipOrganization, adminToken);
+        expect(response.status).toBe(200);
+        await QueueHandler.awaitAll();
+        const settlement = await Settlement.select().where('externalId', payout.id).first(true);
+        expect(settlement.syncedAt).not.toBeNull();
+        expect(settlement.unexplainedAmount).toBe(0);
+        // The queue is empty again
+        const statusResponse = await getStatus(membershipOrganization, adminToken);
+        expect(statusResponse.body).toEqual([]);
+    });
+    test('A user without platform full access cannot run the sync', async () => {
+        const user = await new UserFactory({ organization: membershipOrganization }).create();
+        const token = await TokenModel.createToken(user);
+        await expect(post(membershipOrganization, token)).rejects.toThrow(
+            STExpect.simpleError({ code: 'permission_denied' }),
+        );
+        await expect(getStatus(membershipOrganization, token)).rejects.toThrow(
+            STExpect.simpleError({ code: 'permission_denied' }),
+        );
+    });
+    test('The sync is not available for other organizations', async () => {
+        const otherOrganization = await new OrganizationFactory({}).create();
+        await expect(post(otherOrganization, adminToken)).rejects.toThrow(
+            STExpect.simpleError({ code: 'not_available' }),
+        );
+    });
+});

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),
+        });
+    }
+}