Add Workflows network layer by vegaro · Pull Request #3300 · RevenueCat/purchases-android

vegaro · 2026-04-06T13:20:13Z

Motivation

This is the first milestone toward multipage paywalls on Android. The backend exposes two endpoints for workflows: one to list available workflows for a subscriber and one to fetch the full published workflow document. The detail endpoint uses an envelope pattern where the server decides whether to return the workflow payload inline or redirect to a CDN URL. This PR adds the full networking layer so the SDK can fetch and parse workflows end-to-end.

Description

Endpoints

Two new Endpoint subtypes: GetWorkflows (list) and GetWorkflow (detail). The list endpoint participates in signature verification (same as offerings); the detail endpoint does not.

Models

All workflow types live in WorkflowModels.kt: WorkflowSummary, WorkflowsListResponse, PublishedWorkflow (the full document with steps, screens, trigger actions), and WorkflowFetchResult which bundles the parsed workflow with any enrolled_variants from the response envelope.

WorkflowResponseAction is an enum (INLINE, USE_CDN) so the envelope action is never compared as a raw string.

Response envelope processing

WorkflowDetailHttpProcessor handles the detail endpoint's envelope outside of Backend:

inline: unwraps the data object as the workflow payload.
use_cdn: delegates to an injected WorkflowCdnFetcher to download the compiled JSON from the CDN URL.
Extracts enrolled_variants from the envelope for experiment tracking.

WorkflowDetailHttpProcessor is its own class Backend.call() thin (just network + delegate) and makes envelope logic independently testable.

CDN fetching

WorkflowCdnFetcher is a fun interface so tests can substitute a lambda. The production implementation, FileCachedWorkflowCdnFetcher, uses FileRepository for disk caching when available and falls back to a direct URL read otherwise. Injected into Backend via PurchasesFactory.

Note

Medium Risk
Adds new backend requests and response processing for workflow documents, including optional CDN download and disk caching, which introduces new network/file I/O paths and envelope parsing that could fail at runtime. Changes are additive but touch Backend request flow and endpoint signature-verification configuration.

Overview
Adds a new workflows network layer: Endpoint.GetWorkflows (list, participates in signature verification) and Endpoint.GetWorkflow (detail, no signature verification), with corresponding Backend.getWorkflows/getWorkflow methods and callback de-duping.

Introduces workflow parsing and envelope normalization: new serializable models (WorkflowsListResponse, PublishedWorkflow, etc.), WorkflowJsonParser, and WorkflowDetailHttpProcessor that unwraps inline payloads or fetches compiled JSON via CDN (use_cdn) while preserving enrolled_variants.

Wires production CDN fetching with disk caching by injecting FileCachedWorkflowCdnFetcher(DefaultFileRepository) from PurchasesFactory, and adds unit tests covering endpoint paths/flags, backend workflow fetching, and envelope/CDN handling.

^{Reviewed by Cursor Bugbot for commit 895becd. Bugbot is set up for automated code reviews on this repo. Configure here.}

- Add `getWorkflows` and `getWorkflow` endpoint paths - Add `WorkflowsListResponse` and `PublishedWorkflow` response models - Add `WorkflowDetailProcessor` to handle `inline`/`use_cdn` response actions - Add `WorkflowCdnFetcher` protocol and `DirectWorkflowCdnFetcher` implementation - Add `GetWorkflowsOperation` and `GetWorkflowOperation` cacheable network operations - Add `WorkflowsAPI` facade and wire into `Backend` - Add unit tests for all new components iOS equivalent of RevenueCat/purchases-android#3300 Made-with: Cursor

Made-with: Cursor

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 37aaf43. Configure here.}

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

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

- Throw JSONException instead of IllegalArgumentException for unknown workflow response actions so AsyncCall.run() catches it gracefully - Use imported InternalRevenueCatAPI in @file:OptIn instead of FQN Made-with: Cursor

facumenzella · 2026-04-07T13:24:25Z

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

