@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/storekit/references/storekit-advanced.md

@@ -1,804 +1,511 @@
-# StoreKit 2 Advanced Reference
+# StoreKit 2 Advanced Patterns
 
-Covers subscription control styles, offer management, testing, server-side
-validation, and advanced subscription handling patterns for StoreKit 2.
-Use this after the core purchase, transaction listener, and entitlement patterns
-from the top-level StoreKit skill are in place.
+Reach for this file once purchasing, the launch-time listener and entitlement
+checks from [core-patterns.md](core-patterns.md) are in place. Each heading
+names the release an API needs; the skill as a whole targets iOS 26.
 
 ## Contents
 
-- [SubscriptionStoreView Control Styles](#subscriptionstoreview-control-styles)
-- [Subscription Group Management](#subscription-group-management)
+- [Paywall Control Styles](#paywall-control-styles)
+- [Where the Controls Sit](#where-the-controls-sit)
+- [Button Labels](#button-labels)
+- [Container Backgrounds](#container-backgrounds)
+- [Store Buttons](#store-buttons)
+- [Policy Destinations](#policy-destinations)
+- [An Icon per Option](#an-icon-per-option)
+- [Sign-In Action](#sign-in-action)
+- [Grouping Options (iOS 18+)](#grouping-options-ios-18)
 - [Introductory Offers](#introductory-offers)
 - [Promotional Offers](#promotional-offers)
-- [Win-Back Offers](#win-back-offers)
+- [Win-Back Offers (iOS 18+)](#win-back-offers-ios-18)
 - [Offer Codes](#offer-codes)
+- [Which Offer a Transaction Used](#which-offer-a-transaction-used)
 - [Server-Side Validation](#server-side-validation)
-- [StoreKit Testing in Xcode](#storekit-testing-in-xcode)
-- [Subscription Renewal States](#subscription-renewal-states)
+- [Testing in Xcode](#testing-in-xcode)
+- [Renewal States and What to Grant](#renewal-states-and-what-to-grant)
 - [Grace Period and Billing Retry](#grace-period-and-billing-retry)
-- [Refund Handling](#refund-handling)
+- [Refunds](#refunds)
 - [Family Sharing](#family-sharing)
-- [Ask to Buy Handling](#ask-to-buy-handling)
-- [.currentEntitlementTask SwiftUI Modifier](#currententitlementtask-swiftui-modifier)
-- [Subscription Status Listener](#subscription-status-listener)
-- [Product Promotion Management](#product-promotion-management)
-- [Price Increase Handling](#price-increase-handling)
+- [Ask to Buy](#ask-to-buy)
+- [Task Modifiers](#task-modifiers)
+- [Live Subscription Status](#live-subscription-status)
+- [Promoted Purchases on the Product Page](#promoted-purchases-on-the-product-page)
+- [Price Increases](#price-increases)
 - [Unfinished Transactions](#unfinished-transactions)
-- [Common Advanced Mistakes](#common-advanced-mistakes)
+- [Advanced Mistakes](#advanced-mistakes)
 
-## SubscriptionStoreView Control Styles
+## Paywall Control Styles
 
-Apply control styles to change how subscription options render in
-`SubscriptionStoreView`.
+`.subscriptionStoreControlStyle(_:)` chooses how plans are presented.
 
-```swift
-// Individual buttons for each subscription option
-.subscriptionStoreControlStyle(.buttons)
-
-// Inline picker for compact selection
-.subscriptionStoreControlStyle(.picker)
-
-// Picker with the selected option visually emphasized
-.subscriptionStoreControlStyle(.prominentPicker)
-
-// Full-page swipeable picker (one option per page)
-.subscriptionStoreControlStyle(.pagedPicker)
-
-// Paged picker with prominent selected option
-.subscriptionStoreControlStyle(.pagedProminentPicker)
-
-// Minimal inline picker for tight layouts
-.subscriptionStoreControlStyle(.compactPicker)
-
-// System decides based on context
-.subscriptionStoreControlStyle(.automatic)
-```
-
-### Control Placement
-
-Specify where controls appear within the view. Not every placement is supported
-by every control style, so let unsupported combinations fall back to the system
-default instead of assuming exact placement on every platform.
-
-```swift
-.subscriptionStoreControlStyle(.picker, placement: .bottom)
-// Placement options: .bottom, .leading, .trailing, .scrollView,
-// .bottomBar, .buttonsInBottomBar
-```
+| Style | Look | Since |
+|-------|------|-------|
+| `.automatic` | the system decides for the context | iOS 17 |
+| `.buttons` | one button per plan | iOS 17 |
+| `.picker` | an inline picker | iOS 17 |
+| `.prominentPicker` | a picker that emphasises the selected plan | iOS 17 |
+| `.pagedPicker` | one plan per swipeable page | iOS 18 |
+| `.pagedProminentPicker` | paged, with the selection emphasised | iOS 18 |
+| `.compactPicker` | a minimal picker for tight layouts | iOS 18 |
 
-### Button Labels
+## Where the Controls Sit
 
-Control what information subscription buttons display:
+`.subscriptionStoreControlStyle(_:placement:)` (iOS 18) adds a placement. The
+placement type belongs to the style, so the valid values differ:
 
-```swift
-.subscriptionStoreButtonLabel(.multiline)   // Full details (name, price, period)
-.subscriptionStoreButtonLabel(.price)       // Price only
-.subscriptionStoreButtonLabel(.displayName) // Product name only
-.subscriptionStoreButtonLabel(.action)      // Action text ("Subscribe")
-.subscriptionStoreButtonLabel(.singleLine)  // Condensed single line
-.subscriptionStoreButtonLabel(.automatic)   // System default
-```
+| Style | Placements on iOS |
+|-------|-------------------|
+| `.picker`, `.prominentPicker` | `.automatic`, `.scrollView`, `.buttonsInBottomBar` |
+| `.pagedPicker`, `.pagedProminentPicker`, `.compactPicker` | `.automatic`, `.scrollView`, `.bottomBar`, `.buttonsInBottomBar` |
+| `.automatic` | `.automatic`, `.scrollView`, `.bottomBar`, `.buttonsInBottomBar` |
 
-### Container Backgrounds
+`.leading`, `.trailing` and `.bottom` exist only on tvOS, so
+`.subscriptionStoreControlStyle(.picker, placement: .bottom)` does not compile
+for iOS. Even a valid placement is a request: the system can fall back to its
+default on some platforms, so do not promise an exact position.
 
 ```swift
-.containerBackground(.blue.gradient, for: .subscriptionStore)
-
-.containerBackground(for: .subscriptionStoreHeader) {
-    Image("premium-header").resizable().scaledToFill()
-}
+@available(iOS 18, *)
+struct PagedPlans: View {
+    let group: String
 
-.containerBackground(for: .subscriptionStoreFullHeight) {
-    LinearGradient(colors: [.blue, .purple], startPoint: .top, endPoint: .bottom)
+    var body: some View {
+        SubscriptionStoreView(groupID: group)
+            .subscriptionStoreControlStyle(.pagedPicker, placement: .bottomBar)
+    }
 }
 ```
 
-### Subscription Store Buttons
+## Button Labels
 
-```swift
-.storeButton(.visible, for: .restorePurchases)
-.storeButton(.visible, for: .redeemCode)
-.storeButton(.visible, for: .cancellation)
-.storeButton(.visible, for: .policies)
-.storeButton(.hidden, for: .signIn)
-```
+`.subscriptionStoreButtonLabel(_:)` (iOS 17):
 
-### Policy Destinations
+| Label | Shows |
+|-------|-------|
+| `.multiline` | name, price and period |
+| `.price` | only the price |
+| `.displayName` | only the plan name |
+| `.action` | a verb such as "Subscribe" |
+| `.singleLine` | everything squeezed onto one line |
+| `.automatic` | the system default |
 
-```swift
-// URL-based
-.subscriptionStorePolicyDestination(url: termsURL, for: .termsOfService)
-.subscriptionStorePolicyDestination(url: privacyURL, for: .privacyPolicy)
-
-// Custom view
-.subscriptionStorePolicyDestination(for: .termsOfService) {
-    TermsOfServiceView()
-}
+## Container Backgrounds
 
-// Style policy link text
-.subscriptionStorePolicyForegroundStyle(.white)
-```
-
-### Decorative Icons per Option
+| Call | Paints |
+|------|--------|
+| `.containerBackground(.indigo.gradient, for: .subscriptionStore)` | the whole paywall, from a style |
+| `.containerBackground(for: .subscriptionStoreHeader) { Image("hero").resizable() }` | only the header area |
+| `.containerBackground(for: .subscriptionStoreFullHeight) { LinearGradient(...) }` | full height, behind everything |
 
-```swift
-.subscriptionStoreControlIcon { product, subscriptionInfo in
-    if subscriptionInfo.subscriptionPeriod.unit == .year {
-        Image(systemName: "star.fill")
-    } else {
-        Image(systemName: "star")
-    }
-}
-```
+## Store Buttons
 
-### Sign-In Action
+`.storeButton(_:for:)` shows or hides system buttons. Kinds:
+`.restorePurchases`, `.redeemCode`, `.cancellation`, `.policies`, `.signIn`.
+Visibility is `.visible` or `.hidden`.
 
 ```swift
-.storeButton(.visible, for: .signIn)
-.subscriptionStoreSignInAction {
-    showSignInSheet = true
-}
+SubscriptionStoreView(groupID: group)
+    .storeButton(.visible, for: .restorePurchases, .redeemCode)
+    .storeButton(.hidden, for: .signIn)
 ```
 
-## Subscription Group Management
+## Policy Destinations
 
-The option hierarchy helper views in this section are iOS 18+ APIs for
-organizing subscription choices inside `SubscriptionStoreView`.
+- By URL: `.subscriptionStorePolicyDestination(url:for:)` with
+  `.termsOfService` or `.privacyPolicy`.
+- By view: `.subscriptionStorePolicyDestination(for: .termsOfService) { TermsView() }`.
+- Link colour: `.subscriptionStorePolicyForegroundStyle(.secondary)`.
 
-### Hierarchical Layouts with SubscriptionOptionGroup
+## An Icon per Option
 
 ```swift
-SubscriptionStoreView(groupID: "premium_group") {
-    SubscriptionOptionGroup("Monthly Plans") { product in
-        product.subscription?.subscriptionPeriod.unit == .month
+SubscriptionStoreView(groupID: group)
+    .subscriptionStoreControlIcon { _, info in
+        Image(systemName: info.subscriptionPeriod.unit == .year ? "star.circle.fill" : "calendar")
     }
-    SubscriptionOptionGroup("Annual Plans") { product in
-        product.subscription?.subscriptionPeriod.unit == .year
-    }
-}
 ```
 
-### Automatic Period Grouping
+## Sign-In Action
 
-```swift
-SubscriptionStoreView(groupID: "premium_group") {
-    SubscriptionPeriodGroupSet()
-}
-```
-
-### Sections with Headers
+Show the system sign-in button and decide what it does:
 
 ```swift
-SubscriptionStoreView(groupID: "premium_group") {
-    SubscriptionOptionSection("Standard", isIncluded: { product in
-        product.subscription?.groupLevel == 1
-    }) {
-        Text("Basic features included")
-    }
-    SubscriptionOptionSection("Pro", isIncluded: { product in
-        product.subscription?.groupLevel == 2
-    }) {
-        Text("All features included")
-    }
-}
+SubscriptionStoreView(groupID: group)
+    .storeButton(.visible, for: .signIn)
+    .subscriptionStoreSignInAction { showLogin = true }
+    .sheet(isPresented: $showLogin) { LoginSheet() }
 ```
 
-### Visible Relationships
+## Grouping Options (iOS 18+)
 
-Filter which subscription levels are shown relative to the current subscription:
+The hierarchy helpers arrange plans inside `SubscriptionStoreView`; the
+content-builder initializer that takes them is iOS 18.
 
 ```swift
-// Show all options
-SubscriptionStoreView(groupID: "group_id", visibleRelationships: .all)
+@available(iOS 18, *)
+struct TieredPlans: View {
+    let group: String
 
-// Show only upgrades from current subscription
-SubscriptionStoreView(groupID: "group_id", visibleRelationships: .upgrade)
+    var body: some View {
+        SubscriptionStoreView(groupID: group) {
+            SubscriptionOptionGroup("Monthly") { $0.subscription?.subscriptionPeriod.unit == .month }
+            SubscriptionOptionGroup("Yearly") { $0.subscription?.subscriptionPeriod.unit == .year }
+        }
+    }
+}
 ```
 
-### Custom Subscription Store Controls
+- `SubscriptionOptionGroup(_:isIncluded:)` groups plans by a predicate.
+- `SubscriptionPeriodGroupSet()` groups by billing period for you.
+- `SubscriptionOptionSection(_:isIncluded:)` adds a section with a header;
+  the predicate can look at `product.subscription?.groupLevel` to split tiers.
+
+`SubscriptionStoreView(groupID:visibleRelationships:)` is iOS 17: `.all`
+lists every plan, `.upgrade` only plans above the current one.
 
 `SubscriptionStoreButton`, `SubscriptionStorePicker`,
-`SubscriptionOptionGroup`, and related option controls are supported inside a
-custom `SubscriptionStoreControlStyle.makeBody(configuration:)`. Do not place
-them as arbitrary standalone content outside a custom control style.
+`SubscriptionOptionGroup` and their relatives are building blocks for a custom
+`SubscriptionStoreControlStyle` and belong inside its
+`makeBody(configuration:)`. Placing them as free-standing content outside a
+control style is not supported.
 
 ## Introductory Offers
 
-### Checking Eligibility
-
 ```swift
-// Per-product eligibility
-let isEligible = product.subscription?.isEligibleForIntroOffer ?? false
-
-// Per-group eligibility
-let groupEligible = await Product.SubscriptionInfo.isEligibleForIntroOffer(
-    for: groupID
-)
-```
-
-### Accessing Offer Details
-
-```swift
-if let introOffer = product.subscription?.introductoryOffer {
-    let price = introOffer.displayPrice       // Localized price
-    let period = introOffer.period            // SubscriptionPeriod
-    let count = introOffer.periodCount        // Number of periods
-    let mode = introOffer.paymentMode         // .freeTrial, .payAsYouGo, .payUpFront
-
-    switch introOffer.paymentMode {
+func trialLine(for plan: Product, group: String) async -> String? {
+    guard let intro = plan.subscription?.introductoryOffer,
+          await Product.SubscriptionInfo.isEligibleForIntroOffer(for: group) else { return nil }
+    let length = "\(intro.periodCount) x \(intro.period.value) \(intro.period.unit)"
+    switch intro.paymentMode {
     case .freeTrial:
-        Text("Free for \(count) \(period.unit)")
+        return "Free for \(length), then \(plan.displayPrice)"
     case .payAsYouGo:
-        Text("\(price)/\(period.unit) for \(count) periods")
+        return "\(intro.displayPrice) per period for \(length)"
     case .payUpFront:
-        Text("\(price) for \(count) \(period.unit)")
+        return "\(intro.displayPrice) up front for \(length)"
     default:
-        EmptyView()
+        return nil
     }
 }
 ```
 
-### Introductory offers apply automatically when eligible. No special purchase options needed.
+- Eligibility per product: `product.subscription?.isEligibleForIntroOffer`,
+  treat `nil` as `false`. Per group:
+  `await Product.SubscriptionInfo.isEligibleForIntroOffer(for: groupID)`.
+- `introductoryOffer` gives `displayPrice` (localized), `period`
+  (`Product.SubscriptionPeriod`), `periodCount` and `paymentMode`.
+- An eligible user gets the intro offer automatically; no purchase option is
+  involved.
 
 ## Promotional Offers
 
-Promotional offers require server-side signature generation.
-
-### Accessing Promotional Offers
-
-```swift
-let promoOffers = product.subscription?.promotionalOffers ?? []
-for offer in promoOffers {
-    print("Offer: \(offer.id ?? "nil"), price: \(offer.displayPrice)")
-}
-```
+Promotional offers need a signature produced by your server. List them from
+`product.subscription?.promotionalOffers` (empty when `nil`); each has an
+optional `id` and a `displayPrice`.
 
-### Purchasing with a Promotional Offer
+On iOS 26 the server signs a compact JWS and the app passes it with
+`Product.PurchaseOption.promotionalOffer(_:compactJWS:)`, which returns an
+array of options and is back-deployed:
 
 ```swift
-// 1. Get signature from your server
-let signature = Product.SubscriptionOffer.Signature(
-    keyID: serverKeyID,
-    nonce: serverNonce,
-    timestamp: serverTimestamp,
-    signature: serverSignatureData
-)
-
-// 2. Purchase with the offer
-guard let offerID = offer.id else { throw StoreError.invalidOffer }
-let result = try await product.purchase(options: [
-    .promotionalOffer(offerID: offerID, signature: signature)
-])
-```
+enum OfferError: Error { case missingID }
 
-### SwiftUI Automatic Promotional Offer
-
-For StoreKit SwiftUI views on iOS 26+, provide the offer and the compact JWS
-signature asynchronously:
-
-```swift
-.subscriptionPromotionalOffer { product, subscription in
-    subscription.promotionalOffers.first
-} compactJWS: { product, subscription, offer in
-    guard let offerID = offer.id else { throw StoreError.invalidOffer }
-    return try await offerSigner.compactJWS(
-        productID: product.id,
-        offerID: offerID
-    )
-}
-```
-
-### Preferred Offer Selection
-
-Let the system choose the best offer for each user:
-
-```swift
-.preferredSubscriptionOffer { product, subscription, eligibleOffers in
-    // Return the best offer, or nil for no offer
-    return eligibleOffers.first
+func redeem(_ offer: Product.SubscriptionOffer, on plan: Product, signer: OfferSigner) async throws -> Product.PurchaseResult {
+    guard let offerID = offer.id else { throw OfferError.missingID }
+    let jws = try await signer.compactJWS(product: plan.id, offer: offerID)
+    let options = Set(Product.PurchaseOption.promotionalOffer(offerID, compactJWS: jws))
+    return try await plan.purchase(options: options)
 }
 ```
 
-## Win-Back Offers
-
-Target former subscribers who cancelled. Available since iOS 18.
-
-### Accessing Win-Back Offers
-
-```swift
-let winBackOffers = product.subscription?.winBackOffers ?? []
-```
-
-`winBackOffers` is the raw offer list for the product. Filter it through
-`renewalInfo.eligibleWinBackOfferIDs` before showing or applying offers.
-
-### Checking Eligibility via Renewal Info
-
-```swift
-let statuses = try await Product.SubscriptionInfo.status(for: groupID)
-let eligibleOfferIDs = statuses.flatMap { status -> [String] in
-    guard case .verified(let renewalInfo) = status.renewalInfo else { return [] }
-    return renewalInfo.eligibleWinBackOfferIDs
-}
-
-let offersByID = Dictionary(uniqueKeysWithValues: winBackOffers.compactMap { offer in
-    offer.id.map { ($0, offer) }
-})
-
-let eligibleWinBackOffers = eligibleOfferIDs.compactMap { offersByID[$0] }
-for offer in eligibleWinBackOffers {
-    // Display or apply only eligible offers.
-}
-```
+The older forms, `.promotionalOffer(offerID:signature:)` with a
+`Product.SubscriptionOffer.Signature(keyID:nonce:timestamp:signature:)`
+(iOS 17.4) and `.promotionalOffer(offerID:keyID:nonce:signature:timestamp:)`
+(iOS 15), are deprecated in iOS 26. Keep them only behind an availability
+check for older targets.
 
-### Purchasing with a Win-Back Offer
+Store views on iOS 26 take the offer and the signature as closures:
 
 ```swift
-let result = try await product.purchase(options: [
-    .winBackOffer(winBackOffer)
-])
-```
-
-## Offer Codes
+@available(iOS 26, *)
+struct WinTheUserBack: View {
+    let group: String
+    let signer: OfferSigner
 
-### Redemption Sheet
-
-```swift
-@State private var showRedeemSheet = false
-
-var body: some View {
-    Button("Redeem Code") { showRedeemSheet = true }
-        .offerCodeRedemption(isPresented: $showRedeemSheet) { result in
-            switch result {
-            case .success:
-                await storeManager.updateEntitlements()
-            case .failure(let error):
-                print("Redemption failed: \(error)")
+    var body: some View {
+        SubscriptionStoreView(groupID: group)
+            .subscriptionPromotionalOffer { _, subscription in
+                subscription.promotionalOffers.first
+            } compactJWS: { product, _, offer in
+                try await signer.compactJWS(product: product.id, offer: offer.id ?? "")
             }
-        }
-}
-```
-
-### Show Redeem Button on Subscription Store
-
-```swift
-.storeButton(.visible, for: .redeemCode)
-```
-
-### Testing Offer Codes
-
-Test offer-code redemption in StoreKit configuration files and sandbox. In
-StoreKit testing, use the configured offer-code reference name:
-
-```swift
-try await product.purchase(options: [.codeOffer(referenceName: "SUMMER2024")])
-```
-
-Also test the user-facing redemption path with `.storeButton(.visible, for:
-.redeemCode)` or `.offerCodeRedemption(isPresented:)`, then verify the resulting
-transaction uses `transaction.offer?.type == .code` and the expected
-`transaction.offer?.id`.
-
-### Verifying Applied Offers in Transactions
-
-```swift
-if let offer = transaction.offer {
-    switch offer.type {
-    case .introductory: break  // Introductory offer applied
-    case .promotional: break   // Promotional offer applied
-    case .code: break          // Offer code redeemed
-    case .winBack: break       // Win-back offer applied
-    default: break
     }
-
-    let offerID = offer.id
 }
 ```
 
-## Server-Side Validation
-
-### Sending JWS to Server
-
-StoreKit 2 transactions are JWS (JSON Web Signature) tokens. Send the raw
-JWS string to your server for validation.
-
-```swift
-case .success(let verification):
-    let transaction = try checkVerified(verification)
-
-    // Send to server for validation
-    let jwsString = verification.jwsRepresentation
-    try await sendToServer(jws: jwsString, productID: transaction.productID)
-
-    await transaction.finish()
-```
-
-### Server-Side Verification
-
-On your server, use Apple's App Store Server Library:
-- `verifyAndDecodeTransaction(signedTransaction:)` to validate and decode
-- `verifyAndDecodeRenewalInfo(signedRenewalInfo:)` for subscription renewal info
-- The JWS format matches `JWSTransaction` from the App Store Server API and
-  App Store Server Notifications V2
-
-### Device Verification
-
-Bind transactions to specific devices to prevent replay attacks:
-
-```swift
-let deviceVerification = transaction.deviceVerification
-let nonce = transaction.deviceVerificationNonce
-// Send both to server for additional validation
-```
-
-## StoreKit Testing in Xcode
-
-### StoreKit Configuration Files
-
-1. Create a StoreKit Configuration file in Xcode: File > New > File >
-   StoreKit Configuration File
-2. Add products matching your App Store Connect configuration
-3. Set the configuration in the scheme: Edit Scheme > Run > Options >
-   StoreKit Configuration
-
-### Configuration File Contents
-
-Define products with:
-- Product ID, reference name, product type
-- Price and locale
-- Subscription group and level (for subscriptions)
-- Introductory and promotional offers
-- Family Sharing settings
-
-### Testing Features
-
-```swift
-// Simulate Ask to Buy
-try await product.purchase(options: [.simulatesAskToBuyInSandbox(true)])
-
-// Test-only: set purchase date and renewal behavior
-try await product.purchase(options: [
-    .purchaseDate(Date(), renewalBehavior: .default)
-])
-
-// Test-only: apply offer code by reference name
-try await product.purchase(options: [.codeOffer(referenceName: "SUMMER2024")])
-```
-
-### StoreKit Testing Capabilities
-
-- Simulate failed transactions, interrupted purchases, refunds
-- Test Ask to Buy pending approvals for promotional, win-back, and offer-code purchases
-- Speed up subscription renewals (renewals happen in minutes, not months)
-- Test grace period and billing retry states
-- Clear purchase history between test runs
-- Test offer redemption flows
-- Simulate subscription expiration and cancellation
+That replaces `.subscriptionPromotionalOffer(offer:signature:)`, deprecated in
+iOS 26.
 
-### Transaction Manager in Xcode
+`.preferredSubscriptionOffer { product, subscription, eligibleOffers in ... }`
+(iOS 18) picks which eligible offer a store view presents to this user;
+return `nil` for none.
 
-Use Debug > StoreKit > Manage Transactions to:
-- View all test transactions
-- Delete transactions to reset state
-- Request refunds
-- Expire subscriptions
-- Approve or decline Ask to Buy requests
+## Win-Back Offers (iOS 18+)
 
-## Subscription Renewal States
-
-### Active States (grant access)
+Win-back offers target people who used to subscribe and cancelled.
+`product.subscription?.winBackOffers` (empty when `nil`) is the raw list for
+the product, not for this user: filter it through the verified
+`renewalInfo.eligibleWinBackOfferIDs` before showing or applying anything.
 
 ```swift
-switch status.state {
-case .subscribed:
-    // Active, auto-renewing subscription
-    grantAccess()
-
-case .inGracePeriod:
-    // Payment failed but grace period active -- still grant access
-    // Show a gentle prompt to update payment method
-    grantAccess()
-    showPaymentUpdatePrompt()
-```
-
-### Degraded States (consider limited or no access)
-
-```swift
-case .inBillingRetryPeriod:
-    // Payment failed, Apple is retrying -- access decision is yours
-    // Apple recommends granting limited access to encourage payment update
-    grantLimitedAccess()
-    showPaymentFailedBanner()
-
-case .expired:
-    // Subscription ended -- check expirationReason
-    revokeAccess()
-    if let reason = renewalInfo.expirationReason {
-        switch reason {
-        case .autoRenewDisabled: showResubscribeOffer()
-        case .billingError: showUpdatePaymentMethod()
-        case .didNotConsentToPriceIncrease: showPriceInfo()
-        case .productUnavailable: break
-        default: break
+@available(iOS 18, *)
+func eligibleWinBacks(for plan: Product, group: String) async throws -> [Product.SubscriptionOffer] {
+    let all = plan.subscription?.winBackOffers ?? []
+    let byID = Dictionary(all.compactMap { offer in offer.id.map { ($0, offer) } },
+                          uniquingKeysWith: { first, _ in first })
+    var allowedIDs: [String] = []
+    for status in try await Product.SubscriptionInfo.status(for: group) {
+        if case .verified(let renewal) = status.renewalInfo {
+            allowedIDs.append(contentsOf: renewal.eligibleWinBackOfferIDs)
         }
     }
-
-case .revoked:
-    // Apple refunded -- must revoke access
-    revokeAccess()
-```
-
-### Expiration Reasons
-
-| Reason | Meaning |
-|---|---|
-| `.autoRenewDisabled` | User voluntarily cancelled |
-| `.billingError` | Payment method failed |
-| `.didNotConsentToPriceIncrease` | User did not agree to price increase |
-| `.productUnavailable` | Product no longer available |
-| `.unknown` | Unspecified reason |
-
-## Grace Period and Billing Retry
-
-### Grace Period
-
-When enabled in App Store Connect, subscribers retain access for a short
-period after a billing failure. Check `status.state == .inGracePeriod` and
-the `gracePeriodExpirationDate` on renewal info.
-
-```swift
-if status.state == .inGracePeriod,
-   case .verified(let renewalInfo) = status.renewalInfo {
-    let expirationDate = renewalInfo.gracePeriodExpirationDate
-    // Grant access but prompt to update payment method
+    return allowedIDs.compactMap { byID[$0] }
 }
 ```
 
-### Billing Retry
-
-Apple automatically retries failed payments. During billing retry, the
-subscription state is `.inBillingRetryPeriod`. Check `renewalInfo.isInBillingRetry`.
-
-## Refund Handling
-
-### Initiating Refund Requests
-
-```swift
-// From a transaction instance
-let refundStatus = try await transaction.beginRefundRequest(in: windowScene)
+The result keeps the order of `eligibleWinBackOfferIDs`. Buy with
+`plan.purchase(options: [.winBackOffer(offer)])`.
 
-// From a transaction ID
-let refundStatus = try await Transaction.beginRefundRequest(
-    for: transactionID, in: windowScene
-)
-```
-
-### SwiftUI Refund Sheet
+## Offer Codes
 
 ```swift
-@State private var showRefund = false
+struct RedeemRow: View {
+    @State private var showRedeem = false
 
-Button("Request Refund") { showRefund = true }
-    .refundRequestSheet(for: transactionID, isPresented: $showRefund) { result in
-        // Handle refund request dismissal
+    var body: some View {
+        Button("Redeem code") { showRedeem = true }
+            .offerCodeRedemption(isPresented: $showRedeem) { result in
+                switch result {
+                case .success:
+                    Task { await EntitlementStore.shared.refresh() }
+                case .failure:
+                    showRedeem = false
+                }
+            }
     }
+}
 ```
 
-### Detecting Refunds
+- `.offerCodeRedemption(isPresented:onCompletion:)` (iOS 16) presents the
+  system sheet; refresh entitlements on success, handle the error on failure.
+- On a subscription store, `.storeButton(.visible, for: .redeemCode)` adds a
+  redeem button instead.
+- Test in a StoreKit configuration file and in sandbox. In StoreKit testing,
+  `.codeOffer(referenceName:)` from `StoreKitTest` applies a code by its
+  reference name. Also drive the real redemption path (button or sheet), then
+  check `transaction.offer?.type == .code` and the expected
+  `transaction.offer?.id`.
 
-Refunds appear via `Transaction.updates` with a non-nil `revocationDate`.
-Always check `revocationDate` when evaluating entitlements.
+## Which Offer a Transaction Used
 
-```swift
-if let revocationDate = transaction.revocationDate {
-    revokeAccess(for: transaction.productID)
-    // revocationPercentage indicates partial vs full refund
-    let percentage = transaction.revocationPercentage
-}
-```
+`transaction.offer` (iOS 17.2) is optional and has `type` and `id`. The
+`type` is `.introductory`, `.promotional`, `.code` or `.winBack`; keep a
+`default` branch for future cases. It replaces `offerType` and `offerID`,
+deprecated in iOS 17.2.
 
-## Family Sharing
+## Server-Side Validation
 
-### Checking Ownership Type
+Every StoreKit 2 transaction is a signed JWS. Send the raw string, not decoded
+fields:
 
 ```swift
-switch transaction.ownershipType {
-case .purchased:
-    // User purchased directly
-    break
-case .familyShared:
-    // Shared via Family Sharing -- may be revoked if sharer leaves
-    break
-default:
-    break
+func report(_ check: VerificationResult<StoreKit.Transaction>, to api: ReceiptAPI) async throws {
+    let transaction = try verified(check)
+    try await api.submit(jws: check.jwsRepresentation, product: transaction.productID)
+    await transaction.finish()
 }
 ```
 
-### Family Shareable Products
+- On the server, Apple's App Store Server Library decodes and checks it:
+  `verifyAndDecodeTransaction(signedTransaction:)` for transactions and
+  `verifyAndDecodeRenewalInfo(signedRenewalInfo:)` for renewal info.
+- The format is the `JWSTransaction` used by the App Store Server API and App
+  Store Server Notifications V2.
+- Against replay, also send `transaction.deviceVerification` and
+  `transaction.deviceVerificationNonce` so the server can bind the
+  transaction to the device.
 
-Check `product.isFamilyShareable` to determine if a product supports
-Family Sharing. Enable Family Sharing in App Store Connect per product.
+## Testing in Xcode
 
-Family Sharing changes arrive via `Transaction.updates`. When a family
-member stops sharing, the transaction is revoked.
+Setup:
 
-## Ask to Buy Handling
+1. File > New > File > StoreKit Configuration File.
+2. Add products that mirror App Store Connect.
+3. Choose it in Edit Scheme > Run > Options > StoreKit Configuration.
 
-Ask to Buy applies to child accounts in Family Sharing. The purchase returns
-`.pending`; show a waiting-for-approval state, keep content locked, and unlock
-only after the approved transaction arrives from `Transaction.updates`.
+The file holds product ID, reference name, type, price and locale,
+subscription group and level, introductory and promotional offers, and Family
+Sharing.
 
-```swift
-case .pending:
-    // Show UI indicating purchase needs parental approval
-    showPendingApprovalState()
-    // When approved, the transaction arrives via Transaction.updates
-```
+Purchase options for tests:
 
-### Testing Ask to Buy
+| Option | Source | Effect |
+|--------|--------|--------|
+| `.simulatesAskToBuyInSandbox(true)` | StoreKit | turns the purchase into an Ask to Buy request |
+| `.purchaseDate(someDate, renewalBehavior: .renewUntilNow)` | StoreKitTest, iOS 17 | backdates the purchase; `.cancelImmediately` is the other behaviour |
+| `.codeOffer(referenceName: "SPRING")` | StoreKitTest, iOS 17 | applies an offer code |
 
-```swift
-try await product.purchase(options: [.simulatesAskToBuyInSandbox(true)])
-```
-
-Then approve or decline in Xcode's Transaction Manager. Include this path when
-testing promotional offers, win-back offers, offer codes, and renewal states so
-deferred approval does not bypass verification or entitlement updates.
+What the local test environment lets you do:
 
-## .currentEntitlementTask SwiftUI Modifier
+- make transactions fail, interrupt purchases, issue refunds;
+- leave Ask to Buy pending for promotional, win-back and offer-code purchases;
+- speed renewals up to minutes instead of months;
+- enter grace period and billing retry;
+- clear purchase history between runs;
+- redeem offers;
+- expire or cancel subscriptions.
 
-### Basic Usage
-
-```swift
-.currentEntitlementTask(for: "com.app.premium") { state in
-    self.entitlementState = state
-}
-```
+The Transaction Manager (Debug > StoreKit > Manage Transactions) lists test
+transactions and can delete them (to reset), refund them, expire
+subscriptions, and approve or decline Ask to Buy.
 
-### EntitlementTaskState Pattern
+## Renewal States and What to Grant
 
-```swift
-enum EntitlementTaskState<Value> {
-    case loading
-    case success(Value)    // Value is VerificationResult<Transaction>?
-    case failure(any Error)
-}
-```
+| State | Access | Tell the user |
+|-------|--------|---------------|
+| `.subscribed` | full | nothing |
+| `.inGracePeriod` | full | a gentle prompt to update the payment method |
+| `.inBillingRetryPeriod` | your call; Apple suggests limited access to encourage a fix | a "payment failed" banner |
+| `.expired` | none | depends on `renewalInfo.expirationReason` |
+| `.revoked` | none, Apple refunded it | nothing to sell |
 
-Pattern-match the verified optional transaction before granting access:
+Expiration reasons and a reasonable response:
 
-```swift
-.currentEntitlementTask(for: ProductID.premium) { state in
-    if case .success(.some(.verified(let transaction))) = state,
-       transaction.revocationDate == nil {
-        self.isPremium = true
-    } else {
-        self.isPremium = false
-    }
-}
-```
+| `expirationReason` | Meaning | Response |
+|--------------------|---------|----------|
+| `.autoRenewDisabled` | the user cancelled | a resubscribe offer |
+| `.billingError` | payment failed | ask for a new payment method |
+| `.didNotConsentToPriceIncrease` | declined a price rise | explain the new price |
+| `.productUnavailable` | the plan is no longer sold | nothing |
+| `.unknown` | no reason given | nothing specific |
 
-### Related Task Modifiers
+## Grace Period and Billing Retry
 
-```swift
-// Load a single product
-.storeProductTask(for: "com.app.premium") { taskState in
-    // taskState: Product.TaskState (.loading, .success(Product), .unavailable, .failure)
-}
+- Grace period is switched on in App Store Connect; subscribers keep access
+  for a short time after a failed charge. Detect it with
+  `status.state == .inGracePeriod` and read
+  `renewalInfo.gracePeriodExpirationDate` from the verified renewal info.
+  Grant access and ask for a payment update.
+- Apple retries failed charges by itself. The state is
+  `.inBillingRetryPeriod`, and `renewalInfo.isInBillingRetry` is `true`.
 
-// Load multiple products
-.storeProductsTask(for: ["id1", "id2"]) { taskState in
-    // taskState: Product.CollectionTaskState (.loading, .success([Product], unavailable:), .failure)
-}
+## Refunds
 
-// Monitor subscription status
-.subscriptionStatusTask(for: "group_id") { taskState in
-    // Receive subscription status updates
-}
-```
+- From a transaction: `try await transaction.beginRefundRequest(in: windowScene)`.
+- From an ID: `try await Transaction.beginRefundRequest(for: transactionID, in: windowScene)`.
+- In SwiftUI: `.refundRequestSheet(for: transactionID, isPresented: $asking) { result in ... }`.
 
-## Subscription Status Listener
+A granted refund arrives on `Transaction.updates` with a `revocationDate`.
+Remove access for `transaction.productID`; `transaction.revocationPercentage`
+tells a partial refund from a full one.
 
-Listen for real-time subscription status changes:
+## Family Sharing
 
-```swift
-func listenForStatusChanges() -> Task<Void, Never> {
+- `transaction.ownershipType` is `.purchased` (bought by this user) or
+  `.familyShared` (can disappear when the organiser stops sharing); keep a
+  default branch.
+- `product.isFamilyShareable` says whether the product can be shared; sharing
+  is enabled per product in App Store Connect.
+- Sharing changes come through `Transaction.updates`; when a member stops
+  sharing, the transaction is revoked.
+
+## Ask to Buy
+
+- Applies to child accounts in a Family Sharing group.
+- The purchase returns `.pending`. Show a waiting state, keep content locked,
+  and unlock only when the approved transaction arrives on
+  `Transaction.updates`.
+- Test with `.simulatesAskToBuyInSandbox(true)` and approve or decline in the
+  Transaction Manager.
+- Run the Ask to Buy path through promotional, win-back, offer-code and
+  renewal tests too, so a deferred approval cannot skip verification or the
+  entitlement refresh.
+
+## Task Modifiers
+
+- `.currentEntitlementTask(for: productID) { state in ... }` (iOS 17) reports
+  an `EntitlementTaskState<VerificationResult<Transaction>?>`: `.loading`,
+  `.success(value)` or `.failure(any Error)`. Grant access only for
+  `.success(.some(.verified(let transaction)))` with a `nil`
+  `revocationDate`.
+- `.storeProductTask(for: id) { state in ... }` loads one product;
+  `Product.TaskState` is `.loading`, `.success(Product)`, `.unavailable` or
+  `.failure`.
+- `.storeProductsTask(for: ids) { state in ... }` loads several;
+  `Product.CollectionTaskState` is `.loading`,
+  `.success([Product], unavailable:)` or `.failure`.
+- `.subscriptionStatusTask(for: groupID) { state in ... }` follows a group's
+  status.
+
+## Live Subscription Status
+
+`Product.SubscriptionInfo.Status.all` (iOS 17) streams status changes for
+every group:
+
+```swift
+func watchPlans(onChange: @escaping @Sendable (Product.SubscriptionInfo.RenewalState) -> Void) -> Task<Void, Never> {
     Task {
-        for await (groupID, statuses) in Product.SubscriptionInfo.Status.all {
+        for await (_, statuses) in Product.SubscriptionInfo.Status.all {
             for status in statuses {
-                guard case .verified(let renewalInfo) = status.renewalInfo else { continue }
-                await handleStatusChange(state: status.state, renewalInfo: renewalInfo)
+                guard case .verified = status.renewalInfo else { continue }
+                onChange(status.state)
             }
         }
     }
 }
 ```
 
-## Product Promotion Management
+## Promoted Purchases on the Product Page
 
-Control the order and visibility of promoted in-app purchases on the App Store
-product page:
+`Product.PromotionInfo` (iOS 16.4) reads and overrides, on this device, the
+order and visibility of in-app purchases promoted on the App Store product
+page. Configure the defaults in App Store Connect and override per device only
+when needed.
 
-```swift
-// Product.PromotionInfo provides device-level promotion customization
-// Configure in App Store Connect and override per-device as needed
-```
+## Price Increases
 
-## Price Increase Handling
+Read `renewalInfo.priceIncreaseStatus` from verified renewal info:
 
-```swift
-if case .verified(let renewalInfo) = status.renewalInfo {
-    switch renewalInfo.priceIncreaseStatus {
-    case .noIncreasePending: break
-    case .pending:
-        // User has not yet consented -- show price increase info
-        showPriceIncreaseConsent(newPrice: renewalInfo.renewalPrice,
-                                 currency: renewalInfo.currency)
-    case .agreed:
-        // User accepted the price increase
-        break
-    }
-}
-```
+| Value | Meaning |
+|-------|---------|
+| `.noIncreasePending` | nothing to show |
+| `.pending` | the user has not agreed yet; show the new price from `renewalInfo.renewalPrice` and `renewalInfo.currency` |
+| `.agreed` | accepted |
 
 ## Unfinished Transactions
 
-`Transaction.updates` emits unfinished transactions once immediately after app
-launch. Use `Transaction.unfinished` when you need an explicit recovery sweep,
-such as after a delivery-server outage or a late listener startup:
+`Transaction.updates` hands over unfinished transactions once, just after
+launch. `Transaction.unfinished` lets you sweep for them on purpose, for
+example after your delivery server was down or when the listener started
+late:
 
 ```swift
-func processUnfinishedTransactions() async {
-    for await result in Transaction.unfinished {
-        guard case .verified(let transaction) = result else { continue }
-        await deliverContent(for: transaction)
+func sweepUnfinished(using store: EntitlementStore) async {
+    for await pending in StoreKit.Transaction.unfinished {
+        guard case .verified(let transaction) = pending else { continue }
+        try? await store.deliver(transaction)
         await transaction.finish()
     }
 }
 ```
 
-Keep the `Transaction.updates` listener as the primary always-on path, and use
-the sweep as a recovery tool rather than a replacement for the listener.
-
-## Common Advanced Mistakes
-
-### Missing a recovery path for unfinished transactions
-
-```swift
-// WRONG: No launch listener and no recovery sweep
-init() { }
-
-// CORRECT: Start updates at launch; sweep unfinished transactions when needed
-init() {
-    transactionListener = listenForTransactions()
-    Task { await processUnfinishedTransactions() }
-}
-```
-
-### Treating billing retry as expired
+The listener remains the always-on path; the sweep is recovery, not a
+substitute.
 
-```swift
-// WRONG: Revoking access during billing retry
-case .inBillingRetryPeriod: revokeAccess()
-
-// CORRECT: Grant limited access and prompt payment update
-case .inBillingRetryPeriod:
-    grantLimitedAccess()
-    showUpdatePaymentPrompt()
-```
+## Advanced Mistakes
 
-### Not handling Family Sharing revocation
-
-```swift
-// WRONG: Assuming family-shared access is permanent
-if transaction.ownershipType == .familyShared {
-    grantPermanentAccess()
-}
-
-// CORRECT: Check revocation status and listen for changes
-if transaction.ownershipType == .familyShared,
-   transaction.revocationDate == nil {
-    grantAccess()  // May be revoked later via Transaction.updates
-}
-```
+| Wrong | Right |
+|-------|-------|
+| An `App` initializer with neither listener nor sweep | start the listener in `init()`, and run the unfinished sweep in a `Task` when recovery is needed |
+| Removing access in `.inBillingRetryPeriod` | limited access plus a prompt to fix payment |
+| Treating `.familyShared` as permanent | also require `revocationDate == nil` and let `Transaction.updates` deliver a later revocation |