Add Apple iOS 26 billing plan type support

[yusuftor]

Changes in this pull request

Adds support for Apple's iOS 26 billing plan types on annual subscriptions. Two Superwall Products that share an Apple product identifier — one configured for the up-front annual plan, one for the monthly-commitment plan — can now be merchandised together on a paywall.

• AppStoreProduct gains an optional BillingPlanType (.upFront / .monthly) decoded from the billingPlanType field on the store product payload. Legacy paywalls without the field decode unchanged.
• Paywall now exposes both appStoreProductIds (composite Product IDs, used for slot addressing) and a new appStoreProductIdentifiers (deduped Apple IDs, used to drive the StoreKit fetch).
• StoreKitManager fetches by Apple ID and builds a per-call productsByCompositeId map of StoreProduct clones, each carrying its own billingPlanType. Two clones can share an underlying SK2 product with independent billing plans.
• StoreProduct exposes billingPlanType and isBillingPlanAvailable, plus a copyForCompositeProduct helper.
• SK2StoreProduct routes price, period, and computed per-period prices through the matching Product.SubscriptionInfo.PricingTerm when a plan is configured, falling back to the existing single-price path otherwise.
• TransactionManager resolves purchases via the composite map first, falling back to the Apple-ID map.
• ProductPurchaserSK2 inserts .billingPlanType(...) into the SK2 purchase option set on iOS 26+ when a plan is configured.

Behaviour change

PaywallInfo.productIds now contains composite IDs (e.g. com.app.annual:MONTHLY) for Products that opt into a billing plan. The underlying Apple identifier is still reachable via the Product's type.appStore.id.

Server dependency

This PR is forward-compatible — it decodes the new billingPlanType field if present and falls back to nil otherwise. The corresponding server change in paywall-next (emitting billing_plan_type on productsV2 entries and composite sw_composite_product_ids) is not yet shipped. Until the server ships that, the new code paths stay dormant and existing paywalls behave exactly as before.

Checklist

• All unit tests pass.
• All UI tests pass.
• Demo project builds and runs on iOS.
• Demo project builds and runs on Mac Catalyst.
• Demo project builds and runs on visionOS.
• I added/updated tests or detailed why my change isn't tested.
• I added an entry to the `CHANGELOG.md` for any breaking changes, enhancements, or bug fixes.
• I have run `swiftlint` in the main directory and fixed any issues.
• I have updated the SDK documentation as well as the online docs.
• I have reviewed the contributing guide

🤖 Generated with Claude Code

Greptile Summary

This PR adds iOS 26 billing plan type support, allowing two Superwall Products sharing the same Apple product identifier to differ in their BillingPlanType (.upFront / .monthly) and be merchandised independently on a paywall.

• AppStoreProduct gains an optional BillingPlanType decoded from billingPlanType; SK2StoreProduct resolves the matching PricingTerms at init and caches price/period/intro-offer from it, gated behind #if compiler(>=6.3) / #available(iOS 26.4, *).
• StoreKitManager fetches by Apple ID and builds a per-call productsByCompositeId map of cloned StoreProduct instances, each carrying an independent billing plan; TransactionManager and AddPaywallProducts resolve lookups through this composite map first.
• ProductPurchaserSK2 inserts .billingPlanType(...) into the SK2 purchase-option set on iOS 26.4+ when a plan is active; CI workflows pin to latest-stable Xcode so the iOS 26.4 SDK is always available.

Confidence Score: 5/5

Safe to merge; the new billing plan paths are dormant until the server ships the corresponding field, so existing paywalls are unaffected.

All production code paths are correctly gated behind compiler and availability checks. The composite-ID map accumulates entries without ever overwriting the Apple-ID cache, keeping preloaded paywalls intact. The only inconsistency is a protocol-default value that diverges from the SK2 override and the public documentation — it surfaces only in test mode for SK1 products and has no production impact.

Sources/SuperwallKit/StoreKit/Products/StoreProduct/StoreProductType.swift — the default isBillingPlanAvailable value diverges from SK2 behaviour and the StoreProduct documentation.

Important Files Changed

