Subscription switching: Billing integration (#6787)

Task/Issue URL:
https://app.asana.com/1/137249556945/project/72649045549333/task/1211320822502364?focus=true

### Description
This PR implements the foundational billing infrastructure required for
subscription plan switching functionality. It adds the core Google Play
Billing integration without exposing any UI changes to users.

### Steps to test this PR _Optional_

- [ ] Smoke test subscriptions but no functionality has been added to
the flow
- [ ] CI checks are green ✅ 

### No UI changes

Author: nalcalag

subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/billing/BillingClientAdapter.kt

@@ -38,6 +38,15 @@ interface BillingClientAdapter {
         offerToken: String,
         externalId: String,
     ): LaunchBillingFlowResult
+
+    suspend fun launchSubscriptionUpdate(
+        activity: Activity,
+        productDetails: ProductDetails,
+        offerToken: String,
+        externalId: String,
+        oldPurchaseToken: String,
+        replacementMode: SubscriptionReplacementMode = SubscriptionReplacementMode.DEFERRED,
+    ): LaunchBillingFlowResult
 }
 
 sealed class BillingInitResult {
@@ -92,3 +101,19 @@ enum class BillingError {
     BILLING_CRASH_ERROR, // This is our own error
     ;
 }
+
+/**
+ * Defines supported replacement modes for Google Play Billing subscription updates.
+ *
+ * Currently, we only use the [DEFERRED] mode in our implementation.
+ *
+ * For a complete list of available values, refer to the official documentation:
+ * https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.ReplacementMode
+ */
+enum class SubscriptionReplacementMode(val value: Int) {
+    /**
+     * New subscription starts after current subscription expires.
+     * Best for: When you want to avoid billing complications or user requested delayed switch.
+     */
+    DEFERRED(6),
+}

subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/billing/PlayBillingManager.kt

@@ -77,6 +77,19 @@ interface PlayBillingManager {
         externalId: String,
         offerId: String?,
     )
+
+    /**
+     * Launches the subscription update flow
+     *
+     * It is safe to call this method without specifying dispatcher as it's handled internally
+     */
+    suspend fun launchSubscriptionUpdate(
+        activity: Activity,
+        newPlanId: String,
+        externalId: String,
+        newOfferId: String?,
+        replacementMode: SubscriptionReplacementMode = SubscriptionReplacementMode.DEFERRED,
+    )
 }
 
 @SingleInstanceIn(AppScope::class)
@@ -212,6 +225,63 @@ class RealPlayBillingManager @Inject constructor(
         }
     }
 
