Add View/Edit FI saved payment method UI and checkout integration

Sources/BraintreePayPal/BTPayPalCheckoutRequest.swift

@@ -250,11 +250,25 @@ import BraintreeCore
 
 extension BTPayPalCheckoutRequest {
 
-    /// :nodoc: Not part of the public API. `@nonobjc` keeps this out of the generated Objective-C header.
+    /// :nodoc: Not part of the public API. `public` is required by `@_spi` because the symbol
+    /// crosses a module boundary; `@_spi` is what restricts visibility, and the method does not
+    /// exist under a plain `import BraintreePayPal`.
+    ///
+    /// `@_spi` has no bearing on Objective-C header generation, and this type is `@objcMembers`,
+    /// so `@nonobjc` guards that side independently. It is inert while this signature stays
+    /// `async rethrows`, and load-bearing if it is ever simplified.
+    ///
+    /// Scoped rather than a plain setter so the merchant's request is not left in edit mode after
+    /// the call — they may reuse the same instance for an ordinary checkout.
     @_documentation(visibility: private)
     @_spi(BraintreePayPalSavedPaymentMethod)
     @nonobjc
-    public func enableEditBillingAgreement() {
+    public func withEditBillingAgreement(
+        _ body: () async throws -> BTPayPalAccountNonce
+    ) async rethrows -> BTPayPalAccountNonce {
+        let previous = editBillingAgreement
         editBillingAgreement = true
+        defer { editBillingAgreement = previous }
+        return try await body()
     }
 }

Sources/BraintreePayPalSavedPaymentMethod/BTPayPalCreditMessageItem.swift

@@ -0,0 +1,50 @@
+import Foundation
+
+#if canImport(BraintreeCore)
+import BraintreeCore
+#endif
+
+/// A single block of a presentment message. Blocks are returned in the order they must be displayed.
+struct BTPayPalCreditMessageItem: Equatable {
+
+    // MARK: - Internal Properties
+
+    /// The kind of block, or `nil` when PayPal returns a type this SDK version does not recognize.
+    let type: BTPayPalCreditMessageItemType?
+
+    /// The text to display, for example `"4 interest-free payments of $13.75 with "`.
+    let text: String?
+
+    /// The screen reader text for blocks whose `text` relies on symbols or abbreviations.
+    let alternativeText: String?
+
+    /// The URL to open when a `link` or `image` block is tapped.
+    let clickURL: URL?
+
+    /// The image to render for an `image` block.
+    let sourceURL: URL?
+
+    /// A non-unique identifier for the block, for example `"periodic_payment_count"` or `"paypal_logo"`.
+    let name: String?
+
+    /// Whether `clickURL` may be loaded in an embedded web view rather than an external browser.
+    let isEmbeddable: Bool
+
+    // MARK: - Initializer
+
+    /// Parses a single content block of a presentment message.
+    /// - Returns: `nil` when the block is not an object.
+    init?(json: BTJSON) {
+        guard json.isObject else {
+            return nil
+        }
+
+        self.type = json["type"].asString().flatMap(BTPayPalCreditMessageItemType.init(rawValue:))
+        self.text = json["text"].asString()
+        self.alternativeText = json["alternative_text"].asString()
+        self.clickURL = json["click_url"].asURL()
+        self.sourceURL = json["source_url"].asURL()
+        self.name = json["name"].asString()
+        self.isEmbeddable = json["embeddable"].asBool() ?? false
+    }
+}

Sources/BraintreePayPalSavedPaymentMethod/BTPayPalCreditMessageItemType.swift

@@ -0,0 +1,14 @@
+import Foundation
+
+/// The kind of content block making up a presentment message.
+enum BTPayPalCreditMessageItemType: String {
+
+    /// A logo image, with `alternativeText` as its alt text.
+    case image = "IMAGE"
+
+    /// Tappable copy that opens `clickURL`, such as "Learn more".
+    case link = "LINK"
+
+    /// Plain copy.
+    case text = "TEXT"
+}

Sources/BraintreePayPalSavedPaymentMethod/BTPayPalCreditMessagingLanderView.swift

@@ -0,0 +1,16 @@
+import SwiftUI
+import SafariServices
+
+/// Presents the credit-messaging "Learn more" lander (`click_url`) in an
+/// `SFSafariViewController`, giving buyers Safari's built-in security and reader chrome
+/// without pulling in a new dependency or triggering an app-switch consent alert.
+struct BTPayPalCreditMessagingLanderView: UIViewControllerRepresentable {
+
+    let url: URL
+
+    func makeUIViewController(context: Context) -> SFSafariViewController {
+        SFSafariViewController(url: url)
+    }
+
+    func updateUIViewController(_ controller: SFSafariViewController, context: Context) {}
+}

Sources/BraintreePayPalSavedPaymentMethod/BTPayPalCreditMessagingResult.swift

@@ -0,0 +1,52 @@
+import Foundation
+
+#if canImport(BraintreeCore)
+import BraintreeCore
+#endif
+
+/// The Pay Later message to display alongside a vaulted PayPal payment method.
+struct BTPayPalCreditMessagingResult: Equatable {
+
+    // MARK: - Internal Properties
+
+    /// The identifier of the message that was selected.
+    let messageID: String?
+
+    /// The template the message was built from, for example `"PLST_SQ"`.
+    let messageType: String?
+
+    /// The main text and logo blocks of the message.
+    let mainItems: [BTPayPalCreditMessageItem]
+
+    /// Legal disclaimers that PayPal requires to be displayed with `mainItems`.
+    let disclaimerItems: [BTPayPalCreditMessageItem]
+
+    /// The interactive blocks of the message, such as the "Learn more" link.
+    let actionItems: [BTPayPalCreditMessageItem]
+
+    /// The tracking beacon to fire once the message is on screen.
+    let impressionURL: URL?
+
+    // MARK: - Initializer
+
+    /// Parses the preferred message out of a `v2/credit/fetch-presentment-messages` response.
+    /// - Returns: `nil` when PayPal has no message to show for this buyer.
+    init?(json: BTJSON) {
+        let preferredMessage = json["messages"][0]["preferred_message"]
+        let content = preferredMessage["content"]
+        let mainItems = content["main_items"].asArray()?.compactMap(BTPayPalCreditMessageItem.init) ?? []
+
+        // Reporting success with no copy would fire the impression beacon for a message the buyer never saw.
+        // Image blocks carry their copy in `alternativeText` rather than `text`.
+        guard mainItems.contains(where: { $0.text?.isEmpty == false || $0.alternativeText?.isEmpty == false }) else {
+            return nil
+        }
+
+        self.messageID = preferredMessage["id"].asString()
+        self.messageType = preferredMessage["type"].asString()
+        self.mainItems = mainItems
+        self.disclaimerItems = content["disclaimer_items"].asArray()?.compactMap(BTPayPalCreditMessageItem.init) ?? []
+        self.actionItems = content["action_items"].asArray()?.compactMap(BTPayPalCreditMessageItem.init) ?? []
+        self.impressionURL = preferredMessage["analytics"]["impression_url"].asURL()
+    }
+}

Sources/BraintreePayPalSavedPaymentMethod/BTPayPalFundingInstrumentFetchType.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+/// Determines which funding instrument the Braintree GraphQL API resolves, and therefore which identity field is required.
+enum BTPayPalFundingInstrumentFetchType: String {
+
+    /// The default funding instrument vaulted on the buyer's billing agreement. Resolved from the client token's payment method ID JWT.
+    case stickyFI = "STICKY_FI"
+
+    /// The funding instrument the buyer selected while approving a checkout. Resolved from that order's ID.
+    case fiFromApprovedCheckout = "FI_FROM_APPROVED_CHECKOUT"
+}

Sources/BraintreePayPalSavedPaymentMethod/BTPayPalPayer.swift

@@ -0,0 +1,30 @@
+import Foundation
+
+#if canImport(BraintreeCore)
+import BraintreeCore
+#endif
+
+/// The buyer's PayPal account.
+struct BTPayPalPayer: Equatable {
+
+    // MARK: - Internal Properties
+
+    /// The email address associated with the buyer's PayPal account.
+    let email: String?
+
+    /// Whether the buyer is allowed to change the funding instrument PayPal will charge.
+    let isEditable: Bool
+
+    // MARK: - Initializer
+
+    /// Parses the `payer` field of a funding instrument details response.
+    /// - Returns: `nil` when PayPal returns no payer.
+    init?(json: BTJSON) {
+        guard json.isObject else {
+            return nil
+        }
+
+        self.email = json["email"].asString()
+        self.isEditable = json["editable"].asBool() ?? false
+    }
+}

Sources/BraintreePayPalSavedPaymentMethod/BTPayPalSavedPaymentMethod.swift

@@ -0,0 +1,42 @@
+import Foundation
+
+#if canImport(BraintreeCore)
+import BraintreeCore
+#endif
+
+/// A funding instrument PayPal can charge on the buyer's behalf.
+struct BTPayPalSavedPaymentMethod: Equatable {
+
+    // MARK: - Internal Properties
+
+    /// The kind of funding instrument, or `nil` when PayPal returns a type this SDK version does not recognize.
+    let type: BTPayPalSavedPaymentMethodType?
+
+    /// The display name of the funding instrument, for example `"Visa"` or `"CREDIT UNION 1"`.
+    let label: String?
+
+    /// The card art or bank glyph to render alongside the label.
+    let imageURL: URL?
+
+    /// The last digits of the funding instrument's account number.
+    let lastDigits: String?
+
+    /// A further qualifier on `type`, for example the card's product name.
+    let subtype: String?
+
+    // MARK: - Initializer
+
+    /// Parses a single entry of the `paymentMethods` array.
+    /// - Returns: `nil` when the entry is not an object.
+    init?(json: BTJSON) {
+        guard json.isObject else {
+            return nil
+        }
+
+        self.type = json["type"].asString().flatMap(BTPayPalSavedPaymentMethodType.init(rawValue:))
+        self.label = json["label"].asString()
+        self.imageURL = json["imageUrl"].asURL()
+        self.lastDigits = json["lastDigits"].asString()
+        self.subtype = json["subtype"].asString()
+    }
+}