@purchasely/cordova-plugin-purchasely 6.0.1 → 6.1.1

package/Package.swift

@@ -56,7 +56,7 @@ let package = Package(
         // documents another. That makes the linked SDK depend on install time and lets
         // the two integration paths drift apart. Bump this with the podspec, in the
         // same commit, and VERSIONS.md with it.
-        .package(url: "https://github.com/Purchasely/Purchasely-iOS.git", exact: "6.0.1")
+        .package(url: "https://github.com/Purchasely/Purchasely-iOS.git", exact: "6.1.2")
     ],
     targets: [
         .target(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purchasely/cordova-plugin-purchasely",
-  "version": "6.0.1",
+  "version": "6.1.1",
   "description": "Purchasely is a solution to ease the integration and boost your In-App Purchases & Subscriptions on the App Store, Google Play Store, Amazon Appstore and Huawei App Gallery.",
   "cordova": {
     "id": "@purchasely/cordova-plugin-purchasely",
@@ -65,6 +65,11 @@
   },
   "homepage": "https://github.com/Purchasely/Purchasely-Cordova#readme",
   "overrides": {
-    "js-yaml@3": "^3.15.1"
+    "js-yaml@3": "^3.15.2",
+    "browserslist": "^4.28.7"
+  },
+  "resolutions": {
+    "js-yaml": "^3.15.2",
+    "browserslist": "^4.28.7"
   }
 }

package/plugin.xml

@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='utf-8'?>
-<plugin id="@purchasely/cordova-plugin-purchasely" version="6.0.1" xmlns="http://apache.org/cordova/ns/plugins/1.0" xmlns:android="http://schemas.android.com/apk/res/android">
+<plugin id="@purchasely/cordova-plugin-purchasely" version="6.1.1" xmlns="http://apache.org/cordova/ns/plugins/1.0" xmlns:android="http://schemas.android.com/apk/res/android">
     <name>Purchasely</name>
     <js-module name="Purchasely" src="www/Purchasely.js">
         <clobbers target="Purchasely" />
@@ -38,7 +38,7 @@
                 <source url="https://github.com/CocoaPods/Specs.git"/>
             </config>
             <pods use-frameworks="true">
-                <pod name="Purchasely" spec="6.0.1" nospm="true"/>
+                <pod name="Purchasely" spec="6.1.2" nospm="true"/>
             </pods>
         </podspec>
     </platform>
@@ -53,7 +53,7 @@
             <preference name="GradlePluginKotlinCodeStyle" value="official" />
         </config-file>
         <framework src="src/android/build-extras.gradle" custom="true" type="gradleReference" />
-        <framework src="io.purchasely:core:6.0.2" />
+        <framework src="io.purchasely:core:6.1.1" />
         <source-file src="src/android/PurchaselyPlugin.kt" target-dir="java/cordova/plugin/purchasely" />
     </platform>
 </plugin>

package/src/android/PurchaselyPlugin.kt

@@ -16,6 +16,7 @@ import io.purchasely.ext.PLYEvent
 import io.purchasely.ext.PLYInterceptResult
 import io.purchasely.ext.PLYInterceptorInfo
 import io.purchasely.ext.PLYRunningMode
+import io.purchasely.ext.PLYWebRedemptionListener
 import io.purchasely.ext.PurchaseListener
 import io.purchasely.ext.Purchasely
 import io.purchasely.ext.State
@@ -33,6 +34,7 @@ import io.purchasely.models.PLYPlan
 import io.purchasely.models.PLYPresentationPlan
 import io.purchasely.models.PLYProduct
 import io.purchasely.models.PLYSubscriptionData
+import io.purchasely.models.PLYWebRedemptionResult
 import io.purchasely.views.presentation.PLYThemeMode
 import io.purchasely.views.presentation.models.PLYDimensionType
 import io.purchasely.views.presentation.models.PLYTransition
@@ -53,6 +55,9 @@ import java.util.Calendar
 import java.util.Date
 import java.util.Locale
 import java.util.TimeZone
+import java.util.UUID
+import java.net.URI
+import java.net.URISyntaxException
 import java.util.concurrent.ConcurrentHashMap
 
 /**
@@ -87,9 +92,43 @@ class PurchaselyPlugin : CordovaPlugin(), CoroutineScope {
 
     override fun onDestroy() {
         job.cancel()
+        clearCallbackContexts()
         super.onDestroy()
     }
 
+    /**
+     * Cordova calls this when the WebView navigates, which invalidates every callbackId the
+     * previous page handed us.
+     */
+    override fun onReset() {
+        clearCallbackContexts()
+        super.onReset()
+    }
+
+    /**
+     * Drop every stored [CallbackContext].
+     *
+     * These live on the companion object, so they are STATIC: they outlive both the plugin
+     * instance and the WebView. Neither teardown path cleared them before, which left two
+     * problems. Each stale context holds a reference to the dead CordovaWebView, so the
+     * whole view tree leaked. And the native SDK listeners registered at `start()` outlive
+     * the activity, so an event arriving after a teardown was sent into a dead bridge
+     * instead of being dropped.
+     *
+     * The redemption case is the one that matters most. `webRedemptionListener` is set on
+     * the builder, and `Purchasely.Builder.build()` REASSIGNS the SDK's static listener on
+     * every call, so a page reload that starts again replaces the lambda rather than
+     * stacking one. Until it does, the lambda from the previous plugin instance is still
+     * live and reads `webRedemptionCallback` lazily, at fire time. Clearing here is what
+     * makes that window a clean no-op rather than a send into a dead callbackId.
+     */
+    private fun clearCallbackContexts() {
+        defaultCallback = null
+        eventsCallback = null
+        attributesCallback = null
+        webRedemptionCallback = null
+    }
+
     override fun execute(
         action: String,
         args: JSONArray,
@@ -103,6 +142,8 @@ class PurchaselyPlugin : CordovaPlugin(), CoroutineScope {
                 "addUserAttributeListener" -> addUserAttributesListener(callbackContext)
                 "removeUserAttributeListener" -> removeUserAttributesListener()
                 "removeEventsListener" -> removeEventsListener()
+                "addWebRedemptionListener" -> addWebRedemptionListener(callbackContext)
+                "removeWebRedemptionListener" -> removeWebRedemptionListener(callbackContext)
                 "getAnonymousUserId" -> getAnonymousUserId(callbackContext)
                 "isAnonymous" -> isAnonymous(callbackContext)
                 "userLogin" -> userLogin(getStringFromJson(args.getString(0)), callbackContext)
@@ -281,6 +322,37 @@ class PurchaselyPlugin : CordovaPlugin(), CoroutineScope {
         val allowCampaigns = if (options.has("allowCampaigns")) options.optBoolean("allowCampaigns") else null
         val deeplink = getStringFromJson(options.optString("deeplink"))
         val sdkVersion = getStringFromJson(options.optString("sdkVersion"))
+        // Both bridges report a refused-and-skipped option at the SAME severity, and
+        // deliberately with a plain log line on both: Log.e here, NSLog on iOS. Neither
+        // renders UI. Do not reach for anything that puts an overlay or a dialog in front
+        // of the host app: start() continues, the option was simply ignored, and a
+        // third-party SDK has no business interrupting someone else's app over an option
+        // it chose to skip.
+        // v6.1.0: three states, and they are not interchangeable. See [resolveProxyOption].
+        val proxyOption = resolveProxyOption(options)
+        if (proxyOption is PLYProxyOption.Invalid) {
+            Log.e("Purchasely", "`proxy` must be an https base URL, for example " +
+                "\"https://svc.purchasely.io\", or null to clear the proxy. Received a " +
+                "${proxyOption.rawValue?.length ?: 0}-character value. The proxy is not applied.")
+        }
+        val appHandlesRedemptionAlert = options.optBoolean("appHandlesRedemptionAlert", false)
+
+        // v6.1.0: JS has no UUID type, so the id crosses the bridge as a string and is parsed
+        // here. The native builder takes a UUID?, which is where the guarantee used to live; a
+        // string-typed bridge is the only place left to catch a bad value. Refuse it loudly and
+        // skip the option. The SDK still starts, matching how native treats an unusable proxy url.
+        val anonymousUserIdString = getStringFromJson(options.optString("anonymousUserId"))
+        val anonymousUserId = parseCanonicalUuid(anonymousUserIdString)
+        if (anonymousUserIdString != null && anonymousUserId == null) {
+            // The value is NOT logged. A mis-wired field lands here just as easily as a
+            // typo -- an email, an appUserId -- and logcat is collected during support. The
+            // length still distinguishes a truncated id from a wrong field. Matches iOS.
+            Log.e("Purchasely", "`anonymousUserId` must be a canonical UUID string, for example " +
+                "\"3f2504e0-4f89-11d3-9a0c-0305e82c3301\". Received a " +
+                "${anonymousUserIdString.length}-character value. " +
+                "The anonymous user id is not applied.")
+        }
+        val anonymousUserIdOverride = options.optBoolean("anonymousUserIdOverride", false)
 
         Purchasely.Builder(cordova.context)
             .apiKey(apiKey)
@@ -293,6 +365,22 @@ class PurchaselyPlugin : CordovaPlugin(), CoroutineScope {
                 allowCampaigns?.let { this.allowCampaigns(it) }
                 // Cold-start deeplink: replayed automatically once started.
                 deeplink?.let { this.handleDeeplink(Uri.parse(it)) }
+                // The three 6.1.0 options are applied through a seam so a unit test can
+                // verify WHICH builder call each resolver state produces. Without it,
+                // swapping the Clear and Set branches passed every test in the repository.
+                applyStartOptions(
+                    builder = this,
+                    proxyOption = proxyOption,
+                    anonymousUserId = anonymousUserId,
+                    anonymousUserIdOverride = anonymousUserIdOverride,
+                    appHandlesRedemptionAlert = appHandlesRedemptionAlert,
+                    // Registered unconditionally: the native SDK has no runtime setter on
+                    // purpose, because a redemption can settle during start(). It sends
+                    // nothing when addWebRedemptionListener recorded no callback.
+                    redemptionListener = PLYWebRedemptionListener { result ->
+                        deliverRedemption(result)
+                    },
+                )
             }
             .build()
 
@@ -392,6 +480,65 @@ class PurchaselyPlugin : CordovaPlugin(), CoroutineScope {
         Purchasely.eventListener = null
     }
 
+    /**
+     * v6.1.0. Record the callback the redemption outcome is routed to.
+     *
+     * The native [PLYWebRedemptionListener] is registered on the builder chain in [start] (the
+     * SDK has no runtime setter, because a redemption can settle during `start()`), so this
+     * action only records where to send the outcome. JS must call it BEFORE `start()`.
+     */
+    private fun addWebRedemptionListener(callbackContext: CallbackContext) {
+        // Close the previous stream before replacing it, or its JS closure stays in
+        // cordova.callbacks forever. See [releaseCallbackStream].
+        releaseCallbackStream(webRedemptionCallback)
+        webRedemptionCallback = callbackContext
+    }
+
+    private fun removeWebRedemptionListener(callbackContext: CallbackContext) {
+        // The native listener stays registered; clearing the callback makes it a no-op.
+        releaseCallbackStream(webRedemptionCallback)
+        webRedemptionCallback = null
+        // Acknowledge the remove itself, so ITS callbackId is freed too. A void action that
+        // never answers leaks its own entry exactly like the listener's.
+        callbackContext.success()
+    }
+
+    /**
+     * Send one settled redemption to the JS listener.
+     *
+     * Everything the SDK hands over crosses here, so a test can fire a fabricated
+     * [PLYWebRedemptionResult] through the real delivery path and assert exactly what
+     * Cordova receives: the JSON body, and `keepCallback = true` so the stream stays open
+     * for the next redemption.
+     *
+     * A no-op when no listener is registered, which is why registering the SDK listener
+     * unconditionally at `start()` is behaviour-neutral.
+     */
+    internal fun deliverRedemption(result: PLYWebRedemptionResult) {
+        val callback = webRedemptionCallback ?: return
+        val pluginResult = PluginResult(
+            PluginResult.Status.OK,
+            webRedemptionResultToJson(result, Companion::transformSubscriptionToMap)
+        )
+        pluginResult.keepCallback = true
+        callback.sendPluginResult(pluginResult)
+    }
+
+    /**
+     * End a kept-alive Cordova callback stream, freeing its JavaScript closure.
+     *
+     * Every result the bridge sends a listener carries `keepCallback = true`, so dropping
+     * the native reference alone leaks the JS closure until the WebView reloads. NO_RESULT
+     * with `keepCallback = false` is cordova.js's own documented way out: it "is used to
+     * remove a callback from the list without calling the callbacks".
+     */
+    private fun releaseCallbackStream(callback: CallbackContext?) {
+        if (callback == null) return
+        val terminal = PluginResult(PluginResult.Status.NO_RESULT)
+        terminal.keepCallback = false
+        callback.sendPluginResult(terminal)
+    }
+
     private fun getAnonymousUserId(callbackContext: CallbackContext) {
         callbackContext.success(Purchasely.anonymousUserId)
     }
@@ -808,45 +955,10 @@ class PurchaselyPlugin : CordovaPlugin(), CoroutineScope {
         }
     }
 
-    // Hardening for the upcoming rc.4 native release: PLYPlan.toMap()'s raw "type" entry is
-    // moving from an ordinal (Int) to the DistributionType name (String). transformPlanToMap
-    // already overwrites "type" explicitly wherever it's used, but allProducts/
-    // productWithIdentifier/the subscription's nested "product" field pass product.toMap()
-    // straight through -- normalize those raw plan entries so the JS PlanType contract
-    // (an ordinal) stays stable across both native formats. Both formats resolve to the same
-    // ordinal since DistributionType's declared order already matches Purchasely.PlanType.
-    private fun normalizePlanTypeOrdinal(raw: Any?): Int? = when (raw) {
-        is Number -> raw.toInt()
-        is String -> runCatching { DistributionType.valueOf(raw).ordinal }.getOrNull()
-        else -> null
-    }
-
-    private fun normalizeProductPlans(map: Map<String, Any?>): Map<String, Any?> {
-        val plans = map["plans"] as? List<*> ?: return map
-        val normalized = plans.map { plan ->
-            val planMap = plan as? Map<*, *> ?: return@map plan
-            HashMap(planMap).apply { this["type"] = normalizePlanTypeOrdinal(this["type"]) }
-        }
-        return HashMap(map).apply { this["plans"] = normalized }
-    }
-
     private fun transformSubscriptionsToJson(list: List<PLYSubscriptionData>): JSONArray {
         val result = JSONArray()
         for (data in list) {
-            val map = HashMap(data.data.toMap())
-            map["plan"] = transformPlanToMap(data.plan)
-            map["product"] = normalizeProductPlans(data.product.toMap())
-            map["subscriptionSource"] = when (data.data.storeType) {
-                StoreType.GOOGLE_PLAY_STORE -> StoreType.GOOGLE_PLAY_STORE.ordinal
-                StoreType.AMAZON_APP_STORE -> StoreType.AMAZON_APP_STORE.ordinal
-                StoreType.HUAWEI_APP_GALLERY -> StoreType.HUAWEI_APP_GALLERY.ordinal
-                StoreType.APPLE_APP_STORE -> StoreType.APPLE_APP_STORE.ordinal
-                // CDV-W-15: NONE/WEB_CHECKOUT_STRIPE have no JS SubscriptionSource case of
-                // their own; both map to `none` (4), matching iOS's PLYSubscriptionSource.None.
-                StoreType.NONE, StoreType.WEB_CHECKOUT_STRIPE -> 4
-                else -> null
-            }
-            result.put(JSONObject(map))
+            result.put(JSONObject(transformSubscriptionToMap(data)))
         }
         return result
     }
@@ -1374,6 +1486,7 @@ class PurchaselyPlugin : CordovaPlugin(), CoroutineScope {
         var defaultCallback: CallbackContext? = null
         var eventsCallback: CallbackContext? = null
         var attributesCallback: CallbackContext? = null
+        var webRedemptionCallback: CallbackContext? = null
 
         // Serializes a v6 PLYPresentationOutcome to the wire contract. `result` is kept as an
         // int (PurchaseResult 0/1/2) for back-compat with the pre-6.0 JS layer.
@@ -1426,6 +1539,47 @@ class PurchaselyPlugin : CordovaPlugin(), CoroutineScope {
             )
         }
 
+        // These three live in the companion, not on the instance, so that
+        // `Companion::transformSubscriptionToMap` is an UNBOUND reference. The SDK keeps
+        // the redemption listener in a static (Purchasely.webRedemptionListener), so a
+        // bound reference would keep the plugin, its Activity and its WebView reachable
+        // for as long as that static holds the lambda. None of them touches instance state.
+        // Hardening for the upcoming rc.4 native release: PLYPlan.toMap()'s raw "type" entry is
+        // moving from an ordinal (Int) to the DistributionType name (String). transformPlanToMap
+        // already overwrites "type" explicitly wherever it's used, but allProducts/
+        // productWithIdentifier/the subscription's nested "product" field pass product.toMap()
+        // straight through -- normalize those raw plan entries so the JS PlanType contract
+        // (an ordinal) stays stable across both native formats. Both formats resolve to the same
+        // ordinal since DistributionType's declared order already matches Purchasely.PlanType.
+        private fun normalizePlanTypeOrdinal(raw: Any?): Int? = when (raw) {
+            is Number -> raw.toInt()
+            is String -> runCatching { DistributionType.valueOf(raw).ordinal }.getOrNull()
+            else -> null
+        }
+
+        private fun normalizeProductPlans(map: Map<String, Any?>): Map<String, Any?> {
+            val plans = map["plans"] as? List<*> ?: return map
+            val normalized = plans.map { plan ->
+                val planMap = plan as? Map<*, *> ?: return@map plan
+                HashMap(planMap).apply { this["type"] = normalizePlanTypeOrdinal(this["type"]) }
+            }
+            return HashMap(map).apply { this["plans"] = normalized }
+        }
+
+        /**
+         * Map one [PLYSubscriptionData] to the JS subscription shape.
+         *
+         * Shared by `userSubscriptions`, `userSubscriptionsHistory` and the web redemption
+         * listener, whose `context.subscription` is the same type, so the three report one shape.
+         */
+        internal fun transformSubscriptionToMap(data: PLYSubscriptionData): Map<String, Any?> {
+            return HashMap(data.data.toMap()).apply {
+                this["plan"] = transformPlanToMap(data.plan)
+                this["product"] = normalizeProductPlans(data.product.toMap())
+                this["subscriptionSource"] = subscriptionSourceFor(data.data.storeType)
+            }
+        }
+
         private fun transformPlanToMap(plan: PLYPlan?): Map<String?, Any?> {
             if (plan == null) return HashMap()
             val map = HashMap(plan.toMap())
@@ -1493,3 +1647,179 @@ class PurchaselyPlugin : CordovaPlugin(), CoroutineScope {
          */
     }
 }
+
+/**
+ * Map a native [StoreType] to the `subscriptionSource` wire value.
+ *
+ * The ordinal IS the wire value, and it matches iOS's `PLYSubscriptionSource` one for one:
+ * apple 0, google 1, amazon 2, huawei 3, stripe 4, none 5. Verified against the shipped
+ * 6.1.0 artifacts on both platforms, so there is no per-platform translation here.
+ *
+ * Listed exhaustively on purpose, and `internal` so a unit test drives THIS function
+ * rather than re-deriving the mapping. The previous version named four stores and
+ * collapsed `NONE` and `WEB_CHECKOUT_STRIPE` into a hardcoded 4, on the stated but FALSE
+ * premise that iOS's `None` was 4. It is 5, and 4 is Stripe. So a Web2App subscription
+ * reported `none`, and a sourceless one reported Stripe's value. An `else` branch is what
+ * let that pass unnoticed; without one, a store type added by a future SDK fails the
+ * Kotlin build here instead of silently reporting the wrong source.
+ */
+internal fun subscriptionSourceFor(storeType: StoreType?): Int? = when (storeType) {
+    StoreType.APPLE_APP_STORE -> StoreType.APPLE_APP_STORE.ordinal
+    StoreType.GOOGLE_PLAY_STORE -> StoreType.GOOGLE_PLAY_STORE.ordinal
+    StoreType.AMAZON_APP_STORE -> StoreType.AMAZON_APP_STORE.ordinal
+    StoreType.HUAWEI_APP_GALLERY -> StoreType.HUAWEI_APP_GALLERY.ordinal
+    StoreType.WEB_CHECKOUT_STRIPE -> StoreType.WEB_CHECKOUT_STRIPE.ordinal
+    StoreType.NONE -> StoreType.NONE.ordinal
+    null -> null
+}
+
+/**
+ * Apply the three 6.1.0 start options to a [Purchasely.Builder].
+ *
+ * Extracted so a unit test can assert WHICH builder call each resolver state produces. The
+ * resolvers were covered on their own, but the branch consuming them was not: swapping the
+ * `Clear` and `Set` cases, or inverting the override flag, passed every test in the
+ * repository. That branch is the whole point of the release.
+ *
+ * `Absent` and `Invalid` make NO call, so the SDK keeps whatever it already has. `Clear`
+ * calls `proxy(null)`, which is a real native operation and not the same as making no call.
+ */
+internal fun applyStartOptions(
+    builder: Purchasely.Builder,
+    proxyOption: PLYProxyOption,
+    anonymousUserId: UUID?,
+    anonymousUserIdOverride: Boolean,
+    appHandlesRedemptionAlert: Boolean,
+    redemptionListener: PLYWebRedemptionListener,
+) {
+    when (proxyOption) {
+        is PLYProxyOption.Absent -> {}
+        is PLYProxyOption.Invalid -> {}
+        is PLYProxyOption.Clear -> builder.proxy(null)
+        is PLYProxyOption.Set -> builder.proxy(proxyOption.api)
+    }
+    anonymousUserId?.let { builder.anonymousUserId(it, anonymousUserIdOverride) }
+    builder.webRedemptionListener(appHandlesRedemptionAlert, redemptionListener)
+}
+
+/**
+ * How the `proxy` start option resolves. Purchasely 6.1.0.
+ *
+ * The three JS states are not interchangeable, and a fourth case exists for a value that
+ * will not convert to a URI. Collapsing [Absent] into [Clear] would turn every start into
+ * an implicit clear; collapsing [Clear] into [Absent] would make a clear silently do
+ * nothing.
+ */
+internal sealed class PLYProxyOption {
+    /** The key is absent. Make no native call: leave the current setting untouched. */
+    object Absent : PLYProxyOption()
+
+    /** The key is present and null. Call `proxy(null)` to clear the proxy. */
+    object Clear : PLYProxyOption()
+
+    /** The key holds a usable value. Call `proxy(api)`. */
+    data class Set(val api: String) : PLYProxyOption()
+
+    /** The key holds a value that will not convert. Log it and make no native call. */
+    data class Invalid(val rawValue: String?) : PLYProxyOption()
+}
+
+/**
+ * Resolve the `proxy` start option.
+ *
+ * Pure, and `internal` so a unit test drives the real bridge logic instead of a copy.
+ *
+ * `JSONObject.has` is what separates an absent key from an explicit null, and
+ * `JSONObject.isNull` separates the null from a value. `optString` cannot do this on its
+ * own: it renders `JSONObject.NULL` as the STRING `"null"`, which is exactly how a clear
+ * used to be swallowed into the absent branch.
+ *
+ * The scheme, the host, and the absence of a query, a fragment and credentials are the
+ * native SDK's business: it refuses a bad value with an error log and keeps the production
+ * host, and it drops a trailing slash. This only rejects what will not convert at all,
+ * which keeps the accepted set the same as the iOS bridge's `NSURL` conversion.
+ */
+internal fun resolveProxyOption(options: JSONObject): PLYProxyOption {
+    if (!options.has("proxy")) return PLYProxyOption.Absent
+    if (options.isNull("proxy")) return PLYProxyOption.Clear
+
+    val raw = options.opt("proxy")
+    if (raw !is String) return PLYProxyOption.Invalid(raw?.toString())
+    // A blank value is refused HERE, to match iOS: `[NSURL URLWithString:@""]` is nil, so
+    // the iOS bridge resolves Invalid and never calls native. Leaving it to the SDK would
+    // make the two platforms accept different sets of strings for the same option.
+    if (raw.isBlank()) return PLYProxyOption.Invalid(raw)
+    return try {
+        URI(raw)
+        PLYProxyOption.Set(raw)
+    } catch (e: URISyntaxException) {
+        PLYProxyOption.Invalid(raw)
+    }
+}
+
+/**
+ * Flatten a [PLYWebRedemptionResult] to the 5-key shape the JS listener receives.
+ * See `addWebRedemptionListener` in www/Purchasely.js for the shape itself.
+ *
+ * [subscriptionToMap] is injected so a unit test can drive this without constructing an SDK
+ * [PLYSubscriptionData]. Production passes the plugin's own `transformSubscriptionToMap`.
+ *
+ * EVERY NULL IS PUT AS [JSONObject.NULL] EXPLICITLY, and the object is built here rather
+ * than returned as a `Map` for the caller to wrap. `JSONObject(Map)` disagrees across
+ * implementations: Android's wraps a null and keeps the key, the reference `org.json` DROPS
+ * the entry — which would reach JS as `undefined` instead of `null`.
+ */
+internal fun webRedemptionResultToJson(
+    result: PLYWebRedemptionResult,
+    subscriptionToMap: (PLYSubscriptionData) -> Map<String, Any?>,
+): JSONObject {
+    val json = JSONObject()
+    when (result) {
+        is PLYWebRedemptionResult.Success -> {
+            json.put("isSuccess", true)
+            val context = result.context
+            if (context == null) {
+                json.put("context", JSONObject.NULL)
+            } else {
+                val subscription = context.subscription
+                json.put("context", JSONObject().put(
+                    "subscription",
+                    if (subscription == null) JSONObject.NULL
+                    else JSONObject(subscriptionToMap(subscription))
+                ))
+            }
+            json.put("replay", result.replay)
+            json.put("errorCode", JSONObject.NULL)
+            json.put("errorMessage", JSONObject.NULL)
+        }
+        is PLYWebRedemptionResult.Failure -> {
+            json.put("isSuccess", false)
+            json.put("context", JSONObject.NULL)
+            // A failure still reports replay, so the shape never changes between branches.
+            json.put("replay", false)
+            json.put("errorCode", result.errorCode ?: JSONObject.NULL)
+            json.put("errorMessage", result.errorMessage ?: JSONObject.NULL)
+        }
+    }
+    return json
+}
+
+/**
+ * Parse a canonical UUID string, or return null.
+ *
+ * JS has no UUID type, so an anonymous user id crosses the bridge as a string.
+ * `UUID.fromString` is lenient and accepts a short form such as `"1-2-3-4-5"` that the iOS
+ * `NSUUID` parser refuses. The round-trip check makes both platforms agree on what
+ * "canonical" means, so one id string is accepted, or refused, on both.
+ *
+ * `internal` so a unit test drives it without an Android logger. The caller logs a refusal.
+ */
+internal fun parseCanonicalUuid(value: String?): UUID? {
+    if (value == null) return null
+    val parsed = try {
+        UUID.fromString(value)
+    } catch (e: IllegalArgumentException) {
+        return null
+    }
+    return if (parsed.toString().equals(value, ignoreCase = true)) parsed else null
+}

package/src/ios/CDVPurchasely+Events.h

@@ -8,7 +8,7 @@
 #import <Cordova/CDVPlugin.h>
 #import "CDVPurchasely.h"
 
-@interface CDVPurchasely (Events) <PLYEventDelegate> {
+@interface CDVPurchasely (Events) <PLYEventDelegate, PLYWebRedemptionDelegate> {
 
 }
 

package/src/ios/CDVPurchasely+Events.m

@@ -27,6 +27,40 @@
 	}
 }
 
+/// `PLYWebRedemptionDelegate`. The SDK calls this on the main thread, once per settled
+/// redemption, on success and on failure alike, and always after the matching
+/// REDEMPTION_CONSUMED / REDEMPTION_FAILED event reached the event delegate.
+///
+/// Mapped to the flat 5-key shape the Android bridge emits, so one JS listener drives both
+/// platforms. `context` and `context.subscription` stay separately nullable: a success can
+/// carry no context at all, and a present context can carry no subscription.
+///
+/// `errorMessage` can hold the backend's masked email hint for an expired link. The
+/// REDEMPTION_FAILED event drops that hint on purpose; this channel keeps it, so the app
+/// can tell the user where the fresh link went.
+///
+/// The Android bridge carries it too: `RedemptionOutcome.Expired.toResult()` appends the
+/// same hint. So the "show it, never log it" rule the JS docs state is unconditional, and
+/// must not be written as an iOS-only caveat.
+- (void)webRedemptionCompletedWithResult:(PLYWebRedemptionResult * _Nonnull)result {
+	if (self.webRedemptionCommand == nil) {
+		return;
+	}
+
+	PLYSubscription *subscription = result.context.subscription;
+	NSDictionary<NSString *, id> *body =
+		[CDVPurchasely webRedemptionBodyWithSuccess:result.isSuccess
+										 hasContext:result.context != nil
+									   subscription:subscription != nil ? subscription.asDictionary : nil
+											 replay:result.replay
+										  errorCode:result.errorCode
+									   errorMessage:result.errorMessage];
+
+	CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK messageAsDictionary:body];
+	[pluginResult setKeepCallbackAsBool:YES];
+	[self.commandDelegate sendPluginResult:pluginResult callbackId:self.webRedemptionCommand.callbackId];
+}
+
 - (void)reloadContent: (NSNotification *)aNotification {
 	if (self.purchasedCommand) {
 		CDVPluginResult* pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK];

package/src/ios/CDVPurchasely.h

@@ -8,11 +8,59 @@
 #import <Cordova/CDVPlugin.h>
 #import <Purchasely/Purchasely-Swift.h>
 
+/// How the `proxy` start option resolves. Purchasely 6.1.0.
+///
+/// The three JS states are NOT interchangeable, and a fourth case exists for a value the
+/// bridge cannot convert. `proxyWithApi:` takes an `NSURL *_Nullable`, where nil means
+/// CLEAR, so an unconvertible string must skip the modifier rather than pass nil: passing
+/// nil would silently disable a proxy the app explicitly asked for, because of a typo.
+typedef NS_ENUM(NSInteger, CDVPurchaselyProxyOption) {
+    /// The key is absent. Make no native call: leave the current setting untouched.
+    CDVPurchaselyProxyOptionAbsent = 0,
+    /// The key is present and null. Call `proxyWithApi:nil` to clear the proxy.
+    CDVPurchaselyProxyOptionClear,
+    /// The key holds a convertible string. Call `proxyWithApi:` with the URL.
+    CDVPurchaselyProxyOptionSet,
+    /// The key holds a string `NSURL` cannot convert. Log and make no native call.
+    CDVPurchaselyProxyOptionInvalid
+};
+
 // Protocol conformance (PLYEventDelegate / PLYUserAttributeDelegate) is declared on the
 // CDVPurchasely (Events) and (UserAttributes) categories, which implement the delegate methods.
 @interface CDVPurchasely : CDVPlugin {
 }
 
+/// Resolve the `proxy` start option to one of the four cases above.
+///
+/// Pure, and exposed so a unit test drives the real bridge logic instead of a copy. `value`
+/// is the raw option, so `nil` for an absent key and `NSNull` for an explicit JS null.
+/// `outUrl` receives the URL only for `CDVPurchaselyProxyOptionSet`.
++ (CDVPurchaselyProxyOption)proxyOptionFor:(id _Nullable)value url:(NSURL * _Nullable * _Nullable)outUrl;
+
+/// Build the flat 5-key body a settled Web2App redemption reports to JS.
+///
+/// Takes primitives rather than a `PLYWebRedemptionResult`, because that class declares
+/// `init` unavailable and a test cannot construct one. `hasContext` is separate from
+/// `subscription` on purpose: a present context carrying no subscription is NOT the same as
+/// no context at all, and both must stay expressible.
+///
+/// Exposed so the XCTest target asserts the real shape the delegate emits, rather than a
+/// copy of it. Matches the React Native bridge's seam of the same name.
++ (NSDictionary<NSString *, id> * _Nonnull)webRedemptionBodyWithSuccess:(BOOL)isSuccess
+                                                             hasContext:(BOOL)hasContext
+                                                           subscription:(NSDictionary * _Nullable)subscription
+                                                                 replay:(BOOL)replay
+                                                              errorCode:(NSString * _Nullable)errorCode
+                                                           errorMessage:(NSString * _Nullable)errorMessage;
+
+/// Parse a canonical UUID string, or return nil.
+///
+/// JS has no UUID type, so an anonymous user id crosses the bridge as a string. Exposed so
+/// a unit test can pin the cross-platform contract: this refuses the lenient short form
+/// (`"1-2-3-4-5"`) that Android's `UUID.fromString` accepts, which is why the Android
+/// bridge adds a round-trip check.
++ (NSUUID * _Nullable)canonicalUUIDFromString:(id _Nullable)value;
+
 // The presentation currently displayed (v6 uses id<PLYPresentation> for close()/back()).
 @property (nonatomic, strong) id<PLYPresentation> currentPresentation;
 
@@ -20,6 +68,12 @@
 @property CDVInvokedUrlCommand* eventCommand;
 @property CDVInvokedUrlCommand* attributeCommand;
 
+// Purchasely 6.1.0. The command `addWebRedemptionListener` recorded, or nil. The
+// PLYWebRedemptionDelegate is registered on the builder chain in `start:` (the native SDK
+// has no runtime setter), so this is the only switch: nil makes
+// `webRedemptionCompletedWithResult:` a no-op.
+@property CDVInvokedUrlCommand* webRedemptionCommand;
+
 @property (nonatomic) NSMutableArray<id<PLYPresentation>> *presentationsLoaded;
 
 @property (nonatomic) CDVInvokedUrlCommand* purchaseResolve;
@@ -57,6 +111,9 @@
 - (void)userSubscriptionsHistory:(CDVInvokedUrlCommand*)command;
 - (void)addEventsListener:(CDVInvokedUrlCommand*)command;
 - (void)removeEventsListener:(CDVInvokedUrlCommand*)command;
+- (void)releaseCallbackStream:(CDVInvokedUrlCommand * _Nullable)command;
+- (void)addWebRedemptionListener:(CDVInvokedUrlCommand*)command;
+- (void)removeWebRedemptionListener:(CDVInvokedUrlCommand*)command;
 - (void)registerActionInterceptor:(CDVInvokedUrlCommand*)command;
 - (void)unregisterActionInterceptor:(CDVInvokedUrlCommand*)command;
 - (void)completeActionInterceptor:(CDVInvokedUrlCommand*)command;

package/src/ios/CDVPurchasely.m

@@ -29,6 +29,82 @@
     self.pendingInterceptCompletions = [NSMutableDictionary new];
 }
 
++ (CDVPurchaselyProxyOption)proxyOptionFor:(id _Nullable)value url:(NSURL * _Nullable * _Nullable)outUrl {
+    if (outUrl != NULL) {
+        *outUrl = nil;
+    }
+    // An absent key and an explicit null are different operations. Check NSNull FIRST:
+    // it is a real object, so an `isKindOfClass:[NSString class]` test would fall through
+    // to the absent branch and turn a requested clear into a silent no-op.
+    if (value == nil) {
+        return CDVPurchaselyProxyOptionAbsent;
+    }
+    if (value == [NSNull null]) {
+        return CDVPurchaselyProxyOptionClear;
+    }
+    if (![value isKindOfClass:[NSString class]]) {
+        return CDVPurchaselyProxyOptionInvalid;
+    }
+    // Do not validate the scheme, the host, a query, a fragment or credentials here. The
+    // native SDK refuses those with an error log and keeps the production host, and it
+    // drops a trailing slash. The bridge only rejects what will not convert at all.
+    NSURL *url = [NSURL URLWithString:(NSString *)value];
+    if (url == nil) {
+        return CDVPurchaselyProxyOptionInvalid;
+    }
+    if (outUrl != NULL) {
+        *outUrl = url;
+    }
+    return CDVPurchaselyProxyOptionSet;
+}
+
++ (NSDictionary<NSString *, id> * _Nonnull)webRedemptionBodyWithSuccess:(BOOL)isSuccess
+                                                             hasContext:(BOOL)hasContext
+                                                           subscription:(NSDictionary * _Nullable)subscription
+                                                                 replay:(BOOL)replay
+                                                              errorCode:(NSString * _Nullable)errorCode
+                                                           errorMessage:(NSString * _Nullable)errorMessage {
+    // Every key is always present, on both branches, so a JS listener reads one shape
+    // whether the redemption was granted or refused. Absence is NSNull, never a missing
+    // key: a missing key reaches JS as `undefined` instead of `null`.
+    id context = [NSNull null];
+    if (hasContext) {
+        context = @{ @"subscription": subscription ?: [NSNull null] };
+    }
+    return @{
+        @"isSuccess":    @(isSuccess),
+        @"context":      context,
+        @"replay":       @(replay),
+        @"errorCode":    errorCode ?: [NSNull null],
+        @"errorMessage": errorMessage ?: [NSNull null]
+    };
+}
+
++ (NSUUID * _Nullable)canonicalUUIDFromString:(id _Nullable)value {
+    if (![value isKindOfClass:[NSString class]]) {
+        return nil;
+    }
+    return [[NSUUID alloc] initWithUUIDString:(NSString *)value];
+}
+
+/// Cordova calls this when the WebView navigates, which invalidates every callbackId the
+/// previous page handed us. Without it the stored commands stay live and every listener
+/// callback is sent to a dead callbackId after a reload.
+///
+/// The redemption case is the one that matters most: `webRedemptionDelegate:` is set on the
+/// builder at `start:`, and the SDK holds the delegate weakly, so this object keeps
+/// receiving outcomes for as long as the plugin lives.
+/// `webRedemptionCompletedWithResult:` reads `webRedemptionCommand` at fire time, so a
+/// reloaded page can re-register and keep working; clearing here makes the window in
+/// between a clean no-op rather than a send on a dead callbackId.
+- (void)onReset {
+    self.eventCommand = nil;
+    self.attributeCommand = nil;
+    self.webRedemptionCommand = nil;
+    self.purchasedCommand = nil;
+    [super onReset];
+}
+
 - (void)start:(CDVInvokedUrlCommand*)command {
     // v6: a single options dictionary (see the JS↔native contract), no longer positional args.
     NSDictionary *opts = [command argumentAtIndex:0];
@@ -91,6 +167,68 @@
         builder = [builder allowCampaigns:allowCampaigns.boolValue];
     }
 
+    // Both bridges report a refused-and-skipped option at the SAME severity, and
+    // deliberately with a plain log line on both: NSLog here, Log.e on Android. Neither
+    // renders UI. Do not reach for anything that puts an overlay or an alert in front of
+    // the host app: start() continues, the option was simply ignored, and a third-party
+    // SDK has no business interrupting someone else's app over an option it chose to skip.
+
+    // v6.1.0: JS has no UUID type, so the id crosses the bridge as a string and is parsed
+    // here. The native builder takes an NSUUID, which is where the guarantee used to live;
+    // a string-typed bridge is the only place left to catch a bad value. Refuse it loudly
+    // and skip the option. The SDK still starts, matching how native treats an unusable
+    // proxy url.
+    id anonymousUserId = opts[@"anonymousUserId"];
+    if ([anonymousUserId isKindOfClass:[NSString class]]) {
+        NSUUID *parsed = [CDVPurchasely canonicalUUIDFromString:anonymousUserId];
+        if (parsed == nil) {
+            // The value is NOT logged. A mis-wired field lands here just as easily as a
+            // typo -- an email, an appUserId -- and a device log is captured during
+            // support. The length is enough to tell a truncated id from a wrong field.
+            NSLog(@"[Purchasely] `anonymousUserId` must be a canonical UUID string, for example "
+                   "\"3f2504e0-4f89-11d3-9a0c-0305e82c3301\". Received a %lu-character value. "
+                   "The anonymous user id is not applied.",
+                  (unsigned long)((NSString *)anonymousUserId).length);
+        } else {
+            NSNumber *override = opts[@"anonymousUserIdOverride"];
+            BOOL shouldOverride = [override isKindOfClass:[NSNumber class]] ? override.boolValue : NO;
+            builder = [builder appAnonymousUserId:parsed override:shouldOverride];
+        }
+    }
+
+    // v6.1.0: three states, and they are not interchangeable. An absent key makes no
+    // native call and leaves the current setting untouched; an explicit null clears the
+    // proxy and returns to api.purchasely.io, which is a supported operation and not an
+    // error; a string routes the API host. A value NSURL cannot convert skips the
+    // modifier, because `proxyWithApi:nil` means CLEAR, not "ignore this value", so
+    // passing nil would silently disable a proxy the app asked for.
+    NSURL *proxyUrl = nil;
+    switch ([CDVPurchasely proxyOptionFor:opts[@"proxy"] url:&proxyUrl]) {
+        case CDVPurchaselyProxyOptionAbsent:
+            break;
+        case CDVPurchaselyProxyOptionClear:
+            builder = [builder proxyWithApi:nil];
+            break;
+        case CDVPurchaselyProxyOptionSet:
+            builder = [builder proxyWithApi:proxyUrl];
+            break;
+        case CDVPurchaselyProxyOptionInvalid:
+            NSLog(@"[Purchasely] `proxy` must be an https base URL, for example "
+                   "\"https://svc.purchasely.io\", or null to clear the proxy. Received "
+                   "\"%@\". The proxy is not applied.", opts[@"proxy"]);
+            break;
+    }
+
+    // v6.1.0: registered unconditionally. The native SDK has no runtime setter on purpose,
+    // because a redemption can settle during `start()` (a cold start that the `ply/redeem`
+    // link itself triggered, or a token a previous launch left pending). The delegate
+    // callback returns early when `addWebRedemptionListener` recorded no command, so this
+    // is behaviour-neutral by default.
+    NSNumber *handlesRedemptionAlert = opts[@"appHandlesRedemptionAlert"];
+    builder = [builder webRedemptionDelegate:self
+                   appHandlesRedemptionAlert:[handlesRedemptionAlert isKindOfClass:[NSNumber class]]
+                                             ? handlesRedemptionAlert.boolValue : NO];
+
     // Cold-start deeplink URL captured at launch (handled automatically once start completes).
     NSString *deeplink = opts[@"deeplink"];
     if ([deeplink isKindOfClass:[NSString class]] && deeplink.length > 0) {
@@ -527,6 +665,41 @@
     self.eventCommand = nil;
 }
 
+/// End a kept-alive Cordova callback stream, freeing its JavaScript closure.
+///
+/// Every result this bridge sends a listener carries `keepCallback:YES`, so dropping the
+/// native command alone leaks the JS closure until the WebView reloads. NO_RESULT with
+/// `keepCallback:NO` is cordova.js's own documented way out: it "is used to remove a
+/// callback from the list without calling the callbacks".
+- (void)releaseCallbackStream:(CDVInvokedUrlCommand * _Nullable)command {
+    if (command == nil) {
+        return;
+    }
+    CDVPluginResult *terminal = [CDVPluginResult resultWithStatus:CDVCommandStatus_NO_RESULT];
+    [terminal setKeepCallbackAsBool:NO];
+    [self.commandDelegate sendPluginResult:terminal callbackId:command.callbackId];
+}
+
+// v6.1.0. The PLYWebRedemptionDelegate is registered on the builder chain in `start:` (the
+// native SDK has no runtime setter, because a redemption can settle during start()), so
+// this action only records the command to route the outcome to. Call it BEFORE start().
+- (void)addWebRedemptionListener:(CDVInvokedUrlCommand*)command {
+    // Close the previous stream before replacing it, or its JS closure stays in
+    // cordova.callbacks forever.
+    [self releaseCallbackStream:self.webRedemptionCommand];
+    self.webRedemptionCommand = command;
+}
+
+- (void)removeWebRedemptionListener:(CDVInvokedUrlCommand*)command {
+    // The delegate stays registered. Clearing the command makes
+    // `webRedemptionCompletedWithResult:` a no-op.
+    [self releaseCallbackStream:self.webRedemptionCommand];
+    self.webRedemptionCommand = nil;
+    // Acknowledge the remove itself, so ITS callbackId is freed too. A void action that
+    // never answers leaks its own entry exactly like the listener's.
+    [self successFor:command resultBool:YES];
+}
+
 - (void)removeUserAttributeListener:(CDVInvokedUrlCommand*)command {
     // v6 `setUserAttributeDelegate:` is _Nonnull (no native unregister). Clearing
     // attributeCommand makes the user-attribute callbacks a no-op.

package/www/Purchasely.js

@@ -59,11 +59,25 @@ function presentationDispatcher(success, callbacks) {
 //   allowDeeplink   (bool, optional)
 //   allowCampaigns  (bool, optional)
 //   deeplink        (string, optional — cold-start deeplink URL)
+//
+// Purchasely 6.1.0 adds four options:
+//   anonymousUserId         (string, optional — a canonical UUID string; a bad value is
+//                            logged and skipped, start() still succeeds)
+//   anonymousUserIdOverride (bool, optional — false; true SPLITS the user history)
+//   proxy                   (string|null, optional — Android+iOS. THREE STATES:
+//                              'https://…'  routes the API host
+//                              null         CLEARS it, back to api.purchasely.io
+//                              key absent   leaves the current setting untouched
+//                            A clear is a supported native operation, not an error.)
+//   appHandlesRedemptionAlert (bool, optional — false keeps the SDK popin, true hands the
+//                            result screen to the app. See addWebRedemptionListener.)
+//
+// README.md "What is new in 6.1.0" is the reference for all four.
 exports.start = function (options, success, error) {
     var opts = options || {};
     var cordovaSdkVersion = cordova.define.moduleMap['cordova/plugin_list'].exports['metadata']['cordova-plugin-purchasely']
     if(!cordovaSdkVersion) {
-        cordovaSdkVersion = "6.0.1";
+        cordovaSdkVersion = "6.1.1";
     }
     opts.sdkVersion = cordovaSdkVersion;
     exec(success, error, 'Purchasely', 'start', [opts]);
@@ -89,7 +103,76 @@ PLYStartBuilder.prototype.storekitVersion = function (value) { this._options.sto
 PLYStartBuilder.prototype.storeKit1 = function (value) { this._options.storeKit1 = value; return this; };
 PLYStartBuilder.prototype.deeplink = function (value) { this._options.deeplink = value; return this; };
 
+// Purchasely 6.1.0. `id` must be a canonical UUID string; `override` defaults to false.
+// See the exports.start option block for the full contract.
+PLYStartBuilder.prototype.anonymousUserId = function (id, override) {
+    this._options.anonymousUserId = id;
+    this._options.anonymousUserIdOverride = override === undefined ? false : override;
+    return this;
+};
+
+// Purchasely 6.1.0. Pass an https base URL to route the API host, or null to CLEAR a
+// proxy and return to api.purchasely.io. Both differ from never calling the modifier,
+// which leaves the current setting untouched. See the exports.start option block.
+//
+// An argument is required. `proxy()` with none is refused, because the no-argument native
+// modifiers disagree across platforms: iOS `proxy()` routes through Purchasely's own
+// proxy at svc.purchasely.io, while Android `proxy()` clears. A Cordova shorthand would
+// therefore mean two different things on the two platforms.
+//
+// `undefined` is never stored: JSON.stringify drops an undefined-valued key, which would
+// make an explicit clear indistinguishable from an absent option on both natives.
+PLYStartBuilder.prototype.proxy = function (api) {
+    // An explicit `undefined` is treated exactly like no argument at all, and NOT as null.
+    // The two public entry points have to agree on the same input: JSON.stringify drops an
+    // undefined-valued key, so `start({ proxy: undefined })` reaches native as Absent.
+    // Mapping it to null here would make `builder(k).proxy(config.proxy)` CLEAR the proxy
+    // whenever config.proxy has not loaded yet, which is the opposite of leaving it alone.
+    if (arguments.length === 0 || api === undefined) {
+        defaultError('[Purchasely] proxy() requires an argument: an https base URL, or ' +
+            'null to clear the proxy. The proxy option is not applied.');
+        return this;
+    }
+    this._options.proxy = api;
+    return this;
+};
+
+// Purchasely 6.1.0. false (the default) keeps the SDK's own redemption popin.
+PLYStartBuilder.prototype.appHandlesRedemptionAlert = function (handles) {
+    this._options.appHandlesRedemptionAlert = handles;
+    return this;
+};
+
+// Purchasely 6.1.0: the PRIMARY way to receive Web2App redemption outcomes.
+//
+//   Purchasely.builder(apiKey).webRedemptionListener(onRedemption, true).start()
+//
+// The callback never crosses the bridge: each native registers ITSELF as the delegate at
+// start() and forwards outcomes as a Cordova callback stream, so this is a JS concern only.
+//
+// STORED HERE, SUBSCRIBED IN start(), just before the native call. Do not move it back:
+// subscribing at chain time leaks a live callback from a builder that is never started. A
+// redemption can only settle once the SDK runs, so subscribing here still covers one that
+// settles DURING start(), which is the case the feature exists for.
+//
+// 2nd argument = appHandlesRedemptionAlert; omitting it keeps the native default. Callback
+// first, matching iOS -- the natives disagree on order (Android takes the flag first).
+PLYStartBuilder.prototype.webRedemptionListener = function (callback, appHandlesRedemptionAlert) {
+    // Kept off _options on purpose: that object is the exec payload, and a callback has no
+    // business being serialized into it.
+    this._webRedemptionCallback = callback;
+    if (appHandlesRedemptionAlert !== undefined) {
+        this._options.appHandlesRedemptionAlert = appHandlesRedemptionAlert;
+    }
+    return this;
+};
+
 PLYStartBuilder.prototype.start = function (success, error) {
+    // Subscribe immediately before the native start call, never earlier. See
+    // webRedemptionListener above for why this is deferred to here.
+    if (this._webRedemptionCallback) {
+        exports.addWebRedemptionListener(this._webRedemptionCallback);
+    }
     if (success) {
         exports.start(this._options, success, error);
         return undefined;
@@ -118,6 +201,37 @@ exports.addEventsListener = function (success, error) {
     exec(success, error, 'Purchasely', 'addEventsListener', []);
 };
 
+// Purchasely 6.1.0: the outcome of a Web2App redemption ({scheme}://ply/redeem/{token}).
+//
+// SECONDARY PATH, for replacing the listener while the SDK already runs. Prefer
+// builder(apiKey).webRedemptionListener(cb). Both share ONE native slot: last caller wins.
+//
+// success receives { isSuccess, context, replay, errorCode, errorMessage }:
+//   isSuccess     Bool.
+//   context       { subscription } or null, and `subscription` is separately nullable.
+//                 Same shape as userSubscriptions(), so purchaseToken, nextRenewalDate and
+//                 cancelledDate may be absent -- Android sends an explicit null, iOS omits
+//                 the key. A truthiness check covers both; `!== undefined` does not.
+//   replay        Bool. The SERVER says the token was redeemed before. False on failure.
+//   errorCode     'EXPIRED_REDEMPTION_TOKEN' | 'INVALID_REDEMPTION_TOKEN' | null.
+//   errorMessage  Human-readable, English, or null. Never contains the token.
+//
+// Called on the main thread, exactly once per settled redemption.
+//
+// PRIVACY, BOTH PLATFORMS: errorMessage for an expired link can carry a MASKED EMAIL
+// ADDRESS. Show it to the user; never log it or send it to analytics or a crash reporter.
+// The rule is unconditional -- do NOT gate it on a platform check. The REDEMPTION_FAILED
+// event drops the hint, so that channel is safe.
+exports.addWebRedemptionListener = function (success, error) {
+    exec(success, error, 'Purchasely', 'addWebRedemptionListener', []);
+};
+
+// Purchasely 6.1.0: stop receiving redemption outcomes. The native delegate stays
+// registered (it is fixed at start()); clearing the callback makes it a no-op.
+exports.removeWebRedemptionListener = function () {
+    exec(() => {}, defaultError, 'Purchasely', 'removeWebRedemptionListener', []);
+};
+
 exports.addUserAttributeListener = function(success, error) {
     exec(success, error, 'Purchasely', 'addUserAttributeListener', []);
 };
@@ -508,6 +622,11 @@ exports.userDidConsumeSubscriptionContent = function () {
 
 // PAR-29: invalidateCache forces a fresh fetch instead of returning the cached list
 // (native default false on both platforms).
+// A subscription's purchaseToken, nextRenewalDate and cancelledDate can all be ABSENT, and
+// the two platforms report absence differently: Android sends the key with an explicit
+// null, iOS omits it entirely (and never emits purchaseToken at all, because the native
+// PLYSubscription has no such property). Handle both -- a truthiness check covers them,
+// `!== undefined` does not. Same shape as the web redemption context's `subscription`.
 exports.userSubscriptions = function (success, error, invalidateCache) {
     exec(success, defaultError, 'Purchasely', 'userSubscriptions', [!!invalidateCache]);
 };
@@ -731,12 +850,23 @@ exports.PurchaseResult = {
 	RESTORED: 2
 }
 
+// Values are the NATIVE raw values, verified against the shipped 6.1.0 artifacts:
+// iOS PLYSubscriptionSource (stripe = 4, none = 5) and Android StoreType ordinals
+// (WEB_CHECKOUT_STRIPE = 4, NONE = 5). Both platforms agree, so there is no
+// per-platform mapping here and no renumbering hazard.
+//
+// `webCheckoutStripe` was missing and `none` was 4, which was correct before the native
+// SDKs inserted the Stripe case at 4 (Android ~5.5.0) and pushed NONE to 5. A Web2App
+// subscription therefore reported `none`, and a genuinely sourceless one reported a value
+// this object had no name for. A Web2App redemption grants a subscription from exactly
+// that source, so `context.subscription` is the payload most likely to carry it.
 exports.SubscriptionSource = {
     appleAppStore: 0,
     googlePlayStore: 1,
     amazonAppstore: 2,
     huaweiAppGallery: 3,
-    none: 4
+    webCheckoutStripe: 4,
+    none: 5
 }
 
 exports.PlanType = {