@mmerterden/multi-agent-pipeline 20.0.0 → 20.2.0

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

@@ -0,0 +1,371 @@
+# 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
+[storekit-advanced.md](storekit-advanced.md).
+
+## 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)
+
+## Purchase Flow
+
+Handle every `PurchaseResult`, verify before access, deliver durably, then
+finish.
+
+```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
+    }
+}
+```
+
+## Transaction.updates Listener
+
+Start at app launch, not when a paywall appears. Keep the task retained for the
+app lifetime.
+
+```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()
+            }
+        }
+    }
+}
+```
+
+## Entitlement Checking
+
+Use `Transaction.currentEntitlements`; skip transactions with a non-nil
+`revocationDate`. Track consumable fulfillment in your own app or server ledger.
+
+```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
+    }
+}
+```
+
+### SwiftUI .currentEntitlementTask Modifier
+
+```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
+
+Built-in SwiftUI view for subscription paywalls. Handles product loading,
+purchase UI, and restore purchases automatically.
+
+```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)
+```
+
+For hierarchical layouts (`SubscriptionOptionGroup`, `SubscriptionOptionSection`,
+`SubscriptionPeriodGroupSet`) and control styles see
+[storekit-advanced.md](storekit-advanced.md).
+
+## StoreView and ProductView
+
+Merchandise 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()
+        }
+    }
+```
+
+```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)
+```
+
+## 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
+}
+```
+
+## App Transaction
+
+Verify the legitimacy of the app installation. Use for business model changes
+or detecting tampered installations (iOS 16+).
+
+```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 */ }
+}
+```
+
+## 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)]
+}
+```
+
+## 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 Listener 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)
+}
+```
+
+### 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
+
+```swift
+// WRONG: No terms or privacy policy
+SubscriptionStoreView(groupID: "group_id")
+
+// CORRECT
+SubscriptionStoreView(groupID: "group_id")
+    .subscriptionStorePolicyDestination(url: termsURL, for: .termsOfService)
+    .subscriptionStorePolicyDestination(url: privacyURL, for: .privacyPolicy)
+```

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

@@ -225,18 +225,9 @@ struct ToggleFavoriteIntent: AppIntent {
     }
 }
 
-struct InteractiveWidgetView: View {
-    let entry: FavoriteEntry
-    var body: some View {
-        HStack {
-            Text(entry.itemName)
-            Spacer()
-            Button(intent: ToggleFavoriteIntent(itemID: entry.itemID)) {
-                Image(systemName: entry.isFavorite ? "star.fill" : "star")
-            }
-        }
-        .padding()
-    }
+// In the widget view:
+Button(intent: ToggleFavoriteIntent(itemID: entry.itemID)) {
+    Image(systemName: entry.isFavorite ? "star.fill" : "star")
 }
 ```
 
