@padosoft/react-native-ecr17 0.0.0

package/package.json

@@ -0,0 +1,102 @@
+{
+	"name": "@padosoft/react-native-ecr17",
+	"version": "0.0.0",
+	"description": "react-native-ecr17 is a RN package built with Nitro for the ECR17 protocol, allowing integration with POS terminals.",
+	"main": "./lib/commonjs/index.js",
+	"module": "./lib/module/index.js",
+	"types": "./lib/typescript/src/index.d.ts",
+	"react-native": "src/index",
+	"source": "src/index",
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"clean": "git clean -dfX",
+		"build": "bob build",
+		"codegen": "nitrogen --logLevel=\"debug\" && bun run build"
+	},
+	"keywords": [
+		"react-native",
+		"react-native-ecr17",
+		"ecr17"
+	],
+	"files": [
+		"src",
+		"react-native.config.js",
+		"lib",
+		"nitrogen",
+		"cpp",
+		"nitro.json",
+		"android/build.gradle",
+		"android/fix-prefab.gradle",
+		"android/gradle.properties",
+		"android/CMakeLists.txt",
+		"android/src",
+		"ios/**/*.h",
+		"ios/**/*.m",
+		"ios/**/*.mm",
+		"ios/**/*.cpp",
+		"ios/**/*.swift",
+		"*.podspec",
+		"README.md"
+	],
+	"workspaces": [
+		"example"
+	],
+	"repository": "https://github.com/padosoft/react-native-ecr17.git",
+	"author": "padosoft",
+	"license": "MIT",
+	"bugs": "https://github.com/padosoft/react-native-ecr17/issues",
+	"homepage": "https://github.com/padosoft/react-native-ecr17#readme",
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"devDependencies": {
+		"@types/react": "19.2.0",
+		"nitrogen": "0.35.8",
+		"react": "19.2.3",
+		"react-native-builder-bob": "^0.41.0",
+		"react-native-nitro-modules": "0.35.8",
+		"typescript": "^6.0.3"
+	},
+	"peerDependencies": {
+		"react": "*",
+		"react-native": "*",
+		"react-native-nitro-modules": "*"
+	},
+	"eslintConfig": {
+		"root": true,
+		"extends": [
+			"@react-native",
+			"prettier"
+		],
+		"plugins": [
+			"prettier"
+		],
+		"rules": {
+			"prettier/prettier": [
+				"warn",
+				{
+					"quoteProps": "consistent",
+					"singleQuote": true,
+					"tabWidth": 2,
+					"trailingComma": "es5",
+					"useTabs": false
+				}
+			]
+		}
+	},
+	"react-native-builder-bob": {
+		"source": "src",
+		"output": "lib",
+		"targets": [
+			"commonjs",
+			"module",
+			[
+				"typescript",
+				{
+					"project": "tsconfig.json"
+				}
+			]
+		]
+	}
+}

package/react-native.config.js

@@ -0,0 +1,18 @@
+// React Native CLI autolinking config for this native module.
+// https://github.com/react-native-community/cli/blob/main/docs/dependencies.md
+//
+// Declaring the android/ios platforms makes the CLI treat this package as a
+// native dependency and autolink it. On Android that registers Ecr17Package,
+// whose static initializer loads libEcr17.so (System.loadLibrary) so the Nitro
+// HybridObjects are registered before JS creates them.
+
+module.exports = {
+  dependency: {
+    platforms: {
+      /** @type {import('@react-native-community/cli-types').IOSDependencyParams} */
+      ios: {},
+      /** @type {import('@react-native-community/cli-types').AndroidDependencyParams} */
+      android: {},
+    },
+  },
+};

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./specs/client.nitro";
+export * from "./specs/transport.nitro";
+export * from "./types/client";
+export * from "./utils/client";

package/src/specs/client.nitro.ts

