import XCTest
import StripeTerminal

@testable import stripe_terminal_react_native

final class ErrorsTests: XCTestCase {

    private func makeNSError(
        domain: String = "com.stripe-terminal",
        code: Int = ErrorCode.Code.readerBusy.rawValue, // Use valid default ErrorCode
        userInfo: [String: Any] = [:],
        description: String = "Error occurred",
        failureReason: String? = nil,
        recoverySuggestion: String? = nil
    ) -> NSError {
        var info: [String: Any] = userInfo
        info[NSLocalizedDescriptionKey] = description
        if let failureReason {
            info[NSLocalizedFailureReasonErrorKey] = failureReason
        }
        if let recoverySuggestion {
            info[NSLocalizedRecoverySuggestionErrorKey] = recoverySuggestion
        }
        return NSError(domain: domain, code: code, userInfo: info)
    }

    func testNSErrorSourceIsProvidedByCallerWithoutChangingOtherFields() throws {
        let nsError = makeNSError(
            userInfo: [ErrorConstants.readerMessage: "Reader is in use"],
            description: "Reader is busy"
        )
        var rnError = Errors.mapToStripeErrorObject(nsError: nsError, source: .rn)
        var nativeError = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        XCTAssertEqual(rnError.removeValue(forKey: "error_source") as? String, "rn")
        XCTAssertEqual(nativeError.removeValue(forKey: "error_source") as? String, "native")
        XCTAssertEqual(rnError as NSDictionary, nativeError as NSDictionary)
        XCTAssertEqual(nsError.code, ErrorCode.Code.readerBusy.rawValue)
        XCTAssertNil(nsError.userInfo["error_source"])
    }

    func testCodeOnlyErrorsHaveRnSourceEvenForNativeErrorCodes() throws {
        let nativeCodeResult = Errors.createErrorFromCode(code: .readerBusy, message: "Reader is busy")
        let rnCodeResult = Errors.createErrorFromRnCodeEnum(rnCode: .READER_BUSY, message: "Reader is busy")

        for result in [nativeCodeResult, rnCodeResult] {
            let error = try XCTUnwrap(result["error"] as? [String: Any])
            XCTAssertEqual(error["error_source"] as? String, "rn")
            XCTAssertEqual(error["code"] as? String, "READER_BUSY")
            XCTAssertEqual(error["message"] as? String, "Reader is busy")
        }
    }

    func testGetConnectedReaderWithoutReaderResolvesExplicitNullInNonEmptyMap() throws {
        if !Terminal.isInitialized() {
            Terminal.initWithTokenProvider(TokenProvider.shared)
        }
        XCTAssertNil(Terminal.shared.connectedReader)

        let sut = StripeTerminalReactNative()
        var resolved: [String: Any]?
        var rejected = false
        sut.getConnectedReader(
            resolver: { resolved = $0 as? [String: Any] },
            rejecter: { _, _, _ in rejected = true }
        )

        XCTAssertFalse(rejected)
        let result = try XCTUnwrap(resolved)
        XCTAssertEqual(Array(result.keys), ["reader"])
        XCTAssertTrue(result["reader"] is NSNull)
    }

    func testNSErrorOverloadsPreserveExplicitSource() throws {
        let nsError = makeNSError(domain: "com.partner", code: 99, description: "Partner failure")
        for source in [ErrorSource.rn, .native] {
            let plain = Errors.createErrorFromNSError(nsError: nsError, source: source)
            let withUuid = Errors.createErrorFromNSError(nsError: nsError, uuid: "intent-uuid", source: source)
            let mappedWithUuid = Errors.mapToStripeErrorObject(nsError: nsError, uuid: "intent-uuid", source: source)
            let error = try XCTUnwrap(plain["error"] as? [String: Any])

            XCTAssertEqual(error["error_source"] as? String, source.rawValue)
            XCTAssertEqual(error["name"] as? String, "NonStripeError")
            XCTAssertEqual(plain as NSDictionary, withUuid as NSDictionary)
            XCTAssertEqual(error as NSDictionary, mappedWithUuid as NSDictionary)
        }
    }

    func testInitializeLocaleBuilderFailureHasNativeSource() throws {
        let sut = StripeTerminalReactNative()
        var results: [[String: Any]] = []
        sut.initialize(
            params: ["localeConfig": ["type": "hardcoded", "locale": "not_a_locale"]],
            resolver: { results.append($0 as? [String: Any] ?? [:]) },
            rejecter: { _, _, _ in XCTFail("The builder failure should resolve") }
        )

        XCTAssertEqual(results.count, 1)
        let error = try XCTUnwrap(results.first?["error"] as? [String: Any])
        XCTAssertEqual(error["error_source"] as? String, "native")
    }

    func testInitializeMissingLocaleConfigHasRnSource() throws {
        let sut = StripeTerminalReactNative()
        var results: [[String: Any]] = []

        sut.initialize(
            params: [:],
            resolver: { results.append($0 as? [String: Any] ?? [:]) },
            rejecter: { _, _, _ in XCTFail("Missing locale config should resolve") }
        )

        XCTAssertEqual(results.count, 1)
        let error = try XCTUnwrap(results.first?["error"] as? [String: Any])
        XCTAssertEqual(error["error_source"] as? String, "rn")
        XCTAssertEqual(error["code"] as? String, "INVALID_REQUIRED_PARAMETER")
        XCTAssertEqual(error["message"] as? String, "You must provide a localeConfig")
    }

    func testConnectionMissingLocationErrorsKeepRnSource() throws {
        if !Terminal.isInitialized() {
            Terminal.initWithTokenProvider(TokenProvider.shared)
        }

        let sut = StripeTerminalReactNative()
        let readerClass = try XCTUnwrap(NSClassFromString("SCPReader") as? NSObject.Type)
        let reader = try XCTUnwrap(readerClass.init() as? Reader)
        reader.setValue("SIMULATED", forKey: "serialNumber")
        sut.discoveredReadersList = [reader]
        let methods = [
            ("bluetoothScan", "Bluetooth"),
            ("bluetoothProximity", "Bluetooth"),
            ("tapToPay", "Tap to Pay"),
            ("usb", "USB"),
        ]

        for (method, label) in methods {
            let params: NSDictionary = [
                "discoveryMethod": method,
                "simulated": true,
                "reader": ["serialNumber": "SIMULATED"],
            ]
            let expected = Errors.createErrorFromNSError(
                nsError: NSError(
                    domain: "StripeTerminal",
                    code: -1,
                    userInfo: [NSLocalizedDescriptionKey: "Location ID is required for \(label) connection"]
                ),
                source: .rn
            )
            var easyResults: [[String: Any]] = []
            sut.easyConnect(
                params: params,
                resolver: { easyResults.append($0 as? [String: Any] ?? [:]) },
                rejecter: { _, _, _ in XCTFail("Missing location should resolve") }
            )
            XCTAssertEqual(easyResults.count, 1, method)
            XCTAssertEqual(easyResults.first as NSDictionary?, expected as NSDictionary, method)

            var connectResults: [[String: Any]] = []
            sut.connectReader(
                params: params,
                resolver: { connectResults.append($0 as? [String: Any] ?? [:]) },
                rejecter: { _, _, _ in XCTFail("Missing location should resolve") }
            )
            XCTAssertEqual(connectResults.count, 1, method)
            XCTAssertEqual(connectResults.first as NSDictionary?, expected as NSDictionary, method)
        }
    }

    func testConnectionBuilderErrorsHaveNativeSource() throws {
        if !Terminal.isInitialized() {
            Terminal.initWithTokenProvider(TokenProvider.shared)
        }
        let sut = StripeTerminalReactNative()
        // An empty configured location reaches the real SDK builder, unlike an omitted location.
        let builderError: NSError
        do {
            _ = try BluetoothConnectionConfigurationBuilder(delegate: sut, locationId: "").build()
            return XCTFail("The SDK builder must reject an empty location before invoking the bridge")
        } catch {
            builderError = error as NSError
        }
        let readerClass = try XCTUnwrap(NSClassFromString("SCPReader") as? NSObject.Type)
        let reader = try XCTUnwrap(readerClass.init() as? Reader)
        reader.setValue("SIMULATED", forKey: "serialNumber")
        sut.discoveredReadersList = [reader]
        let params: NSDictionary = [
            "discoveryMethod": "bluetoothScan",
            "simulated": true,
            "locationId": "",
            "reader": ["serialNumber": "SIMULATED"],
        ]
        var easyResults: [[String: Any]] = []
        sut.easyConnect(
            params: params,
            resolver: { easyResults.append($0 as? [String: Any] ?? [:]) },
            rejecter: { _, _, _ in XCTFail("SDK builder failure should resolve") }
        )
        var connectResults: [[String: Any]] = []
        sut.connectReader(
            params: params,
            resolver: { connectResults.append($0 as? [String: Any] ?? [:]) },
            rejecter: { _, _, _ in XCTFail("SDK builder failure should resolve") }
        )
        let expected = Errors.createErrorFromNSError(nsError: builderError, source: .native)
        XCTAssertEqual(easyResults.count, 1)
        XCTAssertEqual(connectResults.count, 1)
        XCTAssertEqual(easyResults.first as NSDictionary?, expected as NSDictionary)
        XCTAssertEqual(connectResults.first as NSDictionary?, expected as NSDictionary)
    }

