@oneuptime/common 13.0.5 → 13.0.6

package/build/dist/Server/Services/BillingService.js

@@ -92,6 +92,43 @@ const RETRYABLE_CONNECTION_ERROR_CODES = [
     "EAI_AGAIN",
     "ENOTFOUND",
 ];
+/*
+ * Stripe's refusal to charge an invoice while its PaymentIntent is waiting on
+ * the cardholder. Another card cannot help anywhere: the invoice already has a
+ * payment in flight, and a second charge would be a second debit.
+ */
+const INVOICE_REQUIRES_ACTION_ERROR_CODE = "invoice_payment_intent_requires_action";
+/*
+ * Stripe declines that mean "the card is fine, the cardholder has to
+ * authenticate". They arrive as a StripeCardError. Whether a backup card
+ * should be charged instead depends on who is watching - see
+ * canRetryWithDifferentPaymentMethod.
+ */
+const AUTHENTICATION_REQUIRED_ERROR_CODES = [
+    "authentication_required",
+];
+/*
+ * Subscriptions that will never raise another invoice. Their payment method
+ * is irrelevant, and Stripe refuses updates to a canceled subscription.
+ */
+const FINISHED_SUBSCRIPTION_STATUSES = [
+    "canceled",
+    "incomplete_expired",
+];
+/*
+ * Statuses where Stripe refuses a default_payment_method update outright.
+ *
+ * An `incomplete` subscription is one whose very first invoice has not been
+ * paid; the API reference is explicit that such a subscription "can only have
+ * metadata and default_source updated", and answers anything else with a 400.
+ * Attempting it would fail the whole repair for the customer whose pin we are
+ * trying to clear, so the pin is left where it is: within 23 hours the
+ * subscription either becomes active - and the next card change syncs it - or
+ * turns into incomplete_expired, with its open invoice voided and no further
+ * invoice ever raised. default_source is still cleared, because Stripe allows
+ * that one even here.
+ */
+const STATUSES_REFUSING_PAYMENT_METHOD_UPDATE = ["incomplete"];
 export class BillingService extends BaseService {
     constructor() {
         super();
@@ -623,7 +660,7 @@ export class BillingService extends BaseService {
                 providerError.rawType === "invalid_request_error"));
     }
     async changePlan(data) {
-        var _a, _b, _c;
+        var _a;
         logger.debug("Changing plan");
         logger.debug(data);
         if (!this.isBillingEnabled()) {
@@ -736,6 +773,23 @@ export class BillingService extends BaseService {
                 endTrialAt: endTrialAt,
             });
         }
