feat(v6)!: cross-platform parity audit remediation (transitions, attributes, v5 cleanup)

[kherembourg]

Context

Cross-platform parity audit of the v6 React Native bridge against the pinned native SDKs (iOS/Android 6.0.0-rc.3). The audit compared the TS surface, the iOS Objective-C bridge, and the Android Kotlin bridge for behavioral divergences, dead v5 residue, payload/enum mismatches, and GDPR wire-format correctness. This PR remediates every confirmed finding, ports the audit test additions, and documents each breaking change in MIGRATION-v6.md.

Every iOS selector touched here was verified to exist in the pinned rc.3 header (Purchasely-Swift.h, checksum ffb024…, the build Podfile.lock resolves to). No native pins were bumped.

Fixes by ID

• RN-W-01 — signPromotionalOffer on Android was a permanent reject("Not supported on Android"). Now resolves as a no-op success (no StoreKit equivalent exists on Android). No TS Platform.OS guard added (transparent pass-through); JSDoc marks it iOS-only; MIGRATION-v6.md corrected (moved out of the "unchanged" list with an explicit note).
• RN-W-02 — iOS display() no longer hardcodes showController:type:PLYUIControllerTypeProductPage. It now parses the full PLYTransition (type fullScreen/push/modal/drawer/popin/inlinePaywall, dismissible, backgroundColors, percentage height) and displays through the SDK's own displayWithTransition:completion:. See behavior note below on the iOS dimension ceiling.
• FLT-W-02 / PAR-19 — new top-level closeAllScreens() (TS + iOS RCT_EXPORT_METHOD + Android @ReactMethod).
• RN-W-04 / ENM-07 — iOS constantsToExport now includes sourceNone; TS gains SubscriptionSource.NONE.
• RN-W-05 — Android start() now defaults an unknown runningMode ordinal to Observer, aligned with iOS.
• RN-W-06 — per-platform JSDoc on PLYPresentationPlan (basePlanId/storeOfferId Android-only; offerId cross-platform but distinct id spaces). No behavior change.
• RN-W-07 — iOS PLYPlan+Hybrid always emits hasIntroductoryPrice as a boolean (it was deleted from the dict for free-trial plans, breaking the non-optional TS contract); hasFreeTrial still set.
• RN-W-08 — dead RCTConvert_PurchaselyRN.m deleted + 4 project.pbxproj references removed (plutil -lint OK; podspec uses a glob, no stale explicit reference).
• RN-W-09 — orphaned iOS startWithAPIKey removed (impl + any reference; the only remaining mention is a negative-assertion test).
• ENM-06 — dead v5 runningModeTransactionOnly / runningModePaywallObserver constants removed (iOS, Android, interfaces.ts, both native tests). Observer/Full keep their original ordinals (1/4).
• ENM-04 / REC-11 — onesignalPlayerId / Attributes.ONESIGNAL_PLAYER_ID removed; oneSignalExternalId + oneSignalUserId added. iOS uses the native symbols (PLYAttributeOneSignalExternalId/…UserId), never hardcoded ints — PLYAttributeOneSignalPlayerId still exists in the pinned header (its native removal ships separately) but is no longer referenced. Android uses Attribute.ONESIGNAL_*.ordinal.
• PAR-12 — getConstants() removed from the public Purchasely export (it leaked a raw 60+-field numeric blob). The enums still read NativeModules.Purchasely.getConstants() internally, so nothing else changes.
• PAR-14 — purchaseResultFromOrdinal no longer re-exported from the package root (export type * drops the runtime value); the SDK's own internal use is unaffected.
• PAR-24 — cumulatedRevenuesInUSD + subscriptionDurationIn{Days,Weeks,Months} reactivated as optional with Android-only JSDoc (verified present in Android's native PLYSubscription; iOS PLYSubscription+Hybrid never emits them and was not touched).
• PAR-30 — userLogout(clearUserAttributes = true) now forwarded to both natives (userLogout:(BOOL) iOS, userLogout(Boolean) Android) instead of being hardcoded/omitted.
• PAR-07 — getBuiltInAttributes() / getBuiltInAttribute(key) exposed (TS + both natives). iOS uses getBuiltInAttributes / getBuiltInAttributeWith:.
• rc.4 hardening — plan type parsing tolerates both the numeric ordinal (today) and Android's upcoming DistributionType string at both JS transform points (the interceptAction('purchase', …) payload and the display()/preload() outcome's plan), via normalizePlan/normalizePlanType.

