feat: migrate to Purchasely 6.0 native SDK (6.0.0-rc.1)

[chouaibMo]

Supersedes #56, which GitHub auto-closed when this branch was renamed from release/6.0.0-rc.1 to feat/migration-v6.

Summary

Migrates the Purchasely Cordova plugin to the Purchasely 6.0 native SDKs (iOS Purchasely 6.0.0-rc.2, Android io.purchasely:core 6.0.0-rc.2), mirroring the Flutter migration in Purchasely-Flutter#120. Wrapper version → 6.0.0-rc.1.

This is a migration, not a rewrite — the breaking surfaces are SDK start, presentation display mode, and the action-interceptor result; the rest stays source-compatible (with deprecated aliases for renamed methods).

What changed

JavaScript (purchasely/www/Purchasely.js)

• start(apiKey, …) → start(options, success, error) config object
• RunningMode values are now name strings (observer/full) — the native iOS/Android enums use different raw values, so the bridge maps by name; default is now observer. paywallObserver kept as a deprecated alias
• synchronize(success, error) now reports completion (was fire-and-forget)
• Deeplink: allowDeeplink / handleDeeplink (+ new allowCampaigns); old readyToOpenDeeplink / isDeeplinkHandled kept as deprecated aliases
• setDefaultPresentationDismissHandler (old …ResultHandler kept as alias)
• Presentation: isFullscreen bool → display-mode string (bool still normalized); add backPresentation(); removed presentSubscriptions, presentProduct/PlanWithIdentifier, show/hidePresentation (no v6 primitive)
• Interceptor: onProcessAction(InterceptResult) replaces the bool (legacy bool mapped); PaywallAction kept + PresentationAction alias
• New constants: InterceptResult, PresentationType, CloseReason, TransitionType, DimensionType, Store, StorekitVersion
• Unit tests (__tests__/Purchasely.test.js) updated in lockstep — 80 tests pass

iOS (purchasely/src/ios/CDVPurchasely.m, Objective-C)

