feat: ECR17 transport, orchestration, response parsing & full command set

[lopadova]

Overview

Implements the full ECR17 stack on top of the framing/LRC core: TCP/LAN transport,
ACK/NAK + retransmit orchestration, response parsing, the complete command set,
an async Promise API with events, and payment-safety throughout. Base: main.

CI: cpp-tests 82/82 ✅ · ts-checks ✅ · android-build ✅ (manual dispatch).
iOS Swift transport is written best-effort (no macOS CI runner — see roadmap).

What's included

• Builders (Ecr17Protocol): all commands — P X p i c H U C T G E R K s S —
  fixed-width, validated, byte-exact vs spec.
• Parsers (Ecr17Response): E/V/s/T/C/e/K incl. DCC; defensive (no UB).
• Orchestration (Ecr17Session): physical ACK/NAK handshake, retransmit-up-to-3,
  timeouts, progress (SOH) + receipt (S) forwarding, stream framer; tested
  against an in-memory FakeTransport.
• Async client (HybridEcr17Client): connect/status/pay/payExtended/
  reverse/preAuth/incrementalAuth/preAuthClosure/verifyCard/closeSession/
  totals/sendLastResult/enableEcrPrinting/reprint/vas + progress/receipt/
  connection events. Auto-connect; tokenization (U) flow; configurable receipt drain.
• Native transport: Kotlin TCP (HybridEcr17Transport.kt, CI-built) + Swift
  Network.framework (best-effort). Nitro generates the C++↔Kotlin JNI bridge.

💰 Payment safety (money-critical)

• No double charge: on a drop, autoReconnect restores the socket, but a
  financial command is never blindly re-sent — payments/reversals/pre-auths
  reconnect and surface the error; recover the outcome via sendLastResult()
  (spec command G). Only read-only/idempotent ops are retried. The decision is
  isolated in RetryPolicy.hpp and unit-tested (test_retry_policy.cpp).
• LRC validated on every frame (NAK on failure); fixed-width validation on send.

Tests

82 C++ tests (LRC, codec edge cases, every builder layout, every parser, session
flows incl. tokenization/receipt-drain/NAK-retransmit/timeout/disconnect, and the
retry-safety invariants) + an opt-in real-terminal integration test
(ECR17_TERMINAL_HOST=… ctest -R Integration).

Process: each change went through local tests → local Copilot review → CI green.
Learnings in docs/LESSON.md, status in PROGRESS.md, workflow distilled into
root AGENTS.md.

Remaining (roadmap)

• iOS native transport verification (needs a macOS CI runner).
• Auto-reconnect-on-drop retries only safe commands by design (financial recover via G).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 00100c408d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Serialize command exchanges on the shared session

Every public command runs inside Promise::async, so two JS calls can enter runTransaction at the same time and share the same session_/native callbacks. Because Ecr17Session::exchange() resets the receive buffer and then both exchanges wait on the same callback stream, concurrent calls such as pay() plus status() can clear or consume each other's frames, ACK the wrong response, or return a mismatched result. Add a transaction-level mutex around all runTransaction/runAckOnly exchanges so only one ECR17 command is in flight per client.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Treat closed Android sockets as disconnected

When the terminal drops the TCP connection, the reader loop exits and sets running = false, but the socket remains non-null and not explicitly closed. On Android/Java, Socket.isConnected only means the socket has connected before, so after an unexpected peer close this can still return true; runTransaction then computes dropped=false, skips auto-reconnect/retry, and later ensureConnected() also refuses to open a fresh socket. Include running or close/null the socket in the reader's finally path so unexpected EOF is observable as disconnected.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Avoid reporting pre-auth amount digits as card type

For successful pre-auth responses, the parser reads preAuthorizedAmount from positions 41-48 and then unconditionally reads cardType from position 48, so any approved amount ending in 1, 2, or 3 is exposed to JS as debit/credit/other even though that byte is just the last amount digit. This affects successful preAuth() results with those amount endings; leave cardType empty for the OK layout or parse it from a non-overlapping KO/common offset.

