@fire-spark/payments-clisitef-pinpad-rn 0.8.1 → 0.8.2

package/dist/index.d.ts

@@ -66,6 +66,13 @@ declare const CLISITEF_COMMAND: {
 /** `continueTransaction` answers to `CONFIRM` (20). */
 declare const CLISITEF_YES = "0";
 declare const CLISITEF_NO = "1";
+/** `continueTransaction` answer to `CHECK_ABORT` (23): interrupt. */
+declare const CLISITEF_INTERRUPT = "1";
+/**
+ * Commands answered after `abortTransaction(-1)` without `stage 1`; then the
+ * adapter stops answering and leaves the record open (legacy criterion).
+ */
+declare const CLISITEF_DRAIN_LIMIT = 10;
 /** `TipoCampo` ids stored with `STORE_FIELD` (Fiserv "Tabela TipoCampo"). */
 declare const CLISITEF_FIELD: {
   readonly TRANSACTION_DATE: 105;
@@ -305,9 +312,10 @@ declare const isOpen: (record: ClisitefTransactionRecord) => boolean;
 /**
  * `confirmed`: `stage 2` closed with 0. `declined`: failed before the card
  * was charged. `undone`: `finishTransaction(0)` sent after a capture or an
- * approval. `unresolved`: the undo itself failed; needs review.
+ * approval. `unresolved`: the undo itself failed; needs review. `open`: given
+ * up, but the routine never returned `stage 1`; the next charge recovers it.
  */
-type ClisitefOutcomeStatus = "confirmed" | "declined" | "undone" | "unresolved";
+type ClisitefOutcomeStatus = "confirmed" | "declined" | "undone" | "unresolved" | "open";
 type ClisitefOutcome = {
   status: ClisitefOutcomeStatus;
   /** Provider code: `resultCode`, a client error code, or `null`. */
@@ -342,4 +350,4 @@ type ClisitefTransactionInput = {
  */
 declare const runClisitefTransaction: (input: ClisitefTransactionInput) => Promise<ClisitefOutcome>;
 //#endregion
-export { CLISITEF_CANCEL_CODES, CLISITEF_CAPTURE_FIELDS, CLISITEF_COMMAND, CLISITEF_CONFIRMATION_TIMEOUT_MS, CLISITEF_DEFAULT_OPERATOR, CLISITEF_FIELD, CLISITEF_INCONCLUSIVE_CODES, CLISITEF_MODALITIES, CLISITEF_NO, CLISITEF_PAYMENT_TIMEOUT_MS, CLISITEF_PINPAD_TYPES, CLISITEF_REFUNDS_KEY, CLISITEF_REFUND_STORAGE_KEY, CLISITEF_REVERSALS_KEY, CLISITEF_STORAGE_KEY, CLISITEF_VOID_FIELD, CLISITEF_YES, ClisitefFields, ClisitefMenuDecision, ClisitefMenuPurpose, ClisitefModality, ClisitefOutcome, ClisitefOutcomeStatus, ClisitefPendingReversal, ClisitefPinPadOptions, ClisitefPinPadSettings, ClisitefProviderMetadata, ClisitefTransactionInput, ClisitefTransactionRecord, ClisitefTransactionState, ClisitefVoidContext, ClisitefVoidDeps, clisitefDetails, clisitefLast4, clisitefMetadata, clisitefModalityOf, clisitefPinPadCapabilities, clisitefPinPadDeviceFields, clisitefPinPadErrors, clisitefPinPadPayments, clisitefVoidMetadata, dropReversal, isClisitefModality, isOpen, queueReversal, readClisitefPinPadSettings, readPendingReversals, readRefund, readTransaction, redactSecrets, resolveClisitefMenu, runClisitefTransaction, runClisitefVoid, writeRefund, writeTransaction };
+export { CLISITEF_CANCEL_CODES, CLISITEF_CAPTURE_FIELDS, CLISITEF_COMMAND, CLISITEF_CONFIRMATION_TIMEOUT_MS, CLISITEF_DEFAULT_OPERATOR, CLISITEF_DRAIN_LIMIT, CLISITEF_FIELD, CLISITEF_INCONCLUSIVE_CODES, CLISITEF_INTERRUPT, CLISITEF_MODALITIES, CLISITEF_NO, CLISITEF_PAYMENT_TIMEOUT_MS, CLISITEF_PINPAD_TYPES, CLISITEF_REFUNDS_KEY, CLISITEF_REFUND_STORAGE_KEY, CLISITEF_REVERSALS_KEY, CLISITEF_STORAGE_KEY, CLISITEF_VOID_FIELD, CLISITEF_YES, ClisitefFields, ClisitefMenuDecision, ClisitefMenuPurpose, ClisitefModality, ClisitefOutcome, ClisitefOutcomeStatus, ClisitefPendingReversal, ClisitefPinPadOptions, ClisitefPinPadSettings, ClisitefProviderMetadata, ClisitefTransactionInput, ClisitefTransactionRecord, ClisitefTransactionState, ClisitefVoidContext, ClisitefVoidDeps, clisitefDetails, clisitefLast4, clisitefMetadata, clisitefModalityOf, clisitefPinPadCapabilities, clisitefPinPadDeviceFields, clisitefPinPadErrors, clisitefPinPadPayments, clisitefVoidMetadata, dropReversal, isClisitefModality, isOpen, queueReversal, readClisitefPinPadSettings, readPendingReversals, readRefund, readTransaction, redactSecrets, resolveClisitefMenu, runClisitefTransaction, runClisitefVoid, writeRefund, writeTransaction };

package/dist/index.js

@@ -34,6 +34,13 @@ const CLISITEF_COMMAND = {
 /** `continueTransaction` answers to `CONFIRM` (20). */
 const CLISITEF_YES = "0";
 const CLISITEF_NO = "1";
+/** `continueTransaction` answer to `CHECK_ABORT` (23): interrupt. */
+const CLISITEF_INTERRUPT = "1";
+/**
+* Commands answered after `abortTransaction(-1)` without `stage 1`; then the
+* adapter stops answering and leaves the record open (legacy criterion).
+*/
+const CLISITEF_DRAIN_LIMIT = 10;
 /** `TipoCampo` ids stored with `STORE_FIELD` (Fiserv "Tabela TipoCampo"). */
 const CLISITEF_FIELD = {
 	TRANSACTION_DATE: 105,
@@ -459,6 +466,9 @@ const runClisitefTransaction = (input) => {
 	let approved = false;
 	let closing = false;
 	let aborted = false;
+	/** Why the adapter asked to interrupt; `stage 1` has not arrived yet. */
+	let givingUp = null;
+	let drained = 0;
 	let watchdog;
 	let queue = Promise.resolve();
 	let resolve = () => void 0;
@@ -507,18 +517,37 @@ const runClisitefTransaction = (input) => {
 			});
 		}
 	};
-	const close = async (reason) => {
-		log("close", reason);
-		if (closing) return;
+	/** Stops answering and leaves the record open: `stage 1` never came. */
+	const abandon = () => {
+		log("abandon", {
+			drained,
+			skipped: closing
+		});
+		if (closing || !givingUp) return;
 		closing = true;
-		if (!approved) await client.abortTransaction(CLISITEF_ABORT_FLAG).catch(() => 0);
-		if (captured || approved) return undo(reason);
-		settle("declined", reason);
+		settle("open", givingUp);
+	};
+	/**
+	* Asks CliSiTef to interrupt (`Continua = -1`) and keeps the loop running
+	* until `stage 1`: dropping it earlier leaves the routine open (`-12`). An
+	* approval already confirmed with `finishTransaction(1)` is undone instead.
+	*/
+	const giveUp = (reason) => {
+		log("give up", reason);
+		if (closing || givingUp) return;
+		if (approved) {
+			closing = true;
+			undo(reason);
+			return;
+		}
+		givingUp = reason;
+		watchdog = setTimeout(abandon, input.confirmationTimeoutMs);
+		client.abortTransaction(CLISITEF_ABORT_FLAG).catch(() => 0);
 	};
 	function onAbort() {
 		log("signal aborted (payment deadline)");
 		aborted = true;
-		close({
+		giveUp({
 			code: null,
 			message: "Aborted by the payment deadline"
 		});
@@ -532,6 +561,36 @@ const runClisitefTransaction = (input) => {
 		if (closing) return;
 		await client.continueTransaction(data);
 	};
+	const store = (event) => {
+		fields.set(event.fieldId, event.input);
+		if (CLISITEF_CAPTURE_FIELDS.has(event.fieldId)) captured = true;
+	};
+	const clearQr = () => {
+		ui.action({
+			type: "qr",
+			payload: "",
+			format: "text",
+			expiresAt: null
+		});
+	};
+	/** Answers without the UI while CliSiTef winds down after the abort. */
+	const drain = async (event) => {
+		drained += 1;
+		log("drain", {
+			command: event.command,
+			drained
+		});
+		if (drained > 10) return abandon();
+		const { command } = event;
+		if (command === CLISITEF_COMMAND.STORE_FIELD) store(event);
+		if (command === CLISITEF_COMMAND.QR_HIDE) clearQr();
+		const interrupt = command === CLISITEF_COMMAND.CHECK_ABORT;
+		return reply(interrupt ? "1" : "");
+	};
+	/** A UI answer that arrives after giving up is not sent. */
+	const respond = (event, data) => {
+		return givingUp ? drain(event) : reply(data);
+	};
 	const showMessage = (text) => {
 		const collapsed = collapseCounter(text.trim());
 		if (!collapsed || collapsed === lastMessage) return;
@@ -541,8 +600,8 @@ const runClisitefTransaction = (input) => {
 			kind: "waiting"
 		});
 	};
-	const onMenu = async (text) => {
-		const options = parseClisitefMenu(text);
+	const onMenu = async (event) => {
+		const options = parseClisitefMenu(event.input);
 		const label = title || "Selecione uma opção";
 		const decision = resolveClisitefMenu(...[
 			options,
@@ -555,11 +614,11 @@ const runClisitefTransaction = (input) => {
 			decision
 		});
 		if (decision.kind === "abort") {
-			const reason = {
+			giveUp({
 				code: "FINANCING_ONLY",
 				message: decision.message
-			};
-			return close(reason);
+			});
+			return drain(event);
 		}
 		if (decision.kind === "pick") return reply(decision.value);
 		const p2 = {
@@ -568,7 +627,7 @@ const runClisitefTransaction = (input) => {
 		};
 		const picked = await ui.select(p2);
 		log("ui.select ← out", { picked });
-		return reply(picked);
+		return respond(event, picked);
 	};
 	const onQr = (event) => {
 		const payload = event.input.trim();
@@ -592,20 +651,15 @@ const runClisitefTransaction = (input) => {
 			...redact(event),
 			title
 		});
+		if (givingUp) return drain(event);
 		const { command, input: text } = event;
 		if (command === CLISITEF_COMMAND.STORE_FIELD) {
-			fields.set(event.fieldId, text);
-			if (CLISITEF_CAPTURE_FIELDS.has(event.fieldId)) captured = true;
+			store(event);
 			return reply("");
 		}
 		if (command === CLISITEF_COMMAND.QR_SHOW) return onQr(event);
 		if (command === CLISITEF_COMMAND.QR_HIDE) {
-			ui.action({
-				type: "qr",
-				payload: "",
-				format: "text",
-				expiresAt: null
-			});
+			clearQr();
 			return reply("");
 		}
 		if (MESSAGES.has(command)) {
@@ -625,9 +679,9 @@ const runClisitefTransaction = (input) => {
 			log("ui.confirm → in", { text: text.trim() || title });
 			const yes = await ui.confirm({ text: text.trim() || title });
 			log("ui.confirm ← out", { yes });
-			return reply(yes ? "0" : "1");
+			return respond(event, yes ? "0" : "1");
 		}
-		if (command === CLISITEF_COMMAND.MENU) return onMenu(text);
+		if (command === CLISITEF_COMMAND.MENU) return onMenu(event);
 		if (READS.has(command)) {
 			const known = input.answerField?.(event.fieldId) ?? null;
 			if (known !== null) return reply(known, true);
@@ -640,13 +694,14 @@ const runClisitefTransaction = (input) => {
 			};
 			log("ui.input → in", p1);
 			const value = await ui.input(p1);
-			return reply(value);
+			return respond(event, value);
 		}
 		const message = `Unsupported CliSiTef command ${command}`;
-		return close({
+		giveUp({
 			code: `UNSUPPORTED_COMMAND_${command}`,
 			message
 		});
+		return drain(event);
 	};
 	const confirm = () => {
 		const message = "CliSiTef did not close the confirmation";
@@ -678,6 +733,21 @@ const runClisitefTransaction = (input) => {
 			});
 		});
 	};
+	/**
+	* `stage 1` after giving up. A late approval is undone, never confirmed; a
+	* cancel (`-2`, `-6`, `-15`) needs no `finishTransaction`: CliSiTef sends
+	* the undo itself.
+	*/
+	const windDown = (reason, code) => {
+		closing = true;
+		const closed = {
+			...reason,
+			code: reason.code ?? code
+		};
+		const inconclusive = captured && CLISITEF_INCONCLUSIVE_CODES.has(code);
+		if (code === CLISITEF_RESULT.OK || inconclusive) return undo(closed);
+		settle("declined", closed);
+	};
 	const onResult = async (event) => {
 		const { stage, resultCode: code } = event;
 		log("onTransactionResult", {
@@ -686,6 +756,7 @@ const runClisitefTransaction = (input) => {
 			skipped: closing
 		});
 		if (closing) return;
+		if (givingUp && stage === 1) return windDown(givingUp, code);
 		if (stage === 1 && code === CLISITEF_RESULT.OK) {
 			approved = true;
 			await input.onApproved(fields);
@@ -715,7 +786,8 @@ const runClisitefTransaction = (input) => {
 			message: null
 		});
 	};
-	const enqueue = (handle) => {
+	/** A failed `onData` handler still owes CliSiTef an answer. */
+	const enqueue = (handle, event) => {
 		const run = async () => {
 			await handle();
 		};
@@ -729,10 +801,11 @@ const runClisitefTransaction = (input) => {
 				error
 			});
 			if (closing) return;
-			await close({
+			giveUp({
 				...reason,
 				error
 			});
+			if (event && givingUp) await drain(event).catch(abandon);
 		});
 	};
 	const begin = async () => {
@@ -748,7 +821,7 @@ const runClisitefTransaction = (input) => {
 			});
 		}
 		signal.addEventListener("abort", onAbort);
-		const handleData = (e) => enqueue(() => onData(e));
+		const handleData = (e) => enqueue(() => onData(e), e);
 		const handleResult = (e) => {
 			enqueue(() => onResult(e));
 		};
@@ -1210,6 +1283,7 @@ const paid = (record) => {
 */
 const isAmbiguous = (outcome) => {
 	if (outcome.status === "unresolved") return true;
+	if (outcome.status === "open") return outcome.evidence;
 	if (!outcome.evidence || outcome.status !== "undone") return false;
 	const { code } = outcome;
 	const inconclusive = typeof code === "number" && CLISITEF_INCONCLUSIVE_CODES.has(code);
@@ -1226,7 +1300,8 @@ const outcomeError = (outcome, attempt) => {
 		provider_code: code
 	};
 	if (isAmbiguous(outcome)) return createPaymentError("AMBIGUOUS", extra);
-	if (outcome.aborted) return createPaymentError("TIMEOUT", extra);
+	const cancelled = typeof outcome.code === "number" && CLISITEF_CANCEL_CODES.has(outcome.code);
+	if (outcome.aborted && !cancelled) return createPaymentError("TIMEOUT", extra);
 	if (outcome.code === null) {
 		const message = outcome.message ?? void 0;
 		return createPaymentError("PROVIDER_UNAVAILABLE", {
@@ -1274,9 +1349,13 @@ const debugContext = (ctx) => {
 		deviceSettings: redactSecrets(ctx.deviceSettings)
 	};
 };
-/** `review` when the customer may have paid; `approved` when the undo failed. */
+/**
+* `review` when the customer may have paid; `approved` when the undo failed;
+* `started` when the routine never closed, so the next charge recovers it.
+*/
 const closingState = (outcome) => {
 	if (outcome.status === "unresolved") return "approved";
+	if (outcome.status === "open") return "started";
 	return isAmbiguous(outcome) ? "review" : "undone";
 };
 const terminalError = (error) => {
@@ -1316,7 +1395,10 @@ const clisitefPinPadPayments = (options = {}) => {
 			fallback: "TERMINAL_NOT_CONFIGURED"
 		});
 	};
-	/** Undoes a transaction a crash or a lost result left open. */
+	/**
+	* Undoes a transaction a crash, a lost result or an interrupted abort left
+	* pending in CliSiTef. A `review` record stays as is when nothing is pending.
+	*/
 	const recover = async (storage, record, key = CLISITEF_STORAGE_KEY) => {
 		const { fiscalCoupon, fiscalDate, time } = record;
 		const count = client.getQttPendingTransactions;
@@ -1326,6 +1408,7 @@ const clisitefPinPadPayments = (options = {}) => {
 			record
 		});
 		if (pending === null) return record;
+		if (pending === 0 && record.state === "review") return record;
 		let next;
 		if (pending > 0) {
 			const p1 = {
@@ -1371,12 +1454,17 @@ const clisitefPinPadPayments = (options = {}) => {
 	const isConfigureBusy = (error) => {
 		return error?.provider_code === "-12";
 	};
-	/** Drops a leftover native session so `configure` can run again. */
+	/**
+	* Interrupts a leftover native session so `configure` can run again. No
+	* `submitPendingMessages` or `closePinPad` here: right after an abort they
+	* left the native thread hung in production.
+	*/
 	const releaseNative = async () => {
 		await client.abortTransaction(CLISITEF_ABORT_FLAG).catch(() => 0);
-		await client.submitPendingMessages().catch(() => -1);
-		await client.closePinPad().catch(() => -1);
-		client.invalidate();
+	};
+	/** Open, or flagged for review with the coupon maybe still pending. */
+	const recoverable = (record) => {
+		return isOpen(record) || record.state === "review";
 	};
 	/** Configures and resolves the open records of the device, if any. */
 	const prepare = async (ctx) => {
@@ -1390,7 +1478,7 @@ const clisitefPinPadPayments = (options = {}) => {
 		const storage = storageOf(ctx);
 		const resolve = async (key) => {
 			const found = await readTransaction(storage, key);
-			if (error || !found || !isOpen(found)) return found;
+			if (error || !found || !recoverable(found)) return found;
 			return recover(storage, found, key);
 		};
 		const record = await resolve(CLISITEF_STORAGE_KEY);
@@ -1734,4 +1822,4 @@ const clisitefPinPadPayments = (options = {}) => {
 	};
 };
 //#endregion
-export { CLISITEF_CANCEL_CODES, CLISITEF_CAPTURE_FIELDS, CLISITEF_COMMAND, CLISITEF_CONFIRMATION_TIMEOUT_MS, CLISITEF_DEFAULT_OPERATOR, CLISITEF_FIELD, CLISITEF_INCONCLUSIVE_CODES, CLISITEF_MODALITIES, CLISITEF_NO, CLISITEF_PAYMENT_TIMEOUT_MS, CLISITEF_PINPAD_TYPES, CLISITEF_REFUNDS_KEY, CLISITEF_REFUND_STORAGE_KEY, CLISITEF_REVERSALS_KEY, CLISITEF_STORAGE_KEY, CLISITEF_VOID_FIELD, CLISITEF_YES, clisitefDetails, clisitefLast4, clisitefMetadata, clisitefModalityOf, clisitefPinPadCapabilities, clisitefPinPadDeviceFields, clisitefPinPadErrors, clisitefPinPadPayments, clisitefVoidMetadata, dropReversal, isClisitefModality, isOpen, queueReversal, readClisitefPinPadSettings, readPendingReversals, readRefund, readTransaction, redactSecrets, resolveClisitefMenu, runClisitefTransaction, runClisitefVoid, writeRefund, writeTransaction };
+export { CLISITEF_CANCEL_CODES, CLISITEF_CAPTURE_FIELDS, CLISITEF_COMMAND, CLISITEF_CONFIRMATION_TIMEOUT_MS, CLISITEF_DEFAULT_OPERATOR, CLISITEF_DRAIN_LIMIT, CLISITEF_FIELD, CLISITEF_INCONCLUSIVE_CODES, CLISITEF_INTERRUPT, CLISITEF_MODALITIES, CLISITEF_NO, CLISITEF_PAYMENT_TIMEOUT_MS, CLISITEF_PINPAD_TYPES, CLISITEF_REFUNDS_KEY, CLISITEF_REFUND_STORAGE_KEY, CLISITEF_REVERSALS_KEY, CLISITEF_STORAGE_KEY, CLISITEF_VOID_FIELD, CLISITEF_YES, clisitefDetails, clisitefLast4, clisitefMetadata, clisitefModalityOf, clisitefPinPadCapabilities, clisitefPinPadDeviceFields, clisitefPinPadErrors, clisitefPinPadPayments, clisitefVoidMetadata, dropReversal, isClisitefModality, isOpen, queueReversal, readClisitefPinPadSettings, readPendingReversals, readRefund, readTransaction, redactSecrets, resolveClisitefMenu, runClisitefTransaction, runClisitefVoid, writeRefund, writeTransaction };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fire-spark/payments-clisitef-pinpad-rn",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Fire Spark CliSiTef (Software Express) pinpad adapter for Brazil: debit, credit, voucher and Pix with automatic voids on Android kiosks",
   "type": "module",
   "sideEffects": false,
@@ -17,9 +17,9 @@
     }
   },
   "dependencies": {
-    "@fire-spark/payments": "^0.8.1",
-    "@fire-spark/payments-clisitef-client": "^0.8.1",
-    "@fire-spark/types": "^0.8.1"
+    "@fire-spark/payments": "^0.8.2",
+    "@fire-spark/payments-clisitef-client": "^0.8.2",
+    "@fire-spark/types": "^0.8.2"
   },
   "devDependencies": {
     "tsdown": "^0.22.14",