@stamhoofd/models 2.118.1 → 2.120.0

package/dist/models/BalanceItem.d.ts

@@ -0,0 +1,218 @@
+import type { VATExcemptReason } from '@stamhoofd/structures';
+import { BalanceItemRelation, BalanceItemRelationType, BalanceItemStatus, BalanceItem as BalanceItemStruct, BalanceItemType, BalanceItemWithPayments, BalanceItemWithPrivatePayments } from '@stamhoofd/structures';
+import { QueryableModel } from '@stamhoofd/sql';
+import { Payment } from './Payment.js';
+/**
+ * Keeps track of how much a member/user owes or needs to be reimbursed.
+ */
+export declare class BalanceItem extends QueryableModel {
+    static table: string;
+    id: string;
+    organizationId: string;
+    memberId: string | null;
+    userId: string | null;
+    payingOrganizationId: string | null;
+    /**
+     * The registration ID that is linked to this balance item
+     */
+    registrationId: string | null;
+    /**
+     * The order ID that is linked to this balance item
+     */
+    orderId: string | null;
+    /**
+     * The STPackage ID that is linked to this balance item
+     */
+    packageId: string | null;
+    /**
+     * The depending balance item ID that is linked to this balance item
+     * -> as soon as this balance item is paid, we'll mark this balance item as pending if it is still hidden
+     * -> allows for a pay back system where one user needs to pay back a different user
+     */
+    dependingBalanceItemId: string | null;
+    type: BalanceItemType;
+    relations: Map<BalanceItemRelationType, BalanceItemRelation>;
+    description: string;
+    /**
+     * In case this balance item is associated with an item that was charged for a certain period, the startDate is saved here.
+     * e.g. startDate of the registration.
+     */
+    startDate: Date | null;
+    /**
+     * In case this balance item is associated with an item that was charged for a certain period, the endDate is saved here.
+     * e.g. endDate of the registration.
+     */
+    endDate: Date | null;
+    /**
+     * @deprecated Use quantity
+     */
+    amount: number;
+    get quantity(): number;
+    set quantity(quantity: number);
+    /**
+     * Price per piece
+     *
+     * NOTE: We store an integer of the price up to 4 digits after the comma.
+     * 1 euro = 10000.
+     * 0,01 euro = 100
+     * 0,0001 euro = 1
+     *
+     * This is required for correct VAT calculations without intermediate rounding.
+     */
+    unitPrice: number;
+    VATPercentage: number | null;
+    VATIncluded: boolean;
+    /**
+     * Whether there is a VAT excempt reason.
+     * Note: keep the original VAT in these cases. On time of payment or invoicing, the VAT excemption will be revalidated.
+     * If that fails, we can still charge the VAT.
+     */
+    VATExcempt: VATExcemptReason | null;
+    /**
+     * This is a cached value for storing in the database.
+     * It stores the calculated price with VAT.
+     *
+     * price should = pricePaid + pricePending + priceOpen
+     */
+    priceTotal: number;
+    /**
+     * Cached value, for optimizations
+     *
+     * NOTE: We store an integer of the price up to 4 digits after the comma.
+     * 1 euro = 10000.
+     * 0,01 euro = 100
+     * 0,0001 euro = 1
+     *
+     * This is required for correct VAT calculations without intermediate rounding.
+     */
+    pricePaid: number;
+    /**
+     * Cached value, for optimizations
+     *
+     * NOTE: We store an integer of the price up to 4 digits after the comma.
+     * 1 euro = 10000.
+     * 0,01 euro = 100
+     * 0,0001 euro = 1
+     *
+     * This is required for correct VAT calculations without intermediate rounding.
+     */
+    pricePending: number;
+    /**
+     * Cached value, for optimizations
+     *
+     * NOTE: We store an integer of the price up to 4 digits after the comma.
+     * 1 euro = 10000.
+     * 0,01 euro = 100
+     * 0,0001 euro = 1
+     *
+     * This is required for correct VAT calculations without intermediate rounding.
+     */
+    priceOpen: number;
+    /**
+     * 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)
+     */
+    status: BalanceItemStatus;
+    /**
+     * 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.
+     */
+    dueAt: Date | null;
+    /**
+     * Marking a balance item as 'paid' can have side effects. To prevent executing these side effects multiple times, we store it in here.
+     */
+    paidAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+    /**
+     * @deprecated: use priceWithVAT
+     * NOTE: This contains an integer of the price up to 4 digits after the comma.
+     * 1 euro = 10000.
+     * 0,01 euro = 100
+     * 0,0001 euro = 1
+     *
+     * This is required for correct VAT calculations without intermediate rounding.
+     */
+    get price(): number;
+    /**
+     * Difference here is that when the VAT is excempt, this is still set, while VAT will be zero.
+     */
+    get calculatedVAT(): number;
+    /**
+     * Note: This is not 100% accurate due to rounding
+     * Legally, VAT must be calculated at the invoice level and rounded there, so calculating VAT at the line level will always contain errors - unless we work with prices that already include VAT.
+     * Technically, we cannot pass infinitely precise numbers through the system to avoid rounding. Therefore, the returned number is rounded to 4 decimal places. For typical amounts with only 2 decimal places, this does not result in a loss of accuracy.
+     * As a result, VAT calculation must be performed again at the end, just before payment.
+     */
+    get VAT(): number;
+    get priceWithVAT(): number;
+    /**
+     * Note: when the VAT is already included, the result of this will be unreliable because of rounding issues.
+     * Do not use this in calculations!
+     */
+    get priceWithoutVAT(): number;
+    get isAfterDueDate(): boolean;
+    /**
+     * Note: cancelled balance items can also return 'true', because if they have pending/paid payments, they are still due with a negative price
+     */
+    get isDue(): boolean;
+    /**
+     * NOTE: This contains an integer of the price up to 4 digits after the comma.
+     * 1 euro = 10000.
+     * 0,01 euro = 100
+     * 0,0001 euro = 1
+     *
+     * This is required for correct VAT calculations without intermediate rounding.
+     */
+    get calculatedPriceOpen(): number;
+    /**
+     * Returns zero if the balance item is canceled, otherwise priceWithVAT
+     */
+    get priceDue(): number;
+    /**
+     * price minus pricePaid
+     */
+    get priceUnpaid(): number;
+    get isPaid(): boolean;
+    /**
+     * Options.cancellationFeePercentage: 0-10000 (0-100%)
+     * By default 0% will be charged
+     * Will create a new cancellation fee if the cancellation fee percentage is not 0%
+     */
+    static deleteItems(items: BalanceItem[], options?: {
+        cancellationFeePercentage?: number;
+    }): Promise<BalanceItem[]>;
+    createCancellationItem(fee: number): Promise<BalanceItem>;
+    static reactivateItems(items: BalanceItem[]): Promise<void>;
+    static undoForDeletedOrders(orderIds: string[]): Promise<void>;
+    static deleteForDeletedOrders(orderIds: string[], options?: {
+        cancellationFeePercentage?: number;
+    }): Promise<BalanceItem[] | undefined>;
+    static deleteForDeletedMember(memberId: string, options?: {
+        cancellationFeePercentage?: number;
+    }): Promise<BalanceItem[]>;
+    static deleteForDeletedRegistration(registrationId: string, options?: {
+        cancellationFeePercentage?: number;
+    }): Promise<BalanceItem[]>;
+    static getForRegistration(registrationId: string, organizationId?: string): Promise<{
+        payments: Payment[];
+        balanceItemPayments: import("./BalanceItemPayment.js").BalanceItemPayment[];
+        items: BalanceItem[];
+    }>;
+    /**
+     * Update the outstanding balance of multiple members in one go (or all members)
+     */
+    static updatePricePaid(balanceItemIds: string[] | 'all'): Promise<void>;
+    static loadPayments(items: (BalanceItem | {
+        id: string;
+    })[]): Promise<{
+        payments: Payment[];
+        balanceItemPayments: import("./BalanceItemPayment.js").BalanceItemPayment[];
+    }>;
+    getStructure(): BalanceItemStruct;
+    static getStructureWithPayments(items: (BalanceItem | BalanceItemStruct)[]): Promise<BalanceItemWithPayments[]>;
+    static getStructureWithPrivatePayments(items: BalanceItem[]): Promise<BalanceItemWithPrivatePayments[]>;
+    static balanceItemsForUsersAndMembers(organizationId: string | null, userIds: string[], memberIds: string[]): Promise<BalanceItem[]>;
+    static balanceItemsForOrganization(organizationId: string): Promise<BalanceItem[]>;
+}
+//# sourceMappingURL=BalanceItem.d.ts.map

package/dist/models/BalanceItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BalanceItem.d.ts","sourceRoot":"","sources":["../../src/models/BalanceItem.ts"],"names":[],"mappings":"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"}