@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/storekit/references/core-patterns.md

@@ -1,371 +1,432 @@
 # StoreKit 2 Core Patterns
 
-Full code for the core purchase, transaction listener, entitlement, and store
-view flows described in the top-level StoreKit skill, plus the annotated common
-mistakes. Load this when you need a complete, copyable example for a core flow;
-SKILL.md keeps the review guidance and short snippets. For control styles,
-offers, testing, server validation, and advanced subscription handling see
+Complete, copyable code for the core flows, followed by the ten common
+mistakes with a wrong and a right version each. Control styles, offers,
+testing, server validation and subscription edge cases are in
 [storekit-advanced.md](storekit-advanced.md).
 
+The examples share one entitlement store, one verification helper and one
+completion handler. Files that also import SwiftUI spell the type
+`StoreKit.Transaction`.
+
 ## Contents
 
-- [Purchase Flow](#purchase-flow)
-- [Transaction.updates Listener](#transactionupdates-listener)
-- [Entitlement Checking](#entitlement-checking)
-- [SubscriptionStoreView](#subscriptionstoreview)
-- [StoreView and ProductView](#storeview-and-productview)
-- [Subscription Status Checking](#subscription-status-checking)
-- [App Transaction](#app-transaction)
-- [SwiftUI Purchase Callbacks](#swiftui-purchase-callbacks)
-- [Common Mistakes](#common-mistakes)
+- [Buying with PurchaseAction](#buying-with-purchaseaction)
+- [Launch-Time Transaction Listener](#launch-time-transaction-listener)
+- [Computing Entitlements](#computing-entitlements)
+- [Subscription Paywall](#subscription-paywall)
+- [Product Shelves: StoreView and ProductView](#product-shelves-storeview-and-productview)
+- [Is a Plan Active?](#is-a-plan-active)
+- [Verifying the Install with AppTransaction](#verifying-the-install-with-apptransaction)
+- [Store View Callbacks](#store-view-callbacks)
+- [Ten Mistakes, Fixed](#ten-mistakes-fixed)
 
-## Purchase Flow
+## Buying with PurchaseAction
 
-Handle every `PurchaseResult`, verify before access, deliver durably, then
-finish.
+A custom SwiftUI button that buys through `PurchaseAction` (iOS 17):
 
 ```swift
-@Environment(\.purchase) private var purchase
-
-func purchaseProduct(_ product: Product) async throws {
-    let result = try await purchase(product, options: [
-        .appAccountToken(userAccountToken)
-    ])
-    switch result {
-    case .success(let verification):
-        let transaction = try checkVerified(verification)
-        await deliverContent(for: transaction)
-        await transaction.finish()
-    case .userCancelled:
-        break
-    case .pending:
-        // Ask to Buy or deferred approval: show pending UI, no unlock yet.
-        showPendingApprovalMessage()
-    @unknown default:
-        break
-    }
+import StoreKit
+import SwiftUI
+
+func verified<Value>(_ check: VerificationResult<Value>) throws -> Value {
+    try check.payloadValue
 }
 
-func checkVerified<T>(_ result: VerificationResult<T>) throws -> T {
-    switch result {
-    case .verified(let value): return value
-    case .unverified(_, let error): throw error
+struct BuyProButton: View {
+    let product: Product
+    let accountID: UUID
+    @Environment(\.purchase) private var purchase
+    @State private var awaitingApproval = false
+
+    var body: some View {
+        Button("Unlock for \(product.displayPrice)") {
+            Task { await buy() }
+        }
+        .alert("Waiting for approval", isPresented: $awaitingApproval) {}
+    }
+
+    private func buy() async {
+        let options: Set<Product.PurchaseOption> = [.appAccountToken(accountID)]
+        do {
+            switch try await purchase(product, options: options) {
+            case .pending:
+                awaitingApproval = true
+            case .userCancelled:
+                return
+            case .success(let check):
+                let receipt = try verified(check)
+                try await EntitlementStore.shared.deliver(receipt)
+                await receipt.finish()
+            @unknown default:
+                return
+            }
+        } catch {
+            awaitingApproval = false
+        }
     }
 }
 ```
 
-## Transaction.updates Listener
+- `.success` carries a `VerificationResult`. `verified(_:)` reads its
+  `payloadValue`, which returns the transaction when the signature checks out
+  and throws the verification error when it does not. Deliver, then finish.
+- `.userCancelled` does nothing.
+- `.pending` means Ask to Buy or another deferred approval: tell the user and
+  unlock nothing until the approved transaction arrives on
+  `Transaction.updates`.
+- `@unknown default` keeps the switch valid when Apple adds a case.
 
-Start at app launch, not when a paywall appears. Keep the task retained for the
-app lifetime.
+## Launch-Time Transaction Listener
+
+Start it in the `App` initializer and keep the task for the life of the
+process. Its type is `Task<Void, Never>`, so no thrown error can end it.
 
 ```swift
+import StoreKit
+import SwiftUI
+
 @main
-struct MyApp: App {
-    private let transactionListener: Task<Void, Never>
+struct RecipesApp: App {
+    private let purchaseWatcher: Task<Void, Never>
 
     init() {
-        transactionListener = Self.listenForTransactions()
+        purchaseWatcher = Self.watchTransactions()
     }
 
     var body: some Scene {
-        WindowGroup { ContentView() }
+        WindowGroup { Text("Recipes") }
     }
 
-    static func listenForTransactions() -> Task<Void, Never> {
+    private static func watchTransactions() -> Task<Void, Never> {
         Task(priority: .background) {
-            for await result in Transaction.updates {
-                guard case .verified(let transaction) = result else { continue }
-                await StoreManager.shared.updateEntitlements()
-                await transaction.finish()
+            for await incoming in StoreKit.Transaction.updates {
+                if case .verified(let receipt) = incoming {
+                    await EntitlementStore.shared.refresh()
+                    await receipt.finish()
+                }
             }
         }
     }
 }
 ```
 
-## Entitlement Checking
+Unverified updates fall through untouched. For each verified one,
+entitlements are recomputed first and the transaction finished afterwards.
+
+A plain `Task` is enough here. It inherits the main actor from the `App`, but
+the loop spends its time suspended in `for await` and the entitlement refresh
+runs on the main-actor `EntitlementStore` anyway; `Task.detached` would only add
+a hop and drop the task-local values.
 
-Use `Transaction.currentEntitlements`; skip transactions with a non-nil
-`revocationDate`. Track consumable fulfillment in your own app or server ledger.
+## Computing Entitlements
 
 ```swift
-@Observable
+import Observation
+import StoreKit
+
 @MainActor
-class StoreManager {
-    static let shared = StoreManager()
-    var purchasedProductIDs: Set<String> = []
-    var isPremium: Bool { purchasedProductIDs.contains(ProductID.premium) }
-
-    func updateEntitlements() async {
-        var purchased = Set<String>()
-        for await result in Transaction.currentEntitlements {
-            if case .verified(let transaction) = result,
-               transaction.revocationDate == nil {
-                purchased.insert(transaction.productID)
-            }
+@Observable
+final class EntitlementStore {
+    static let shared = EntitlementStore()
+
+    private(set) var owned: Set<String> = []
+
+    var hasPro: Bool { owned.contains(StoreItem.proUnlock) }
+
+    func refresh() async {
+        var active: Set<String> = []
+        for await entry in StoreKit.Transaction.currentEntitlements {
+            guard case .verified(let receipt) = entry,
+                  receipt.revocationDate == nil else { continue }
+            active.insert(receipt.productID)
         }
-        purchasedProductIDs = purchased
+        owned = active
+    }
+
+    func deliver(_ receipt: StoreKit.Transaction) async throws {
+        await refresh()
     }
 }
+
+func settle(_ outcome: Result<Product.PurchaseResult, any Error>) async {
+    guard case .success(.success(let check)) = outcome,
+          let receipt = try? verified(check) else { return }
+    try? await EntitlementStore.shared.deliver(receipt)
+    await receipt.finish()
+}
 ```
 
+`refresh()` starts from an empty set each time: only verified entries with no
+`revocationDate` count, and the result replaces the old set in one
+assignment. `settle(_:)` is the shared completion handler for store views:
+the outer `Result` says whether the purchase call failed, the inner
+`PurchaseResult` whether it succeeded, and the `VerificationResult` whether it
+can be trusted.
+
 ### SwiftUI .currentEntitlementTask Modifier
 
+For a single product, a view can gate itself (iOS 17):
+
 ```swift
-struct PremiumGatedView: View {
-    @State private var state: EntitlementTaskState<VerificationResult<Transaction>?> = .loading
+import StoreKit
+import SwiftUI
+
+struct ProGate<Unlocked: View, Locked: View>: View {
+    let productID: String
+    @ViewBuilder var unlocked: Unlocked
+    @ViewBuilder var locked: Locked
+    @State private var gate: EntitlementTaskState<VerificationResult<StoreKit.Transaction>?> = .loading
 
     var body: some View {
-        Group {
-            switch state {
-            case .loading: ProgressView()
-            case .failure: PaywallView()
-            case .success(.some(.verified(let transaction))) where transaction.revocationDate == nil:
-                PremiumContentView()
+        ZStack {
+            switch gate {
+            case .loading:
+                ProgressView()
+            case .failure:
+                locked
+            case .success(.some(.verified(let receipt))) where receipt.revocationDate == nil:
+                unlocked
             case .success:
-                PaywallView()
+                locked
+            @unknown default:
+                locked
             }
         }
-        .currentEntitlementTask(for: ProductID.premium) { state in
-            self.state = state
-        }
+        .currentEntitlementTask(for: productID) { gate = $0 }
     }
 }
 ```
 
-## SubscriptionStoreView
+## Subscription Paywall
 
-Built-in SwiftUI view for subscription paywalls. Handles product loading,
-purchase UI, and restore purchases automatically.
+The built-in view loads the group's products, shows the purchase UI and can
+restore by itself.
 
 ```swift
-SubscriptionStoreView(groupID: "YOUR_GROUP_ID")
-    .subscriptionStoreControlStyle(.prominentPicker)
-    .subscriptionStoreButtonLabel(.multiline)
-    .storeButton(.visible, for: .restorePurchases)
-    .storeButton(.visible, for: .redeemCode)
-    .subscriptionStorePolicyDestination(url: termsURL, for: .termsOfService)
-    .subscriptionStorePolicyDestination(url: privacyURL, for: .privacyPolicy)
-    .onInAppPurchaseCompletion { product, result in
-        if case .success(.success(.verified(let transaction))) = result {
-            await deliverContent(for: transaction)
-            await transaction.finish()
-        }
+import StoreKit
+import SwiftUI
+
+struct MembershipPaywall: View {
+    let group: String
+    let terms: URL
+    let privacy: URL
+
+    var body: some View {
+        SubscriptionStoreView(groupID: group)
+            .storeButton(.visible, for: .restorePurchases, .redeemCode)
+            .subscriptionStorePolicyDestination(url: terms, for: .termsOfService)
+            .subscriptionStorePolicyDestination(url: privacy, for: .privacyPolicy)
+            .subscriptionStoreButtonLabel(.multiline)
+            .subscriptionStoreControlStyle(.prominentPicker)
+            .onInAppPurchaseCompletion { _, outcome in await settle(outcome) }
     }
+}
 ```
 
 ### Custom Marketing Content
 
+A trailing closure replaces the header; `.containerBackground(_:for:)` with
+`.subscriptionStore` paints behind the whole paywall.
+
 ```swift
-SubscriptionStoreView(groupID: "YOUR_GROUP_ID") {
-    VStack {
-        Image(systemName: "crown.fill").font(.system(size: 60)).foregroundStyle(.yellow)
-        Text("Unlock Premium").font(.largeTitle.bold())
-        Text("Access all features").foregroundStyle(.secondary)
+SubscriptionStoreView(groupID: group) {
+    VStack(spacing: 8) {
+        Image(systemName: "fork.knife.circle.fill")
+            .font(.system(size: 56))
+        Text("Recipes Plus").font(.largeTitle.bold())
+        Text("Every cookbook, offline, on all your devices")
+            .foregroundStyle(.secondary)
     }
+    .padding()
 }
-.containerBackground(.blue.gradient, for: .subscriptionStore)
+.containerBackground(.orange.gradient, for: .subscriptionStore)
 ```
 
-For hierarchical layouts (`SubscriptionOptionGroup`, `SubscriptionOptionSection`,
-`SubscriptionPeriodGroupSet`) and control styles see
+Grouped layouts (`SubscriptionOptionGroup`, `SubscriptionOptionSection`,
+`SubscriptionPeriodGroupSet`) and the control styles are in
 [storekit-advanced.md](storekit-advanced.md).
 
-## StoreView and ProductView
+## Product Shelves: StoreView and ProductView
 
-Merchandise multiple products with localized names, prices, and purchase buttons.
+`StoreView` lists several products, each with its localized name, price and
+buy button; `ProductView` shows one. `.productViewStyle(.large)` works on
+both. The icon closure that receives a `ProductIconPhase` exists on
+`ProductView(id:icon:placeholderIcon:)`, so an ID-based view with a phase
+closure also needs `placeholderIcon`; `ProductView(_ product:icon:)` takes the
+phase closure alone.
 
 ```swift
-StoreView(ids: [ProductID.gems100, ProductID.premium], prefersPromotionalIcon: true)
-    .productViewStyle(.large)
-    .storeButton(.visible, for: .restorePurchases)
-    .onInAppPurchaseCompletion { product, result in
-        if case .success(.success(.verified(let transaction))) = result {
-            await deliverContent(for: transaction)
-            await transaction.finish()
-        }
+import StoreKit
+import SwiftUI
+
+struct AddOnShelf: View {
+    let ids: [String]
+
+    var body: some View {
+        StoreView(ids: ids, prefersPromotionalIcon: true)
+            .storeButton(.visible, for: .restorePurchases)
+            .productViewStyle(.large)
+            .onInAppPurchaseCompletion { _, outcome in await settle(outcome) }
     }
-```
+}
 
-```swift
-ProductView(id: ProductID.premium) { iconPhase in
-    switch iconPhase {
-    case .success(let image): image.resizable().scaledToFit()
-    case .loading: ProgressView()
-    default: Image(systemName: "star.fill")
+struct FeaturedPack: View {
+    let id: String
+
+    var body: some View {
+        ProductView(id: id) { phase in
+            if case .success(let art) = phase {
+                art.resizable().aspectRatio(contentMode: .fit)
+            } else if case .loading = phase {
+                ProgressView()
+            } else {
+                Image(systemName: "shippingbox")
+            }
+        } placeholderIcon: {
+            ProgressView()
+        }
+        .productViewStyle(.large)
     }
 }
-.productViewStyle(.large)
 ```
 
-## Subscription Status Checking
+## Is a Plan Active?
 
 ```swift
-func checkSubscriptionActive(groupID: String) async throws -> Bool {
-    let statuses = try await Product.SubscriptionInfo.status(for: groupID)
-    for status in statuses {
-        guard case .verified = status.renewalInfo,
-              case .verified = status.transaction else { continue }
-        if status.state == .subscribed || status.state == .inGracePeriod {
-            return true
-        }
+func hasActivePlan(in group: String) async throws -> Bool {
+    let statuses = try await Product.SubscriptionInfo.status(for: group)
+    return statuses.contains { entry in
+        guard case .verified = entry.transaction,
+              case .verified = entry.renewalInfo else { return false }
+        return [.subscribed, .inGracePeriod].contains(entry.state)
     }
-    return false
 }
 ```
 
-## App Transaction
+A status counts only when both its renewal info and its transaction verify.
 
-Verify the legitimacy of the app installation. Use for business model changes
-or detecting tampered installations (iOS 16+).
+## Verifying the Install with AppTransaction
 
 ```swift
-func verifyAppPurchase() async {
+func checkInstall() async -> Date? {
     do {
-        let result = try await AppTransaction.shared
-        switch result {
-        case .verified(let appTransaction):
-            let originalVersion = appTransaction.originalAppVersion
-            let purchaseDate = appTransaction.originalPurchaseDate
-            // Migration logic for users who paid before subscription model
+        switch try await AppTransaction.shared {
+        case .verified(let install):
+            _ = install.originalAppVersion
+            return install.originalPurchaseDate
         case .unverified:
-            // Potentially tampered -- restrict features as appropriate
-            break
+            return nil
         }
-    } catch { /* Could not retrieve app transaction */ }
+    } catch {
+        return nil
+    }
 }
 ```
 
-## SwiftUI Purchase Callbacks
+With `.verified`, `originalAppVersion` and `originalPurchaseDate` tell you
+whether this user bought the app before a switch to subscriptions, so you can
+grandfather them. `.unverified` may mean a tampered install: restrict
+features. The `catch` covers failing to fetch the app transaction at all.
+
+## Store View Callbacks
 
 ```swift
-.onInAppPurchaseStart { product in
-    await analytics.trackPurchaseStarted(product.id)
-}
-.onInAppPurchaseCompletion { product, result in
-    if case .success(.success(.verified(let transaction))) = result {
-        await deliverContent(for: transaction)
-        await transaction.finish()
+struct TrackedStore: View {
+    let ids: [String]
+    let accountID: UUID
+    let log: @Sendable (String) -> Void
+
+    var body: some View {
+        StoreView(ids: ids)
+            .inAppPurchaseOptions { _ in [.appAccountToken(accountID)] }
+            .onInAppPurchaseStart { product in log("purchase_started \(product.id)") }
+            .onInAppPurchaseCompletion { _, outcome in await settle(outcome) }
     }
 }
-.inAppPurchaseOptions { product in
-    [.appAccountToken(userAccountToken)]
-}
 ```
 
-## Common Mistakes
+`.onInAppPurchaseStart` suits analytics, `.onInAppPurchaseCompletion` does
+verify, deliver, finish, and `.inAppPurchaseOptions` supplies options per
+product.
 
-### 1. Not starting Transaction.updates at app launch
+## Ten Mistakes, Fixed
 
-```swift
-// WRONG: No listener -- misses renewals, refunds, Ask to Buy approvals
-@main struct MyApp: App {
-    var body: some Scene { WindowGroup { ContentView() } }
-}
-// CORRECT: Start listener in App init (see Transaction.updates Listener above)
-```
+### 1. No listener at launch
+
+Wrong: an `App` with an empty initializer never hears about renewals, refunds
+or Ask to Buy approvals.
+
+Right: start `Transaction.updates` in `init()`, as in
+[Launch-Time Transaction Listener](#launch-time-transaction-listener).
+
+### 2. Never finishing
+
+Wrong: unlocking and returning. The transaction comes back in the unfinished
+queue on every launch.
 
-### 2. Forgetting transaction.finish()
+Right: record the delivery with a call that can fail, then finish. If the
+record fails, leave the transaction unfinished so it is offered again.
 
 ```swift
-// WRONG: Never finished -- reappears in unfinished queue forever
-let transaction = try checkVerified(verification)
-unlockFeature(transaction.productID)
-
-// CORRECT: Deliver durably, then finish. If delivery fails, do not finish yet.
-let transaction = try checkVerified(verification)
-try await recordDelivery(transaction)
-await transaction.finish()
+func complete(_ receipt: StoreKit.Transaction, ledger: PurchaseLedger) async throws {
+    try await ledger.record(receipt.id, product: receipt.productID)
+    await receipt.finish()
+}
 ```
 
-### 3. Ignoring verification result
+### 3. Trusting unverified data
 
-```swift
-// WRONG: Using unverified transaction -- security risk
-let transaction = verification.unsafePayloadValue
+Wrong: `check.unsafePayloadValue` hands you the payload whether or not the
+signature holds; that is a security hole.
 
-// CORRECT: Verify before using
-let transaction = try checkVerified(verification)
-```
+Right: `let receipt = try verified(check)`.
 
-### 4. Using original In-App Purchase APIs in new StoreKit 2 code
+### 4. Original IAP API in new code
 
-```swift
-// AVOID: Original In-App Purchase APIs
-let request = SKProductsRequest(productIdentifiers: ["com.app.premium"])
-SKPaymentQueue.default().add(payment)
+Avoid: `SKProductsRequest(productIdentifiers:)` and
+`SKPaymentQueue.default().add(payment)`.
 
-// PREFERRED: StoreKit 2
-let products = try await Product.products(for: ["com.app.premium"])
-let result = try await product.purchase()
-```
+Prefer: `Product.products(for:)` and `product.purchase()`.
 
-### 5. Not checking revocationDate
+### 5. Ignoring revocation
 
-```swift
-// WRONG: Grants access to refunded purchases
-if case .verified(let transaction) = result {
-    purchased.insert(transaction.productID)
-}
+Wrong: inserting `productID` for every verified transaction also grants
+refunded purchases.
 
-// CORRECT: Skip revoked transactions
-if case .verified(let transaction) = result, transaction.revocationDate == nil {
-    purchased.insert(transaction.productID)
-}
-```
+Right: require `revocationDate == nil` as well.
 
-### 6. Hardcoding prices
+### 6. Hard-coded prices
 
-```swift
-// WRONG: Wrong for other currencies and regions
-Text("Buy Premium for $4.99")
+Wrong: `Text("Pro for $4.99")` is wrong in every other currency and region.
 
-// CORRECT: Localized price from Product
-Text("Buy \(product.displayName) for \(product.displayPrice)")
-```
+Right: `Text("\(product.displayName): \(product.displayPrice)")`.
 
-### 7. Not handling .pending purchase result
+### 7. Dropping pending purchases
 
-```swift
-// WRONG: Silently drops pending Ask to Buy
-default: break
+Wrong: `default: break` in the result switch silently swallows Ask to Buy.
 
-// CORRECT: Explain approval is pending; unlock only after Transaction.updates
-case .pending:
-    showPendingApprovalMessage()
-```
+Right: a `case .pending` that tells the user approval is pending; unlock
+only when `Transaction.updates` delivers the approved transaction.
 
-### 8. Checking entitlements only once at launch
+### 8. One entitlement check at launch
 
-```swift
-// WRONG: Check once, never update
-func appDidFinish() { Task { await updateEntitlements() } }
+Wrong: computing entitlements once and caching them for the session.
 
-// CORRECT: Re-check on Transaction.updates AND on foreground return
-// Transaction.updates listener handles mid-session changes.
-// Also use .task { await storeManager.updateEntitlements() } on content views.
-```
+Right: recompute from the `Transaction.updates` listener for changes during
+the session, and again when the app returns to the foreground, for example
+`.task { await store.refresh() }` on the content view.
 
-### 9. Missing restore purchases button
+### 9. No restore control
 
-```swift
-// WRONG: No restore option -- App Store rejection risk
-SubscriptionStoreView(groupID: "group_id")
+Wrong: a `SubscriptionStoreView` without restore, which App Review may
+reject.
 
-// CORRECT
-SubscriptionStoreView(groupID: "group_id")
-    .storeButton(.visible, for: .restorePurchases)
-```
+Right: `.storeButton(.visible, for: .restorePurchases)`.
 
-### 10. Subscription views without policy links
+### 10. No policy links
 
-```swift
-// WRONG: No terms or privacy policy
-SubscriptionStoreView(groupID: "group_id")
+Wrong: a subscription screen with no Terms of Service or Privacy Policy.
 
-// CORRECT
-SubscriptionStoreView(groupID: "group_id")
-    .subscriptionStorePolicyDestination(url: termsURL, for: .termsOfService)
-    .subscriptionStorePolicyDestination(url: privacyURL, for: .privacyPolicy)
-```
+Right: both `.subscriptionStorePolicyDestination(url:for:)` calls, one for
+`.termsOfService` and one for `.privacyPolicy`.