SIGN IN SIGN UP

Improve Checkpoints APIs (#4108)

### Description

Iteration on the internal Checkpoints API surface
(`@InternalRevenueCatAPI`, so no public API signature changes):

- **`CheckpointPaywallOutcome.Purchased` carries the
`StoreTransaction`** for the purchased transaction (it was already in
scope at the only construction site and discarded).
- **New `CheckpointPaywallOutcome.WebCheckoutOpened`**: recorded when
the user taps a web checkout CTA and leaves to pay externally, delivered
when the paywall dismisses. A later purchase/restore/error in the same
presentation replaces it.
- **`NoAction(DISABLED)` removed**: it was not actionable by the
developer. Both disabled paths (missing configuration components and the
remote-config kill switch) now resolve to `CONFIGURATION_UNAVAILABLE`,
with distinct log messages.
- **`CheckpointResult.NoAction.Reason.value` is now internal**:
consumers compare against the constants; `Reason.toString()` returns the
bare value (e.g. `NO_MATCH`) for logging.
- **`CheckpointListener` methods take single parameter objects**
(`CheckpointHitContext` and `CheckpointCompletedContext`, both extending
an abstract `CheckpointContext` with the common `identifier` and
`customVariables`; the completed context adds `result`) so fields can be
added later without breaking implementors. The `CheckpointInfo`
indirection and `CheckpointResult.checkpoint` are removed.
- **Missing KDoc added** to `CheckpointPaywallOutcome` cases and
`Reason` constants.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Breaking changes to internal checkpoint listener and result types
affect all implementors; paywall outcome and no-action reason changes
alter app branching for gates and analytics.
> 
> **Overview**
> Refines the internal **Checkpoints** API (`@InternalRevenueCatAPI`):
listener callbacks, result shapes, paywall outcomes, and how “nothing
happened” is reported.
> 
> **`CheckpointListener`** now receives **`CheckpointHitContext`** and
**`CheckpointCompletedContext`** (shared **`CheckpointContext`** with
`identifier` and `customVariables`; completed adds `result`) instead of
**`CheckpointInfo`** plus a separate result. **`CheckpointResult`** no
longer embeds checkpoint metadata—callers use the listener context or
their own checkpoint id.
> 
> **Paywall outcomes:** **`CheckpointPaywallOutcome.Purchased`** now
includes **`StoreTransaction`**. New **`WebCheckoutOpened`** is recorded
when the user leaves for external web checkout
(`PaywallListener.onWebCheckoutOpened`); a later purchase/restore/error
in the same presentation can replace it.
> 
> **No-action semantics:** **`DISABLED`** is removed from resolution and
public **`NoAction.Reason`**; missing components and remote kill-switch
paths return **`CONFIGURATION_UNAVAILABLE`** with clearer messages.
**`Reason.value`** is internal; logging uses **`toString()`** (e.g.
`NO_MATCH`).
> 
> Examples, api-tester, and tests are updated for the new signatures and
**`WebCheckoutOpened`** handling.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
4124f834369a6ed9217ec5f13069dbee10d8ccab. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
T
Toni Rico committed
0edf33e87121b5a6238f8d19685290f2e000a5a8
Parent: add9676
Committed by GitHub <noreply@github.com> on 8/27/2026, 10:17:14 AM