@mj-biz-apps/orders-core-entities-server 5.35.1 → 5.36.1

package/dist/CheckoutSessionService.js

@@ -18,6 +18,7 @@ import { ExplainMissingCheckoutAttendees, LoadProductsRequiringAttendees } from
 import { ResolvePersonByEmail } from './PersonByEmail.js';
 import { OpenPaymentIntent, SUPPORTED_PAYMENT_CURRENCY } from './PaymentIntentService.js';
 import { ResolvePaymentProvider } from './PaymentProviderResolver.js';
+import { ResolveCheckoutPublishableKey } from './CheckoutPublishableKey.js';
 import { FindReusableProviderCustomerRef, SnapshotSellsSubscription, SaveCheckoutInstrumentForRenewals, } from './CheckoutSavedInstrument.js';
 import { CheckoutMemberDiscountNotConfiguredError, DEFAULT_TYPED_CODE_PRECEDENCE, IsRegisteredMemberPromotionCode, ResolveCheckoutMemberDiscountResolver, } from './CheckoutMemberDiscountResolver.js';
 import { CapturePaymentOperation } from './CapturePaymentOperation.js';
@@ -26,6 +27,7 @@ import { raiseCheckoutCaptureTerminalAlert, raiseCheckoutSettledNotBookedAlert }
 import { CheckoutStepLog } from './CheckoutStepLog.js';
 import { isCaptureRefusalRetryable, isTerminalCapturePrecheck, } from './checkoutCaptureRetry.js';
 import { DescribeCheckoutSnapshot, SendOrderDescriptionToGateway } from './IntentDescription.js';
+import { SetSystemOrderOrigin } from './SystemOrderOrigin.js';
 import { LoadRenewalPaymentOrder, PayerOwnsRenewalCustomer, RenewalPaymentAlreadyConfirmed, RenewalPaymentLinkSecret, RenewalPaymentRefusal, RenewalPaymentTokenMessage, VerifyRenewalPaymentToken, } from './CheckoutRenewalPayment.js';
 const CHECKOUT_WIDGET_ENTITY = 'MJ_BizApps_Orders: Checkout Widgets';
 const CHECKOUT_DISTRIBUTION_ENTITY = 'MJ_BizApps_Orders: Checkout Widget Distributions';
@@ -133,6 +135,13 @@ function SettledButShortMessage(cause) {
     return `${what}, so your payment does not cover the total and the order was not placed. `
         + 'Our team has been notified and will arrange a refund.';
 }
