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

package/dist/PaymentProviderResolver.js

@@ -0,0 +1,220 @@
+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;
+};
+/**
+ * PaymentProviderResolver — turns a `PaymentProvider` row into a working driver.
+ *
+ * Two jobs, and the second is the one with teeth.
+ *
+ * 1. FIND THE DRIVER. `PaymentProviderType.Code` is the `@RegisterClass` key (D37), so resolution is a
+ *    ClassFactory lookup and adding a gateway needs no schema change. A missing registration REFUSES
+ *    rather than falling back to the base class: the base's methods all decline, so a fallback would
+ *    look like a gateway that cannot do anything rather than like a driver nobody registered — and the
+ *    difference is a five-minute fix versus an afternoon.
+ *
+ * 2. FIND THE CREDENTIALS, WITHOUT EVER STORING THEM. `PaymentProvider.CredentialsRef` is a POINTER —
+ *    the name of a place to look, not a secret. Nothing in this schema holds an API key, because a
+ *    database that holds live payment credentials is a database whose backups do too.
+ *
+ * THE SECRET SEAM. `CredentialsRef` resolves through `BaseSecretResolver`, registered by ClassFactory
+ * like everything else here. The default reads environment variables, which is right for a single
+ * deployment and inadequate for a real one — so a customer using Vault, AWS Secrets Manager or Azure
+ * Key Vault registers a subclass and changes no other code. Naming the seam is the point; pretending
+ * environment variables are a secret store would be the mistake.
+ *
+ * CREDENTIALS ARE NEVER CACHED. They are fetched per operation and dropped. A cache would keep live
+ * keys in process memory for the lifetime of a server for the sake of avoiding a lookup that happens
+ * once per payment, which is not a trade worth making.
+ *
+ * CONNECTS TO:
+ *   BASE:    ./BasePaymentProvider.ts
+ *   DRIVERS: ./StripePaymentProvider.ts · ./ManualPaymentProvider.ts · ./StoredValuePaymentProvider.ts
+ *   DOC:     plans/archive/bizapps-orders-master.md D19, D37
+ */
+import { RunView } from '@memberjunction/core';
+import { MJGlobal, RegisterClassEx } from '@memberjunction/global';
+import { LoadOrdersEngine, OrdersEngine } from '@mj-biz-apps/orders-entities';
+import { BasePaymentProvider, } from './BasePaymentProvider.js';
+const PAYMENT_PROVIDER_ENTITY = 'MJ_BizApps_Orders: Payment Providers';
+/**
+ * How a `CredentialsRef` becomes actual secrets.
+ *
+ * The default treats the ref as an environment-variable PREFIX, so `STRIPE_BLUECYPRESS` reads
+ * `STRIPE_BLUECYPRESS_API_KEY` and `STRIPE_BLUECYPRESS_WEBHOOK_SECRET`. Prefixed rather than a single
+ * variable because one deployment routinely holds several configured accounts — a live one and a test
+ * one at minimum — and they need separate keys.
+ */
+export class BaseSecretResolver {
+    /**
+     * Returns whatever it can find. An EMPTY result is not an error here: a Manual provider has no
+     * credentials at all, and the driver that needs a key is the one that should complain about its
+     * absence, with the context to say what it was trying to do.
+     */
+    async Resolve(_credentialsRef) {
+        return {};
+    }
+}
+/**
+ * The default: `CredentialsRef` is an environment-variable PREFIX.
+ *
+ * `STRIPE_BLUECYPRESS` reads `STRIPE_BLUECYPRESS_API_KEY` and `STRIPE_BLUECYPRESS_WEBHOOK_SECRET`.
+ * Prefixed rather than a single variable because one deployment routinely holds several configured
+ * accounts — a live one and a test one at minimum — and they need separate keys.
+ *
+ * Registered with NO key, so it is the fallback a deployment replaces by registering its own against
+ * `BaseSecretResolver` — the same shape as `DefaultPriceResolver`.
+ */
+let EnvironmentSecretResolver = class EnvironmentSecretResolver extends BaseSecretResolver {
+    async Resolve(credentialsRef) {
+        if (!credentialsRef)
+            return {};
+        const prefix = credentialsRef.replace(/[^A-Za-z0-9_]/g, '_').toUpperCase();
+        const env = process.env;
+        const credentials = {};
+        // `|| undefined` rather than `?? ''`: an empty string satisfies a truthiness check downstream
+        // and produces an authorization header of `Bearer `, which fails confusingly.
+        credentials.ApiKey = env[`${prefix}_API_KEY`] || undefined;
+        credentials.WebhookSecret = env[`${prefix}_WEBHOOK_SECRET`] || undefined;
+        return credentials;
+    }
+};
+EnvironmentSecretResolver = __decorate([
+    RegisterClassEx(BaseSecretResolver, { skipNullKeyWarning: true })
+], EnvironmentSecretResolver);
+export { EnvironmentSecretResolver };
+/** Tree-shaking anchor for the secret seam. */
+export function LoadEnvironmentSecretResolver() {
+    // intentionally empty
+}
+export class PaymentProviderNotConfiguredError extends Error {
+}
+/**
+ * Load a configured provider row and hand back a ready driver.
+ *
+ * Throws rather than returning null. Every caller of this is about to move money and cannot proceed
+ * without a driver, so there is no branch for a caller to take — and an exception carries the reason to
+ * a log, where a returned null would arrive as "cannot read property of undefined" somewhere else.
+ */
+export async function ResolvePaymentProvider(paymentProviderID, provider, user) {
+    const config = await LoadPaymentProviderConfig(paymentProviderID, provider, user);
+    return BuildPaymentProvider(config, provider, user);
+}
+/** The configured account, with its type's code and capability flags flattened onto it. */
+export async function LoadPaymentProviderConfig(paymentProviderID, provider, user) {
+    if (!/^[0-9a-fA-F-]{36}$/.test(paymentProviderID)) {
+        throw new PaymentProviderNotConfiguredError(`'${paymentProviderID}' is not a valid payment provider identifier.`);
+    }
+    const rv = new RunView(provider);
+    // The generated view flattens the type's fields onto the provider, which is what makes this one
+    // query rather than two. `PaymentProviderType` is the related entity, so `Code` arrives as
+    // `PaymentProviderType` — MJ names a related display field after its entity.
+    const result = await rv.RunView({
+        EntityName: PAYMENT_PROVIDER_ENTITY,
+        ExtraFilter: `ID = '${paymentProviderID}'`,
+        ResultType: 'simple',
+    }, user);
+    const row = result?.Results?.[0];
+    if (!row) {
+        throw new PaymentProviderNotConfiguredError(`No payment provider ${paymentProviderID} exists. A payment cannot be routed without one.`);
+    }
+    if (!row.IsActive) {
+        throw new PaymentProviderNotConfiguredError(`Payment provider '${row.Name}' is inactive. Reactivate it or point the payment at another, ` +
+            `rather than letting an inactive gateway be used silently.`);
+    }
+    const typeCode = await resolveTypeCode(row.PaymentProviderTypeID, row.PaymentProviderType, provider, user);
+    return {
+        ID: row.ID,
+        TypeCode: typeCode.Code,
+        CompanyID: row.CompanyID,
+        Name: row.Name,
+        CredentialsRef: row.CredentialsRef,
+        IsLiveMode: !!row.IsLiveMode,
+        Capabilities: {
+            SupportsTokenization: typeCode.SupportsTokenization,
+            SupportsRefund: typeCode.SupportsRefund,
+            SupportsWebhooks: typeCode.SupportsWebhooks,
+        },
+    };
+}
+/**
+ * Instantiate the driver for a config and attach everything it needs.
+ *
+ * Exposed separately from `ResolvePaymentProvider` so the webhook route can build a driver from a config
+ * it already loaded — the route resolves a provider from the URL before it has a payment in hand, and
+ * making it re-query would mean two lookups for one request.
+ */
+export async function BuildPaymentProvider(config, provider, user) {
+    const driver = MJGlobal.Instance.ClassFactory.CreateInstance(BasePaymentProvider, config.TypeCode);
+    if (!driver) {
+        throw new PaymentProviderNotConfiguredError(`No payment driver is registered for provider type '${config.TypeCode}'. Register one with ` +
+            `@RegisterClass(BasePaymentProvider, '${config.TypeCode}') and call its Load* anchor from ` +
+            `the server bootstrap — without the anchor the decorator is tree-shaken away and the ` +
+            `class is silently absent.`);
+    }
+    // REFUSE THE BASE CLASS. `CreateInstance` falls back to the base when no key matches, and the base
+    // declines every operation — so accepting it would turn "nobody registered a Stripe driver" into
+    // "Stripe cannot take payments", which sends the reader to the gateway instead of to the bootstrap.
+    if (driver.constructor === BasePaymentProvider) {
+        throw new PaymentProviderNotConfiguredError(`Provider type '${config.TypeCode}' resolved to the BASE payment driver, which implements ` +
+            `nothing. Its Load* anchor is almost certainly missing from the server bootstrap.`);
+    }
+    const secrets = MJGlobal.Instance.ClassFactory.CreateInstance(BaseSecretResolver) ??
+        new EnvironmentSecretResolver();
+    driver.Config = config;
+    driver.Credentials = await secrets.Resolve(config.CredentialsRef);
+    driver.Provider = provider;
+    driver.User = user;
+    return driver;
+}
+/**
+ * The type's `Code` and capability flags.
+ *
+ * The provider view carries the type's NAME as a related field, and name is not key — a deployment may
+ * rename 'Stripe' to 'Stripe (Blue Cypress)' and the ClassFactory key must not move with it. So the
+ * type row is read for its `Code`.
+ */
+async function resolveTypeCode(typeID, relatedName, provider, user) {
+    // CACHE FIRST, THEN THE QUERY — and the fallback is not belt-and-braces.
+    //
+    // Provider types are seeded metadata and belong in {@link OrdersEngine} like every other lookup,
+    // so the common path is a property read. But unlike the other lookups, a provider type is also
+    // created at RUN TIME: a deployment adding a gateway, and the integration fixture creating one
+    // inside a rolled-back transaction. A cache loaded before that row existed cannot see it, and a
+    // miss here does not degrade gracefully — it throws `PaymentProviderNotConfiguredError`, which
+    // reads as "this gateway is not set up" for a gateway that plainly is.
+    //
+    // So a miss falls through to the query it always did. Same behaviour, same errors; the reads
+    // that hit the cache simply stop costing a round trip.
+    await LoadOrdersEngine(provider, user);
+    const cached = OrdersEngine.Instance.PaymentProviderTypeByID(typeID);
+    let type = cached
+        ? {
+            Code: cached.Code,
+            SupportsTokenization: cached.SupportsTokenization,
+            SupportsRefund: cached.SupportsRefund,
+            SupportsWebhooks: cached.SupportsWebhooks,
+        }
+        : undefined;
+    if (!type) {
+        const rv = new RunView(provider);
+        const result = await rv.RunView({
+            EntityName: 'MJ_BizApps_Orders: Payment Provider Types',
+            ExtraFilter: `ID = '${typeID}'`,
+            ResultType: 'simple',
+        }, user);
+        type = result?.Results?.[0];
+    }
+    if (!type) {
+        throw new PaymentProviderNotConfiguredError(`Payment provider type ${typeID}${relatedName ? ` ('${relatedName}')` : ''} was not found.`);
+    }
+    return {
+        Code: type.Code,
+        SupportsTokenization: !!type.SupportsTokenization,
+        SupportsRefund: !!type.SupportsRefund,
+        SupportsWebhooks: !!type.SupportsWebhooks,
+    };
+}
+//# sourceMappingURL=PaymentProviderResolver.js.map

