Support card reader auto-reconnection

Modules/Sources/Hardware/CardReader/CardReaderReconnectionState.swift

@@ -0,0 +1,18 @@
+import Foundation
+
+/// Represents the state of a card reader auto-reconnection attempt.
+/// When a Bluetooth card reader unexpectedly disconnects, the Stripe Terminal SDK
+/// automatically attempts to reconnect. These states track that process.
+public enum CardReaderReconnectionState: Equatable {
+    /// No reconnection attempt is in progress.
+    case idle
+
+    /// The SDK is attempting to automatically reconnect to the reader.
+    case reconnecting(reader: CardReader)
+
+    /// The auto-reconnection succeeded.
+    case succeeded(reader: CardReader)
+
+    /// The auto-reconnection failed.
+    case failed(reader: CardReader)
+}

Modules/Sources/Hardware/CardReader/CardReaderService.swift

@@ -20,6 +20,9 @@ public protocol CardReaderService {
     /// The Publisher that emits when TTP Terms and Services are accepted
     var tapToPayCardReaderAcceptToSEvents: AnyPublisher<Void, Never> { get }
 
+    /// The Publisher that emits reconnection state changes for Bluetooth readers
+    var reconnectionEvents: AnyPublisher<CardReaderReconnectionState, Never> { get }
+
     // MARK: - Commands
 
     /// Checks for support of a given reader type and discovery method combination. Does not start discovery.
@@ -73,4 +76,9 @@ public protocol CardReaderService {
     ///
     /// To check the progress of the update, observe the softwareUpdateEvents publisher.
     func installUpdate() -> Void
+
+    /// Cancels an in-progress auto-reconnection attempt.
+    /// Use this when the user wants to manually connect a different reader
+    /// or cancel the automatic reconnection process.
+    func cancelReconnection() -> Future<Void, Error>
 }

Modules/Sources/Hardware/CardReader/CardReaderServiceError.swift

@@ -45,6 +45,9 @@ public enum CardReaderServiceError: Error {
     /// Error thrown while updating the reader firmware
     case softwareUpdate(underlyingError: UnderlyingError = .internalServiceError, batteryLevel: Double?)
 
+    /// Error thrown while cancelling an auto-reconnection attempt
+    case reconnectionCancellation(underlyingError: UnderlyingError = .internalServiceError)
+
     /// The user has denied the app permission to use Bluetooth
     case bluetoothDenied
 
@@ -74,7 +77,8 @@ extension CardReaderServiceError: LocalizedError {
                 .refundCreation(let underlyingError),
                 .refundPayment(let underlyingError, _),
                 .refundCancellation(let underlyingError),
-                .softwareUpdate(let underlyingError, _):
+                .softwareUpdate(let underlyingError, _),
+                .reconnectionCancellation(let underlyingError):
             return underlyingError.errorDescription
         case .paymentCaptureWithPaymentMethod(underlyingError: let underlyingError, paymentMethod: _):
             return underlyingError.errorDescription ?? underlyingError.localizedDescription

Modules/Sources/Hardware/CardReader/StripeCardReader/NoOpCardReaderService.swift

@@ -21,6 +21,10 @@ public struct NoOpCardReaderService: CardReaderService {
     public var tapToPayCardReaderAcceptToSEvents: AnyPublisher<Void, Never>
     = PassthroughSubject<Void, Never>().eraseToAnyPublisher()
 
+    /// The Publisher that emits reconnection state changes for Bluetooth readers
+    public var reconnectionEvents: AnyPublisher<CardReaderReconnectionState, Never>
+    = CurrentValueSubject<CardReaderReconnectionState, Never>(.idle).eraseToAnyPublisher()
+
     public init() {}
     // MARK: - Commands
 
@@ -110,4 +114,11 @@ public struct NoOpCardReaderService: CardReaderService {
     public func installUpdate() -> Void {
         // no-op
     }
+
+    /// Cancels an in-progress auto-reconnection attempt.
+    public func cancelReconnection() -> Future<Void, Error> {
+        return Future() { promise in
+            promise(.success(()))
+        }
+    }
 }

Modules/Sources/Hardware/CardReader/StripeCardReader/StripeCardReaderService.swift

@@ -10,6 +10,7 @@ public final class StripeCardReaderService: NSObject {
     private var discoveryCancellable: StripeTerminal.Cancelable?
     private var paymentCancellable: StripeTerminal.Cancelable?
     private var refundCancellable: StripeTerminal.Cancelable?
+    private var reconnectionCancelable: StripeTerminal.Cancelable?
     private var cancellables = Set<AnyCancellable>()
 
     private var discoveredReadersSubject = CurrentValueSubject<[CardReader], Error>([])
@@ -18,6 +19,7 @@ public final class StripeCardReaderService: NSObject {
     private let readerEventsSubject = PassthroughSubject<CardReaderEvent, Never>()
     private let softwareUpdateSubject = CurrentValueSubject<CardReaderSoftwareUpdateState, Never>(.none)
     private let tapToPayCardReaderAcceptToSSubject = PassthroughSubject<Void, Never>()
+    private let reconnectionStateSubject = CurrentValueSubject<CardReaderReconnectionState, Never>(.idle)
 
     private var connectionAttemptInvalidated: Bool = false
 
@@ -69,6 +71,10 @@ extension StripeCardReaderService: CardReaderService {
         tapToPayCardReaderAcceptToSSubject.eraseToAnyPublisher()
     }
 
+    public var reconnectionEvents: AnyPublisher<CardReaderReconnectionState, Never> {
+        reconnectionStateSubject.eraseToAnyPublisher()
+    }
+
     // MARK: - CardReaderService conformance. Commands
 
     public func checkSupport(for cardReaderType: CardReaderType,
@@ -493,6 +499,7 @@ extension StripeCardReaderService: CardReaderService {
                 switch result {
                 case .success(let locationId):
                     let buildConfig = BluetoothConnectionConfigurationBuilder(delegate: self, locationId: locationId)
+                        .setAutoReconnectOnUnexpectedDisconnect(true)
                     do {
                         let config = try buildConfig.build()
                         return promise(.success(config))
@@ -630,6 +637,44 @@ extension StripeCardReaderService: CardReaderService {
     public func installUpdate() -> Void {
         Terminal.shared.installAvailableUpdate()
     }
+
+    public func cancelReconnection() -> Future<Void, Error> {
+        Future { [weak self] promise in
+            guard let self else {
+                return promise(.success(()))
+            }
+
+            guard let reconnectionCancelable = self.reconnectionCancelable,
+                  !reconnectionCancelable.completed else {
+                self.reconnectionCancelable = nil
+                self.reconnectionStateSubject.send(.idle)
+                return promise(.success(()))
+            }
+
+            DDLogInfo("💳 Reconnection cancellation requested")
+            reconnectionCancelable.cancel { [weak self] error in
+                self?.reconnectionCancelable = nil
+
+                // Treat cancelFailedAlreadyCompleted as success - reconnection already completed.
+                if let error = error as? ErrorCode,
+                   error.code == .cancelFailedAlreadyCompleted {
+                    DDLogInfo("💳 Reconnection cancellation: reconnection already completed")
+                    self?.reconnectionStateSubject.send(.idle)
+                    promise(.success(()))
+                } else if let error = error {
+                    self?.connectedReadersSubject.send([])
+                    self?.reconnectionStateSubject.send(.idle)
+                    let underlyingError = Self.logAndDecodeError(error)
+                    promise(.failure(CardReaderServiceError.reconnectionCancellation(underlyingError: underlyingError)))
+                } else {
+                    DDLogInfo("💳 Reconnection cancellation succeeded")
+                    self?.connectedReadersSubject.send([])
+                    self?.reconnectionStateSubject.send(.idle)
+                    promise(.success(()))
+                }
+            }
+        }
+    }
 }
 
 struct CardReaderMetadata {
@@ -994,6 +1039,40 @@ extension StripeCardReaderService: MobileReaderDelegate {
     public func reader(_ reader: Reader, didDisconnect reason: DisconnectReason) {
         connectedReadersSubject.send([])
     }
+
+    // MARK: - Reconnection delegate methods
+
+    public func reader(_ reader: Reader, didStartReconnect cancelable: Cancelable, disconnectReason: DisconnectReason) {
+        DDLogInfo("💳 Reader started auto-reconnection, reason: \(Terminal.stringFromDisconnectReason(disconnectReason))")
+        reconnectionCancelable = cancelable
+        // Clear connected readers so the UI shows reconnecting state instead of connected
+        connectedReadersSubject.send([])
+        let cardReader = CardReader(reader: reader)
+        reconnectionStateSubject.send(.reconnecting(reader: cardReader))
+    }
+
+    public func readerDidSucceedReconnect(_ reader: Reader) {
+        DDLogInfo("💳 Reader auto-reconnection succeeded")
+        reconnectionCancelable = nil
+        let cardReader = CardReader(reader: reader)
+        reconnectionStateSubject.send(.succeeded(reader: cardReader))
+        connectedReadersSubject.send([cardReader])
+        reconnectionStateSubject.send(.idle)
+    }
+
+    public func readerDidFailReconnect(_ reader: Reader) {
+        // Only log as an error if reconnection was still in progress.
+        // When the user cancels reconnection, the cancelable is nilled out before
+        // this delegate fires, so the failure is expected and not worth logging.
+        if reconnectionCancelable != nil {
+            DDLogError("💳 Reader auto-reconnection failed")
+        }
+        reconnectionCancelable = nil
+        let cardReader = CardReader(reader: reader)
+        reconnectionStateSubject.send(.failed(reader: cardReader))
+        connectedReadersSubject.send([])
+        reconnectionStateSubject.send(.idle)
+    }
 }
 
 extension StripeCardReaderService: TapToPayReaderDelegate {

Modules/Sources/PointOfSale/Card Present Payments/CardPresentPaymentFacade.swift

@@ -55,4 +55,9 @@ public protocol CardPresentPaymentFacade {
 
     /// Cancels any in-progress payment, returning when complete
     func cancelPayment() async throws
+
+    /// Cancels an in-progress auto-reconnection attempt.
+    /// Use this when the user wants to manually connect a different reader
+    /// or cancel the automatic reconnection process.
+    func cancelReconnection() async
 }

Modules/Sources/PointOfSale/Card Present Payments/CardPresentPaymentPreviewService.swift

@@ -41,6 +41,14 @@ final class CardPresentPaymentPreviewService: CardPresentPaymentFacade {
         // no-op
     }
 
+    func cancelPayment() async throws {
+        // no-op
+    }
+
+    func cancelReconnection() async {
+        // no-op
+    }
+
     func updateCardReaderSoftware() async throws {
         // no-op
     }

Modules/Sources/PointOfSale/Card Present Payments/CardPresentPaymentReaderConnectionStatus.swift

@@ -5,4 +5,5 @@ public enum CardPresentPaymentReaderConnectionStatus: Equatable {
     case connected(CardPresentPaymentCardReader)
     case cancellingConnection
     case disconnecting
+    case reconnecting(CardPresentPaymentCardReader)
 }

Modules/Sources/PointOfSale/Card Present Payments/CardPresentPaymentsRetryApproach.swift

@@ -29,7 +29,8 @@ private extension CardReaderServiceError {
                 .paymentCancellation(underlyingError: let underlyingError),
                 .refundCreation(underlyingError: let underlyingError),
                 .refundCancellation(underlyingError: let underlyingError),
-                .softwareUpdate(underlyingError: let underlyingError, _):
+                .softwareUpdate(underlyingError: let underlyingError, _),
+                .reconnectionCancellation(underlyingError: let underlyingError):
             return underlyingError.retryApproach(with: retryAction)
         case .refundPayment(underlyingError: let underlyingError, shouldRetry: let shouldRetry):
             guard shouldRetry else {

Modules/Sources/PointOfSale/Controllers/POSPaymentModel.swift

@@ -111,7 +111,7 @@ extension POSPaymentModel {
                     switch status {
                     case .connected:
                         return true
-                    case .disconnected, .disconnecting, .cancellingConnection:
+                    case .disconnected, .disconnecting, .cancellingConnection, .reconnecting:
                         return false
                     }
                 }
@@ -171,7 +171,15 @@ extension POSPaymentModel {
     }
 
     func cancelThenCollectPayment() async {
+        if case .reconnecting = cardReaderConnectionStatus {
+            await cardPresentPaymentService.cancelReconnection()
+        }
+
         try? await cardPresentPaymentService.cancelPayment()
+
+        guard case .connected = cardReaderConnectionStatus else {
+            return
+        }
         await collectCardPayment()
     }
 
@@ -182,6 +190,12 @@ extension POSPaymentModel {
         }
     }
 
+    func cancelReconnection() {
+        Task { @MainActor [weak self] in
+            await self?.cardPresentPaymentService.cancelReconnection()
+        }
+    }
+
     func disconnectCardReader() {
         analytics.track(.cardReaderDisconnectTapped)
         Task { @MainActor [weak self] in

Modules/Sources/PointOfSale/Models/PointOfSaleAggregateModel.swift

@@ -382,6 +382,11 @@ extension PointOfSaleAggregateModel {
         paymentModel.connectCardReader()
     }
 
+    @MainActor
+    func cancelReconnection() {
+        paymentModel.cancelReconnection()
+    }
+
     @MainActor
     func disconnectCardReader() {
         paymentModel.disconnectCardReader()

Modules/Sources/PointOfSale/Models/PointOfSaleSettingsController.swift

@@ -61,7 +61,7 @@ protocol POSSettingsControllerProtocol {
                 guard let self else { return }
                 let cardReader: CardPresentPaymentCardReader?
                 switch connectionStatus {
-                case .connected(let reader):
+                case .connected(let reader), .reconnecting(let reader):
                     cardReader = reader
                 default:
                     cardReader = nil

Modules/Sources/PointOfSale/Presentation/Card Present Payments/Reader Messages/PointOfSaleCardPresentPaymentReconnectingMessageViewModel.swift

@@ -0,0 +1,22 @@
+import Foundation
+
+struct PointOfSaleCardPresentPaymentReconnectingMessageViewModel {
+    let title = Localization.title
+    let cancelReconnectionButtonTitle = Localization.cancelReconnection
+}
+
+private extension PointOfSaleCardPresentPaymentReconnectingMessageViewModel {
+    enum Localization {
+        static let title = NSLocalizedString(
+            "pointOfSale.cardPresent.reconnecting.title",
+            value: "Reconnecting reader...",
+            comment: "Title shown on the Point of Sale Checkout when the card reader is reconnecting"
+        )
+
+        static let cancelReconnection = NSLocalizedString(
+            "pointOfSale.cardPresent.cancelReconnection.button.title",
+            value: "Cancel reconnection",
+            comment: "Button to cancel card reader reconnection, shown on the Point of Sale Checkout"
+        )
+    }
+}

Modules/Sources/PointOfSale/Presentation/CardReaderConnection/CardReaderConnectionStatusView.swift

@@ -5,6 +5,7 @@ struct CardReaderConnectionStatusView: View {
     @Environment(PointOfSaleAggregateModel.self) private var posModel
     @ScaledMetric private var scale: CGFloat = 1.0
     @Environment(\.isEnabled) var isEnabled
+    @State private var isCancellingReconnection = false
 
     @ViewBuilder
     private func circleIcon(with color: Color) -> some View {
@@ -57,9 +58,27 @@ struct CardReaderConnectionStatusView: View {
                     .padding(Constants.disconnectedBorderInset)
                 }
                 .accessibilityIdentifier("pos-connect-reader-button")
+            case .reconnecting:
+                Menu {
+                    Button {
+                        isCancellingReconnection = true
+                        posModel.cancelReconnection()
+                    } label: {
+                        Text(Localization.cancelReconnection)
+                    }
+                } label: {
+                    progressIndicatingCardReaderStatus(
+                        title: isCancellingReconnection ? Localization.cancellingReconnection : Localization.readerReconnecting
+                    )
+                }
+                .disabled(isCancellingReconnection)
+                .accessibilityIdentifier("pos-reader-reconnecting")
             }
         }
         .font(Constants.font)
+        .onChange(of: posModel.cardReaderConnectionStatus) {
+            isCancellingReconnection = false
+        }
         .dynamicTypeSize(...DynamicTypeSize.accessibility2)
         .opacity(isEnabled ? 1 : 0.5)
     }
@@ -148,8 +167,8 @@ private extension CardReaderConnectionStatusView {
         )
 
         static let disconnectCardReader = NSLocalizedString(
-            "pointOfSale.floatingButtons.disconnectCardReader.button.title",
-            value: "Disconnect Reader",
+            "pointOfSale.floatingButtons.disconnectCardReader.button.title.2",
+            value: "Disconnect reader",
             comment: "The title of the menu button to disconnect a connected card reader, as confirmation."
         )
 
@@ -159,6 +178,24 @@ private extension CardReaderConnectionStatusView {
             comment: "The title of the floating button to indicate that the reader is not ready for another " +
             "connection, usually because a connection has just been cancelled"
         )
+
+        static let readerReconnecting = NSLocalizedString(
+            "pointOfSale.floatingButtons.readerReconnecting.title",
+            value: "Reconnecting…",
+            comment: "The title of the floating button to indicate that the reader is attempting to reconnect."
+        )
+
+        static let cancelReconnection = NSLocalizedString(
+            "pointOfSale.floatingButtons.cancelReconnection.button.title",
+            value: "Cancel reconnection",
+            comment: "The title of the menu button to cancel an ongoing card reader reconnection attempt."
+        )
+
+        static let cancellingReconnection = NSLocalizedString(
+            "pointOfSale.floatingButtons.cancellingReconnection.title",
+            value: "Cancelling…",
+            comment: "The title of the floating button to indicate that the reader reconnection is being cancelled."
+        )
     }
 }