@@ -0,0 +1,102 @@
+import type { HybridObject } from "react-native-nitro-modules";
+import type {
+	CardVerificationRequest,
+	CardVerificationResult,
+	CloseSessionResult,
+	ConnectionState,
+	IncrementalAuthRequest,
+	LrcMode,
+	PaymentRequest,
+	PaymentResult,
+	PreAuthClosureRequest,
+	PreAuthRequest,
+	PreAuthResult,
+	ProgressEvent,
+	ReceiptLine,
+	ReversalRequest,
+	ReversalResult,
+	TotalsResult,
+	VasResult,
+} from "../types/client";
+
+export interface Ecr17Config {
+	host: string;
+	port?: number;
+
+	terminalId: string;
+	cashRegisterId: string;
+
+	lrcMode?: LrcMode;
+
+	keepAlive?: boolean;
+	autoReconnect?: boolean;
+
+	connectionTimeoutMs?: number;
+	responseTimeoutMs?: number;
+	ackTimeoutMs?: number;
+
+	// After a transaction result, keep forwarding 'S' receipt lines (onReceiptLine)
+	// until this many ms of silence. 0/undefined = off. Set when ECR-printing is on.
+	receiptDrainMs?: number;
+
+	retryCount?: number;
+	retryDelayMs?: number;
+
+	debug?: boolean;
+}
+
+export const PosTerminalStatusMessage = {
+	0: "Terminal not configured",
+	1: "Terminal configured, no DLL",
+	2: "Terminal operative (after a DLL)",
+	3: "Terminal not aligned (first DLL requested)",
+	4: "KMPB/KPOS key corrupted (first DLL requested)",
+	5: "DLL solicited by GT pending",
+	6: "Remote SW updated request pending",
+	[-1]: "Unknown",
+} as const;
+
+export type PosTerminalStatus = keyof typeof PosTerminalStatusMessage;
+
+export interface PosStatusResponse {
+	terminalId: string;
+	terminalDateTime: Date;
+	status: PosTerminalStatus;
+	softwareRelease: string;
+}
+
+export interface Ecr17Client
+	extends HybridObject<{
+		ios: "c++";
+		android: "c++";
+	}> {
+	// --- Configuration (synchronous) ---
+	configure(config: Ecr17Config): void;
+	configuration(): Ecr17Config;
+
+	// --- Connection ---
+	connect(): Promise<void>;
+	disconnect(): void;
+	isConnected(): boolean;
+
+	// --- Commands (asynchronous: each performs a full request/response exchange) ---
+	status(): Promise<PosStatusResponse>; //                's'
+	pay(request: PaymentRequest): Promise<PaymentResult>; // 'P'
+	payExtended(request: PaymentRequest): Promise<PaymentResult>; // 'X'
+	reverse(request: ReversalRequest): Promise<ReversalResult>; //  'S'
+	preAuth(request: PreAuthRequest): Promise<PreAuthResult>; //    'p'
+	incrementalAuth(request: IncrementalAuthRequest): Promise<PreAuthResult>; // 'i'
+	preAuthClosure(request: PreAuthClosureRequest): Promise<PaymentResult>; //   'c'
+	verifyCard(request: CardVerificationRequest): Promise<CardVerificationResult>; // 'H'
+	closeSession(): Promise<CloseSessionResult>; // 'C'
+	totals(): Promise<TotalsResult>; //             'T'
+	sendLastResult(): Promise<PaymentResult>; //    'G'
+	enableEcrPrinting(enabled: boolean): Promise<void>; // 'E'
+	reprint(toEcr: boolean): Promise<void>; //             'R'
+	vas(xmlRequest: string): Promise<VasResult>; //        'K'
+
+	// --- Events ---
+	setOnProgress(callback: (event: ProgressEvent) => void): void;
+	setOnReceiptLine(callback: (line: ReceiptLine) => void): void;
+	setOnConnectionStateChange(callback: (state: ConnectionState) => void): void;
+}

package/src/specs/transport.nitro.ts