    func testUnsupportedEasyConnectConfigurationHasRnSource() throws {
        if !Terminal.isInitialized() {
            Terminal.initWithTokenProvider(TokenProvider.shared)
        }
        let sut = StripeTerminalReactNative()
        var results: [[String: Any]] = []
        sut.easyConnect(
            params: ["discoveryMethod": "bluetoothScan", "simulated": true, "locationId": "tml_test"],
            resolver: { results.append($0 as? [String: Any] ?? [:]) },
            rejecter: { _, _, _ in XCTFail("Unsupported configuration should resolve") }
        )

        XCTAssertEqual(results.count, 1)
        let error = try XCTUnwrap(results.first?["error"] as? [String: Any])
        XCTAssertEqual(error["error_source"] as? String, "rn")
        XCTAssertEqual(error["nativeErrorCode"] as? String, "StripeTerminal:-1")
        XCTAssertTrue((error["message"] as? String)?.hasPrefix("Easy connect is not supported for ") == true)
    }

    func testReaderUpdateDelegateErrorsHaveNativeSource() throws {
        let sut = ErrorEventEmitter()
        let readerClass = try XCTUnwrap(NSClassFromString("SCPReader") as? NSObject.Type)
        let reader = try XCTUnwrap(readerClass.init() as? Reader)
        let nsError = makeNSError(code: ErrorCode.Code.readerSoftwareUpdateFailed.rawValue)

        sut.reader(reader, didFinishInstallingUpdate: nil, error: nsError)

        XCTAssertEqual(sut.events.count, 1)
        let expected = Errors.createErrorFromNSError(nsError: nsError, source: .native)
        let expectedError = try XCTUnwrap(expected["error"] as? [String: Any])
        for (name, body) in sut.events {
            XCTAssertEqual(name, ReactNativeConstants.FINISH_INSTALLING_UPDATE.rawValue)
            let error = try XCTUnwrap(body["error"] as? [String: Any])
            XCTAssertEqual(error as NSDictionary, expectedError as NSDictionary)
            XCTAssertNil(body["result"])
        }
    }

    func testReaderUpdateStartIncludesCallbackReaderBeforeConnectionCompletes() throws {
        if !Terminal.isInitialized() {
            Terminal.initWithTokenProvider(TokenProvider.shared)
        }
        XCTAssertNil(Terminal.shared.connectedReader)

        let sut = ErrorEventEmitter()
        let readerClass = try XCTUnwrap(NSClassFromString("SCPReader") as? NSObject.Type)
        let reader = try XCTUnwrap(readerClass.init() as? Reader)
        reader.setValue("TEST_READER", forKey: "serialNumber")
        reader.setValue("1.2.3", forKey: "deviceSoftwareVersion")
        let updateClass = try XCTUnwrap(NSClassFromString("SCPReaderSoftwareUpdate") as? NSObject.Type)
        let update = try XCTUnwrap(updateClass.init() as? ReaderSoftwareUpdate)
        update.setValue(Date(timeIntervalSince1970: 0), forKey: "requiredAt")

        sut.reader(reader, didStartInstallingUpdate: update, cancelable: nil)

        XCTAssertEqual(sut.events.count, 1)
        let (name, body) = try XCTUnwrap(sut.events.first)
        XCTAssertEqual(name, ReactNativeConstants.START_INSTALLING_UPDATE.rawValue)
        let mappedReader = try XCTUnwrap(body["reader"] as? [String: Any])
        XCTAssertEqual(mappedReader["serialNumber"] as? String, "TEST_READER")
        XCTAssertEqual(mappedReader["deviceSoftwareVersion"] as? String, "1.2.3")
        XCTAssertNotNil(body["result"])
        XCTAssertNil(Terminal.shared.connectedReader)
    }

    func testReaderUpdateProgressIsNumeric() throws {
        let sut = ErrorEventEmitter()
        let readerClass = try XCTUnwrap(NSClassFromString("SCPReader") as? NSObject.Type)
        let reader = try XCTUnwrap(readerClass.init() as? Reader)

        sut.reader(reader, didReportReaderSoftwareUpdateProgress: 0.5)

        XCTAssertEqual(sut.events.count, 1)
        let result = try XCTUnwrap(sut.events.first?.1["result"] as? [String: Any])
        XCTAssertEqual(result["progress"] as? Float, 0.5)
        XCTAssertNil(result["progress"] as? String)
    }

    func testMapToStripeErrorObject_StripeDomain() {
        // GIVEN an NSError within the Stripe domain
        let underlying = makeNSError(
            domain: "underlying.domain",
            code: 42,
            description: "Underlying failure",
            failureReason: "The underlying operation failed",
            recoverySuggestion: "Retry the underlying operation"
        )
        let nsError = makeNSError(
            code: ErrorCode.Code.readerBusy.rawValue,
            userInfo: [NSUnderlyingErrorKey: underlying],
            description: "Reader is busy",
            failureReason: "The reader is currently in use",
            recoverySuggestion: "Wait and retry"
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "READER_BUSY")
        XCTAssertEqual(error["nativeErrorCode"] as? String, String(ErrorCode.Code.readerBusy.rawValue))
        XCTAssertEqual(error["message"] as? String, "Reader is busy Wait and retry")

        guard let underlyingInfo = error["underlyingError"] as? [String: Any] else {
            return XCTFail("underlyingError should be at top-level")
        }
        XCTAssertEqual(underlyingInfo["iosDomain"] as? String, "underlying.domain")
        XCTAssertEqual(underlyingInfo["code"] as? String, "42")
        XCTAssertEqual(underlyingInfo["message"] as? String, "Underlying failure")
        XCTAssertEqual(underlyingInfo["iosLocalizedFailureReason"] as? String, "The underlying operation failed")
        XCTAssertEqual(underlyingInfo["iosLocalizedRecoverySuggestion"] as? String, "Retry the underlying operation")

        guard let metadata = error["metadata"] as? [String: Any] else {
            return XCTFail("Metadata should be present")
        }
        XCTAssertNil(metadata["underlyingError"], "underlyingError should not be in metadata")
    }

    func testMapToStripeErrorObject_underlyingErrorOmitsOuterLocalizedInfo() throws {
        let underlying = makeNSError(domain: "underlying.domain", code: 42, description: "Underlying failure")
        let nsError = makeNSError(
            userInfo: [NSUnderlyingErrorKey: underlying],
            failureReason: "The reader is currently in use",
            recoverySuggestion: "Wait and retry"
        )

        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)
        let underlyingInfo = try XCTUnwrap(error["underlyingError"] as? [String: Any])

