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

package/dist/PaymentLineEntityServer.js

@@ -0,0 +1,303 @@
+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;
+};
+/**
+ * PaymentLine server subclass — the cash-application guard (plan D18/D41) AND the cash leg (D13).
+ *
+ * `PaymentLine` is the junction that says "this much of that payment settles this order". The only
+ * protection it had was `CHECK (Amount <> 0)`, so nothing stopped applying $500 against a $100
+ * order. The rollup triggers would dutifully compute `Balance = -400` and `PaymentStatus = 'Paid'`,
+ * and the customer would appear to be owed money the ledger has no record of.
+ *
+ * ONE RULE HERE (D68 revised the other away)
+ *   A negative application (un-apply, or spending a credit) may not push the order's applied total
+ *   BELOW zero. Un-applying more than was ever applied is always a mistake.
+ *
+ * THERE IS DELIBERATELY NO CEILING. An earlier version refused any application that pushed the
+ * order's applied total above its gross, on the reasoning that an over-payment should be recorded
+ * "deliberately" as a credit memo. That was wrong, and it made the honest case unrecordable: a
+ * customer who sends 1000 for a 900 order has done nothing unusual, and the money is in the bank
+ * whether or not the schema likes it. Over-applying now simply drives the order's balance negative,
+ * and a negative balance IS the credit — spendable on another order via the Account Credit tender.
+ *
+ * WHAT GUARDS THE PAYMENT INSTEAD: `PaymentHeaderEntityServer` requires a captured payment's Amount
+ * to equal the sum of its lines (D68). That is a payment-side sum, so it belongs on the payment —
+ * and being an equality rather than a ceiling, it makes over-allocating a payment impossible by
+ * construction rather than by a second check.
+ *
+ * ── THE CASH LEG MOVED HERE (2026-07-26, D13 payment half) ──────────────────────────────────
+ * It used to live on `PaymentHeader` capture, which booked `Dr Cash / Cr AR` against the RECEIVING
+ * company and nothing else. That was wrong the moment an order carried another company's product:
+ * the collector's receivable was credited for money it was never owed, and the owner's receivable
+ * stayed open forever — balanced, posted, and invisible.
+ *
+ * ALLOCATION is the earliest point the companies are even KNOWN. A capture says how much cash
+ * arrived; only the allocation says whose revenue it settles. So the entries belong here, one per
+ * company owning a line on the order (plans/archive/intercompany-balancing.md §2).
+ *
+ * `BookedAt` is the idempotency key rather than a `JournalEntryID`, because one allocation produces
+ * N entries. They are found the other way round, through accounting's D25 provenance pair.
+ *
+ * CONNECTS TO:
+ *   FACTORY:  PaymentAllocationFactory (./PaymentAllocationFactory.ts)
+ *   LOOKUP:   AccountingEngineBase.ResolveIntercompanyAccounts (BA-D26)
+ *   TRIGGERS: trg_PaymentLine_RollupTotals → spRecalcOrderHeaderTotals (D41)
+ *   TABLE:    __mj_BizAppsOrders.PaymentLine
+ */
+import { BaseEntity, BaseEntityResult, BaseRemotableOperation, LogError, RunView, ValidationErrorInfo, ValidationErrorType, } from '@memberjunction/core';
+import { MJGlobal, RegisterClass } from '@memberjunction/global';
+import { mjBizAppsOrdersPaymentLineEntity } from '@mj-biz-apps/orders-entities';
+import { AccountingEngineBase } from '@mj-biz-apps/accounting-engine-base';
+import { BuildGLAccountResolver, EntityIDFor } from './AccountingBridge.js';
+import { PaymentAllocationFactory } from './PaymentAllocationFactory.js';
+const PAYMENT_LINE_ENTITY = 'MJ_BizApps_Orders: Payment Lines';
+const ORDER_HEADER_ENTITY = 'MJ_BizApps_Orders: Order Headers';
+const ORDER_LINE_ENTITY = 'MJ_BizApps_Orders: Order Lines';
+const PAYMENT_HEADER_ENTITY = 'MJ_BizApps_Orders: Payment Headers';
+/** Payment statuses whose allocations belong in the ledger. */
+const BOOKED_STATUSES = new Set(['Captured', 'Refunded']);
+/** Cents of slack, so decimal rounding never trips the guard on an exact-payment case. */
+const TOLERANCE = 0.005;
+let PaymentLineEntityServer = class PaymentLineEntityServer extends mjBizAppsOrdersPaymentLineEntity {
+    /**
+     * The applied-total check runs in `Save`, not `Validate`, because it needs to read sibling rows
+     * — `Validate()` is synchronous by contract, and a guard that cannot see the other applications
+     * is not a guard.
+     */
+    async Save(options) {
+        const problem = await this.checkApplicationTotal();
+        if (problem) {
+            // Registered rather than thrown: a rejected application is a business outcome the
+            // caller inspects on LatestResult, the same contract every other save failure uses.
+            this.RegisterResultHistoryEntry(this.buildRejection(problem));
+            return false;
+        }
+        // `BookedAt` is the idempotency key: a re-saved allocation (a note edited, a user
+        // backfilled) must not credit AR a second time.
+        if (this.BookedAt)
+            return super.Save(options);
+        // When saved as part of a parent PaymentHeader save, the parent PaymentHeader
+        // coordinates the booking of all allocations in one atomic batch inside the parent transaction.
+        if (options?.IsParentEntitySave) {
+            return super.Save(options);
+        }
+        const payment = await this.loadPayment();
+        // Nothing to book yet for an allocation against a Pending payment — no cash has landed.
+        // It books when the payment reaches Captured, not here.
+        if (!payment || !BOOKED_STATUSES.has(payment.Status))
+            return super.Save(options);
+        const dbProvider = this.ProviderToUse;
+        await dbProvider.BeginTransaction();
+        try {
+            if (!(await super.Save(options))) {
+                throw new Error(`Failed to save the payment allocation: ${this.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+            await this.bookAllocation(payment, options);
+            await dbProvider.CommitTransaction();
+            return true;
+        }
+        catch (err) {
+            LogError(`PaymentLineEntityServer.Save failed for allocation ${this.ID}: ${err}`);
+            try {
+                await dbProvider.RollbackTransaction();
+            }
+            catch (rollbackErr) {
+                LogError(`Rollback failed after allocation save error: ${rollbackErr}`);
+            }
+            // Same reasoning as OrderEntityServer (D50): a bare `false` leaves LatestResult holding
+            // the row's SUCCESSFUL save, so the caller sees no reason for the refusal.
+            this.RegisterResultHistoryEntry(this.buildRejection(err instanceof Error ? err.message : String(err)));
+            return false;
+        }
+    }
+    /**
+     * Book one journal entry per company owning a line on the order this allocation settles.
+     *
+     * Single-company orders produce exactly one entry — the shape the ledger had before — so this
+     * is a generalisation of the old behaviour rather than a parallel path.
+     */
+    async bookAllocation(payment, options) {
+        const provider = this.ProviderToUse;
+        const user = this.ContextCurrentUser;
+        const orderLines = await this.loadOrderLines();
+        if (orderLines.length === 0) {
+            throw new Error(`Cannot allocate ${this.Amount} to order ${this.OrderHeaderID}: the order has no lines, so ` +
+                `there is no basis for deciding whose revenue the cash settles.`);
+        }
+        const order = await this.loadOrderNumber();
+        // The intercompany lookup is accounting's (BA-D26), read from its cache. Config is cheap
+        // after the first call and keeps the pair current when one is added mid-session.
+        await AccountingEngineBase.Instance.Config(false, user, provider);
+        const factory = new PaymentAllocationFactory(await BuildGLAccountResolver(provider, user), (source, target, asOf) => {
+            const hit = AccountingEngineBase.Instance.ResolveIntercompanyAccounts(source, target, asOf);
+            return hit ? { DueToGLAccountID: hit.DueTo.GLAccountID, DueFromGLAccountID: hit.DueFrom.GLAccountID } : null;
+        }, EntityIDFor(PAYMENT_LINE_ENTITY));
+        const { Drafts } = await factory.BuildAllocationDrafts({
+            PaymentLineID: this.ID,
+            PaymentNumber: payment.PaymentNumber,
+            OrderNumber: order,
+            Amount: this.Amount ?? 0,
+            ReceivingCompanyID: payment.ReceivingCompanyID,
+            OrderLines: orderLines,
+            TargetOrderLineID: this.OrderLineID ?? null,
+            PaymentDate: payment.PaymentDate,
+            // A negative allocation un-applies cash, and a refunded payment reverses: both mirror.
+            IsReversal: payment.Status === 'Refunded' || (this.Amount ?? 0) < 0,
+        });
+        const result = await this.createJournalEntries(Drafts, provider, user);
+        if ((result.Results?.length ?? 0) !== Drafts.length) {
+            throw new Error(`Accounting returned ${result.Results?.length ?? 0} journal entries for an allocation that ` +
+                `produced ${Drafts.length} drafts. The cash leg is incomplete; refusing to commit.`);
+        }
+        this.BookedAt = new Date();
+        if (!(await super.Save(options))) {
+            throw new Error(`Failed to stamp BookedAt on the allocation: ${this.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+    /** The payment this allocation belongs to, or null when it cannot be read. */
+    async loadPayment() {
+        if (!this.PaymentHeaderID)
+            return null;
+        const rv = new RunView(this.ProviderToUse);
+        const res = await rv.RunView({
+            EntityName: PAYMENT_HEADER_ENTITY,
+            ExtraFilter: `ID='${this.PaymentHeaderID}'`,
+            Fields: ['PaymentNumber', 'ReceivingCompanyID', 'Status', 'PaymentDate'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, this.ContextCurrentUser);
+        const row = res?.Results?.[0];
+        if (!row)
+            return null;
+        return {
+            PaymentNumber: row.PaymentNumber,
+            ReceivingCompanyID: row.ReceivingCompanyID,
+            Status: row.Status,
+            PaymentDate: row.PaymentDate ? new Date(row.PaymentDate) : new Date(),
+        };
+    }
+    /** Every line of the order, with the company that owns it — the pro-rating basis. */
+    async loadOrderLines() {
+        const rv = new RunView(this.ProviderToUse);
+        // LineTotalGross (= net + tax) is the basis on purpose: it is exactly what booking DEBITED
+        // to AR for the line, and what the order's TotalGross rolls up from. Allocating on any
+        // other basis would clear a different amount than was ever receivable.
+        const res = await rv.RunView({
+            EntityName: ORDER_LINE_ENTITY,
+            ExtraFilter: `OrderHeaderID='${this.OrderHeaderID}'`,
+            Fields: ['ID', 'CompanyID', 'LineTotalGross'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, this.ContextCurrentUser);
+        if (!res?.Success) {
+            throw new Error(`Could not read the order's lines to allocate the payment: ${res?.ErrorMessage ?? 'unknown error'}`);
+        }
+        return (res.Results ?? []).map((l) => ({
+            OrderLineID: l.ID,
+            CompanyID: l.CompanyID,
+            Amount: Number(l.LineTotalGross ?? 0),
+        }));
+    }
+    async loadOrderNumber() {
+        const rv = new RunView(this.ProviderToUse);
+        const res = await rv.RunView({
+            EntityName: ORDER_HEADER_ENTITY,
+            ExtraFilter: `ID='${this.OrderHeaderID}'`,
+            Fields: ['OrderNumber'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, this.ContextCurrentUser);
+        return res?.Results?.[0]?.OrderNumber ?? String(this.OrderHeaderID);
+    }
+    async createJournalEntries(drafts, provider, user) {
+        const op = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRemotableOperation, 'Accounting.CreateJournalEntries');
+        if (!op) {
+            throw new Error(`The 'Accounting.CreateJournalEntries' operation is not registered. The BizApps ` +
+                `Accounting server package must be loaded before payments can book the cash leg.`);
+        }
+        const result = await op.Execute({ Drafts: drafts }, { provider, user });
+        if (!result.Success) {
+            throw new Error(`Accounting.CreateJournalEntries did not execute: ${result.ErrorMessage ?? result.ResultCode ?? 'unknown error'}`);
+        }
+        const payload = result.Output;
+        if (!payload)
+            throw new Error('Accounting.CreateJournalEntries returned no payload.');
+        if (!payload.Success) {
+            const detail = (payload.Errors ?? []).map((e) => `${e.Code ?? 'ERROR'}: ${e.Message ?? ''}`).join('; ');
+            throw new Error(`Journal entry booking failed for the payment allocation. ${detail}`);
+        }
+        return payload;
+    }
+    Validate() {
+        const result = super.Validate();
+        if (!this.OrderHeaderID) {
+            result.Success = false;
+            result.Errors.push(new ValidationErrorInfo('OrderHeaderID', 'A payment line must name the order it settles.', this.OrderHeaderID, ValidationErrorType.Failure));
+        }
+        return result;
+    }
+    /** Returns a message when this application would take the order out of range, else null. */
+    async checkApplicationTotal() {
+        if (!this.OrderHeaderID || !this.Amount)
+            return null;
+        const rv = new RunView(this.ProviderToUse);
+        const orders = await rv.RunView({
+            EntityName: ORDER_HEADER_ENTITY,
+            ExtraFilter: `ID='${this.OrderHeaderID}'`,
+            Fields: ['TotalGross', 'OrderNumber'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, this.ContextCurrentUser);
+        const order = orders?.Results?.[0];
+        // An order we cannot read is not this guard's problem to report — the FK will reject it.
+        if (!order)
+            return null;
+        const siblings = await rv.RunView({
+            EntityName: PAYMENT_LINE_ENTITY,
+            ExtraFilter: `OrderHeaderID='${this.OrderHeaderID}'`,
+            Fields: ['ID', 'Amount'],
+            ResultType: 'simple',
+            BypassCache: true,
+        }, this.ContextCurrentUser);
+        // Exclude this row when it is an UPDATE, so an edit is measured against its new value only.
+        const existing = (siblings?.Results ?? [])
+            .filter((l) => !this.ID || l.ID.toLowerCase() !== String(this.ID).toLowerCase())
+            .reduce((sum, l) => sum + Number(l.Amount ?? 0), 0);
+        const proposed = Math.round((existing + Number(this.Amount)) * 100) / 100;
+        // NO CEILING. Over-applying is deliberately permitted (D68): a customer paying more than an
+        // order is worth is an everyday event, and the resulting NEGATIVE balance is exactly how this
+        // system represents a customer credit — spendable on another order through the Account Credit
+        // tender. The ceiling that used to live here refused that, which is why a payment could not be
+        // recorded for what actually arrived. Consistency between a payment and its own allocations is
+        // enforced instead, on the payment side (PaymentHeaderEntityServer, D68).
+        if (proposed < -TOLERANCE) {
+            return (`Applying ${this.Amount} would take the total applied against order ${order.OrderNumber} ` +
+                `to ${proposed}. Only ${existing} has ever been applied, so there is nothing more to ` +
+                `un-apply.`);
+        }
+        return null;
+    }
+    buildRejection(message) {
+        const result = new BaseEntityResult();
+        result.Success = false;
+        result.Type = this.IsSaved ? 'update' : 'create';
+        result.Message = message;
+        result.OriginalValues = this.Fields.map((f) => ({ FieldName: f.Name, Value: f.OldValue }));
+        result.NewValues = this.Fields.map((f) => ({ FieldName: f.Name, Value: f.Value }));
+        result.StartedAt = new Date();
+        result.EndedAt = new Date();
+        return result;
+    }
+};
+PaymentLineEntityServer = __decorate([
+    RegisterClass(BaseEntity, PAYMENT_LINE_ENTITY)
+], PaymentLineEntityServer);
+export { PaymentLineEntityServer };
+/** Tree-shaking anchor — the guard lives in Save, reachable only via the registration. */
+export function LoadPaymentLineEntityServer() {
+    // intentionally empty
+}
+//# sourceMappingURL=PaymentLineEntityServer.js.map

package/dist/PaymentLineEntityServer.js.map

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

package/dist/PaymentProviderBehavior.d.ts

@@ -0,0 +1,222 @@
+/**
+ * The parts of talking to a payment gateway that can be got wrong without a network — and therefore
+ * the parts worth proving without one.
+ *
+ * Three things live here, and each is here because its failure mode is silent:
+ *
+ *   1. MINOR-UNIT CONVERSION. Stripe and most gateways transact in the currency's smallest unit, so
+ *      $12.34 is `1234`. Getting that wrong is a factor-of-100 error that looks like a plausible
+ *      amount at both ends — charge 12 cents for a $12 order, or $1,234 for a $12.34 one. Worse, JPY
+ *      has NO minor unit, so the "obvious" `× 100` overcharges a Japanese customer a hundredfold.
+ *
+ *   2. WEBHOOK SIGNATURE VERIFICATION. The webhook route is unauthenticated by necessity (D19) — the
+ *      signature IS the authentication. A verifier that accepts anything is a public endpoint that
+ *      marks orders paid, and it passes every test that only ever feeds it valid input.
+ *
+ *   3. IDEMPOTENCY. Gateways retry, and they retry on success too — a webhook that times out on our
+ *      side is redelivered. Processing one twice books the cash twice.
+ *
+ * CONNECTS TO:
+ *   SERVER: ./BasePaymentProvider.ts and the drivers under it
+ *   ROUTE:  ./PaymentWebhookHandler.ts
+ *   DOC:    plans/archive/bizapps-orders-master.md D19, D37
+ */
+/** How many minor units make one major unit. */
+export declare function CurrencyExponent(currencyCode: string): number;
+/**
+ * Turn an amount we hold as a decimal into the integer the gateway wants.
+ *
+ * Rounds rather than truncates, and rounds the SCALED value: `Math.round(12.345 * 100)` is 1235 while
+ * `Math.round(12.345) * 100` is 1200. Both look like money.
+ *
+ * Throws on a non-finite amount instead of sending `NaN` to a gateway, which some accept as zero.
+ */
+export declare function ToMinorUnits(amount: number, currencyCode: string): number;
+/** And back, for reading what the gateway reported. */
+export declare function FromMinorUnits(minor: number, currencyCode: string): number;
+export interface SignatureVerification {
+    Valid: boolean;
+    /** Why not, when not. Logged, never returned to the caller — see PaymentWebhookHandler. */
+    Reason?: string;
+}
+/**
+ * Verify a Stripe-style `Stripe-Signature` header.
+ *
+ * The scheme: `t=<unix seconds>,v1=<hex hmac>[,v1=<another>]`, where the HMAC is SHA-256 over
+ * `${t}.${rawBody}` keyed with the endpoint secret. Multiple `v1` values appear during a secret
+ * rotation, and ANY match is a pass — a verifier that only reads the first one breaks silently
+ * halfway through a rotation, which is the worst possible moment.
+ *
+ * THE RAW BODY IS NOT NEGOTIABLE. The signature covers the exact bytes Stripe sent. Any JSON
+ * round-trip — key reordering, whitespace, unicode normalisation — changes them, and the signature
+ * then fails for a legitimate event. That is why the route captures the raw body before any parser
+ * touches it.
+ *
+ * TIMESTAMP TOLERANCE defends against replay: a valid old payload stays valid forever without it.
+ * Default five minutes, matching Stripe's own guidance. `nowSeconds` is a parameter so this is
+ * testable without waiting.
+ */
+export declare function VerifyWebhookSignature(rawBody: string, signatureHeader: string | null | undefined, secret: string | null | undefined, opts?: {
+    NowSeconds?: number;
+    ToleranceSeconds?: number;
+}): Promise<SignatureVerification>;
+/** HMAC-SHA256 as lowercase hex, via Web Crypto. */
+export declare function HmacSha256Hex(secret: string, payload: string): Promise<string>;
+/**
+ * Constant-time hex comparison.
+ *
+ * `===` on a signature leaks how many leading characters were right through how long the comparison
+ * took. That is a real attack against a public endpoint, and the fix costs nothing. `timingSafeEqual`
+ * throws on a length mismatch, so the lengths are checked first — and a mismatched length is itself
+ * not secret, since the algorithm fixes it.
+ */
+export declare function SignaturesMatch(expected: string, provided: string): boolean;
+/** `PaymentIntent.Status` — the CHECK-constrained set our column allows. */
+export type IntentStatus = 'RequiresPayment' | 'Processing' | 'Succeeded' | 'Canceled' | 'Failed';
+/**
+ * Map a gateway's own status onto ours.
+ *
+ * UNKNOWN MAPS TO `Processing`, NOT to `Succeeded` or `Failed`. A status we do not recognise means the
+ * gateway has told us something this code was not written for, and both confident answers are
+ * dangerous: `Succeeded` books cash that may not exist, `Failed` abandons a payment that may be fine.
+ * `Processing` is the honest reading — something is happening and we do not yet know what — and it
+ * leaves the payment for a human or a later event to resolve.
+ */
+export declare function MapStripeIntentStatus(providerStatus: string | null | undefined): IntentStatus;
+/** What a webhook should cause, decided before anything is written. */
+export type WebhookAction = 'Apply' | 'AlreadyApplied' | 'Ignore' | 'Reject';
+export interface WebhookDecision {
+    Action: WebhookAction;
+    Reason: string;
+}
+/**
+ * Decide what to do with an event, given what we have already seen.
+ *
+ * `AlreadyApplied` IS A SUCCESS, and that distinction is the whole point. A gateway that does not get
+ * a 2xx retries, so returning an error for a duplicate guarantees it comes back — forever. The
+ * response must say "yes, we have this" without doing the work twice.
+ *
+ * `Ignore` is for events we are not interested in. Gateways send far more than any one integration
+ * consumes, and treating an unrecognised event as an error means a Stripe dashboard full of red for
+ * events we were never going to read.
+ */
+export declare function DecideWebhookAction(input: {
+    EventID: string | null | undefined;
+    EventKind: string | null | undefined;
+    /** True when a `PaymentIntent` row already carries this `ProviderEventID`. */
+    AlreadySeen: boolean;
+    /** The kinds this integration acts on. */
+    HandledKinds: readonly string[];
+    /** False when the event names an intent we have no record of. */
+    IntentKnown: boolean;
+}): WebhookDecision;
+/**
+ * Split a captured amount into the cash actually received and the gateway's cut.
+ *
+ * The capture entry is `Dr Cash (net) / Dr Processing Fee / Cr A/R (gross)` (D18), so these three
+ * numbers must reconcile exactly or the entry will not balance. Deriving `net` by subtraction rather
+ * than trusting a reported net is deliberate: a gateway that rounds its own net differently would
+ * leave a penny with no home in the ledger.
+ *
+ * ALL THREE ARE EXACT AT 2DP, BUT `Net + Fee` IN JAVASCRIPT IS NOT. Adding two correctly-rounded
+ * decimals drifts in binary floating point — 32.06 + 1.27 is 33.330000000000005 — so a caller
+ * reconciling them must round the SUM before comparing, exactly as `Money()` does everywhere else in
+ * this package. This is the same hazard that made a balanced journal entry fail an exact-equality check
+ * in accounting; the numbers were never wrong, the comparison was.
+ */
+export declare function SplitCapturedAmount(grossAmount: number, feeAmount: number): {
+    Gross: number;
+    Fee: number;
+    Net: number;
+};
+/**
+ * Stripe's published US bank-debit price: 0.8% of the amount, capped at $5.
+ *
+ * FOR THE STUB ONLY, and the name says so deliberately. The live path reads the fee off the charge's
+ * balance transaction like every other capture — what Stripe actually charged is a fact, and computing
+ * it here would be this file's opinion competing with the gateway's record. A stub that reported a
+ * ZERO fee would be worse still: it would make the fee leg of the capture entry (D18) unreachable in
+ * every test, so the arithmetic most worth exercising would be the arithmetic never exercised. That is
+ * the same reasoning behind the card stub's 2.9% + 30c, and the same reason this constant will drift
+ * from Stripe's price list one day without breaking anything real.
+ *
+ * The cap is a MAJOR-UNIT USD figure. A bank debit is a US rail, so the currency is USD in practice;
+ * a caller passing anything else gets the percentage without the cap rather than a cap converted at a
+ * rate this module has no business knowing.
+ */
+export declare function AchFeeEstimate(grossAmount: number, currencyCode?: string): number;
+/**
+ * What a settlement event should do to the payment we opened for it.
+ *
+ * `Hold` is the important one and the reason this is a decision table rather than an `if`. It means
+ * the event and the payment disagree in a way this code was not written for — a success against a
+ * refunded payment, a capture with no ledger entry behind it — and the honest response is to record
+ * nothing and say so. Both confident answers are worse: acting books or unbooks real money on a
+ * reading we have already admitted we do not understand.
+ */
+export type SettlementAction = 'Promote' | 'Fail' | 'Reverse' | 'Hold' | 'None';
+export interface SettlementDecision {
+    Action: SettlementAction;
+    Reason: string;
+}
+/**
+ * Decide what a bank-debit event does to its payment.
+ *
+ * THE ASYMMETRY IS THE WHOLE DESIGN. A card tells you at the till; a bank debit tells you up to four
+ * business days later, and it can tell you TWICE — "taken" and then, a week after that, "returned"
+ * (insufficient funds, account closed, unauthorised). So there is no single moment where the answer is
+ * known, and a payment has to be able to move forward AND backward:
+ *
+ *   Pending  + succeeded → `Promote`  the payment becomes Captured, which is what books the cash
+ *   Pending  + failed    → `Fail`     nothing was ever booked, so nothing needs reversing
+ *   Captured + failed    → `Reverse`  the money left again; a REVERSING payment says so in the ledger
+ *
+ * WHY `Reverse` AND NOT AN UPDATE. A returned debit is not "the payment never happened" — it happened,
+ * the ledger recorded it, a period may have closed over it. Editing the original would erase a true
+ * fact about a past date. A reversing payment is the same answer the rest of this application already
+ * gives (`ReversesPaymentHeaderID`, D53), and it leaves both facts standing.
+ *
+ * `None` covers the ordinary quiet cases — an event that changes nothing, a promotion that already
+ * happened — and is a SUCCESS. A gateway that does not get a 2xx retries forever.
+ */
+export declare function DecideSettlement(input: {
+    /** How the driver read the intent after this event. */
+    EventStatus: IntentStatus | null | undefined;
+    /** `PaymentHeader.Status`, or null when no payment was opened for this intent. */
+    HeaderStatus: string | null | undefined;
+    /** True when the header carries a `JournalEntryID` — the cash is in the ledger. */
+    HeaderBooked: boolean;
+    /** True when a reversing payment already points at this one. */
+    AlreadyReversed: boolean;
+}): SettlementDecision;
+/** What the save path knows about a payment that is asking to become `Captured`. */
+export interface CaptureTimingFacts {
+    /** The status the caller wrote. */
+    RequestedStatus: string;
+    /** The status already on disk, or undefined for a new payment. */
+    PersistedStatus?: string | null;
+    /** False for a payment being inserted. */
+    IsSaved: boolean;
+    /** False for a RECORDED payment — cheque, cash, wire — which has no gateway to wait for. */
+    HasProvider: boolean;
+    /** The driver's own declaration. See `BasePaymentProvider.SettlesAsynchronously`. */
+    SettlesAsynchronously: boolean;
+}
+/**
+ * Whether a payment asking to be `Captured` must be held at `Pending` because its rail settles on
+ * somebody else's schedule.
+ *
+ * WHY THIS IS A FUNCTION AND NOT AN `IF` IN THE SAVE PATH. The rule used to live only in
+ * `Orders.CapturePayment`, which made it a rule that ONE CALLER followed rather than one the system
+ * enforced — a workflow, a UI form or a test builder writing `Status: 'Captured'` went straight past
+ * it and booked `Dr Cash` for a bank debit that had not cleared. Balanced, posted, and undetectable
+ * downstream. Stating it here means the entity server and the operation ask the same question of the
+ * same code instead of both remembering.
+ *
+ * THE PROMOTION MUST PASS. When the webhook moves a `Pending` payment to `Captured`, that IS the
+ * bank answering; holding it again would mean a bank debit could never book at all. The persisted
+ * status is the signal — already `Pending` means promotion, anything else means a caller declaring
+ * cash that has not moved.
+ */
+export declare function ShouldHoldForLateSettlement(facts: CaptureTimingFacts): boolean;
+//# sourceMappingURL=PaymentProviderBehavior.d.ts.map

package/dist/PaymentProviderBehavior.d.ts.map

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