Add Workflows network layer

AGENTS.md

@@ -113,6 +113,10 @@ Variant names combine both dimensions, e.g. `defaultsBc8Debug`, `customEntitleme
 - **`@ExperimentalPreviewRevenueCatPurchasesAPI`** - Public APIs for developers that may change before being made stable
 - **`@ExperimentalPreviewRevenueCatUIPurchasesAPI`** - Same as above but for the `:ui:revenuecatui` module
 
+## Code Style
+
+- **Imports over inline fully-qualified references**: Always add an `import` statement at the top of the file rather than using a fully-qualified name inline (e.g., write `import foo.Bar` and use `Bar`, not `foo.Bar` inline in the code).
+
 ## Testing Framework
 
 ### Technologies Used

config/detekt/detekt-baseline.xml

@@ -164,6 +164,7 @@
     <ID>TooManyFunctions:HTTPClient.kt$HTTPClient</ID>
     <ID>TooManyFunctions:Purchases.kt$Purchases : LifecycleDelegate</ID>
     <ID>TooManyFunctions:SubscriberAttributesCache.kt$SubscriberAttributesCache</ID>
+    <ID>TooManyFunctions:CoroutinesExtensionsCommon.kt$com.revenuecat.purchases.CoroutinesExtensionsCommon.kt</ID>
     <ID>TooManyFunctions:coroutinesExtensions.kt$com.revenuecat.purchases.coroutinesExtensions.kt</ID>
     <ID>TooManyFunctions:listenerConversions.kt$com.revenuecat.purchases.listenerConversions.kt</ID>
     <ID>UnusedParameter:SampleWeatherData.kt$SampleWeatherData.Companion$environment: Environment</ID>

purchases/src/defaults/kotlin/com/revenuecat/purchases/Purchases.kt

@@ -15,6 +15,7 @@ import com.revenuecat.purchases.common.errorLog
 import com.revenuecat.purchases.common.events.FeatureEvent
 import com.revenuecat.purchases.common.infoLog
 import com.revenuecat.purchases.common.log
+import com.revenuecat.purchases.common.workflows.WorkflowFetchResult
 import com.revenuecat.purchases.customercenter.CustomerCenterListener
 import com.revenuecat.purchases.deeplinks.DeepLinkParser
 import com.revenuecat.purchases.interfaces.Callback
@@ -394,6 +395,16 @@ public class Purchases internal constructor(
         purchasesOrchestrator.getOfferings(listener)
     }
 
+    @InternalRevenueCatAPI
+    @JvmSynthetic
+    public fun getWorkflowWith(
+        workflowId: String,
+        onError: (PurchasesError) -> Unit,
+        onSuccess: (WorkflowFetchResult) -> Unit,
+    ) {
+        purchasesOrchestrator.getWorkflow(workflowId, onSuccess, onError)
+    }
+
     /**
      * Gets the StoreProduct(s) for the given list of product ids for all product types.
      * @param [productIds] List of productIds

purchases/src/main/kotlin/com/revenuecat/purchases/CoroutinesExtensionsCommon.kt

@@ -1,6 +1,7 @@
 package com.revenuecat.purchases
 
 import android.content.Context
+import com.revenuecat.purchases.common.workflows.WorkflowFetchResult
 import com.revenuecat.purchases.models.BillingFeature
 import com.revenuecat.purchases.models.StoreProduct
 import com.revenuecat.purchases.models.StoreTransaction
@@ -281,3 +282,28 @@ public suspend fun Purchases.Companion.awaitCanMakePayments(
         )
     }
 }
+
+/**
+ * Fetches a published workflow by identifier.
+ *
+ * Coroutine friendly version of [Purchases.getWorkflowWith].
+ *
+ * @param workflowId The identifier of the workflow to fetch.
+ * @throws [PurchasesException] with a [PurchasesError] if there's an error fetching the workflow.
+ * @return The [WorkflowFetchResult] for the given identifier.
+ */
+@OptIn(InternalRevenueCatAPI::class)
+@InternalRevenueCatAPI
+@JvmSynthetic
+@Throws(PurchasesException::class)
+public suspend fun Purchases.awaitGetWorkflow(
+    workflowId: String,
+): WorkflowFetchResult {
+    return suspendCoroutine { continuation ->
+        getWorkflowWith(
+            workflowId = workflowId,
+            onSuccess = continuation::resume,
+            onError = { continuation.resumeWithException(PurchasesException(it)) },
+        )
+    }
+}

purchases/src/main/kotlin/com/revenuecat/purchases/PurchasesFactory.kt

@@ -39,11 +39,15 @@ import com.revenuecat.purchases.common.offlineentitlements.PurchasedProductsFetc
 import com.revenuecat.purchases.common.verification.SignatureVerificationMode
 import com.revenuecat.purchases.common.verification.SigningManager
 import com.revenuecat.purchases.common.warnLog
+import com.revenuecat.purchases.common.workflows.FileCachedWorkflowCdnFetcher
+import com.revenuecat.purchases.common.workflows.WorkflowDetailResolver
+import com.revenuecat.purchases.common.workflows.WorkflowManager
 import com.revenuecat.purchases.identity.IdentityManager
 import com.revenuecat.purchases.paywalls.FontLoader
 import com.revenuecat.purchases.paywalls.OfferingFontPreDownloader
 import com.revenuecat.purchases.paywalls.PaywallPresentedCache
 import com.revenuecat.purchases.paywalls.events.PaywallStoredEvent
+import com.revenuecat.purchases.storage.DefaultFileRepository
 import com.revenuecat.purchases.strings.ConfigureStrings
 import com.revenuecat.purchases.strings.Emojis
 import com.revenuecat.purchases.subscriberattributes.SubscriberAttributesManager
@@ -198,6 +202,16 @@ internal class PurchasesFactory(
                 backendHelper,
             )
 
+            val workflowManager = WorkflowManager(
+                backend = backend,
+                workflowDetailResolver = WorkflowDetailResolver(
+                    workflowCdnFetcher = FileCachedWorkflowCdnFetcher(
+                        fileRepository = DefaultFileRepository(contextForStorage),
+                    ),
+                    signatureVerificationMode = signatureVerificationMode,
+                ),
+            )
+
             val purchasesStateProvider = PurchasesStateCache(PurchasesState())
 
             // Override used for integration tests.
@@ -415,6 +429,7 @@ internal class PurchasesFactory(
                 localeProvider = localeProvider,
                 virtualCurrencyManager = virtualCurrencyManager,
                 purchaseParamsValidator = purchaseParamsValidator,
+                workflowManager = workflowManager,
             )
 
             return Purchases(purchasesOrchestrator)

purchases/src/main/kotlin/com/revenuecat/purchases/PurchasesOrchestrator.kt

@@ -51,6 +51,8 @@ import com.revenuecat.purchases.common.sha1
 import com.revenuecat.purchases.common.subscriberattributes.SubscriberAttributeKey
 import com.revenuecat.purchases.common.verboseLog
 import com.revenuecat.purchases.common.warnLog
+import com.revenuecat.purchases.common.workflows.WorkflowFetchResult
+import com.revenuecat.purchases.common.workflows.WorkflowManager
 import com.revenuecat.purchases.customercenter.CustomerCenterListener
 import com.revenuecat.purchases.deeplinks.WebPurchaseRedemptionHelper
 import com.revenuecat.purchases.google.isSuccessful
@@ -152,6 +154,8 @@ internal class PurchasesOrchestrator(
         ),
     private val virtualCurrencyManager: VirtualCurrencyManager,
     private val purchaseParamsValidator: PurchaseParamsValidator,
+
+    private val workflowManager: WorkflowManager,
     val processLifecycleOwnerProvider: () -> LifecycleOwner = { ProcessLifecycleOwner.get() },
     private val blockstoreHelper: BlockstoreHelper = BlockstoreHelper(application, identityManager),
     private val backupManager: BackupManager = BackupManager(application),
@@ -559,6 +563,21 @@ internal class PurchasesOrchestrator(
         )
     }
 
+    @InternalRevenueCatAPI
+    fun getWorkflow(
+        workflowId: String,
+        onSuccess: (WorkflowFetchResult) -> Unit,
+        onError: (PurchasesError) -> Unit,
+    ) {
+        workflowManager.getWorkflow(
+            appUserID = identityManager.currentAppUserID,
+            workflowId = workflowId,
+            appInBackground = state.appInBackground,
+            onSuccess = onSuccess,
+            onError = onError,
+        )
+    }
+
     fun getProducts(
         productIds: List<String>,
         type: ProductType? = null,

purchases/src/main/kotlin/com/revenuecat/purchases/common/Backend.kt

@@ -22,6 +22,8 @@ import com.revenuecat.purchases.common.networking.WebBillingProductsResponse
 import com.revenuecat.purchases.common.networking.buildPostReceiptResponse
 import com.revenuecat.purchases.common.offlineentitlements.ProductEntitlementMapping
 import com.revenuecat.purchases.common.verification.SignatureVerificationMode
+import com.revenuecat.purchases.common.workflows.WorkflowDetailResponse
+import com.revenuecat.purchases.common.workflows.WorkflowJsonParser
 import com.revenuecat.purchases.customercenter.CustomerCenterConfigData
 import com.revenuecat.purchases.customercenter.CustomerCenterRoot
 import com.revenuecat.purchases.interfaces.RedeemWebPurchaseListener
@@ -96,6 +98,9 @@ internal typealias VirtualCurrenciesCallback = Pair<(VirtualCurrencies) -> Unit,
 
 internal typealias WebBillingProductsCallback = Pair<(WebBillingProductsResponse) -> Unit, (PurchasesError) -> Unit>
 
+@OptIn(InternalRevenueCatAPI::class)
+internal typealias WorkflowDetailCallback = Pair<(WorkflowDetailResponse) -> Unit, (PurchasesError) -> Unit>
+
 internal enum class PostReceiptErrorHandlingBehavior {
     SHOULD_BE_MARKED_SYNCED,
     SHOULD_USE_OFFLINE_ENTITLEMENTS_AND_NOT_CONSUME,
@@ -177,6 +182,10 @@ internal class Backend(
     @get:Synchronized @set:Synchronized
     @Volatile var webBillingProductsCallbacks = mutableMapOf<String, MutableList<WebBillingProductsCallback>>()
 
+    @get:Synchronized @set:Synchronized
+    @Volatile var workflowDetailCallbacks =
+        mutableMapOf<BackgroundAwareCallbackCacheKey, MutableList<WorkflowDetailCallback>>()
+
     fun close() {
         this.dispatcher.close()
     }
@@ -975,6 +984,68 @@ internal class Backend(
         }
     }
 
+    fun getWorkflow(
+        appUserID: String,
+        workflowId: String,
+        appInBackground: Boolean,
+        onSuccess: (WorkflowDetailResponse) -> Unit,
+        onError: (PurchasesError) -> Unit,
+    ) {
+        val endpoint = Endpoint.GetWorkflow(appUserID, workflowId)
+        val path = endpoint.getPath()
+        val cacheKey = BackgroundAwareCallbackCacheKey(listOf(path), appInBackground)
+        val call = object : Dispatcher.AsyncCall() {
+            override fun call(): HTTPResult {
+                return httpClient.performRequest(
+                    appConfig.baseURL,
+                    endpoint,
+                    body = null,
+                    postFieldsToSign = null,
+                    backendHelper.authenticationHeaders,
+                    fallbackBaseURLs = appConfig.fallbackBaseURLs,
+                )
+            }
+
+            override fun onError(error: PurchasesError) {
+                synchronized(this@Backend) {
+                    workflowDetailCallbacks.remove(cacheKey)
+                }?.forEach { (_, onErrorHandler) ->
+                    onErrorHandler(error)
+                }
+            }
+
+            override fun onCompletion(result: HTTPResult) {
+                synchronized(this@Backend) {
+                    workflowDetailCallbacks.remove(cacheKey)
+                }?.forEach { (onSuccessHandler, onErrorHandler) ->
+                    if (result.isSuccessful()) {
+                        try {
+                            onSuccessHandler(
+                                WorkflowJsonParser.parseWorkflowDetailResponse(result.payload),
+                            )
+                        } catch (e: SerializationException) {
+                            onErrorHandler(e.toPurchasesError().also { errorLog(it) })
+                        } catch (e: IllegalArgumentException) {
+                            onErrorHandler(e.toPurchasesError().also { errorLog(it) })
+                        }
+                    } else {
+                        onErrorHandler(result.toPurchasesError().also { errorLog(it) })
+                    }
+                }
+            }
+        }
+        synchronized(this@Backend) {
+            val delay = if (appInBackground) Delay.DEFAULT else Delay.NONE
+            workflowDetailCallbacks.addBackgroundAwareCallback(
+                call,
+                dispatcher,
+                cacheKey,
+                onSuccess to onError,
+                delay,
+            )
+        }
+    }
+
     fun getWebBillingProducts(
         appUserID: String,
         productIds: Set<String>,

purchases/src/main/kotlin/com/revenuecat/purchases/common/networking/Endpoint.kt

@@ -27,6 +27,14 @@ internal sealed class Endpoint(
             }
         }
     }
+
+    data class GetWorkflow(val userId: String, val workflowId: String) : Endpoint(
+        "/v1/subscribers/%s/workflows/%s",
+        "get_workflow",
+    ) {
+        override fun getPath(useFallback: Boolean) =
+            pathTemplate.format(Uri.encode(userId), Uri.encode(workflowId))
+    }
     object LogIn : Endpoint("/v1/subscribers/identify", "log_in") {
         override fun getPath(useFallback: Boolean) = pathTemplate
     }
@@ -102,6 +110,7 @@ internal sealed class Endpoint(
             LogIn,
             PostReceipt,
             is GetOfferings,
+            is GetWorkflow,
             GetProductEntitlementMapping,
             PostRedeemWebPurchase,
             is GetVirtualCurrencies,
@@ -130,6 +139,7 @@ internal sealed class Endpoint(
                 true
             is GetAmazonReceipt,
             is GetOfferings,
+            is GetWorkflow,
             is PostAttributes,
             PostDiagnostics,
             PostEvents,

purchases/src/main/kotlin/com/revenuecat/purchases/common/workflows/WorkflowCdnFetcher.kt

@@ -0,0 +1,35 @@
+@file:OptIn(InternalRevenueCatAPI::class)
+
+package com.revenuecat.purchases.common.workflows
+
+import com.revenuecat.purchases.InternalRevenueCatAPI
+import com.revenuecat.purchases.storage.FileRepository
+import kotlinx.coroutines.runBlocking
+import java.io.File
+import java.io.IOException
+import java.net.URL
+
+/**
+ * Fetches compiled workflow JSON from a CDN URL (inject for tests; use [FileCachedWorkflowCdnFetcher] in production).
+ */
+internal fun interface WorkflowCdnFetcher {
+    @Throws(IOException::class)
+    fun fetchCompiledWorkflowJson(cdnUrl: String): String
+}
+
+/**
+ * Uses [FileRepository] for disk caching.
+ */
+internal class FileCachedWorkflowCdnFetcher(
+    private val fileRepository: FileRepository,
+) : WorkflowCdnFetcher {
+
+    @Throws(IOException::class)
+    override fun fetchCompiledWorkflowJson(cdnUrl: String): String {
+        val url = URL(cdnUrl)
+        return runBlocking {
+            val uri = fileRepository.generateOrGetCachedFileURL(url)
+            File(uri).readText()
+        }
+    }
+}