+/**
+ * How long a caller that finds a session Processing waits for the other completion to finish. The
+ * browser's complete call and the payment webhook can both arrive for one payment (#724); the one
+ * that loses the latch waits for the winner and answers with its order.
+ */
+const PROCESSING_WAIT_MS = 30_000;
+const PROCESSING_POLL_MS = 1_000;
 export class CheckoutSessionService {
     /**
      * Resolves a public distribution slug, validates widget status, and mints an active CheckoutSession.
@@ -221,7 +230,7 @@ export class CheckoutSessionService {
             WidgetID: widget.ID,
             WidgetName: widget.Name,
             CompanyID: widget.CompanyID,
-            Configuration: this.sanitizeConfigurationForClient(configObj),
+            Configuration: await this.clientConfiguration(configObj, widget.Name, contextUser),
             CustomCSS: configObj.customUI.css || widget.CustomCSS,
             CustomJS: configObj.customUI.js || widget.CustomJS,
             ExpiresAt: session.ExpiresAt.toISOString()
@@ -316,7 +325,7 @@ export class CheckoutSessionService {
             WidgetID: widget.ID,
             WidgetName: widget.Name,
             CompanyID: widget.CompanyID,
-            Configuration: this.sanitizeConfigurationForClient(configObj),
+            Configuration: await this.clientConfiguration(configObj, widget.Name, contextUser),
             CustomCSS: configObj.customUI.css || widget.CustomCSS,
             CustomJS: configObj.customUI.js || widget.CustomJS,
             ExpiresAt: session.ExpiresAt.toISOString(),
@@ -354,7 +363,8 @@ export class CheckoutSessionService {
      * anonymous caller. `Configuration` is admin-authored JSON with an open index signature,
      * so a future secret-shaped key (a webhook secret, an API credential, a server-side
      * payment provider ref) must never ride along to the browser. `stripePublishableKey`
-     * is publishable by definition and survives.
+     * is publishable by definition and survives — but its VALUE is decided by
+     * `ResolveCheckoutPublishableKey` (see `clientConfiguration`), not taken from here as is.
      */
     /**
      * Keys that may cross to an unauthenticated browser. Anything else in the
@@ -387,6 +397,24 @@ export class CheckoutSessionService {
         'questions',
         'choiceGroups',
     ]); }
+    /**
+     * The Configuration an anonymous browser receives: the allowlisted keys, with
+     * `stripePublishableKey` replaced by the resolved key — the payment provider's
+     * `<CredentialsRef>_PUBLISHABLE_KEY` when the server has one, else the widget's own value.
+     * Every path that hands a browser a widget Configuration goes through here, so the session API
+     * and the server-rendered host page cannot disagree about which key to load Stripe.js with.
+     */
+    static async clientConfiguration(configObj, widgetName, contextUser) {
+        const client = this.sanitizeConfigurationForClient(configObj);
+        const publishable = await ResolveCheckoutPublishableKey(configObj, widgetName, contextUser);
+        if (publishable.Key) {
+            client.stripePublishableKey = publishable.Key;
+        }
+        else {
+            delete client.stripePublishableKey;
+        }
+        return client;
+    }
     static sanitizeConfigurationForClient(configObj) {
         const sanitized = {};
         for (const [key, value] of Object.entries(configObj)) {
@@ -429,7 +457,12 @@ export class CheckoutSessionService {
         }
         return allowed;
     }
-    /** Marks expired-but-still-Open sessions Expired. Bounded; best-effort. */
+    /**
+     * Marks expired-but-still-Open sessions Expired. Bounded; best-effort.
+     *
+     * A session whose payment settled has charged the buyer with no order, so expiring it raises the
+     * "settled with no order" alert: otherwise it would leave nothing for staff to see (#724).
+     */
     static async ReapExpiredOpenSessions(contextUser, limit = 50) {
         const rv = new RunView();
         const nowUtc = new Date().toISOString();
@@ -457,6 +490,9 @@ export class CheckoutSessionService {
                 session.Status = 'Expired';
                 if (await session.Save()) {
                     n++;
+                    if (await this.sessionPaymentSettled(session, md, contextUser)) {
+                        void raiseCheckoutSettledNotBookedAlert(session.ID, session.PaymentIntentID, 'The checkout expired after its payment settled, and no order was created.', contextUser);
+                    }
                 }
             }
             catch (err) {
@@ -465,6 +501,27 @@ export class CheckoutSessionService {
         }
         return n;
     }
+    /** True when the session's payment intent is recorded as settled. Reads our row, not the gateway. */
+    static async sessionPaymentSettled(session, md, contextUser) {
+        if (!session.PaymentIntentID) {
+            return false;
+        }
+        const intent = await md.GetEntityObject(PAYMENT_INTENT_ENTITY, contextUser);
+        return (await intent.Load(session.PaymentIntentID)) && SETTLED_INTENT_STATUSES.includes(intent.Status);
+    }
+    /**
+     * Waits, up to `PROCESSING_WAIT_MS`, for a session another caller latched to Processing to leave
+     * that state, reloading it in place. Returns at once when it is not Processing.
+     */
+    static async awaitProcessingFinished(session) {
+        const deadline = Date.now() + PROCESSING_WAIT_MS;
+        while (session.Status === 'Processing' && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, PROCESSING_POLL_MS));
+            if (!(await session.Load(session.ID))) {
+                return;
+            }
+        }
+    }
     /**
      * Verifies a caller-presented client session key against the session row's stored key.
      * The session GUID alone must never be sufficient to drive a session — both values are
@@ -1078,7 +1135,7 @@ export class CheckoutSessionService {
         order.NewRecord();
         order.CompanyID = widget.CompanyID;
         order.Status = 'Draft';
-        order.Origin = 'Widget';
+        SetSystemOrderOrigin(order, 'Widget');
         order.SourceCheckoutWidgetID = widget.ID;
         // Defence-in-depth: the server pre-warms this engine at startup (@RegisterForStartup),
         // but that pre-warm only reaches modules already evaluated when Startup() runs, which
@@ -1763,27 +1820,13 @@ export class CheckoutSessionService {
                 Status: session.Status
             };
         }
+        // The payment webhook may be completing this session right now (#724): answer with its order.
+        await this.awaitProcessingFinished(session);
         // Replay safety: a session that already completed returns its existing order rather
         // than an error — a network retry after a successful booking must never double-book
         // and must never strand the buyer without their order id.
         if (session.Status === 'Confirmed' && session.DraftOrderID) {
-            const existingOrder = await md.GetEntityObject(ORDER_HEADER_ENTITY, contextUser);
-            const orderLoaded = await existingOrder.Load(session.DraftOrderID);
-            // A first complete can confirm the order and then fail to book the payment.
-            // Replay is one retry: CapturePayment is idempotent on `checkout-complete:${session.ID}`.
-            // `payment_intent.succeeded` is the other — BookSettledCheckoutPaymentIfNeeded, including
-            // on AlreadyApplied webhook deliveries so a 500 after applyEvent still converges.
-            if (orderLoaded) {
-                await this.applySettledPaymentToOrder(session, existingOrder, contextUser, { Source: 'Checkout' });
-            }
-            return {
-                Success: true,
-                SessionID: sessionID,
-                Status: 'Confirmed',
-                OrderID: session.DraftOrderID,
-                OrderNumber: orderLoaded ? (existingOrder.OrderNumber || session.DraftOrderID) : session.DraftOrderID,
-                TotalGross: orderLoaded ? (existingOrder.TotalGross ?? undefined) : undefined
-            };
+            return this.replayConfirmedSession(session, md, contextUser, { Source: 'Checkout', Report: {} });
         }
         if (session.Status !== 'Open') {
             return {
@@ -1801,12 +1844,77 @@ export class CheckoutSessionService {
                 Status: 'Expired'
             };
         }
+        return this.completeOpenSession(session, md, contextUser, { Source: 'Checkout', Evidence: evidence, Report: {} });
+    }
+    /**
+     * Completes a session paid for at the gateway whose browser never asked (#724): the buyer closed
+     * the tab, or lost the page, after the payment succeeded. Reached from the payment webhook, so there
+     * is no client session key: the signature-verified event is the proof, and the completion checks
+     * the intent's state and amount against the re-priced order exactly as the browser's call does.
+     *
+     * The session expiry is not enforced: the buyer paid inside it, and expiry stops a session from
+     * being driven further, not a paid one from being booked.
+     *
+     * Any refusal raises the "settled with no order" alert, since nobody is on the page to see it.
+     */
+    static async completeFromWebhook(session, md, contextUser) {
+        const trigger = { Source: 'Webhook', Report: {} };
+        const result = await this.completeOpenSession(session, md, contextUser, trigger);
+        if (result.Success) {
+            return trigger.Report.Capture ?? { Attempted: true, Booked: true };
+        }
+        const reason = result.ErrorMessage ?? 'the checkout could not be completed';
+        if (trigger.Report.Retryable) {
+            return { Attempted: true, Booked: false, Retryable: true, ErrorMessage: reason };
+        }
+        if (!trigger.Report.Alerted) {
+            void raiseCheckoutSettledNotBookedAlert(session.ID, session.PaymentIntentID, reason, contextUser);
+        }
+        return { Attempted: true, Booked: false, Retryable: false, ErrorMessage: reason };
+    }
+    /**
+     * The existing order of a Confirmed session, booking its payment if the first completion did
+     * not. CapturePayment is idempotent on `checkout-complete:${session.ID}`, so this is one of the
+     * retries; `payment_intent.succeeded` is the other (BookSettledCheckoutPaymentIfNeeded, including
+     * on AlreadyApplied webhook deliveries so a 500 after applyEvent still converges).
+     */
+    static async replayConfirmedSession(session, md, contextUser, trigger) {
+        const orderID = session.DraftOrderID ?? '';
+        const existingOrder = await md.GetEntityObject(ORDER_HEADER_ENTITY, contextUser);
+        const orderLoaded = await existingOrder.Load(orderID);
+        if (orderLoaded) {
+            trigger.Report.Capture = await this.applySettledPaymentToOrder(session, existingOrder, contextUser, { Source: trigger.Source });
+        }
+        return {
+            Success: true,
+            SessionID: session.ID,
+            Status: 'Confirmed',
+            OrderID: orderID,
+            OrderNumber: orderLoaded ? (existingOrder.OrderNumber || orderID) : orderID,
+            TotalGross: orderLoaded ? (existingOrder.TotalGross ?? undefined) : undefined
+        };
+    }
+    /**
+     * Builds and confirms the order for an Open session — the work behind both the browser's
+     * complete call and the payment webhook. The caller has checked the session may be completed.
+     */
+    static async completeOpenSession(session, md, contextUser, trigger) {
+        const sessionID = session.ID;
+        const evidence = trigger.Evidence;
         if (session.DraftOrderID) {
-            return this.completeRenewalPayment(session, md, contextUser);
+            return this.completeRenewalPayment(session, md, contextUser, trigger);
         }
         // Atomically latch status to Processing to prevent concurrent duplicate checkout processing
         const latched = await this.latchSessionProcessingAtomic(sessionID, md, contextUser);
         if (!latched) {
+            // The other caller for this payment (browser or webhook) holds the latch: wait for it.
+            if (await session.Load(sessionID)) {
+                await this.awaitProcessingFinished(session);
+                if (session.Status === 'Confirmed' && session.DraftOrderID) {
+                    return this.replayConfirmedSession(session, md, contextUser, trigger);
+                }
+            }
+            trigger.Report.Retryable = true;
             return {
                 Success: false,
                 ErrorMessage: 'Session is not in an Open status or was concurrently processed',
@@ -1899,7 +2007,7 @@ export class CheckoutSessionService {
             order.CompanyID = widget.CompanyID;
             order.BillToPersonID = session.PersonID ?? null;
             order.ShipToPersonID = session.PersonID ?? null;
-            order.Origin = 'Widget';
+            SetSystemOrderOrigin(order, 'Widget');
             order.OrderType = 'Sale';
             order.SourceCheckoutWidgetID = widget.ID;
             // VAT location evidence beside the billing address (#480). Null when the edge has no
@@ -2105,6 +2213,7 @@ export class CheckoutSessionService {
                                 ? `Promotion code ${typedCodeDeclined.Code} was declined on re-price (${typedCodeDeclined.Reason}). ${paymentFailure.Message}`
                                 : paymentFailure.Message;
                         void raiseCheckoutSettledNotBookedAlert(sessionID, session.PaymentIntentID, reason, contextUser);
+                        trigger.Report.Alerted = true;
                     }
                     return {
                         Success: false,
@@ -2120,7 +2229,7 @@ export class CheckoutSessionService {
                 order.CardIssuingCountry = paymentCheck.CardIssuingCountry;
                 // Payment has checked out, so from here a failure leaves a paid checkout without
                 // an order. Record the attempt; Confirm rolls back on failure, the record does not.
-                confirmStep = await CheckoutStepLog.Begin(sessionID, 'Confirm', 'Checkout', contextUser);
+                confirmStep = await CheckoutStepLog.Begin(sessionID, 'Confirm', trigger.Source, contextUser);
             }
             // Payment has checked out (or none was due): create the Persons the checkout needs.
             if (newPayerFields) {
@@ -2163,7 +2272,7 @@ export class CheckoutSessionService {
             }
             // Book the PaymentHeader + allocation now that the order exists. retrieve-on-complete
             // only stamps PaymentIntent.Status = Succeeded; AmountPaid stays 0 until CapturePayment.
-            await this.applySettledPaymentToOrder(session, order, contextUser, { Source: 'Checkout' });
+            trigger.Report.Capture = await this.applySettledPaymentToOrder(session, order, contextUser, { Source: trigger.Source });
             // Mint the GuestOrder identity claim for the buyer's email so a later account
             // (MJ core's IdentityClaimEngineServer) can attach the order + its entitlement
             // grants on redemption or claim-on-login. Best-effort: a claim failure must never
@@ -2220,6 +2329,8 @@ export class CheckoutSessionService {
             }
             await CheckoutSessionService.revertSessionOpenAtomic(sessionID, md, contextUser);
             session.Status = 'Open';
+            // A thrown save or read may pass on a later attempt; a refusal above would not.
+            trigger.Report.Retryable = true;
             LogError(`[CheckoutSessionService] CompleteCheckout failed for session ${sessionID}: ${msg}`);
             return {
                 Success: false,
@@ -2284,7 +2395,7 @@ export class CheckoutSessionService {
      * booked through the ordinary checkout capture, which also replaces the renewal card. No order is
      * created or confirmed here — the renewal order already is.
      */
-    static async completeRenewalPayment(session, md, contextUser) {
+    static async completeRenewalPayment(session, md, contextUser, trigger) {
         const refuse = (message, status = session.Status) => ({
             Success: false,
             ErrorMessage: message,
@@ -2303,16 +2414,18 @@ export class CheckoutSessionService {
             return refuse(paymentProblem.Message);
         }
         if (!(await this.latchSessionProcessingAtomic(session.ID, md, contextUser))) {
+            trigger.Report.Retryable = true;
             return refuse('Session is not in an Open status or was concurrently processed', 'Unknown');
         }
         if (!(await this.stampSessionConfirmedAtomic(session.ID, renewal.OrderID, md, contextUser))) {
             await this.revertSessionOpenAtomic(session.ID, md, contextUser);
+            trigger.Report.Retryable = true;
             return refuse('The renewal payment could not be recorded. Please try again.', 'Open');
         }
         session.Status = 'Confirmed';
         const order = await md.GetEntityObject(ORDER_HEADER_ENTITY, contextUser);
         if (await order.Load(renewal.OrderID)) {
-            await this.applySettledPaymentToOrder(session, order, contextUser, { Source: 'Checkout' });
+            trigger.Report.Capture = await this.applySettledPaymentToOrder(session, order, contextUser, { Source: trigger.Source });
         }
         return {
             Success: true,
@@ -2412,26 +2525,36 @@ export class CheckoutSessionService {
      *   2. This method, from `payment_intent.succeeded` — including AlreadyApplied deliveries,
      *      so a 500 after the intent row is stamped still converges on the next Stripe retry.
      *
-     * No-ops when the intent is not a confirmed checkout session (back-office captures).
+     * A session the payment settled for that is still Open was never completed: the buyer's page
+     * closed before it asked (#724). This method completes it, as the browser would have. One that
+     * expired first is past completing, and raises the "settled with no order" alert.
+     *
+     * No-ops when no checkout session owns the intent (back-office captures).
      */
     static async BookSettledCheckoutPaymentIfNeeded(paymentIntentID, contextUser) {
         if (!paymentIntentID) {
             return { Attempted: false, Booked: false };
         }
-        const rv = new RunView();
-        const found = await rv.RunView({
-            EntityName: CHECKOUT_SESSION_ENTITY,
-            ExtraFilter: `PaymentIntentID = '${EscapeText(paymentIntentID)}' AND Status = 'Confirmed'`,
-            MaxRows: 1,
-            ResultType: 'simple',
-        }, contextUser);
-        const sessionID = found?.Results?.[0]?.ID;
-        if (!sessionID) {
-            return { Attempted: false, Booked: false };
-        }
         const md = new Metadata();
         const session = await md.GetEntityObject(CHECKOUT_SESSION_ENTITY, contextUser);
-        if (!(await session.Load(sessionID)) || !session.DraftOrderID) {
+        const sessionID = (await this.sessionIDForIntent(paymentIntentID, `Status = 'Confirmed'`, contextUser)) ??
+            (await this.sessionIDForIntent(paymentIntentID, `Status IN ('Open', 'Processing', 'Expired')`, contextUser));
+        if (!sessionID || !(await session.Load(sessionID))) {
+            return { Attempted: false, Booked: false };
+        }
+        await this.awaitProcessingFinished(session);
+        if (session.Status === 'Open') {
+            return this.completeFromWebhook(session, md, contextUser);
+        }
+        if (session.Status === 'Processing') {
+            return { Attempted: true, Booked: false, Retryable: true, ErrorMessage: 'the checkout is still being completed' };
+        }
+        if (session.Status === 'Expired') {
+            const reason = 'The checkout expired before it was completed, so its settled payment has no order.';
+            void raiseCheckoutSettledNotBookedAlert(session.ID, session.PaymentIntentID, reason, contextUser);
+            return { Attempted: true, Booked: false, Retryable: false, ErrorMessage: reason };
+        }
+        if (session.Status !== 'Confirmed' || !session.DraftOrderID) {
             return { Attempted: false, Booked: false };
         }
         const order = await md.GetEntityObject(ORDER_HEADER_ENTITY, contextUser);
@@ -2440,6 +2563,17 @@ export class CheckoutSessionService {
         }
         return this.applySettledPaymentToOrder(session, order, contextUser, { Source: 'Webhook' });
     }
+    /** The checkout session that opened this payment intent, among those `statusFilter` admits. */
+    static async sessionIDForIntent(paymentIntentID, statusFilter, contextUser) {
+        const rv = new RunView();
+        const found = await rv.RunView({
+            EntityName: CHECKOUT_SESSION_ENTITY,
+            ExtraFilter: `PaymentIntentID = '${EscapeText(paymentIntentID)}' AND ${statusFilter}`,
+            MaxRows: 1,
+            ResultType: 'simple',
+        }, contextUser);
+        return found?.Results?.[0]?.ID;
+    }
     /**
      * Operator replay of the Capture step (`Orders.ReplayCheckoutStep`, #326). The same idempotent
      * CapturePayment as the complete call and the webhook, recorded as a Replay by the operator.