@capvision/pos

TypeScript library to communicate with payment terminals (EPT / POS) that speak the CaisseAP / Concert V3 (v3.20) protocol, over serial/USB or TCP/IP.

It abstracts the link-layer protocol (handshake, framing, LRC, retries, multi-frame responses) and the business frames (payment, refund, cancellation), so the host application only deals with simple submit* calls and a typed response.

Features

• 🔌 Serial/USB and TCP/IP transports.
• 🧭 Fully configurable serial link (baud, data bits, parity, stop bits, flow control, DTR/RTS) plus auto-detection across a library of known configurations to support the widest range of terminals.
• 🧱 Layered, testable architecture: business socket → protocol codec → byte transport. Add custom media via a transportFactory.
• 🛑 Cancellation (AbortSignal), per-stage timeouts, NAK resend, EOT link-release on abort, and an optional pre-transaction watchdog.
• 🔒 PCI-aware logging: card data (PAN, CMC7 track) is masked.
• ✅ 116 hardware-free tests (Vitest) covering the protocol, framing, responses and auto-detection.

Install

npm install @capvision/pos

Node ≥ 22. The serial transport needs the serialport peer dependency (^13); TCP/IP uses Node's built-in net.

Quick start

import { POSSocket_Serial, POSSocket_TCPIP } from "@capvision/pos";

// Serial / USB (default 9600 8N1)
const pos = new POSSocket_Serial("COM3");
// Auto-detect the serial configuration:
// const pos = new POSSocket_Serial("COM3", { autoDetect: true });
// Or TCP/IP:
// const pos = new POSSocket_TCPIP("192.168.1.50", 8888);

await pos.openConnection();
try {
    const res = await pos.submitPayment(10.5); // €10.50
    if (res.success) console.log("Accepted", res.amount, res.paymentMethod);
    else if (res.canceled) console.log("Cancelled");
    else console.log("Refused:", res.reason);
} finally {
    await pos.closeConnection();
}

Operations: submitPayment(amount), submitRefund(amount), submitCancellation(amount). Amounts are in monetary units (e.g. 10.5 = €10.50) and must be strictly positive. All accept an optional { signal: AbortSignal }.

Documentation

• 📖 docs/GUIDE.md — full developer guide: architecture, serial compatibility & auto-detection, TCP/IP, cancellation/timeouts, custom transports, error handling, security.
• 📐 docs/feature.md — protocol/functional reference (for re-implementation in another language).
• 🛠️ docs/README.md — build & npm publishing (Azure Pipelines).

Scripts

| Script | Description | |---|---| | npm run build | Build the library into dist/ (tsup). | | npm test | Run the Vitest suite (no hardware required). | | npm run test:watch | Vitest in watch mode. | | npm run test:coverage | Vitest with coverage. | | npm run test:integration | Interactive harness in tool/ (real terminal). | | npm run check | Biome format + lint (--write). |

License

Proprietary — © Cap Vision (capvision.fr). All rights reserved.