@padosoft/react-native-ecr17 0.0.0

package/cpp/Lcr/Lcr.cpp

@@ -0,0 +1,42 @@
+#include "Lcr.hpp"
+
+namespace margelo::nitro::ecr17 {
+
+static constexpr uint8_t STX = 0x02;
+static constexpr uint8_t ETX = 0x03;
+
+uint8_t Lrc::compute(const std::vector<uint8_t>& payload, LrcMode mode) {
+    uint8_t lrc = BASE;
+
+    switch (mode) {
+        case LrcMode::STX:
+        case LrcMode::STX_NOEXT:
+            lrc ^= STX;
+            break;
+
+        default:
+            break;
+    }
+
+    for (auto b : payload) {
+        lrc ^= b;
+    }
+
+    switch (mode) {
+        case LrcMode::STX:
+        case LrcMode::NOEXT:
+            lrc ^= ETX;
+            break;
+
+        default:
+            break;
+    }
+
+    return lrc;
+}
+
+uint8_t Lrc::compute(const std::string& payload, LrcMode mode) {
+    return compute(std::vector<uint8_t>(payload.begin(), payload.end()), mode);
+}
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Lcr/Lcr.hpp

@@ -0,0 +1,22 @@
+// cpp/core/Lrc.hpp
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "LrcMode.hpp"
+
+namespace margelo::nitro::ecr17 {
+
+class Lrc {
+   public:
+    static constexpr uint8_t BASE = 0x7F;
+
+    static uint8_t compute(const std::vector<uint8_t>& payload, LrcMode mode);
+
+    static uint8_t compute(const std::string& payload, LrcMode mode);
+};
+
+}  // namespace margelo::nitro::ecr17

package/cpp/PacketCodec/PacketCodec.cpp

@@ -0,0 +1,146 @@
+#include "PacketCodec.hpp"
+
+#include <algorithm>  // std::find
+#include <iterator>   // std::distance
+
+namespace margelo::nitro::ecr17 {
+
+PacketCodec::PacketCodec(LrcMode mode) : lrcMode_(mode) {}
+
+std::vector<uint8_t> PacketCodec::encodeApplication(const std::string& payload) {
+    std::vector<uint8_t> frame;
+
+    frame.push_back(STX);
+
+    frame.insert(frame.end(), payload.begin(), payload.end());
+
+    frame.push_back(ETX);
+
+    uint8_t lrc = Lrc::compute(payload, lrcMode_);
+
+    frame.push_back(lrc);
+
+    return frame;
+}
+
+std::vector<uint8_t> PacketCodec::encodeControl(uint8_t ctrl) {
+    std::vector<uint8_t> frame;
+
+    frame.push_back(ctrl);
+    frame.push_back(ETX);
+
+    uint8_t lrc = Lrc::compute(std::vector<uint8_t>{ctrl}, lrcMode_);
+
+    frame.push_back(lrc);
+
+    return frame;
+}
+
+DecodedPacket PacketCodec::decode(const std::vector<uint8_t>& data) {
+    if (data.empty()) {
+        return {
+            PacketType::UNKNOWN,
+            "",
+            false,
+        };
+    }
+
+    uint8_t first = data[0];
+
+    if (first == ACK) {
+        return {
+            PacketType::ACK,
+            "",
+            true,
+        };
+    }
+
+    if (first == NAK) {
+        return {
+            PacketType::NAK,
+            "",
+            true,
+        };
+    }
+
+    if (first == SOH) {
+        // Progress update packet: SOH + message + EOT (no LRC). We need at least
+        // SOH and the trailing EOT before stripping the first/last byte,
+        // otherwise the iterator range below would be invalid (last < first).
+        if (data.size() < 2) {
+            return {
+                PacketType::UNKNOWN,
+                "",
+                false,
+            };
+        }
+
+        // The spec mandates SOH + 20-char message + EOT. Reject any frame whose
+        // final byte is not EOT so that garbage or a truncated read is never
+        // silently accepted as a valid progress update.
+        if (data.back() != EOT) {
+            return {
+                PacketType::UNKNOWN,
+                "",
+                false,
+            };
+        }
+
+        std::string payload(data.begin() + 1, data.end() - 1);
+
+        return {
+            PacketType::PROGRESS,
+            payload,
+            true,
+        };
+    }
+
+    if (first == STX) {
+        auto etxIt = std::find(data.begin(), data.end(), ETX);
+
+        if (etxIt == data.end()) {
+            return {
+                PacketType::UNKNOWN,
+                "",
+                false,
+            };
+        }
+
+        size_t etxIndex = std::distance(data.begin(), etxIt);
+
+        // A well-formed application frame is exactly STX + payload + ETX + LRC,
+        // so the LRC must be the final byte. Reject both a truncated frame (no
+        // LRC after ETX) and a buffer with trailing bytes -- e.g. a coalesced
+        // socket read holding a second frame ("STX..ETX LRC STX..") or garbage
+        // after the LRC. Splitting a byte stream into individual frames is the
+        // transport layer's responsibility, and DecodedPacket cannot carry the
+        // unconsumed remainder.
+        if (etxIndex + 2 != data.size()) {
+            return {
+                PacketType::UNKNOWN,
+                "",
+                false,
+            };
+        }
+
+        std::string payload(data.begin() + 1, data.begin() + etxIndex);
+
+        uint8_t rxLrc = data[etxIndex + 1];
+
+        uint8_t calcLrc = Lrc::compute(payload, lrcMode_);
+
+        return {
+            PacketType::APPLICATION,
+            payload,
+            rxLrc == calcLrc,
+        };
+    }
+
+    return {
+        PacketType::UNKNOWN,
+        "",
+        false,
+    };
+}
+
+}  // namespace margelo::nitro::ecr17

package/cpp/PacketCodec/PacketCodec.hpp

@@ -0,0 +1,48 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "Lcr/Lcr.hpp"
+
+namespace margelo::nitro::ecr17 {
+
+enum class PacketType {
+    APPLICATION,
+    // SOH-framed procedure progress update (0x01 ... 0x04), see protocol spec.
+    PROGRESS,
+    ACK,
+    NAK,
+    UNKNOWN,
+};
+
+struct DecodedPacket {
+    PacketType type;
+    std::string payload;
+    bool validLrc;
+};
+
+class PacketCodec {
+   public:
+    static constexpr uint8_t STX = 0x02;
+    static constexpr uint8_t ETX = 0x03;
+    static constexpr uint8_t SOH = 0x01;
+    static constexpr uint8_t EOT = 0x04;
+    static constexpr uint8_t ACK = 0x06;
+    static constexpr uint8_t NAK = 0x15;
+
+    explicit PacketCodec(LrcMode mode);
+
+    std::vector<uint8_t> encodeApplication(const std::string& payload);
+
+    std::vector<uint8_t> encodeControl(uint8_t ctrl);
+
+    DecodedPacket decode(const std::vector<uint8_t>& data);
+
+   private:
+    LrcMode lrcMode_;
+};
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Session/Ecr17Session.cpp

@@ -0,0 +1,260 @@
+#include "Session/Ecr17Session.hpp"
+
+#include <algorithm>
+#include <chrono>
+#include <stdexcept>
+#include <thread>
+
+namespace margelo::nitro::ecr17 {
+
+using clock = std::chrono::steady_clock;
+
+Ecr17Session::Ecr17Session(Transport& transport, const SessionConfig& config)
+    : transport_(transport), config_(config), codec_(config.lrcMode) {
+    transport_.setDataCallback([this](const std::vector<uint8_t>& data) { onData(data); });
+    transport_.setDisconnectCallback([this]() { onDisconnect(); });
+}
+
+void Ecr17Session::onData(const std::vector<uint8_t>& data) {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        rxBuffer_.insert(rxBuffer_.end(), data.begin(), data.end());
+    }
+    cv_.notify_all();
+}
+
+void Ecr17Session::onDisconnect() {
+    {
+        std::lock_guard<std::mutex> lock(mutex_);
+        disconnected_ = true;
+    }
+    cv_.notify_all();
+}
+
+// Extracts one complete frame from the front of rxBuffer_, dropping leading junk
+// bytes to resynchronise. Returns nullopt if no complete frame is available yet.
+// Caller must hold mutex_.
+std::optional<std::vector<uint8_t>> Ecr17Session::extractFrameLocked() {
+    while (!rxBuffer_.empty()) {
+        const uint8_t first = rxBuffer_.front();
+
+        if (first == PacketCodec::ACK || first == PacketCodec::NAK) {
+            if (rxBuffer_.size() < 3) {
+                return std::nullopt;  // wait for ETX + LRC
+            }
+            std::vector<uint8_t> frame(rxBuffer_.begin(), rxBuffer_.begin() + 3);
+            rxBuffer_.erase(rxBuffer_.begin(), rxBuffer_.begin() + 3);
+            return frame;
+        }
+
+        if (first == PacketCodec::STX) {
+            auto etx = std::find(rxBuffer_.begin(), rxBuffer_.end(), PacketCodec::ETX);
+            if (etx == rxBuffer_.end() || etx + 1 == rxBuffer_.end()) {
+                return std::nullopt;  // wait for ETX and the trailing LRC
+            }
+            auto lastByte = etx + 1;  // LRC
+            std::vector<uint8_t> frame(rxBuffer_.begin(), lastByte + 1);
+            rxBuffer_.erase(rxBuffer_.begin(), lastByte + 1);
+            return frame;
+        }
+
+        if (first == PacketCodec::SOH) {
+            auto eot = std::find(rxBuffer_.begin(), rxBuffer_.end(), PacketCodec::EOT);
+            if (eot == rxBuffer_.end()) {
+                return std::nullopt;  // wait for EOT
+            }
+            std::vector<uint8_t> frame(rxBuffer_.begin(), eot + 1);
+            rxBuffer_.erase(rxBuffer_.begin(), eot + 1);
+            return frame;
+        }
+
+        // Unrecognised lead byte: drop it and resynchronise.
+        rxBuffer_.erase(rxBuffer_.begin());
+    }
+    return std::nullopt;
+}
+
+std::optional<DecodedPacket> Ecr17Session::waitForFrame(int timeoutMs) {
+    std::unique_lock<std::mutex> lock(mutex_);
+    const auto deadline = clock::now() + std::chrono::milliseconds(timeoutMs);
+    while (true) {
+        if (auto frame = extractFrameLocked()) {
+            return codec_.decode(*frame);
+        }
+        if (disconnected_) {
+            throw std::runtime_error("ECR17: transport disconnected during exchange");
+        }
+        if (cv_.wait_until(lock, deadline) == std::cv_status::timeout) {
+            if (auto frame = extractFrameLocked()) {
+                return codec_.decode(*frame);
+            }
+            return std::nullopt;
+        }
+    }
+}
+
+void Ecr17Session::sendControl(uint8_t control) {
+    transport_.send(codec_.encodeControl(control));
+}
+
+bool Ecr17Session::isReceipt(const std::string& payload) {
+    // Send-ticket message from the terminal uses message code 'S' at position 10.
+    return payload.size() >= 10 && payload[9] == 'S';
+}
+
+void Ecr17Session::resetForNewTransaction() {
+    std::lock_guard<std::mutex> lock(mutex_);
+    disconnected_ = false;
+    rxBuffer_.clear();
+    pendingResult_.reset();
+}
+
+void Ecr17Session::sendAckOnly(const std::string& requestPayload) {
+    resetForNewTransaction();
+    ackHandshake(requestPayload);
+}
+
+void Ecr17Session::ackHandshake(const std::string& requestPayload) {
+    const std::vector<uint8_t> requestFrame = codec_.encodeApplication(requestPayload);
+
+    transport_.send(requestFrame);
+    int attempts = 1;
+    auto deadline = clock::now() + std::chrono::milliseconds(config_.ackTimeoutMs);
+
+    while (true) {
+        const auto remaining =
+            std::chrono::duration_cast<std::chrono::milliseconds>(deadline - clock::now()).count();
+        if (remaining <= 0) {
+            if (attempts > config_.retryCount) {
+                throw std::runtime_error("ECR17: no ACK after " + std::to_string(attempts) +
+                                         " attempts");
+            }
+            std::this_thread::sleep_for(std::chrono::milliseconds(config_.retryDelayMs));
+            transport_.send(requestFrame);
+            ++attempts;
+            deadline = clock::now() + std::chrono::milliseconds(config_.ackTimeoutMs);
+            continue;
+        }
+
+        std::optional<DecodedPacket> pkt = waitForFrame(static_cast<int>(remaining));
+        if (!pkt) {
+            continue;
+        }
+        if (pkt->type == PacketType::ACK) {
+            return;
+        }
+        if (pkt->type == PacketType::NAK) {
+            if (attempts > config_.retryCount) {
+                throw std::runtime_error("ECR17: NAK after " + std::to_string(attempts) +
+                                         " attempts");
+            }
+            std::this_thread::sleep_for(std::chrono::milliseconds(config_.retryDelayMs));
+            transport_.send(requestFrame);
+            ++attempts;
+            deadline = clock::now() + std::chrono::milliseconds(config_.ackTimeoutMs);
+            continue;
+        }
+        if (pkt->type == PacketType::APPLICATION) {
+            // The terminal sent the application response without (or before) a
+            // physical ACK. The request was clearly received, so treat the
+            // handshake as satisfied and stash the frame for waitForResult() to
+            // validate/ACK — dropping it would lose a completed transaction.
+            pendingResult_ = pkt;
+            return;
+        }
+        // Ignore any progress frames that may precede the ACK.
+    }
+}
+
+DecodedPacket Ecr17Session::exchange(const std::string& requestPayload) {
+    resetForNewTransaction();     // start clean (reusable across reconnects)
+    ackHandshake(requestPayload);  // send + physical ACK handshake (with retransmission)
+    return waitForResult();
+}
+
+DecodedPacket Ecr17Session::exchangeWithAdditionalData(const std::string& requestPayload,
+                                                       const std::string& additionalPayload) {
+    resetForNewTransaction();
+    ackHandshake(requestPayload);     // main request -> ACK
+    ackHandshake(additionalPayload);  // 'U' additional-data message -> ACK
+    return waitForResult();
+}
+
+DecodedPacket Ecr17Session::waitForResult() {
+    auto deadline = clock::now() + std::chrono::milliseconds(config_.responseTimeoutMs);
+    while (true) {
+        std::optional<DecodedPacket> pkt;
+        if (pendingResult_) {
+            // A frame the ACK handshake received early — process it first.
+            pkt = std::move(pendingResult_);
+            pendingResult_.reset();
+        } else {
+            const auto remaining =
+                std::chrono::duration_cast<std::chrono::milliseconds>(deadline - clock::now())
+                    .count();
+            if (remaining <= 0) {
+                throw std::runtime_error("ECR17: no application response before timeout");
+            }
+            pkt = waitForFrame(static_cast<int>(remaining));
+            if (!pkt) {
+                continue;
+            }
+        }
+        switch (pkt->type) {
+            case PacketType::PROGRESS:
+                if (onProgress_) onProgress_(pkt->payload);
+                break;
+            case PacketType::APPLICATION:
+                if (!pkt->validLrc) {
+                    sendControl(PacketCodec::NAK);
+                    break;
+                }
+                sendControl(PacketCodec::ACK);
+                if (isReceipt(pkt->payload)) {
+                    if (onReceiptLine_) onReceiptLine_(pkt->payload);
+                    break;
+                }
+                drainReceipts();  // forward receipts that follow the result (if enabled)
+                return *pkt;
+            case PacketType::ACK:
+            case PacketType::NAK:
+                break;  // stray confirmation; ignore
+            case PacketType::UNKNOWN:
+                sendControl(PacketCodec::NAK);
+                break;
+        }
+    }
+}
+
+void Ecr17Session::drainReceipts() {
+    if (config_.receiptDrainMs <= 0) {
+        return;
+    }
+    // Keep forwarding 'S' receipt lines that arrive after the result until the
+    // terminal goes quiet for receiptDrainMs.
+    while (true) {
+        std::optional<DecodedPacket> pkt = waitForFrame(config_.receiptDrainMs);
+        if (!pkt) {
+            return;  // idle: no more receipts
+        }
+        switch (pkt->type) {
+            case PacketType::APPLICATION:
+                if (pkt->validLrc) {
+                    sendControl(PacketCodec::ACK);
+                    if (isReceipt(pkt->payload) && onReceiptLine_) {
+                        onReceiptLine_(pkt->payload);
+                    }
+                } else {
+                    sendControl(PacketCodec::NAK);  // request retransmit, like waitForResult
+                }
+                break;
+            case PacketType::PROGRESS:
+                if (onProgress_) onProgress_(pkt->payload);
+                break;
+            default:
+                break;
+        }
+    }
+}
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Session/Ecr17Session.hpp

@@ -0,0 +1,97 @@
+#pragma once
+
+#include <condition_variable>
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "Lcr/Lcr.hpp"  // brings LrcMode
+#include "PacketCodec/PacketCodec.hpp"
+#include "Transport/Transport.hpp"
+
+namespace margelo::nitro::ecr17 {
+
+struct SessionConfig {
+    LrcMode lrcMode = LrcMode::STD;
+    int ackTimeoutMs = 2000;       // wait for the physical ACK/NAK
+    int responseTimeoutMs = 60000; // wait for the application response
+    int retryCount = 3;            // retransmissions on NAK/timeout (spec: up to 3)
+    int retryDelayMs = 200;        // delay between retransmissions
+    int receiptDrainMs = 0;        // after the result, keep forwarding 'S' receipt
+                                   // lines until this many ms of silence (0 = off)
+};
+
+// Drives one ECR17 request/response exchange over a Transport: frames the
+// request, handles the physical ACK/NAK handshake with retransmission, waits for
+// the application response while forwarding progress (SOH) and receipt ('S')
+// messages, and ACK/NAKs incoming frames per their LRC validity.
+//
+// Pure C++ and transport-agnostic: unit-tested against FakeTransport. A single
+// exchange runs at a time (the protocol is one transaction per terminal).
+class Ecr17Session {
+   public:
+    Ecr17Session(Transport& transport, const SessionConfig& config);
+
+    void setOnProgress(std::function<void(const std::string&)> cb) { onProgress_ = std::move(cb); }
+    void setOnReceiptLine(std::function<void(const std::string&)> cb) {
+        onReceiptLine_ = std::move(cb);
+    }
+
+    // Sends `requestPayload` (the application message, without STX/ETX) and
+    // returns the decoded application result. Throws std::runtime_error on
+    // retransmission exhaustion, ACK/response timeout, or transport disconnect.
+    DecodedPacket exchange(const std::string& requestPayload);
+
+    // Like exchange(), but sends an extra additional-data message (command 'U',
+    // tokenization) after the main request is ACKed, before the result: the
+    // documented flow is request(flag=1) -> ACK -> 'U' -> ACK -> result.
+    DecodedPacket exchangeWithAdditionalData(const std::string& requestPayload,
+                                             const std::string& additionalPayload);
+
+    // For commands whose only reply is the physical ACK (e.g. enable/disable ECR
+    // printing 'E'). Performs the ACK handshake with retransmission and returns
+    // once ACK is received; does NOT wait for an application response. Throws on
+    // retransmission exhaustion / timeout / disconnect.
+    void sendAckOnly(const std::string& requestPayload);
+
+   private:
+    void onData(const std::vector<uint8_t>& data);
+    void onDisconnect();
+    // Clears stale RX bytes and the disconnected flag so the session is reusable
+    // across reconnects (a new transaction starts from a clean state).
+    void resetForNewTransaction();
+    // Sends a request and completes the physical ACK handshake (with
+    // retransmission). Does NOT reset state — callers reset once per transaction.
+    void ackHandshake(const std::string& requestPayload);
+    // Waits for the application result after the ACK handshake, forwarding
+    // progress (SOH) and receipt ('S') frames, NAKing invalid-LRC frames.
+    DecodedPacket waitForResult();
+    void drainReceipts();
+    std::optional<std::vector<uint8_t>> extractFrameLocked();
+    std::optional<DecodedPacket> waitForFrame(int timeoutMs);
+    void sendControl(uint8_t control);
+    static bool isReceipt(const std::string& payload);
+
+    Transport& transport_;
+    SessionConfig config_;
+    PacketCodec codec_;
+
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    std::vector<uint8_t> rxBuffer_;
+    bool disconnected_ = false;
+
+    // Holds an application response that arrived during the ACK handshake (some
+    // terminals send the result before/without a physical ACK). Consumed by
+    // waitForResult() so the completed transaction's result is never dropped.
+    // Touched only by the worker thread, never the data-callback thread.
+    std::optional<DecodedPacket> pendingResult_{};
+
+    std::function<void(const std::string&)> onProgress_{};
+    std::function<void(const std::string&)> onReceiptLine_{};
+};
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Session/RetryPolicy.hpp

@@ -0,0 +1,23 @@
+#pragma once
+
+namespace margelo::nitro::ecr17 {
+
+// Decides whether a command may be safely RE-SENT after an auto-reconnect.
+//
+// ⚠️ MONEY-CRITICAL INVARIANT: a financial command (safeToRetry == false) must
+// NEVER be retried. If the connection drops after the terminal has processed the
+// payment but before the response arrives, a blind re-send would charge the
+// cardholder twice. Such cases are recovered by querying the terminal's last
+// result (command 'G' / sendLastResult), NOT by retransmitting the request.
+//
+// Only read-only / idempotent commands (status, totals, sendLastResult,
+// enable-printing) pass safeToRetry == true.
+//
+// Reconnecting the socket is a separate, always-safe action; this function only
+// governs whether the *request* is replayed.
+inline bool shouldRetryAfterReconnect(bool autoReconnect, bool transportDropped,
+                                      bool safeToRetry) {
+    return autoReconnect && transportDropped && safeToRetry;
+}
+
+}  // namespace margelo::nitro::ecr17