Gate-focused checkpoint() API

[tonidero]

Description

New Checkpoints API based on gating behind a closure when the user goes through the checkpoint flow, if any:

Purchases.sharedInstance.checkpoint("onboarding_completed", CheckpointParams {}) { result ->
    // result == null: nothing was presented (no rule matched, nothing could be served, or presenting failed)
    // result != null: the user passed the presented flow; result.obtainedEntitlements is what they obtained
    navigateToHome()
}

When the callback fires

CheckpointPassedCallback.onCheckpointPassed is invoked at most once, on the main thread, when the user passes the checkpoint:

• with null when nothing was presented, whatever the reason.
• with a FlowResult when the presented flow ended with a purchase or restore, or through a close action.

It is not invoked when the user backs out of the presented flow (system back, or a navigate_back action on a workflow's first step).

Only one checkpoint flow is presented at a time. A checkpoint that resolves to a flow while another flow is already on screen is ignored and its callback is never invoked: the call that presented the flow is the one that reports. A checkpoint that resolves to nothing still passes null meanwhile.

---

Note

High Risk
Breaking internal checkpoint API and paywall presentation lifecycle changes affect monetization gating, concurrent checkpoint behavior, and entitlement reporting for integrators on the new surface.

Overview
Replaces the suspend awaitCheckpoint / CheckpointResult surface with a callback-based Purchases.checkpoint() API aimed at gating: CheckpointPassedCallback receives FlowResult? (null when nothing was presented; otherwise obtainedEntitlements for what the user gained). The call does not throw—failures and no-match cases are logged and surface as null. The callback is skipped when the user backs out of the flow or when a second checkpoint would present while another flow is already on screen.

Public CheckpointResult and CheckpointPaywallOutcome are removed; presentation outcomes move to internal CheckpointFlowOutcome. Offering resolutions now present a fallback offering paywall instead of returning data for app-owned UI. CheckpointWorkflowPresenter defers tearing down the window until after the app is notified via finishPresentation.

Core seam renames: resolveCheckpoint → internalResolveCp, checkpointManagerSlot → internalCpManagerSlot. LocalRulesEvaluator logging is tightened. API testers, checkpointtester / paywall-tester samples, and unit tests are updated for the new contract.

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

[RevenueCat-Danger-Bot]

	1 Message
📖	This PR changes 883 lines of production Kotlin/Java (limit 300); skipped via skip-pr-lines-changed-check label.

Generated by 🚫 Danger

[cursor]

Stale Bugbot comment from a previous run.

[rickvdl]

I actually had it fetch the customer info beforehand 🤔 but now that I think about it this also makes sense and is a bit less complex.

[tonidero]

Right, I try to minimize the requests when hitting a checkpoint, so only getting it from cache.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ 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 f8c0a57. Configure here.}

[cursor]

Back-out leaves screens stuck

Medium Severity

The new checkpoint() callback is intentionally skipped when the user backs out, but these screens set running/waitingFor before the call and only clear it in that callback. System back (or navigate_back on the first step) therefore leaves the UI disabled with no way to retry, restart, or continue. Onboarding still claims a flow outcome must not strand the user mid-flow; hard paywall still claims dismissal leaves the content locked and lets the user try again. The same latch exists on the entitlement gate, custom, soft paywall, and use-case screens.

Additional Locations (2)

• examples/checkpointtester/src/main/java/com/revenuecat/checkpointtester/ui/screens/hardpaywall/HardPaywallViewModel.kt#L34-L52
• examples/paywall-tester/src/main/java/com/revenuecat/paywallstester/ui/screens/checkpoints/CheckpointsViewModel.kt#L57-L68

 

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

[tonidero]

This is actually fixed in the follow-up PR: #4155

[rickvdl]

I think this looks great! We're fully aligned now as far as I could see 💪 Just one small difference