Add embedded checkout support to CheckoutWebViewController and CheckoutDelegate

This commit integrates embedded checkout functionality into the view controller
layer and delegate protocol while maintaining backward compatibility.

CheckoutWebViewController changes:
- Added CheckoutOptions parameter to initializer for embedded checkout configuration
- Implemented embedded checkout delegate methods:
  - checkoutViewDidChangeState() for state change events
  - checkoutViewDidComplete() for completion with embedded payload
  - checkoutViewDidFail() for error handling with embedded error payloads
  - checkoutViewDidEmitWebPixelEvent() for embedded web pixel events
- Enhanced error recovery logic for embedded checkout error types

CheckoutDelegate changes:
- Extended protocol with embedded checkout event methods
- Added default implementations for all new methods to maintain compatibility
- Documented embedded checkout methods with Schema 2025-04 specification

All changes are backward compatible - existing implementations continue
to work unchanged while new embedded checkout functionality is available
for apps that need it.

Author: tiagocandido

Sources/ShopifyCheckoutSheetKit/CheckoutDelegate.swift

@@ -44,6 +44,20 @@ public protocol CheckoutDelegate: AnyObject {
 
     /// Tells te delegate that a Web Pixel event was emitted
     func checkoutDidEmitWebPixelEvent(event: PixelEvent)
+    
+    // MARK: - Embedded Checkout Events (Schema 2025-04)
+    
+    /// Tells the delegate that the embedded checkout state has changed
+    func checkoutDidChangeState(state: CheckoutStatePayload)
+    
+    /// Tells the delegate that the embedded checkout successfully completed with order details
+    func checkoutDidComplete(payload: CheckoutCompletePayload)
+    
+    /// Tells the delegate that the embedded checkout encountered one or more errors
+    func checkoutDidFail(errors: [ErrorPayload])
+    
+    /// Tells the delegate that an embedded checkout web pixel event was emitted
+    func checkoutDidEmitWebPixelEvent(payload: WebPixelsPayload)
 }
 
 extension CheckoutDelegate {
@@ -68,4 +82,22 @@ extension CheckoutDelegate {
             UIApplication.shared.open(url)
         }
     }
+    
+    // MARK: - Embedded Checkout Default Implementations
+    
+    public func checkoutDidChangeState(state: CheckoutStatePayload) {
+        /// No-op by default
+    }
+    
+    public func checkoutDidComplete(payload: CheckoutCompletePayload) {
+        /// No-op by default
+    }
+    
+    public func checkoutDidFail(errors: [ErrorPayload]) {
+        /// No-op by default
+    }
+    
+    public func checkoutDidEmitWebPixelEvent(payload: WebPixelsPayload) {
+        /// No-op by default
+    }
 }

Sources/ShopifyCheckoutSheetKit/CheckoutWebViewController.swift

@@ -62,7 +62,7 @@ class CheckoutWebViewController: UIViewController, UIAdaptivePresentationControl
 
     // MARK: Initializers
 
-    public init(checkoutURL url: URL, delegate: CheckoutDelegate? = nil, entryPoint: MetaData.EntryPoint? = nil) {
+    public init(checkoutURL url: URL, delegate: CheckoutDelegate? = nil, entryPoint: MetaData.EntryPoint? = nil, options: CheckoutOptions? = nil) {
         checkoutURL = url
         self.delegate = delegate
 
@@ -71,6 +71,9 @@ class CheckoutWebViewController: UIViewController, UIAdaptivePresentationControl
         checkoutView.scrollView.contentInsetAdjustmentBehavior = .never
         self.checkoutView = checkoutView
 
+        // Set checkout options for embedded checkout support
+        checkoutView.checkoutOptions = options
+
         super.init(nibName: nil, bundle: nil)
 
         title = ShopifyCheckoutSheetKit.configuration.title
@@ -246,6 +249,39 @@ extension CheckoutWebViewController: CheckoutWebViewDelegate {
     func checkoutViewDidEmitWebPixelEvent(event: PixelEvent) {
         delegate?.checkoutDidEmitWebPixelEvent(event: event)
     }
+    
+    // MARK: - Embedded Checkout Delegate Methods
+    
+    func checkoutViewDidChangeState(state: CheckoutStatePayload) {
+        delegate?.checkoutDidChangeState(state: state)
+    }
+
+    func checkoutViewDidComplete(payload: CheckoutCompletePayload) {
+        ConfettiCannon.fire(in: view)
+        CheckoutWebView.invalidate(disconnect: false)
+        delegate?.checkoutDidComplete(payload: payload)
+    }
+
+    func checkoutViewDidFail(errors: [ErrorPayload]) {
+        CheckoutWebView.invalidate()
+        delegate?.checkoutDidFail(errors: errors)
+
+        // For embedded checkout errors, attempt recovery based on error group and URL type
+        let shouldAttemptRecovery = errors.contains { error in
+            // Only recover from specific recoverable network errors (5xx server errors)
+            return error.group == "network" && error.type == "server_error" && (error.code?.hasPrefix("5") == true)
+        } && !CheckoutURL(from: checkoutURL).isMultipassURL()
+
+        if shouldAttemptRecovery {
+            presentFallbackViewController(url: checkoutURL)
+        } else {
+            dismiss(animated: true)
+        }
+    }
+
+    func checkoutViewDidEmitWebPixelEvent(payload: WebPixelsPayload) {
+        delegate?.checkoutDidEmitWebPixelEvent(payload: payload)
+    }
 
     private func canRecoverFromError(_: CheckoutError) -> Bool {
         /// Reuse of multipass tokens will cause 422 errors. A new token must be generated