package/dist/PaymentProviderResolver.js.map

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

package/dist/PaymentReversalFactory.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Building the payment that takes money back out — the one way, used by both callers.
+ *
+ * TWO THINGS REVERSE A PAYMENT, and until bank debits arrived only one of them existed:
+ *
+ *   `Orders.RefundPayment`   somebody DECIDED to give the money back
+ *   `PaymentSettlement`      the BANK took it back, days after we booked it as received
+ *
+ * They differ entirely in why they happen and not at all in what they must write. Both produce a new
+ * `PaymentHeader` with `Status='Refunded'` and `ReversesPaymentHeaderID` pointing at the original,
+ * carrying negative `PaymentLine`s that un-apply the cash from the orders the original settled. That
+ * shape is not incidental — `Status='Refunded'` is precisely what makes `PaymentHeaderEntityServer`
+ * book the MIRROR of the capture entry (D53), and the negative lines are what move each order's
+ * `Balance` back up. A second implementation that got any part of it subtly different would produce a
+ * reversal that balances, posts, and is wrong, which is the failure mode nothing downstream catches.
+ *
+ * SO THE MECHANICS LIVE HERE AND THE POLICY LIVES IN THE CALLERS. Whether a refund is allowed, how
+ * much is still refundable, whether a returned debit should reverse at all — those are decisions, and
+ * they stay with whoever is making them. This module only knows how to write the reversal once the
+ * decision is made.
+ *
+ * WHY `.Set()` AND `BaseEntity` RATHER THAN A TYPED SUBCLASS. `PaymentHeader`'s `Lines` collection is
+ * transient — CodeGen cannot emit it, so the generated entity has no property for it — and the whole
+ * point of this factory is to hand the header its lines before the single co-ordinated save. That is
+ * the same reason `RefundPaymentOperation` and `CapturePaymentOperation` work this way.
+ *
+ * CONNECTS TO:
+ *   CALLERS: ./RefundPaymentOperation.ts · ./PaymentSettlement.ts
+ *   BOOKING: ./PaymentHeaderEntityServer.ts — the reversal books through the ordinary save path
+ *   DOC:     plans/archive/bizapps-orders-master.md D17, D39, D53, D68
+ */
+import { type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import { mjBizAppsOrdersPaymentLineEntity } from '@mj-biz-apps/orders-entities';
+/** The fields of the original payment a reversal has to carry forward. */
+export interface ReversiblePayment {
+    ID: string;
+    PaymentNumber: string;
+    ReceivingCompanyID: string;
+    BillToOrganizationID: string | null;
+    BillToPersonID: string | null;
+    PaymentTypeID: string;
+    PaymentDetailID: string | null;
+}
+/** One order the original payment was applied to, and by how much. */
+export interface AppliedAllocation {
+    OrderHeaderID: string;
+    Amount: number;
+}
+/** Why this reversal is being written, and what to stamp on it. */
+export interface PaymentReversalRequest {
+    /** Positive magnitude, as `Amount` is stored on both a capture and a reversal. */
+    Amount: number;
+    Reason: string | null;
+    /** The gateway's own refund/return id, when the money moved through one. */
+    ProviderRefundID?: string | null;
+    /** Defaults to `Refund of {original}`. Settlement overrides it to name the return. */
+    Description?: string;
+}
+export interface PaymentReversalResult {
+    ID: string;
+    Number: string;
+    JournalEntryID?: string;
+}
+/**
+ * The orders a captured payment settled, and by how much.
+ *
+ * Only POSITIVE lines: a payment that has already been partly reversed carries negative lines too, and
+ * counting them would shrink the base a further reversal is spread across.
+ */
+export declare function LoadAppliedAllocations(provider: IMetadataProvider, user: UserInfo, paymentID: string): Promise<AppliedAllocation[]>;
+/**
+ * Un-apply the reversed cash from the orders the original settled.
+ *
+ * PROPORTIONAL, so a payment split across three orders reverses across the same three rather than
+ * dumping the whole thing on whichever happened to be first — which would leave two orders looking
+ * paid and one looking wildly overdue. The final line absorbs the rounding remainder so the un-applied
+ * total is exact rather than a penny short, which the allocation invariant would reject.
+ */
+export declare function BuildUnapplyLines(provider: IMetadataProvider, user: UserInfo, applications: AppliedAllocation[], reversalAmount: number): Promise<mjBizAppsOrdersPaymentLineEntity[]>;
+/**
+ * A fresh instrument snapshot for the reversal, never the original's row (D39).
+ *
+ * `PaymentDetail` is a point-in-time record of the instrument as it was. Sharing one row between the
+ * capture and its reversal would mean editing either rewrites the other's history.
+ */
+export declare function CopyPaymentDetail(provider: IMetadataProvider, user: UserInfo, sourceID: string): Promise<string>;
+/**
+ * The next number in the shared payment series.
+ *
+ * The SAME counter the capture path uses, so a reversal sits in the same series as everything else
+ * rather than in a parallel one nobody thinks to search.
+ */
+export declare function NextPaymentNumber(provider: IMetadataProvider): Promise<string>;
+/**
+ * Write the reversing payment, header and un-apply lines in ONE save.
+ *
+ * ONE SAVE IS THE REQUIREMENT, not an optimisation. `PaymentHeaderEntityServer` checks the allocation
+ * invariant across the header and its lines together (D68) and books the mirrored entries as the lines
+ * go down. Saving the header first would present a reversal for the full amount with no allocations
+ * against it — which the invariant correctly rejects — and any failure between the two steps would
+ * leave that state in the database permanently.
+ *
+ * THE FEE IS NOT MIRRORED. A processor does not hand its cut back when a payment reverses, so a
+ * reversal that carried the original's fee would credit back money nobody received.
+ */
+export declare function CreateReversingPayment(provider: IMetadataProvider, user: UserInfo, original: ReversiblePayment, request: PaymentReversalRequest, lines: mjBizAppsOrdersPaymentLineEntity[]): Promise<PaymentReversalResult>;
+//# sourceMappingURL=PaymentReversalFactory.d.ts.map

package/dist/PaymentReversalFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaymentReversalFactory.d.ts","sourceRoot":"","sources":["../src/PaymentReversalFactory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAIH,KAAK,iBAAiB,EAEtB,KAAK,QAAQ,EAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEH,gCAAgC,EACnC,MAAM,8BAA8B,CAAC;AAStC,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACnC,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CACxC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACnC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,EACd,YAAY,EAAE,iBAAiB,EAAE,EACjC,cAAc,EAAE,MAAM,GACvB,OAAO,CAAC,gCAAgC,EAAE,CAAC,CAyB7C;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACnC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAepF;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CACxC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE,gCAAgC,EAAE,GAC1C,OAAO,CAAC,qBAAqB,CAAC,CAoChC"}

package/dist/PaymentReversalFactory.js

@@ -0,0 +1,174 @@
+/**
+ * Building the payment that takes money back out — the one way, used by both callers.
+ *
+ * TWO THINGS REVERSE A PAYMENT, and until bank debits arrived only one of them existed:
+ *
+ *   `Orders.RefundPayment`   somebody DECIDED to give the money back
+ *   `PaymentSettlement`      the BANK took it back, days after we booked it as received
+ *
+ * They differ entirely in why they happen and not at all in what they must write. Both produce a new
+ * `PaymentHeader` with `Status='Refunded'` and `ReversesPaymentHeaderID` pointing at the original,
+ * carrying negative `PaymentLine`s that un-apply the cash from the orders the original settled. That
+ * shape is not incidental — `Status='Refunded'` is precisely what makes `PaymentHeaderEntityServer`
+ * book the MIRROR of the capture entry (D53), and the negative lines are what move each order's
+ * `Balance` back up. A second implementation that got any part of it subtly different would produce a
+ * reversal that balances, posts, and is wrong, which is the failure mode nothing downstream catches.
+ *
+ * SO THE MECHANICS LIVE HERE AND THE POLICY LIVES IN THE CALLERS. Whether a refund is allowed, how
+ * much is still refundable, whether a returned debit should reverse at all — those are decisions, and
+ * they stay with whoever is making them. This module only knows how to write the reversal once the
+ * decision is made.
+ *
+ * WHY `.Set()` AND `BaseEntity` RATHER THAN A TYPED SUBCLASS. `PaymentHeader`'s `Lines` collection is
+ * transient — CodeGen cannot emit it, so the generated entity has no property for it — and the whole
+ * point of this factory is to hand the header its lines before the single co-ordinated save. That is
+ * the same reason `RefundPaymentOperation` and `CapturePaymentOperation` work this way.
+ *
+ * CONNECTS TO:
+ *   CALLERS: ./RefundPaymentOperation.ts · ./PaymentSettlement.ts
+ *   BOOKING: ./PaymentHeaderEntityServer.ts — the reversal books through the ordinary save path
+ *   DOC:     plans/archive/bizapps-orders-master.md D17, D39, D53, D68
+ */
+import { CompositeKey, RunView, } from '@memberjunction/core';
+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 money = (v) => Math.round((v + Number.EPSILON) * 100) / 100;
+/**
+ * The orders a captured payment settled, and by how much.
+ *
+ * Only POSITIVE lines: a payment that has already been partly reversed carries negative lines too, and
+ * counting them would shrink the base a further reversal is spread across.
+ */
+export async function LoadAppliedAllocations(provider, user, paymentID) {
+    const rv = new RunView(provider);
+    const result = await rv.RunView({
+        EntityName: PAYMENT_LINE_ENTITY,
+        ExtraFilter: `PaymentHeaderID='${paymentID}'`,
+        Fields: ['OrderHeaderID', 'Amount'],
+        ResultType: 'simple',
+        // The lines may have been written moments ago by the capture this is reversing, and a
+        // cached read that missed them would spread the reversal across too few orders.
+        BypassCache: true,
+    }, user);
+    return (result?.Results ?? []).filter((r) => Number(r.Amount) > 0);
+}
+/**
+ * Un-apply the reversed cash from the orders the original settled.
+ *
+ * PROPORTIONAL, so a payment split across three orders reverses across the same three rather than
+ * dumping the whole thing on whichever happened to be first — which would leave two orders looking
+ * paid and one looking wildly overdue. The final line absorbs the rounding remainder so the un-applied
+ * total is exact rather than a penny short, which the allocation invariant would reject.
+ */
+export async function BuildUnapplyLines(provider, user, applications, reversalAmount) {
+    const built = [];
+    const appliedTotal = applications.reduce((s, a) => s + Number(a.Amount), 0);
+    if (appliedTotal <= 0)
+        return built;
+    let allocated = 0;
+    for (let i = 0; i < applications.length; i++) {
+        const app = applications[i];
+        const isLast = i === applications.length - 1;
+        const share = isLast
+            ? money(reversalAmount - allocated)
+            : money((Number(app.Amount) / appliedTotal) * reversalAmount);
+        allocated = money(allocated + share);
+        if (share <= 0)
+            continue;
+        const line = await provider.GetEntityObject(PAYMENT_LINE_ENTITY, user);
+        line.NewRecord();
+        line.OrderHeaderID = app.OrderHeaderID;
+        // NEGATIVE: this removes cash from the order, which is what moves Balance back up.
+        line.Amount = -share;
+        line.AllocatedAt = new Date();
+        line.AllocatedByUserID = user?.ID ?? null;
+        built.push(line);
+    }
+    return built;
+}
+/**
+ * A fresh instrument snapshot for the reversal, never the original's row (D39).
+ *
+ * `PaymentDetail` is a point-in-time record of the instrument as it was. Sharing one row between the
+ * capture and its reversal would mean editing either rewrites the other's history.
+ */
+export async function CopyPaymentDetail(provider, user, sourceID) {
+    const source = await provider.GetEntityObject(PAYMENT_DETAIL_ENTITY, CompositeKey.FromID(sourceID), user);
+    const copy = await provider.GetEntityObject(PAYMENT_DETAIL_ENTITY, user);
+    copy.NewRecord();
+    // `CopyFrom` skips primary keys by default, which is the only exclusion this needs: the
+    // `__mj_*` columns the hand-rolled loop also skipped are ReadOnly and are not parameters of
+    // spCreatePaymentDetail, so copying them cannot reach the insert.
+    copy.CopyFrom(source);
+    if (!(await copy.Save())) {
+        throw new Error(`Failed to copy the payment instrument: ${copy.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    }
+    return copy.ID;
+}
+/**
+ * The next number in the shared payment series.
+ *
+ * The SAME counter the capture path uses, so a reversal sits in the same series as everything else
+ * rather than in a parallel one nobody thinks to search.
+ */
+export async function NextPaymentNumber(provider) {
+    const db = provider;
+    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')}`;
+}
+/**
+ * Write the reversing payment, header and un-apply lines in ONE save.
+ *
+ * ONE SAVE IS THE REQUIREMENT, not an optimisation. `PaymentHeaderEntityServer` checks the allocation
+ * invariant across the header and its lines together (D68) and books the mirrored entries as the lines
+ * go down. Saving the header first would present a reversal for the full amount with no allocations
+ * against it — which the invariant correctly rejects — and any failure between the two steps would
+ * leave that state in the database permanently.
+ *
+ * THE FEE IS NOT MIRRORED. A processor does not hand its cut back when a payment reverses, so a
+ * reversal that carried the original's fee would credit back money nobody received.
+ */
+export async function CreateReversingPayment(provider, user, original, request, lines) {
+    const reversal = await provider.GetEntityObject(PAYMENT_HEADER_ENTITY, user);
+    reversal.NewRecord();
+    reversal.PaymentNumber = await NextPaymentNumber(provider);
+    reversal.ReceivingCompanyID = original.ReceivingCompanyID;
+    reversal.BillToOrganizationID = original.BillToOrganizationID;
+    reversal.BillToPersonID = original.BillToPersonID;
+    reversal.PaymentDate = new Date();
+    reversal.PaymentTypeID = original.PaymentTypeID;
+    reversal.Amount = request.Amount;
+    reversal.ProcessingFeeAmount = 0;
+    reversal.ReversesPaymentHeaderID = original.ID;
+    reversal.ReversalReason = request.Reason ?? null;
+    reversal.ProviderRefundID = request.ProviderRefundID ?? null;
+    reversal.Status = 'Refunded';
+    reversal.Description = request.Description ?? `Refund of ${original.PaymentNumber}`;
+    if (original.PaymentDetailID) {
+        reversal.PaymentDetailID = await CopyPaymentDetail(provider, user, original.PaymentDetailID);
+    }
+    // Attached, not assigned — the collection stamps PaymentHeaderID.
+    for (const line of lines)
+        reversal.Lines.Add(line);
+    if (!(await reversal.Save())) {
+        throw new Error(`Failed to create the reversal of ${original.PaymentNumber}: ` +
+            `${reversal.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    }
+    return {
+        ID: reversal.ID,
+        Number: reversal.PaymentNumber,
+        JournalEntryID: reversal.JournalEntryID ?? undefined,
+    };
+}
+//# sourceMappingURL=PaymentReversalFactory.js.map

package/dist/PaymentReversalFactory.js.map

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

package/dist/PaymentSettlement.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import { type SettlementAction } from './PaymentProviderBehavior.js';
+import type { WebhookEvent } from './BasePaymentProvider.js';
+export interface SettlementOutcome {
+    Action: SettlementAction;
+    Reason: string;
+    /** The payment the event was about, when there was one. */
+    PaymentHeaderID?: string;
+    /** The reversing payment written, when the action was `Reverse`. */
+    ReversalPaymentHeaderID?: string;
+}
+/**
+ * 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 declare function SettlePaymentForEvent(event: WebhookEvent, paymentIntentID: string, provider: IMetadataProvider, user: UserInfo): Promise<SettlementOutcome>;
+//# sourceMappingURL=PaymentSettlement.d.ts.map

package/dist/PaymentSettlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaymentSettlement.d.ts","sourceRoot":"","sources":["../src/PaymentSettlement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAOH,KAAK,iBAAiB,EAEtB,KAAK,QAAQ,EAChB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAkB7D,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACvC,KAAK,EAAE,YAAY,EACnB,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,iBAAiB,CAAC,CAmE5B"}