Breaking changes (see MIGRATION-v6.md)

• Purchasely.getConstants() no longer exposed publicly (PAR-12) — use the typed enums.
• onesignalPlayerId / Attributes.ONESIGNAL_PLAYER_ID removed (ENM-04) — use ONESIGNAL_EXTERNAL_ID / ONESIGNAL_USER_ID.
• v5 runningModeTransactionOnly / runningModePaywallObserver constants removed (ENM-06).
• purchaseResultFromOrdinal no longer re-exported from the package root (PAR-14, was documented @internal).

Behavior notes

• signPromotionalOffer on Android is a no-op success — don't rely on the shape of the resolved value there.
• iOS transition dimension ceiling (rc.3): the pinned native SDK only bridges a legacy 0–1 heightPercentage to Objective-C. So on iOS height: { type: 'percentage', value }, type, dismissible, and backgroundColors are honored; height: { type: 'pixel' } and width (any unit) are accepted but ignored with a console warning (native content-hugging sizing applies). Android honors width/height in both units. Documented in MIGRATION-v6.md.
• Fallback (no transition arg): both platforms pass a nil transition, honoring the backend-defined presentation.transition (iOS displayWithTransition:nil, Android display(transition = null)). Note this replaces iOS's previous hardcoded full-screen ProductPage — the new behavior matches the SDK's own display() and Android.
• runningMode unknown-ordinal fallback is now Observer on both platforms.

New APIs

closeAllScreens() · SubscriptionSource.NONE · getBuiltInAttributes() / getBuiltInAttribute(key) · userLogout(clearUserAttributes?) · Attributes.ONESIGNAL_EXTERNAL_ID / Attributes.ONESIGNAL_USER_ID.

GDPR trace (REC-15 / ENM-12)

Verdict, counter-verified on both platforms:

• RN's own wire strings are kebab-case singular (e.g. third-party-integration); the other Purchasely SDKs use SCREAMING_SNAKE_CASE plural (e.g. THIRD_PARTY_INTEGRATIONS).
• No raw string reaches the backend. Both bridges map the input strings to native PLYDataProcessingPurpose enum objects and pass an NSSet/Set of those enums to Purchasely.revokeDataProcessingConsent(For:). The raw string is consumed at the bridge boundary; only the resolved native enum crosses it. Confirmed against the native enum members on both sides (iOS: allNonEssentials/analytics/identifiedAnalytics/campaigns/personalization/thirdPartyIntegrations; Android: same set under io.purchasely.ext.PLYDataProcessingPurpose).
• Double-convention tolerance added (iOS mapPurposesFromStrings:, Android mapPurposesFromReadableArray): normalize to lowercase, _→-, and singularize third-party-integrations→third-party-integration, so both the kebab and the SCREAMING_SNAKE plural conventions resolve to the same native purpose. Unknown strings are silently ignored (never forwarded). All 6 purposes covered on both platforms.
• Locked in with a JUnit test (revokeDataProcessingConsent accepts both kebab-case and SCREAMING_SNAKE_CASE wire strings).

Known issues (out of scope, distinct bug)

• iOS builder backgroundColor / progressColor are never wired. The JS builder forwards them in the payload and Android consumes them, but iOS applyPresentationDisplayOptions only reads displayCloseButton / displayBackButton — the two color options are silently dropped on iOS. Pre-existing; should be fixed separately.

