feat: @padosoft/ecr17-node (Node.js API) and a production POSIX transport

[47PADO47]

Stacked on #26.

The layering is now one C++ core with thin API packages on top:

@padosoft/ecr17          C++ core: protocol, session, money-safe client, PosixTransport + WinsockTransport
  ├─ @padosoft/ecr17-node          Node.js API (this PR)
  ├─ @padosoft/react-native-ecr17  Nitro binding
  └─ (later) Swift, Kotlin/AAR, C API + .NET

@padosoft/ecr17-node has the same createEcr17Client, methods, requests, results and events as @padosoft/react-native-ecr17. It runs on the same C++ client through Node-API, so the money-safety logic still exists only once.

import { createEcr17Client } from "@padosoft/ecr17-node";
const client = createEcr17Client({ host: "192.168.1.50", terminalId: "12345678", cashRegisterId: "00000001" });
const result = await client.pay({ amountCents: 650 });

• PosixTransport (in the core, packages/ecr17/posix, macOS/Linux) is a port of WinsockTransport: write-free MSG_PEEK pre-send probe, one drop signal, and no SIGPIPE. It has 14 loopback tests, run by cpp-tests on Linux. The real-terminal test now uses it, and the test-only PosixTcpTransport is removed.
• Addon (packages/ecr17-node/node/addon.cpp, Node-API 8, cmake-js): requests go in, the core's raw structs come out, and src/mappers.ts mirrors HybridEcr17Client.cpp.
  • Each client owns one worker thread, so the event loop and libuv's pool are never blocked.
  • Results and events share one ordered queue.
  • An idle client doesn't keep the process alive.
  • It finds the core through -DECR17_DIR, Node resolution, or the monorepo sibling.
• TypeScript (src/): built with tsdown through @padosoft/config (ESM + CJS). The addon is loaded from build/Release/ or prebuilds/<platform>-<arch>/, or from ECR17_NODE_ADDON if set.
• Tests: 17 Node tests drive TS → addon → core → TCP against a scripted fake terminal. The money-safety test checks that a payment interrupted by a drop goes out exactly once and that sendLastResult recovers it. It was mutation-checked.
• CI: the new node.yml builds and tests the addon on linux-x64, linux-arm64, darwin-arm64 and win32-x64. It also typechecks with a self-contained tsconfig.ci.json, because CI's token gets 401 on the private @padosoft/config, and builds with tsdown. The release workflow calls it and ships the prebuilds.

Bugs found and fixed while testing:

• Event ordering: a payment's promise could resolve before its progress event.
• Exit crash: SIGABRT at process exit, because Node finalizes thread-safe functions before object finalizers.
• Listener errors: they were swallowed silently.
• Test hang: a missing addon hung the test suite.

Verified locally on macOS:

• 114 C++ tests.
• 17 Node tests, including a build through the monorepo-sibling fallback with no workspace install.
• Four teardown scenarios, all exit 0.

CI was green on all four platforms on the previous push.

Not done:

• No run against a physical terminal yet.
• No darwin-x64 prebuild.
• @padosoft/ecr17 still depends on the unpublished @padosoft/native-modules.
• Cloudflare Pages fails on chore: bun monorepo, @padosoft/ecr17 core with SwiftPM, apps/docs, TS scripts #26 and feat: @padosoft/ecr17-node (Node.js API) and a production POSIX transport #28. Most likely the docs project's root directory needs to change from docs-site to apps/docs in the Cloudflare dashboard.

Next, per the agreed plan: a separate PR that switches the RN binding to PosixTransport on iOS and Android and removes the Swift/Kotlin transports. It's gated on a real-terminal test.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying react-native-ecr17-protocol with    Cloudflare Pages

Latest commit:	1365a03
Status:	🚫  Build failed.

View logs