feat: support pending changes for plan upgrades (supabase#36430)

This PR implements the new flow to confirm subscription upgrades using Orb pending changes. This is backwards compatible and based on a flag exposed by the backend (`subscriptionPreview.pending_subscription_flow`).

Just like the organization creation, the entire flow is slightly different - instead of creating a payment method separately, the payment method is added inline while doing the upgrade and then attached to the customer. If payment fails, the upgrade will not go through. If payment requires additional action, the user needs to confirm the payment before allowing the upgrade.

For testing the new flow locally, toggle the flag in `flags.ts` on the backend.

Changes include
- No longer rely on the `changeType` from the plans endpoint as this is regularly out-of-sync and displays wrong up/downgrade info due to race conditions
- `readOnly` mode for Stripe elements if anything is loading/submitting
- Reduced prop drilling for some components
- Hide payment method and address selection on downgrade

Author: kevcodez

apps/studio/components/interfaces/Billing/Subscription/Subscription.utils.ts

@@ -1,4 +1,4 @@
-import type { OrgSubscription, ProjectSelectedAddon } from 'data/subscriptions/types'
+import type { OrgSubscription, PlanId, ProjectSelectedAddon } from 'data/subscriptions/types'
 import { IS_PLATFORM } from 'lib/constants'
 
 export const getAddons = (selectedAddons: ProjectSelectedAddon[]) => {
@@ -32,3 +32,43 @@ export const billingPartnerLabel = (billingPartner?: string) => {
       return billingPartner
   }
 }
+
+type PlanChangeType = 'upgrade' | 'downgrade' | 'none'
+
+export const getPlanChangeType = (
+  fromPlan: PlanId | undefined,
+  toPlan: PlanId | undefined
+): PlanChangeType => {
+  const planChangeTypes: Record<PlanId, Record<PlanId, PlanChangeType>> = {
+    free: {
+      free: 'none',
+      pro: 'upgrade',
+      team: 'upgrade',
+      enterprise: 'upgrade',
+    },
+    pro: {
+      free: 'downgrade',
+      pro: 'none',
+      team: 'upgrade',
+      enterprise: 'upgrade',
+    },
+    team: {
+      free: 'downgrade',
+      pro: 'downgrade',
+      team: 'none',
+      enterprise: 'upgrade',
+    },
+    enterprise: {
+      free: 'downgrade',
+      pro: 'downgrade',
+      team: 'downgrade',
+      enterprise: 'none',
+    },
+  }
+
+  if (!fromPlan || !toPlan) {
+    return 'none'
+  }
+
+  return planChangeTypes[fromPlan]?.[toPlan] ?? 'none'
+}

apps/studio/components/interfaces/Organization/BillingSettings/CreditTopUp.tsx

@@ -252,8 +252,10 @@ export const CreditTopUp = ({ slug }: { slug: string | undefined }) => {
                   name="paymentMethod"
                   render={() => (
                     <PaymentMethodSelection
+                      createPaymentMethodInline={false}
                       onSelectPaymentMethod={(pm) => form.setValue('paymentMethod', pm)}
                       selectedPaymentMethod={form.getValues('paymentMethod')}
+                      readOnly={executingTopUp || paymentConfirmationLoading}
                     />
                   )}
                 />

apps/studio/components/interfaces/Organization/BillingSettings/PaymentMethods/NewPaymentMethodElement.tsx

@@ -15,7 +15,8 @@ const NewPaymentMethodElement = forwardRef(
     {
       pending_subscription_flow_enabled,
       email,
-    }: { pending_subscription_flow_enabled: boolean; email?: string },
+      readOnly,
+    }: { pending_subscription_flow_enabled: boolean; email?: string; readOnly: boolean },
     ref
   ) => {
     const stripe = useStripe()
@@ -58,7 +59,7 @@ const NewPaymentMethodElement = forwardRef(
       createPaymentMethod,
     }))
 
-    return <PaymentElement options={{ defaultValues: { billingDetails: { email } } }} />
+    return <PaymentElement options={{ defaultValues: { billingDetails: { email } }, readOnly }} />
   }
 )
 