+        /*
+         * The replacements are created WITHOUT a subscription-level
+         * default_payment_method, on purpose.
+         *
+         * Stripe charges subscription.default_payment_method ahead of the
+         * customer's default. Passing the card that happened to be default on the
+         * day of the plan change pinned the new subscriptions to it for good: when
+         * that card later started declining and the customer added a new one and
+         * made it their default, autopay kept charging the old card, and the
+         * project went past_due on a card the customer had already replaced.
+         *
+         * Left unpinned, every invoice is charged to whatever the customer's
+         * default is when the invoice is raised. The paymentMethods.length guard
+         * above still applies - getPaymentMethods promotes a default whenever the
+         * customer has a payment method but no default, so an unpinned
+         * subscription has a card to fall back to.
+         */
         if (!canSwapPriceOnSubscription) {
             logger.debug("Replacing the flat-fee subscription");
             newSubscriptionId = await this.createFlatFeeSubscription({
@@ -744,7 +798,6 @@ export class BillingService extends BaseService {
                 quantity: data.quantity,
                 isYearly: data.isYearly,
                 trialDate: endTrialAt || null,
-                defaultPaymentMethodId: (_b = paymentMethods[0]) === null || _b === void 0 ? void 0 : _b.id,
                 metadata: this.getReplacementSubscriptionMetadata({
                     projectId: data.projectId,
                     replacedSubscriptionId: data.subscriptionId,
@@ -761,7 +814,7 @@ export class BillingService extends BaseService {
                 customerId: customerId,
                 serverMeteredPlans: data.serverMeteredPlans,
                 trialDate: endTrialAt || null,
-                defaultPaymentMethodId: (_c = paymentMethods[0]) === null || _c === void 0 ? void 0 : _c.id,
+                // Unpinned for the same reason as the flat-fee replacement above.
                 metadata: this.getReplacementSubscriptionMetadata({
                     projectId: data.projectId,
                     replacedSubscriptionId: data.meteredSubscriptionId,
@@ -930,11 +983,108 @@ export class BillingService extends BaseService {
         if (!this.isBillingEnabled()) {
             throw new BadDataException(Errors.BillingService.BILLING_NOT_ENABLED);
         }
+        /*
+         * Detaching is by payment method id alone - Stripe does not ask which
+         * customer it belongs to - so the caller's customer is checked here rather
+         * than trusted to have been checked upstream.
+         */
+        await this.assertPaymentMethodBelongsToCustomer({
+            customerId: customerId,
+            paymentMethodId: paymentMethodId,
+        });
         const paymentMethods = await this.getPaymentMethods(customerId);
         if (paymentMethods.length === 1) {
             throw new BadDataException(Errors.BillingService.MIN_REQUIRED_PAYMENT_METHOD_NOT_MET);
         }
         await this.stripe.paymentMethods.detach(paymentMethodId);
+        const remainingPaymentMethods = paymentMethods.filter((paymentMethod) => {
+            return paymentMethod.id !== paymentMethodId;
+        });
+        /*
+         * Everything below repairs state after a detach that has already
+         * happened, so none of it is allowed to fail the delete: the card is gone
+         * whether or not these land, and reporting the delete as failed would only
+         * make the customer try again against a card that no longer exists. A
+         * repair that does not land is picked up by the next read of the payment
+         * methods, which promotes a default (and re-syncs the subscriptions) when
+         * the customer has none.
+         */
+        try {
+            /*
+             * Detaching the customer's default leaves the customer with no default
+             * at all, and an unpinned subscription with no customer default cannot
+             * be charged. Promote the card that getPaymentMethods would have charged
+             * next, so autopay has somewhere to go before the next invoice.
+             */
+            const hasDefaultLeft = remainingPaymentMethods.some((paymentMethod) => {
+                return paymentMethod.isDefault;
+            });
+            if (!hasDefaultLeft && remainingPaymentMethods[0]) {
+                await this.setDefaultPaymentMethod(customerId, remainingPaymentMethods[0].id);
+            }
+            /*
+             * A subscription pinned to the detached card - or to any card other than
+             * the default - would otherwise keep trying to charge it. Clear the pin so
+             * the (possibly new) customer default decides.
+             */
+            await this.syncSubscriptionPaymentMethodsWithCustomerDefault(customerId);
+        }
+        catch (err) {
+            logger.error(`Detached payment method ${paymentMethodId} for customer ${customerId}, but could not repair the default payment method or the subscriptions' payment method: ${err}`, { customerId });
+        }
+    }
+    /*
+     * Makes a payment method the customer's default, and makes autopay use it.
+     *
+     * Setting the customer default alone is not enough: a subscription with its
+     * own default_payment_method ignores the customer default entirely, which is
+     * how a customer who replaced a declining card kept being charged on the old
+     * one. The subscriptions are re-synced here, and a failure to do that is
+     * reported rather than swallowed - the customer asked for autopay to move to
+     * this card, and a success response would tell them it had.
+     */
+    async makePaymentMethodDefault(customerId, paymentMethodId) {
+        if (!this.isBillingEnabled()) {
+            throw new BadDataException(Errors.BillingService.BILLING_NOT_ENABLED);
+        }
+        await this.assertPaymentMethodBelongsToCustomer({
+            customerId: customerId,
+            paymentMethodId: paymentMethodId,
+        });
+        await this.setDefaultPaymentMethod(customerId, paymentMethodId);
+        await this.syncSubscriptionPaymentMethodsWithCustomerDefault(customerId);
+    }
+    /*
+     * Refuses a payment method that is not attached to this customer.
+     *
+     * The payment method id arrives from the browser. Without this, a project
+     * could make - or detach - a card attached to another project's customer.
+     * A payment method Stripe does not know gets the same answer as one that
+     * belongs to someone else, so the response says nothing about which ids
+     * exist.
+     */
+    async assertPaymentMethodBelongsToCustomer(data) {
+        const notOwnedError = new BadDataException("Payment method does not belong to this project");
+        if (!data.paymentMethodId || !data.customerId) {
+            throw notOwnedError;
+        }
+        let paymentMethod;
+        try {
+            paymentMethod = await this.readPaymentProvider(() => {
+                return this.stripe.paymentMethods.retrieve(data.paymentMethodId);
+            });
+        }
+        catch (err) {
+            if (this.isResourceMissingError(err)) {
+                throw notOwnedError;
+            }
+            throw err;
+        }
+        const owner = paymentMethod === null || paymentMethod === void 0 ? void 0 : paymentMethod.customer;
+        const ownerId = typeof owner === "string" ? owner : (owner === null || owner === void 0 ? void 0 : owner.id) || undefined;
+        if (!ownerId || ownerId !== data.customerId) {
+            throw notOwnedError;
+        }
     }
     async hasPaymentMethods(customerId) {
         if (!this.isBillingEnabled()) {
@@ -1082,11 +1232,162 @@ export class BillingService extends BaseService {
         return startsAt;
     }
     async setDefaultPaymentMethod(customerId, paymentMethodId) {
-        await this.stripe.customers.update(customerId, {
-            invoice_settings: {
-                default_payment_method: paymentMethodId,
+        await this.writePaymentProvider({
+            write: () => {
+                return this.stripe.customers.update(customerId, {
+                    invoice_settings: {
+                        default_payment_method: paymentMethodId,
+                    },
+                });
             },
+            actionDescription: "update your default payment method",
+        });
+    }
+    /**
+     * A write to the payment provider, reported the way a read is.
+     *
+     * It is NOT retried: a read that is repeated costs a second lookup, while a
+     * write that is repeated can apply the change twice. What this adds is the
+     * translation - a raw StripeError is not an OneUptime Exception, so it
+     * reaches the express handler's fallback branch and becomes an opaque
+     * 500 {"error":"Server Error"}. On the flow that repairs autopay that is the
+     * worst possible answer: the customer is told "Server Error" and cannot tell
+     * a rate limit they should retry from a card the provider refused.
+     */
+    async writePaymentProvider(data) {
+        try {
+            return await data.write();
+        }
+        catch (err) {
+            throw BillingService.toPaymentProviderWriteFailure(err, data.actionDescription);
+        }
+    }
+    /**
+     * Names the real condition behind a failed provider write.
+     *
+     * Anything that is not the provider talking is left exactly as it is: a bug
+     * of ours dressed up as a payment error would send the reader looking at
+     * Stripe's status page instead of at the stack trace.
+     */
+    static toPaymentProviderWriteFailure(err, actionDescription) {
+        if (err instanceof Exception) {
+            return err;
+        }
+        const providerError = (err !== null && err !== void 0 ? err : {});
+        const isProviderError = typeof providerError.statusCode === "number" ||
+            (typeof providerError.type === "string" &&
+                providerError.type.startsWith("Stripe"));
+        if (!isProviderError) {
+            return err;
+        }
+        logger.error(err);
+        /*
+         * The same classification the read path uses: a rate limit, a provider
+         * 5xx or a dropped connection is the provider being unavailable, and the
+         * customer should be told to try again rather than that their card is
+         * wrong.
+         */
+        if (BillingService.isRetryablePaymentProviderRead(err)) {
+            return new ServiceUnavailableException(`Could not reach the payment provider to ${actionDescription}${providerError.code ? ` (${providerError.code})` : ""}. Please try again.`);
+        }
+        const providerMessage = ((err === null || err === void 0 ? void 0 : err.message) || "").trim();
+        return new BadDataException(providerMessage || `Could not ${actionDescription}. Please try again.`);
+    }
+    /*
+     * Makes every live subscription of the customer charge the customer's
+     * default payment method.
+     *
+     * Stripe picks the card for a subscription invoice in this order:
+     * subscription.default_payment_method, subscription.default_source, then
+     * customer.invoice_settings.default_payment_method. A subscription created
+     * with its own default_payment_method therefore keeps charging that card
+     * forever - changing the customer's default, adding a new card, or paying
+     * one invoice by hand with another card does not move it. That is how a
+     * customer who replaced a declining card kept seeing autopay fail against
+     * the old one.
+     *
+     * The fix is to clear the subscription-level pin so the customer default
+     * decides, rather than to copy the default onto the subscription: a copy is
+     * a second place that has to be kept in step, and it is that second place
+     * going stale that broke autopay.
+     *
+     * Nothing is cleared while the customer has no default payment method -
+     * there is nothing for the subscription to fall back to, and an unpinned
+     * subscription with no customer default cannot be charged at all. An
+     * `incomplete` subscription keeps its pin too, because Stripe refuses that
+     * update outright - see STATUSES_REFUSING_PAYMENT_METHOD_UPDATE.
+     *
+     * Returns the ids of the subscriptions that were changed.
+     */
+    async syncSubscriptionPaymentMethodsWithCustomerDefault(customerId) {
+        var _a;
+        if (!this.isBillingEnabled()) {
+            throw new BadDataException(Errors.BillingService.BILLING_NOT_ENABLED);
+        }
+        const customer = await this.readPaymentProvider(() => {
+            return this.stripe.customers.retrieve(customerId);
+        });
+        if (customer.deleted) {
+            return [];
+        }
+        const customerDefault = (_a = customer.invoice_settings) === null || _a === void 0 ? void 0 : _a.default_payment_method;
+        const customerDefaultId = typeof customerDefault === "string"
+            ? customerDefault
+            : (customerDefault === null || customerDefault === void 0 ? void 0 : customerDefault.id) || undefined;
+        if (!customerDefaultId) {
+            return [];
+        }
+        const subscriptions = await this.readPaymentProvider(() => {
+            return this.stripe.subscriptions.list({
+                customer: customerId,
+                status: "all",
+                limit: 100,
+            });
         });
+        const updatedSubscriptionIds = [];
+        for (const subscription of subscriptions.data) {
+            if (FINISHED_SUBSCRIPTION_STATUSES.includes(subscription.status)) {
+                continue;
+            }
+            const pinnedPaymentMethod = subscription.default_payment_method;
+            const pinnedPaymentMethodId = typeof pinnedPaymentMethod === "string"
+                ? pinnedPaymentMethod
+                : (pinnedPaymentMethod === null || pinnedPaymentMethod === void 0 ? void 0 : pinnedPaymentMethod.id) || undefined;
+            const updateParams = {};
+            const isStalePin = Boolean(pinnedPaymentMethodId && pinnedPaymentMethodId !== customerDefaultId);
+            const canUpdatePaymentMethod = !STATUSES_REFUSING_PAYMENT_METHOD_UPDATE.includes(subscription.status);
+            if (isStalePin && canUpdatePaymentMethod) {
+                // An empty string unsets the field, so the customer default applies.
+                updateParams.default_payment_method = "";
+            }
+            if (isStalePin && !canUpdatePaymentMethod) {
+                logger.debug(`Leaving the payment method of ${subscription.status} subscription ${subscription.id} pinned: the payment provider refuses that update in this state`);
+            }
+            /*
+             * A legacy source outranks the customer default too. It is only
+             * consulted when the subscription has no default_payment_method - the
+             * state the line above leaves it in - so it is cleared in the same
+             * request. Stripe allows this field even on an `incomplete`
+             * subscription, so it is cleared there as well.
+             */
+            if (subscription.default_source) {
+                updateParams.default_source = "";
+            }
+            if (Object.keys(updateParams).length === 0) {
+                continue;
+            }
+            await this.writePaymentProvider({
+                write: () => {
+                    return this.stripe.subscriptions.update(subscription.id, updateParams);
+                },
+                actionDescription: "move automatic payments to your default card",
+            });
+            updatedSubscriptionIds.push(subscription.id);
+        }
+        if (updatedSubscriptionIds.length > 0) {
+            logger.info(`Cleared stale subscription-level payment methods for customer ${customerId} on subscriptions ${updatedSubscriptionIds.join(", ")}`);
+        }
+        return updatedSubscriptionIds;
     }
     async getPaymentMethods(customerId) {
         var _a, _b;
@@ -1157,6 +1458,28 @@ export class BillingService extends BaseService {
             // set the first payment method as default.
             await this.setDefaultPaymentMethod(customerId, paymentMethods[0].id);
             paymentMethods[0].isDefault = true;
+            /*
+             * The customer had no default until now, so any subscription pinned to
+             * some other card has been charging that card with nothing to fall back
+             * on. Now that there is a default, point the subscriptions at it.
+             *
+             * Only on this branch. It runs when a customer has no default - their
+             * first card, or right after their default was detached - which is rare.
+             * The common path of this read stays free of subscription reads: every
+             * billing page render goes through here, and extra provider reads per
+             * render are what tipped the account into rate limiting before.
+             *
+             * Best effort: this is a read of the payment methods, and it must still
+             * answer if the subscriptions cannot be updated right now. The next time
+             * the customer adds a card, changes the default or deletes one, the
+             * subscriptions are synced again.
+             */
+            try {
+                await this.syncSubscriptionPaymentMethodsWithCustomerDefault(customerId);
+            }
+            catch (err) {
+                logger.error(`Set ${paymentMethods[0].id} as the default payment method for customer ${customerId}, but could not sync the subscriptions' payment method: ${err}`, { customerId });
+            }
         }
         return paymentMethods;
     }
@@ -1307,6 +1630,30 @@ export class BillingService extends BaseService {
         }
         return paymentIntent.client_secret;
     }
+    /*
+     * What a PaymentIntent is doing right now. An open invoice's PaymentIntent
+     * can be waiting on the cardholder (requires_action), already failed
+     * (requires_payment_method), or still with the bank (processing - an India
+     * e-mandate card debit sits there for about a day). Only the first can be
+     * finished in the browser, so callers have to look before handing a client
+     * secret out.
+     */
+    async getPaymentIntent(paymentIntentId) {
+        var _a;
+        const paymentIntent = await this.readPaymentProvider(() => {
+            return this.stripe.paymentIntents.retrieve(paymentIntentId);
+        });
+        const paymentMethod = paymentIntent.payment_method;
+        return {
+            id: paymentIntent.id,
+            status: paymentIntent.status,
+            clientSecret: paymentIntent.client_secret || undefined,
+            paymentMethodId: typeof paymentMethod === "string"
+                ? paymentMethod
+                : (paymentMethod === null || paymentMethod === void 0 ? void 0 : paymentMethod.id) || undefined,
+            lastPaymentErrorMessage: ((_a = paymentIntent.last_payment_error) === null || _a === void 0 ? void 0 : _a.message) || undefined,
+        };
+    }
     async getPaymentIntentIdFromInvoice(invoiceId) {
         const invoice = await this.stripe.invoices.retrieve(invoiceId);
         if (!invoice) {
@@ -1507,10 +1854,19 @@ export class BillingService extends BaseService {
      * method may succeed.
      *
      * Not retryable:
-     * - invoice_payment_intent_requires_action (3DS/SCA): the payment method
-     *   works but needs customer authentication — throw so the interactive
-     *   flow (BillingInvoiceAPI) surfaces the authentication prompt for the
-     *   default method instead of silently charging a backup method.
+     * - invoice_payment_intent_requires_action (3DS/SCA): the invoice already
+     *   has a payment in flight that is waiting on the cardholder. A second
+     *   card would be a second debit, wherever the call came from.
+     * - authentication_required, but only when the caller can put the
+     *   authentication prompt in front of the cardholder. That is the
+     *   interactive route, which hands the browser the client secret; charging
+     *   a backup card there would move the invoice off the card the customer
+     *   chose and leave the prompt unanswered. Unattended callers
+     *   (generateInvoiceAndChargeCustomer, behind the SMS/call and AI balance
+     *   recharge) have no browser to prompt and no second chance: their invoice
+     *   is voided on failure, so the authentication could never be completed
+     *   anywhere. There, another card is the only way the balance gets topped
+     *   up and paging keeps working.
      * - Invoice-state or connectivity errors: another payment method would
      *   not help, and if the outcome of the attempt is unknown a retry could
      *   double-charge the customer.
@@ -1520,16 +1876,32 @@ export class BillingService extends BaseService {
      * failover only catches the synchronous ones (unverified/unusable
      * accounts).
      */
-    canRetryWithDifferentPaymentMethod(err) {
+    canRetryWithDifferentPaymentMethod(err, options) {
         var _a, _b;
         const stripeError = err;
+        if ((stripeError === null || stripeError === void 0 ? void 0 : stripeError.code) === INVOICE_REQUIRES_ACTION_ERROR_CODE) {
+            return false;
+        }
+        if (options.canSurfaceAuthenticationPrompt &&
+            AUTHENTICATION_REQUIRED_ERROR_CODES.includes((stripeError === null || stripeError === void 0 ? void 0 : stripeError.code) || "")) {
+            return false;
+        }
         if ((stripeError === null || stripeError === void 0 ? void 0 : stripeError.type) === "StripeCardError") {
             return true;
         }
         return Boolean(((_a = stripeError === null || stripeError === void 0 ? void 0 : stripeError.code) === null || _a === void 0 ? void 0 : _a.startsWith("payment_method_")) ||
             ((_b = stripeError === null || stripeError === void 0 ? void 0 : stripeError.code) === null || _b === void 0 ? void 0 : _b.startsWith("bank_account_")));
     }
-    async payInvoice(customerId, invoiceId) {
+    /*
+     * Pays an invoice, falling back to the customer's other cards when one is
+     * declined.
+     *
+     * canSurfaceAuthenticationPrompt says whether the caller is able to show the
+     * cardholder an authentication prompt - true for the interactive
+     * /billing-invoices/pay route, false (the default) for the unattended
+     * recharge paths, which have nobody to prompt.
+     */
+    async payInvoice(customerId, invoiceId, options) {
         var _a, _b, _c, _d;
         // after the invoice is paid, // please fetch subscription and check the status.
         const paymentMethods = await this.getPaymentMethods(customerId);
@@ -1566,7 +1938,9 @@ export class BillingService extends BaseService {
             }
             catch (err) {
                 logger.error(`Failed to pay invoice ${invoiceId} with payment method ${paymentMethod.type} ending in ${paymentMethod.last4Digits}: ${err}`);
-                if (!this.canRetryWithDifferentPaymentMethod(err)) {
+                if (!this.canRetryWithDifferentPaymentMethod(err, {
+                    canSurfaceAuthenticationPrompt: Boolean(options === null || options === void 0 ? void 0 : options.canSurfaceAuthenticationPrompt),
+                })) {
                     throw err;
                 }
                 lastError = err;
@@ -1815,6 +2189,12 @@ __decorate([
     __metadata("design:paramtypes", [String, String]),
     __metadata("design:returntype", Promise)
 ], BillingService.prototype, "deletePaymentMethod", null);
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:returntype", Promise)
+], BillingService.prototype, "makePaymentMethodDefault", null);
 __decorate([
     CaptureSpan(),
     __metadata("design:type", Function),
@@ -1827,6 +2207,12 @@ __decorate([
     __metadata("design:paramtypes", [String, String]),
     __metadata("design:returntype", Promise)
 ], BillingService.prototype, "setDefaultPaymentMethod", null);
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], BillingService.prototype, "syncSubscriptionPaymentMethodsWithCustomerDefault", null);
 __decorate([
     CaptureSpan(),
     __metadata("design:type", Function),
@@ -1881,6 +2267,12 @@ __decorate([
     __metadata("design:paramtypes", [String]),
     __metadata("design:returntype", Promise)
 ], BillingService.prototype, "getPaymentIntentClientSecret", null);
+__decorate([
+    CaptureSpan(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], BillingService.prototype, "getPaymentIntent", null);
 __decorate([
     CaptureSpan(),
     __metadata("design:type", Function),
@@ -1921,7 +2313,7 @@ __decorate([
 __decorate([
     CaptureSpan(),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, String]),
+    __metadata("design:paramtypes", [String, String, Object]),
     __metadata("design:returntype", Promise)
 ], BillingService.prototype, "payInvoice", null);
 __decorate([