Useful? React with 👍 / 👎.

[Copilot]

Pull request overview

Implements the full ECR17 stack on top of the existing framing/LRC core: complete request builders, response parsers, an ACK/NAK + retransmit session orchestrator with timeouts, a native TCP transport (Kotlin + best-effort Swift), and an async Promise/event-based HybridEcr17Client that ties them together. Payment-safety is enforced via an isolated RetryPolicy that prevents financial commands from being blindly replayed on auto-reconnect, with recovery via sendLastResult ('G'). Adds 82 C++ unit tests, an opt-in real-terminal integration test, CI workflows (ts-checks, android-build), self-contained CI tsconfig, and substantial README/agent-context documentation.

Changes:

• Complete ECR17 command builders, response parsers, session orchestration, and native transport (Kotlin/Swift) wired through a Nitro async client API with progress/receipt/connection events.
• Money-safety policy (RetryPolicy.hpp) keeping financial commands from being replayed after reconnect, with extensive C++ test coverage including a FakeTransport and opt-in real-terminal test.
• New CI (ts-checks, android-build) and refreshed README / AGENTS.md / CLAUDE.md / LESSON.md / PROGRESS.md documentation.

Reviewed changes

Copilot reviewed 38 out of 39 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
PROGRESS.md	New session/phase progress log (contains some duplicated stale checklist entries).
package/tsconfig.ci.json	Self-contained typecheck config avoiding the private @padosoft/config.
package/src/types/client.ts	New request/result/event TypeScript types for the full command set.
package/src/specs/transport.nitro.ts	Nitro spec for the native Ecr17Transport (Swift/Kotlin).
package/src/specs/client.nitro.ts	Expanded client spec with async commands, events, and receiptDrainMs.
package/src/index.ts	Re-exports the new transport spec.
package/README.md	Major rewrite documenting the full feature set, async API, events, and AI-agent context.
package/nitro.json	Registers the new Ecr17Transport HybridObject.
package/ios/HybridEcr17Transport.swift	iOS Swift TCP transport via Network.framework (best-effort, no iOS CI).
package/cpp/Transport/NativeTransportAdapter.{hpp,cpp}	Adapts the Nitro transport spec to the C++ Transport interface.
package/cpp/Transport/FakeTransport.hpp	Deterministic in-memory transport for session tests.
package/cpp/Session/RetryPolicy.hpp	Money-critical decision: never replay financial commands after reconnect.
package/cpp/Session/Ecr17Session.{hpp,cpp}	ACK/NAK + retransmit orchestrator, progress/receipt forwarding, receipt drain.
package/cpp/PacketCodec/PacketCodec.cpp	Rejects SOH frames not terminated with EOT.
package/cpp/Ecr17Response/Ecr17Response.{hpp,cpp}	Defensive parsers for E/V/s/T/C/e/K responses (incl. DCC).
package/cpp/Ecr17Protocol/Ecr17Protocol.{hpp,cpp}	Complete command builder set with fixed-width validation.
package/cpp/Ecr17Client/Ecr17Client.{hpp,cpp}	Async client wiring transport + session + parsers, tokenization flow, retry policy.
package/cpp/tests/*	New tests: protocol commands, responses, session, retry policy, integration, packet codec regression.
package/cpp/tests/CMakeLists.txt	Builds new test files and links pthread.
package/cpp/tests/PosixTcpTransport.hpp	Test-only POSIX TCP transport for the opt-in integration test.
package/android/src/main/java/com/margelo/nitro/ecr17/HybridEcr17Transport.kt	Kotlin TCP transport with intentional-disconnect handling.
package/android/CMakeLists.txt	Adds new C++ sources to the Android build.
docs/LESSON.md, CLAUDE.md, AGENTS.md	Agent-facing project guidance / accumulated lessons / non-negotiables.
.gitignore	Ignores the privately-kept full Nexi spec markdown.
.github/workflows/{ts-checks.yml,android-build.yml,cpp-tests.yml}	New CI for TS+nitrogen and Android build; checkout bumped to v5.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.