@mj-biz-apps/orders-core-entities-server 5.32.0 → 5.33.0

package/dist/AmountChange.d.ts

@@ -0,0 +1,140 @@
+/**
+ * AmountChange — lower a booked term's amount (#506, golive #221 case A).
+ *
+ * CHECK: read everything the change depends on and plan it, writing nothing. `Orders.AmendArrangement` with
+ * `NewAmount` and `Preview: true` returns this plan: the reduction and its tax, the catch-up, the staged entries
+ * offset and the new schedule, the instalments reduced or cancelled, and any credit memo.
+ *
+ * APPLY: an approved Price concession carrying `NewAmount` is applied in the approval's own transaction:
+ *   - the catch-up, the offsets and the new schedule are posted through Accounting.CreateJournalEntries;
+ *   - the term's amount becomes the new amount;
+ *   - the instalments not yet invoiced are lowered, or cancelled when lowered to nothing;
+ *   - what they cannot absorb is credited on a credit memo (#662): see below;
+ *   - an `AmountChanged` subscription event records it, and accounting's acknowledgment task is raised.
+ * The concession's `ScheduleReduction` and `CreditMemoAmount` (set by the concession itself) are what the order's
+ * balance takes off the booked lines; the schedule check takes off only `ScheduleReduction`.
+ *
+ * THE CREDIT MEMO IS THE APPROVED CHANGE ITSELF (#662). A reduction the uninvoiced instalments cannot absorb in full
+ * (part of it lands on an invoice already sent, the order is billed as a whole, or a refund is asked for) is
+ * credited on a memo the concession carries: its amount and document number. Applying it
+ *   - posts the memo's entry, dated the effective day: deferred revenue and tax debited, the receivable credited;
+ *   - credits the invoiced instalment it names, up to that invoice's open amount (`AmountCredited`), or, when the
+ *     customer asked for a paid invoice's credit back, records it there for finance to refund;
+ *   - lowers the line's `BilledToDate` by the memo's net, as a return's memo does.
+ * Whatever no invoice takes is the customer's credit: the order's balance falls by the memo, so a paid order goes
+ * negative, which is how an account credit is held (D68). A refund is not paid here; finance refunds it from the
+ * order's payments with `Orders.RefundPayment`, and the acknowledgment task says so.
+ *
+ * WHEN IT IS REFUSED:
+ *   - the term is not Scheduled or Active, or its renewal is already placed (reverse that first);
+ *   - the line that bought the term has had a return against it, so the term's amount no longer describes what
+ *     the customer was billed for it;
+ *   - the new amount is not lower than the current one, or is zero (that is a cancellation);
+ *   - a staged entry that would need an offset is already in a journal-entry batch;
+ *   - the staged entries do not add up to the term's amount, so the share already earned cannot be read;
+ *   - "applies to invoice" names something that is not an invoiced instalment of this order's covering company;
+ *   - an instalment would be lowered below what has already been paid on it;
+ *   - the line would stay billed for more than its new amount;
+ *   - a credit memo is needed and the line carries a charge other than tax, whose share nothing can say;
+ *   - no one other than the requester holds the acknowledgment role, so accounting could not be told.
+ *
+ * CONNECTS TO:
+ *   PLAN:   ./AmountChangePlan.ts
+ *   SHARES: ./TermExtension.ts (renewal check, acknowledgers, the term's driver, its staged entries, the task)
+ *           ./ReversalBehavior.ts + ./ReversalResolver.ts (the tax the line was charged, mirrored)
+ *           ./PaymentScheduleBehavior.ts (which rows bill the line's company)
+ *   CALLER: AmendArrangementOperation (preview) · OrderConcessionEntityServer (value, apply)
+ *   WRITES: Accounting.CreateJournalEntries · Subscription Terms · Order Header Payment Schedules ·
+ *           Order Lines (BilledToDate) · Subscription Events · Tasks
+ */
+import { type EntitySaveOptions } from '@memberjunction/core';
+import { type AmountChangePlan, type CreditMemoSplit, type InstalmentChange, type ReductionPlan } from './AmountChangePlan.js';
+import type { ApprovalTaskContext } from './ConcessionApprovalTask.js';
+export interface AmountChangeRequest {
+    SubscriptionTermID: string;
+    /** The term's new amount: net of discount, before tax. */
+    NewAmount: number;
+    /** The invoiced instalment the reduction is about, when it is about one. */
+    AppliesToInvoiceID?: string | null;
+    /** The customer asked for a refund of a paid invoice's credit. */
+    RefundRequested?: boolean;
+    /** Who asked. Excluded from the acknowledgment, which they cannot confirm themselves. */
+    RequestedByUserID: string;
+    /** The concession being approved or applied, which is not one of the line's earlier changes. */
+    OrderConcessionID?: string | null;
+}
+/** Everything an amount change would do, read and planned but not written. */
+export interface CheckedAmountChange {
+    TermID: string;
+    TermNumber: number;
+    SubscriptionID: string;
+    SubscriptionNumber: string;
+    OrderHeaderID: string;
+    OrderNumber: string | null;
+    OrderLineID: string;
+    CurrentAmount: number;
+    NewAmount: number;
+    /** The tax charged on the reduction, mirrored from the line's own tax charges. */
+    TaxReduction: number;
+    /** Reduction plus its tax: what the customer is billed less. */
+    GrossReduction: number;
+    EffectiveDate: Date;
+    Recognition: AmountChangePlan;
+    Billing: ReductionPlan;
+    /** What the billing plan takes off the instalments not yet invoiced, reduction and tax together. */
+    ScheduleReduction: number;
+    /** The rest of the gross reduction, credited on a credit memo, as net and tax. Zero when none is needed. */
+    CreditMemo: CreditMemoSplit;
+    AcknowledgerIDs: string[];
+}
+/** Check an amount change and plan it, or say why it cannot be made. Reads only. */
+export declare function CheckAmountChange(request: AmountChangeRequest, ctx: ApprovalTaskContext): Promise<CheckedAmountChange | string>;
+/** The document number the order's next credit memo takes. */
+export declare function NextCreditMemoNumber(orderHeaderID: string, orderNumber: string | null, ctx: ApprovalTaskContext): Promise<string>;
+/** The approved concession an amount change is applied from. */
+export interface ApprovedAmountChange {
+    ID: string;
+    SubscriptionTermID: string;
+    NewAmount: number;
+    AppliesToPaymentScheduleID: string | null;
+    RefundRequested: boolean;
+    RequestedByUserID: string;
+    ReasonCategory: string;
+    Reason: string;
+    /** The reduction the concession was valued at when recorded. */
+    ComputedValue: number;
+    /** The credit memo stamped on approval, and its number. Zero and null when none is needed. */
+    CreditMemoAmount: number;
+    CreditMemoNumber: string | null;
+}
+/**
+ * Apply an approved amount change to its term. Joins the caller's transaction; throws on any refusal, so the
+ * caller's approval rolls back with it.
+ */
+export declare function ApplyAmountChange(concession: ApprovedAmountChange, ctx: ApprovalTaskContext): Promise<CheckedAmountChange>;
+/**
+ * Write a reduction plan's instalments: each takes its new amount, or is cancelled at zero. Refuses an
+ * instalment invoiced since the plan was made. `waited` finishes "was invoiced while …".
+ */
+export declare function LowerInstalments(changes: InstalmentChange[], waited: string, ctx: ApprovalTaskContext, options?: EntitySaveOptions): Promise<void>;
+/** An approved amount change, as what it takes off its line. */
+export interface AppliedAmountChange {
+    OrderConcessionID: string;
+    OrderLineID: string;
+    CompanyID: string;
+    /** What it took off the line's instalment billing, before tax: the schedule reduction's net. */
+    Net: number;
+    /** The tax on that. */
+    Tax: number;
+    /** Both: the concession's ScheduleReduction. Zero when a credit memo took the whole reduction. */
+    Gross: number;
+    /** The whole reduction before tax, credit memo included: the concession's value. */
+    ReducedNet: number;
+}
+/**
+ * The approved amount changes on an order. The schedule check and each instalment invoice take their schedule
+ * reductions off the lines they changed, so the lowered instalments still tie to the lines. A credit memo's part is
+ * not taken off: it was billed on an invoice already sent, and the memo gives it back.
+ */
+export declare function AppliedAmountChanges(orderHeaderID: string, ctx: ApprovalTaskContext): Promise<AppliedAmountChange[]>;
+//# sourceMappingURL=AmountChange.d.ts.map

package/dist/AmountChange.d.ts.map

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