@@ -0,0 +1,25 @@
+import type { HybridObject } from "react-native-nitro-modules";
+
+// Low-level byte transport for the ECR17 LAN connection.
+//
+// Implemented natively (Swift on iOS, Kotlin on Android) so it can use the
+// platform networking stacks. The C++ protocol core consumes it through a thin
+// adapter; all ECR17 framing/orchestration stays in shared C++.
+//
+// Received bytes are delivered via setOnData (called from a native reader
+// thread). `send` is fire-and-forget; back-pressure/ordering is the transport's
+// responsibility.
+export interface Ecr17Transport
+	extends HybridObject<{
+		ios: "swift";
+		android: "kotlin";
+	}> {
+	connect(host: string, port: number, timeoutMs: number): Promise<void>;
+	disconnect(): void;
+	isConnected(): boolean;
+
+	send(bytes: ArrayBuffer): void;
+
+	setOnData(callback: (bytes: ArrayBuffer) => void): void;
+	setOnDisconnect(callback: () => void): void;
+}

package/src/types/client.ts

@@ -0,0 +1,196 @@
+// LRC scope selector. Which framing bytes are folded into the LRC (base 0x7F):
+//  - "stx":       STX + payload + ETX
+//  - "std":       payload only
+//  - "noext":     payload + ETX
+//  - "stx_noext": STX + payload
+export type LrcMode = "stx" | "std" | "noext" | "stx_noext";
+
+// Transport connection lifecycle.
+export type ConnectionState = "disconnected" | "connecting" | "connected";
+
+// Normalized transaction outcome (mapped from the raw 2-digit result code).
+//  "00" -> ok, "01" -> ko, "05" -> cardNotPresent, "09" -> unknownTag.
+export type TransactionOutcome = "ok" | "ko" | "cardNotPresent" | "unknownTag" | "unknown";
+
+// Card category reported by the terminal (response "Card type": 1/2/3).
+export type CardType = "debit" | "credit" | "other" | "unknown";
+
+// How the card was read (response "Transaction type": ICC/MAG/MAN/CLM/CLI).
+export type TransactionEntryMode = "icc" | "mag" | "manual" | "clessMag" | "clessIcc" | "unknown";
+
+// Requested card handling for a payment (request "Payment type": 0..3).
+export type PaymentCardType = "auto" | "debit" | "credit" | "other";
+
+// Tokenization service requested alongside a payment/preauth/verification (command "U").
+export type TokenizationService = "recurring" | "unscheduledOrOneClick";
+
+export interface TokenizationRequest {
+  service: TokenizationService;
+  // Unique contract code at merchant level, alphanumeric, up to 18 chars.
+  contractCode: string;
+}
+
+// ---------------------------------------------------------------------------
+// Requests
+// ---------------------------------------------------------------------------
+
+export interface PaymentRequest {
+  amountCents: number;
+  // Defaults to the configured cashRegisterId when omitted.
+  cashRegisterId?: string;
+  paymentType?: PaymentCardType;
+  // true => start with the card already inserted in the terminal.
+  cardAlreadyPresent?: boolean;
+  // Text (e.g. contract code) printed at the end of the receipt (max 128 chars).
+  receiptText?: string;
+  // Attach tokenization additional data ("U") to this transaction.
+  tokenization?: TokenizationRequest;
+}
+
+export interface ReversalRequest {
+  cashRegisterId?: string;
+  // STAN of the transaction to reverse; "000000" (default) reverses the last
+  // payment with no STAN check.
+  stan?: string;
+}
+
+export interface PreAuthRequest {
+  amountCents: number;
+  cashRegisterId?: string;
+  paymentType?: PaymentCardType;
+  cardAlreadyPresent?: boolean;
+  receiptText?: string;
+  tokenization?: TokenizationRequest;
+}
+
+export interface IncrementalAuthRequest {
+  amountCents: number;
+  // Unique pre-authorization code from the original pre-auth response.
+  originalPreAuthCode: string;
+  cashRegisterId?: string;
+  receiptText?: string;
+}
+
+export interface PreAuthClosureRequest {
+  amountCents: number;
+  originalPreAuthCode: string;
+  cashRegisterId?: string;
+  receiptText?: string;
+}
+
+export interface CardVerificationRequest {
+  cashRegisterId?: string;
+  paymentType?: PaymentCardType;
+  tokenization?: TokenizationRequest;
+}
+
+// ---------------------------------------------------------------------------
+// Results
+// ---------------------------------------------------------------------------
+
+// DCC / currency-exchange block (only meaningful when applied === true).
+export interface CurrencyExchange {
+  applied: boolean;
+  rate?: number;
+  currencyCode?: string;
+  amountCents?: number;
+  precision?: number;
+}
+
+export interface PaymentResult {
+  outcome: TransactionOutcome;
+  resultCode: string; // raw "00"/"01"/"05"/"09"
+  pan?: string;
+  entryMode?: TransactionEntryMode;
+  authCode?: string;
+  hostDateTime?: string; // raw DDDHHMM as received from host
+  cardType?: CardType;
+  acquirerId?: string;
+  stan?: string;
+  onlineId?: string;
+  errorDescription?: string;
+  currencyExchange?: CurrencyExchange;
+}
+
+export interface ReversalResult {
+  outcome: TransactionOutcome;
+  resultCode: string;
+  pan?: string;
+  entryMode?: TransactionEntryMode;
+  hostDateTime?: string;
+  cardType?: CardType;
+  acquirerId?: string;
+  stan?: string;
+  onlineId?: string;
+  actionCode?: string;
+  errorDescription?: string;
+}
+
+export interface PreAuthResult {
+  outcome: TransactionOutcome;
+  resultCode: string;
+  pan?: string;
+  entryMode?: TransactionEntryMode;
+  authCode?: string;
+  preAuthorizedAmountCents?: number;
+  preAuthCode?: string;
+  actionCode?: string;
+  hostDateTime?: string;
+  cardType?: CardType;
+  acquirerId?: string;
+  stan?: string;
+  onlineId?: string;
+  errorDescription?: string;
+}
+
+export interface CardVerificationResult {
+  outcome: TransactionOutcome;
+  resultCode: string;
+  pan?: string;
+  entryMode?: TransactionEntryMode;
+  authCode?: string;
+  hostDateTime?: string;
+  cardType?: CardType;
+  acquirerId?: string;
+  stan?: string;
+  onlineId?: string;
+  actionCode?: string;
+  errorDescription?: string;
+}
+
+export interface TotalsResult {
+  outcome: TransactionOutcome;
+  resultCode: string;
+  posTotalCents: number;
+}
+
+export interface CloseSessionResult {
+  outcome: TransactionOutcome;
+  resultCode: string;
+  posTotalCents?: number;
+  hostTotalCents?: number;
+  actionCode?: string;
+  errorDescription?: string;
+}
+
+export interface VasResult {
+  responseId: string; // RESPID ("0" = OK)
+  responseMessage: string; // RESPMSG
+  orderId?: string; // ORDER_ID when present
+  rawXml: string; // full concatenated XML response
+}
+
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+
+// Progress-update message shown on the ECR display during a procedure (SOH frame).
+export interface ProgressEvent {
+  message: string;
+}
+
+// A single receipt line streamed by the terminal ("S" message) when ECR
+// printing is enabled.
+export interface ReceiptLine {
+  text: string;
+}

package/src/utils/client.ts

@@ -0,0 +1,10 @@
+import { NitroModules } from "react-native-nitro-modules";
+import type { Ecr17Client, Ecr17Config } from "../specs/client.nitro";
+
+export function createEcr17Client(config: Ecr17Config): Ecr17Client {
+	const client = NitroModules.createHybridObject<Ecr17Client>("Ecr17Client");
+
+	client.configure(config);
+
+	return client;
+}