Add custom store products, new purchase controller method

[ianrumac]

Changes in this pull request

Adds custom store products — products configured on a custom store in the Superwall dashboard (e.g. Stripe or your own payment backend) that can be attached to paywalls and purchased through the developer's PurchaseController, bypassing Google Play Billing entirely. Android port of Superwall-iOS #454.

Custom product pipeline

• New model types: Store.CUSTOM, CustomStoreProduct, ProductItem.StoreProductType.Custom, and CrossplatformProduct.StoreProduct.Custom, handled across all serialization paths.
• API contract: the backend resolves custom store products to store == "OTHER" so that old SDKs (which predate CUSTOM) ignore them. Deserializers therefore try the custom product shape first for OTHER products and fall back to Other if the fields don't match.
• Store now decodes through a custom serializer that maps any unknown store name to OTHER instead of throwing, so future store types can't break config/paywall/entitlement parsing regardless of the decoding Json configuration.
• Paywall load pre-fetches custom products from the /products endpoint (fetchAndCacheCustomProducts) and caches them as ApiStoreProduct-backed StoreProducts, so prices/periods/trials template into the paywall like any other product. A /products failure for declared custom products is surfaced as a product-load failure instead of presenting a broken paywall.
• StoreProduct.isCustomProduct is inferred from the backing product (ApiStoreProduct with platform == custom) rather than stored as a flag.

Unified purchase API

• New single PurchaseController.purchase(activity, product: StoreProduct, basePlanId, offerId) method handles both Google Play and custom products — the old signature with ProductDetails swapped for the StoreProduct wrapper. Implementers branch on product.isCustomProduct to route custom products through their own payment flow, and must grant entitlements themselves via setSubscriptionStatus(...) (the SDK does not grant entitlements for custom products, matching iOS).
• The old purchase(activity, productDetails, basePlanId, offerId) is deprecated but fully backward compatible: the new method's default implementation bridges Play products to it, so existing controllers work unchanged and only see a deprecation warning. Custom products through an unmigrated controller fail loudly with a message saying exactly what to override.
• PurchaseControllerJava is untouched; Play purchases bridge to it internally, custom products fail with a clear error there.

Transaction flow

• TransactionManager.handleCustomProductPurchase short-circuits Google Play Billing for custom products: pre-generates a UUID transaction id (exposed as StoreProduct.customTransactionId), delegates to the purchase controller, and builds a synthetic StoreTransaction for analytics — transaction_start/transaction_complete and subscriptionStart/freeTrialStart fire as usual.
• Free-trial eligibility for custom products is derived from the customer's entitlement history (mirroring web products), so repeat purchasers don't emit spurious freeTrialStart events.
• Custom products require a fully external PurchaseController (same contract as iOS). An earlier hybrid CustomProductPurchaseController was removed: it classified as an internal controller, so the automatic Play sync would recompute subscription status from Play purchases alone and wipe dev-granted custom entitlements.

Rename

• TestStoreProduct → ApiStoreProduct (moved to store/abstractions/product), now shared between test mode and custom products.

Checklist

• All unit tests pass.
• All UI tests pass.
• Demo project builds and runs.
• I added/updated tests or detailed why my change isn't tested.
• I added an entry to the CHANGELOG.md for any breaking changes, enhancements, or bug fixes.
• I have run ktlint in the main directory and fixed any issues.
• I have updated the SDK documentation as well as the online docs.
• I have reviewed the contributing guide

Greptile Summary

This PR introduces support for custom store products (products sourced from the Superwall API rather than Google Play Billing), adds a new PurchaseController.purchase(customProduct: StoreProduct) interface method for routing these purchases through an external payment system (e.g. Stripe), and renames TestStoreProduct → ApiStoreProduct to share the implementation between test mode and custom products.

