Payments Module

public protocol PaymentsClient: Sendable {
    /// Configure the payments system. Call once at app start. Idempotent.
    func configure(_ config: PaymentsConfig) async

    /// Stream of subscription state changes
    func states() -> AsyncStream<PaymentsState>

    /// Get current subscription state immediately (cached)
    func currentState() async -> PaymentsState

    /// Purchase a product by ID
    func purchase(productID: String) async throws

    /// Restore previous purchases, returning the resulting state
    @discardableResult
    func restore() async throws -> PaymentsState

    /// Prefetch offerings for the paywall (optional optimization)
    func prefetchOfferings() async

    /// Get available product offerings with pricing
    func getOfferings() async throws -> [PaymentsOffering]
}

public struct PaymentsState: Sendable, Equatable {
    public let isSubscribed: Bool
    public let activeEntitlementIDs: Set<String>
    public let expirationDate: Date?
    public let productID: String?
}

// SwiftAIBoilerplatePro.swift — loadPaymentsConfig()
private func loadPaymentsConfig() throws -> PaymentsConfig {
    #if DEBUG
    // In DEBUG with AUTH_BYPASS=1, return a placeholder config (the mock client gets sample offerings)
    if ProcessInfo.processInfo.environment["AUTH_BYPASS"] == "1" {
        return PaymentsConfig(apiKey: "debug_mode_placeholder_key", entitlementID: "pro")
    }
    #endif

    guard !AppConfiguration.REVENUECAT_API_KEY.isEmpty else {
        throw AppError.validation(message: "Missing REVENUECAT_API_KEY. Add to Config/Secrets.xcconfig")
    }

    return PaymentsConfig(
        apiKey: AppConfiguration.REVENUECAT_API_KEY,
        entitlementID: AppConfiguration.RC_ENTITLEMENT_ID
    )
}

// CompositionRoot.swift
#if DEBUG
if ProcessInfo.processInfo.environment["AUTH_BYPASS"] != "0" {
    self.paymentsClient = PreviewMocks.MockPaymentsClient()
} else {
    self.paymentsClient = Payments.RevenueCatClient(config: paymentsConfig)
}
#else
self.paymentsClient = Payments.RevenueCatClient(config: paymentsConfig)
#endif

// RevenueCatClient automatically:
// - Syncs with App Store
// - Tracks subscription status via the customer info stream
// - Maps RevenueCat receipts to PaymentsState
// - Emits state changes via states() (AsyncStream)

# From RevenueCat Dashboard → Project Settings → API Keys
REVENUECAT_API_KEY = YOUR_RC_KEY

# Entitlement ID from RevenueCat Dashboard
RC_ENTITLEMENT_ID = pro

// PaywallViewModel.purchase() buys the selected offering
public func purchase() async {
    guard let offering = selectedOffering else {
        errorMessage = "Please select a subscription plan"
        return
    }
    do {
        try await paymentsClient.purchase(productID: offering.id)
        // Success! State updates automatically via states()
    } catch let paymentsError as PaymentsError {
        errorMessage = paymentsError.asAppError().localizedUserMessage
    } catch {
        errorMessage = AppError.from(error).localizedUserMessage
    }
}

// PaywallViewModel.restore() returns the resulting state directly
public func restore() async {
    do {
        let restoredState = try await paymentsClient.restore()
        isSubscribed = restoredState.isSubscribed
        if !restoredState.isSubscribed {
            errorMessage = "No active subscription found to restore."
        }
    } catch let paymentsError as PaymentsError {
        errorMessage = paymentsError.asAppError().localizedUserMessage
    } catch {
        errorMessage = AppError.from(error).localizedUserMessage
    }
}

// Check if user has pro access
let state = await paymentsClient.currentState()
if state.isSubscribed {
    // Show premium features
} else {
    // Show paywall
}

// Illustrative paywall presentation — SettingsView triggers `showPaywall`
// and presents PaywallView in a sheet:
if !viewModel.isSubscribed {
    Button("Go Premium") {
        showPaywall = true
    }
}
.sheet(isPresented: $showPaywall) {
    PaywallView(paymentsClient: viewModel.paymentsClientAccessor) {
        showPaywall = false
    }
}

// 1. Create the product in App Store Connect
// 2. Add it to your RevenueCat offering / package
// 3. PaywallViewModel.offerings picks it up; PaywallView renders a
//    PlanOptionCard for it automatically:
ForEach(viewModel.offerings) { offering in
    PlanOptionCard(
        offering: offering,
        isSelected: viewModel.selectedOffering?.id == offering.id,
        onSelect: { viewModel.selectOffering(offering) }
    )
}

// Pattern: gate a free-tier limit behind the pro entitlement
func canSendMessage(todayCount: () async -> Int) async -> Bool {
    let state = await paymentsClient.currentState()

    if state.isSubscribed {
        return true  // Unlimited for pro
    } else {
        return await todayCount() < 20  // Your own free-tier limit
    }
}

// Multiple entitlements
if state.activeEntitlementIDs.contains("pro") {
    // Pro features
}

if state.activeEntitlementIDs.contains("premium_support") {
    // Priority support
}

final class MockPaymentsClient: PaymentsClient, @unchecked Sendable {
    func configure(_ config: PaymentsConfig) {}
    func states() -> AsyncStream<PaymentsState> { /* yields .free */ }
    func currentState() async -> PaymentsState { PaymentsState(isSubscribed: false) }
    func purchase(productID: String) async throws {}
    @discardableResult
    func restore() async throws -> PaymentsState { PaymentsState(isSubscribed: false) }
    func prefetchOfferings() async {}
    func getOfferings() async throws -> [PaymentsOffering] { /* sample monthly + annual */ }
}