Tests

• Jest: 221/221 pass (yarn test). Audit test additions ported (Étape 0).
• Typecheck: 0 errors (yarn typecheck).
• Lint: passes with an explicit config — eslint --no-eslintrc -c .eslintrc.js packages/purchasely/src reports 0 errors. The root yarn lint script fails only in the nested-worktree setup (two .eslintrc.js in the cascade resolve @typescript-eslint from two node_modules); this is a pre-existing environment issue reproducible on the base tree, not a code regression.
• Native tests (iOS XCTest / Android JUnit): not executed (require the example app context). The modified native test files were verified syntactically consistent with the code changes (removed/added constants match the bridge implementations).

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR is a cross-platform parity audit remediation for the v6 React Native SDK bridge. It closes a large set of divergences found between the TypeScript surface, the iOS Objective-C bridge, and the Android Kotlin bridge against the pinned native SDKs (6.0.0-rc.3).

• Removes v5 residue (runningModeTransactionOnly, runningModePaywallObserver, startWithAPIKey, onesignalPlayerId, RCTConvert_PurchaselyRN.m), adds new APIs (closeAllScreens, getBuiltInAttributes/getBuiltInAttribute, userLogout(clearUserAttributes)), and wires the full v6 display path (displayWithTransition:completion:) on iOS in place of the legacy showController:type: call.
• Expands GDPR purpose normalization to accept both kebab-case singular and SCREAMING_SNAKE_CASE plural conventions on both platforms, adds rc.4 hardening for Android's upcoming DistributionType string plan types via normalizePlan, and fixes the hasIntroductoryPrice always-boolean contract on iOS.

Confidence Score: 3/5

The TypeScript, Android Kotlin, and enum-cleanup changes are solid and well-tested. The iOS display path refactoring is the riskiest change: removing the nil-controller guard trades explicit error propagation for an assumption about the v6 SDK completion contract not covered by native XCTest.

The iOS displayPresentation completion block now sets presentedPresentationViewController = presentation.controller and emits onPresented without checking for a nil controller. The old code triggered emitDismissed(err) on nil to keep the JS lifecycle consistent. The new path relies on displayWithTransition:completion: never calling the completion with a nil controller — reasonable for rc.3, but without native XCTest coverage a silent regression in a future SDK bump could go undetected. The mock runningModeFull discrepancy (3 vs. 4) also means new startBuilder tests verify against the wrong wire value.

packages/purchasely/ios/PurchaselyRN.m (displayPresentation completion block, nil-controller path removal) and packages/purchasely/src/mocks/testUtils.ts (runningModeFull value discrepancy).

Important Files Changed

