Add DeferredPurchasesListener, deprecate EntitlementsUpdateListener

[NickSxti]

Summary

• Introduce DeferredPurchasesListener interface with onDeferredPurchaseCompleted method for specifically handling deferred (pending) purchase completions
• Deprecate EntitlementsUpdateListener (still works for backward compat — fires for ALL entitlement updates)
• Add JS-layer correlation filtering: track product IDs from purchaseWithResult when status is PENDING, match against onEntitlementsUpdated events to detect deferred purchase completions
• Both listeners coexist: old fires for all updates, new fires only for tracked deferred purchases
• Native side unchanged — single onEntitlementsUpdated event, filtering is JS-only
• 12 TDD tests covering all edge cases

Architecture

purchaseWithResult(status: PENDING)
  → pendingPurchaseProductIds.add(productId)

onEntitlementsUpdated (native event)
  → entitlementsUpdateListener?.onEntitlementsUpdated(entitlements)  // always fires
  → if hasPendingPurchaseCompleted(entitlements):
      deferredPurchasesListener?.onDeferredPurchaseCompleted(entitlements)  // only for deferred
      pendingPurchaseProductIds.delete(productId)  // prevent double-fire

New public API

• DeferredPurchasesListener interface (exported from index)
• QonversionConfigBuilder.setDeferredPurchasesListener(listener)
• QonversionApi.setDeferredPurchasesListener(listener) (runtime setter)

Backward compatibility

• Existing setEntitlementsUpdateListener still works (marked @deprecated)
• Old listener set via config constructor still works
• No changes to native iOS/Android modules

Test plan

• 12 unit tests (TDD: Red → Green) covering:
  • Pending purchase tracking from purchaseWithResult
  • Filtering: fires only for tracked pending products
  • No-fire when no pending purchases exist
  • Cleanup after deferred completion (no double-fire)
  • Success purchases are NOT tracked
  • Listener replacement
  • Old listener backward compat (fires for all updates)
  • Both listeners coexist independently
  • Single native event subscription (no duplication)
• TypeScript compilation passes
• iOS example app builds

Known limitations

• Pending purchase tracking is in-memory — lost on app restart (acceptable: sandwich will add native filtering later)
• Only purchaseWithResult tracks pending status (deprecated purchase/purchaseProduct don't return PurchaseResult)

🤖 Generated with Claude Code

[NickSxti]

Self-Review

What this PR does now

• New DeferredPurchasesListener interface with onDeferredPurchaseCompleted
• Deprecated EntitlementsUpdateListener (JSDoc @deprecated)
• Two independent listener slots — each subscribed to its own native event
• Native bridges (iOS/Android) emit both onEntitlementsUpdated and onDeferredPurchaseCompleted from the same delegate callback
• 11 unit tests

What this PR does NOT do

No actual deferred purchase filtering yet. Both events currently fire from the same source (qonversionDidReceiveUpdatedEntitlements). A customer setting setDeferredPurchasesListener will receive ALL entitlement updates — not just deferred ones.

True filtering requires one of:

1. QonversionSandwich change (preferred): add qonversionDidCompleteDeferredPurchase protocol method that only fires when a pending transaction completes
2. JS-layer correlation heuristic: track product IDs from purchaseWithResult calls that return status: PENDING, then match against subsequent entitlement updates. Limitations: lost on app restart, possible false positives.

Architecture decision: separate slots, not adapter

The initial commit used an adapter pattern (setEntitlementsUpdateListener → wraps → setDeferredPurchasesListener). This was reverted in the second commit because it had a future-breaking bug: when sandwich adds real filtering, old customers using setEntitlementsUpdateListener would silently lose non-deferred updates.

Current architecture:

Method	Native event	Fires for
setEntitlementsUpdateListener (deprecated)	onEntitlementsUpdated	All updates (always)
setDeferredPurchasesListener (new)	onDeferredPurchaseCompleted	All updates now → deferred only after sandwich change

Both can coexist. Old code is future-proof.

Remaining work

• Build & test Android (no JDK 17+ locally — CI will verify)
• Sandwich SDK: add dedicated deferred purchase callback
• Wire onDeferredPurchaseCompleted exclusively to new sandwich callback
• Remove onDeferredPurchaseCompleted emission from general entitlements delegate

[NickSxti]

LEVER Self-Review

Logic

✅ Correlation filtering correctly tracks pendingPurchaseProductIds from purchaseWithResult when isPending is true, and matches against entitlement.productId + entitlement.isActive in updates.

⚠️ In-memory tracking limitation: If the app is killed between a pending purchase and the entitlement update, the deferred listener won't fire. This is acceptable because:

1. The sandwich layer will add native-side filtering in a future version
2. The entitlementsUpdateListener (deprecated) still fires for ALL updates as a fallback

⚠️ Only purchaseWithResult tracks pending: The deprecated purchase() and purchaseProduct() methods don't return PurchaseResult, so they can't detect pending status. Customers using old purchase methods won't get deferred callbacks — they should use purchaseWithResult which is the recommended API.

Edge cases

✅ No double-fire: pendingPurchaseProductIds.delete() removes tracking after first match
✅ Success purchases not tracked (only PENDING triggers tracking)
✅ Unrelated entitlement updates don't trigger deferred listener
✅ Listener replacement works (old listener stops receiving, new one takes over)
✅ Single event subscription even when both listeners are set

Risks

• Low: If multiple products are pending simultaneously, hasPendingPurchaseCompleted returns true on first match, so a single entitlement update containing multiple pending products will only fire the deferred listener once. This seems correct — one callback per update event.

Backward compatibility

✅ Old EntitlementsUpdateListener set via config or setEntitlementsUpdateListener() still fires for ALL entitlement updates
✅ No native code changes — native modules only emit onEntitlementsUpdated
✅ onDeferredPurchaseCompleted event kept in TurboModule spec as reserved for future sandwich support

Verification

✅ 12 TDD tests pass (Red → Green methodology)
✅ TypeScript compiles cleanly (tsc --noEmit)
✅ iOS example app builds

[NickSxti]

Self-review notes after rework to native events:

Architecture change - Replaced JS-layer pendingPurchaseProductIds filtering with direct native onDeferredPurchaseCompleted event from Sandwich SDK. This is more reliable (no in-memory state lost on app restart) and consistent with how the native SDKs work.

Breaking change in DeferredPurchasesListener interface - onDeferredPurchaseCompleted now receives a DeferredTransaction object (with productId, transactionId, originalTransactionId, type, value, currency) instead of Map<string, Entitlement>. Since this was not yet released, this is fine.

Native module changes:

• iOS: Added qonversionDidCompleteDeferredPurchase to QonversionEventDelegate protocol and QonversionEventHandler, emits via emitOnDeferredPurchaseCompleted in RNQonversion.mm
• Android: Added onDeferredPurchaseCompleted override in QonversionModule.kt, emits via emitOnDeferredPurchaseCompleted

Event subscriptions are now independent - setDeferredPurchasesListener subscribes to onDeferredPurchaseCompleted (not onEntitlementsUpdated), so each listener has its own native event source.

10 tests passing covering: native event subscription, DeferredTransaction payload, listener replacement, independent event subscriptions, coexistence with EntitlementsUpdateListener.

Depends on: Sandwich SDK PR qonversion/sandwich-sdk#302