Support fetching eligible win-back offers for a product

[fire-at-will]

Description

This PR adds the ability for developers to fetch the win-back offers that a subscriber is eligible for on a given product.

New APIs

All API additions in this PR are marked as internal for now. They will be made public once we introduce the ability to redeem a win-back offer in a future PR.

The PR introduces a new WinBackOffer type to represent a win-back offer:

@available(iOS 18.0, macOS 15.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
@objc(RCWinBackOffer)
internal final class WinBackOffer: NSObject, Sendable {

    /// The ``StoreProductDiscount`` in this offer.
    @objc internal let discount: StoreProductDiscount

    init(discount: StoreProductDiscount) {
        self.discount = discount
    }

}

Additionally, the PR introduces two new functions on the Purchases singleton for fetching the win-back offers for a given product that a subscriber is eligible for. These functions are not available when the ENABLE_CUSTOM_ENTITLEMENT_COMPUTATION compiler flag is enabled.

@available(iOS 18.0, macOS 15.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
 func eligibleWinBackOffers(
     forProduct product: StoreProduct
 ) async throws -> [WinBackOffer]

@available(iOS 18.0, macOS 15.0, tvOS 18.0, watchOS 11.0, visionOS 2.0, *)
 func eligibleWinBackOffers(
     forProduct product: StoreProduct,
     completion: @escaping @Sendable (Result<[WinBackOffer], PublicError>) -> Void
 )

Note

Since we're keeping this functionality as internal for now, this PR is marked with the pr:other tag so that it doesn't get marked as a new feature in the auto-generated changelogs.

[fire-at-will]

completion is marked as @Sendable to avoid warnings below when we dispatch the completion handler on the main actor

[fire-at-will]

added visionOS check

[MarkVillacampa]

This is looking really really good!! Great work!

[MarkVillacampa]

Technically, you can only be subscribed to a product once, so there must be at most 1 renewalInfo instance that is NOT a family shared one. So maybe we could simplify the logic of the rest of the function by just finding the first status transaction with transaction.ownershipType == .purchased, like Apple does in their sample code:

let purchasedStatus = statuses.first {
    $0.transaction.unsafePayloadValue.ownershipType == .purchased
}

https://developer.apple.com/videos/play/wwdc2024/10110/

[fire-at-will]

Yeah, this is where I thought I might be able to do a bit better than Apple's example in the event where there were multiple renewalInfos.

Is there any chance that there would be more than one renewalInfo for a single product ID if a user subscribes, churns, and then re-subscribed? I'm not seeing many details about this in the docs.

I've implemented this change here and will merge it in to this PR if we think we're safe in the case I mentioned above. 👍

[MarkVillacampa]

The documentation does not explicitly state that, but it says:

The array can have more than one subscription status if your subscription supports Family Sharing.

Which I'd argue highly suggest the array can normally only have one status (the purchased one) and potentially more only if it supports family sharing.

Given that, plus Apple's sample code makes me very confident there will always be just one status with ownershipType == .purchased

https://developer.apple.com/documentation/storekit/product/subscriptioninfo/3822296-status

[MarkVillacampa]

By using just one status above, we can get rid of all the deduplication logic here.