Support Fetching and Redeeming Win-Back Offers on Custom Paywall

[fire-at-will]

Description

This PR introduces four new functions to the Capacitor SDK that enables developers to fetch & redeem win-back offers on their custom paywalls. These functions are only supported on on iOS 18.0+ and require StoreKit 2 to be used.

Fetching eligible win-back offers

getEligibleWinBackOffersForProduct(
  options: GetEligibleWinBackOffersForProductOptions,
): Promise<{
  eligibleWinBackOffers: PurchasesWinBackOffer[]; 
}>;

getEligibleWinBackOffersForPackage(
  options: GetEligibleWinBackOffersForPackageOptions,
): Promise<{
  eligibleWinBackOffers: PurchasesWinBackOffer[];
}>;

Redeeming win-back offers

purchaseProductWithWinBackOffer(
  options: PurchaseProductWithWinBackOfferOptions,
 ): Promise<MakePurchaseResult | undefined>;

purchasePackageWithWinBackOffer(
  options: PurchasePackageWithWinBackOfferOptions,
): Promise<MakePurchaseResult | undefined>;

Each function throws an appropriate error if it is called on an unsupported platform, OS version, or StoreKit version.

Other Changes

The PurchaseTester app was updated with a new screen to support testing these flows

Testing

All flows were tested manually through the new screen in the PurchaseTester app.

[fire-at-will]

The function signature for fetching eligible winback offers in PHC is:

static func eligibleWinBackOffers(
     for productIdentifier: String,
     completion: @escaping ([[String: Any]]?, ErrorContainer?) -> Void
 )

Note the [[String: Any]]? in the callback - it returns an array of objects. This function allows us to parse that response type, since the normal getCompletionBlockHandler assumes a return type of [String: Any]?

[tonidero]

LGTM! Nicely done!

[tonidero]

Hmm right, we probably should use unavailable for more methods 😅 (not for this PR!)

[tonidero]

Thanks for doing the change!