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

package/dist/AdvanceOrderStateOperation.js

@@ -0,0 +1,267 @@
+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;
+};
+/**
+ * @fileoverview `Orders.AdvanceOrderState` — move a booked order up the status ladder.
+ *
+ * WHAT THIS IS FOR. Back-office entry of something that has ALREADY happened: a sale taken at a
+ * counter, a shipment that went out before anyone opened the system, a migration from whatever came
+ * before. The order needs to land in its final state without a human clicking through
+ * Confirmed → Posted → Fulfilled (D17).
+ *
+ * WHAT IT REPLACED, AND WHY IT SHRANK. This was `Orders.CreateOrderInState`, which took an
+ * `OrderDraft` — a hand-maintained mirror of the order entity — created the order by delegating to
+ * `Orders.ConfirmOrder`, and only then advanced it. Both halves of that are gone: composing and
+ * booking an order is now `order.Save()` through MJ's entity graph, which runs the identical booking
+ * walk on the server subclass. What is left is the part a save cannot do, and that part is this file.
+ *
+ * WHY THE LADDER STILL NEEDS AN OPERATION. Advancing to Posted is a plain save. Advancing to
+ * Fulfilled is not: the fulfillable LINES have to be marked first, and whether the order may move at
+ * all depends on how many could not be. That is a decision over a set of rows, taken on the server,
+ * with a caller-supplied override — a save on one header has nowhere to put it.
+ *
+ * NOTHING HERE BOOKS. Journal entries, subscriptions and entitlements are the confirm's business and
+ * have already happened by the time this runs. This operation reads the ledger back only to REPORT
+ * it, so a caller can tell "advanced an order that booked" from "advanced an order that did not".
+ *
+ * @module @mj-biz-apps/orders-core-entities-server
+ */
+import { BaseRemotableOperation, RunView, } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { IsAwaitingFulfillment } from './FulfillmentBehavior.js';
+import { ORDER_HEADER_ENTITY } from './entity-names.js';
+import { RequireUUID } from './sql-guards.js';
+const ORDER_LINE_ENTITY = 'MJ_BizApps_Orders: Order Lines';
+const PRODUCT_ENTITY = 'MJ_BizApps_Orders: Products';
+const PRODUCT_TYPE_ENTITY = 'MJ_BizApps_Orders: Product Types';
+const key = (id) => (id ?? '').toLowerCase();
+const quote = (ids) => [...new Set(ids.map((i) => `'${i}'`))].join(',');
+/** The status ladder, in the order an order climbs it. */
+const LADDER = ['Draft', 'Quoted', 'Confirmed'];
+/** Where this operation will take an order. Everything else is somebody else's job. */
+const ACCEPTED_TARGETS = new Set(['Fulfilled']);
+let AdvanceOrderStateOperation = class AdvanceOrderStateOperation extends BaseRemotableOperation {
+    constructor() {
+        super(...arguments);
+        this.OperationKey = 'Orders.AdvanceOrderState';
+    }
+    async InternalExecute(input, provider, user) {
+        const target = (input?.TargetStatus ?? '').trim();
+        if (!ACCEPTED_TARGETS.has(target)) {
+            return this.refuse(target, [
+                this.blocker('UNSUPPORTED_TARGET', `'${target || '(none)'}' is not a state this operation advances to. Use Fulfilled.`, target === 'Draft' || target === 'Quoted' || target === 'Confirmed'
+                    ? 'Those states are reached by saving the order itself — set Status and call Save(). ' +
+                        'Confirmed runs the booking walk on the way through, which is where it belongs.'
+                    : 'Voiding is a separate decision about an existing order, not a rung on the ladder.'),
+            ]);
+        }
+        if (!input?.OrderHeaderID) {
+            return this.refuse(target, [this.blocker('NO_ORDER', 'An OrderHeaderID is required.')]);
+        }
+        // Reaches SQL filter text below.
+        RequireUUID(input.OrderHeaderID, 'OrderHeaderID');
+        const header = await provider.GetEntityObject(ORDER_HEADER_ENTITY, user);
+        if (!(await header.Load(input.OrderHeaderID))) {
+            return this.refuse(target, [
+                this.blocker('NOT_FOUND', `Order ${input.OrderHeaderID} could not be loaded.`),
+            ]);
+        }
+        const orderID = header.ID;
+        const status = header.Status ?? 'Draft';
+        const transitions = [];
+        let unfulfilled = 0;
+        // AN ORDER THAT HAS NOT BOOKED CANNOT BE ADVANCED.
+        if (status !== 'Confirmed') {
+            return this.refuse(target, [
+                this.blocker('NOT_CONFIRMED', `The order is ${status}. Only a Confirmed order can be advanced.`, 'Set Status to Confirmed and save the order — that runs the booking walk. Then advance it.'),
+            ], orderID, header.OrderNumber, status);
+        }
+        const rv = new RunView(provider);
+        if (header.FulfillmentStatus === 'Fulfilled') {
+            return {
+                Success: true,
+                Message: `The order is already Fulfilled.`,
+                OrderHeaderID: orderID,
+                OrderNumber: header.OrderNumber ?? null,
+                Status: 'Fulfilled',
+                RequestedStatus: target,
+                Transitions: [],
+                ...(await this.readBookedEntries(orderID, provider)),
+                UnfulfilledLineCount: 0,
+                Blockers: [],
+            };
+        }
+        // Mark the fulfillable lines FIRST.
+        unfulfilled = await this.fulfillLines(orderID, rv, provider, user);
+        if (unfulfilled > 0 && !input?.ForceFulfillment) {
+            transitions.push({
+                From: header.FulfillmentStatus ?? 'Pending',
+                To: 'Fulfilled',
+                Applied: false,
+                Reason: `${unfulfilled} fulfillable line(s) could not be marked Fulfilled. The order sits in ` +
+                    `the fulfillment queue. Set ForceFulfillment to advance anyway.`,
+            });
+            return this.stopped(orderID, header, target, header.FulfillmentStatus ?? 'Pending', transitions, unfulfilled, provider);
+        }
+        header.FulfillmentStatus = 'Fulfilled';
+        if (input?.Reason) {
+            const existing = header.Description ?? '';
+            header.Description = existing ? `${existing} — ${input.Reason}` : input.Reason;
+        }
+        const saved = await header.Save();
+        transitions.push({
+            From: 'Pending',
+            To: 'Fulfilled',
+            Applied: saved,
+            Reason: saved && unfulfilled > 0
+                ? `Forced with ${unfulfilled} line(s) still Pending.`
+                : header.LatestResult?.CompleteMessage ?? null,
+        });
+        const booked = await this.readBookedEntries(orderID, provider);
+        return {
+            Success: saved,
+            Message: saved ? undefined : `The order could not be advanced to Fulfilled: ${header.LatestResult?.CompleteMessage ?? 'Save failed'}`,
+            OrderHeaderID: orderID,
+            OrderNumber: header.OrderNumber ?? null,
+            Status: saved ? 'Fulfilled' : (header.FulfillmentStatus ?? 'Pending'),
+            RequestedStatus: target,
+            Transitions: transitions,
+            EntryCount: booked.EntryCount,
+            AllBalanced: booked.AllBalanced,
+            UnfulfilledLineCount: unfulfilled,
+            Blockers: [],
+        };
+    }
+    /**
+     * What booked against this order's lines, read back rather than assumed.
+     *
+     * The confirm happened on a different call — possibly on a different day, for a migration — so
+     * this operation has no first-hand knowledge of it. Reporting zero entries because nobody looked
+     * is indistinguishable from an order that never booked, and this whole file exists to keep those
+     * two apart.
+     */
+    async readBookedEntries(orderID, provider) {
+        const rows = (await provider.ExecuteSQL(`
+              SELECT je.ID AS EntryID,
+                     SUM(ISNULL(jel.DebitAmount, 0)) AS D,
+                     SUM(ISNULL(jel.CreditAmount, 0)) AS C
+                FROM __mj_BizAppsAccounting.JournalEntry je
+                JOIN __mj_BizAppsAccounting.JournalEntryLine jel ON jel.JournalEntryID = je.ID
+               WHERE je.LinkedRecordID IN (
+                     SELECT CAST(ol.ID AS NVARCHAR(400)) FROM __mj_BizAppsOrders.OrderLine ol
+                      WHERE ol.OrderHeaderID = '${orderID}')
+               GROUP BY je.ID`)) ?? [];
+        return {
+            EntryCount: rows.length,
+            AllBalanced: rows.every((r) => Math.abs(Number(r.D) - Number(r.C)) < 0.005),
+        };
+    }
+    /** Move the header, reporting a refusal rather than throwing — a stalled advance is still a result. */
+    async setStatus(header, 
+    // Derived from the entity: `Status` is CHECK-constrained, so CodeGen owns this union and it
+    // widens with the constraint. Restating it here would freeze it at today's six values.
+    status, reason) {
+        header.Status = status;
+        if (reason) {
+            const existing = header.Description ?? '';
+            header.Description = existing ? `${existing} — ${reason}` : reason;
+        }
+        if (!(await header.Save())) {
+            return { ok: false, reason: header.LatestResult?.CompleteMessage ?? 'no reason given' };
+        }
+        return { ok: true, reason: null };
+    }
+    /**
+     * Mark every line that is awaiting fulfilment, and report how many would not go.
+     *
+     * The three lookups are per-order rather than per-line on purpose: a migration advances orders in
+     * bulk, and a per-line product/type round trip turns a hundred-line order into three hundred
+     * queries.
+     */
+    async fulfillLines(orderID, rv, provider, user) {
+        const lines = await rv.RunView({ EntityName: ORDER_LINE_ENTITY, ExtraFilter: `OrderHeaderID = '${orderID}'`, ResultType: 'simple' }, user);
+        const rows = lines.Results ?? [];
+        if (!rows.length)
+            return 0;
+        const products = await rv.RunView({
+            EntityName: PRODUCT_ENTITY,
+            ExtraFilter: `ID IN (${quote(rows.map((l) => l.ProductID))})`,
+            ResultType: 'simple',
+        }, user);
+        const typeIDs = [...new Set((products.Results ?? []).map((p) => p.ProductTypeID))].filter(Boolean);
+        const types = typeIDs.length
+            ? await rv.RunView({ EntityName: PRODUCT_TYPE_ENTITY, ExtraFilter: `ID IN (${quote(typeIDs)})`, ResultType: 'simple' }, user)
+            : { Results: [] };
+        const requiresByType = new Map((types.Results ?? []).map((t) => [key(t.ID), !!t.RequiresFulfillment]));
+        const typeByProduct = new Map((products.Results ?? []).map((p) => [key(p.ID), key(p.ProductTypeID)]));
+        let remaining = 0;
+        for (const row of rows) {
+            const shaped = {
+                ID: row.ID,
+                RequiresFulfillment: requiresByType.get(typeByProduct.get(key(row.ProductID)) ?? '') ?? false,
+                FulfillmentStatus: row.FulfillmentStatus ?? null,
+                ReversesOrderLineID: row.ReversesOrderLineID,
+                IsRollupParent: !!row.IsRollupParent,
+            };
+            if (!IsAwaitingFulfillment(shaped))
+                continue;
+            const entity = await provider.GetEntityObject(ORDER_LINE_ENTITY, user);
+            if (!(await entity.Load(row.ID))) {
+                remaining++;
+                continue;
+            }
+            entity.FulfillmentStatus = 'Fulfilled';
+            if (!(await entity.Save()))
+                remaining++;
+        }
+        return remaining;
+    }
+    /** The order is booked and moved as far as it could, but not as far as asked. */
+    async stopped(orderID, header, target, status, transitions, unfulfilled, provider) {
+        return {
+            Success: false,
+            Message: `The order stopped at ${status} rather than ${target}.`,
+            OrderHeaderID: orderID,
+            OrderNumber: header.OrderNumber ?? null,
+            Status: status,
+            RequestedStatus: target,
+            Transitions: transitions,
+            ...(await this.readBookedEntries(orderID, provider)),
+            UnfulfilledLineCount: unfulfilled,
+            Blockers: [],
+        };
+    }
+    blocker(code, message, hint) {
+        return { Code: code, Message: message, ResolutionHint: hint ?? null, LineNumber: null };
+    }
+    refuse(target, blockers, orderID = null, orderNumber = null, status = null) {
+        return {
+            Success: false,
+            Message: blockers.map((b) => b.Message).join(' '),
+            OrderHeaderID: orderID,
+            OrderNumber: orderNumber,
+            Status: status,
+            RequestedStatus: target,
+            Transitions: [],
+            EntryCount: 0,
+            AllBalanced: true,
+            UnfulfilledLineCount: 0,
+            Blockers: blockers,
+        };
+    }
+};
+AdvanceOrderStateOperation = __decorate([
+    RegisterClass(BaseRemotableOperation, 'Orders.AdvanceOrderState')
+], AdvanceOrderStateOperation);
+export { AdvanceOrderStateOperation };
+/**
+ * Force the class registration. Tree-shaking removes a class nobody imports, and the decorator only
+ * runs if the module is loaded — so the server's bootstrap calls this.
+ */
+export function LoadAdvanceOrderStateOperation() {
+    // no-op by design
+}
+//# sourceMappingURL=AdvanceOrderStateOperation.js.map