Filename	Overview
packages/purchasely/ios/PurchaselyRN.m	Major refactor: replaces preloadWithCompletion+showController with displayWithTransition:completion:, adds plyTransitionFromMap, removes nil-controller error guard, adds getBuiltInAttributes/Attribute, closeAllScreens, userLogout(BOOL), and fixes GDPR purpose normalization. The nil-controller removal is the main point of concern.
packages/purchasely/android/src/main/java/com/reactnativepurchasely/PurchaselyModule.kt	Adds OneSignal attrs, fixes runningMode default (unknown→Observer instead of Full), no-op signPromotionalOffer, getBuiltInAttributes/Attribute, closeAllScreens, userLogout(Boolean), GDPR purpose normalization widening. Changes are clean and mirror the iOS bridge.
packages/purchasely/src/presentationTypes.ts	Adds normalizePlanType and normalizePlan for rc.4 forward-compat string plan types. Unknown strings are returned unchanged rather than nulled — intentional but means type: string leaks through the PlanType-typed field at runtime without a console warning.
packages/purchasely/src/index.ts	Removes getConstants public export, adds closeAllScreens/getBuiltInAttributes/getBuiltInAttribute, userLogout(clearUserAttributes=true), changes barrel export to export type * from presentationTypes. All changes are well-aligned with the PR intent.
packages/purchasely/src/enums.ts	Removes ONESIGNAL_PLAYER_ID, adds ONESIGNAL_EXTERNAL_ID/ONESIGNAL_USER_ID; removes v5 running modes; adds SubscriptionSource.NONE. All changes match native bridges exactly.
packages/purchasely/src/tests/presentation.integration.test.ts	Substantial new test coverage: builder chain modifiers, onLoaded callback, hot-swap handlers, interceptor outcomes, rc.4 plan-type normalization. All tests are well-structured and cover the changed behaviour.
packages/purchasely/src/tests/startBuilder.test.ts	New file covering PurchaselyBuilder chain modifiers. Tests verify against mockConstants.runningModeFull (value 3) rather than the actual native wire value (4), a pre-existing mock discrepancy in testUtils.ts.
packages/purchasely/src/mocks/testUtils.ts	Updated mock constants: removes v5 running modes, adds sourceNone, oneSignalExternalId/userId, getBuiltInAttributes/Attribute and closeAllScreens mocks. runningModeFull remains 3 (pre-existing discrepancy vs. native value of 4).

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant JS as JS (presentation.ts)
    participant iOS as iOS Bridge (PurchaselyRN.m)
    participant SDK as Native SDK (rc.3)

    JS->>iOS: displayPresentation(requestId, transition, payload)
    iOS->>iOS: plyTransitionFromMap(transition)
    iOS->>SDK: [request displayWithTransition:nativeTransition completion:onFetchCompletion]
    SDK-->>iOS: onFetchCompletion(presentation)
    iOS->>iOS: "kPresentationsByRequest[requestId] = presentation"
    iOS->>iOS: "presentedPresentationViewController = presentation.controller"
    iOS->>JS: emit PRESENTED
    Note over iOS: OLD: nil controller → emitDismissed(err)<br/>NEW: nil controller silent (guard removed)
    SDK-->>iOS: onDismissed(outcome)
    iOS->>JS: emit DISMISSED
    JS->>JS: normalizePlan(event.plan)
    JS-->>JS: display() resolves with PLYPresentationOutcome

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant JS as JS (presentation.ts)
    participant iOS as iOS Bridge (PurchaselyRN.m)
    participant SDK as Native SDK (rc.3)

    JS->>iOS: displayPresentation(requestId, transition, payload)
    iOS->>iOS: plyTransitionFromMap(transition)
    iOS->>SDK: [request displayWithTransition:nativeTransition completion:onFetchCompletion]
    SDK-->>iOS: onFetchCompletion(presentation)
    iOS->>iOS: "kPresentationsByRequest[requestId] = presentation"
    iOS->>iOS: "presentedPresentationViewController = presentation.controller"
    iOS->>JS: emit PRESENTED
    Note over iOS: OLD: nil controller → emitDismissed(err)<br/>NEW: nil controller silent (guard removed)
    SDK-->>iOS: onDismissed(outcome)
    iOS->>JS: emit DISMISSED
    JS->>JS: normalizePlan(event.plan)
    JS-->>JS: display() resolves with PLYPresentationOutcome

Loading

Comments Outside Diff (1)