        XCTAssertEqual(underlyingInfo["message"] as? String, "Underlying failure")
        XCTAssertNil(underlyingInfo["iosLocalizedFailureReason"])
        XCTAssertNil(underlyingInfo["iosLocalizedRecoverySuggestion"])
    }

    func testMapToStripeErrorObject_withoutRecoverySuggestionKeepsDescription() {
        let underlying = makeNSError(
            domain: "underlying.domain",
            code: 42,
            recoverySuggestion: "Retry the underlying operation"
        )
        let suggestions: [String?] = [nil, ""]

        for suggestion in suggestions {
            let nsError = makeNSError(
                userInfo: [NSUnderlyingErrorKey: underlying],
                description: "Reader is busy",
                recoverySuggestion: suggestion
            )

            let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

            XCTAssertEqual(error["message"] as? String, "Reader is busy")
        }
    }

    func testMapToStripeErrorObject_NonStripeDomain() {
        // GIVEN an NSError from a non-Stripe domain
        let nsError = makeNSError(domain: "com.partner", code: 99, description: "Partner failure")

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN
        XCTAssertEqual(error["name"] as? String, "NonStripeError")
        XCTAssertEqual(error["code"] as? String, "UNEXPECTED_SDK_ERROR")
        XCTAssertEqual(error["nativeErrorCode"] as? String, "com.partner:99")
        XCTAssertEqual(error["message"] as? String, "Partner failure")
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    func testCreateErrorReturnsWrappedStructure() {
        // GIVEN an NSError
        let nsError = makeNSError(code: ErrorCode.Code.readerBusy.rawValue)

        // WHEN createError is called
        let wrapped = Errors.createErrorFromNSError(nsError: nsError, source: .native)

        // THEN
        guard let error = wrapped["error"] as? [String: Any] else {
            return XCTFail("Expected error key in wrapper")
        }
        XCTAssertEqual(error["name"] as? String, "StripeError")
    }

    func testSanitizeUserInfoFiltersUnsupportedTypes() {
        // GIVEN userInfo containing complex nested structures
        let underlying = makeNSError(domain: "nested", code: 12, userInfo: ["nonJson": NSSet(array: [1, 2])])
        let nsError = makeNSError(
            userInfo: [
                "string": "value",
                "number": 10,
                NSUnderlyingErrorKey: underlying,
                "date": Date(timeIntervalSince1970: 0),
                "url": URL(string: "https://example.com") as Any
            ]
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    // MARK: - createError Overloads Tests

    func testCreateError_withErrorCodeAndMessage() {
        // GIVEN an ErrorCode.Code and message
        let code = ErrorCode.Code.readerBusy
        let message = "Reader is currently busy"

        // WHEN createError is called
        let result = Errors.createErrorFromCode(code: code, message: message)

        // THEN it should return wrapped error with correct mapping
        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error key in result")
        }
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "READER_BUSY")
        XCTAssertEqual(error["message"] as? String, message)
        XCTAssertEqual(error["nativeErrorCode"] as? String, code.stringValue)
    }

    func testCreateError_withRNCodeStringAndMessage() {
        // GIVEN an RN error code enum and message
        let rnCode = Errors.RNErrorCode.BLUETOOTH_PERMISSION_DENIED
        let message = "Bluetooth access denied"

        // WHEN createError is called
        let result = Errors.createErrorFromRnCodeEnum(rnCode: rnCode, message: message)

        // THEN it should return wrapped error
        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error key in result")
        }
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, rnCode.rawValue)
        XCTAssertEqual(error["message"] as? String, message)
        XCTAssertEqual(error["nativeErrorCode"] as? String, rnCode.rawValue)
    }

    func testCreateError_withRNErrorCodeEnumAndMessage() {
        // GIVEN an RNErrorCode enum and message
        let rnCode = Errors.RNErrorCode.CANCEL_FAILED
        let message = "Cancel operation failed"

        // WHEN createError is called
        let result = Errors.createErrorFromRnCodeEnum(rnCode: rnCode, message: message)

        // THEN it should return wrapped error
        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error key in result")
        }
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, rnCode.rawValue)
        XCTAssertEqual(error["message"] as? String, message)
        XCTAssertEqual(error["nativeErrorCode"] as? String, rnCode.rawValue)
    }

    // MARK: - validateRequiredParameters Tests

    func testValidateRequiredParameters_allPresent() {
        // GIVEN a dictionary with all required parameters
        let params: NSDictionary = [
            "param1": "value1",
            "param2": 42,
            "param3": true
        ]
        let requiredParams = ["param1", "param2", "param3"]

        // WHEN validateRequiredParameters is called
        let result = Errors.validateRequiredParameters(params: params, requiredParams: requiredParams)

        // THEN it should return nil (no missing parameters)
        XCTAssertNil(result)
    }

    func testValidateRequiredParameters_someMissing() {
        // GIVEN a dictionary missing some required parameters
        let params: NSDictionary = [
            "param1": "value1",
            "param3": true
        ]
        let requiredParams = ["param1", "param2", "param3"]

        // WHEN validateRequiredParameters is called
        let result = Errors.validateRequiredParameters(params: params, requiredParams: requiredParams)

        // THEN it should return the missing parameter name
        XCTAssertEqual(result, "param2")
    }

    func testValidateRequiredParameters_multipleMissing() {
        // GIVEN a dictionary missing multiple required parameters
        let params: NSDictionary = [
            "param1": "value1"
        ]
        let requiredParams = ["param1", "param2", "param3"]

        // WHEN validateRequiredParameters is called
        let result = Errors.validateRequiredParameters(params: params, requiredParams: requiredParams)

        // THEN it should return comma-separated missing parameters
        XCTAssertEqual(result, "param2, param3")
    }

    func testValidateRequiredParameters_emptyParams() {
        // GIVEN an empty dictionary
        let params: NSDictionary = [:]
        let requiredParams = ["param1", "param2"]

        // WHEN validateRequiredParameters is called
        let result = Errors.validateRequiredParameters(params: params, requiredParams: requiredParams)

        // THEN it should return all required parameters as missing
        XCTAssertEqual(result, "param1, param2")
    }

    func testValidateRequiredParameters_noRequiredParams() {
        // GIVEN any dictionary with no required parameters
        let params: NSDictionary = ["param1": "value1"]
        let requiredParams: [String] = []

        // WHEN validateRequiredParameters is called
        let result = Errors.validateRequiredParameters(params: params, requiredParams: requiredParams)

        // THEN it should return nil
        XCTAssertNil(result)
    }

    func testCollectInputsInvalidNestedStringsResolveInvalidRequiredParameter() throws {
        let invalidInputs: [NSDictionary] = [
            ["formType": "email", "title": 42],
            [
                "formType": "selection",
                "title": "Choose",
                "selectionButtons": [["text": "First"]]
            ]
        ]
        let sut = StripeTerminalReactNative()

        for input in invalidInputs {
            var resolved: [String: Any]?
            sut.collectInputs(
                ["inputs": [input]],
                resolver: { resolved = $0 as? [String: Any] },
                rejecter: { _, _, _ in XCTFail("Invalid input should resolve") }
            )

            let error = try XCTUnwrap(resolved?["error"] as? [String: Any])
            XCTAssertEqual(error["error_source"] as? String, "rn")
            XCTAssertEqual(error["code"] as? String, "INVALID_REQUIRED_PARAMETER")
        }
    }

    // MARK: - Edge Cases and Boundary Tests

    func testMapToStripeErrorObject_emptyMessage() {
        // GIVEN an NSError with empty message
        let nsError = makeNSError(description: "")

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN message should fallback to "Unknown error"
        XCTAssertEqual(error["message"] as? String, "Unknown error")
    }

    func testMapToStripeErrorObject_withPaymentIntent() {
        // GIVEN an NSError with payment intent in userInfo
        let paymentIntentId = "pi_test_123"
        let nsError = makeNSError(
            code: ErrorCode.Code.readerBusy.rawValue,
            userInfo: ["paymentIntent": paymentIntentId]
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN basic error structure should be present
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "READER_BUSY")

        // metadata should exist
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    func testMapToStripeErrorObject_complexNestedUserInfo() {
        // GIVEN an NSError with deeply nested userInfo
        let complexUserInfo: [String: Any] = [
            "level1": [
                "level2": [
                    "level3": ["key": "value"],
                    "array": [1, 2, 3],
                    "url": URL(string: "https://example.com")!,
                    "date": Date(timeIntervalSince1970: 1234567890)
                ]
            ],
            "unsupported": NSSet(array: ["filtered", "out"])
        ]
        let nsError = makeNSError(userInfo: complexUserInfo)

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN error structure should handle complex userInfo gracefully
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    // MARK: - Comprehensive ErrorCode Mapping Tests

    func testErrorCodeMapping_integrationErrors() {
        // GIVEN integration-related ErrorCode.Code values
        let testCases: [(ErrorCode.Code, String)] = [
            (.canceled, "CANCELED"),
            (.notConnectedToReader, "NOT_CONNECTED_TO_READER"),
            (.alreadyConnectedToReader, "ALREADY_CONNECTED_TO_READER"),
            (.confirmInvalidPaymentIntent, "CONFIRM_INVALID_PAYMENT_INTENT"),
            (.invalidRefundParameters, "INVALID_REQUIRED_PARAMETER"),
            (.cancelFailedAlreadyCompleted, "CANCEL_FAILED"),
            (.invalidClientSecret, "INVALID_CLIENT_SECRET"),
            (.invalidDiscoveryConfiguration, "MISSING_REQUIRED_PARAMETER"),
            (.unsupportedSDK, "UNSUPPORTED_SDK"),
            (.invalidRequiredParameter, "INVALID_REQUIRED_PARAMETER"),
            (.invalidRequiredParameterOnBehalfOf, "INVALID_REQUIRED_PARAMETER"),
            (.readerConnectionConfigurationInvalid, "MISSING_REQUIRED_PARAMETER"),
            (.readerTippingParameterInvalid, "INVALID_TIP_PARAMETER"),
            (.invalidLocationIdParameter, "MISSING_REQUIRED_PARAMETER")
        ]

        for (errorCode, expectedRNCode) in testCases {
            // WHEN creating error with integration ErrorCode
            let nsError = makeNSError(code: errorCode.rawValue)
            let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

            // THEN it should map to correct RN error code
            XCTAssertEqual(error["code"] as? String, expectedRNCode,
                          "Failed integration mapping for \(errorCode)")
        }
    }

    func testErrorCodeMapping_bluetoothErrors() {
        // GIVEN Bluetooth-related ErrorCode.Code values
        let testCases: [(ErrorCode.Code, String)] = [
            (.bluetoothDisabled, "BLUETOOTH_PERMISSION_DENIED"),
            (.bluetoothAccessDenied, "BLUETOOTH_PERMISSION_DENIED"),
            (.bluetoothScanTimedOut, "BLUETOOTH_SCAN_TIMED_OUT"),
            (.bluetoothLowEnergyUnsupported, "BLUETOOTH_LOW_ENERGY_UNSUPPORTED"),
            (.bluetoothError, "BLUETOOTH_ERROR"),
            (.bluetoothDisconnected, "BLUETOOTH_DISCONNECTED"),
            (.bluetoothPeerRemovedPairingInformation, "BLUETOOTH_ERROR"),
            (.bluetoothAlreadyPairedWithAnotherDevice, "READER_CONNECTED_TO_ANOTHER_DEVICE"),
            (.bluetoothConnectTimedOut, "REQUEST_TIMED_OUT"),
            (.bluetoothConnectionFailedBatteryCriticallyLow, "READER_BATTERY_CRITICALLY_LOW"),
            (.bluetoothReconnectStarted, "BLUETOOTH_RECONNECT_STARTED"),
            (.bluetoothConnectionInvalidLocationIdParameter, "INVALID_REQUIRED_PARAMETER")
        ]

        for (errorCode, expectedRNCode) in testCases {
            // WHEN creating error with Bluetooth ErrorCode
            let nsError = makeNSError(code: errorCode.rawValue)
            let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

            // THEN it should map to correct RN error code
            XCTAssertEqual(error["code"] as? String, expectedRNCode,
                          "Failed Bluetooth mapping for \(errorCode)")
        }
    }

    func testErrorCodeMapping_readerErrors() {
        // GIVEN Reader-related ErrorCode.Code values
        let testCases: [(ErrorCode.Code, String)] = [
            (.readerBusy, "READER_BUSY"),
            (.readerCommunicationError, "READER_COMMUNICATION_ERROR"),
            (.incompatibleReader, "UNSUPPORTED_READER_VERSION"),
            (.unsupportedReaderVersion, "UNSUPPORTED_READER_VERSION"),
            (.unknownReaderIpAddress, "GENERIC_READER_ERROR"),
            (.connectFailedReaderIsInUse, "READER_CONNECTED_TO_ANOTHER_DEVICE"),
            (.unexpectedReaderError, "GENERIC_READER_ERROR"),
            (.encryptionKeyFailure, "READER_MISSING_ENCRYPTION_KEYS"),
            (.encryptionKeyStillInitializing, "READER_MISSING_ENCRYPTION_KEYS"),
            (.readerMissingEncryptionKeys, "READER_MISSING_ENCRYPTION_KEYS"),
            (.invalidReaderForUpdate, "READER_SOFTWARE_UPDATE_FAILED"),
            (.readerSoftwareUpdateFailed, "READER_SOFTWARE_UPDATE_FAILED"),
            (.readerSoftwareUpdateFailedBatteryLow, "READER_SOFTWARE_UPDATE_FAILED_BATTERY_LOW"),
            (.readerSoftwareUpdateFailedServerError, "READER_SOFTWARE_UPDATE_FAILED_SERVER_ERROR"),
            (.readerSoftwareUpdateFailedReaderError, "READER_SOFTWARE_UPDATE_FAILED_READER_ERROR"),
            (.readerSoftwareUpdateFailedInterrupted, "READER_SOFTWARE_UPDATE_FAILED_INTERRUPTED"),
            (.readerSoftwareUpdateFailedExpiredUpdate, "READER_SOFTWARE_UPDATE_FAILED"),
            (.readerConnectionOfflineNeedsUpdate, "UNSUPPORTED_READER_VERSION"),
            (.readerNotAccessibleInBackground, "UNSUPPORTED_OPERATION")
        ]

        for (errorCode, expectedRNCode) in testCases {
            // WHEN creating error with Reader ErrorCode
            let nsError = makeNSError(code: errorCode.rawValue)
            let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

            // THEN it should map to correct RN error code
            XCTAssertEqual(error["code"] as? String, expectedRNCode,
                          "Failed Reader mapping for \(errorCode)")
        }
    }

    func testErrorCodeMapping_paymentErrors() {
        // GIVEN Payment-related ErrorCode.Code values
        let testCases: [(ErrorCode.Code, String)] = [
            (.declinedByStripeAPI, "DECLINED_BY_STRIPE_API"),
            (.declinedByReader, "DECLINED_BY_READER"),
            (.refundFailed, "STRIPE_API_ERROR"),
            (.cardInsertNotRead, "CARD_INSERT_NOT_READ"),
            (.cardSwipeNotRead, "CARD_SWIPE_NOT_READ"),
            (.cardReadTimedOut, "CARD_READ_TIMED_OUT"),
            (.cardRemoved, "CARD_REMOVED"),
            (.cardLeftInReader, "CARD_LEFT_IN_READER"),
            (.cardSwipeNotAvailable, "CARD_SWIPE_NOT_AVAILABLE"),
            (.commandRequiresCardholderConsent, "CUSTOMER_CONSENT_REQUIRED"),
            (.invalidAmount, "INVALID_REQUIRED_PARAMETER"),
            (.invalidCurrency, "INVALID_REQUIRED_PARAMETER")
        ]

        for (errorCode, expectedRNCode) in testCases {
            // WHEN creating error with Payment ErrorCode
            let nsError = makeNSError(code: errorCode.rawValue)
            let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

            // THEN it should map to correct RN error code
            XCTAssertEqual(error["code"] as? String, expectedRNCode,
                          "Failed Payment mapping for \(errorCode)")
        }
    }

    func testErrorCodeMapping_networkErrors() {
        // GIVEN Network-related ErrorCode.Code values
        let testCases: [(ErrorCode.Code, String)] = [
            (.connectionTokenProviderCompletedWithNothing, "CONNECTION_TOKEN_PROVIDER_ERROR"),
            (.connectionTokenProviderCompletedWithNothingWhileForwarding, "CONNECTION_TOKEN_PROVIDER_ERROR_WHILE_FORWARDING"),
            (.connectionTokenProviderCompletedWithError, "CONNECTION_TOKEN_PROVIDER_ERROR"),
            (.connectionTokenProviderCompletedWithErrorWhileForwarding, "CONNECTION_TOKEN_PROVIDER_ERROR_WHILE_FORWARDING"),
            (.connectionTokenProviderTimedOut, "REQUEST_TIMED_OUT"),
            (.internetConnectTimeOut, "REQUEST_TIMED_OUT"),
            (.requestTimedOut, "REQUEST_TIMED_OUT"),
            (.notConnectedToInternet, "STRIPE_API_CONNECTION_ERROR"),
            (.stripeAPIError, "STRIPE_API_ERROR"),
            (.stripeAPIResponseDecodingError, "STRIPE_API_RESPONSE_DECODING_ERROR"),
            (.internalNetworkError, "STRIPE_API_CONNECTION_ERROR"),
            (.sessionExpired, "SESSION_EXPIRED")
        ]

        for (errorCode, expectedRNCode) in testCases {
            // WHEN creating error with Network ErrorCode
            let nsError = makeNSError(code: errorCode.rawValue)
            let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

            // THEN it should map to correct RN error code
            XCTAssertEqual(error["code"] as? String, expectedRNCode,
                          "Failed Network mapping for \(errorCode)")
        }
    }

    func testErrorCodeMapping_offlineErrors() {
        // GIVEN Offline-related ErrorCode.Code values
        let testCases: [(ErrorCode.Code, String)] = [
            (.offlineAndCardExpired, "OFFLINE_AND_CARD_EXPIRED"),
            (.offlineTransactionDeclined, "OFFLINE_TRANSACTION_DECLINED"),
            (.interacNotSupportedOffline, "INTERAC_NOT_SUPPORTED_OFFLINE"),
            (.onlinePinNotSupportedOffline, "ONLINE_PIN_NOT_SUPPORTED_OFFLINE"),
            (.offlineTestCardInLivemode, "OFFLINE_TESTMODE_PAYMENT_IN_LIVEMODE"),
            (.offlinePaymentsDatabaseTooLarge, "OFFLINE_PAYMENTS_DATABASE_TOO_LARGE"),
            (.readerConnectionNotAvailableOffline, "READER_CONNECTION_NOT_AVAILABLE_OFFLINE"),
            (.offlineCollectAndConfirmMismatch, "OFFLINE_COLLECT_AND_CONFIRM_MISMATCH"),
            (.readerConnectionOfflineLocationMismatch, "LOCATION_CONNECTION_NOT_AVAILABLE_OFFLINE"),
            (.readerConnectionOfflinePairingUnseenDisabled, "MISSING_PREREQUISITE"),
            (.noLastSeenAccount, "NO_LAST_SEEN_ACCOUNT"),
            (.notConnectedToInternetAndOfflineBehaviorRequireOnline, "NOT_CONNECTED_TO_INTERNET_AND_REQUIRE_ONLINE_SET"),
            (.amountExceedsMaxOfflineAmount, "AMOUNT_EXCEEDS_MAX_OFFLINE_AMOUNT"),
            (.missingEMVData, "MISSING_EMV_DATA"),
            (.invalidOfflineCurrency, "INVALID_OFFLINE_CURRENCY"),
            (.accountIdMismatchWhileForwarding, "ACCOUNT_ID_MISMATCH_WHILE_FORWARDING"),
            (.updatePaymentIntentUnavailableWhileOffline, "UNEXPECTED_OPERATION"),
            (.updatePaymentIntentUnavailableWhileOfflineModeEnabled, "UNEXPECTED_OPERATION"),
            (.forwardingLiveModePaymentInTestMode, "OFFLINE_LIVEMODE_PAYMENT_IN_TESTMODE"),
            (.forwardingTestModePaymentInLiveMode, "OFFLINE_TESTMODE_PAYMENT_IN_LIVEMODE"),
            (.offlineBehaviorForceOfflineWithFeatureDisabled, "FORCE_OFFLINE_WITH_FEATURE_DISABLED")
        ]

        for (errorCode, expectedRNCode) in testCases {
            // WHEN creating error with Offline ErrorCode
            let nsError = makeNSError(code: errorCode.rawValue)
            let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

            // THEN it should map to correct RN error code
            XCTAssertEqual(error["code"] as? String, expectedRNCode,
                          "Failed Offline mapping for \(errorCode)")
        }
    }

    func testErrorCodeMapping_miscellaneousErrors() {
        // GIVEN Miscellaneous ErrorCode.Code values
        let testCases: [(ErrorCode.Code, String)] = [
            (.locationServicesDisabled, "LOCATION_SERVICES_DISABLED"),
            (.nfcDisabled, "TAP_TO_PAY_NFC_DISABLED"),
            (.commandNotAllowed, "UNSUPPORTED_OPERATION"),
            (.unsupportedMobileDeviceConfiguration, "UNSUPPORTED_OPERATION"),
            (.passcodeNotEnabled, "UNSUPPORTED_OPERATION"),
            (.commandNotAllowedDuringCall, "UNSUPPORTED_OPERATION"),
            (.featureNotAvailableWithConnectedReader, "UNSUPPORTED_OPERATION"),
            (.featureNotAvailable, "UNSUPPORTED_OPERATION"),
            (.invalidListLocationsLimitParameter, "INVALID_REQUIRED_PARAMETER"),
            (.collectInputsApplicationError, "COLLECT_INPUTS_APPLICATION_ERROR"),
            (.collectInputsTimedOut, "COLLECT_INPUTS_TIMED_OUT"),
            (.collectInputsInvalidParameter, "COLLECT_INPUTS_INVALID_PARAMETER"),
            (.collectInputsUnsupported, "COLLECT_INPUTS_UNSUPPORTED"),
            (.surchargeNoticeRequiresUpdatePaymentIntent, "ALLOW_REDISPLAY_INVALID"),
            (.surchargeUnavailableWithDynamicCurrencyConversion, "UNEXPECTED_OPERATION"),
            (.requestDynamicCurrencyConversionRequiresUpdatePaymentIntent, "UNEXPECTED_OPERATION"),
            (.dynamicCurrencyConversionNotAvailable, "UNEXPECTED_OPERATION"),
            (.surchargingNotAvailable, "UNEXPECTED_OPERATION"),
            (.usbDiscoveryTimedOut, "USB_DISCOVERY_TIMED_OUT"),
            (.usbDisconnected, "USB_DISCONNECTED"),
            (.unexpectedSdkError, "UNEXPECTED_SDK_ERROR")
        ]

        for (errorCode, expectedRNCode) in testCases {
            // WHEN creating error with Miscellaneous ErrorCode
            let nsError = makeNSError(code: errorCode.rawValue)
            let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

            // THEN it should map to correct RN error code
            XCTAssertEqual(error["code"] as? String, expectedRNCode,
                          "Failed Miscellaneous mapping for \(errorCode)")
        }
    }

    func testErrorCodeMapping_comprehensiveCoverage() {
        // GIVEN ErrorCode.Code values that require explicit mapping coverage
        let testCases: [(ErrorCode.Code, String)] = [
            (.cancelFailedUnavailable, "CANCEL_FAILED"),
            (.nilPaymentIntent, "INVALID_REQUIRED_PARAMETER"),
            (.nilSetupIntent, "INVALID_REQUIRED_PARAMETER"),
            (.nilRefundPaymentMethod, "INVALID_REQUIRED_PARAMETER"),
            (.invalidConnectionConfiguration, "INVALID_REQUIRED_PARAMETER"),
            (.surchargeConsentRequiresAmountSurcharge, "INVALID_REQUIRED_PARAMETER"),
            (.surchargeConsentNoticeRequiresAmountSurchargeAndCollectConsent, "INVALID_REQUIRED_PARAMETER"),
            (.surchargeConsentRequestedForUnsupportedReader, "UNSUPPORTED_OPERATION"),
            (.surchargeConsentDeclined, "DECLINED_BY_STRIPE_API"),
            (.surchargeConsentTimeout, "REQUEST_TIMED_OUT"),
            (.canceledDueToIntegrationError, "CANCELED_DUE_TO_INTEGRATION_ERROR"),
            (.tapToPayReaderTOSAcceptanceRequiresiCloudSignIn, "READER_SOFTWARE_UPDATE_FAILED"),
            (.tapToPayReaderTOSAcceptanceCanceled, "CANCELED"),
            (.tapToPayReaderFailedToPrepare, "READER_SOFTWARE_UPDATE_FAILED"),
            (.tapToPayReaderDeviceBanned, "UNSUPPORTED_READER_VERSION"),
            (.tapToPayReaderTOSNotYetAccepted, "READER_SOFTWARE_UPDATE_FAILED"),
            (.tapToPayReaderTOSAcceptanceFailed, "READER_SOFTWARE_UPDATE_FAILED"),
            (.tapToPayReaderMerchantBlocked, "TAP_TO_PAY_READER_MERCHANT_BLOCKED"),
            (.tapToPayReaderInvalidMerchant, "INVALID_REQUIRED_PARAMETER"),
            (.tapToPayReaderAccountDeactivated, "DECLINED_BY_STRIPE_API"),
            (.printerBusy, "PRINTER_BUSY"),
            (.printerPaperJam, "PRINTER_PAPERJAM"),
            (.printerOutOfPaper, "PRINTER_OUT_OF_PAPER"),
            (.printerCoverOpen, "PRINTER_COVER_OPEN"),
            (.printerAbsent, "PRINTER_ABSENT"),
            (.printerUnavailable, "PRINTER_UNAVAILABLE"),
            (.printerError, "PRINTER_ERROR"),
            (.readerBatteryLow, "READER_BATTERY_LOW"),
            (.readerConnectedToAnotherDevice, "READER_CONNECTED_TO_ANOTHER_DEVICE"),
            (.readerTampered, "READER_TAMPERED"),
            (.genericReaderError, "GENERIC_READER_ERROR"),
            (.collectDataApplicationError, "COLLECT_INPUTS_APPLICATION_ERROR"),
            (.displaySurchargeConsentApplicationError, "COLLECT_INPUTS_APPLICATION_ERROR"),
            (.commandInvalidAllowRedisplay, "ALLOW_REDISPLAY_INVALID"),
            (.tapToPayInternalNetworkError, "STRIPE_API_CONNECTION_ERROR")
        ]

        // WHEN mapping each ErrorCode to RNErrorCode
        // THEN the mapping should be correct for each case
        for (errorCode, expectedRNCode) in testCases {
            // WHEN creating error with Additional ErrorCode
            let nsError = makeNSError(code: errorCode.rawValue)
            let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

            // THEN it should map to correct RN error code
            XCTAssertEqual(error["code"] as? String, expectedRNCode,
                          "Failed Additional case mapping for \(errorCode)")
        }
    }


    // MARK: - Missing Coverage Tests

    func testMapToStripeErrorObject_invalidStripeErrorCode() {
        // GIVEN an NSError with Stripe domain but invalid error code (not handled by ErrorCode.Code enum)
        // Note: Current implementation uses exhaustive switch, so all valid ErrorCode cases are explicitly mapped
        // Instead, we test the unmappedErrorCode scenario through a valid case that maps to UNEXPECTED_SDK_ERROR but isn't unexpectedSdkError itself

        // Find a case that maps to UNEXPECTED_SDK_ERROR but isn't the actual unexpectedSdkError case
        let testCode = ErrorCode.Code.updatePaymentIntentUnavailableWhileOffline // This maps to UNEXPECTED_OPERATION, not UNEXPECTED_SDK_ERROR
        let nsError = makeNSError(domain: "com.stripe-terminal", code: testCode.rawValue, description: "Test unmapped scenario")

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN should map correctly without unmappedErrorCode
        // (since all cases are now explicitly mapped)
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "UNEXPECTED_OPERATION") // This is the correct mapping
        XCTAssertEqual(error["nativeErrorCode"] as? String, String(testCode.rawValue))

        // metadata should exist
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    func testMapToStripeErrorObject_unexpectedSdkErrorHandling() {
        // GIVEN the specific unexpectedSdkError case
        let nsError = makeNSError(code: ErrorCode.Code.unexpectedSdkError.rawValue, description: "SDK error")

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN should map correctly
        XCTAssertEqual(error["code"] as? String, "UNEXPECTED_SDK_ERROR")
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    func testMapToStripeErrorObject_nilDomainHandling() {
        // GIVEN an NSError with nil/empty components (edge case)
        let nsError = NSError(domain: "", code: 0, userInfo: [:])

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN should handle gracefully as non-Stripe error
        XCTAssertEqual(error["name"] as? String, "NonStripeError")
        XCTAssertEqual(error["code"] as? String, "UNEXPECTED_SDK_ERROR")
        XCTAssertEqual(error["nativeErrorCode"] as? String, ":0")

        // metadata should exist
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    func testMapToStripeErrorObject_multipleUnderlyingErrors() {
        // GIVEN an NSError with nested underlying errors
        let deepUnderlying = makeNSError(domain: "deep.error", code: 99, description: "Deep error")
        let midUnderlying = makeNSError(domain: "mid.error", code: 88,
                                       userInfo: [NSUnderlyingErrorKey: deepUnderlying],
                                       description: "Mid error")
        let topError = makeNSError(domain: "com.stripe-terminal",
                                  code: ErrorCode.Code.readerBusy.rawValue,
                                  userInfo: [NSUnderlyingErrorKey: midUnderlying],
                                  description: "Top error")

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: topError, source: .native)

        // THEN should capture only the immediate underlying error at top-level
        guard let underlyingInfo = error["underlyingError"] as? [String: Any] else {
            return XCTFail("Expected underlyingError at top-level")
        }
        XCTAssertEqual(underlyingInfo["iosDomain"] as? String, "mid.error")
        XCTAssertEqual(underlyingInfo["code"] as? String, "88")
        XCTAssertEqual(underlyingInfo["message"] as? String, "Mid error")
    }

    func testCreateError_withNSError_preservesStructure() {
        // GIVEN an NSError
        let nsError = makeNSError(code: ErrorCode.Code.cardReadTimedOut.rawValue, description: "Card timeout")

        // WHEN creating error wrapper
        let result = Errors.createErrorFromNSError(nsError: nsError, source: .native)

        // THEN should return proper wrapper structure
        XCTAssertNotNil(result["error"])
        XCTAssertNil(result["paymentIntent"], "Should not have paymentIntent for this error type")

        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error object")
        }
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "CARD_READ_TIMED_OUT")
    }

    func testCreateErrorFromNSError_regularError_returnsCompleteStructure() {
        // GIVEN a regular NSError (not a Confirm*Error)
        let regularError = makeNSError(
            code: ErrorCode.Code.readerBusy.rawValue,
            description: "Reader is busy"
        )

        // WHEN creating error without UUID
        let result = Errors.createErrorFromNSError(nsError: regularError, source: .native)

        // THEN should return structure with 'error' at top level,
        // and error object should have complete structure
        XCTAssertEqual(result.count, 1, "Should only have 'error' key for non-Confirm errors")
        XCTAssertNotNil(result["error"])
        XCTAssertNil(result["paymentIntent"])
        XCTAssertNil(result["setupIntent"])
        XCTAssertNil(result["refund"])

        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error object")
        }
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "READER_BUSY")
        XCTAssertNotNil(error["message"])
        XCTAssertNotNil(error["nativeErrorCode"])
        XCTAssertNotNil(error["metadata"])
        XCTAssertNil(error["apiError"], "apiError should not be present when userInfo has no API error fields")
    }

    func testCreateErrorFromNSError_withUUID_regularError_doesNotAddResponseObjects() {
        // GIVEN a regular NSError (not a Confirm*Error)
        let regularError = makeNSError(
            code: ErrorCode.Code.cardReadTimedOut.rawValue,
            description: "Card read timeout"
        )

        // WHEN creating error with UUID
        let result = Errors.createErrorFromNSError(nsError: regularError, uuid: "test-uuid-123", source: .native)

        // THEN should still only have 'error' key (UUID doesn't matter for non-Confirm errors)
        XCTAssertEqual(result.count, 1, "Should only have 'error' key")
        XCTAssertNotNil(result["error"])
        XCTAssertNil(result["paymentIntent"], "Should not have paymentIntent for non-Confirm error")
        XCTAssertNil(result["setupIntent"], "Should not have setupIntent for non-Confirm error")
        XCTAssertNil(result["refund"], "Should not have refund for non-Confirm error")

        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error object")
        }
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "CARD_READ_TIMED_OUT")
    }

    func testCreateErrorFromNSError_stripeAPIError_includesApiError() {
        // GIVEN a Stripe API error
        let apiError = makeNSError(
            domain: "com.stripe-terminal",
            code: ErrorCode.Code.stripeAPIError.rawValue,
            userInfo: [
                ErrorConstants.stripeAPIErrorCode: "invalid_request",
                ErrorConstants.stripeAPIDeclineCode: "generic_decline",
                ErrorConstants.stripeAPIFailureReason: "Test failure",
                ErrorConstants.stripeAPIRequestId: "req_123"
            ]
        )

        // WHEN creating error
        let result = Errors.createErrorFromNSError(nsError: apiError, source: .native)

        // THEN should have apiError at top level within error object
        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error object")
        }

        guard let apiError = error["apiError"] as? [String: Any] else {
            return XCTFail("Expected apiError in error object")
        }

        XCTAssertEqual(apiError["code"] as? String, "invalid_request")
        XCTAssertEqual(apiError["declineCode"] as? String, "generic_decline")
        XCTAssertEqual(apiError["message"] as? String, "Test failure")
        XCTAssertNotNil(error["metadata"])
    }

    func testCreateErrorFromNSError_stripeErrorWithoutApiInfo_doesNotIncludeApiError() {
        // GIVEN a Stripe error without API error information in userInfo
        let stripeError = makeNSError(
            domain: "com.stripe-terminal",
            code: ErrorCode.Code.readerBusy.rawValue,
            userInfo: [:] // No API error fields
        )

        // WHEN creating error
        let result = Errors.createErrorFromNSError(nsError: stripeError, source: .native)

        // THEN should NOT have apiError key (matching Android behavior when ApiError is null)
        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error object")
        }

        XCTAssertNil(error["apiError"], "apiError should not be present when userInfo has no API error fields")
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "READER_BUSY")
        XCTAssertNotNil(error["metadata"])
    }

    func testCreateErrorFromNSError_confirmPaymentIntentError_structureAlignedWithAndroid() {
        // GIVEN a ConfirmPaymentIntentError with declineCode
        let confirmError = MockConfirmPaymentIntentError(
            requestError: nil,
            declineCode: "card_declined"
        )

        // WHEN creating error (without UUID, simulating failure case)
        let result = Errors.createErrorFromNSError(nsError: confirmError, source: .native)

        // THEN the wrapper should match Android ('error' key with StripeError object), the error
        // object should have the correct structure, and apiError should be directly on the error.
        XCTAssertNotNil(result["error"], "Must have 'error' at top level")

        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error object")
        }

        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "DECLINED_BY_STRIPE_API")
        XCTAssertNotNil(error["message"])
        XCTAssertNotNil(error["nativeErrorCode"])

        guard let apiError = error["apiError"] as? [String: Any] else {
            return XCTFail("Expected apiError at top-level within error object")
        }
        XCTAssertEqual(apiError["declineCode"] as? String, "card_declined")

        XCTAssertNil(error["paymentIntent"], "Mock error does not contain a PaymentIntent")
        XCTAssertNil(error["setupIntent"], "Mock error does not contain a SetupIntent")
        XCTAssertNil(error["refund"], "Mock error does not contain a Refund")

        XCTAssertNotNil(error["metadata"])
    }

    func testCreateErrorFromNSError_confirmSetupIntentError_structureAlignedWithAndroid() {
        // GIVEN a ConfirmSetupIntentError
        let confirmError = MockConfirmSetupIntentError(
            requestError: nil,
            declineCode: "insufficient_funds"
        )

        // WHEN creating error with UUID
        let result = Errors.createErrorFromNSError(nsError: confirmError, uuid: "si-uuid-456", source: .native)

        // THEN the wrapper should match Android and apiError with declineCode should be present.
        XCTAssertNotNil(result["error"])

        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error object")
        }

        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "DECLINED_BY_STRIPE_API")

        guard let apiError = error["apiError"] as? [String: Any] else {
            return XCTFail("Expected apiError")
        }
        XCTAssertEqual(apiError["declineCode"] as? String, "insufficient_funds")

        XCTAssertNil(error["setupIntent"], "Mock error does not contain a SetupIntent")
    }

    func testCreateErrorFromNSError_confirmRefundError_structureAlignedWithAndroid() {
        // GIVEN a ConfirmRefundError
        let confirmError = MockConfirmRefundError(requestError: nil)

        // WHEN creating error
        let result = Errors.createErrorFromNSError(nsError: confirmError, uuid: "refund-uuid", source: .native)

        // THEN the wrapper should have the correct structure.
        XCTAssertNotNil(result["error"])

        guard let error = result["error"] as? [String: Any] else {
            return XCTFail("Expected error object")
        }

        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertNotNil(error["metadata"])

        XCTAssertNil(error["refund"], "Mock error does not contain a Refund")
    }

    func testMapToStripeErrorObject_doesNotIncludeResponseObjects() {
        // GIVEN a ConfirmPaymentIntentError with declineCode
        let confirmError = MockConfirmPaymentIntentError(
            requestError: nil,
            declineCode: "card_declined",
            mockPaymentIntent: nil
        )

        // WHEN using mapToStripeErrorObject (not createErrorFromNSError)
        let error = Errors.mapToStripeErrorObject(nsError: confirmError, source: .native)

        // THEN this lower-level mapper should NOT include response objects.
        // createErrorFromNSError adds PI/SI/Refund before wrapping the error.
        XCTAssertNil(error["paymentIntent"], "mapToStripeErrorObject should NOT include paymentIntent")
        XCTAssertNil(error["setupIntent"], "mapToStripeErrorObject should NOT include setupIntent")
        XCTAssertNil(error["refund"], "mapToStripeErrorObject should NOT include refund")
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertNotNil(error["apiError"], "Should have apiError with declineCode")
    }

    func testToUpperSnakeCase_edgeCases() {
        // GIVEN various string formats that might appear in error codes
        let testCases: [(String, String)] = [
            ("", ""),
            ("singleword", "SINGLEWORD"),
            ("camelCase", "CAMEL_CASE"),
            ("PascalCase", "PASCAL_CASE"),
            ("already_snake_case", "ALREADY_SNAKE_CASE"),
            ("ALREADY_UPPER", "ALREADY_UPPER"),
            ("mixedCASEExample", "MIXED_CASE_EXAMPLE"),
            ("number123Test", "NUMBER123_TEST"),
            ("HTTPSConnection", "HTTPS_CONNECTION"),
            ("multipleConsecutiveCAPS", "MULTIPLE_CONSECUTIVE_CAPS")
        ]

        // Note: toUpperSnakeCase is private, so we test it indirectly through unmapped error codes
        // This verifies the behavior through the public API
        for (input, expected) in testCases {
            // Test through the unmapped error code path
            if !input.isEmpty && input != expected {
                // Create a scenario where toUpperSnakeCase would be called
                let fakeErrorCode = ErrorCode.Code.readerBusy // Use any valid code
                // The actual testing of toUpperSnakeCase happens internally
                // when processing unmapped error codes

                // This is more of a documentation test showing the expected behavior
                XCTAssertNotEqual(input, expected, "Test case should show transformation: \(input) -> \(expected)")
            }
        }
    }

    func testMapToStripeErrorObject_withoutUnderlyingError() {
        // GIVEN an NSError with localized information but no underlying error
        let nsError = makeNSError(
            description: "Simple error",
            failureReason: "The reader is currently in use",
            recoverySuggestion: "Wait and retry"
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN error structure should be present
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["message"] as? String, "Simple error Wait and retry")

        // metadata should exist (can be empty)
        XCTAssertNotNil(error["metadata"] as? [String: Any])

        // The outer NSError must not be copied into underlyingError
        XCTAssertNil(error["underlyingError"])
    }

    // MARK: - Specialized Error Extraction Tests

    func testExtractSpecializedErrorFields_ConfirmRefundError() {
        // GIVEN a ConfirmRefundError with requestError
        // Note: We cannot test actual Refund extraction because Stripe SDK objects
        // cannot be instantiated (init is marked unavailable)
        let mockRequestError = makeNSError(domain: "com.stripe-terminal", code: 123, description: "Request failed")

        let confirmRefundError = MockConfirmRefundError(requestError: mockRequestError)

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: confirmRefundError, source: .native)

        // THEN basic error structure should be present
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    func testExtractSpecializedErrorFields_ConfirmRefundError_NoRequestError() {
        // GIVEN a ConfirmRefundError without requestError
        // Note: We cannot test actual Refund extraction because Stripe SDK objects
        // cannot be instantiated (init is marked unavailable)
        let confirmRefundError = MockConfirmRefundError(requestError: nil)

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: confirmRefundError, source: .native)

        // THEN basic error structure should be present
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    func testExtractSpecializedErrorFields_ConfirmPaymentIntentError() {
        // GIVEN a ConfirmPaymentIntentError with requestError and declineCode
        // Note: We cannot test actual PaymentIntent extraction because Stripe SDK objects
        // cannot be instantiated (init is marked unavailable)
        let mockRequestError = makeNSError(domain: "com.stripe-terminal", code: 456, description: "Network error")
        let declineCode = "card_declined"

        let confirmPaymentIntentError = MockConfirmPaymentIntentError(
            requestError: mockRequestError,
            declineCode: declineCode
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: confirmPaymentIntentError, source: .native)

        // THEN should extract declineCode into apiError at top-level
        guard let apiError = error["apiError"] as? [String: Any] else {
            return XCTFail("Expected apiError at top-level")
        }

        XCTAssertEqual(apiError["declineCode"] as? String, "card_declined")
    }

    func testExtractSpecializedErrorFields_ConfirmPaymentIntentError_NoOptionalFields() {
        // GIVEN a ConfirmPaymentIntentError without optional fields (no declineCode)
        // In real scenarios, ConfirmPaymentIntentError without any API error fields
        // means it's not an API-level error, so apiError should not be present
        let confirmPaymentIntentError = MockConfirmPaymentIntentError(
            requestError: nil,
            declineCode: nil
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: confirmPaymentIntentError, source: .native)

        // THEN apiError should NOT be present (matching Android behavior when ApiError is null)
        XCTAssertNil(error["apiError"], "apiError should not be present when no API error information exists")
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertEqual(error["code"] as? String, "DECLINED_BY_STRIPE_API")
    }

    func testExtractSpecializedErrorFields_ConfirmSetupIntentError() {
        // GIVEN a ConfirmSetupIntentError with requestError and declineCode
        // Note: We cannot test actual SetupIntent extraction because Stripe SDK objects
        // cannot be instantiated (init is marked unavailable)
        let mockRequestError = makeNSError(domain: "com.stripe-terminal", code: 789, description: "API error")
        let declineCode = "insufficient_funds"

        let confirmSetupIntentError = MockConfirmSetupIntentError(
            requestError: mockRequestError,
            declineCode: declineCode
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: confirmSetupIntentError, source: .native)

        // THEN should extract declineCode into apiError at top-level
        guard let apiError = error["apiError"] as? [String: Any] else {
            return XCTFail("Expected apiError at top-level")
        }

        XCTAssertEqual(apiError["declineCode"] as? String, "insufficient_funds")
    }

    func testExtractSpecializedErrorFields_ConfirmSetupIntentError_OnlyDeclineCode() {
        // GIVEN a ConfirmSetupIntentError with declineCode only
        // Note: We cannot test actual SetupIntent extraction because Stripe SDK objects
        // cannot be instantiated (init is marked unavailable)
        let confirmSetupIntentError = MockConfirmSetupIntentError(
            requestError: nil,
            declineCode: "expired_card"
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: confirmSetupIntentError, source: .native)

        // THEN should extract declineCode into apiError
        guard let apiError = error["apiError"] as? [String: Any] else {
            return XCTFail("Expected apiError at top-level")
        }

        XCTAssertEqual(apiError["declineCode"] as? String, "expired_card")
    }

    func testExtractSpecializedErrorFields_NonConfirmError() {
        // GIVEN a regular NSError (not a Confirm*Error)
        let regularError = makeNSError(
            code: ErrorCode.Code.readerBusy.rawValue,
            description: "Regular error"
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: regularError, source: .native)

        // THEN should have basic error structure
        XCTAssertEqual(error["name"] as? String, "StripeError")
        XCTAssertNotNil(error["metadata"] as? [String: Any])
    }

    func testExtractSpecializedErrorFields_CreateErrorWrapper() {
        // GIVEN a ConfirmPaymentIntentError with declineCode
        let confirmPaymentIntentError = MockConfirmPaymentIntentError(
            requestError: nil,
            declineCode: "card_declined"
        )

        // WHEN creating error wrapper (the public API used by RN bridge)
        let wrapped = Errors.createErrorFromNSError(nsError: confirmPaymentIntentError, source: .native)

        // THEN should have proper structure with declineCode in apiError
        guard let error = wrapped["error"] as? [String: Any] else {
            return XCTFail("Expected error object")
        }
        XCTAssertEqual(error["name"] as? String, "StripeError")

        guard let apiError = error["apiError"] as? [String: Any] else {
            return XCTFail("Expected apiError in error")
        }
        XCTAssertEqual(apiError["declineCode"] as? String, "card_declined")
    }

    // MARK: - Platform-Specific Metadata Tests

    func testAddPlatformMetadata_withAllFields() {
        // GIVEN an NSError with iOS-specific fields in userInfo
        let userInfo: [String: Any] = [
            ErrorConstants.deviceBannedUntilDate: "2025-12-31T23:59:59Z",
            ErrorConstants.prepareFailedReason: "Device setup failed",
            ErrorConstants.httpStatusCode: 503,
            ErrorConstants.readerMessage: "Insert card",
            ErrorConstants.stripeAPIRequestId: "req_123abc",
            ErrorConstants.stripeAPIFailureReason: "API rate limit exceeded",
            ErrorConstants.offlineDeclineReason: "Card expired",
            ErrorConstants.tapToPayReaderErrorName: "SessionExpired"
        ]
        let nsError = makeNSError(
            code: ErrorCode.Code.readerBusy.rawValue,
            userInfo: userInfo,
            description: "Test error"
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN all platform-specific fields should be in metadata
        guard let metadata = error["metadata"] as? [String: Any] else {
            return XCTFail("Expected metadata")
        }

        XCTAssertEqual(metadata[ErrorConstants.rnMetadataDeviceBannedUntilDate] as? String, "2025-12-31T23:59:59Z")
        XCTAssertEqual(metadata[ErrorConstants.rnMetadataPrepareFailedReason] as? String, "Device setup failed")
        XCTAssertEqual(metadata[ErrorConstants.rnMetadataHttpStatusCode] as? Int, 503)
        XCTAssertEqual(metadata[ErrorConstants.rnMetadataReaderMessage] as? String, "Insert card")
        XCTAssertEqual(metadata[ErrorConstants.rnMetadataStripeAPIRequestId] as? String, "req_123abc")
        XCTAssertEqual(metadata[ErrorConstants.rnMetadataStripeAPIFailureReason] as? String, "API rate limit exceeded")
        XCTAssertEqual(metadata[ErrorConstants.rnMetadataOfflineDeclineReason] as? String, "Card expired")
        XCTAssertEqual(metadata[ErrorConstants.rnMetadataTapToPayReaderErrorName] as? String, "SessionExpired")
    }

    func testAddPlatformMetadata_withPartialFields() {
        // GIVEN an NSError with only some iOS-specific fields
        let userInfo: [String: Any] = [
            ErrorConstants.httpStatusCode: 404,
            ErrorConstants.stripeAPIRequestId: "req_xyz789"
        ]
        let nsError = makeNSError(
            code: ErrorCode.Code.stripeAPIError.rawValue,
            userInfo: userInfo,
            description: "API error"
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN only provided fields should be in metadata
        guard let metadata = error["metadata"] as? [String: Any] else {
            return XCTFail("Expected metadata")
        }

        XCTAssertEqual(metadata[ErrorConstants.rnMetadataHttpStatusCode] as? Int, 404)
        XCTAssertEqual(metadata[ErrorConstants.rnMetadataStripeAPIRequestId] as? String, "req_xyz789")

        XCTAssertNil(metadata[ErrorConstants.rnMetadataDeviceBannedUntilDate])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataPrepareFailedReason])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataReaderMessage])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataStripeAPIFailureReason])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataOfflineDeclineReason])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataTapToPayReaderErrorName])
    }

    func testAddPlatformMetadata_withNoSpecialFields() {
        // GIVEN an NSError with no iOS-specific fields
        let nsError = makeNSError(
            code: ErrorCode.Code.bluetoothDisabled.rawValue,
            userInfo: [:],
            description: "Bluetooth disabled"
        )

        // WHEN mapping to stripe error object
        let error = Errors.mapToStripeErrorObject(nsError: nsError, source: .native)

        // THEN metadata should exist (but be empty for iOS when no special fields)
        // and platform-specific fields should not be present
        guard let metadata = error["metadata"] as? [String: Any] else {
            return XCTFail("Expected metadata")
        }

        XCTAssertNil(metadata[ErrorConstants.rnMetadataDeviceBannedUntilDate])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataPrepareFailedReason])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataHttpStatusCode])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataReaderMessage])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataStripeAPIRequestId])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataStripeAPIFailureReason])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataOfflineDeclineReason])
        XCTAssertNil(metadata[ErrorConstants.rnMetadataTapToPayReaderErrorName])

        XCTAssertEqual(metadata.count, 0, "Metadata should be empty when no platform-specific fields are present")
    }

    func testErrorConstants_usesSDKKeys() {
        // GIVEN the ErrorConstants from Stripe Terminal SDK
        // WHEN checking the constant values
        // THEN they should match the SDK's ErrorKey enum raw values

        // These assertions verify that we're using the correct SDK keys
        // The actual values come from StripeTerminal.ErrorKey enum
        XCTAssertFalse(ErrorConstants.deviceBannedUntilDate.isEmpty)
        XCTAssertFalse(ErrorConstants.prepareFailedReason.isEmpty)
        XCTAssertFalse(ErrorConstants.httpStatusCode.isEmpty)
        XCTAssertFalse(ErrorConstants.stripeAPIRequestId.isEmpty)
        XCTAssertFalse(ErrorConstants.stripeAPIFailureReason.isEmpty)
        XCTAssertFalse(ErrorConstants.stripeAPIErrorType.isEmpty)
        XCTAssertFalse(ErrorConstants.stripeAPIDocUrl.isEmpty)
        XCTAssertFalse(ErrorConstants.stripeAPIErrorParameter.isEmpty)
        XCTAssertFalse(ErrorConstants.readerMessage.isEmpty)
        XCTAssertFalse(ErrorConstants.offlineDeclineReason.isEmpty)
        XCTAssertFalse(ErrorConstants.tapToPayReaderErrorName.isEmpty)
        XCTAssertFalse(ErrorConstants.stripeAPIDeclineCode.isEmpty)
        XCTAssertFalse(ErrorConstants.stripeAPICharge.isEmpty)
        XCTAssertFalse(ErrorConstants.stripeAPIError.isEmpty)
    }

    // MARK: - Error and PaymentIntent/SetupIntent Mutual Exclusivity Tests

    /// Tests that general error response does NOT contain PaymentIntent.
    /// Business logic: In StripeTerminalReactNative callbacks, when error path is taken with a general error,
    /// the result from Errors.createErrorFromNSError should NOT include paymentIntent.
    ///
    /// This mirrors the callback pattern:
    /// ```
    /// if let error = processError as NSError? {
    ///     var result = Errors.createErrorFromNSError(nsError: error, source: .native)
    ///     resolve(result)  // result should NOT have paymentIntent for general errors
    /// }
    /// ```
    func testGeneralErrorResponse_doesNotContainPaymentIntent() {
        // GIVEN a general error (not ConfirmPaymentIntentError)
        let generalError = makeNSError(code: ErrorCode.Code.readerBusy.rawValue, description: "Reader busy")

        // WHEN creating error response (simulating error path in callback)
        let result = Errors.createErrorFromNSError(nsError: generalError, source: .native)

        // THEN result must have error but NOT paymentIntent
        XCTAssertNotNil(result[ErrorConstants.rnError])
        XCTAssertNil(result[ErrorConstants.rnPaymentIntent], "General error response must NOT contain 'paymentIntent'")
    }

    /// Tests that general error response does NOT contain SetupIntent.
    /// Business logic: In StripeTerminalReactNative callbacks, when error path is taken with a general error,
    /// the result from Errors.createErrorFromNSError should NOT include setupIntent.
    func testGeneralErrorResponse_doesNotContainSetupIntent() {
        // GIVEN a general error (not ConfirmSetupIntentError)
        let generalError = makeNSError(code: ErrorCode.Code.readerBusy.rawValue, description: "Reader busy")

        // WHEN creating error response (simulating error path in callback)
        let result = Errors.createErrorFromNSError(nsError: generalError, source: .native)

        // THEN result must have error but NOT setupIntent
        XCTAssertNotNil(result[ErrorConstants.rnError])
        XCTAssertNil(result[ErrorConstants.rnSetupIntent], "General error response must NOT contain 'setupIntent'")
    }

    // MARK: - mapFromApiError Tests

    func testMapFromApiError_returnsNilWhenApiErrorIsNil() {
        // GIVEN a nil ApiError
        let apiError: ApiError? = nil

        // WHEN mapping
        let result = Errors.mapFromApiError(apiError)

        // THEN should return nil
        XCTAssertNil(result)
    }

    // NOTE: Additional mapFromApiError tests require a real ApiError instance.
    // Since ApiError's init() is unavailable and it cannot be subclassed,
    // full coverage of mapFromApiError is achieved through:
    // 1. PaymentIntent mapping tests (via Mappers.mapFromPaymentIntent)
    // 2. Integration tests with real SDK responses
    // 3. The extractApiErrorToTopLevel tests which cover similar logic for NSError-based API errors

    // MARK: - AppsOnDevicesConnectionTokenProvider Validation Tests

    func testValidateAppsOnDevicesConnectionTokenProviderNotUsed_RejectsWhenTrue() {
        // GIVEN params with useAppsOnDevicesConnectionTokenProvider set to true
        let params: NSDictionary = ["useAppsOnDevicesConnectionTokenProvider": true]

        // WHEN validating AppsOnDevices usage
        let error = Errors.validateAppsOnDevicesConnectionTokenProviderNotUsed(params)

        // THEN should return an error
        XCTAssertNotNil(error)
        guard let errorDict = error?["error"] as? [String: Any] else {
            XCTFail("Expected error dictionary")
            return
        }
        XCTAssertEqual(errorDict["code"] as? String, "UNSUPPORTED_SDK")
        XCTAssertEqual(errorDict["message"] as? String, "AppsOnDevicesConnectionTokenProvider is not supported on iOS.")
    }

    func testValidateAppsOnDevicesConnectionTokenProviderNotUsed_AllowsWhenFalse() {
        // GIVEN params with useAppsOnDevicesConnectionTokenProvider set to false
        let params: NSDictionary = ["useAppsOnDevicesConnectionTokenProvider": false]

        // WHEN validating AppsOnDevices usage
        let error = Errors.validateAppsOnDevicesConnectionTokenProviderNotUsed(params)

        // THEN should return nil (no error)
        XCTAssertNil(error)
    }
}

