@padosoft/react-native-ecr17 0.0.0

package/cpp/Transport/FakeTransport.hpp

@@ -0,0 +1,95 @@
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <vector>
+
+#include "Transport/Transport.hpp"
+
+namespace margelo::nitro::ecr17 {
+
+// In-memory Transport for unit tests. Deterministic and synchronous:
+//
+//  - `enqueueResponse(bytes)` queues a scripted terminal reply.
+//  - Every time the session sends an APPLICATION request (a frame starting with
+//    STX, i.e. an initial send or a retransmit) the next queued response is
+//    delivered synchronously via the data callback. Control sends (ACK/NAK,
+//    which start with 0x06/0x15) are just recorded and never trigger a reply.
+//
+// This lets a test script "ACK + result", "NAK then (on retransmit) ACK+result",
+// progress/receipt streams, or no reply at all (to exercise timeouts), without
+// any real sockets or threads.
+class FakeTransport : public Transport {
+   public:
+    static constexpr uint8_t STX = 0x02;
+
+    void connect() override { connected_ = true; }
+    void disconnect() override { connected_ = false; }
+    bool isConnected() const override { return connected_; }
+
+    void send(const std::vector<uint8_t>& bytes) override {
+        sent_.push_back(bytes);
+        const bool isApplicationRequest = !bytes.empty() && bytes.front() == STX;
+        if (isApplicationRequest && disconnectOnRequest_) {
+            triggerDisconnect();
+            return;
+        }
+        if (isApplicationRequest && !responses_.empty()) {
+            std::vector<uint8_t> next = std::move(responses_.front());
+            responses_.erase(responses_.begin());
+            if (dataCallback_) {
+                dataCallback_(next);
+            }
+        }
+    }
+
+    void setDataCallback(DataCallback cb) override { dataCallback_ = std::move(cb); }
+    void setDisconnectCallback(DisconnectCallback cb) override { disconnectCallback_ = std::move(cb); }
+
+    // --- Test helpers ---
+    void enqueueResponse(std::vector<uint8_t> bytes) { responses_.push_back(std::move(bytes)); }
+
+    // Make the next application-request send drop the connection instead of replying.
+    void disconnectOnNextRequest() { disconnectOnRequest_ = true; }
+
+    // Simulate a successful reconnect: clear the drop flag and mark connected.
+    void rearm() {
+        disconnectOnRequest_ = false;
+        connected_ = true;
+    }
+
+    // Deliver bytes immediately as if received from the terminal.
+    void pushIncoming(const std::vector<uint8_t>& bytes) {
+        if (dataCallback_) {
+            dataCallback_(bytes);
+        }
+    }
+
+    void triggerDisconnect() {
+        connected_ = false;
+        if (disconnectCallback_) {
+            disconnectCallback_();
+        }
+    }
+
+    const std::vector<std::vector<uint8_t>>& sentFrames() const { return sent_; }
+    size_t applicationRequestCount() const {
+        size_t count = 0;
+        for (const auto& f : sent_) {
+            if (!f.empty() && f.front() == STX) {
+                ++count;
+            }
+        }
+        return count;
+    }
+
+   private:
+    bool connected_ = false;
+    DataCallback dataCallback_{};
+    DisconnectCallback disconnectCallback_{};
+    std::vector<std::vector<uint8_t>> sent_{};
+    std::vector<std::vector<uint8_t>> responses_{};
+    bool disconnectOnRequest_ = false;
+};
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Transport/NativeTransportAdapter.cpp

@@ -0,0 +1,42 @@
+#include "Transport/NativeTransportAdapter.hpp"
+
+#include <NitroModules/ArrayBuffer.hpp>
+
+#include <utility>
+
+namespace margelo::nitro::ecr17 {
+
+NativeTransportAdapter::NativeTransportAdapter(std::shared_ptr<HybridEcr17TransportSpec> transport)
+    : transport_(std::move(transport)) {}
+
+void NativeTransportAdapter::connect() {
+    // Connection is initiated by HybridEcr17Client via the spec's async connect();
+    // nothing to do here.
+}
+
+void NativeTransportAdapter::disconnect() { transport_->disconnect(); }
+
+bool NativeTransportAdapter::isConnected() const { return transport_->isConnected(); }
+
+void NativeTransportAdapter::send(const std::vector<uint8_t>& bytes) {
+    transport_->send(ArrayBuffer::copy(bytes));
+}
+
+void NativeTransportAdapter::setDataCallback(DataCallback cb) {
+    transport_->setOnData([cb = std::move(cb)](const std::shared_ptr<ArrayBuffer>& buffer) {
+        if (!cb || buffer == nullptr) {
+            return;
+        }
+        const uint8_t* data = buffer->data();
+        if (data == nullptr) {
+            return;
+        }
+        cb(std::vector<uint8_t>(data, data + buffer->size()));
+    });
+}
+
+void NativeTransportAdapter::setDisconnectCallback(DisconnectCallback cb) {
+    transport_->setOnDisconnect(std::move(cb));
+}
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Transport/NativeTransportAdapter.hpp

@@ -0,0 +1,32 @@
+#pragma once
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "HybridEcr17TransportSpec.hpp"  // generated Nitro spec (Swift/Kotlin impl)
+#include "Transport/Transport.hpp"
+
+namespace margelo::nitro::ecr17 {
+
+// Adapts the native Nitro transport (Ecr17Transport HybridObject, implemented in
+// Swift/Kotlin) to the C++ Transport interface used by Ecr17Session. Converts
+// between std::vector<uint8_t> and Nitro's ArrayBuffer. Connection lifecycle is
+// driven by HybridEcr17Client directly via the spec (async Promise); the session
+// only uses send + the data/disconnect callbacks.
+class NativeTransportAdapter : public Transport {
+   public:
+    explicit NativeTransportAdapter(std::shared_ptr<HybridEcr17TransportSpec> transport);
+
+    void connect() override;      // no-op: client drives connect() via the spec (async)
+    void disconnect() override;
+    bool isConnected() const override;
+    void send(const std::vector<uint8_t>& bytes) override;
+    void setDataCallback(DataCallback cb) override;
+    void setDisconnectCallback(DisconnectCallback cb) override;
+
+   private:
+    std::shared_ptr<HybridEcr17TransportSpec> transport_;
+};
+
+}  // namespace margelo::nitro::ecr17

package/cpp/Transport/Transport.hpp

@@ -0,0 +1,31 @@
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <string>
+#include <vector>
+
+namespace margelo::nitro::ecr17 {
+
+using DataCallback = std::function<void(const std::vector<uint8_t>&)>;
+
+using DisconnectCallback = std::function<void()>;
+
+class Transport {
+   public:
+    virtual ~Transport() = default;
+
+    virtual void connect() = 0;
+
+    virtual void disconnect() = 0;
+
+    virtual bool isConnected() const = 0;
+
+    virtual void send(const std::vector<uint8_t>& bytes) = 0;
+
+    virtual void setDataCallback(DataCallback cb) = 0;
+
+    virtual void setDisconnectCallback(DisconnectCallback cb) = 0;
+};
+
+}  // namespace margelo::nitro::ecr17

package/cpp/tests/CMakeLists.txt

@@ -0,0 +1,55 @@
+cmake_minimum_required(VERSION 3.16)
+project(ecr17_cpp_tests CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# GoogleTest via FetchContent (CI has network access).
+include(FetchContent)
+FetchContent_Declare(
+  googletest
+  URL https://github.com/google/googletest/archive/refs/tags/v1.15.2.tar.gz
+)
+# Keep CRT linkage consistent on Windows runners.
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+FetchContent_MakeAvailable(googletest)
+
+enable_testing()
+
+# Production C++ sources under test (../ is package/cpp).
+set(ECR17_CPP_DIR ${CMAKE_CURRENT_SOURCE_DIR}/..)
+
+add_executable(ecr17_cpp_tests
+  test_lrc.cpp
+  test_packet_codec.cpp
+  test_protocol.cpp
+  test_protocol_commands.cpp
+  test_response.cpp
+  test_session.cpp
+  test_retry_policy.cpp
+  test_integration_terminal.cpp
+  test_flows.cpp
+  ${ECR17_CPP_DIR}/Lcr/Lcr.cpp
+  ${ECR17_CPP_DIR}/PacketCodec/PacketCodec.cpp
+  ${ECR17_CPP_DIR}/Ecr17Protocol/Ecr17Protocol.cpp
+  ${ECR17_CPP_DIR}/Ecr17Response/Ecr17Response.cpp
+  ${ECR17_CPP_DIR}/Session/Ecr17Session.cpp
+)
+
+target_include_directories(ecr17_cpp_tests PRIVATE
+  ${ECR17_CPP_DIR}                  # resolves "Lcr/Lcr.hpp", "PacketCodec/..."
+  ${CMAKE_CURRENT_SOURCE_DIR}/stubs # test-only LrcMode.hpp (Nitrogen-generated in real builds)
+)
+
+if(MSVC)
+  target_compile_options(ecr17_cpp_tests PRIVATE /W4)
+else()
+  target_compile_options(ecr17_cpp_tests PRIVATE -Wall -Wextra)
+endif()
+
+find_package(Threads REQUIRED)
+target_link_libraries(ecr17_cpp_tests PRIVATE GTest::gtest_main Threads::Threads)
+
+include(GoogleTest)
+gtest_discover_tests(ecr17_cpp_tests)

package/cpp/tests/PosixTcpTransport.hpp

@@ -0,0 +1,105 @@
+#pragma once
+
+// Test-only POSIX TCP transport, used by the opt-in real-terminal integration
+// test. Lets a developer run the C++ protocol core (builders + session + parsers)
+// against an actual terminal over the LAN, without the native (Kotlin/Swift)
+// transport. POSIX-only (Linux/macOS); excluded on Windows.
+#if !defined(_WIN32)
+
+#include <arpa/inet.h>
+#include <netdb.h>
+#include <sys/socket.h>
+#include <unistd.h>
+
+#include <atomic>
+#include <cstdint>
+#include <stdexcept>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "Transport/Transport.hpp"
+
+namespace margelo::nitro::ecr17 {
+
+class PosixTcpTransport : public Transport {
+   public:
+    PosixTcpTransport(std::string host, int port) : host_(std::move(host)), port_(port) {}
+    ~PosixTcpTransport() override { disconnect(); }
+
+    void connect() override {
+        addrinfo hints{};
+        hints.ai_family = AF_UNSPEC;
+        hints.ai_socktype = SOCK_STREAM;
+        addrinfo* res = nullptr;
+        if (getaddrinfo(host_.c_str(), std::to_string(port_).c_str(), &hints, &res) != 0) {
+            throw std::runtime_error("PosixTcpTransport: host resolution failed");
+        }
+        fd_ = ::socket(res->ai_family, res->ai_socktype, res->ai_protocol);
+        if (fd_ < 0) {
+            freeaddrinfo(res);
+            throw std::runtime_error("PosixTcpTransport: socket() failed");
+        }
+        if (::connect(fd_, res->ai_addr, res->ai_addrlen) != 0) {
+            freeaddrinfo(res);
+            ::close(fd_);
+            fd_ = -1;
+            throw std::runtime_error("PosixTcpTransport: connect() failed");
+        }
+        freeaddrinfo(res);
+        running_ = true;
+        reader_ = std::thread([this]() { readLoop(); });
+    }
+
+    void disconnect() override {
+        running_ = false;
+        if (fd_ >= 0) {
+            ::shutdown(fd_, SHUT_RDWR);
+            ::close(fd_);
+            fd_ = -1;
+        }
+        if (reader_.joinable()) {
+            reader_.join();
+        }
+    }
+
+    bool isConnected() const override { return fd_ >= 0; }
+
+    void send(const std::vector<uint8_t>& bytes) override {
+        if (fd_ >= 0) {
+            ::send(fd_, bytes.data(), bytes.size(), 0);
+        }
+    }
+
+    void setDataCallback(DataCallback cb) override { onData_ = std::move(cb); }
+    void setDisconnectCallback(DisconnectCallback cb) override { onDisconnect_ = std::move(cb); }
+
+   private:
+    void readLoop() {
+        uint8_t buffer[4096];
+        while (running_) {
+            ssize_t n = ::recv(fd_, buffer, sizeof(buffer), 0);
+            if (n <= 0) {
+                break;
+            }
+            if (onData_) {
+                onData_(std::vector<uint8_t>(buffer, buffer + n));
+            }
+        }
+        if (onDisconnect_) {
+            onDisconnect_();
+        }
+    }
+
+    std::string host_;
+    int port_;
+    int fd_ = -1;
+    std::atomic<bool> running_{false};
+    std::thread reader_;
+    DataCallback onData_{};
+    DisconnectCallback onDisconnect_{};
+};
+
+}  // namespace margelo::nitro::ecr17
+
+#endif  // !_WIN32

package/cpp/tests/stubs/LrcMode.hpp

@@ -0,0 +1,25 @@
+#pragma once
+
+// TEST-ONLY STUB.
+//
+// In a real build this header is generated by Nitrogen from the TypeScript
+// union `type LrcMode = "stx" | "std" | "noext" | "stx_noext"` (see
+// package/src/types/client.ts). The unit tests compile the pure-logic C++
+// units (Lrc, PacketCodec, Ecr17Protocol) in isolation, without running
+// Nitrogen, so we provide a minimal enum that mirrors the generated one.
+//
+// The member names MUST match what the production code references
+// (Lrc.cpp uses LrcMode::STX, LrcMode::STX_NOEXT, LrcMode::NOEXT). If Nitrogen
+// turns out to emit different casing, that is a real bug to reconcile when the
+// codegen is run — this stub documents the contract the code assumes today.
+
+namespace margelo::nitro::ecr17 {
+
+enum class LrcMode {
+    STX,
+    STD,
+    NOEXT,
+    STX_NOEXT,
+};
+
+}  // namespace margelo::nitro::ecr17

package/cpp/tests/test_flows.cpp

@@ -0,0 +1,148 @@
+// End-to-end protocol *flow* tests, modelled on the documented Nexi ECR17
+// sequences (basic payment, reversal/"annullamento", re-payment, status,
+// NAK retransmission).
+//
+// These exercise the layers that exist today: request building
+// (Ecr17Protocol) + physical framing (PacketCodec). Response *field* parsing
+// is not implemented yet, so terminal responses are synthesized as spec-shaped
+// payloads and asserted at the framing/classification level (packet type, LRC
+// validity, message code position), not by parsed fields.
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "Ecr17Protocol/Ecr17Protocol.hpp"
+#include "PacketCodec/PacketCodec.hpp"
+
+using namespace margelo::nitro::ecr17;
+
+namespace {
+
+constexpr uint8_t kStx = 0x02;
+constexpr uint8_t kEtx = 0x03;
+constexpr uint8_t kSoh = 0x01;
+constexpr uint8_t kEot = 0x04;
+constexpr uint8_t kAck = 0x06;
+constexpr uint8_t kNak = 0x15;
+
+const std::string kTerminal = "12345678";
+const std::string kCashReg = "00000001";
+
+// Terminal-side framing of a progress-update packet: SOH + 20-char message + EOT.
+std::vector<uint8_t> progressFrame(const std::string& msg20) {
+    std::vector<uint8_t> f{kSoh};
+    f.insert(f.end(), msg20.begin(), msg20.end());
+    f.push_back(kEot);
+    return f;
+}
+
+// Terminal-side framing of a spec-shaped result message ('E', result "00" = OK).
+std::vector<uint8_t> okResultFrame(PacketCodec& codec) {
+    std::string e = kTerminal + "0" + "E" + "00" + std::string(60, '0');
+    return codec.encodeApplication(e);
+}
+
+}  // namespace
+
+// Documented "Basic Payment Flow": request -> ACK -> progress -> result -> ACK.
+TEST(Flow, BasicPayment) {
+    PacketCodec codec(LrcMode::STD);
+
+    // 1. ECR -> POS: payment request on the wire (STX .. ETX .. LRC).
+    std::string req = Ecr17Protocol::buildPaymentMessage(kTerminal, kCashReg, 650);
+    auto reqFrame = codec.encodeApplication(req);
+    EXPECT_EQ(reqFrame.front(), kStx);
+    EXPECT_EQ(reqFrame[reqFrame.size() - 2], kEtx);
+
+    // POS validates and recovers the exact request payload.
+    DecodedPacket atPos = codec.decode(reqFrame);
+    EXPECT_EQ(atPos.type, PacketType::APPLICATION);
+    EXPECT_TRUE(atPos.validLrc);
+    EXPECT_EQ(atPos.payload, req);
+    EXPECT_EQ(atPos.payload[9], 'P');
+
+    // 2. POS -> ECR: physical ACK.
+    EXPECT_EQ(codec.decode(codec.encodeControl(kAck)).type, PacketType::ACK);
+
+    // 3. POS -> ECR: progress update while contacting the host (no LRC).
+    DecodedPacket prog = codec.decode(progressFrame("ATTENDERE PREGO     "));
+    EXPECT_EQ(prog.type, PacketType::PROGRESS);
+    EXPECT_EQ(prog.payload, "ATTENDERE PREGO     ");
+
+    // 4. POS -> ECR: positive result.
+    DecodedPacket result = codec.decode(okResultFrame(codec));
+    EXPECT_EQ(result.type, PacketType::APPLICATION);
+    EXPECT_TRUE(result.validLrc);
+    EXPECT_EQ(result.payload[9], 'E');
+    EXPECT_EQ(result.payload.substr(10, 2), "00");
+
+    // 5. ECR -> POS: ACK confirming receipt of the result.
+    EXPECT_EQ(codec.decode(codec.encodeControl(kAck)).type, PacketType::ACK);
+}
+
+// Documented NAK handling: a NAK triggers retransmission of the same message
+// (up to 3 times). Framing is deterministic, so the retransmitted bytes match.
+TEST(Flow, NakTriggersIdenticalRetransmit) {
+    PacketCodec codec(LrcMode::STD);
+    std::string req = Ecr17Protocol::buildPaymentMessage(kTerminal, kCashReg, 1999);
+    auto first = codec.encodeApplication(req);
+
+    EXPECT_EQ(codec.decode(codec.encodeControl(kNak)).type, PacketType::NAK);
+
+    auto retransmit = codec.encodeApplication(req);
+    EXPECT_EQ(first, retransmit);
+}
+
+// Documented "Reversal Last Transaction" (annullamento), command 'S'.
+TEST(Flow, ReversalAnnullamento) {
+    PacketCodec codec(LrcMode::STD);
+
+    std::string req = Ecr17Protocol::buildReversalMessage(kTerminal, kCashReg, "000123");
+    ASSERT_EQ(req.size(), 26u);
+    EXPECT_EQ(req[9], 'S');
+    EXPECT_EQ(req.substr(18, 6), "000123");
+
+    DecodedPacket atPos = codec.decode(codec.encodeApplication(req));
+    EXPECT_EQ(atPos.type, PacketType::APPLICATION);
+    EXPECT_TRUE(atPos.validLrc);
+    EXPECT_EQ(atPos.payload, req);
+
+    EXPECT_EQ(codec.decode(codec.encodeControl(kAck)).type, PacketType::ACK);
+    DecodedPacket result = codec.decode(okResultFrame(codec));
+    EXPECT_TRUE(result.validLrc);
+    EXPECT_EQ(result.payload[9], 'E');
+}
+
+// Pay -> annullamento -> ripaga (re-payment with the corrected amount).
+TEST(Flow, PayReverseRepay) {
+    PacketCodec codec(LrcMode::STD);
+
+    auto pay1 = codec.encodeApplication(Ecr17Protocol::buildPaymentMessage(kTerminal, kCashReg, 650));
+    auto rev = codec.encodeApplication(Ecr17Protocol::buildReversalMessage(kTerminal, kCashReg));
+    auto pay2 = codec.encodeApplication(Ecr17Protocol::buildPaymentMessage(kTerminal, kCashReg, 720));
+
+    for (const auto* frame : {&pay1, &rev, &pay2}) {
+        DecodedPacket d = codec.decode(*frame);
+        EXPECT_EQ(d.type, PacketType::APPLICATION);
+        EXPECT_TRUE(d.validLrc);
+    }
+
+    EXPECT_EQ(codec.decode(pay1).payload.substr(23, 8), "00000650");
+    EXPECT_EQ(codec.decode(pay2).payload.substr(23, 8), "00000720");
+    EXPECT_NE(pay1, pay2);  // the corrected re-payment differs on the wire
+}
+
+// Terminal status request/round-trip ('s').
+TEST(Flow, StatusRequest) {
+    PacketCodec codec(LrcMode::STD);
+    std::string req = Ecr17Protocol::buildStatusMessage(kTerminal);
+    EXPECT_EQ(req, "123456780s");
+
+    DecodedPacket atPos = codec.decode(codec.encodeApplication(req));
+    EXPECT_EQ(atPos.type, PacketType::APPLICATION);
+    EXPECT_TRUE(atPos.validLrc);
+    EXPECT_EQ(atPos.payload, req);
+}

package/cpp/tests/test_integration_terminal.cpp

@@ -0,0 +1,72 @@
+// OPT-IN real-terminal integration test.
+//
+// Skipped unless ECR17_TERMINAL_HOST is set, so it never affects CI. To run it
+// against a real Nexi terminal on your LAN:
+//
+//   ECR17_TERMINAL_HOST=192.168.1.50 \
+//   ECR17_TERMINAL_PORT=10000 \
+//   ECR17_TERMINAL_ID=00000000 \
+//   ECR17_LRC_MODE=std \
+//   ctest --test-dir build --output-on-failure -R Integration
+//
+// It connects over real TCP, sends a Terminal Status ('s') request through the
+// full C++ core (builder -> session/ACK-NAK -> parser) and prints the result.
+
+#if !defined(_WIN32)
+
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <iostream>
+#include <string>
+
+#include "Ecr17Protocol/Ecr17Protocol.hpp"
+#include "Ecr17Response/Ecr17Response.hpp"
+#include "PosixTcpTransport.hpp"
+#include "Session/Ecr17Session.hpp"
+
+using namespace margelo::nitro::ecr17;
+
+namespace {
+LrcMode lrcModeFromEnv() {
+    const char* m = std::getenv("ECR17_LRC_MODE");
+    const std::string mode = m ? m : "std";
+    if (mode == "stx") return LrcMode::STX;
+    if (mode == "noext") return LrcMode::NOEXT;
+    if (mode == "stx_noext") return LrcMode::STX_NOEXT;
+    return LrcMode::STD;
+}
+}  // namespace
+
+TEST(Integration, RealTerminalStatus) {
+    const char* host = std::getenv("ECR17_TERMINAL_HOST");
+    if (host == nullptr) {
+        GTEST_SKIP() << "set ECR17_TERMINAL_HOST to run against a real terminal";
+    }
+    const char* portEnv = std::getenv("ECR17_TERMINAL_PORT");
+    const char* idEnv = std::getenv("ECR17_TERMINAL_ID");
+    const int port = portEnv ? std::atoi(portEnv) : 10000;
+    const std::string terminalId = idEnv ? idEnv : "00000000";
+
+    PosixTcpTransport transport(host, port);
+    transport.connect();
+
+    SessionConfig cfg;
+    cfg.lrcMode = lrcModeFromEnv();
+    cfg.ackTimeoutMs = 3000;
+    cfg.responseTimeoutMs = 15000;
+    Ecr17Session session(transport, cfg);
+
+    DecodedPacket pkt = session.exchange(Ecr17Protocol::buildStatusMessage(terminalId));
+    StatusResponse status = Ecr17Response::parseStatus(pkt.payload);
+
+    std::cout << "[ECR17] terminalId=" << status.terminalId << " status=" << status.status
+              << " dateTime=" << status.dateTimeRaw << " sw=" << status.softwareRelease << std::endl;
+
+    EXPECT_TRUE(pkt.validLrc);
+    EXPECT_FALSE(status.terminalId.empty());
+
+    transport.disconnect();
+}
+
+#endif  // !_WIN32

package/cpp/tests/test_lrc.cpp

@@ -0,0 +1,66 @@
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "Lcr/Lcr.hpp"
+
+using margelo::nitro::ecr17::Lrc;
+using margelo::nitro::ecr17::LrcMode;
+
+namespace {
+
+constexpr uint8_t kBase = 0x7F;
+constexpr uint8_t kStx = 0x02;
+constexpr uint8_t kEtx = 0x03;
+
+// Reference implementation kept intentionally independent from the production
+// code, so the tests assert against first principles rather than a copy.
+uint8_t reference(const std::vector<uint8_t>& payload, LrcMode mode) {
+    uint8_t lrc = kBase;
+    if (mode == LrcMode::STX || mode == LrcMode::STX_NOEXT) {
+        lrc ^= kStx;
+    }
+    for (uint8_t b : payload) {
+        lrc ^= b;
+    }
+    if (mode == LrcMode::STX || mode == LrcMode::NOEXT) {
+        lrc ^= kEtx;
+    }
+    return lrc;
+}
+
+}  // namespace
+
+TEST(Lrc, EmptyPayloadStdIsBase) {
+    EXPECT_EQ(Lrc::compute(std::vector<uint8_t>{}, LrcMode::STD), kBase);
+}
+
+TEST(Lrc, EmptyPayloadStxFoldsStxAndEtx) {
+    // 0x7F ^ 0x02 ^ 0x03 == 0x7E
+    EXPECT_EQ(Lrc::compute(std::vector<uint8_t>{}, LrcMode::STX), 0x7E);
+}
+
+TEST(Lrc, KnownVectorAllModes) {
+    const std::vector<uint8_t> payload{'A'};  // 0x41
+    EXPECT_EQ(Lrc::compute(payload, LrcMode::STD), 0x3E);
+    EXPECT_EQ(Lrc::compute(payload, LrcMode::STX), 0x3F);
+    EXPECT_EQ(Lrc::compute(payload, LrcMode::NOEXT), 0x3D);
+    EXPECT_EQ(Lrc::compute(payload, LrcMode::STX_NOEXT), 0x3C);
+}
+
+TEST(Lrc, MatchesReferenceForEveryMode) {
+    const std::vector<uint8_t> payload{0x00, 0x7F, 0x55, 0xAA, 'Z', 0x10};
+    for (LrcMode mode : {LrcMode::STX, LrcMode::STD, LrcMode::NOEXT, LrcMode::STX_NOEXT}) {
+        EXPECT_EQ(Lrc::compute(payload, mode), reference(payload, mode));
+    }
+}
+
+TEST(Lrc, StringAndVectorOverloadsAgree) {
+    const std::string payload = "12345678P0";
+    const std::vector<uint8_t> bytes(payload.begin(), payload.end());
+    for (LrcMode mode : {LrcMode::STX, LrcMode::STD, LrcMode::NOEXT, LrcMode::STX_NOEXT}) {
+        EXPECT_EQ(Lrc::compute(payload, mode), Lrc::compute(bytes, mode));
+    }
+}