1. packages/purchasely/ios/PurchaselyRN.m, line 1442-1460 (link)

   Nil-controller error path silently removed

   The old onFetchCompletion block explicitly checked presentation.controller == nil, then called emitDismissed(err) — keeping the JS lifecycle in a consistent state (dismiss event paired with every presented event). That guard was removed with the reasoning that displayWithTransition:completion: guarantees the view is already handed to UIKit before the callback fires.

   That assumption is valid for the current rc.3 SDK, but if any future SDK version calls the completion in an error scenario with a nil controller (e.g., a presentation that fails post-fetch but before display), the JS side will receive onPresented with no matching onDismissed and presentedPresentationViewController will silently be set to nil — which would break a subsequent request.close() call on iOS that relies on this property. Consider adding a lightweight guard (if (presentation.controller == nil) { emitDismissed(someError); return; }) after setting presentedPresentationViewController to preserve the invariant without blocking current behaviour.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/purchasely/ios/PurchaselyRN.m
   Line: 1442-1460
   
   Comment:
   **Nil-controller error path silently removed**
   
   The old `onFetchCompletion` block explicitly checked `presentation.controller == nil`, then called `emitDismissed(err)` — keeping the JS lifecycle in a consistent state (dismiss event paired with every presented event). That guard was removed with the reasoning that `displayWithTransition:completion:` guarantees the view is already handed to UIKit before the callback fires.
   
   That assumption is valid for the current rc.3 SDK, but if any future SDK version calls the completion in an error scenario with a nil controller (e.g., a presentation that fails post-fetch but before display), the JS side will receive `onPresented` with no matching `onDismissed` and `presentedPresentationViewController` will silently be set to nil — which would break a subsequent `request.close()` call on iOS that relies on this property. Consider adding a lightweight guard (`if (presentation.controller == nil) { emitDismissed(someError); return; }`) after setting `presentedPresentationViewController` to preserve the invariant without blocking current behaviour.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

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

---

### Issue 1 of 3
packages/purchasely/ios/PurchaselyRN.m:1442-1460
**Nil-controller error path silently removed**

The old `onFetchCompletion` block explicitly checked `presentation.controller == nil`, then called `emitDismissed(err)` — keeping the JS lifecycle in a consistent state (dismiss event paired with every presented event). That guard was removed with the reasoning that `displayWithTransition:completion:` guarantees the view is already handed to UIKit before the callback fires.

That assumption is valid for the current rc.3 SDK, but if any future SDK version calls the completion in an error scenario with a nil controller (e.g., a presentation that fails post-fetch but before display), the JS side will receive `onPresented` with no matching `onDismissed` and `presentedPresentationViewController` will silently be set to nil — which would break a subsequent `request.close()` call on iOS that relies on this property. Consider adding a lightweight guard (`if (presentation.controller == nil) { emitDismissed(someError); return; }`) after setting `presentedPresentationViewController` to preserve the invariant without blocking current behaviour.

### Issue 2 of 3
packages/purchasely/src/presentationTypes.ts:275-305
**Unknown string `type` passes through silently as a non-`PlanType` value**

`normalizePlanType` returns `null` for any string not in `PLAN_TYPE_NAME_MAP`, and `normalizePlan` then returns the raw plan object unchanged — so `plan.type` remains a `string` at runtime while TypeScript thinks it's a `PlanType` number. Any consumer that pattern-matches on `plan.type === PlanType.PLAN_TYPE_AUTO_RENEWING_SUBSCRIPTION` would silently fail to match, with no indication of why.

This is the documented intent ("left as-is rather than silently dropped"), but without a `console.warn` for unrecognized strings, debugging this on a future Android rc.4+ device where a new `DistributionType` member appears would be hard. A one-line `console.warn('[Purchasely] normalizePlanType: unrecognized type string', value)` before returning `null` would preserve the pass-through behaviour while making the gap visible.

### Issue 3 of 3
packages/purchasely/src/__mocks__/testUtils.ts:47-48
**`runningModeFull` mock value (3) doesn't match the real native wire value (4)**

Both the iOS bridge (`PLYRNRunningModeFull = 4`) and the Android bridge (`const runningModeFull = 4`) export ordinal `4` for Full mode. The mock has `runningModeFull: 3`, which means all JS unit tests that check `RunningMode.FULL` (including the new `startBuilder.test.ts`) are verifying against an incorrect wire value. A production device would send `4` to the native `start()`, not `3`. If a regression ever sent `3` instead of `4`, the tests would pass but the native bridge's `else → Observer` fallback would silently activate.

