@purchasely/cordova-plugin-purchasely 6.0.0 → 6.1.0

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

@@ -13,14 +13,96 @@
 
 @implementation CDVPurchasely
 
-- (instancetype)init {
-    self = [super init];
+// pluginInitialize is Cordova's setup hook and is called by every host, after
+// viewController/webView/commandDelegate are assigned. The previous -init override was only
+// reached on cordova-ios, whose -initWithWebViewEngine: calls [self init]; Capacitor's
+// vendored CapacitorCordova calls [super init] instead, which dispatches to NSObject and
+// never reaches a subclass override - so under Capacitor these collections stayed nil, and
+// writing into a nil NSMutableDictionary/NSMutableArray is a silent no-op. That lost every
+// interceptor callbackId (intercepted actions completed .notHandled without reaching JS) and
+// every preloaded presentation ("Presentation not loaded" from preload/display).
+- (void)pluginInitialize {
+    [super pluginInitialize];
 
     self.presentationsLoaded = [NSMutableArray new];
     self.actionInterceptorCallbackIds = [NSMutableDictionary new];
     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;
+}
 
-    return self;
++ (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 {
@@ -85,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) {
@@ -521,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.
@@ -1266,6 +1445,18 @@ static BOOL PLYPresentationActionFromString(NSString *kind, PLYPresentationActio
             } else if (presentation != nil) {
                 [self.presentationsLoaded addObject:presentation];
                 [self successFor:command resultDict:[self resultDictionaryForFetchPresentation:presentation]];
+            } else {
+                // Neither branch taken means the Cordova command is never completed and the
+                // JS promise returned by preload() stays pending for the life of the page:
+                // no resolve, no reject, no error, nothing logged. Answer instead, so the
+                // caller can handle it.
+                //
+                // Purchasely 6.0.0 does not produce this pair (PresentationRequest.swift
+                // maps a success-with-nil presentation to PLYError.presentationNotLoaded),
+                // so this is defence in depth against a future SDK, not a fix for a
+                // reproduced failure. It costs one branch and removes a whole class of
+                // silent hang.
+                [self failureFor:command resultString: @"Presentation preload completed without a presentation and without an error"];
             }
         }];
     });

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.0";
+        cordovaSdkVersion = "6.1.0";
     }
     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 = {