@mj-biz-apps/orders-core-entities-server 0.0.1 → 5.2.0

package/dist/CancelSubscriptionOperation.js

@@ -0,0 +1,317 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * Orders.CancelSubscription — cancel a subscription atomically, by POLICY (design §5).
+ *
+ * WHY THIS IS AN OPERATION AND NOT A FORM
+ * The mechanics already worked: a reversal order line with a negative quantity produces mirrored
+ * journal entries through the ordinary booking path (D16). What did not work was asking a human to
+ * do it. Amith's case — a subscription running 1/1–12/31, cancelled on 7/1 — needs a line of
+ * quantity `-0.5`. That is correct double-entry and terrible data entry, and it silently ignores
+ * the `SubscriptionType`'s own rules about WHEN coverage may end and WHETHER money comes back.
+ *
+ * So the caller supplies a subscription, a date and a reason. `SubscriptionBehavior` decides what
+ * the rules permit; this operation performs it in ONE transaction:
+ *
+ *   1. resolve the affected term (the one whose window covers the request, else the latest)
+ *   2. ask the behaviour what the rules say — effective date, refund, reversal fraction
+ *   3. when there is something to reverse, emit a reversal ORDER whose single line carries the
+ *      negative quantity and points at the original line, and confirm it — booking mirrors the JEs
+ *   4. stamp the term (Canceled/Completed, CanceledAt, CancellationEffectiveDate)
+ *   5. stamp the subscription (Canceled, EndDate = access-through, so grace is visible)
+ *   6. revoke standing grants when access-through has already passed; leave them when
+ *      grace remains — the read evaluator honours `subscription.EndDate` either way
+ *   7. log a `SubscriptionEvent` — the lifecycle record that made the table worth having
+ *
+ * ATOMICITY: everything above shares one transaction opened here. The reversal order's own
+ * `OrderEntityServer.Save` nests inside it as savepoints (the same composition booking already
+ * relies on), so a failure anywhere leaves the subscription exactly as it was — never a reversed
+ * ledger with a still-active subscription, or vice versa.
+ *
+ * FAILURE MODEL: logical failures (unknown subscription, already cancelled, no term) come back
+ * INSIDE the output as `Success: false` with a message — the same contract accounting's operations
+ * use. Only genuine faults throw.
+ *
+ * CONNECTS TO:
+ *   POLICY: SubscriptionBehavior.DecideCancellation (./SubscriptionBehavior.ts)
+ *   BOOKING: OrderEntityServer.Save (./OrderEntityServer.ts) — the reversal order goes through it
+ *   TABLES: __mj_BizAppsOrders.{Subscription,SubscriptionTerm,SubscriptionEvent,OrderHeader,OrderLine}
+ */
+import { BaseRemotableOperation, CompositeKey, LogError, RunView, } from '@memberjunction/core';
+import { MJGlobal, RegisterClass } from '@memberjunction/global';
+import { RequireUUID } from './sql-guards.js';
+import { RevokeGrantsForCanceledSubscription } from './EntitlementEngine.js';
+import { SubscriptionBehavior, } from './SubscriptionBehavior.js';
+const SUBSCRIPTION_ENTITY = 'MJ_BizApps_Orders: Subscriptions';
+const SUBSCRIPTION_TERM_ENTITY = 'MJ_BizApps_Orders: Subscription Terms';
+const SUBSCRIPTION_EVENT_ENTITY = 'MJ_BizApps_Orders: Subscription Events';
+const SUBSCRIPTION_TYPE_ENTITY = 'MJ_BizApps_Orders: Subscription Types';
+const ORDER_HEADER_ENTITY = 'MJ_BizApps_Orders: Order Headers';
+const ORDER_LINE_ENTITY = 'MJ_BizApps_Orders: Order Lines';
+let CancelSubscriptionOperation = class CancelSubscriptionOperation extends BaseRemotableOperation {
+    constructor() {
+        super(...arguments);
+        this.OperationKey = 'Orders.CancelSubscription';
+    }
+    async InternalExecute(input, provider, user) {
+        // Caller-supplied ids reach SQL filter text downstream. Validated here,
+        // at the boundary, so every frame below this one can trust them.
+        RequireUUID(input.SubscriptionID, 'SubscriptionID');
+        const requestDate = input.RequestDate ? new Date(input.RequestDate) : new Date();
+        const subscription = await this.loadSubscription(provider, user, input.SubscriptionID);
+        if (!subscription) {
+            return { Success: false, Message: `No subscription found with ID '${input.SubscriptionID}'.` };
+        }
+        if (subscription.Status === 'Canceled') {
+            // Not an error worth throwing over — the caller asked for a state that already holds.
+            return { Success: false, Message: `Subscription is already canceled.` };
+        }
+        const rules = await this.loadRules(provider, user, subscription.SubscriptionTypeID);
+        if (!rules) {
+            return {
+                Success: false,
+                Message: `Subscription type '${subscription.SubscriptionTypeID}' was not found.`,
+            };
+        }
+        const term = await this.resolveTerm(provider, user, subscription.ID, requestDate);
+        if (!term) {
+            return {
+                Success: false,
+                Message: `Subscription has no term to cancel — nothing was ever booked against it.`,
+            };
+        }
+        const decision = this.behaviorFor(rules).DecideCancellation({
+            Rules: rules,
+            RequestDate: requestDate,
+            Term: {
+                StartDate: new Date(term.StartDate),
+                EndDate: new Date(term.EndDate),
+                Amount: Number(term.Amount),
+                TermNumber: term.TermNumber,
+            },
+        });
+        if (input.Preview) {
+            return { Success: true, Decision: decision, SubscriptionTermID: term.ID, Message: decision.Explanation };
+        }
+        const dbProvider = provider;
+        await dbProvider.BeginTransaction();
+        try {
+            const reversal = decision.ReversalFraction > 0
+                ? await this.emitReversalOrder(provider, user, subscription, term, decision, input.Reason)
+                : undefined;
+            await this.stampTerm(provider, user, term.ID, decision);
+            await this.stampSubscription(provider, user, subscription.ID, decision);
+            await this.syncGrantsOnCancel(provider, user, subscription.ID, decision, input.Reason);
+            await this.logEvent(provider, user, subscription.ID, decision, input.Reason, reversal?.ID);
+            await dbProvider.CommitTransaction();
+            return {
+                Success: true,
+                Message: decision.Explanation,
+                Decision: decision,
+                SubscriptionTermID: term.ID,
+                ReversalOrderID: reversal?.ID,
+                ReversalOrderNumber: reversal?.Number,
+            };
+        }
+        catch (err) {
+            LogError(`Orders.CancelSubscription failed for ${input.SubscriptionID}: ${err}`);
+            try {
+                await dbProvider.RollbackTransaction();
+            }
+            catch (rollbackErr) {
+                LogError(`Rollback failed after CancelSubscription error: ${rollbackErr}`);
+            }
+            return {
+                Success: false,
+                Message: err instanceof Error ? err.message : String(err),
+                Decision: decision,
+                SubscriptionTermID: term.ID,
+            };
+        }
+    }
+    // ─── Reads ─────────────────────────────────────────────────────────────────
+    async loadSubscription(provider, user, id) {
+        const rv = new RunView(provider);
+        const result = await rv.RunView({
+            EntityName: SUBSCRIPTION_ENTITY,
+            ExtraFilter: `ID='${id}'`,
+            Fields: [
+                'ID',
+                'CompanyID',
+                'SubscriptionTypeID',
+                'ProductID',
+                'Status',
+                'HolderOrganizationID',
+                'BeneficiaryPersonID',
+            ],
+            ResultType: 'simple',
+            // The caller may have just written this row; a cached read would decide policy on
+            // stale status.
+            BypassCache: true,
+        }, user);
+        return result?.Results?.[0] ?? null;
+    }
+    async loadRules(provider, user, typeID) {
+        const rv = new RunView(provider);
+        const result = await rv.RunView({ EntityName: SUBSCRIPTION_TYPE_ENTITY, ExtraFilter: `ID='${typeID}'`, ResultType: 'simple' }, user);
+        return result?.Results?.[0] ?? null;
+    }
+    /**
+     * The term the request lands in, or — when the request falls outside every window (an early
+     * cancellation of a future term, or a late one after everything lapsed) — the latest term.
+     * Cancelling always has to act on SOMETHING for the reversal to point at.
+     */
+    async resolveTerm(provider, user, subscriptionID, requestDate) {
+        const rv = new RunView(provider);
+        const result = await rv.RunView({
+            EntityName: SUBSCRIPTION_TERM_ENTITY,
+            ExtraFilter: `SubscriptionID='${subscriptionID}' AND Status IN ('Scheduled','Active')`,
+            OrderBy: 'TermNumber DESC',
+            ResultType: 'simple',
+            BypassCache: true,
+        }, user);
+        const terms = result?.Results ?? [];
+        if (terms.length === 0)
+            return null;
+        const at = requestDate.getTime();
+        const covering = terms.find((t) => new Date(t.StartDate).getTime() <= at && new Date(t.EndDate).getTime() >= at);
+        return covering ?? terms[0];
+    }
+    // ─── Writes ────────────────────────────────────────────────────────────────
+    /**
+     * A reversal order carrying ONE line: the negative slice of the original purchase.
+     *
+     * It goes through the ordinary confirm path rather than writing journal entries directly, so the
+     * mirrored ledger, the GL account resolution and the all-or-none guarantee are the SAME code
+     * that booked the original. `ReversesOrderLineID` is what makes a negative quantity legal
+     * (OrderLineEntityServer validates exactly that).
+     */
+    async emitReversalOrder(provider, user, subscription, term, decision, reason) {
+        const original = await this.loadOriginalLine(provider, user, term.OrderLineID);
+        if (!original) {
+            throw new Error(`The order line that bought term ${term.TermNumber} (${term.OrderLineID}) no longer exists, ` +
+                `so the cancellation cannot be reversed against it.`);
+        }
+        const order = await provider.GetEntityObject(ORDER_HEADER_ENTITY, user);
+        order.NewRecord();
+        // 'Cancellation' — one of the CK_OrderHeader_OrderType values. There is no 'Reversal'
+        // order type; reversal is what the negative LINE does, not what the order is called.
+        order.OrderType = 'Cancellation';
+        order.OrderDate = decision.EffectiveDate;
+        order.CompanyID = subscription.CompanyID;
+        order.BillToOrganizationID = subscription.HolderOrganizationID;
+        order.BillToPersonID = subscription.BeneficiaryPersonID;
+        order.Notes = reason ? `Subscription cancellation: ${reason}` : 'Subscription cancellation';
+        const line = await provider.GetEntityObject(ORDER_LINE_ENTITY, user);
+        line.NewRecord();
+        line.ProductID = original.ProductID;
+        line.LineNumber = 1;
+        // A FRACTION OF THE ORIGINAL LINE, not of one unit. The purchased line may already carry a
+        // prorated quantity (a short first period), so reversing `-fraction` flat would unwind more
+        // than was ever sold. Rounded to the column's 4dp scale for the same reason the purchase
+        // path rounds: an unrounded quantity is truncated on insert and the recomputed total then
+        // disagrees with the stored one.
+        const reversalQuantity = Math.round(Number(original.Quantity) * decision.ReversalFraction * 1e4) / 1e4;
+        if (reversalQuantity === 0) {
+            throw new Error(`The computed reversal (${decision.ReversalFraction} of quantity ${original.Quantity}) ` +
+                `rounds to zero, which is not a valid order line. Nothing can be reversed at this size.`);
+        }
+        line.Quantity = -reversalQuantity;
+        line.UnitPrice = original.UnitPrice;
+        line.DiscountPct = original.DiscountPct ?? 0;
+        line.ReversesOrderLineID = original.ID;
+        line.ServicePeriodStart = decision.EffectiveDate;
+        line.ServicePeriodEnd = new Date(term.EndDate);
+        // Attached rather than assigned: `Lines` is a RelatedRecordCollection on the generated
+        // class, and `Add()` stamps OrderHeaderID and the LineNumber for us.
+        order.Lines.Add(line);
+        order.Status = 'Confirmed';
+        if (!(await order.Save())) {
+            throw new Error(`Failed to book the reversal order: ${order.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+        return { ID: order.ID, Number: order.OrderNumber };
+    }
+    async loadOriginalLine(provider, user, orderLineID) {
+        const rv = new RunView(provider);
+        const result = await rv.RunView({
+            EntityName: ORDER_LINE_ENTITY,
+            ExtraFilter: `ID='${orderLineID}'`,
+            Fields: ['ID', 'OrderHeaderID', 'ProductID', 'Quantity', 'UnitPrice', 'DiscountPct'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, user);
+        return result?.Results?.[0] ?? null;
+    }
+    async stampTerm(provider, user, termID, decision) {
+        const term = await provider.GetEntityObject(SUBSCRIPTION_TERM_ENTITY, CompositeKey.FromID(termID), user);
+        term.Status = decision.TermStatus;
+        term.CanceledAt = new Date();
+        term.CancellationEffectiveDate = decision.EffectiveDate;
+        if (!(await term.Save())) {
+            throw new Error(`Failed to stamp the term: ${term.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+    async stampSubscription(provider, user, subscriptionID, decision) {
+        const sub = await provider.GetEntityObject(SUBSCRIPTION_ENTITY, CompositeKey.FromID(subscriptionID), user);
+        sub.Status = 'Canceled';
+        sub.CanceledAt = new Date();
+        // EndDate is the ACCESS date, not the revenue date — grace is exactly the window where the
+        // customer still gets in but nothing more is earned.
+        sub.EndDate = decision.AccessThroughDate;
+        sub.AutoRenew = false;
+        if (!(await sub.Save())) {
+            throw new Error(`Failed to stamp the subscription: ${sub.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+    async logEvent(provider, user, subscriptionID, decision, reason, reversalOrderID) {
+        const event = await provider.GetEntityObject(SUBSCRIPTION_EVENT_ENTITY, user);
+        event.NewRecord();
+        event.SubscriptionID = subscriptionID;
+        event.EventType = 'Canceled';
+        event.OccurredAt = new Date();
+        event.RelatedOrderHeaderID = reversalOrderID ?? null;
+        event.EventData = JSON.stringify({
+            EffectiveDate: decision.EffectiveDate,
+            AccessThroughDate: decision.AccessThroughDate,
+            RefundAmount: decision.RefundAmount,
+            ReversalFraction: decision.ReversalFraction,
+            TermStatus: decision.TermStatus,
+            Explanation: decision.Explanation,
+            Reason: reason ?? null,
+        });
+        if (!(await event.Save())) {
+            throw new Error(`Failed to log the cancellation event: ${event.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+    /**
+     * Stored grant Status is a lie after cancel unless we revoke when access has already
+     * ended. Grace (AccessThroughDate still in the future) leaves the rows standing — the
+     * evaluator honours subscription.EndDate rather than the original ValidTo.
+     */
+    async syncGrantsOnCancel(provider, user, subscriptionID, decision, reason) {
+        await RevokeGrantsForCanceledSubscription(subscriptionID, decision.AccessThroughDate, reason ? `Subscription canceled: ${reason}` : 'Subscription canceled', provider, user);
+    }
+    /** The base behaviour, or the type's registered subclass when it names one (D45). */
+    behaviorFor(rules) {
+        if (!rules.DriverClass)
+            return new SubscriptionBehavior();
+        const driver = MJGlobal.Instance.ClassFactory.CreateInstance(SubscriptionBehavior, rules.DriverClass);
+        if (!driver) {
+            throw new Error(`Subscription type '${rules.Code}' names driver '${rules.DriverClass}', which is not registered.`);
+        }
+        return driver;
+    }
+};
+CancelSubscriptionOperation = __decorate([
+    RegisterClass(BaseRemotableOperation, 'Orders.CancelSubscription')
+], CancelSubscriptionOperation);
+export { CancelSubscriptionOperation };
+/** Tree-shaking anchor — called from the server bootstrap so the registration is retained. */
+export function LoadCancelSubscriptionOperation() {
+    // intentionally empty
+}
+//# sourceMappingURL=CancelSubscriptionOperation.js.map

package/dist/CancelSubscriptionOperation.js.map

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

package/dist/CapturePaymentOperation.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview `Orders.CapturePayment` — take a payment and allocate it, in one transaction.
+ *
+ * WHY THIS EXISTS AT ALL. A payment is a HEADER plus its ALLOCATION LINES, and
+ * `PaymentHeaderEntityServer.Lines` is a TRANSIENT collection rather than a column. CodeGen cannot
+ * emit it on the client entity, so a browser `entity.Save()` has nowhere to put the allocations.
+ * That is precisely the situation `Orders.SaveOrder` was built for, and it needs the same answer.
+ *
+ * A two-step create-then-allocate flow was rejected: between the steps there would be a captured
+ * payment with no allocations in the database — cash recorded against nothing — and any failure in
+ * the second step would leave it there permanently.
+ *
+ * READ WHAT THE ENGINE COMPUTED; DO NOT RECOMPUTE. The fee, the net, and every order rollup are
+ * read back from the saved rows. Recomputing them here would eventually disagree with the ledger,
+ * and the disagreement surfaces as a balanced journal entry for the wrong amount — which nothing
+ * downstream can catch.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server
+ */
+import { type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import { OrdersCapturePaymentOperation as OrdersCapturePaymentOperationBase, type OrdersCapturePaymentInput, type OrdersCapturePaymentOutput } from '@mj-biz-apps/orders-entities';
+export declare class CapturePaymentOperation extends OrdersCapturePaymentOperationBase {
+    protected InternalExecute(input: OrdersCapturePaymentInput, provider: IMetadataProvider, user: UserInfo): Promise<OrdersCapturePaymentOutput>;
+    /**
+     * Header + detail + allocation lines, saved ONCE.
+     *
+     * The allocations go onto the transient `Lines` collection and are written inside the header's
+     * own transaction — the whole reason this operation exists. Status is set to Captured BEFORE the
+     * save, because `savePendingLines` books from that collection and a header saved Pending would
+     * persist its lines without booking anything.
+     */
+    private writePayment;
+    /**
+     * Whether this payment's gateway settles on someone else's schedule.
+     *
+     * Asked of the DRIVER, not of configuration — see `BasePaymentProvider.SettlesAsynchronously` for
+     * why an operator must not be able to declare that ACH settles instantly.
+     *
+     * FALSE WHEN ANYTHING GOES WRONG, deliberately. A payment with no provider is a recorded one
+     * (cheque, cash) and captures immediately; a provider that cannot be resolved is a configuration
+     * fault that the save path is about to report far more clearly than a status guess here would.
+     * Defaulting to the existing behaviour keeps every rail that worked before working unchanged.
+     */
+    private settlesAsynchronously;
+    /**
+     * Read back what the engine computed.
+     *
+     * Every number here comes from the saved rows — the fee the driver decided, the rollups the
+     * triggers moved. Nothing is recalculated, because a second calculation is a second opinion, and
+     * the one that reaches the screen would not be the one in the ledger.
+     */
+    private project;
+    /** The entries this payment's allocations produced, found through accounting's D25 provenance pair. */
+    private readEntries;
+    /** Gap-conscious payment numbering — the same sequence every other capture path uses. */
+    private nextPaymentNumber;
+    private blocker;
+    private refuse;
+}
+/** Tree-shaking anchor — call from the server bootstrap so @RegisterClass is retained. */
+export declare function LoadCapturePaymentOperation(): void;
+//# sourceMappingURL=CapturePaymentOperation.d.ts.map

package/dist/CapturePaymentOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CapturePaymentOperation.d.ts","sourceRoot":"","sources":["../src/CapturePaymentOperation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAKH,KAAK,iBAAiB,EAEtB,KAAK,QAAQ,EAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACH,6BAA6B,IAAI,iCAAiC,EAOlE,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAClC,MAAM,8BAA8B,CAAC;AAiBtC,qBACa,uBAAwB,SAAQ,iCAAiC;cAC1D,eAAe,CAC3B,KAAK,EAAE,yBAAyB,EAChC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,0BAA0B,CAAC;IAmOtC;;;;;;;OAOG;YACW,YAAY;IA8F1B;;;;;;;;;;OAUG;YACW,qBAAqB;IAenC;;;;;;OAMG;YACW,OAAO;IAqErB,uGAAuG;YACzF,WAAW;IA8DzB,yFAAyF;YAC3E,iBAAiB;IAgB/B,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,MAAM;CAWjB;AAED,0FAA0F;AAC1F,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}