@@ -261,53 +252,11 @@ struct DeliveryAttributes: ActivityAttributes {
 
 ### ActivityConfiguration
 
-Provide Lock Screen content and Dynamic Island closures in the widget bundle.
-
-```swift
-struct DeliveryActivityWidget: Widget {
-    var body: some WidgetConfiguration {
-        ActivityConfiguration(for: DeliveryAttributes.self) { context in
-            VStack(alignment: .leading) {
-                Text(context.attributes.restaurantName).font(.headline)
-                HStack {
-                    Text("Driver: \(context.state.driverName)")
-                    Spacer()
-                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
-                }
-            }
-            .padding()
-        } dynamicIsland: { context in
-            DynamicIsland {
-                DynamicIslandExpandedRegion(.leading) {
-                    Image(systemName: "box.truck.fill").font(.title2)
-                }
-                DynamicIslandExpandedRegion(.trailing) {
-                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
-                        .font(.caption)
-                }
-                DynamicIslandExpandedRegion(.center) {
-                    Text(context.attributes.restaurantName).font(.headline)
-                }
-                DynamicIslandExpandedRegion(.bottom) {
-                    HStack {
-                        ForEach(DeliveryStep.allCases, id: \.self) { step in
-                            Image(systemName: step.icon)
-                                .foregroundStyle(step <= context.state.currentStep ? .primary : .tertiary)
-                        }
-                    }
-                }
-            } compactLeading: {
-                Image(systemName: "box.truck.fill")
-            } compactTrailing: {
-                Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
-                    .frame(width: 40).monospacedDigit()
-            } minimal: {
-                Image(systemName: "box.truck.fill")
-            }
-        }
-    }
-}
-```
+Provide Lock Screen content and Dynamic Island closures in the widget bundle. The
+`ActivityConfiguration(for:)` body returns the Lock Screen view; its
+`dynamicIsland` closure declares the expanded regions plus `compactLeading`,
+`compactTrailing`, and `minimal`. See [references/widgetkit-advanced.md](references/widgetkit-advanced.md)
+("Live Activity Full ActivityConfiguration Example") for a complete implementation.
 
 ### Dynamic Island Regions
 
@@ -339,8 +288,11 @@ await activity.end(final, dismissalPolicy: .after(.now.addingTimeInterval(3600))
 
 ## Control Center Widgets (iOS 18+)
 
+Wrap a `ControlWidgetButton` or `ControlWidgetToggle` in a
+`StaticControlConfiguration` (or `AppIntentControlConfiguration`). Each control
+runs an `AppIntent` action.
+
 ```swift
-// Button control
 struct OpenCameraControl: ControlWidget {
     var body: some ControlWidgetConfiguration {
         StaticControlConfiguration(kind: "OpenCamera") {
@@ -351,41 +303,18 @@ struct OpenCameraControl: ControlWidget {
         .displayName("Open Camera")
     }
 }
-
-// Toggle control with value provider
-struct FlashlightControl: ControlWidget {
-    var body: some ControlWidgetConfiguration {
-        StaticControlConfiguration(kind: "Flashlight", provider: FlashlightValueProvider()) { value in
-            ControlWidgetToggle(isOn: value, action: ToggleFlashlightIntent()) {
-                Label("Flashlight", systemImage: value ? "flashlight.on.fill" : "flashlight.off.fill")
-            }
-        }
-        .displayName("Flashlight")
-    }
-}
 ```
 
-## Lock Screen Widgets
+See [references/widgetkit-advanced.md](references/widgetkit-advanced.md) ("Control Center Control
+Examples") for a toggle control backed by a value provider.
 
-Use accessory families and `AccessoryWidgetBackground`.
+## Lock Screen Widgets
 
-```swift
-struct StepsWidget: Widget {
-    let kind = "StepsWidget"
-    var body: some WidgetConfiguration {
-        StaticConfiguration(kind: kind, provider: StepsProvider()) { entry in
-            ZStack {
-                AccessoryWidgetBackground()
-                VStack {
-                    Image(systemName: "figure.walk")
-                    Text("\(entry.stepCount)").font(.headline)
-                }
-            }
-        }
-        .supportedFamilies([.accessoryCircular, .accessoryRectangular, .accessoryInline])
-    }
-}
-```
+Use accessory families (`.accessoryCircular`, `.accessoryRectangular`,
+`.accessoryInline`) and wrap content in `AccessoryWidgetBackground()` for the
+standard translucent backing. See [references/widgetkit-advanced.md](references/widgetkit-advanced.md)
+("Lock Screen Accessory Widget Example") for a full widget, and
+"AccessoryWidgetBackground" for rendering-mode adaptation.
 
 ## StandBy Mode
 
@@ -430,16 +359,11 @@ Adapt widgets to the Liquid Glass visual style using `WidgetAccentedRenderingMod
 
 ### WidgetPushHandler
 
-Enable push-based timeline reloads without scheduled polling.
-
-```swift
-struct MyWidgetPushHandler: WidgetPushHandler {
-    func pushTokenDidChange(_ pushInfo: WidgetPushInfo, widgets: [WidgetInfo]) {
-        let tokenString = pushInfo.token.map { String(format: "%02x", $0) }.joined()
-        // Send tokenString to your server
-    }
-}
-```
+Enable push-based timeline reloads without scheduled polling: implement
+`WidgetPushHandler.pushTokenDidChange(_:widgets:)`, register the token with your
+server, and send an APNs push to trigger a reload. See
+[references/widgetkit-advanced.md](references/widgetkit-advanced.md) ("Push-Based Timeline Reloads") for
+the handler plus the `ControlPushHandler` equivalent.
 
 ### CarPlay Widgets
 

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

@@ -9,6 +9,9 @@
 - [Multiple Widget Support in WidgetBundle](#multiple-widget-support-in-widgetbundle)
 - [Widget Previews and Snapshots](#widget-previews-and-snapshots)
 - [AccessoryWidgetBackground](#accessorywidgetbackground)
+- [Lock Screen Accessory Widget Example](#lock-screen-accessory-widget-example)
+- [Live Activity Full ActivityConfiguration Example](#live-activity-full-activityconfiguration-example)
+- [Control Center Control Examples](#control-center-control-examples)
 - [Dynamic Island Expanded Layout Patterns](#dynamic-island-expanded-layout-patterns)
 - [Alert Configuration for Live Activities](#alert-configuration-for-live-activities)
 - [Push Notification Support for Live Activities](#push-notification-support-for-live-activities)
@@ -390,6 +393,110 @@ var body: some View {
 Use `.widgetAccentable()` to mark views that should receive the accent tint in
 `.accented` rendering mode.
 
+## Lock Screen Accessory Widget Example
+
+A full Lock Screen widget using accessory families and `AccessoryWidgetBackground`.
+
+```swift
+struct StepsWidget: Widget {
+    let kind = "StepsWidget"
+    var body: some WidgetConfiguration {
+        StaticConfiguration(kind: kind, provider: StepsProvider()) { entry in
+            ZStack {
+                AccessoryWidgetBackground()
+                VStack {
+                    Image(systemName: "figure.walk")
+                    Text("\(entry.stepCount)").font(.headline)
+                }
+            }
+        }
+        .supportedFamilies([.accessoryCircular, .accessoryRectangular, .accessoryInline])
+    }
+}
+```
+
+## Live Activity Full ActivityConfiguration Example
+
+A complete `ActivityConfiguration` with Lock Screen content and the Dynamic
+Island closures (expanded regions, compact, minimal).
+
+```swift
+struct DeliveryActivityWidget: Widget {
+    var body: some WidgetConfiguration {
+        ActivityConfiguration(for: DeliveryAttributes.self) { context in
+            VStack(alignment: .leading) {
+                Text(context.attributes.restaurantName).font(.headline)
+                HStack {
+                    Text("Driver: \(context.state.driverName)")
+                    Spacer()
+                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
+                }
+            }
+            .padding()
+        } dynamicIsland: { context in
+            DynamicIsland {
+                DynamicIslandExpandedRegion(.leading) {
+                    Image(systemName: "box.truck.fill").font(.title2)
+                }
+                DynamicIslandExpandedRegion(.trailing) {
+                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
+                        .font(.caption)
+                }
+                DynamicIslandExpandedRegion(.center) {
+                    Text(context.attributes.restaurantName).font(.headline)
+                }
+                DynamicIslandExpandedRegion(.bottom) {
+                    HStack {
+                        ForEach(DeliveryStep.allCases, id: \.self) { step in
+                            Image(systemName: step.icon)
+                                .foregroundStyle(step <= context.state.currentStep ? .primary : .tertiary)
+                        }
+                    }
+                }
+            } compactLeading: {
+                Image(systemName: "box.truck.fill")
+            } compactTrailing: {
+                Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
+                    .frame(width: 40).monospacedDigit()
+            } minimal: {
+                Image(systemName: "box.truck.fill")
+            }
+        }
+    }
+}
+```
+
+## Control Center Control Examples
+
+Button and toggle controls for Control Center (iOS 18+). A toggle can read its
+current state from a value provider.
+
+```swift
+// Button control
+struct OpenCameraControl: ControlWidget {
+    var body: some ControlWidgetConfiguration {
+        StaticControlConfiguration(kind: "OpenCamera") {
+            ControlWidgetButton(action: OpenCameraIntent()) {
+                Label("Camera", systemImage: "camera.fill")
+            }
+        }
+        .displayName("Open Camera")
+    }
+}
+
+// Toggle control with value provider
+struct FlashlightControl: ControlWidget {
+    var body: some ControlWidgetConfiguration {
+        StaticControlConfiguration(kind: "Flashlight", provider: FlashlightValueProvider()) { value in
+            ControlWidgetToggle(isOn: value, action: ToggleFlashlightIntent()) {
+                Label("Flashlight", systemImage: value ? "flashlight.on.fill" : "flashlight.off.fill")
+            }
+        }
+        .displayName("Flashlight")
+    }
+}
+```
+
 ## Dynamic Island Expanded Layout Patterns
 
 ### Full Layout Example