+import com.revenuecat.purchases.InternalRevenueCatAPI
+import kotlinx.serialization.json.Json
+
+internal object WorkflowJsonParser {


This feels like an unnecessary abstraction to me. Or what am I missing? Can't we reuse an existing parser?

facumenzella · 2026-04-07T13:30:03Z

...ses/src/main/kotlin/com/revenuecat/purchases/common/workflows/WorkflowDetailHttpProcessor.kt

+        val keyIterator = keys()
+        while (keyIterator.hasNext()) {
+            val key = keyIterator.next()
+            map[key] = optString(key)


optString will convert anything to string? How does that work? Can we add tests for non-string keys?

facumenzella

Just a couple of questions. Looks good

tonidero

Not a lot of context and just some thoughts. But happy to iterate on this in future PRs since it's still not used

tonidero · 2026-04-07T14:27:38Z

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

    private val eventsDispatcher: Dispatcher,
    private val httpClient: HTTPClient,
    private val backendHelper: BackendHelper,
+    workflowCdnFetcher: WorkflowCdnFetcher = FileCachedWorkflowCdnFetcher(fileRepository = null),


Hmm why default here to a different one since we're creating the Backend instance in the PurchasesFactory with a value? If this is for tests, I wonder if we should just make this explicit there... Also, it would make fileRespository not nullable, which feels better?

tonidero · 2026-04-07T14:30:16Z

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

+@Serializable
+internal data class WorkflowsListResponse(
+    val workflows: List<WorkflowSummary> = emptyList(),
+    @SerialName("ui_config") val uiConfig: UiConfig,


Just curious... why is the uiConfig needed here if we also have it in the individual workflow's model?

tonidero · 2026-04-07T14:31:21Z

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

+    val screens: Map<String, WorkflowScreen>,
+    @SerialName("ui_config") val uiConfig: UiConfig,
+    @SerialName("content_max_width") val contentMaxWidth: Int? = null,
+    val metadata: JsonObject? = null,


Hmm I guess this could have nested data? Otherwise, we could make this a Map<String, Any> for ease of use.

tonidero · 2026-04-07T14:44:18Z

...ses/src/main/kotlin/com/revenuecat/purchases/common/workflows/WorkflowDetailHttpProcessor.kt

+            ?: throw JSONException("Unknown workflow response action: $rawAction")
+        val normalizedPayload = when (action) {
+            WorkflowResponseAction.INLINE -> root.getJSONObject("data").toString()
+            WorkflowResponseAction.USE_CDN -> workflowCdnFetcher.fetchCompiledWorkflowJson(root.getString("url"))


I wonder if we should just stick to plain Json serialization here, and avoid the custom parsing we are doing here. Then, do the fetching of the compiled workflow as a higher level later on top of the network call? Feels the network call and the logic are a bit mixed right now...

vegaro added the pr:fix A bug fix label Apr 6, 2026

vegaro changed the title ~~Add workflows network layer (multipage paywalls milestone 1)~~ Add Workflows network layer Apr 6, 2026

vegaro added pr:RevenueCatUI feat:PaywallV2 labels Apr 6, 2026

Add GetWorkflows and GetWorkflow

be06ed6

vegaro force-pushed the feat/multipage-paywalls-milestone-1-go8 branch from 6ebd871 to be06ed6 Compare April 6, 2026 13:25

vegaro mentioned this pull request Apr 6, 2026

Add workflows network layer for multipage paywalls RevenueCat/purchases-ios#6557

Open

Add typed WorkflowTrigger model to match backend response shape

37aaf43

Made-with: Cursor

vegaro marked this pull request as ready for review April 7, 2026 09:59

vegaro requested a review from a team as a code owner April 7, 2026 09:59

vegaro requested a review from facumenzella April 7, 2026 09:59

cursor bot reviewed Apr 7, 2026

View reviewed changes

purchases/src/main/kotlin/com/revenuecat/purchases/common/Backend.kt Show resolved Hide resolved

purchases/src/main/kotlin/com/revenuecat/purchases/common/workflows/WorkflowCdnFetcher.kt Outdated Show resolved Hide resolved

Fix unknown action crash and use consistent import style

895becd

- Throw JSONException instead of IllegalArgumentException for unknown workflow response actions so AsyncCall.run() catches it gracefully - Use imported InternalRevenueCatAPI in @file:OptIn instead of FQN Made-with: Cursor

facumenzella reviewed Apr 7, 2026

View reviewed changes

facumenzella approved these changes Apr 7, 2026

View reviewed changes

tonidero reviewed Apr 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Workflows network layer#3300

Add Workflows network layer#3300
vegaro wants to merge 3 commits intomainfrom
feat/multipage-paywalls-milestone-1-go8

vegaro commented Apr 6, 2026 •

edited by cursor bot

Loading

Uh oh!

cursor bot left a comment

Uh oh!

Uh oh!

Uh oh!

facumenzella Apr 7, 2026

Uh oh!

facumenzella Apr 7, 2026

Uh oh!

facumenzella left a comment

Uh oh!

tonidero left a comment

Uh oh!

tonidero Apr 7, 2026

Uh oh!

tonidero Apr 7, 2026

Uh oh!

tonidero Apr 7, 2026

Uh oh!

tonidero Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

vegaro commented Apr 6, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Description

Endpoints

Models

Response envelope processing

CDN fetching

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

facumenzella Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

facumenzella Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

facumenzella left a comment

Choose a reason for hiding this comment

Uh oh!

tonidero left a comment

Choose a reason for hiding this comment

Uh oh!

tonidero Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

tonidero Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

tonidero Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

tonidero Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vegaro commented Apr 6, 2026 •

edited by cursor bot

Loading