refactor: simplify error names - nest error in CheckoutError

Author: kieran-osgood-shopify

Samples/MobileBuyIntegration/MobileBuyIntegration/ViewControllers/CartViewController.swift

@@ -603,7 +603,7 @@ extension CartViewController: CheckoutDelegate {
         }
     }
 
-    func checkoutDidFail(error: ShopifyCheckoutSheetKit.CheckoutError) {
+    func checkoutDidFail(error: CheckoutError) {
         var errorMessage = ""
 
         /// Internal Checkout SDK error
@@ -634,7 +634,7 @@ extension CartViewController: CheckoutDelegate {
         }
     }
 
-    private func handleCheckoutUnavailable(_ message: String, _ code: CheckoutUnavailable) {
+    private func handleCheckoutUnavailable(_ message: String, _ code: CheckoutError.CheckoutUnavailable) {
         switch code {
         case let .clientError(clientErrorCode):
             print("[CheckoutUnavailable] (checkoutError)", message, clientErrorCode)

Sources/ShopifyCheckoutSheetKit/CheckoutError.swift

@@ -23,47 +23,33 @@
 
 import Foundation
 
-public enum CheckoutErrorCode: String, Codable {
-    case invalidPayload = "INVALID_PAYLOAD"
-    case invalidSignature = "INVALID_SIGNATURE"
-    case notAuthorized = "NOT_AUTHORIZED"
-    case payloadExpired = "PAYLOAD_EXPIRED"
-    case customerAccountRequired = "CUSTOMER_ACCOUNT_REQUIRED"
-    case storefrontPasswordRequired = "STOREFRONT_PASSWORD_REQUIRED"
-    case cartCompleted = "CART_COMPLETED"
-    case invalidCart = "INVALID_CART"
-    case killswitchEnabled = "KILLSWITCH_ENABLED"
-    case unrecoverableFailure = "UNRECOVERABLE_FAILURE"
-    case policyViolation = "POLICY_VIOLATION"
-    case vaultedPaymentError = "VAULTED_PAYMENT_ERROR"
-    case checkoutLiquidNotMigrated = "CHECKOUT_LIQUID_NOT_MIGRATED"
-}
-
-public enum CheckoutUnavailable {
-    case clientError(code: CheckoutErrorCode)
-    case httpError(statusCode: Int)
-}
-
-/// A type representing Shopify Checkout specific errors.
-/// "recoverable" indicates that though the request has failed, it should be retried in a fallback browser experience.
-public enum CheckoutError: Swift.Error {
+/// `CheckoutError` represents scenarios where Shopify Checkout may error
+///
+/// Each error relates to a different portion of Web Shopify Checkout, except `.sdk` which is an internal swift error
+/// When the error is not `.sdk` it is useful to first confirm where the issue exists in your Storefront
+/// within a browser, to exclude Checkout Kit from the investigation
+///
+/// Every event has a "recoverable" property that indicates this error may be recoverable when retried in a fallback browser experience
+/// This may have a degraded experience, implement CheckoutDelegate.shouldRecoverFromError to opt out
+public enum CheckoutError: Error {
     /// Issued when an internal error within Shopify Checkout SDK
     /// In event of an sdkError you could use the stacktrace to inform you of how to proceed,
-    /// if the issue persists, it is recommended to open a bug report in http://github.com/Shopify/checkout-sheet-kit-swift
-    case sdk(underlying: Swift.Error, recoverable: Bool = true)
+    /// if the issue persists, it is recommended to open a bug report in:
+    /// http://github.com/Shopify/checkout-sheet-kit-swift/issues
+    case sdk(underlying: Error, recoverable: Bool = true)
 
     /// Issued when the storefront configuration has caused an error.
-    /// Note that the Checkout Sheet Kit only supports stores migrated for extensibility.
-    case misconfiguration(message: String, code: CheckoutErrorCode, recoverable: Bool = false)
+    case misconfiguration(message: String, code: ErrorCode, recoverable: Bool = false)
 
     /// Issued when checkout has encountered a unrecoverable error (for example server side error)
-    /// if the issue persists, it is recommended to open a bug report in http://github.com/Shopify/checkout-sheet-kit-swift
+    /// if the issue persists, it is recommended to open a bug report:
+    /// http://github.com/Shopify/checkout-sheet-kit-swift/issues
     case unavailable(message: String, code: CheckoutUnavailable, recoverable: Bool)
 
     /// Issued when checkout is no longer available and will no longer be available with the checkout url supplied.
     /// This may happen when the user has paused on checkout for a long period (hours) and then attempted to proceed again with the same checkout url
     /// In event of checkoutExpired, a new checkout url will need to be generated
-    case expired(message: String, code: CheckoutErrorCode, recoverable: Bool = false)
+    case expired(message: String, code: ErrorCode, recoverable: Bool = false)
 
     public var isRecoverable: Bool {
         switch self {
@@ -74,15 +60,32 @@ public enum CheckoutError: Swift.Error {
             return recoverable
         }
     }
-}
 
-public struct CheckoutErrorEvent: CheckoutNotification {
-    public static let method = "checkout.error"
-    public let code: CheckoutErrorCode
-    public let message: String
+    public enum ErrorCode: String, Codable {
+        /// misconfiguration: recoverable:false
+        case payloadExpired = "PAYLOAD_EXPIRED"
+        case invalidPayload = "INVALID_PAYLOAD"
+        case invalidSignature = "INVALID_SIGNATURE"
+        case notAuthorized = "NOT_AUTHORIZED"
+        case customerAccountRequired = "CUSTOMER_ACCOUNT_REQUIRED"
+        case storefrontPasswordRequired = "STOREFRONT_PASSWORD_REQUIRED"
+
+        /// unavailable: recoverable:true
+        case killswitchEnabled = "KILLSWITCH_ENABLED"
+        case unrecoverableFailure = "UNRECOVERABLE_FAILURE"
+        case policyViolation = "POLICY_VIOLATION"
+        case vaultedPaymentError = "VAULTED_PAYMENT_ERROR"
+
+        /// expired: recoverable:false
+        case cartCompleted = "CART_COMPLETED"
+        case invalidCart = "INVALID_CART"
+
+        /// deprecated?
+        case checkoutLiquidNotMigrated = "CHECKOUT_LIQUID_NOT_MIGRATED"
+    }
 
-    public init(code: CheckoutErrorCode, message: String) {
-        self.code = code
-        self.message = message
+    public enum CheckoutUnavailable {
+        case clientError(code: ErrorCode)
+        case httpError(statusCode: Int)
     }
 }

Sources/ShopifyCheckoutSheetKit/CheckoutErrorEvent.swift

@@ -0,0 +1,33 @@
+/*
+ MIT License
+
+ Copyright 2023 - Present, Shopify Inc.
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+public struct CheckoutErrorEvent: CheckoutNotification {
+    public static let method = "checkout.error"
+    public let code: CheckoutError.ErrorCode
+    public let message: String
+
+    public init(code: CheckoutError.ErrorCode, message: String) {
+        self.code = code
+        self.message = message
+    }
+}

Sources/ShopifyCheckoutSheetKit/CheckoutWebView.swift

@@ -363,7 +363,7 @@ extension CheckoutWebView: WKScriptMessageHandler {
             viewDelegate.checkoutViewDidFailWithError(
                 error: .unavailable(
                     message: errorEvent.message,
-                    code: CheckoutUnavailable.clientError(code: errorEvent.code),
+                    code: .clientError(code: errorEvent.code),
                     recoverable: true
                 ))
         }
@@ -433,7 +433,7 @@ extension CheckoutWebView: WKNavigationDelegate {
                 viewDelegate?.checkoutViewDidFailWithError(
                     error: .unavailable(
                         message: errorMessageForStatusCode,
-                        code: CheckoutUnavailable.httpError(statusCode: statusCode),
+                        code: CheckoutError.CheckoutUnavailable.httpError(statusCode: statusCode),
                         recoverable: false
                     ))
             case 404:
@@ -451,30 +451,30 @@ extension CheckoutWebView: WKNavigationDelegate {
                     viewDelegate?.checkoutViewDidFailWithError(
                         error: .unavailable(
                             message: errorMessageForStatusCode,
-                            code: CheckoutUnavailable.httpError(statusCode: statusCode),
+                            code: .httpError(statusCode: statusCode),
                             recoverable: false
                         ))
                 }
             case 410:
                 OSLogger.shared.debug("Gone (410)")
                 viewDelegate?.checkoutViewDidFailWithError(
                     error: .expired(
-                        message: "Checkout has expired.", code: CheckoutErrorCode.invalidCart
+                        message: "Checkout has expired.", code: CheckoutError.ErrorCode.invalidCart
                     ))
             case 500 ... 599:
                 OSLogger.shared.debug("Server error (5xx)")
                 viewDelegate?.checkoutViewDidFailWithError(
                     error: .unavailable(
                         message: errorMessageForStatusCode,
-                        code: CheckoutUnavailable.httpError(statusCode: statusCode),
+                        code: .httpError(statusCode: statusCode),
                         recoverable: allowRecoverable
                     ))
             default:
                 OSLogger.shared.debug("\(statusCode) error received")
                 viewDelegate?.checkoutViewDidFailWithError(
                     error: .unavailable(
                         message: errorMessageForStatusCode,
-                        code: CheckoutUnavailable.httpError(statusCode: statusCode),
+                        code: .httpError(statusCode: statusCode),
                         recoverable: false
                     ))
             }