package/dist/AdvanceOrderStateOperation.js.map

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

package/dist/ApplyAccountCreditOperation.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Orders.ApplyAccountCredit — spend an order's credit balance on another order (plan D68).
+ *
+ * WHAT AN ACCOUNT CREDIT IS
+ * Not a separate instrument. When a customer pays more than an order is worth, the surplus stays on
+ * that order as a NEGATIVE balance, and that negative balance IS the credit. Nothing else holds it —
+ * deliberately, because a second record carrying the same balance is a second thing that can
+ * disagree with the first. (A gift card is different: `StoredValueAccount` exists because nothing
+ * else could hold that money.)
+ *
+ * WHAT THIS OPERATION WRITES
+ * A payment whose `Amount` is ZERO, carrying two offsetting allocations:
+ *
+ *     Payment PAY-000042   Amount 0.00   type AccountCredit
+ *       PaymentDetail.SourceOrderHeaderID = <the credit order>
+ *       line 1:  <credit order>   -100.00     the credit is consumed
+ *       line 2:  <target order>   +100.00     and lands here
+ *                        SUM = 0.00  ==  Amount
+ *
+ * Zero is not a degenerate case here, it is the truth: no new cash entered the business. The money
+ * arrived earlier, on the payment that over-paid the first order; this only re-attributes it. The
+ * D68 invariant (`Amount` = sum of lines) therefore holds exactly, with nothing special-cased.
+ *
+ * WHY NOT JUST EDIT THE ORIGINAL PAYMENT'S LINES
+ * Because a credit is not always traceable to one payment — it can accumulate from several, or
+ * survive a partial refund — and because a captured payment is frozen (51005/51010/51011). Rewriting
+ * history to express a new event would destroy the audit trail of money that genuinely moved.
+ *
+ * THE LEDGER FALLS OUT OF THE EXISTING MACHINERY
+ * `PaymentLineEntityServer` already books each allocation and already treats a negative amount as a
+ * reversal, so the two lines produce a mirrored pair and an ordinary pair:
+ *
+ *     credit order:   Dr A/R 100        Cr Cash 100     (mirrored — the reversal)
+ *     target order:   Dr Cash 100       Cr A/R 100
+ *
+ * Cash nets to zero across them; A/R moves from one order to the other. No new booking code exists
+ * for this operation, and none should — if it needed its own entries, that would mean the allocation
+ * path did not really understand negative applications.
+ *
+ * CROSS-COMPANY IS NOT A SPECIAL CASE EITHER. When the two orders belong to different companies the
+ * same path raises the intercompany legs, because the allocation factory splits per owning company.
+ * Note this is not merely convenient: a single `Dr A/R / Cr A/R` entry spanning two companies could
+ * not be booked at all (accounting refuses cross-company entries, D6), so the per-company shape is
+ * the only bookable form rather than an implementation preference.
+ *
+ * FAILURE MODEL: logical refusals come back INSIDE the output as `Success: false` with a reason —
+ * the same contract `Orders.RefundPayment` and `Orders.CancelSubscription` use. Only genuine faults
+ * throw.
+ *
+ * CONNECTS TO:
+ *   BOOKING: PaymentLineEntityServer.Save — both legs book through the ordinary allocation path
+ *   TABLES:  __mj_BizAppsOrders.{PaymentHeader,PaymentLine,PaymentDetail,OrderHeader}
+ *   DOC:     plans/archive/bizapps-orders-master.md D68
+ */
+import { BaseRemotableOperation, IMetadataProvider, UserInfo } from '@memberjunction/core';
+export interface ApplyAccountCreditInput {
+    /** The order carrying the credit (its Balance is negative). */
+    SourceOrderHeaderID: string;
+    /** The order to spend it on. */
+    TargetOrderHeaderID: string;
+    /** Omit to apply as much as both sides allow. */
+    Amount?: number;
+    Reason?: string;
+    /** Compute and validate without writing — for a confirmation screen. */
+    Preview?: boolean;
+}
+export interface ApplyAccountCreditOutput {
+    Success: boolean;
+    Message?: string;
+    /** What was (or would be) applied. */
+    AppliedAmount?: number;
+    /** The source order's credit still available AFTER this application. */
+    RemainingCredit?: number;
+    /** The target order's balance AFTER this application. */
+    TargetBalanceAfter?: number;
+    PaymentHeaderID?: string;
+    PaymentNumber?: string;
+}
+export declare class ApplyAccountCreditOperation extends BaseRemotableOperation<ApplyAccountCreditInput, ApplyAccountCreditOutput> {
+    OperationKey: string;
+    protected InternalExecute(input: ApplyAccountCreditInput, provider: IMetadataProvider, user: UserInfo): Promise<ApplyAccountCreditOutput>;
+    private loadOrder;
+    /**
+     * The `AccountCredit` tender's ID.
+     *
+     * Cache first, then the query it always did. The row is seeded metadata and the cache answers it
+     * without a round trip; the fallback stays because a deployment that has not seeded this tender
+     * yet, or one that added it in the transaction now running, must still resolve it — and the
+     * caller's whole operation depends on finding it.
+     */
+    private accountCreditTypeID;
+    /** Gap-free payment numbering, same sequence the capture path uses. */
+    private nextPaymentNumber;
+}
+/** Tree-shaking anchor — called from the server bootstrap so the registration is retained. */
+export declare function LoadApplyAccountCreditOperation(): void;
+//# sourceMappingURL=ApplyAccountCreditOperation.d.ts.map