Filename	Overview
Sources/SuperwallKit/StoreKit/Products/StoreProduct/SK2StoreProduct.swift	Core billing plan logic: resolves and caches pricing term at init, routes price/period/intro-offer through it; isBillingPlanAvailable correctly returns false for unconfigured plans.
Sources/SuperwallKit/StoreKit/Products/StoreProduct/StoreProduct.swift	Adds billingPlanType/isBillingPlanAvailable public surface and copyForCompositeProduct helper; protocol default for isBillingPlanAvailable is true for non-SK2 types, inconsistent with SK2 and public docs.
Sources/SuperwallKit/StoreKit/StoreKitManager.swift	Refactored to fetch by Apple ID and build a per-call composite-ID map of cloned StoreProducts; accumulates rather than resets to support preloading across paywalls.
Sources/SuperwallKit/Models/Product/AppStoreProduct.swift	Adds optional BillingPlanType enum with manual Codable round-trip; decodeIfPresent ensures backward compatibility with legacy paywall JSON.
Sources/SuperwallKit/Paywall/Request/Operators/AddPaywallProducts.swift	Lookup path updated to prefer composite-ID map, with Apple-ID fallback for non-composite products; intro-offer check correctly uses Apple-ID-keyed map.
Sources/SuperwallKit/StoreKit/Transactions/Purchasing/StoreKit 2/ProductPurchaserSK2.swift	Inserts .billingPlanType(_:) purchase option on iOS 26.4+ when plan is configured; correctly guarded by compiler and availability checks.
Sources/SuperwallKit/StoreKit/Products/StoreProduct/StoreProductType.swift	Protocol gains billingPlanType, isBillingPlanAvailable, and withBillingPlanType; default isBillingPlanAvailable returns true for non-SK2 types which diverges from SK2 and StoreProduct documentation.
Sources/SuperwallKit/Models/Paywall/Paywall.swift	Adds appStoreProductIdentifiers (deduped Apple IDs for SK fetch) and deduplicates productIdsWithIntroOffers to handle shared Apple IDs across billing plan slots.
Sources/SuperwallKit/StoreKit/Transactions/TransactionManager.swift	Purchase resolution now routes through product(withId:) which prefers composite map before falling back to Apple-ID map.
Tests/SuperwallKitTests/Models/PaywallBillingPlanTests.swift	New tests covering appStoreProductIdentifiers deduplication and productIdsWithIntroOffers deduplication; well structured.
Tests/SuperwallKitTests/StoreKit/StoreKitManagerTests.swift	Migrated from XCTest to Swift Testing framework; existing product-substitution tests preserved with equivalent assertions.

Sequence Diagram

sequenceDiagram
    participant Server
    participant Paywall
    participant SKManager as StoreKitManager
    participant SKProduct as SK2StoreProduct
    participant Purchaser as ProductPurchaserSK2

    Server->>Paywall: Decode products with billingPlanType
    Note over Paywall: appStoreProductIdentifiers (deduped Apple IDs)
    Paywall->>SKManager: getProducts(forPaywall:)
    SKManager->>SKManager: fetch by Apple ID (StoreKit.Product.products)
    loop Each App Store product slot
        SKManager->>SKProduct: copyForCompositeProduct(billingPlanType:)
        Note over SKProduct: Resolves PricingTerms at init, caches price/period/intro offer
        SKManager->>SKManager: "productsByCompositeId[compositeId] = clone"
    end
    SKManager-->>Paywall: (productsByCompositeId, productItems)
    Note over Paywall: User taps purchase
    Paywall->>SKManager: product(withId: compositeId)
    SKManager-->>Paywall: StoreProduct clone with billingPlanType
    Paywall->>Purchaser: purchase(product:)
    alt iOS 26.4+ and plan available
        Purchaser->>Purchaser: options.insert(.billingPlanType(sk2Plan))
    end
    Purchaser->>SKProduct: sk2Product.purchase(options:)

Loading

Comments Outside Diff (2)