• Migrated to the v6 @objc API (verified against the framework's generated Purchasely-Swift.h) — no Swift rewrite/shim needed: apiKey builder → startWithInitialized:; PLYPresentationBuilder.forPlacementId:/forScreenId: → build → preloadWithCompletion: / displayFrom:transitionType:; interceptAction:handler: → PLYInterceptResult; setDefaultPresentationDismissHandler:; allowDeeplink:/handleDeeplink:/allowCampaigns:; closeAllScreens; backPresentation
• PLYPresentationOutcome serialization (result int, closeReason, error, presentation)
• Fixed v6 type changes: PLYAttribute is now an enum (was used as a pointer); declared PLYEventDelegate/PLYUserAttributeDelegate conformance on the implementing categories; guarded user-attribute callbacks (v6 delegate setters are _Nonnull)

Android (purchasely/src/android/PurchaselyPlugin.kt, Kotlin)

• Migrated to io.purchasely:core 6.0.0-rc.2: options-dict start; PLYPresentationBase.builder().build().preload() → loaded.display(activity, transition){ outcome }; interceptAction(…) → PLYInterceptResult; dismiss handler; deeplink renames; synchronize success/error; CoroutineScope for suspend queries
• Removed PLYProductActivity / PLYSubscriptionsActivity (+ layouts/themes, plugin.xml source-file/AndroidManifest entries) — dropped in native 6.0

CI / E2E

• ci.yml / publish.yml aligned with Flutter (action bumps, workflow_dispatch, concurrency); prerelease tags publish under the npm next dist-tag, stable under latest
• New e2e-android.yml / e2e-ios.yml + an Appium + WebdriverIO project (purchasely/example/e2e/) mirroring the Flutter E2E_TEST_INDEX suite: a deterministic WEBVIEW-context bridge suite (hard gate) and a best-effort dismiss suite; workflow_dispatch + nightly + scoped PRs

Docs

• MIGRATION-v6.md (new), VERSIONS.md row 6.0.0-rc.1 → 6.0.0-rc.2 / 6.0.0-rc.2, READMEs, CLAUDE.md, example app updated to the 6.0 API

Verification

• ✅ iOS example builds against Purchasely 6.0.0-rc.2 (BUILD SUCCEEDED; only a benign setThemeMode deprecation)
• ✅ Android example builds app-debug.apk against io.purchasely:core 6.0.0-rc.2, and runs on an API 34 emulator — SDK initializes (sdkVersion=6.0.0-rc.2), events flow (PRESENTATION_LOADED/VIEWED, PURCHASE_TAPPED), no crash
• ✅ 80/80 JS unit tests pass; version-consistency check passes

Notes for reviewers

• RC: mark the GitHub release pre-release; npm publish auto-selects the next dist-tag for X.Y.Z-* tags
• E2E: the deterministic bridge suite hard-gates; device suites are best-effort (dispatch/nightly), same policy as Flutter. To make device suites pass in CI, a placement (default ONBOARDING) must exist for com.purchasely.demo on the example API key's backend — they need one real-runner shakeout
• Known limitations (documented as TODO(v6-verify)): drawer/popin transition dimensions default (JS sends only a display-mode string); a single interceptor completion is stashed per round-trip

See VERSIONS.md and the native release notes: iOS 6.0.0-rc.2, Android 6.0.0-rc.2.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR migrates the Cordova plugin to the Purchasely 6.0 native SDKs. The main changes are:

• Options-based SDK startup in JavaScript and native bridges.
• New v6 presentation, deeplink, dismiss, and interceptor APIs.
• Android and iOS native bridge updates for Purchasely 6.0.
• New E2E workflows and Appium/WebdriverIO example tests.
• Updated migration docs, package versions, and native dependencies.

Confidence Score: 4/5

The migrated presentation bridge needs fixes before merging.

• Android exposes a synthetic fetched-presentation id through the public id field.
• iOS can miss the dismiss callback for fetched presentations if v6 lifecycle handlers must be registered before preload.
• Android still has a shared callback slot for overlapping presentation calls.

purchasely/src/android/PurchaselyPlugin.kt, purchasely/src/ios/CDVPurchasely.m

Important Files Changed

Filename	Overview
purchasely/www/Purchasely.js	Updates the public JavaScript API for v6 startup options, display modes, deeplink methods, synchronization callbacks, and per-action interceptors.
purchasely/src/android/PurchaselyPlugin.kt	Migrates the Android bridge to v6 SDK calls, coroutine-based queries, loaded presentation display, and per-action interceptor completion.
purchasely/src/ios/CDVPurchasely.m	Migrates the iOS bridge to v6 builder, display, dismiss, deeplink, and interceptor APIs.
purchasely/plugin.xml	Updates native SDK versions and removes old Android presentation activity resources from plugin installation.
.github/workflows/ci.yml	Updates CI triggers, concurrency, Node version, and reusable action versions.
.github/workflows/e2e-android.yml	Adds Android Appium/WebdriverIO E2E coverage against an emulator and real backend.
.github/workflows/e2e-ios.yml	Adds iOS Appium/WebdriverIO E2E coverage against a simulator and real backend.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
  participant App as Cordova app
  participant JS as Purchasely.js
  participant Native as Native bridge
  participant SDK as Purchasely SDK
  App->>JS: start(options)
  JS->>Native: exec start
  Native->>SDK: build/start v6 SDK
  App->>JS: fetchPresentation(...)
  JS->>Native: exec fetchPresentation
  Native->>SDK: build + preload
  SDK-->>Native: loaded presentation
  Native-->>JS: presentation object
  App->>JS: presentPresentation(presentation, mode)
  JS->>Native: exec presentPresentation
  Native->>SDK: display presentation
  SDK-->>Native: outcome on dismiss/purchase
  Native-->>JS: Cordova callback

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 App as Cordova app
  participant JS as Purchasely.js
  participant Native as Native bridge
  participant SDK as Purchasely SDK
  App->>JS: start(options)
  JS->>Native: exec start
  Native->>SDK: build/start v6 SDK
  App->>JS: fetchPresentation(...)
  JS->>Native: exec fetchPresentation
  Native->>SDK: build + preload
  SDK-->>Native: loaded presentation
  Native-->>JS: presentation object
  App->>JS: presentPresentation(presentation, mode)
  JS->>Native: exec presentPresentation
  Native->>SDK: display presentation
  SDK-->>Native: outcome on dismiss/purchase
  Native-->>JS: Cordova callback

Loading

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
purchasely/src/android/PurchaselyPlugin.kt:570
**Synthetic Presentation Id Escapes**

When Android returns a fetched presentation, this replaces the native presentation id with a local `ply_fetch_...` handle. iOS returns the real id in the same `id` field, so app code that logs, stores, or passes `presentation.id` to another presentation API works on iOS but receives an Android-only handle that cannot identify the presentation.

### Issue 2 of 3
purchasely/src/ios/CDVPurchasely.m:1087
**Late Dismiss Handler Assignment**

For the `fetchPresentation` then `presentPresentation` flow, the dismiss handler is attached only after the presentation has already been built and preloaded. If the v6 presentation object captures lifecycle handlers during the builder/request phase, the paywall can display and dismiss without ever resolving the Cordova success callback.

### Issue 3 of 3
purchasely/src/android/PurchaselyPlugin.kt:594
**Shared Presentation Callback Slot**

Every Android presentation path writes to the same static `purchaseCallback`. If two presentations are started before the first outcome arrives, the later call overwrites the earlier callback, so the first caller never receives its dismiss or purchase result and the outcome can be delivered to the wrong Cordova command.

_{Reviews (1): Last reviewed commit: "refactor(api)!: remove deprecated v5 ali..." | Re-trigger Greptile}

[greptile-apps]

Synthetic Presentation Id Escapes

When Android returns a fetched presentation, this replaces the native presentation id with a local ply_fetch_... handle. iOS returns the real id in the same id field, so app code that logs, stores, or passes presentation.id to another presentation API works on iOS but receives an Android-only handle that cannot identify the presentation.

Context Used: CLAUDE.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: purchasely/src/android/PurchaselyPlugin.kt
Line: 570

Comment:
**Synthetic Presentation Id Escapes**

When Android returns a fetched presentation, this replaces the native presentation id with a local `ply_fetch_...` handle. iOS returns the real id in the same `id` field, so app code that logs, stores, or passes `presentation.id` to another presentation API works on iOS but receives an Android-only handle that cannot identify the presentation.

**Context Used:** CLAUDE.md ([source](https://app.greptile.com/purchasely/github/purchasely/purchasely-cordova/-/custom-context?memory=5b6f5482-f899-484f-8104-ac25efc0799e))

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Late Dismiss Handler Assignment

For the fetchPresentation then presentPresentation flow, the dismiss handler is attached only after the presentation has already been built and preloaded. If the v6 presentation object captures lifecycle handlers during the builder/request phase, the paywall can display and dismiss without ever resolving the Cordova success callback.

Context Used: CLAUDE.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: purchasely/src/ios/CDVPurchasely.m
Line: 1087

Comment:
**Late Dismiss Handler Assignment**

For the `fetchPresentation` then `presentPresentation` flow, the dismiss handler is attached only after the presentation has already been built and preloaded. If the v6 presentation object captures lifecycle handlers during the builder/request phase, the paywall can display and dismiss without ever resolving the Cordova success callback.

**Context Used:** CLAUDE.md ([source](https://app.greptile.com/purchasely/github/purchasely/purchasely-cordova/-/custom-context?memory=5b6f5482-f899-484f-8104-ac25efc0799e))

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Shared Presentation Callback Slot

Every Android presentation path writes to the same static purchaseCallback. If two presentations are started before the first outcome arrives, the later call overwrites the earlier callback, so the first caller never receives its dismiss or purchase result and the outcome can be delivered to the wrong Cordova command.

Context Used: CLAUDE.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: purchasely/src/android/PurchaselyPlugin.kt
Line: 594

Comment:
**Shared Presentation Callback Slot**

Every Android presentation path writes to the same static `purchaseCallback`. If two presentations are started before the first outcome arrives, the later call overwrites the earlier callback, so the first caller never receives its dismiss or purchase result and the outcome can be delivered to the wrong Cordova command.

**Context Used:** CLAUDE.md ([source](https://app.greptile.com/purchasely/github/purchasely/purchasely-cordova/-/custom-context?memory=5b6f5482-f899-484f-8104-ac25efc0799e))

How can I resolve this? If you propose a fix, please make it concise.