// MARK: - Mock Classes for Testing Specialized Errors

// MARK: - Mock Objects for Testing

private class MockConfirmRefundError: NSError {
    private let mockRequestError: NSError?

    init(requestError: NSError? = nil) {
        self.mockRequestError = requestError
        super.init(domain: "com.stripe-terminal", code: ErrorCode.Code.refundFailed.rawValue, userInfo: [:])
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    override var description: String {
        return "SCPConfirmRefundError"
    }

    override func value(forKey key: String) -> Any? {
        switch key {
        case "requestError": return mockRequestError
        default: return super.value(forKey: key)
        }
    }
}

private class MockConfirmPaymentIntentError: NSError {
    private let mockRequestError: NSError?
    private let mockDeclineCode: String?

    init(requestError: NSError?, declineCode: String?, mockPaymentIntent: Any? = nil) {
        self.mockRequestError = requestError
        self.mockDeclineCode = declineCode

        // Build userInfo with both declineCode and stripeAPIErrorCode to match real SDK behavior
        var userInfo: [String: Any] = [:]
        if let declineCode = declineCode {
            userInfo[ErrorConstants.stripeAPIDeclineCode] = declineCode
            // When there's a declineCode, there's always an API error code
            userInfo[ErrorConstants.stripeAPIErrorCode] = "card_error"
        }

        super.init(domain: "com.stripe-terminal", code: ErrorCode.Code.declinedByStripeAPI.rawValue, userInfo: userInfo)
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    override var description: String {
        return "SCPConfirmPaymentIntentError"
    }

    override func value(forKey key: String) -> Any? {
        switch key {
        case "requestError": return mockRequestError
        case "declineCode": return mockDeclineCode
        default: return super.value(forKey: key)
        }
    }
}

private class MockConfirmSetupIntentError: NSError {
    private let mockRequestError: NSError?
    private let mockDeclineCode: String?

    init(requestError: NSError?, declineCode: String?, mockSetupIntent: Any? = nil) {
        self.mockRequestError = requestError
        self.mockDeclineCode = declineCode

        // Build userInfo with both declineCode and stripeAPIErrorCode to match real SDK behavior
        var userInfo: [String: Any] = [:]
        if let declineCode = declineCode {
            userInfo[ErrorConstants.stripeAPIDeclineCode] = declineCode
            // When there's a declineCode, there's always an API error code
            userInfo[ErrorConstants.stripeAPIErrorCode] = "card_error"
        }

        super.init(domain: "com.stripe-terminal", code: ErrorCode.Code.declinedByStripeAPI.rawValue, userInfo: userInfo)
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    override var description: String {
        return "SCPConfirmSetupIntentError"
    }

    override func value(forKey key: String) -> Any? {
        switch key {
        case "requestError": return mockRequestError
        case "declineCode": return mockDeclineCode
        default: return super.value(forKey: key)
        }
    }
}

private final class ErrorEventEmitter: StripeTerminalReactNative {
    var events: [(String, [String: Any])] = []

    override func sendEvent(withName name: String!, body: Any!) {
        events.append((name, body as? [String: Any] ?? [:]))
    }
}