apps/studio/components/interfaces/Organization/BillingSettings/Subscription/DowngradeModal.tsx

@@ -5,10 +5,11 @@ import type { OrgSubscription, ProjectAddon } from 'data/subscriptions/types'
 import { PricingInformation } from 'shared-data'
 import { Modal } from 'ui'
 import { Admonition } from 'ui-patterns'
+import { plans as subscriptionsPlans } from 'shared-data/plans'
+import { useMemo } from 'react'
 
 export interface DowngradeModalProps {
   visible: boolean
-  selectedPlan?: PricingInformation
   subscription?: OrgSubscription
   onClose: () => void
   onConfirm: () => void
@@ -50,12 +51,13 @@ const ProjectDowngradeListItem = ({ projectAddon }: { projectAddon: ProjectAddon
 
 const DowngradeModal = ({
   visible,
-  selectedPlan,
   subscription,
   onClose,
   onConfirm,
   projects,
 }: DowngradeModalProps) => {
+  const selectedPlan = useMemo(() => subscriptionsPlans.find((tier) => tier.id === 'tier_free'), [])
+
   // Filter out the micro addon as we're dealing with that separately
   const previousProjectAddons =
     subscription?.project_addons.flatMap((projectAddons) => {

apps/studio/components/interfaces/Organization/BillingSettings/Subscription/PaymentMethodSelection.tsx

@@ -1,43 +1,143 @@
 import { PermissionAction } from '@supabase/shared-types/out/constants'
-import { useEffect, useState } from 'react'
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 import { toast } from 'sonner'
 
 import AddNewPaymentMethodModal from 'components/interfaces/Billing/Payment/AddNewPaymentMethodModal'
 import { ButtonTooltip } from 'components/ui/ButtonTooltip'
 import { useOrganizationPaymentMethodsQuery } from 'data/organizations/organization-payment-methods-query'
 import { useCheckPermissions } from 'hooks/misc/useCheckPermissions'
 import { useSelectedOrganization } from 'hooks/misc/useSelectedOrganization'
-import { BASE_PATH } from 'lib/constants'
+import { BASE_PATH, STRIPE_PUBLIC_KEY } from 'lib/constants'
 import { getURL } from 'lib/helpers'
 import { AlertCircle, CreditCard, Loader, Plus } from 'lucide-react'
 import { Listbox } from 'ui'
+import HCaptcha from '@hcaptcha/react-hcaptcha'
+import { useIsHCaptchaLoaded } from 'stores/hcaptcha-loaded-store'
+import { useOrganizationPaymentMethodSetupIntent } from 'data/organizations/organization-payment-method-setup-intent-mutation'
+import { SetupIntentResponse } from 'data/stripe/setup-intent-mutation'
+import { loadStripe, PaymentMethod, StripeElementsOptions } from '@stripe/stripe-js'
+import { getStripeElementsAppearanceOptions } from 'components/interfaces/Billing/Payment/Payment.utils'
+import { useTheme } from 'next-themes'
+import { Elements } from '@stripe/react-stripe-js'
+import { NewPaymentMethodElement } from '../PaymentMethods/NewPaymentMethodElement'
+import ShimmeringLoader from 'ui-patterns/ShimmeringLoader'
+
+const stripePromise = loadStripe(STRIPE_PUBLIC_KEY)
 
 export interface PaymentMethodSelectionProps {
   selectedPaymentMethod?: string
   onSelectPaymentMethod: (id: string) => void
   layout?: 'vertical' | 'horizontal'
+  createPaymentMethodInline: boolean
+  readOnly: boolean
 }
 
-const PaymentMethodSelection = ({
-  selectedPaymentMethod,
-  onSelectPaymentMethod,
-  layout = 'vertical',
-}: PaymentMethodSelectionProps) => {
+const PaymentMethodSelection = forwardRef(function PaymentMethodSelection(
+  {
+    selectedPaymentMethod,
+    onSelectPaymentMethod,
+    layout = 'vertical',
+    createPaymentMethodInline = false,
+    readOnly,
+  }: PaymentMethodSelectionProps,
+  ref
+) {
   const selectedOrganization = useSelectedOrganization()
   const slug = selectedOrganization?.slug
   const [showAddNewPaymentMethodModal, setShowAddNewPaymentMethodModal] = useState(false)
+  const captchaLoaded = useIsHCaptchaLoaded()
+  const [captchaToken, setCaptchaToken] = useState<string | null>(null)
+  const [captchaRef, setCaptchaRef] = useState<HCaptcha | null>(null)
+  const [setupIntent, setSetupIntent] = useState<SetupIntentResponse | undefined>(undefined)
+  const { resolvedTheme } = useTheme()
+  const paymentRef = useRef<{ createPaymentMethod: () => Promise<PaymentMethod | undefined> }>(null)
+  const [setupNewPaymentMethod, setSetupNewPaymentMethod] = useState<boolean | null>(null)
 
   const {
     data: paymentMethods,
     isLoading,
     refetch: refetchPaymentMethods,
   } = useOrganizationPaymentMethodsQuery({ slug })
 
+  const captchaRefCallback = useCallback((node: any) => {
+    setCaptchaRef(node)
+  }, [])
+
+  const { mutate: initSetupIntent, isLoading: setupIntentLoading } =
+    useOrganizationPaymentMethodSetupIntent({
+      onSuccess: (intent) => {
+        setSetupIntent(intent)
+      },
+      onError: (error) => {
+        toast.error(`Failed to setup intent: ${error.message}`)
+      },
+    })
+
+  useEffect(() => {
+    if (paymentMethods?.data && paymentMethods.data.length === 0 && setupNewPaymentMethod == null) {
+      setSetupNewPaymentMethod(true)
+    }
+  }, [paymentMethods])
+
+  useEffect(() => {
+    const loadSetupIntent = async (hcaptchaToken: string | undefined) => {
+      const slug = selectedOrganization?.slug
+      if (!slug) return console.error('Slug is required')
+      if (!hcaptchaToken) return console.error('HCaptcha token required')
+
+      setSetupIntent(undefined)
+      initSetupIntent({ slug: slug!, hcaptchaToken })
+    }
+
+    const loadPaymentForm = async () => {
+      if (setupNewPaymentMethod && createPaymentMethodInline && captchaRef && captchaLoaded) {
+        let token = captchaToken
+
+        try {
+          if (!token) {
+            const captchaResponse = await captchaRef.execute({ async: true })
+            token = captchaResponse?.response ?? null
+          }
+        } catch (error) {
+          return
+        }
+
+        await loadSetupIntent(token ?? undefined)
+        resetCaptcha()
+      }
+    }
+
+    loadPaymentForm()
+  }, [createPaymentMethodInline, captchaRef, captchaLoaded, setupNewPaymentMethod])
+
+  const resetCaptcha = () => {
+    setCaptchaToken(null)
+    captchaRef?.resetCaptcha()
+  }
+
   const canUpdatePaymentMethods = useCheckPermissions(
     PermissionAction.BILLING_WRITE,
     'stripe.payment_methods'
   )
 
+  const stripeOptionsPaymentMethod: StripeElementsOptions = useMemo(
+    () =>
+      ({
+        clientSecret: setupIntent ? setupIntent.client_secret! : '',
+        appearance: getStripeElementsAppearanceOptions(resolvedTheme),
+        paymentMethodCreation: 'manual',
+      }) as const,
+    [setupIntent, resolvedTheme]
+  )
+
   useEffect(() => {
     if (paymentMethods?.data && paymentMethods.data.length > 0) {
       const selectedPaymentMethodExists = paymentMethods.data.some(
@@ -55,15 +155,49 @@ const PaymentMethodSelection = ({
     }
   }, [selectedPaymentMethod, paymentMethods, onSelectPaymentMethod])
 
+  // If createPaymentMethod already exists, use it. Otherwise, define it here.
+  const createPaymentMethod = async () => {
+    if (setupNewPaymentMethod || (paymentMethods?.data && paymentMethods.data.length === 0)) {
+      return paymentRef.current?.createPaymentMethod()
+    } else {
+      return { id: selectedPaymentMethod }
+    }
+  }
+
+  useImperativeHandle(ref, () => ({
+    createPaymentMethod,
+  }))
+
   return (
     <>
+      <HCaptcha
+        ref={captchaRefCallback}
+        sitekey={process.env.NEXT_PUBLIC_HCAPTCHA_SITE_KEY!}
+        size="invisible"
+        onOpen={() => {
+          // [Joshen] This is to ensure that hCaptcha popup remains clickable
+          if (document !== undefined) document.body.classList.add('!pointer-events-auto')
+        }}
+        onClose={() => {
+          setSetupIntent(undefined)
+          if (document !== undefined) document.body.classList.remove('!pointer-events-auto')
+        }}
+        onVerify={(token) => {
+          setCaptchaToken(token)
+          if (document !== undefined) document.body.classList.remove('!pointer-events-auto')
+        }}
+        onExpire={() => {
+          setCaptchaToken(null)
+        }}
+      />
+
       <div>
         {isLoading ? (
           <div className="flex items-center px-4 py-2 space-x-4 border rounded-md border-strong bg-surface-200">
             <Loader className="animate-spin" size={14} />
             <p className="text-sm text-foreground-light">Retrieving payment methods</p>
           </div>
-        ) : paymentMethods?.data.length === 0 ? (
+        ) : paymentMethods?.data.length === 0 && !createPaymentMethodInline ? (
           <div className="flex items-center justify-between px-4 py-2 border border-dashed rounded-md bg-alternative">
             <div className="flex items-center space-x-4 text-foreground-light">
               <AlertCircle size={16} strokeWidth={1.5} />
@@ -74,7 +208,13 @@ const PaymentMethodSelection = ({
               type="default"
               disabled={!canUpdatePaymentMethods}
               icon={<CreditCard />}
-              onClick={() => setShowAddNewPaymentMethodModal(true)}
+              onClick={() => {
+                if (createPaymentMethodInline) {
+                  setSetupNewPaymentMethod(true)
+                } else {
+                  setShowAddNewPaymentMethodModal(true)
+                }
+              }}
               htmlType="button"
               tooltip={{
                 content: {
@@ -93,7 +233,7 @@ const PaymentMethodSelection = ({
               Add new
             </ButtonTooltip>
           </div>
-        ) : (
+        ) : paymentMethods?.data && paymentMethods?.data.length > 0 && !setupNewPaymentMethod ? (
           <Listbox
             layout={layout}
             label="Payment method"
@@ -126,14 +266,42 @@ const PaymentMethodSelection = ({
             })}
             <div
               className="flex items-center px-3 py-2 space-x-2 transition cursor-pointer group hover:bg-surface-300"
-              onClick={() => setShowAddNewPaymentMethodModal(true)}
+              onClick={() => {
+                if (createPaymentMethodInline) {
+                  setSetupNewPaymentMethod(true)
+                } else {
+                  setShowAddNewPaymentMethodModal(true)
+                }
+              }}
             >
               <Plus size={16} />
               <p className="transition text-foreground-light group-hover:text-foreground">
                 Add new payment method
               </p>
             </div>
           </Listbox>
+        ) : null}
+
+        {stripePromise && setupIntent && (
+          <Elements stripe={stripePromise} options={stripeOptionsPaymentMethod}>
+            <NewPaymentMethodElement
+              ref={paymentRef}
+              pending_subscription_flow_enabled={true}
+              email={selectedOrganization?.billing_email}
+              readOnly={readOnly}
+            />
+          </Elements>
+        )}
+
+        {setupIntentLoading && (
+          <div className="space-y-2">
+            <ShimmeringLoader className="h-10" />
+            <div className="grid grid-cols-2 gap-4">
+              <ShimmeringLoader className="h-10" />
+              <ShimmeringLoader className="h-10" />
+            </div>
+            <ShimmeringLoader className="h-10" />
+          </div>
         )}
       </div>
 
@@ -158,6 +326,8 @@ const PaymentMethodSelection = ({
       />
     </>
   )
-}
+})
+
+PaymentMethodSelection.displayName = 'PaymentMethodSelection'
 
 export default PaymentMethodSelection