Error Refactor Spike

[KunJeongPark]

Reason for changes

• This PR is a spike, point of discussion for refactor of our Error types.

Problem Statement

Our SDK currently returns a single error type, CoreSDKError, which records:
• Domain: A String indicating the origin of the error (e.g., CardClientErrorDomain, PayPalClientErrorDomain).
• Code: An Int value classifying specific errors.
• Error Description: A string for the error.

This design is similar to NSError, which also provides domain, code, and localizedDescription.

Each module defines its own enum (e.g., CardError, NetworkingClientError) with:

1. Enum cases representing specific error types.
2. Static constants that create CoreSDKError under the hood.
   
   

For example:
• CardClient defines its own errors, including those from 3DS verification.
• Errors propagate up from networking layers as CoreSDKError with names reflecting their module and level of origin, but merchants must use domain and code checks to handle specific cases.

Challenges with the Current Design

1. Error Case Identification (v.1.5.0, last major release and in main) :
   Merchants must rely on the domain and code properties to identify specific errors, which can lead to verbose and error-prone code:

if let error {
    if error.domain == "CardClientErrorDomain" && error.code == 3 {
        // Handle cancellation
    }
}

2. Awkward Helper Functions (current beta release branch):
   To simplify cancellation handling in the beta release, I introduced helper methods like:

if PayPalError.isCheckoutCanceled(error) {
    // Handle cancellation
} else {
    // Handle other errors
}

While functional, this approach is not intuitive or consistent with Swift’s idiomatic error handling.

3. Limited Extensibility:
   Introducing new modules or errors requires updating CoreSDKError and potentially modifying helper methods, increasing maintenance complexity.

4. Merchant Experience:
   The current design does not align well with how merchants typically handle errors. Instead of looking at centralized domains and codes, merchants prefer to interact with module-specific error types directly.

Proposed Alternatives

1. Module-Specific Errors (e.g., Braintree’s Approach)
   • Each module defines its own error type (e.g., CardError, PayPalError), conforming to Error, LocalizedError, and Equatable.
   • Completion handlers return a general Error type, allowing merchants to switch on module-specific errors:

if let error {
    switch error {
    case BTPayPalError.canceled:
        // Handle PayPal cancellation
    case BTAPIClientError.notAuthorized:
        // Handle API client errors
    default:
        // Handle all other errors
    }
}

Advantages:
• Clear and modular error handling.
• Merchants can switch directly on error types without relying on domains and codes.

Disadvantages:
• Merchants must cast errors to module-specific types when needed.

2. Status Enum with Results and Errors
   • Use Status enum with possibly CoreSDKError:

enum Status<ResultType> {
    case succeeded(ResultType)
    case canceled // with or without Error returned
    case failed(Error)
}

• Completion handlers return Status, allowing merchants to handle success, cancellation, and failure in a unified manner:

switch status {
case .succeeded(let result):
    print("Success: \(result)")
case .canceled:
    print("Operation canceled.")
case .failed(let error):
    print("Error: \(error.localizedDescription)")
}

Advantages:
• Simplifies error handling by combining results and statuses.

Disadvantages:
• It may not be a pattern merchants are used to and some flows such as card payment without 3DS don't have cancel path.
• Merchants still need to cast Error for specific cases.

3. NSError-Style General Errors (which is what we currently have)
   • Adopt a design similar to NSError, where all errors are generic with domain, code, and localizedDescription.

Advantages:
• Familiar to many developers.
• Reduces complexity by avoiding module-specific error types.

Disadvantages:
• Does not leverage Swift’s strong typing.
• Error handling becomes verbose and less intuitive.

Recommendation

I recommend adopting module-specific error types (Alternative 1), similar to Braintree’s approach:
• Each module manages its own errors (CardError, PayPalError, NetworkingErrors that conform to Equatable protocol).
• Completion handlers return a generic Error type for compatibility.
• Merchants can handle errors using switch statements or type casting.

I think keeping errors as they are is also a viable option as well.
It is a pattern that developers are used to and I understand reason for this implementation.

Cancel separate handling may be not needed by majority of merchants and helper function
should be adequate for merchants if they want to do so. They can also write their own helper
functions to discern the error codes from our internal module specific enum types.

My final thoughts are to release our current v2_beta branch as beta1 and gage merchant feedback for changes.
There are already significant changes from delegation pattern to completion handler and async/await pattern in beta1.

Checklist

• Added a changelog entry

Authors

List GitHub usernames for everyone who contributed to this pull request.

• @KunJeongPark

[KunJeongPark]

Closing this, can be used as reference.
Note: we have merged in PR that makes CoreSDKError equatable
#303