Refactor Error Handling for AcceleratedCheckouts

[markmur]

🚨 Breaking Changes

1. Removed Deprecated Callback Methods

The following methods have been completely removed:

• .onComplete { }
• .onCancel { }
• .onFail { }

2. New CheckoutDelegate Pattern

Use .checkout(delegate:) to handle checkout flow events:

  class MyCheckoutDelegate: CheckoutDelegate {
      func checkoutDidComplete(event: CheckoutCompletedEvent) {
          // Handle successful checkout
      }

      func checkoutDidFail(error: CheckoutError) {
          // Handle checkout process failures
      }

      func checkoutDidCancel() {
          // Handle checkout cancellation
      }
  }

3. New Validation Error Handling

.onError { } now handles validation errors only (not checkout failures):

  public enum AcceleratedCheckoutError: Error {
      /// Cart validation failed - API correctly rejected input data
      case validation(ValidationError)
  }

Migration Guide

✅ New API:

+  class MyDelegate: CheckoutDelegate {
+      func checkoutDidComplete(event: CheckoutCompletedEvent) {
+          CartManager.shared.resetCart()
+          print("Order created: \(event.orderDetails.id)")
+      }
+
+      func checkoutDidFail(error: CheckoutError) {
+          print("Checkout failed: \(error.localizedDescription)")
+          if !error.isRecoverable {
+              // Handle unrecoverable error
+          }
+      }
+
+      func checkoutDidCancel() {
+          print("Checkout cancelled")
+      }
+  }

  AcceleratedCheckoutButtons(cartID: cartId)
-     .onComplete { event in
-          // Reset cart on successful checkout
-          CartManager.shared.resetCart()
-      }
-      .onFail { error in
-          print("Checkout failed: \(error)")
-      }
-      .onCancel {
-          print("Checkout cancelled")
-      }
+      .checkout(delegate: MyDelegate())
+      .onError { error in
+          switch error {
+          case .validation(let validationError):
+              print("Validation failed with \(validationError.userErrors.count) errors:")
+              for userError in validationError.userErrors {
+                  print("• \(userError.message) at field: \(userError.field?.joined(separator: ".") ?? "unknown")")
+                  print("  Code: \(userError.code ?? "N/A")")
+              }
+          }
      }

New Features

Enhanced Validation Error Information

The new ValidationError provides detailed field-level validation feedback:

  .onError { error in
      if case .validation(let validationError) = error {
          // Access individual validation errors
          for userError in validationError.userErrors {
              print("Field: \(userError.field?.joined(separator: ".") ?? "unknown")")
              print("Message: \(userError.message)")
              print("Code: \(userError.code ?? "N/A")")
          }

          // Utility methods for easier error handling
          if error.hasValidationErrorCode("INVALID_EMAIL") {
              // Handle specific validation error
          }

          // Get all error messages at once
          let allMessages = error.validationMessages
      }
  }

Separation of Concerns

• .checkout(delegate:): Handles checkout flow events (completion, failure, cancellation)
• .onError { }: Handles validation errors that occur before checkout starts
• CheckoutDelegate.checkoutDidFail(): Handles checkout process failures
• Validation errors: Input data rejected by API (field validation, etc.)

Benefits

1. Better Error Context: Validation errors now provide field-specific information
2. Cleaner API: Single delegate pattern instead of multiple callback methods
3. Type Safety: Clear distinction between validation and checkout errors
4. Debugging: Enhanced error information for merchant debugging
5. Consistency: Aligns with existing CheckoutSheetKit delegate patterns

---

Before you merge

Important

• I've added tests to support my implementation
• I have bumped the version number in the podspec.
• I have added a Changelog entry.

[kieran-osgood-shopify]

I think AI is spoofing these tests to make it look like it's testing the behaviour