_{Reviews (1): Last reviewed commit: "feat: tolerate Android's upcoming Distri..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR remediates v6 cross-platform parity gaps between the React Native TypeScript surface and the pinned iOS/Android native SDKs (6.0.0-rc.3), updating bridge behavior, public types/enums, and documentation while expanding test coverage to lock in the corrected contract.

Changes:

• Aligns iOS/Android bridge behavior and constants (e.g., transitions via PLYTransition, running mode fallback, new sourceNone, OneSignal attribute keys, closeAllScreens, built-in attribute reads).
• Hardens JS-side plan parsing to tolerate upcoming Android plan.type string values via normalizePlanType / normalizePlan.
• Updates v6 migration documentation and adds/extends Jest + native unit tests to cover the new/changed surface.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/purchasely/src/types.ts	Reactivates Android-only subscription revenue/duration fields as optional + documents platform asymmetry.
packages/purchasely/src/presentationTypes.ts	Adds internal plan-type normalization helpers and clarifies internal-only exports.
packages/purchasely/src/presentation.ts	Normalizes outcome.plan to tolerate upcoming Android string type values.
packages/purchasely/src/interfaces.ts	Updates Constants keys (OneSignal changes; removes v5 running mode constants).
packages/purchasely/src/interceptor.ts	Normalizes intercepted purchase payload plan typing for rc.4 hardening.
packages/purchasely/src/index.ts	Removes public getConstants, adds APIs (closeAllScreens, built-in attribute reads, logout param), and adjusts barrel exports.
packages/purchasely/src/enums.ts	Adds SubscriptionSource.NONE and replaces removed OneSignal constant with new OneSignal keys.
packages/purchasely/src/tests/types.test.ts	Adds tests for optional Android-only subscription fields + plan normalization helpers.
packages/purchasely/src/tests/startBuilder.test.ts	New direct unit tests for PurchaselyBuilder chain modifiers and start argument shaping.
packages/purchasely/src/tests/presentation.integration.test.ts	Expands integration coverage for builder options, callbacks, interceptors, and plan normalization.
packages/purchasely/src/tests/index.test.ts	Updates public API expectations (no getConstants, no barrel export for internal helper, new APIs).
packages/purchasely/src/tests/enums.test.ts	Updates enum expectations for SubscriptionSource.NONE and OneSignal enum replacement.
packages/purchasely/src/mocks/testUtils.ts	Updates mocked constants and native module mocks for new/removed constants and APIs.
packages/purchasely/ios/PurchaselyTests/PurchaselyRNTests.m	Updates iOS native tests for constants changes (sourceNone, OneSignal keys, running modes).
packages/purchasely/ios/PurchaselyRN.m	Implements transition parsing + display via displayWithTransition, adds APIs, updates constants, and widens GDPR purpose mapping acceptance.
packages/purchasely/ios/Purchasely.xcodeproj/project.pbxproj	Removes deleted RCTConvert_PurchaselyRN.m references from Xcode project.
packages/purchasely/ios/Classes/RCTConvert_PurchaselyRN.m	Deletes dead legacy RCTConvert file.
packages/purchasely/ios/Classes/Hybrid/PLYPlan+Hybrid.m	Ensures hasIntroductoryPrice is always emitted as a boolean to match TS contract.
packages/purchasely/android/src/test/java/com/reactnativepurchasely/PurchaselyModuleTest.kt	Updates Android native unit tests for constants changes and GDPR purpose mapping tolerance.
packages/purchasely/android/src/main/java/com/reactnativepurchasely/PurchaselyModule.kt	Aligns running mode fallback, adds APIs, changes Android promo signing to no-op success, and widens GDPR purpose mapping acceptance.
MIGRATION-v6.md	Documents breaking changes, new APIs, iOS transition dimension ceiling, and rc.4 plan.type forward compatibility.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.