@stamhoofd/models 2.62.0 → 2.63.0

package/src/models/BalanceItem.ts

@@ -1,5 +1,5 @@
 import { column, Database, Model, SQLResultNamespacedRow } from '@simonbackx/simple-database';
-import { BalanceItemPaymentWithPayment, BalanceItemPaymentWithPrivatePayment, BalanceItemRelation, BalanceItemRelationType, BalanceItemStatus, BalanceItemType, BalanceItemWithPayments, BalanceItemWithPrivatePayments, OrderStatus, Payment as PaymentStruct, PrivatePayment } from '@stamhoofd/structures';
+import { BalanceItem as BalanceItemStruct, BalanceItemPaymentWithPayment, BalanceItemPaymentWithPrivatePayment, BalanceItemRelation, BalanceItemRelationType, BalanceItemStatus, BalanceItemType, BalanceItemWithPayments, BalanceItemWithPrivatePayments, OrderStatus, Payment as PaymentStruct, PrivatePayment } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
 import { v4 as uuidv4 } from 'uuid';
 
@@ -90,8 +90,31 @@ export class BalanceItem extends Model {
     @column({ type: 'integer' })
     pricePending = 0;
 
+    /**
+     * Cached value, for optimizations
+     */
+    @column({
+        type: 'integer',
+        beforeSave: function () {
+            return this.calculatedPriceOpen;
+        },
+        skipUpdate: true,
+    })
+    priceOpen = 0;
+
+    /**
+     * todo: deprecate ('pending' and 'paid') + 'hidden' status and replace with 'due' + 'hidden'
+     * -> maybe add 'due' (due if dueAt is null or <= now), 'hidden' (never due), 'future' (= not due until dueAt - but not possible to pay earlier)
+     */
     @column({ type: 'string' })
-    status = BalanceItemStatus.Pending;
+    status = BalanceItemStatus.Due;
+
+    /**
+     * In case the balance item doesn't have to be paid immediately, we can set a due date.
+     * When the due date is reached, it is set to null and the cached balance is updated.
+     */
+    @column({ type: 'datetime', nullable: true })
+    dueAt: Date | null = null;
 
     @column({
         type: 'datetime', beforeSave(old?: any) {
@@ -119,14 +142,13 @@ export class BalanceItem extends Model {
         return this.unitPrice * this.amount;
     }
 
-    get priceOpen() {
+    get calculatedPriceOpen() {
+        if (this.status !== BalanceItemStatus.Due) {
+            return -this.pricePaid - this.pricePending;
+        }
         return this.price - this.pricePaid - this.pricePending;
     }
 
-    updateStatus() {
-        this.status = (this.pricePaid !== 0 || this.price === 0) && this.pricePaid >= this.price ? BalanceItemStatus.Paid : (this.pricePaid !== 0 ? BalanceItemStatus.Pending : (this.status === BalanceItemStatus.Hidden ? BalanceItemStatus.Hidden : BalanceItemStatus.Pending));
-    }
-
     static async deleteItems(items: BalanceItem[]) {
         // Find depending items
         const dependingItemIds = Formatter.uniqueArray(items.filter(i => !!i.dependingBalanceItemId).map(i => i.dependingBalanceItemId!)).filter(id => !items.some(item => item.id === id));
@@ -137,30 +159,19 @@ export class BalanceItem extends Model {
             items = [...items, ...dependingItems];
         }
 
-        const { balanceItemPayments } = await BalanceItem.loadPayments(items);
-
         // todo: in the future we could automatically delete payments that are not needed anymore and weren't paid yet -> to prevent leaving ghost payments
         // for now, an admin can manually cancel those payments
         let needsUpdate = false;
 
         // Set other items to zero (the balance item payments keep the real price)
         for (const item of items) {
-            needsUpdate = true;
-
-            // Don't change status of items that are already paid or are partially paid
-            // Not using item.paidPrice, since this is cached
-            const bip = balanceItemPayments.filter(p => p.balanceItemId === item.id);
-
-            if (bip.length === 0) {
-                // No payments associated with this item
-                item.status = BalanceItemStatus.Hidden;
-                item.amount = 0;
-                await item.save();
-            }
-            else {
-                item.amount = 0;
-                await item.save();
+            if (item.status !== BalanceItemStatus.Due) {
+                continue;
             }
+
+            needsUpdate = true;
+            item.status = BalanceItemStatus.Canceled;
+            await item.save();
         }
 
         if (needsUpdate) {
@@ -172,7 +183,7 @@ export class BalanceItem extends Model {
         let needsUpdate = false;
         for (const item of items) {
             if (item.status === BalanceItemStatus.Hidden) {
-                item.status = BalanceItemStatus.Pending;
+                item.status = BalanceItemStatus.Due;
                 needsUpdate = true;
                 await item.save();
             }
@@ -225,7 +236,6 @@ export class BalanceItem extends Model {
         console.log('Update outstanding balance for', items.length, 'items');
 
         await BalanceItem.updatePricePaid(items.map(i => i.id));
-        await BalanceItem.updatePricePending(items.map(i => i.id));
 
         // Deprecated: the member balances have moved to CachedBalance
         // Update outstanding amount of related members and registrations
@@ -264,7 +274,7 @@ export class BalanceItem extends Model {
      * Update the outstanding balance of multiple members in one go (or all members)
      */
     static async updatePricePaid(balanceItemIds: string[] | 'all') {
-        if (balanceItemIds !== 'all' && balanceItemIds.length == 0) {
+        if (balanceItemIds !== 'all' && balanceItemIds.length === 0) {
             return;
         }
 
@@ -275,13 +285,13 @@ export class BalanceItem extends Model {
         if (balanceItemIds !== 'all') {
             firstWhere = ` AND balanceItemId IN (?)`;
             params.push(balanceItemIds);
+            params.push(balanceItemIds);
 
             secondWhere = `WHERE balance_items.id IN (?)`;
             params.push(balanceItemIds);
         }
 
-        // Note: we'll never mark a balance item as 'paid' via the database -> because we need to rigger the markPaid function manually, which will call the appropriate functions
-        // this method will set the balance item to paid once, and only call the handlers once
+        // Note: this query only works in MySQL because of the SET assignment behaviour allowing to reference newly set values
         const query = `
         UPDATE
             balance_items
@@ -296,41 +306,7 @@ export class BalanceItem extends Model {
                 payments.status = 'Succeeded'${firstWhere}
             GROUP BY
                 balanceItemId
-            ) i ON i.balanceItemId = balance_items.id 
-        SET balance_items.pricePaid = coalesce(i.price, 0), balance_items.status = (CASE
-            WHEN balance_items.status = '${BalanceItemStatus.Paid}' AND balance_items.pricePaid != 0 AND balance_items.pricePaid >= (balance_items.unitPrice * balance_items.amount) THEN '${BalanceItemStatus.Paid}'
-            WHEN balance_items.pricePaid != 0 THEN '${BalanceItemStatus.Pending}'
-            WHEN balance_items.status = '${BalanceItemStatus.Hidden}' THEN '${BalanceItemStatus.Hidden}'
-            ELSE '${BalanceItemStatus.Pending}'
-        END)
-        ${secondWhere}`;
-
-        await Database.update(query, params);
-    }
-
-    /**
-     * Call this after updating the pricePaid
-     */
-    static async updatePricePending(balanceItemIds: string[] | 'all') {
-        if (balanceItemIds !== 'all' && balanceItemIds.length == 0) {
-            return;
-        }
-
-        const params: any[] = [];
-        let firstWhere = '';
-        let secondWhere = '';
-
-        if (balanceItemIds !== 'all') {
-            firstWhere = ` AND balanceItemId IN (?)`;
-            params.push(balanceItemIds);
-
-            secondWhere = `WHERE balance_items.id IN (?)`;
-            params.push(balanceItemIds);
-        }
-
-        const query = `
-        UPDATE
-            balance_items
+            ) paid ON paid.balanceItemId = balance_items.id
         LEFT JOIN (
             SELECT
                 balanceItemId,
@@ -342,16 +318,25 @@ export class BalanceItem extends Model {
                 payments.status != 'Succeeded' AND payments.status != 'Failed'${firstWhere}
             GROUP BY
                 balanceItemId
-            ) i ON i.balanceItemId = balance_items.id 
-        SET balance_items.pricePending = LEAST(
-            GREATEST(0, balance_items.unitPrice * balance_items.amount - balance_items.pricePaid), 
-            coalesce(i.price, 0)
-        )
+            ) pending ON pending.balanceItemId = balance_items.id 
+        SET balance_items.pricePaid = coalesce(paid.price, 0),
+            balance_items.pricePending = coalesce(pending.price, 0),
+            balance_items.priceOpen = (CASE
+                WHEN balance_items.status = '${BalanceItemStatus.Due}' THEN (balance_items.unitPrice * balance_items.amount - balance_items.pricePaid - balance_items.pricePending)
+                ELSE (-balance_items.pricePaid - balance_items.pricePending)
+            END)
         ${secondWhere}`;
 
         await Database.update(query, params);
     }
 
+    /**
+     * @deprecated
+     */
+    static async updatePricePending(balanceItemIds: string[] | 'all') {
+        // deprecated
+    }
+
     static async loadPayments(items: BalanceItem[]) {
         if (items.length == 0) {
             return { balanceItemPayments: [], payments: [] };
@@ -366,8 +351,14 @@ export class BalanceItem extends Model {
         return { payments, balanceItemPayments };
     }
 
+    getStructure() {
+        return BalanceItemStruct.create({
+            ...this,
+        });
+    }
+
     static async getStructureWithPayments(items: BalanceItem[]): Promise<BalanceItemWithPayments[]> {
-        if (items.length == 0) {
+        if (items.length === 0) {
             return [];
         }
 

package/src/models/CachedBalance.ts

@@ -1,6 +1,6 @@
 import { column, Model, SQLResultNamespacedRow } from '@simonbackx/simple-database';
-import { SQL, SQLAlias, SQLCalculation, SQLMinusSign, SQLMultiplicationSign, SQLSelect, SQLSelectAs, SQLSum, SQLWhere, SQLWhereSign } from '@stamhoofd/sql';
-import { BalanceItemStatus, ReceivableBalanceType } from '@stamhoofd/structures';
+import { SQL, SQLAlias, SQLCalculation, SQLGreatest, SQLMin, SQLMinusSign, SQLMultiplicationSign, SQLSelect, SQLSelectAs, SQLSum, SQLWhere, SQLWhereSign } from '@stamhoofd/sql';
+import { BalanceItem as BalanceItemStruct, BalanceItemStatus, ReceivableBalanceType } from '@stamhoofd/structures';
 import { v4 as uuidv4 } from 'uuid';
 import { BalanceItem } from './BalanceItem';
 
@@ -35,9 +35,18 @@ export class CachedBalance extends Model {
     @column({ type: 'integer' })
     amount = 0;
 
+    /**
+     * The sum of unconfirmed payments
+     */
     @column({ type: 'integer' })
     amountPending = 0;
 
+    /**
+     * This is the minimum `dueAt` that lies in the future of all **unpaid** balance items connected to this object.
+     */
+    @column({ type: 'datetime', nullable: true })
+    nextDueAt: Date | null = null;
+
     @column({
         type: 'datetime', beforeSave(old?: any) {
             if (old !== undefined) {
@@ -102,17 +111,7 @@ export class CachedBalance extends Model {
             .where(columnName, objectIds)
             .whereNot('status', BalanceItemStatus.Hidden)
             .where(
-                SQL.where(
-                    new SQLCalculation(
-                        new SQLCalculation(
-                            SQL.column('unitPrice'),
-                            new SQLMultiplicationSign(),
-                            SQL.column('amount'),
-                        ),
-                        new SQLMinusSign(),
-                        SQL.column('pricePaid'),
-                    )
-                    , SQLWhereSign.NotEqual, 0)
+                SQL.where(SQL.column('priceOpen'), SQLWhereSign.NotEqual, 0)
                     .or('pricePending', SQLWhereSign.NotEqual, 0),
             );
 
@@ -124,21 +123,12 @@ export class CachedBalance extends Model {
     }
 
     private static async fetchForObjects(organizationId: string, objectIds: string[], columnName: string, customWhere?: SQLWhere) {
+        const dueOffset = BalanceItemStruct.getDueOffset();
         const query = SQL.select(
             SQL.column(columnName),
             new SQLSelectAs(
-                new SQLCalculation(
-                    new SQLSum(
-                        new SQLCalculation(
-                            SQL.column('unitPrice'),
-                            new SQLMultiplicationSign(),
-                            SQL.column('amount'),
-                        ),
-                    ),
-                    new SQLMinusSign(),
-                    new SQLSum(
-                        SQL.column('pricePaid'),
-                    ),
+                new SQLSum(
+                    SQL.column('priceOpen'),
                 ),
                 new SQLAlias('data__amount'),
             ),
@@ -153,6 +143,7 @@ export class CachedBalance extends Model {
             .where('organizationId', organizationId)
             .where(columnName, objectIds)
             .whereNot('status', BalanceItemStatus.Hidden)
+            .where(SQL.where('dueAt', null).or('dueAt', SQLWhereSign.LessEqual, dueOffset))
             .groupBy(SQL.column(columnName));
 
         if (customWhere) {
@@ -161,7 +152,40 @@ export class CachedBalance extends Model {
 
         const result = await query.fetch();
 
-        const results: [string, { amount: number; amountPending: number }][] = [];
+        // Calculate future due
+        const dueQuery = SQL.select(
+            SQL.column(columnName),
+            new SQLSelectAs(
+                new SQLMin(
+                    SQL.column('dueAt'),
+                ),
+                new SQLAlias('data__dueAt'),
+            ),
+            // If the current amount_due is negative, we can ignore that negative part if there is a future due item
+            new SQLSelectAs(
+                new SQLSum(
+                    SQL.column('priceOpen'),
+                ),
+                new SQLAlias('data__amount'),
+            ),
+            new SQLSelectAs(
+                new SQLSum(
+                    SQL.column('pricePending'),
+                ),
+                new SQLAlias('data__amountPending'),
+            ),
+        )
+            .from(BalanceItem.table)
+            .where('organizationId', organizationId)
+            .where(columnName, objectIds)
+            .where('status', BalanceItemStatus.Due)
+            .whereNot('dueAt', null)
+            .where('dueAt', SQLWhereSign.Greater, dueOffset)
+            .groupBy(SQL.column(columnName));
+
+        const dueResult = await dueQuery.fetch();
+
+        const results: [string, { amount: number; amountPending: number; nextDueAt: Date | null }][] = [];
         for (const row of result) {
             if (!row['data']) {
                 throw new Error('Invalid data namespace');
@@ -187,20 +211,68 @@ export class CachedBalance extends Model {
                 throw new Error('Invalid amountPending');
             }
 
-            results.push([objectId, { amount, amountPending }]);
+            results.push([objectId, { amount, amountPending, nextDueAt: null }]);
+        }
+
+        for (const row of dueResult) {
+            if (!row['data']) {
+                throw new Error('Invalid data namespace');
+            }
+
+            if (!row[BalanceItem.table]) {
+                throw new Error('Invalid ' + BalanceItem.table + ' namespace');
+            }
+
+            const objectId = row[BalanceItem.table][columnName];
+            const dueAt = row['data']['dueAt'];
+            const amount = row['data']['amount'];
+            const amountPending = row['data']['amountPending'];
+
+            if (typeof objectId !== 'string') {
+                throw new Error('Invalid objectId');
+            }
+
+            if (!(dueAt instanceof Date)) {
+                throw new Error('Invalid dueAt');
+            }
+
+            if (typeof amount !== 'number') {
+                throw new Error('Invalid amount');
+            }
+
+            if (typeof amountPending !== 'number') {
+                throw new Error('Invalid amountPending');
+            }
+
+            const result = results.find(r => r[0] === objectId);
+            if (result) {
+                result[1].nextDueAt = dueAt;
+
+                if (result[1].amount < 0) {
+                    if (amount > 0) {
+                        // Let the future due amount fill in the gap until maximum 0
+                        result[1].amount = Math.min(0, result[1].amount + amount);
+                    }
+                }
+
+                result[1].amountPending += amountPending;
+            }
+            else {
+                results.push([objectId, { amount: 0, amountPending: amountPending, nextDueAt: dueAt }]);
+            }
         }
 
         // Add missing object ids (with 0 amount, otherwise we don't reset the amounts back to zero when all the balance items are hidden)
         for (const objectId of objectIds) {
             if (!results.find(([id]) => id === objectId)) {
-                results.push([objectId, { amount: 0, amountPending: 0 }]);
+                results.push([objectId, { amount: 0, amountPending: 0, nextDueAt: null }]);
             }
         }
 
         return results;
     }
 
-    private static async setForResults(organizationId: string, result: [string, { amount: number; amountPending: number }][], objectType: ReceivableBalanceType) {
+    private static async setForResults(organizationId: string, result: [string, { amount: number; amountPending: number; nextDueAt: null | Date }][], objectType: ReceivableBalanceType) {
         if (result.length === 0) {
             return;
         }
@@ -212,10 +284,11 @@ export class CachedBalance extends Model {
                 'objectType',
                 'amount',
                 'amountPending',
+                'nextDueAt',
                 'createdAt',
                 'updatedAt',
             )
-            .values(...result.map(([objectId, { amount, amountPending }]) => {
+            .values(...result.map(([objectId, { amount, amountPending, nextDueAt }]) => {
                 return [
                     uuidv4(),
                     organizationId,
@@ -223,6 +296,7 @@ export class CachedBalance extends Model {
                     objectType,
                     amount,
                     amountPending,
+                    nextDueAt,
                     new Date(),
                     new Date(),
                 ];
@@ -231,6 +305,7 @@ export class CachedBalance extends Model {
             .onDuplicateKeyUpdate(
                 SQL.assignment('amount', SQL.column('v', 'amount')),
                 SQL.assignment('amountPending', SQL.column('v', 'amountPending')),
+                SQL.assignment('nextDueAt', SQL.column('v', 'nextDueAt')),
                 SQL.assignment('updatedAt', SQL.column('v', 'updatedAt')),
             );
 

package/src/models/DocumentTemplate.ts

@@ -208,7 +208,7 @@ export class DocumentTemplate extends Model {
             let debtor: Parent | undefined = parentsWithNRN[0] ?? registration.member.details.parents[0];
             if (parentsWithNRN.length > 1) {
                 for (const balanceItem of balanceItems) {
-                    if (balanceItem && balanceItem.userId && balanceItem.status === BalanceItemStatus.Paid) {
+                    if (balanceItem && balanceItem.userId && balanceItem.priceOpen === 0 && balanceItem.status === BalanceItemStatus.Due) {
                         const user = await User.getByID(balanceItem.userId);
                         if (user) {
                             const parent = parentsWithNRN.find(p => p.hasEmail(user.email));

package/src/models/Order.ts

@@ -157,6 +157,13 @@ export class Order extends Model {
         return false;
     }
 
+    get isDue() {
+        if (this.status === OrderStatus.Canceled || this.status === OrderStatus.Deleted) {
+            return false;
+        }
+        return true;
+    }
+
     get totalToPay() {
         if (this.status === OrderStatus.Canceled || this.status === OrderStatus.Deleted) {
             return 0;

package/src/models/Payment.ts

@@ -1,5 +1,5 @@
 import { column, Model, SQLResultNamespacedRow } from '@simonbackx/simple-database';
-import { BalanceItemDetailed, BalanceItemPaymentDetailed, PaymentCustomer, PaymentGeneral, PaymentMethod, PaymentProvider, PaymentStatus, Settlement, TransferSettings, BaseOrganization } from '@stamhoofd/structures';
+import { BalanceItemDetailed, BalanceItemPaymentDetailed, PaymentCustomer, PaymentGeneral, PaymentMethod, PaymentProvider, PaymentStatus, Settlement, TransferSettings, BaseOrganization, PaymentType } from '@stamhoofd/structures';
 import { Formatter } from '@stamhoofd/utility';
 import { v4 as uuidv4 } from 'uuid';
 
@@ -16,6 +16,18 @@ export class Payment extends Model {
     })
     id!: string;
 
+    /**
+     * Types of payment:
+     * - Payment (default) = positive amount or zero
+     * - Refund = negative amount
+     * - Rebooking = zero payment due to rebooking
+     */
+    @column({ type: 'string' })
+    type = PaymentType.Payment;
+
+    /**
+     * How the payment is paid out or refunded
+     */
     @column({ type: 'string' })
     method: PaymentMethod;