package/dist/ApplyAccountCreditOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApplyAccountCreditOperation.d.ts","sourceRoot":"","sources":["../src/ApplyAccountCreditOperation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,EAEH,sBAAsB,EAEtB,iBAAiB,EAIjB,QAAQ,EACX,MAAM,sBAAsB,CAAC;AAsB9B,MAAM,WAAW,uBAAuB;IACpC,+DAA+D;IAC/D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gCAAgC;IAChC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAaD,qBACa,2BAA4B,SAAQ,sBAAsB,CAAC,uBAAuB,EAAE,wBAAwB,CAAC;IAC/G,YAAY,SAA+B;cAElC,eAAe,CAC3B,KAAK,EAAE,uBAAuB,EAC9B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,wBAAwB,CAAC;YA2JtB,SAAS;IAevB;;;;;;;OAOG;YACW,mBAAmB;IAmBjC,uEAAuE;YACzD,iBAAiB;CAelC;AAED,8FAA8F;AAC9F,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}

package/dist/ApplyAccountCreditOperation.js

@@ -0,0 +1,275 @@
+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.ApplyAccountCredit — spend an order's credit balance on another order (plan D68).
+ *
+ * WHAT AN ACCOUNT CREDIT IS
+ * Not a separate instrument. When a customer pays more than an order is worth, the surplus stays on
+ * that order as a NEGATIVE balance, and that negative balance IS the credit. Nothing else holds it —
+ * deliberately, because a second record carrying the same balance is a second thing that can
+ * disagree with the first. (A gift card is different: `StoredValueAccount` exists because nothing
+ * else could hold that money.)
+ *
+ * WHAT THIS OPERATION WRITES
+ * A payment whose `Amount` is ZERO, carrying two offsetting allocations:
+ *
+ *     Payment PAY-000042   Amount 0.00   type AccountCredit
+ *       PaymentDetail.SourceOrderHeaderID = <the credit order>
+ *       line 1:  <credit order>   -100.00     the credit is consumed
+ *       line 2:  <target order>   +100.00     and lands here
+ *                        SUM = 0.00  ==  Amount
+ *
+ * Zero is not a degenerate case here, it is the truth: no new cash entered the business. The money
+ * arrived earlier, on the payment that over-paid the first order; this only re-attributes it. The
+ * D68 invariant (`Amount` = sum of lines) therefore holds exactly, with nothing special-cased.
+ *
+ * WHY NOT JUST EDIT THE ORIGINAL PAYMENT'S LINES
+ * Because a credit is not always traceable to one payment — it can accumulate from several, or
+ * survive a partial refund — and because a captured payment is frozen (51005/51010/51011). Rewriting
+ * history to express a new event would destroy the audit trail of money that genuinely moved.
+ *
+ * THE LEDGER FALLS OUT OF THE EXISTING MACHINERY
+ * `PaymentLineEntityServer` already books each allocation and already treats a negative amount as a
+ * reversal, so the two lines produce a mirrored pair and an ordinary pair:
+ *
+ *     credit order:   Dr A/R 100        Cr Cash 100     (mirrored — the reversal)
+ *     target order:   Dr Cash 100       Cr A/R 100
+ *
+ * Cash nets to zero across them; A/R moves from one order to the other. No new booking code exists
+ * for this operation, and none should — if it needed its own entries, that would mean the allocation
+ * path did not really understand negative applications.
+ *
+ * CROSS-COMPANY IS NOT A SPECIAL CASE EITHER. When the two orders belong to different companies the
+ * same path raises the intercompany legs, because the allocation factory splits per owning company.
+ * Note this is not merely convenient: a single `Dr A/R / Cr A/R` entry spanning two companies could
+ * not be booked at all (accounting refuses cross-company entries, D6), so the per-company shape is
+ * the only bookable form rather than an implementation preference.
+ *
+ * FAILURE MODEL: logical refusals come back INSIDE the output as `Success: false` with a reason —
+ * the same contract `Orders.RefundPayment` and `Orders.CancelSubscription` use. Only genuine faults
+ * throw.
+ *
+ * CONNECTS TO:
+ *   BOOKING: PaymentLineEntityServer.Save — both legs book through the ordinary allocation path
+ *   TABLES:  __mj_BizAppsOrders.{PaymentHeader,PaymentLine,PaymentDetail,OrderHeader}
+ *   DOC:     plans/archive/bizapps-orders-master.md D68
+ */
+import { BaseRemotableOperation, LogError, RunView, } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { RequireUUID } from './sql-guards.js';
+import { LoadOrdersEngine, OrdersEngine } from '@mj-biz-apps/orders-entities';
+const PAYMENT_HEADER_ENTITY = 'MJ_BizApps_Orders: Payment Headers';
+const PAYMENT_LINE_ENTITY = 'MJ_BizApps_Orders: Payment Lines';
+const PAYMENT_DETAIL_ENTITY = 'MJ_BizApps_Orders: Payment Details';
+const PAYMENT_TYPE_ENTITY = 'MJ_BizApps_Orders: Payment Types';
+const ORDER_HEADER_ENTITY = 'MJ_BizApps_Orders: Order Headers';
+/** The payment type this operation writes. Seeded in metadata/payment-types. */
+const ACCOUNT_CREDIT_TYPE_CODE = 'AccountCredit';
+/** Half a cent — the same tolerance the allocation guard uses. */
+const TOLERANCE = 0.005;
+const money = (v) => Math.round((v + Number.EPSILON) * 100) / 100;
+let ApplyAccountCreditOperation = class ApplyAccountCreditOperation extends BaseRemotableOperation {
+    constructor() {
+        super(...arguments);
+        this.OperationKey = 'Orders.ApplyAccountCredit';
+    }
+    async InternalExecute(input, provider, user) {
+        if (!input?.SourceOrderHeaderID || !input?.TargetOrderHeaderID) {
+            return { Success: false, Message: 'Both SourceOrderHeaderID and TargetOrderHeaderID are required.' };
+        }
+        // Caller-supplied ids reach SQL filter text downstream. Validated here,
+        // at the boundary, so every frame below this one can trust them.
+        RequireUUID(input.SourceOrderHeaderID, 'SourceOrderHeaderID');
+        RequireUUID(input.TargetOrderHeaderID, 'TargetOrderHeaderID');
+        if (input.SourceOrderHeaderID.toLowerCase() === input.TargetOrderHeaderID.toLowerCase()) {
+            return {
+                Success: false,
+                Message: 'The source and target orders are the same. Moving a credit onto the order that already holds it would change nothing.',
+            };
+        }
+        const source = await this.loadOrder(provider, user, input.SourceOrderHeaderID);
+        if (!source)
+            return { Success: false, Message: `Order ${input.SourceOrderHeaderID} was not found.` };
+        const target = await this.loadOrder(provider, user, input.TargetOrderHeaderID);
+        if (!target)
+            return { Success: false, Message: `Order ${input.TargetOrderHeaderID} was not found.` };
+        // The credit is the source order's negative balance, expressed positive.
+        const available = money(-Number(source.Balance ?? 0));
+        if (available <= TOLERANCE) {
+            return {
+                Success: false,
+                Message: `Order ${source.OrderNumber} has no credit to spend — its balance is ${money(Number(source.Balance ?? 0))}. ` +
+                    `A credit exists only when an order has been paid MORE than it is worth, which shows as a negative balance.`,
+            };
+        }
+        // Nothing to pay toward is a refusal rather than a no-op: the caller believes it is settling
+        // something, and silently writing a zero-value payment would hide that it did not.
+        const owing = money(Number(target.Balance ?? 0));
+        if (owing <= TOLERANCE) {
+            return {
+                Success: false,
+                Message: `Order ${target.OrderNumber} has nothing outstanding (balance ${owing}), so there is nothing to apply the credit to.`,
+            };
+        }
+        // Default to as much as both sides allow; an explicit amount is checked against both.
+        const requested = input.Amount === undefined ? Math.min(available, owing) : money(Number(input.Amount));
+        if (!(requested > TOLERANCE)) {
+            return { Success: false, Message: `Amount must be greater than zero (received ${input.Amount}).` };
+        }
+        if (requested > available + TOLERANCE) {
+            return {
+                Success: false,
+                Message: `Order ${source.OrderNumber} only has ${available} of credit; ${requested} was requested.`,
+            };
+        }
+        if (requested > owing + TOLERANCE) {
+            return {
+                Success: false,
+                Message: `Order ${target.OrderNumber} only owes ${owing}; applying ${requested} would over-pay it. ` +
+                    `Apply ${owing} instead, or spend the rest of the credit on another order.`,
+            };
+        }
+        const remainingCredit = money(available - requested);
+        const targetBalanceAfter = money(owing - requested);
+        if (input.Preview) {
+            return {
+                Success: true,
+                Message: `${requested} of order ${source.OrderNumber}'s credit would settle order ${target.OrderNumber}, ` +
+                    `leaving ${remainingCredit} of credit and a balance of ${targetBalanceAfter}.`,
+                AppliedAmount: requested,
+                RemainingCredit: remainingCredit,
+                TargetBalanceAfter: targetBalanceAfter,
+            };
+        }
+        const typeID = await this.accountCreditTypeID(provider, user);
+        if (!typeID) {
+            return {
+                Success: false,
+                Message: `The '${ACCOUNT_CREDIT_TYPE_CODE}' payment type is not present. Push metadata/payment-types before applying credits.`,
+            };
+        }
+        const db = provider;
+        await db.BeginTransaction();
+        try {
+            const detail = await provider.GetEntityObject(PAYMENT_DETAIL_ENTITY, user);
+            detail.NewRecord();
+            detail.CompanyID = target.CompanyID;
+            detail.PaymentTypeID = typeID;
+            detail.SourceOrderHeaderID = source.ID;
+            detail.Notes = input.Reason ?? `Credit from order ${source.OrderNumber}`;
+            if (!(await detail.Save())) {
+                throw new Error(`Could not record the credit tender: ${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+            const payment = await provider.GetEntityObject(PAYMENT_HEADER_ENTITY, user);
+            payment.NewRecord();
+            const paymentNumber = await this.nextPaymentNumber(db);
+            payment.PaymentNumber = paymentNumber;
+            payment.ReceivingCompanyID = target.CompanyID;
+            payment.PaymentTypeID = typeID;
+            payment.PaymentDetailID = detail.ID;
+            // ZERO on purpose — no new cash entered the business, this re-attributes money already
+            // received. The D68 invariant holds exactly: 0 == (-requested) + (+requested).
+            payment.Amount = 0;
+            payment.ProcessingFeeAmount = 0;
+            payment.PaymentDate = new Date();
+            payment.Status = 'Captured';
+            payment.Notes = input.Reason ?? `Applied ${requested} of order ${source.OrderNumber}'s credit`;
+            // Both legs ride the header's Lines collection so they land inside this transaction and
+            // the invariant is checked against the pair, never against a half-written payment.
+            const consume = await provider.GetEntityObject(PAYMENT_LINE_ENTITY, user);
+            consume.NewRecord();
+            consume.OrderHeaderID = source.ID;
+            consume.Amount = -requested;
+            consume.AllocatedByUserID = user?.ID ?? null;
+            const apply = await provider.GetEntityObject(PAYMENT_LINE_ENTITY, user);
+            apply.NewRecord();
+            apply.OrderHeaderID = target.ID;
+            apply.Amount = requested;
+            apply.AllocatedByUserID = user?.ID ?? null;
+            // Attached, not assigned: `Lines` is a RelatedRecordCollection and `Add()` stamps
+            // PaymentHeaderID for us — correct even though the header has not been saved yet.
+            payment.Lines.Add(consume);
+            payment.Lines.Add(apply);
+            if (!(await payment.Save())) {
+                throw new Error(`Could not save the credit application: ${payment.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+            await db.CommitTransaction();
+            return {
+                Success: true,
+                Message: `Applied ${requested} of order ${source.OrderNumber}'s credit to order ${target.OrderNumber} as ${paymentNumber}.`,
+                AppliedAmount: requested,
+                RemainingCredit: remainingCredit,
+                TargetBalanceAfter: targetBalanceAfter,
+                PaymentHeaderID: payment.ID,
+                PaymentNumber: paymentNumber,
+            };
+        }
+        catch (err) {
+            await db.RollbackTransaction();
+            LogError(err);
+            throw err;
+        }
+    }
+    async loadOrder(provider, user, id) {
+        const rv = new RunView(provider);
+        const res = await rv.RunView({
+            EntityName: ORDER_HEADER_ENTITY,
+            ExtraFilter: `ID='${id}'`,
+            Fields: ['ID', 'OrderNumber', 'Status', 'Balance', 'TotalGross', 'CompanyID'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, user);
+        return res?.Results?.[0] ?? null;
+    }
+    /**
+     * The `AccountCredit` tender's ID.
+     *
+     * Cache first, then the query it always did. The row is seeded metadata and the cache answers it
+     * without a round trip; the fallback stays because a deployment that has not seeded this tender
+     * yet, or one that added it in the transaction now running, must still resolve it — and the
+     * caller's whole operation depends on finding it.
+     */
+    async accountCreditTypeID(provider, user) {
+        await LoadOrdersEngine(provider, user);
+        const cached = OrdersEngine.Instance.PaymentTypeByCode(ACCOUNT_CREDIT_TYPE_CODE);
+        if (cached?.ID)
+            return cached.ID;
+        const rv = new RunView(provider);
+        const res = await rv.RunView({
+            EntityName: PAYMENT_TYPE_ENTITY,
+            ExtraFilter: `Code='${ACCOUNT_CREDIT_TYPE_CODE}'`,
+            Fields: ['ID'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, user);
+        return res?.Results?.[0]?.ID ?? null;
+    }
+    /** Gap-free payment numbering, same sequence the capture path uses. */
+    async nextPaymentNumber(db) {
+        const rows = (await db.ExecuteSQL(`
+            DECLARE @seq TABLE (Seq INT);
+            UPDATE __mj_BizAppsOrders.PaymentSequence WITH (UPDLOCK, HOLDLOCK)
+            SET NextSequenceNumber = NextSequenceNumber + 1
+            OUTPUT deleted.NextSequenceNumber INTO @seq(Seq)
+            WHERE ID = 1;
+            SELECT Seq FROM @seq;`));
+        const seq = rows?.[0]?.Seq;
+        if (!seq) {
+            throw new Error('Could not obtain the next payment number — PaymentSequence (ID=1) is missing.');
+        }
+        return `PAY-${String(seq).padStart(6, '0')}`;
+    }
+};
+ApplyAccountCreditOperation = __decorate([
+    RegisterClass(BaseRemotableOperation, 'Orders.ApplyAccountCredit')
+], ApplyAccountCreditOperation);
+export { ApplyAccountCreditOperation };
+/** Tree-shaking anchor — called from the server bootstrap so the registration is retained. */
+export function LoadApplyAccountCreditOperation() {
+    // intentionally empty
+}
+//# sourceMappingURL=ApplyAccountCreditOperation.js.map