• Custom product pipeline: Adds Store.CUSTOM / CustomStoreProduct / ProductItem.StoreProductType.Custom model types, a CrossplatformProduct.StoreProduct.Custom variant with serializer, free-trial eligibility via the existing isWebTrialAvailable path, and a fetchAndCacheCustomProducts pre-fetch step in PaywallRequestManager.
• Transaction flow: TransactionManager.handleCustomProductPurchase short-circuits Google Play Billing for CUSTOM products, delegates to the external PurchaseController, and builds a synthetic StoreTransaction for analytics using a pre-generated UUID.
• Rename: TestStoreProduct → ApiStoreProduct (moved to store/abstractions/product); call sites in TestMode updated; tests renamed accordingly.

Confidence Score: 3/5

Merging as-is will silently break custom-product purchases for any developer using PurchaseControllerJava, and introduces a data-race on a cached StoreProduct field that affects analytics correctness under concurrent access.

Two independent defects affect the core custom-product purchase path: Java-based PurchaseController implementations will always receive a Failed result despite passing the external-controller guard, and the mutable customTransactionId field written on a shared cached instance can be overwritten by a concurrent purchase, corrupting analytics identifiers.

InternalPurchaseController.kt (Java controller dispatch gap) and StoreProduct.kt + TransactionManager.kt (shared mutable customTransactionId written on a cached instance).

Important Files Changed

Filename	Overview
superwall/src/main/java/com/superwall/sdk/store/InternalPurchaseController.kt	Adds custom-product purchase dispatch, but only routes to kotlinPurchaseController — javaPurchaseController is silently ignored, causing purchases to fail for Java-based integrations.
superwall/src/main/java/com/superwall/sdk/store/abstractions/product/StoreProduct.kt	Adds isCustomProduct flag and mutable customTransactionId var; the mutable field on a cached/shared instance introduces a potential data race under concurrent purchases.
superwall/src/main/java/com/superwall/sdk/store/transactions/TransactionManager.kt	New handleCustomProductPurchase covers the full purchase lifecycle for CUSTOM store products; contains an unreachable UUID fallback and inherits the shared-state mutation concern from StoreProduct.
superwall/src/main/java/com/superwall/sdk/paywall/request/PaywallRequestManager.kt	Adds fetchAndCacheCustomProducts prefetch before Play product loading; errors from the /products endpoint are silently swallowed, which can leave the paywall with no product data.
superwall/src/main/java/com/superwall/sdk/delegate/subscription_controller/PurchaseController.kt	Adds default purchase(customProduct: StoreProduct) method with a clear failure message; clean and well-documented extension to the interface.
superwall/src/main/java/com/superwall/sdk/models/product/ProductItem.kt	Adds CUSTOM Store enum value and CustomStoreProduct / StoreProductType.Custom types; consistently handled in all serialization/deserialization branches.
superwall/src/main/java/com/superwall/sdk/store/abstractions/product/ApiStoreProduct.kt	Renamed from TestStoreProduct to ApiStoreProduct; no functional changes, rename correctly propagated to all call sites.
superwall/src/main/java/com/superwall/sdk/store/abstractions/transactions/StoreTransaction.kt	New secondary constructor for custom (non-Play) transactions; reuses GoogleBillingPurchaseTransaction with empty/null billing fields, which is a reasonable shim.

Sequence Diagram

sequenceDiagram
    participant PRM as PaywallRequestManager
    participant NET as Network (/products)
    participant SM as StoreManager (cache)
    participant TM as TransactionManager
    participant PC as PurchaseController (external)
    participant FA as StoreTransactionFactory

    PRM->>PRM: addProducts(paywall)
    PRM->>PRM: fetchAndCacheCustomProducts(paywall)
    PRM->>NET: getSuperwallProducts()
    NET-->>PRM: List SuperwallProduct
    PRM->>SM: cacheProduct(id, StoreProduct.custom(ApiStoreProduct))

    PRM->>SM: getProducts(paywall, request)
    SM-->>PRM: paywall with resolved products

    Note over TM: User taps purchase on CUSTOM product
    TM->>TM: handleCustomProductPurchase(product, source, dismiss)
    TM->>TM: "product.customTransactionId = UUID"
    TM->>PC: "purchase(customProduct = product)"
    PC-->>TM: PurchaseResult.Purchased

    TM->>FA: makeStoreTransaction(customTransactionId, productId, date)
    FA-->>TM: StoreTransaction (no Play receipt)
    TM->>TM: trackTransactionDidSucceed(transaction, product, ...)

