@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.1

package/pipeline/skills/shared/external/storekit/SKILL.md

@@ -16,6 +16,10 @@ When reviewing StoreKit code, explicitly separate "preferred SwiftUI path" from
 direct `product.purchase(options:)` is still valid for lower-level custom
 StoreKit flows.
 
+Full, copyable code for the core flows lives in
+[references/core-patterns.md](references/core-patterns.md). This guide keeps the
+review guidance and short snippets; load the reference for a complete example.
+
 ## Contents
 
 - [Implementation Review Minimums](#implementation-review-minimums)
@@ -24,11 +28,10 @@ StoreKit flows.
 - [Purchase Flow](#purchase-flow)
 - [Transaction.updates Listener](#transactionupdates-listener)
 - [Entitlement Checking](#entitlement-checking)
-- [SubscriptionStoreView (iOS 17+)](#subscriptionstoreview-ios-17)
-- [StoreView (iOS 17+)](#storeview-ios-17)
+- [Store Views (SubscriptionStoreView, StoreView, ProductView)](#store-views-subscriptionstoreview-storeview-productview)
 - [Subscription Status Checking](#subscription-status-checking)
 - [Restore Purchases](#restore-purchases)
-- [App Transaction (App Purchase Verification)](#app-transaction-app-purchase-verification)
+- [App Transaction](#app-transaction)
 - [Purchase Options](#purchase-options)
 - [SwiftUI Purchase Callbacks](#swiftui-purchase-callbacks)
 - [Common Mistakes](#common-mistakes)
@@ -76,20 +79,13 @@ points explicitly:
 Define product IDs as constants. Fetch products with `Product.products(for:)`.
 
 ```swift
-import StoreKit
-
 enum ProductID {
     static let premium = "com.myapp.premium"
-    static let gems100 = "com.myapp.gems100"
     static let monthlyPlan = "com.myapp.monthly"
-    static let yearlyPlan = "com.myapp.yearly"
-    static let all: [String] = [premium, gems100, monthlyPlan, yearlyPlan]
+    static let all: [String] = [premium, monthlyPlan]
 }
 
 let products = try await Product.products(for: ProductID.all)
-for product in products {
-    print("\(product.displayName): \(product.displayPrice)")
-}
 ```
 
 ## Purchase Flow
@@ -105,35 +101,8 @@ Review wording: do not call `product.purchase(options:)` inherently wrong. Say
 "prefer `PurchaseAction` for SwiftUI buttons; keep `product.purchase(options:)`
 for lower-level custom flows that need direct StoreKit control."
 
-```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
-    }
-}
-
-func checkVerified<T>(_ result: VerificationResult<T>) throws -> T {
-    switch result {
-    case .verified(let value): return value
-    case .unverified(_, let error): throw error
-    }
-}
-```
+Full purchase-flow example with `checkVerified` and `.pending` handling:
+references/core-patterns.md#purchase-flow
 
 ## Transaction.updates Listener
 
@@ -146,30 +115,8 @@ In implementation reviews, name the launch-time coverage explicitly: purchases
 made on other devices, Family Sharing changes, subscription renewals, Ask to Buy
 approvals, refunds, revocations, and unfinished transactions.
 
-```swift
-@main
-struct MyApp: App {
-    private let transactionListener: Task<Void, Never>
-
-    init() {
-        transactionListener = Self.listenForTransactions()
-    }
-
-    var body: some Scene {
-        WindowGroup { ContentView() }
-    }
-
-    static func listenForTransactions() -> 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()
-            }
-        }
-    }
-}
-```
+Full launch-time listener wired into `App.init`:
+references/core-patterns.md#transactionupdates-listener
 
 ## Entitlement Checking
 
@@ -185,144 +132,35 @@ covers non-consumables, active or grace-period auto-renewable subscriptions, and
 non-renewing subscriptions; it does not include consumable purchase or delivery
 history." Do not replace this with only a code sample or a revocation check.
 
-```swift
-@Observable
-@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)
-            }
-        }
-        purchasedProductIDs = purchased
-    }
-}
-```
+Full `StoreManager.updateEntitlements()` and the `.currentEntitlementTask`
+SwiftUI gate: references/core-patterns.md#entitlement-checking
 
-### SwiftUI .currentEntitlementTask Modifier
+## Store Views (SubscriptionStoreView, StoreView, ProductView)
 
-```swift
-struct PremiumGatedView: View {
-    @State private var state: EntitlementTaskState<VerificationResult<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()
-            case .success:
-                PaywallView()
-            }
-        }
-        .currentEntitlementTask(for: ProductID.premium) { state in
-            self.state = state
-        }
-    }
-}
-```
-
-## SubscriptionStoreView (iOS 17+)
-
-Built-in SwiftUI view for subscription paywalls. Handles product loading,
-purchase UI, and restore purchases automatically.
+`SubscriptionStoreView(groupID:)` is the built-in subscription paywall; it loads
+products, runs the purchase UI, and can expose restore and policy controls.
+`StoreView(ids:)` merchandises multiple products, and `ProductView(id:)` renders
+a single product. All expose `.onInAppPurchaseCompletion` and
+`.storeButton(.visible, for: .restorePurchases)`.
 
 ```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()
-        }
-    }
-```
-
-### Custom Marketing Content
-
-```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)
-    }
-}
-.containerBackground(.blue.gradient, for: .subscriptionStore)
-```
-
-### Hierarchical Layout
-
-`SubscriptionOptionGroup`, `SubscriptionOptionSection`, and
-`SubscriptionPeriodGroupSet` are iOS 18+ helper views for organizing options
-inside `SubscriptionStoreView`.
-
-```swift
-SubscriptionStoreView(groupID: "YOUR_GROUP_ID") {
-    SubscriptionPeriodGroupSet()
-}
-.subscriptionStoreControlStyle(.picker)
-```
-
-## StoreView (iOS 17+)
-
-Merchandises multiple products with localized names, prices, and purchase buttons.
-
-```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()
-        }
-    }
 ```
 
-### ProductView for Individual Products
+Full paywall, custom marketing content, `StoreView`, and `ProductView` examples:
+references/core-patterns.md#subscriptionstoreview and
+references/core-patterns.md#storeview-and-productview
 
-```swift
-ProductView(id: ProductID.premium) { iconPhase in
-    switch iconPhase {
-    case .success(let image): image.resizable().scaledToFit()
-    case .loading: ProgressView()
-    default: Image(systemName: "star.fill")
-    }
-}
-.productViewStyle(.large)
-```
+For control styles, hierarchical option layouts, offers, and container
+backgrounds see [references/storekit-advanced.md](references/storekit-advanced.md).
 
 ## Subscription Status Checking
 
-```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
-        }
-    }
-    return false
-}
-```
-
-### Renewal States
+Read status with `Product.SubscriptionInfo.status(for: groupID)`; treat
+`.subscribed` and `.inGracePeriod` as active.
 
 | State | Meaning |
 |---|---|
@@ -332,6 +170,10 @@ func checkSubscriptionActive(groupID: String) async throws -> Bool {
 | `.inGracePeriod` | Payment failed but access continues during grace period |
 | `.revoked` | Apple refunded or revoked the subscription |
 
+Full status-check helper: references/core-patterns.md#subscription-status-checking.
+For renewal-state access decisions, expiration reasons, grace period, and billing
+retry see [references/storekit-advanced.md](references/storekit-advanced.md).
+
 ## Restore Purchases
 
 StoreKit 2 handles restoration via `Transaction.currentEntitlements`. Add a
@@ -346,173 +188,46 @@ func restorePurchases() async throws {
 
 On store views: `.storeButton(.visible, for: .restorePurchases)`
 
-## App Transaction (App Purchase Verification)
+## App Transaction
 
-Verify the legitimacy of the app installation. Use for business model changes
-or detecting tampered installations (iOS 16+).
+Verify the legitimacy of the app installation with `AppTransaction.shared`. Use
+for business model changes or detecting tampered installations (iOS 16+); read
+`originalAppVersion` / `originalPurchaseDate` on the verified result and restrict
+features on `.unverified`.
 
-```swift
-func verifyAppPurchase() async {
-    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
-        case .unverified:
-            // Potentially tampered -- restrict features as appropriate
-            break
-        }
-    } catch { /* Could not retrieve app transaction */ }
-}
-```
+Full `verifyAppPurchase()` example: references/core-patterns.md#app-transaction
 
 ## Purchase Options
 
 ```swift
-// App account token for server-side reconciliation
-try await product.purchase(options: [.appAccountToken(UUID())])
-
-// Consumable quantity
-try await product.purchase(options: [.quantity(5)])
-
-// Simulate Ask to Buy in sandbox
-try await product.purchase(options: [.simulatesAskToBuyInSandbox(true)])
+try await product.purchase(options: [.appAccountToken(UUID())]) // server reconciliation
+try await product.purchase(options: [.quantity(5)])             // consumable quantity
+try await product.purchase(options: [.simulatesAskToBuyInSandbox(true)]) // sandbox
 ```
 
 ## SwiftUI Purchase 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()
-    }
-}
-.inAppPurchaseOptions { product in
-    [.appAccountToken(userAccountToken)]
-}
-```
+Store views expose `.onInAppPurchaseStart`, `.onInAppPurchaseCompletion`, and
+`.inAppPurchaseOptions`. In the completion handler, verify the transaction,
+deliver content, then `finish()`.
 
-## Common Mistakes
-
-### 1. Not starting Transaction.updates at app launch
-
-```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 section above)
-```
-
-### 2. Forgetting transaction.finish()
-
-```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()
-```
-
-### 3. Ignoring verification result
-
-```swift
-// WRONG: Using unverified transaction -- security risk
-let transaction = verification.unsafePayloadValue
-
-// CORRECT: Verify before using
-let transaction = try checkVerified(verification)
-```
-
-### 4. Using original In-App Purchase APIs in new StoreKit 2 code
-
-```swift
-// AVOID: Original In-App Purchase APIs
-let request = SKProductsRequest(productIdentifiers: ["com.app.premium"])
-SKPaymentQueue.default().add(payment)
-
-// PREFERRED: StoreKit 2
-let products = try await Product.products(for: ["com.app.premium"])
-let result = try await product.purchase()
-```
-
-### 5. Not checking revocationDate
-
-```swift
-// WRONG: Grants access to refunded purchases
-if case .verified(let transaction) = result {
-    purchased.insert(transaction.productID)
-}
-
-// CORRECT: Skip revoked transactions
-if case .verified(let transaction) = result, transaction.revocationDate == nil {
-    purchased.insert(transaction.productID)
-}
-```
+Full callback example: references/core-patterns.md#swiftui-purchase-callbacks
 
-### 6. Hardcoding prices
-
-```swift
-// WRONG: Wrong for other currencies and regions
-Text("Buy Premium for $4.99")
-
-// CORRECT: Localized price from Product
-Text("Buy \(product.displayName) for \(product.displayPrice)")
-```
-
-### 7. Not handling .pending purchase result
-
-```swift
-// WRONG: Silently drops pending Ask to Buy
-default: break
-
-// CORRECT: Explain approval is pending; unlock only after Transaction.updates
-case .pending:
-    showPendingApprovalMessage()
-```
-
-### 8. Checking entitlements only once at launch
-
-```swift
-// WRONG: Check once, never update
-func appDidFinish() { Task { await updateEntitlements() } }
-
-// 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.
-```
-
-### 9. Missing restore purchases button
-
-```swift
-// WRONG: No restore option -- App Store rejection risk
-SubscriptionStoreView(groupID: "group_id")
-
-// CORRECT
-SubscriptionStoreView(groupID: "group_id")
-    .storeButton(.visible, for: .restorePurchases)
-```
-
-### 10. Subscription views without policy links
+## Common Mistakes
 
-```swift
-// WRONG: No terms or privacy policy
-SubscriptionStoreView(groupID: "group_id")
+The ten most common StoreKit 2 defects, each with a WRONG/CORRECT example, are in
+references/core-patterns.md#common-mistakes:
 
-// CORRECT
-SubscriptionStoreView(groupID: "group_id")
-    .subscriptionStorePolicyDestination(url: termsURL, for: .termsOfService)
-    .subscriptionStorePolicyDestination(url: privacyURL, for: .privacyPolicy)
-```
+1. Not starting `Transaction.updates` at app launch
+2. Forgetting `transaction.finish()`
+3. Ignoring the verification result
+4. Using original In-App Purchase APIs in new StoreKit 2 code
+5. Not checking `revocationDate`
+6. Hardcoding prices instead of `product.displayPrice`
+7. Not handling the `.pending` purchase result
+8. Checking entitlements only once at launch
+9. Missing restore purchases button
+10. Subscription views without Terms / Privacy policy links
 
 ## Review Checklist
 
@@ -536,8 +251,19 @@ SubscriptionStoreView(groupID: "group_id")
 
 ## References
 
-- See [references/app-review-guidelines.md](references/app-review-guidelines.md) for IAP rules (Guideline 3.1.1), subscription display requirements, and rejection prevention.
-- See [references/storekit-advanced.md](references/storekit-advanced.md) for subscription control styles, offer management, testing patterns, and advanced subscription handling.
+- See [references/core-patterns.md](references/core-patterns.md) for full core
+  code: purchase flow, launch-time transaction listener, entitlement checking,
+  store views, subscription status, app transaction, purchase callbacks, and the
+  ten annotated common mistakes. Load it when writing or reviewing a core flow.
+- See [references/storekit-advanced.md](references/storekit-advanced.md) for
+  subscription control styles, offer management (introductory, promotional,
+  win-back, offer codes), server-side validation, StoreKit testing, renewal
+  states, grace period/billing retry, refunds, and Family Sharing. Load it for
+  offers, testing setup, or advanced subscription handling.
+- See [references/app-review-guidelines.md](references/app-review-guidelines.md)
+  for IAP rules (Guideline 3.1.1), subscription display requirements, and
+  rejection prevention. Load it before a submission or when diagnosing a payment
+  rejection.
 - For submission, privacy, metadata, screenshots, and rejection-risk audits use `app-store-review`.
 - For keyword, screenshot-caption, ranking, and conversion strategy use `app-store-optimization`.
 - Official Apple docs: [Choosing a StoreKit API](https://sosumi.ai/documentation/storekit/choosing-a-storekit-api-for-in-app-purchases), [Transaction.updates](https://sosumi.ai/documentation/storekit/transaction/updates), [Transaction.currentEntitlements](https://sosumi.ai/documentation/storekit/transaction/currententitlements),