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

package/dist/PaymentSettlement.js

@@ -0,0 +1,243 @@
+/**
+ * Promoting a bank debit into cash — the only place a webhook is allowed to move money.
+ *
+ * WHY THIS EXISTS AT ALL. `PaymentWebhookHandler` was written deliberately narrow: it records what the
+ * gateway said on the `PaymentIntent` and stops there, because a webhook reaching into the ledger
+ * would give an unauthenticated endpoint a second path into the books. That was exactly right for
+ * cards, where the money has already moved by the time anyone asks and the event only confirms it.
+ *
+ * A bank debit breaks the assumption underneath it. Nothing has moved when the caller asks; the answer
+ * arrives days later, in an event, and there is no other moment at which cash can honestly be booked.
+ * So the webhook has to be able to move money — and this module is that capability, kept in one file,
+ * reachable only when a driver has declared `SettlesAsynchronously`, and doing exactly three things.
+ *
+ * IT DOES NOT BOOK ANYTHING ITSELF. That is the part worth being clear about. `Promote` sets a status
+ * and saves; `PaymentHeaderEntityServer` notices the transition into `Captured` and books the cash
+ * through the same path a card capture uses — including calling back to the driver to ask what
+ * actually moved. `Reverse` writes a reversing payment through the same factory `Orders.RefundPayment`
+ * uses. Nothing here writes a journal entry, and nothing here knows how one is shaped. The ledger keeps
+ * a single author.
+ *
+ * ORDERING MATTERS, AND IT IS NOT THE OBVIOUS ONE. This runs BEFORE the handler stamps
+ * `PaymentIntent.ProviderEventID`, not after. Stamping first would look tidier and would silently
+ * strand payments: the stamp is the idempotency key, so an event that was recorded and then failed to
+ * settle would be judged `AlreadyApplied` on every retry, and a payment the bank confirmed would sit
+ * `Pending` forever with nothing left to move it. Settling first means a failure returns 500 with
+ * nothing stamped, the gateway retries, and both steps run again. The re-run is safe because
+ * `DecideSettlement` reads the PAYMENT'S state rather than the event's novelty — a promotion that
+ * already happened decides `None`.
+ *
+ * CONNECTS TO:
+ *   PURE:    ./PaymentProviderBehavior.ts — DecideSettlement, the decision table
+ *   ROUTE:   ./PaymentWebhookHandler.ts — the only caller
+ *   WRITES:  ./PaymentHeaderEntityServer.ts (promote) · ./PaymentReversalFactory.ts (reverse)
+ *   DOC:     plans/archive/bizapps-orders-master.md D17, D19, D53
+ */
+import { CompositeKey, LogError, LogStatus, RunView, } from '@memberjunction/core';
+import { DecideSettlement } from './PaymentProviderBehavior.js';
+import { BuildUnapplyLines, CreateReversingPayment, LoadAppliedAllocations, } from './PaymentReversalFactory.js';
+const PAYMENT_HEADER_ENTITY = 'MJ_BizApps_Orders: Payment Headers';
+const PAYMENT_LINE_ENTITY = 'MJ_BizApps_Orders: Payment Lines';
+/**
+ * Apply a settlement event to the payment behind its intent.
+ *
+ * THROWS ON FAULTS, DELIBERATELY. A refusal here is not a business outcome to be reported and
+ * forgotten — it means the bank told us something about real money and we failed to record it. The
+ * caller turns a throw into a 500 so the gateway asks again, which is the only way that notice is not
+ * lost. Decisions that legitimately do nothing (`None`, `Hold`) return normally.
+ */
+export async function SettlePaymentForEvent(event, paymentIntentID, provider, user) {
+    const payment = await loadPaymentForIntent(provider, user, paymentIntentID);
+    const alreadyReversed = payment ? await hasReversal(provider, user, payment.ID) : false;
+    // WHETHER THIS PAYMENT PUT CASH IN THE LEDGER IS A QUESTION ABOUT ITS ALLOCATIONS, NOT ITS HEADER.
+    //
+    // This read used to be `Boolean(payment.JournalEntryID)`, and that stopped being the same question
+    // twice over. The cash leg moved to the allocation (D13), so the header's journal entry is only
+    // ever the PROCESSING FEE — and D82 turned the fee entry off for every tender by default. Between
+    // them, `JournalEntryID` is now null on essentially every payment that ever books.
+    //
+    // The decision table reads `HeaderBooked` to choose between reversing a returned debit and holding
+    // it for a person ("Captured but carries no journal entry, so what to reverse is unclear"). With
+    // the old signal every returned ACH debit took the Hold branch: the cash stayed in the ledger, the
+    // order stayed marked paid, and the only outward sign was a settlement waiting on a human who was
+    // never told. Asking the allocations restores the question the table was written to ask.
+    const booked = payment ? await hasBookedAllocations(provider, user, payment.ID) : false;
+    const decision = DecideSettlement({
+        EventStatus: event.Status,
+        HeaderStatus: payment?.Status,
+        HeaderBooked: booked,
+        AlreadyReversed: alreadyReversed,
+    });
+    const base = {
+        Action: decision.Action,
+        Reason: decision.Reason,
+        PaymentHeaderID: payment?.ID,
+    };
+    switch (decision.Action) {
+        case 'Promote':
+            await promote(provider, user, payment, event);
+            LogStatus(`Payment ${payment.PaymentNumber} captured from bank-debit event ${event.EventID}.`);
+            return base;
+        case 'Fail':
+            await markFailed(provider, user, payment, event);
+            LogStatus(`Payment ${payment.PaymentNumber} failed from bank-debit event ${event.EventID}` +
+                `${event.FailureReason ? ` (${event.FailureReason})` : ''}.`);
+            return base;
+        case 'Reverse': {
+            const reversalID = await reverse(provider, user, payment, event);
+            LogStatus(`Payment ${payment.PaymentNumber} was returned by the bank and has been reversed ` +
+                `from event ${event.EventID}.`);
+            return { ...base, ReversalPaymentHeaderID: reversalID };
+        }
+        case 'Hold':
+            // LOUD, because nothing else will be. A held event is money whose state we have declined to
+            // guess at, and the only thing standing between that and a silent discrepancy is this line.
+            LogError(`Bank-debit event ${event.EventID} was NOT applied to payment ` +
+                `${payment?.PaymentNumber ?? '(none)'}: ${decision.Reason}. This needs a person.`);
+            return base;
+        default:
+            LogStatus(`Bank-debit event ${event.EventID}: ${decision.Reason}`);
+            return base;
+    }
+}
+// ─── Reads ─────────────────────────────────────────────────────────────────────────────────────
+async function loadPaymentForIntent(provider, user, paymentIntentID) {
+    const rv = new RunView(provider);
+    const result = await rv.RunView({
+        EntityName: PAYMENT_HEADER_ENTITY,
+        ExtraFilter: `PaymentIntentID='${paymentIntentID}'`,
+        Fields: [
+            'ID',
+            'PaymentNumber',
+            'ReceivingCompanyID',
+            'BillToOrganizationID',
+            'BillToPersonID',
+            'PaymentTypeID',
+            'PaymentDetailID',
+            'Amount',
+            'Status',
+            'JournalEntryID',
+        ],
+        ResultType: 'simple',
+        // The status is the whole decision, and it may have been written by the previous delivery
+        // of a related event moments ago. A cached read here re-promotes an already-captured
+        // payment or reverses one twice.
+        BypassCache: true,
+    }, user);
+    return result?.Results?.[0] ?? null;
+}
+/**
+ * True when any of this payment's allocations has booked — i.e. the cash is in the ledger.
+ *
+ * `PaymentLine.BookedAt` is the allocation's own idempotency key, set in the same transaction that
+ * writes its journal entry, so it is the authority on whether the money exists. Reading one booked
+ * row is enough: allocations book together with the capture.
+ *
+ * `BypassCache` for the same reason the header read has it — the promotion that booked these lines
+ * may have happened moments ago, on a previous delivery of a related event.
+ */
+async function hasBookedAllocations(provider, user, paymentID) {
+    const rv = new RunView(provider);
+    const result = await rv.RunView({
+        EntityName: PAYMENT_LINE_ENTITY,
+        ExtraFilter: `PaymentHeaderID='${paymentID}' AND BookedAt IS NOT NULL`,
+        Fields: ['ID'],
+        MaxRows: 1,
+        ResultType: 'simple',
+        BypassCache: true,
+    }, user);
+    return (result?.Results?.length ?? 0) > 0;
+}
+/** True when a reversing payment already points at this one. */
+async function hasReversal(provider, user, paymentID) {
+    const rv = new RunView(provider);
+    const result = await rv.RunView({
+        EntityName: PAYMENT_HEADER_ENTITY,
+        ExtraFilter: `ReversesPaymentHeaderID='${paymentID}' AND Status='Refunded'`,
+        Fields: ['ID'],
+        ResultType: 'simple',
+        BypassCache: true,
+    }, user);
+    return (result?.Results?.length ?? 0) > 0;
+}
+// ─── Writes ────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Pending → Captured, which is what books the cash.
+ *
+ * NOTHING IS SET BUT THE STATUS. `PaymentHeaderEntityServer` calls the driver on this transition to
+ * ask what actually moved, and overwrites `Amount`, `ProcessingFeeAmount` and `NetAmount` from the
+ * answer. Setting them from the webhook payload here would put our reading of the event in a race with
+ * the gateway's own record of the charge — and the gateway wins that argument every time, so writing
+ * ours would be work whose only possible outcome is being overwritten or being wrong.
+ */
+async function promote(provider, user, payment, event) {
+    const header = await provider.GetEntityObject(PAYMENT_HEADER_ENTITY, CompositeKey.FromID(payment.ID), user);
+    header.Status = 'Captured';
+    if (!(await header.Save())) {
+        throw new Error(`Could not capture payment ${payment.PaymentNumber} from event ${event.EventID}: ` +
+            `${header.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    }
+}
+/**
+ * Pending → Failed. Nothing was booked, so nothing needs reversing.
+ *
+ * The bank's own words go on `Notes` rather than `ReversalReason` — that column belongs to reversals,
+ * and a failed payment did not reverse anything. Appending rather than replacing keeps whatever a
+ * person had already written there.
+ */
+async function markFailed(provider, user, payment, event) {
+    const header = await provider.GetEntityObject(PAYMENT_HEADER_ENTITY, CompositeKey.FromID(payment.ID), user);
+    header.Status = 'Failed';
+    if (event.FailureReason) {
+        const existing = header.Notes ?? '';
+        const note = `Bank debit did not clear: ${event.FailureReason}`;
+        header.Notes = existing ? `${existing}\n${note}` : note;
+    }
+    if (!(await header.Save())) {
+        throw new Error(`Could not mark payment ${payment.PaymentNumber} as failed from event ${event.EventID}: ` +
+            `${header.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    }
+}
+/**
+ * Captured → reversed by a new payment, because the bank took the money back.
+ *
+ * THE FULL AMOUNT, ALWAYS. A return is not a partial refund — the bank does not return part of a
+ * debit — so the reversal mirrors what was booked rather than anything on the event. Reading the
+ * amount off the event would be worse than useless here: a `charge.failed` payload reports the
+ * charge's amount, which is the same number when all is well and a silent under-reversal when it is
+ * not.
+ */
+async function reverse(provider, user, payment, event) {
+    const applications = await LoadAppliedAllocations(provider, user, payment.ID);
+    if (!applications.length) {
+        throw new Error(`Payment ${payment.PaymentNumber} was returned by the bank but is not applied to any order, ` +
+            `so there is nothing to un-apply. This should be impossible for a captured payment.`);
+    }
+    const amount = Math.round(Math.abs(Number(payment.Amount ?? 0)) * 100) / 100;
+    const reason = event.FailureReason
+        ? `Bank debit returned: ${event.FailureReason}`
+        : 'Bank debit returned by the customer’s bank';
+    const dbProvider = provider;
+    await dbProvider.BeginTransaction();
+    try {
+        const lines = await BuildUnapplyLines(provider, user, applications, amount);
+        const reversal = await CreateReversingPayment(provider, user, payment, {
+            Amount: amount,
+            Reason: reason,
+            ProviderRefundID: event.ProviderChargeID ?? null,
+            Description: `Return of ${payment.PaymentNumber}`,
+        }, lines);
+        await dbProvider.CommitTransaction();
+        return reversal.ID;
+    }
+    catch (err) {
+        try {
+            await dbProvider.RollbackTransaction();
+        }
+        catch (rollbackErr) {
+            LogError(`Rollback failed after a bank-debit reversal error: ${rollbackErr}`);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=PaymentSettlement.js.map

package/dist/PaymentSettlement.js.map

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

package/dist/PaymentTermsBehavior.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview When an order is due — the resolution walk, with no database (plan D83).
+ *
+ * WHY THIS EXISTS AT ALL. `OrderHeader.DueDate` was only ever what a caller passed, and nothing
+ * derived it from `PaymentTermsType.NetDays` even though the schema comment promised exactly that.
+ * `PaymentTermsType` had no rows, so nobody could pick terms either. The consequence was not a
+ * missing feature that looked missing:
+ *
+ *     Orders.GetOverdueWorklist, as of 2026-12-31 → 0 rows, £0 overdue, every aging bucket zero
+ *
+ * against 67 orders carrying an unpaid balance. The collections surface reported a quiet afternoon
+ * because its only input was null on every row. Aging, the overdue worklist and the invoice's due
+ * date all read that one column.
+ *
+ * THE WALK, and it is the third of this shape in the app — GL account resolution (D5) and price
+ * resolution (D69) are the other two, so a reader already knows how to read it:
+ *
+ *     1. a STATED DueDate           the caller knows the answer; never recomputed
+ *     2. a STATED PaymentTermsTypeID   derive OrderDate + NetDays
+ *     3. the CUSTOMER's terms       CustomerPaymentTerms, date-effective, optionally per company
+ *     4. the SELLING COMPANY's default  AccountingCompanyProfile.DefaultPaymentTermsTypeID
+ *     5. due on receipt             the terminal default
+ *
+ * WHERE CONTRACTS FIT. They do not — deliberately. A contracts app further down the graph populates
+ * the order's `DueDate` or `PaymentTermsTypeID` directly, and to Orders that is simply rung 1 or 2.
+ * Orders has no knowledge of contracts and should not grow any; "stated" is the whole interface.
+ *
+ * WHICH IS WHY STATED HAS TO BE RECORDED AS STATED. A due date that was supplied and one that was
+ * derived are the same value in the same column, and the difference only shows up on the next save —
+ * when a recompute silently moves a date somebody negotiated. `PricingBehavior` already draws this
+ * distinction for a stated unit price; this follows it.
+ *
+ * UNLIKE D5, IT DOES NOT FAIL LOUDLY. An unresolvable GL account means booked money with nowhere to
+ * go, so refusing is right. Missing terms have a sane answer — due on receipt — and refusing an
+ * order because nobody configured a lookup would be hostile for no gain.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server
+ */
+import { type DateCell } from '@mj-biz-apps/orders-entities';
+/** A terms record as the walk needs it. */
+export interface TermsFacts {
+    PaymentTermsTypeID: string;
+    /** Days from the order date to the due date. 0 means due on receipt. */
+    NetDays: number | null;
+}
+/** One rung 3 candidate: what a particular buyer negotiated. */
+export interface CustomerTermsFacts extends TermsFacts {
+    /** Null when the terms apply whoever is selling. */
+    CompanyID: string | null;
+    StartedAt: DateCell;
+    EndedAt: DateCell;
+    Status: string;
+}
+/** Everything the walk may consult, gathered by the caller. */
+export interface TermsResolutionInput {
+    /** What the caller stated on the order, if anything. */
+    StatedDueDate: DateCell;
+    StatedPaymentTermsTypeID: string | null;
+    /** The date the terms run from. */
+    OrderDate: string;
+    /** The selling company, used to narrow customer terms and to find the company default. */
+    CompanyID: string | null;
+    /** Rung 3 candidates for this buyer, in any order. */
+    CustomerTerms: readonly CustomerTermsFacts[];
+    /** Rung 4 — the selling company's default, or null when it has no profile. */
+    CompanyDefault: TermsFacts | null;
+    /** `NetDays` by terms id, for resolving a stated `PaymentTermsTypeID`. */
+    TermsByID: ReadonlyMap<string, TermsFacts>;
+}
+export type TermsSource = 'StatedDueDate' | 'StatedTerms' | 'CustomerTerms' | 'CompanyDefault' | 'DueOnReceipt';
+export interface TermsResolution {
+    /** `YYYY-MM-DD`, or null only when the order date itself was unusable. */
+    DueDate: string | null;
+    /** The terms record the date came from, when one was involved. */
+    PaymentTermsTypeID: string | null;
+    /** Which rung answered — recorded so a later save can tell stated from derived. */
+    Source: TermsSource;
+    /** True when the caller supplied the date and it must never be recomputed. */
+    WasStated: boolean;
+}
+/** `from` plus `days`, as `YYYY-MM-DD`. */
+export declare function AddDays(from: DateCell, days: number): string | null;
+/**
+ * Whether a customer-terms row applies to this order.
+ *
+ * DATE-EFFECTIVE ON THE ORDER DATE, not on today. Renegotiating terms must not restate what an old
+ * order was due on — an order placed under Net 30 stays due when it was always due, however the
+ * relationship changed afterwards.
+ *
+ * A row scoped to a company applies only to that company's orders; an unscoped row applies to any.
+ */
+export declare function CustomerTermsApply(row: CustomerTermsFacts, orderDate: DateCell, companyID: string | null): boolean;
+/**
+ * The most specific applicable customer terms.
+ *
+ * COMPANY-SCOPED BEATS UNSCOPED, because a subsidiary that negotiated its own terms meant to
+ * override the group's. Among equally specific rows the one that started most recently wins — a
+ * later negotiation supersedes an earlier one — and a row with no start date is treated as having
+ * always applied, so it loses to any dated row.
+ */
+export declare function BestCustomerTerms(rows: readonly CustomerTermsFacts[], orderDate: string, companyID: string | null): CustomerTermsFacts | null;
+/**
+ * Walk the rungs and produce the due date.
+ *
+ * Never throws and never returns "unknown": every order gets a date or an explicit due-on-receipt,
+ * which is the order date itself.
+ */
+export declare function ResolveDueDate(input: TermsResolutionInput): TermsResolution;
+//# sourceMappingURL=PaymentTermsBehavior.d.ts.map

package/dist/PaymentTermsBehavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaymentTermsBehavior.d.ts","sourceRoot":"","sources":["../src/PaymentTermsBehavior.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAExE,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IAClD,oDAAoD;IACpD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,QAAQ,CAAC;IACpB,OAAO,EAAE,QAAQ,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB;IACjC,wDAAwD;IACxD,aAAa,EAAE,QAAQ,CAAC;IACxB,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sDAAsD;IACtD,aAAa,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC7C,8EAA8E;IAC9E,cAAc,EAAE,UAAU,GAAG,IAAI,CAAC;IAClC,0EAA0E;IAC1E,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC9C;AAED,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,aAAa,GAAG,eAAe,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAEhH,MAAM,WAAW,eAAe;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mFAAmF;IACnF,MAAM,EAAE,WAAW,CAAC;IACpB,8EAA8E;IAC9E,SAAS,EAAE,OAAO,CAAC;CACtB;AAkBD,2CAA2C;AAC3C,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAInE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAYlH;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,SAAS,kBAAkB,EAAE,EACnC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,IAAI,GACzB,kBAAkB,GAAG,IAAI,CAa3B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe,CAwD3E"}

package/dist/PaymentTermsBehavior.js

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview When an order is due — the resolution walk, with no database (plan D83).
+ *
+ * WHY THIS EXISTS AT ALL. `OrderHeader.DueDate` was only ever what a caller passed, and nothing
+ * derived it from `PaymentTermsType.NetDays` even though the schema comment promised exactly that.
+ * `PaymentTermsType` had no rows, so nobody could pick terms either. The consequence was not a
+ * missing feature that looked missing:
+ *
+ *     Orders.GetOverdueWorklist, as of 2026-12-31 → 0 rows, £0 overdue, every aging bucket zero
+ *
+ * against 67 orders carrying an unpaid balance. The collections surface reported a quiet afternoon
+ * because its only input was null on every row. Aging, the overdue worklist and the invoice's due
+ * date all read that one column.
+ *
+ * THE WALK, and it is the third of this shape in the app — GL account resolution (D5) and price
+ * resolution (D69) are the other two, so a reader already knows how to read it:
+ *
+ *     1. a STATED DueDate           the caller knows the answer; never recomputed
+ *     2. a STATED PaymentTermsTypeID   derive OrderDate + NetDays
+ *     3. the CUSTOMER's terms       CustomerPaymentTerms, date-effective, optionally per company
+ *     4. the SELLING COMPANY's default  AccountingCompanyProfile.DefaultPaymentTermsTypeID
+ *     5. due on receipt             the terminal default
+ *
+ * WHERE CONTRACTS FIT. They do not — deliberately. A contracts app further down the graph populates
+ * the order's `DueDate` or `PaymentTermsTypeID` directly, and to Orders that is simply rung 1 or 2.
+ * Orders has no knowledge of contracts and should not grow any; "stated" is the whole interface.
+ *
+ * WHICH IS WHY STATED HAS TO BE RECORDED AS STATED. A due date that was supplied and one that was
+ * derived are the same value in the same column, and the difference only shows up on the next save —
+ * when a recompute silently moves a date somebody negotiated. `PricingBehavior` already draws this
+ * distinction for a stated unit price; this follows it.
+ *
+ * UNLIKE D5, IT DOES NOT FAIL LOUDLY. An unresolvable GL account means booked money with nowhere to
+ * go, so refusing is right. Missing terms have a sane answer — due on receipt — and refusing an
+ * order because nobody configured a lookup would be hostile for no gain.
+ *
+ * @module @mj-biz-apps/orders-core-entities-server
+ */
+import { ToISODate } from '@mj-biz-apps/orders-entities';
+/**
+ * ISO date arithmetic that does not drift across a DST boundary.
+ *
+ * Takes the cell in whatever shape it arrived. The previous form split `String(iso)` on '-', which
+ * on a `Date` finds nothing to split and yields `NaN` — so every date-effective terms row silently
+ * stopped applying and the order fell through to the company default. It failed safe rather than
+ * wrong, but it still restated what a customer had negotiated.
+ */
+function dayNumber(cell) {
+    const iso = ToISODate(cell);
+    if (!iso)
+        return Number.NaN;
+    const [y, m, d] = iso.split('-').map(Number);
+    if (!y || !m || !d)
+        return Number.NaN;
+    return Date.UTC(y, m - 1, d);
+}
+/** `from` plus `days`, as `YYYY-MM-DD`. */
+export function AddDays(from, days) {
+    const base = dayNumber(from);
+    if (Number.isNaN(base))
+        return null;
+    return new Date(base + days * 86_400_000).toISOString().slice(0, 10);
+}
+/**
+ * Whether a customer-terms row applies to this order.
+ *
+ * DATE-EFFECTIVE ON THE ORDER DATE, not on today. Renegotiating terms must not restate what an old
+ * order was due on — an order placed under Net 30 stays due when it was always due, however the
+ * relationship changed afterwards.
+ *
+ * A row scoped to a company applies only to that company's orders; an unscoped row applies to any.
+ */
+export function CustomerTermsApply(row, orderDate, companyID) {
+    if (row.Status !== 'Active')
+        return false;
+    if (row.CompanyID && companyID && row.CompanyID.toLowerCase() !== companyID.toLowerCase())
+        return false;
+    // A row scoped to a company cannot apply to an order with no company at all.
+    if (row.CompanyID && !companyID)
+        return false;
+    const on = dayNumber(orderDate);
+    if (Number.isNaN(on))
+        return false;
+    if (row.StartedAt && on < dayNumber(row.StartedAt))
+        return false;
+    // `EndedAt` is exclusive: terms that ended on the 1st do not cover an order placed on the 1st.
+    if (row.EndedAt && on >= dayNumber(row.EndedAt))
+        return false;
+    return true;
+}
+/**
+ * The most specific applicable customer terms.
+ *
+ * COMPANY-SCOPED BEATS UNSCOPED, because a subsidiary that negotiated its own terms meant to
+ * override the group's. Among equally specific rows the one that started most recently wins — a
+ * later negotiation supersedes an earlier one — and a row with no start date is treated as having
+ * always applied, so it loses to any dated row.
+ */
+export function BestCustomerTerms(rows, orderDate, companyID) {
+    const applicable = rows.filter((r) => CustomerTermsApply(r, orderDate, companyID));
+    if (!applicable.length)
+        return null;
+    return applicable.reduce((best, row) => {
+        const bestScoped = best.CompanyID ? 1 : 0;
+        const rowScoped = row.CompanyID ? 1 : 0;
+        if (rowScoped !== bestScoped)
+            return rowScoped > bestScoped ? row : best;
+        const bestStart = best.StartedAt ? dayNumber(best.StartedAt) : Number.NEGATIVE_INFINITY;
+        const rowStart = row.StartedAt ? dayNumber(row.StartedAt) : Number.NEGATIVE_INFINITY;
+        return rowStart > bestStart ? row : best;
+    });
+}
+/**
+ * Walk the rungs and produce the due date.
+ *
+ * Never throws and never returns "unknown": every order gets a date or an explicit due-on-receipt,
+ * which is the order date itself.
+ */
+export function ResolveDueDate(input) {
+    // 1. Stated wins outright. Recomputing what somebody negotiated is the failure this rung exists
+    //    to prevent, and it is also how a contracts app supplies an answer Orders cannot derive.
+    if (input.StatedDueDate) {
+        return {
+            DueDate: ToISODate(input.StatedDueDate),
+            PaymentTermsTypeID: input.StatedPaymentTermsTypeID ?? null,
+            Source: 'StatedDueDate',
+            WasStated: true,
+        };
+    }
+    // 2. Stated terms — the caller chose the terms and wants the date derived from them.
+    if (input.StatedPaymentTermsTypeID) {
+        const terms = input.TermsByID.get(input.StatedPaymentTermsTypeID.toLowerCase());
+        if (terms) {
+            return {
+                DueDate: AddDays(input.OrderDate, terms.NetDays ?? 0),
+                PaymentTermsTypeID: terms.PaymentTermsTypeID,
+                Source: 'StatedTerms',
+                WasStated: false,
+            };
+        }
+        // Terms named but unresolvable: fall through rather than refuse. The id is still recorded on
+        // the order, so the mistake is visible without holding up the sale.
+    }
+    // 3. What this buyer negotiated.
+    const customer = BestCustomerTerms(input.CustomerTerms, input.OrderDate, input.CompanyID);
+    if (customer) {
+        return {
+            DueDate: AddDays(input.OrderDate, customer.NetDays ?? 0),
+            PaymentTermsTypeID: customer.PaymentTermsTypeID,
+            Source: 'CustomerTerms',
+            WasStated: false,
+        };
+    }
+    // 4. What the selling company does by default.
+    if (input.CompanyDefault) {
+        return {
+            DueDate: AddDays(input.OrderDate, input.CompanyDefault.NetDays ?? 0),
+            PaymentTermsTypeID: input.CompanyDefault.PaymentTermsTypeID,
+            Source: 'CompanyDefault',
+            WasStated: false,
+        };
+    }
+    // 5. Due on receipt. An explicit answer rather than a null, so the collections worklist has
+    //    something to age against on every order rather than silently skipping the unconfigured ones.
+    return {
+        DueDate: AddDays(input.OrderDate, 0),
+        PaymentTermsTypeID: null,
+        Source: 'DueOnReceipt',
+        WasStated: false,
+    };
+}
+//# sourceMappingURL=PaymentTermsBehavior.js.map

package/dist/PaymentTermsBehavior.js.map

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

package/dist/PaymentWebhookHandler.d.ts

@@ -0,0 +1,103 @@
+/**
+ * PaymentWebhookHandler — the unauthenticated door, and everything that makes it safe to open.
+ *
+ * THE ROUTE HAS NO AUTHENTICATION, by necessity (D19). Stripe will not present a bearer token; the
+ * signature IS the credential. Every guard below exists because of that.
+ *
+ * TRANSPORT-AGNOSTIC ON PURPOSE. This is a function over `(rawBody, headers)` returning a status and a
+ * body, not an Express handler. Two reasons. It is unit-testable without standing up a server, which
+ * matters because the interesting cases are a forged signature and a replayed event — neither of which
+ * you want to be exercising through HTTP. And the host application owns its middleware order: the route
+ * must be mounted BEFORE the auth middleware and with a raw-body parser, and only the bootstrap knows
+ * how to do that. `MountPaymentWebhook` at the bottom is the thin adapter.
+ *
+ * THE RAW BODY IS LOAD-BEARING. The signature covers the exact bytes sent. A JSON round-trip — key
+ * order, whitespace, unicode normalisation — invalidates it, so any parser that runs before this
+ * silently breaks every webhook. `express.raw({ type: 'application/json' })` on this path only.
+ *
+ * WHAT THE RESPONSE SAYS, AND WHY IT SAYS SO LITTLE. A 2xx means "we will not need this again". A
+ * gateway retries anything else, so:
+ *
+ *   200  applied, or ALREADY applied, or deliberately ignored — all three are settled
+ *   400  malformed or unverifiable — retrying will not help, so do not ask again
+ *   500  we failed to record a valid event — PLEASE retry, this one is ours
+ *
+ * The body carries no detail. A public endpoint that explains why a signature failed is an oracle for
+ * anyone probing it, and the reason belongs in our logs where it is useful and not in a response where
+ * it is a hint.
+ *
+ * CONNECTS TO:
+ *   PURE:   ./PaymentProviderBehavior.ts — signature, idempotency decision
+ *   LOOKUP: ./PaymentProviderResolver.ts
+ *   DOC:    plans/archive/bizapps-orders-master.md D19
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { type WebhookAction } from './PaymentProviderBehavior.js';
+export interface WebhookRequest {
+    /** The EXACT bytes received. See the header — a parsed-and-restringified body will not verify. */
+    RawBody: string;
+    Headers: Record<string, string | undefined>;
+    /** Which configured provider this endpoint is for, from the route path. */
+    PaymentProviderID: string;
+}
+export interface WebhookResponse {
+    Status: 200 | 400 | 500;
+    /** Deliberately terse — see the header. */
+    Body: {
+        received: boolean;
+        outcome?: WebhookAction;
+    };
+}
+/**
+ * Handle one delivery.
+ *
+ * The order of operations is the security model, and it is deliberate:
+ *
+ *   1. resolve the provider   — so we know which secret to verify against
+ *   2. VERIFY THE SIGNATURE   — before the payload is parsed, let alone trusted
+ *   3. parse                  — now that we know it came from the gateway
+ *   4. decide idempotently    — before anything is written
+ *   5. apply                  — inside a transaction
+ *
+ * Nothing before step 2 reads the payload. Parsing first would mean acting on attacker-controlled JSON
+ * to decide whether to trust attacker-controlled JSON.
+ */
+export declare function HandlePaymentWebhook(request: WebhookRequest, provider: IMetadataProvider, user: UserInfo): Promise<WebhookResponse>;
+/**
+ * Mount the route on an Express-shaped app.
+ *
+ * Typed structurally rather than against `express`, so this package takes no dependency on it — the
+ * host already has one, and this file should not be the reason a shared server package pulls in a web
+ * framework.
+ *
+ * TWO THINGS THE CALLER MUST GET RIGHT, and neither can be enforced from here:
+ *
+ *   · Mount BEFORE the auth middleware. Stripe presents no token; auth would reject every delivery.
+ *   · Give this path a RAW body parser and nothing else. `express.json()` anywhere upstream re-encodes
+ *     the payload and every signature fails.
+ *
+ * ```ts
+ * app.post(
+ *     '/webhooks/payments/:providerId',
+ *     express.raw({ type: 'application/json' }),
+ *     MountPaymentWebhook(() => ({ provider: Metadata.Provider, user: systemUser })),
+ * );
+ * ```
+ */
+export declare function MountPaymentWebhook(context: () => {
+    provider: IMetadataProvider;
+    user: UserInfo;
+}): (req: WebhookHttpRequest, res: WebhookHttpResponse) => Promise<void>;
+/** The Express request surface this route actually uses. Structural, so no dependency is needed. */
+export interface WebhookHttpRequest {
+    body?: unknown;
+    headers?: Record<string, string | undefined>;
+    params?: Record<string, string | undefined>;
+}
+/** Likewise for the response. */
+export interface WebhookHttpResponse {
+    status(code: number): {
+        json(body: unknown): void;
+    };
+}
+//# sourceMappingURL=PaymentWebhookHandler.d.ts.map