Loading

Prompt To Fix All With AI

Fix the following 4 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 4
superwall/src/main/java/com/superwall/sdk/store/InternalPurchaseController.kt:65-73
**Java controller silently fails custom-product purchases**

`InternalPurchaseController.purchase(customProduct)` only delegates to `kotlinPurchaseController`, returning `Failed` when it is null — but `javaPurchaseController` could still be non-null. Because `hasExternalPurchaseController` is `true` for Java controllers, `handleCustomProductPurchase` passes its guard (`!factory.makeHasExternalPurchaseController()`) and calls this method, which then returns `PurchaseResult.Failed("No PurchaseController configured…")`. Any developer who configured a `PurchaseControllerJava` and added CUSTOM products will see purchases silently fail with a misleading error, even though they have a valid external controller registered.

### Issue 2 of 4
superwall/src/main/java/com/superwall/sdk/store/abstractions/product/StoreProduct.kt:92
**Shared mutable state race on cached `StoreProduct`**

`customTransactionId` is a `var` on a `StoreProduct` instance that is stored in the shared `storeManager` cache (set in `fetchAndCacheCustomProducts` via `storeManager.cacheProduct`). `TransactionManager.handleCustomProductPurchase` then mutates this field (`product.customTransactionId = UUID.randomUUID().toString()`) on the same shared instance. If two concurrent purchase flows request the same custom product, they can both race to write this field, causing one flow to read the other's transaction ID when building analytics events. The UUID should be generated as a local `val` inside `handleCustomProductPurchase` and passed directly to `makeStoreTransaction`, rather than stored on the cached product.

### Issue 3 of 4
superwall/src/main/java/com/superwall/sdk/store/transactions/TransactionManager.kt:468-488
The `?: java.util.UUID.randomUUID().toString()` fallback can never be reached: `customTransactionId` was just assigned unconditionally on the line above, so it is always non-null at this point. The dead fallback adds noise and could mask future refactors that break the invariant. Generate and hold the UUID in a local `val` instead.

```suggestion
        val customTxnId = java.util.UUID.randomUUID().toString()
        product.customTransactionId = customTxnId

        prepareToPurchase(product, purchaseSource)

        val result = storeManager.purchaseController.purchase(customProduct = product)

        // If we only have an external PurchaseController, the dev's flow handles the
        // rest of the transaction lifecycle (mirrors the existing ExternalPurchase
        // early return below for Play products).
        if (purchaseSource is PurchaseSource.ExternalPurchase &&
            factory.makeHasExternalPurchaseController() &&
            !factory.makeHasInternalPurchaseController()
        ) {
            if (result is PurchaseResult.Purchased) {
                // Still build + track a transaction so analytics include the custom txn id.
                val transaction =
                    factory.makeStoreTransaction(
                        customTransactionId = customTxnId,
                        productIdentifier = product.fullIdentifier,
                        purchaseDate = java.util.Date(),
                    )
```

### Issue 4 of 4
superwall/src/main/java/com/superwall/sdk/paywall/request/PaywallRequestManager.kt:353-361
**Silent failure leaves the paywall in an unresolvable state**

When `network.getSuperwallProducts()` fails, the error is logged but swallowed, and execution continues into `getProducts`. If none of the custom product IDs were successfully cached, the downstream product-loading step will have no data to work with and the paywall will likely show broken product cards or fail to render prices — with no signal to the caller that the pre-fetch step failed. Consider propagating the error so `addProducts` can handle it the same way it handles `getProducts` failures (the surrounding `try/catch`), or at minimum returning a sentinel that prevents the paywall from being presented with empty product data.

_{Reviews (1): Last reviewed commit: "Add custom store products, new purchase ..." | Re-trigger Greptile}

Greptile also left 4 inline comments on this PR.