PresentationResult

public enum PresentationResult: Sendable, Equatable {
    /// Nothing appeared; the reason says why (errors included, as values).
    case notPresented(NotPresentedReason)
    /// The interaction ran (offer sheet, or the purchase sheet on IAP-first
    /// variants); both funnels plus how it ended.
    case presented(Outcome)

    public struct Outcome: Sendable, Equatable {
        public let advertiser: AdvertiserOutcome  // Encore's claim funnel
        public let publisher: PublisherOutcome    // your purchase funnel
        public let dismissal: DismissReason       // how the sheet ended
    }
}

public enum NotPresentedReason: Equatable, Sendable {
    case notConfigured        // configure() was not called
    case alreadyPresenting    // another sheet is already up
    case unsupportedOS        // requires iOS 17+
    case noOffers             // no offers matched this user
    case experimentControl    // NCL control cohort: exposure logged, no UI by design
    case useCaseUnavailable   // no enabled variant for the requested use case
    case error(EncoreError)   // network, decoding, or integration failure
}

public enum AdvertiserOutcome: Sendable, Equatable {
    case notAttempted
    case claimed(ClaimedOffer)    // claim completed on-device; server verification not (yet) observed
    case verified(ClaimedOffer)   // server-level confirmation observed in-session
    case cooldown                 // claim rejected server-side (cross-offer provisional cooldown)
    case failed(EncoreError)      // claim errored
}

public struct ClaimedOffer: Sendable, Equatable {
    public let offerId: String          // equals campaignId on iOS; both exist so bridges line up
    public let campaignId: String
    public let advertiserName: String
    public let transactionId: String?   // joins to a later .strictUnlockVerified on outcomes
}

public enum PublisherOutcome: Sendable, Equatable {
    case notAttempted
    case purchased
    case cancelled
    case pending     // deferred (Ask to Buy / SCA); may complete later
    case failed
}

public extension PresentationResult {
    /// The offer the user claimed, when the advertiser funnel got that far.
    var claim: ClaimedOffer? { get }

    /// nil ⇔ never presented; .notAttempted ⇔ presented, funnel untouched.
    var advertiser: AdvertiserOutcome? { get }
    var publisher: PublisherOutcome? { get }
    var dismissal: DismissReason? { get }

    /// The presentation-level failure, when that is why nothing appeared.
    var error: EncoreError? { get }
}

let result = await Encore.shared.placement("paywall").show()

if result.claim != nil || result.publisher == .purchased {
    // The user claimed an offer or completed your purchase: continue the
    // unlocked path. The record is the decision; nothing else to consult.
} else {
    result.error.map(log)   // presentation failures are values
    runOriginalFlow()       // dismissed, declined, cooldown, nothing appeared, ...
}

switch result {
case .presented(let outcome):
    analytics.log(outcome.advertiser, outcome.publisher, outcome.dismissal)
case .notPresented(let reason):
    analytics.log(reason)
}