+    override suspend fun launchSubscriptionUpdate(
+        activity: Activity,
+        newPlanId: String,
+        externalId: String,
+        newOfferId: String?,
+        replacementMode: SubscriptionReplacementMode,
+    ) = withContext(dispatcherProvider.io()) {
+        if (!billingClient.ready) {
+            logcat { "Service not ready" }
+            connect()
+        }
+
+        val oldPurchaseToken: String? = getCurrentPurchaseToken()
+
+        val productDetails = products.find { it.productId == BASIC_SUBSCRIPTION }
+
+        val offerToken = productDetails
+            ?.subscriptionOfferDetails
+            ?.find { it.basePlanId == newPlanId && it.offerId == newOfferId }
+            ?.offerToken
+
+        if (productDetails == null || offerToken == null || oldPurchaseToken == null) {
+            _purchaseState.emit(Canceled)
+            return@withContext
+        }
+
+        val launchBillingFlowResult = billingClient.launchSubscriptionUpdate(
+            activity = activity,
+            productDetails = productDetails,
+            offerToken = offerToken,
+            externalId = externalId,
+            oldPurchaseToken = oldPurchaseToken,
+            replacementMode = replacementMode,
+        )
+
+        when (launchBillingFlowResult) {
+            LaunchBillingFlowResult.Success -> {
+                _purchaseState.emit(InProgress)
+                billingFlowInProgress = true
+            }
+
+            LaunchBillingFlowResult.Failure -> {
+                _purchaseState.emit(Canceled)
+            }
+        }
+    }
+
+    /**
+     * Gets the current purchase token for the active subscription
+     */
+    private suspend fun getCurrentPurchaseToken(): String? = withContext(dispatcherProvider.io()) {
+        return@withContext purchaseHistory
+            .filter { it.products.contains(BASIC_SUBSCRIPTION) }
+            .maxByOrNull { it.purchaseTime }
+            ?.purchaseToken
+    }
+
     private fun onPurchasesUpdated(result: PurchasesUpdateResult) {
         coroutineScope.launch {
             when (result) {

subscriptions/subscriptions-impl/src/main/java/com/duckduckgo/subscriptions/impl/billing/RealBillingClientAdapter.kt

@@ -178,6 +178,46 @@ class RealBillingClientAdapter @Inject constructor(
         }
     }
 
+    override suspend fun launchSubscriptionUpdate(
+        activity: Activity,
+        productDetails: ProductDetails,
+        offerToken: String,
+        externalId: String,
+        oldPurchaseToken: String,
+        replacementMode: SubscriptionReplacementMode,
+    ): LaunchBillingFlowResult {
+        val client = billingClient
+        if (client == null || !client.isReady) return LaunchBillingFlowResult.Failure
+
+        val subscriptionUpdateParams = BillingFlowParams.SubscriptionUpdateParams.newBuilder()
+            .setOldPurchaseToken(oldPurchaseToken)
+            .setSubscriptionReplacementMode(replacementMode.value)
+            .build()
+
+        val billingFlowParams = BillingFlowParams.newBuilder()
+            .setProductDetailsParamsList(
+                listOf(
+                    BillingFlowParams.ProductDetailsParams.newBuilder()
+                        .setProductDetails(productDetails)
+                        .setOfferToken(offerToken)
+                        .build(),
+                ),
+            )
+            .setObfuscatedAccountId(externalId)
+            .setObfuscatedProfileId(externalId)
+            .setSubscriptionUpdateParams(subscriptionUpdateParams)
+            .build()
+
+        val result = withContext(coroutineDispatchers.main()) {
+            client.launchBillingFlow(activity, billingFlowParams)
+        }
+
+        return when (result.responseCode) {
+            BillingResponseCode.OK -> LaunchBillingFlowResult.Success
+            else -> LaunchBillingFlowResult.Failure
+        }
+    }
+
     private fun reset() {
         billingClient?.endConnection()
         billingClient = null

subscriptions/subscriptions-impl/src/test/java/com/duckduckgo/subscriptions/impl/billing/RealPlayBillingManagerTest.kt

@@ -19,6 +19,7 @@ import com.duckduckgo.subscriptions.impl.billing.FakeBillingClientAdapter.FakeMe
 import com.duckduckgo.subscriptions.impl.billing.FakeBillingClientAdapter.FakeMethodInvocation.GetSubscriptions
 import com.duckduckgo.subscriptions.impl.billing.FakeBillingClientAdapter.FakeMethodInvocation.GetSubscriptionsPurchaseHistory
 import com.duckduckgo.subscriptions.impl.billing.FakeBillingClientAdapter.FakeMethodInvocation.LaunchBillingFlow
+import com.duckduckgo.subscriptions.impl.billing.FakeBillingClientAdapter.FakeMethodInvocation.LaunchSubscriptionUpdate
 import com.duckduckgo.subscriptions.impl.billing.PurchaseState.Canceled
 import com.duckduckgo.subscriptions.impl.billing.PurchaseState.InProgress
 import kotlin.time.Duration.Companion.minutes
@@ -202,6 +203,149 @@ class RealPlayBillingManagerTest {
 
         billingClientAdapter.verifyLaunchBillingFlowInvoked(productDetails, offerToken = offerDetails.offerToken, externalId)
     }
+
+    @Test
+    fun `when launchSubscriptionUpdate called with valid parameters then launches subscription update flow`() = runTest {
+        // Set up purchase history so getCurrentPurchaseToken() returns a valid token
+        val mockPurchase: PurchaseHistoryRecord = mock {
+            whenever(it.products).thenReturn(listOf(BASIC_SUBSCRIPTION))
+            whenever(it.purchaseTime).thenReturn(1000L)
+            whenever(it.purchaseToken).thenReturn("old_purchase_token")
+        }
+        billingClientAdapter.subscriptionsPurchaseHistory = listOf(mockPurchase)
+
+        processLifecycleOwner.currentState = RESUMED
+        runCurrent() // Ensure purchase history is loaded
+
+        billingClientAdapter.launchBillingFlowResult = LaunchBillingFlowResult.Success
+
+        val productDetails = billingClientAdapter.subscriptions.first()
+        val offerDetails = productDetails.subscriptionOfferDetails!!.first()
+        val externalId = "test_external_id"
+        val oldPurchaseToken = "old_purchase_token" // This is what getCurrentPurchaseToken() will return
+        val replacementMode = SubscriptionReplacementMode.DEFERRED
+
+        subject.purchaseState.test {
+            expectNoEvents()
+
+            subject.launchSubscriptionUpdate(
+                activity = mock(),
+                newPlanId = MONTHLY_PLAN_US,
+                externalId = externalId,
+                newOfferId = null,
+                replacementMode = replacementMode,
+            )
+
+            assertEquals(InProgress, awaitItem())
+        }
+
+        billingClientAdapter.verifyLaunchSubscriptionUpdateInvoked(
+            productDetails = productDetails,
+            offerToken = offerDetails.offerToken,
+            externalId = externalId,
+            oldPurchaseToken = oldPurchaseToken,
+            replacementMode = replacementMode,
+        )
+    }
+
+    @Test
+    fun `when launchSubscriptionUpdate called with invalid plan then emits canceled state`() = runTest {
+        // Set up purchase history so getCurrentPurchaseToken() returns a valid token
+        val mockPurchase: PurchaseHistoryRecord = mock {
+            whenever(it.products).thenReturn(listOf(BASIC_SUBSCRIPTION))
+            whenever(it.purchaseTime).thenReturn(1000L)
+            whenever(it.purchaseToken).thenReturn("old_purchase_token")
+        }
+        billingClientAdapter.subscriptionsPurchaseHistory = listOf(mockPurchase)
+
+        processLifecycleOwner.currentState = RESUMED
+        runCurrent() // Ensure purchase history is loaded
+
+        val externalId = "test_external_id"
+
+        subject.purchaseState.test {
+            expectNoEvents()
+
+            subject.launchSubscriptionUpdate(
+                activity = mock(),
+                newPlanId = "invalid_plan_id",
+                externalId = externalId,
+                newOfferId = null,
+            )
+
+            assertEquals(Canceled, awaitItem())
+        }
+
+        billingClientAdapter.verifyLaunchSubscriptionUpdateNotInvoked()
+    }
+
+    @Test
+    fun `when launchSubscriptionUpdate fails then emits canceled state`() = runTest {
+        // Set up purchase history so getCurrentPurchaseToken() returns a valid token
+        val mockPurchase: PurchaseHistoryRecord = mock {
+            whenever(it.products).thenReturn(listOf(BASIC_SUBSCRIPTION))
+            whenever(it.purchaseTime).thenReturn(1000L)
+            whenever(it.purchaseToken).thenReturn("old_purchase_token")
+        }
+        billingClientAdapter.subscriptionsPurchaseHistory = listOf(mockPurchase)
+
+        processLifecycleOwner.currentState = RESUMED
+        runCurrent() // Ensure purchase history is loaded
+
+        billingClientAdapter.launchBillingFlowResult = LaunchBillingFlowResult.Failure
+
+        val productDetails = billingClientAdapter.subscriptions.first()
+        val offerDetails = productDetails.subscriptionOfferDetails!!.first()
+        val externalId = "test_external_id"
+        val oldPurchaseToken = "old_purchase_token" // This is what getCurrentPurchaseToken() will return
+
+        subject.purchaseState.test {
+            expectNoEvents()
+
+            subject.launchSubscriptionUpdate(
+                activity = mock(),
+                newPlanId = MONTHLY_PLAN_US,
+                externalId = externalId,
+                newOfferId = null,
+            )
+
+            assertEquals(Canceled, awaitItem())
+        }
+
+        billingClientAdapter.verifyLaunchSubscriptionUpdateInvoked(
+            productDetails = productDetails,
+            offerToken = offerDetails.offerToken,
+            externalId = externalId,
+            oldPurchaseToken = oldPurchaseToken,
+            replacementMode = SubscriptionReplacementMode.DEFERRED, // default value
+        )
+    }
+
+    @Test
+    fun `when launchSubscriptionUpdate called with no purchase history then emits canceled state`() = runTest {
+        // No purchase history set up, so getCurrentPurchaseToken() will return null
+        billingClientAdapter.subscriptionsPurchaseHistory = emptyList()
+
+        processLifecycleOwner.currentState = RESUMED
+        runCurrent() // Ensure purchase history is loaded
+
+        val externalId = "test_external_id"
+
+        subject.purchaseState.test {
+            expectNoEvents()
+
+            subject.launchSubscriptionUpdate(
+                activity = mock(),
+                newPlanId = MONTHLY_PLAN_US,
+                externalId = externalId,
+                newOfferId = null,
+            )
+
+            assertEquals(Canceled, awaitItem())
+        }
+
+        billingClientAdapter.verifyLaunchSubscriptionUpdateNotInvoked()
+    }
 }
 
 class FakeBillingClientAdapter : BillingClientAdapter {
@@ -287,6 +431,18 @@ class FakeBillingClientAdapter : BillingClientAdapter {
         return launchBillingFlowResult
     }
 
+    override suspend fun launchSubscriptionUpdate(
+        activity: Activity,
+        productDetails: ProductDetails,
+        offerToken: String,
+        externalId: String,
+        oldPurchaseToken: String,
+        replacementMode: SubscriptionReplacementMode,
+    ): LaunchBillingFlowResult {
+        methodInvocations.add(LaunchSubscriptionUpdate(productDetails, offerToken, externalId, oldPurchaseToken, replacementMode))
+        return launchBillingFlowResult
+    }
+
     fun verifyConnectInvoked(times: Int = 1) {
         val invocations = methodInvocations.filterIsInstance<Connect>()
         assertEquals(times, invocations.count())
@@ -324,6 +480,30 @@ class FakeBillingClientAdapter : BillingClientAdapter {
         assertTrue(methodInvocations.filterIsInstance<LaunchBillingFlow>().isEmpty())
     }
 
+    fun verifyLaunchSubscriptionUpdateInvoked(
+        productDetails: ProductDetails,
+        offerToken: String,
+        externalId: String,
+        oldPurchaseToken: String,
+        replacementMode: SubscriptionReplacementMode,
+        times: Int = 1,
+    ) {
+        val invocations = methodInvocations
+            .filterIsInstance<LaunchSubscriptionUpdate>()
+            .filter { invocation ->
+                invocation.productDetails == productDetails &&
+                    invocation.offerToken == offerToken &&
+                    invocation.externalId == externalId &&
+                    invocation.oldPurchaseToken == oldPurchaseToken &&
+                    invocation.replacementMode == replacementMode
+            }
+        assertEquals(times, invocations.count())
+    }
+
+    fun verifyLaunchSubscriptionUpdateNotInvoked() {
+        assertTrue(methodInvocations.filterIsInstance<LaunchSubscriptionUpdate>().isEmpty())
+    }
+
     sealed class FakeMethodInvocation {
         data object Connect : FakeMethodInvocation()
         data class GetSubscriptions(val productIds: List<String>) : FakeMethodInvocation()
@@ -334,5 +514,13 @@ class FakeBillingClientAdapter : BillingClientAdapter {
             val offerToken: String,
             val externalId: String,
         ) : FakeMethodInvocation()
+
+        data class LaunchSubscriptionUpdate(
+            val productDetails: ProductDetails,
+            val offerToken: String,
+            val externalId: String,
+            val oldPurchaseToken: String,
+            val replacementMode: SubscriptionReplacementMode,
+        ) : FakeMethodInvocation()
     }
 }