1. Sources/SuperwallKit/StoreKit/Products/StoreProduct/StoreProduct.swift, line 476-479 (link)

   Non-atomic read-modify-write on nonisolated(unsafe) var product

   The billingPlanType setter performs product = product.withBillingPlanType(newValue) — a read followed by a write with no synchronization. Because product is nonisolated(unsafe), Swift's concurrency checker treats it as safe, but two concurrent writes (or a write racing a price-property read on the UI thread) produce undefined behavior. This is a real exposure because the docs explicitly invite external PurchaseController implementations to call this setter. Consider protecting the property with os_unfair_lock or an NSLock, or making the setter internal (with billingPlanType public read-only) and routing mutation exclusively through copyForCompositeProduct.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: Sources/SuperwallKit/StoreKit/Products/StoreProduct/StoreProduct.swift
   Line: 476-479
   
   Comment:
   **Non-atomic read-modify-write on `nonisolated(unsafe) var product`**
   
   The `billingPlanType` setter performs `product = product.withBillingPlanType(newValue)` — a read followed by a write with no synchronization. Because `product` is `nonisolated(unsafe)`, Swift's concurrency checker treats it as safe, but two concurrent writes (or a write racing a price-property read on the UI thread) produce undefined behavior. This is a real exposure because the docs explicitly invite external `PurchaseController` implementations to call this setter. Consider protecting the property with `os_unfair_lock` or an `NSLock`, or making the setter internal (with `billingPlanType` public read-only) and routing mutation exclusively through `copyForCompositeProduct`.
   
   How can I resolve this? If you propose a fix, please make it concise.

2. Sources/SuperwallKit/StoreKit/StoreKitManager.swift, line 612-638 (link)

   Test-mode composite map is keyed by Apple IDs, not composite IDs

   In the test-mode branch, testProductsByCompositeId is built by copying from self.productsById (Apple-ID-keyed), so the returned map and self.productsByCompositeId both use Apple IDs as keys. Downstream in AddPaywallProducts, PaywallLogic.getProductVariables looks up products via productsById: mergedProductsByCompositeId using productItem.id (the composite ID). For any test fixture that introduces a billing-plan product (e.g., com.app.annual:MONTHLY), the lookup would silently miss and that product's variables would not be set. This means billing-plan scenarios can't be exercised in test mode until this path is updated too.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: Sources/SuperwallKit/StoreKit/StoreKitManager.swift
   Line: 612-638
   
   Comment:
   **Test-mode composite map is keyed by Apple IDs, not composite IDs**
   
   In the test-mode branch, `testProductsByCompositeId` is built by copying from `self.productsById` (Apple-ID-keyed), so the returned map and `self.productsByCompositeId` both use Apple IDs as keys. Downstream in `AddPaywallProducts`, `PaywallLogic.getProductVariables` looks up products via `productsById: mergedProductsByCompositeId` using `productItem.id` (the composite ID). For any test fixture that introduces a billing-plan product (e.g., `com.app.annual:MONTHLY`), the lookup would silently miss and that product's variables would not be set. This means billing-plan scenarios can't be exercised in test mode until this path is updated too.
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

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

---

### Issue 1 of 1
Sources/SuperwallKit/StoreKit/Products/StoreProduct/StoreProductType.swift:158-166
The default `isBillingPlanAvailable` returns `true` for all non-SK2 types (SK1, `APIStoreProduct`, custom), but `SK2StoreProduct` correctly returns `false` when no billing plan is configured. Because `StoreProduct.isBillingPlanAvailable` delegates directly to the underlying product, any SK1 test product will expose `"isBillingPlanAvailable": "true"` in its `attributes` dictionary, causing paywall templates that gate billing-plan copy on that variable to behave differently in test mode versus production (where SK2 returns `false` for unconfigured plans). The `StoreProduct` documentation also explicitly promises `false` for legacy products with no plan configured. Flipping the default to `false` aligns behaviour and matches the documented contract.

```suggestion
extension StoreProductType {
  var billingPlanType: AppStoreProduct.BillingPlanType? { nil }
  var isBillingPlanAvailable: Bool { false }
  func withBillingPlanType(
    _ billingPlanType: AppStoreProduct.BillingPlanType?
  ) -> any StoreProductType {
    self
  }
}
```

_{Reviews (4): Last reviewed commit: "Stop wiping composite product cache betw..." | Re-trigger Greptile}