@fire-spark/payments-clisitef-pinpad-rn 0.7.0 → 0.7.1

package/dist/index.d.ts

@@ -17,12 +17,17 @@ type ClisitefPinPadOptions = {
   timeZone?: string;
   now?: () => Date;
   confirmationTimeoutMs?: number;
+  /**
+   * Payment deadline (`policy.timeout_ms`); defaults to 180 s. A
+   * `runtime.timeout_ms` in the payment or method config overrides it.
+   */
+  timeoutMs?: number;
 };
 /**
  * CliSiTef (Software Express) on the kiosk pinpad, Brazil. One adapter per
  * modality payment (DEBIT / CREDIT / VOUCHER in `payments.config`). The
- * pinpad waits on the customer: give the payment a `runtime.timeout_ms`
- * well above the 30 s default (e.g. 90 000).
+ * pinpad waits on the customer, so the deadline is `timeoutMs` instead of
+ * the 30 s library default.
  */
 declare const clisitefPinPadPayments: (options?: ClisitefPinPadOptions) => PaymentAdapter;
 //#endregion
@@ -80,6 +85,11 @@ declare const CLISITEF_CANCEL_CODES: ReadonlySet<number>;
 declare const CLISITEF_INCONCLUSIVE_CODES: ReadonlySet<number>;
 /** Approved (`stage 1`) without `stage 2`: undo (legacy `CONFIRMATION_TIMEOUT_MS`). */
 declare const CLISITEF_CONFIRMATION_TIMEOUT_MS = 60000;
+/**
+ * Payment deadline: covers the pinpad table load (`OBTENDO REGISTRO`), which
+ * can take minutes, plus card and PIN entry.
+ */
+declare const CLISITEF_PAYMENT_TIMEOUT_MS = 180000;
 /** Legacy operator when the merchant config has none. */
 declare const CLISITEF_DEFAULT_OPERATOR = "KIOSKO_BR";
 /** Device-wide record of the last transaction, to undo it after a crash. */
@@ -204,4 +214,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_NO, CLISITEF_PINPAD_TYPES, CLISITEF_STORAGE_KEY, CLISITEF_YES, ClisitefFields, ClisitefModality, ClisitefOutcome, ClisitefOutcomeStatus, ClisitefPinPadOptions, ClisitefPinPadSettings, ClisitefTransactionInput, ClisitefTransactionRecord, ClisitefTransactionState, clisitefDetails, clisitefLast4, clisitefMetadata, clisitefPinPadCapabilities, clisitefPinPadDeviceFields, clisitefPinPadErrors, clisitefPinPadPayments, isOpen, readClisitefPinPadSettings, readTransaction, runClisitefTransaction, writeTransaction };
+export { CLISITEF_CANCEL_CODES, CLISITEF_CAPTURE_FIELDS, CLISITEF_COMMAND, CLISITEF_CONFIRMATION_TIMEOUT_MS, CLISITEF_DEFAULT_OPERATOR, CLISITEF_FIELD, CLISITEF_INCONCLUSIVE_CODES, CLISITEF_NO, CLISITEF_PAYMENT_TIMEOUT_MS, CLISITEF_PINPAD_TYPES, CLISITEF_STORAGE_KEY, CLISITEF_YES, ClisitefFields, ClisitefModality, ClisitefOutcome, ClisitefOutcomeStatus, ClisitefPinPadOptions, ClisitefPinPadSettings, ClisitefTransactionInput, ClisitefTransactionRecord, ClisitefTransactionState, clisitefDetails, clisitefLast4, clisitefMetadata, clisitefPinPadCapabilities, clisitefPinPadDeviceFields, clisitefPinPadErrors, clisitefPinPadPayments, isOpen, readClisitefPinPadSettings, readTransaction, runClisitefTransaction, writeTransaction };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { PaymentError, createPaymentError, definePaymentErrors, toPaymentError } from "@fire-spark/payments";
-import { CLISITEF_ABORT_FLAG, CLISITEF_CONFIRM, CLISITEF_MODALITY, CLISITEF_RESULT, CLISITEF_TIMEOUT_CODE, clisitef, clisitefAdditionalParams, clisitefFiscalDateTime, formatClisitefAmount, parseClisitefMenu } from "@fire-spark/payments-clisitef-client";
+import { CLISITEF_ABORT_FLAG, CLISITEF_CONFIRM, CLISITEF_MODALITY, CLISITEF_RESULT, CLISITEF_TIMEOUT_CODE, clisitef, clisitefAdditionalParams, clisitefDebug, clisitefDebugCall, clisitefFiscalDateTime, formatClisitefAmount, parseClisitefMenu } from "@fire-spark/payments-clisitef-client";
 //#region src/constants.ts
 /**
 * `onData` commands handled by the adapter (Fiserv "Tabela de códigos de
@@ -71,6 +71,11 @@ const CLISITEF_INCONCLUSIVE_CODES = /* @__PURE__ */ new Set([
 ]);
 /** Approved (`stage 1`) without `stage 2`: undo (legacy `CONFIRMATION_TIMEOUT_MS`). */
 const CLISITEF_CONFIRMATION_TIMEOUT_MS = 6e4;
+/**
+* Payment deadline: covers the pinpad table load (`OBTENDO REGISTRO`), which
+* can take minutes, plus card and PIN entry.
+*/
+const CLISITEF_PAYMENT_TIMEOUT_MS = 18e4;
 /** Legacy operator when the merchant config has none. */
 const CLISITEF_DEFAULT_OPERATOR = "KIOSKO_BR";
 /** Device-wide record of the last transaction, to undo it after a crash. */
@@ -296,6 +301,11 @@ const readClisitefPinPadSettings = (config, device) => {
 	};
 	Object.assign(values, more);
 	const missing = Object.keys(values).filter((key) => !values[key]);
+	clisitefDebug("pinpad.settings", "read", {
+		config,
+		device,
+		missing
+	});
 	if (missing.length) throw notConfigured(missing);
 	if (!isModality(modality)) throw notConfigured(["a valid modality"]);
 	return {
@@ -324,6 +334,7 @@ const isRecord = (value) => {
 };
 const readTransaction = async (storage) => {
 	const raw = await storage.get(CLISITEF_STORAGE_KEY);
+	clisitefDebug("pinpad.store", "read", { raw });
 	if (!raw) return null;
 	try {
 		const parsed = JSON.parse(raw);
@@ -333,6 +344,7 @@ const readTransaction = async (storage) => {
 	}
 };
 const writeTransaction = async (storage, record) => {
+	clisitefDebug("pinpad.store", `write ${record.state}`, record);
 	await storage.set(CLISITEF_STORAGE_KEY, JSON.stringify(record));
 };
 const isOpen = (record) => {
@@ -391,7 +403,23 @@ const runClisitefTransaction = (input) => {
 	let queue = Promise.resolve();
 	let resolve = () => void 0;
 	const done = new Promise((r) => resolve = r);
+	const log = (event, data) => {
+		const flags = {
+			captured,
+			approved,
+			closing,
+			aborted
+		};
+		clisitefDebug("pinpad.transaction", event, {
+			...data && typeof data === "object" ? data : { value: data },
+			flags
+		});
+	};
 	const settle = (status, reason) => {
+		log(`settle ${status}`, {
+			...reason,
+			fields: Object.fromEntries(fields)
+		});
 		clearTimeout(watchdog);
 		for (const subscription of subscriptions) subscription.remove();
 		signal.removeEventListener("abort", onAbort);
@@ -403,6 +431,7 @@ const runClisitefTransaction = (input) => {
 		});
 	};
 	const undo = async (reason) => {
+		log("undo (finishTransaction 0)", reason);
 		try {
 			const p1 = {
 				confirm: CLISITEF_CONFIRM.UNDO,
@@ -418,6 +447,7 @@ const runClisitefTransaction = (input) => {
 		}
 	};
 	const close = async (reason) => {
+		log("close", reason);
 		if (closing) return;
 		closing = true;
 		if (!approved) await client.abortTransaction(CLISITEF_ABORT_FLAG).catch(() => 0);
@@ -425,6 +455,7 @@ const runClisitefTransaction = (input) => {
 		settle("declined", reason);
 	};
 	function onAbort() {
+		log("signal aborted (payment deadline)");
 		aborted = true;
 		close({
 			code: null,
@@ -432,10 +463,18 @@ const runClisitefTransaction = (input) => {
 		});
 	}
 	const reply = async (data) => {
+		log("reply", {
+			data,
+			skipped: closing
+		});
 		if (closing) return;
 		await client.continueTransaction(data);
 	};
 	const onData = async (event) => {
+		log("onData", {
+			...event,
+			title
+		});
 		const { command, input: text } = event;
 		if (command === CLISITEF_COMMAND.STORE_FIELD) {
 			fields.set(event.fieldId, text);
@@ -459,16 +498,24 @@ const runClisitefTransaction = (input) => {
 		}
 		if (SILENT.has(command)) return reply("");
 		if (command === CLISITEF_COMMAND.CONFIRM) {
+			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");
 		}
 		if (command === CLISITEF_COMMAND.MENU) {
 			const options = parseClisitefMenu(text);
 			const label = title || "Selecione uma opção";
-			return reply(await ui.select({
+			log("ui.select → in", {
 				title: label,
 				options
-			}));
+			});
+			const picked = await ui.select({
+				title: label,
+				options
+			});
+			log("ui.select ← out", { picked });
+			return reply(picked);
 		}
 		if (READS.has(command)) {
 			const label = text.trim() || title || "Informe o dado";
@@ -478,7 +525,10 @@ const runClisitefTransaction = (input) => {
 				type: inputType(command),
 				maxLength: max
 			};
-			return reply(await ui.input(p1));
+			log("ui.input → in", p1);
+			const value = await ui.input(p1);
+			log("ui.input ← out", { value });
+			return reply(value);
 		}
 		const message = `Unsupported CliSiTef command ${command}`;
 		return close({
@@ -489,6 +539,7 @@ const runClisitefTransaction = (input) => {
 	const confirm = () => {
 		const message = "CliSiTef did not close the confirmation";
 		const expire = () => {
+			log("confirmation watchdog expired", { skipped: closing });
 			if (closing) return;
 			closing = true;
 			undo({
@@ -501,6 +552,10 @@ const runClisitefTransaction = (input) => {
 			confirm: CLISITEF_CONFIRM.CONFIRM,
 			...input.finish
 		};
+		log("confirm (finishTransaction 1)", {
+			...p1,
+			watchdogMs: input.confirmationTimeoutMs
+		});
 		client.finishTransaction(p1).catch((error) => {
 			if (closing) return;
 			closing = true;
@@ -513,6 +568,11 @@ const runClisitefTransaction = (input) => {
 	};
 	const onResult = async (event) => {
 		const { stage, resultCode: code } = event;
+		log("onTransactionResult", {
+			stage,
+			code,
+			skipped: closing
+		});
 		if (closing) return;
 		if (stage === 1 && code === CLISITEF_RESULT.OK) {
 			approved = true;
@@ -552,6 +612,10 @@ const runClisitefTransaction = (input) => {
 				code: errorCode(error),
 				message: errorMessage(error)
 			};
+			log("handler threw", {
+				...reason,
+				error
+			});
 			if (closing) return;
 			await close({
 				...reason,
@@ -560,6 +624,10 @@ const runClisitefTransaction = (input) => {
 		});
 	};
 	const begin = async () => {
+		log("begin", {
+			start: input.start,
+			finish: input.finish
+		});
 		if (signal.aborted) {
 			aborted = true;
 			return settle("declined", {
@@ -665,6 +733,16 @@ const outcomeError = (outcome, attempt) => {
 		fallback
 	});
 };
+const debugContext = (ctx) => {
+	const { attemptReference, attempt, amount, config, deviceSettings } = ctx;
+	return {
+		attemptReference,
+		attempt,
+		amount,
+		config,
+		deviceSettings
+	};
+};
 const terminalError = (error) => {
 	const message = error instanceof Error ? error.message : String(error);
 	return {
@@ -676,19 +754,24 @@ const terminalError = (error) => {
 /**
 * CliSiTef (Software Express) on the kiosk pinpad, Brazil. One adapter per
 * modality payment (DEBIT / CREDIT / VOUCHER in `payments.config`). The
-* pinpad waits on the customer: give the payment a `runtime.timeout_ms`
-* well above the 30 s default (e.g. 90 000).
+* pinpad waits on the customer, so the deadline is `timeoutMs` instead of
+* the 30 s library default.
 */
 const clisitefPinPadPayments = (options = {}) => {
 	const client = options.client ?? clisitef;
 	const now = options.now ?? (() => /* @__PURE__ */ new Date());
 	const confirmationMs = options.confirmationTimeoutMs ?? 6e4;
+	const timeoutMs = options.timeoutMs ?? 18e4;
 	const lock = createLock();
 	const storageOf = (ctx) => {
 		return options.storage ?? ctx.storage;
 	};
 	const configure = async (settings) => {
 		const code = await client.configure(settings.configure);
+		clisitefDebug("pinpad.adapter.configure", "result", {
+			code,
+			settings
+		});
 		if (code === 0) return null;
 		client.invalidate();
 		return toPaymentError(clisitefPinPadErrors, {
@@ -701,6 +784,10 @@ const clisitefPinPadPayments = (options = {}) => {
 		const { fiscalCoupon, fiscalDate, time } = record;
 		const count = client.getQttPendingTransactions;
 		const pending = await count(fiscalDate, fiscalCoupon).catch(() => null);
+		clisitefDebug("pinpad.adapter.recover", "pending", {
+			pending,
+			record
+		});
 		if (pending === null) return record;
 		let next;
 		if (pending > 0) {
@@ -740,6 +827,7 @@ const clisitefPinPadPayments = (options = {}) => {
 				error
 			};
 		}
+		clisitefDebug("pinpad.adapter.recover", `→ ${next.state}`, next);
 		await writeTransaction(storage, next);
 		return next;
 	};
@@ -750,6 +838,10 @@ const clisitefPinPadPayments = (options = {}) => {
 		const storage = storageOf(ctx);
 		let record = await readTransaction(storage);
 		if (!error && record && isOpen(record)) record = await recover(storage, record);
+		clisitefDebug("pinpad.adapter.prepare", "done", {
+			error,
+			record
+		});
 		return {
 			settings,
 			error,
@@ -855,6 +947,11 @@ const clisitefPinPadPayments = (options = {}) => {
 			...t1,
 			...t2
 		});
+		const fields = Object.fromEntries(outcome.fields);
+		clisitefDebug("pinpad.adapter.charge", "outcome", {
+			...outcome,
+			fields
+		});
 		const metadata = metadataOf(outcome.fields);
 		if (outcome.status === "confirmed") {
 			const details = clisitefDetails(metadata);
@@ -916,8 +1013,14 @@ const clisitefPinPadPayments = (options = {}) => {
 			error: void 0
 		};
 	};
-	const operation = (run) => {
+	const operation = (run, name = "terminal") => {
 		return (ctx) => {
+			const scope = `pinpad.terminal.${name}`;
+			const input = {
+				config: ctx.config,
+				deviceSettings: ctx.deviceSettings
+			};
+			const traced = () => clisitefDebugCall(scope, input, task);
 			const task = async () => {
 				try {
 					const data = await run(ctx);
@@ -930,7 +1033,7 @@ const clisitefPinPadPayments = (options = {}) => {
 					return terminalError(error);
 				}
 			};
-			return lock(task);
+			return lock(traced);
 		};
 	};
 	const terminal = {
@@ -940,15 +1043,17 @@ const clisitefPinPadPayments = (options = {}) => {
 			const error = await configure(s1);
 			if (error) throw new Error(error.message);
 			return "CliSiTef configured";
-		}),
-		test: operation(async () => `CliSiTef ${await client.getVersion()}`),
-		status: operation(async () => client.getHealth() ?? {}),
+		}, "init"),
+		test: operation(async () => {
+			return `CliSiTef ${await client.getVersion()}`;
+		}, "test"),
+		status: operation(async () => client.getHealth() ?? {}, "status"),
 		extra: [{
 			key: "submit_pending_messages",
 			label: "Send pending messages",
 			run: operation(async () => {
 				return `Pending messages sent (${await client.submitPendingMessages()})`;
-			})
+			}, "submit_pending_messages")
 		}, {
 			key: "release_pinpad",
 			label: "Release pinpad",
@@ -957,7 +1062,7 @@ const clisitefPinPadPayments = (options = {}) => {
 				await client.disconnectSitef();
 				client.invalidate();
 				return "Pinpad released";
-			})
+			}, "release_pinpad")
 		}]
 	};
 	return {
@@ -966,12 +1071,31 @@ const clisitefPinPadPayments = (options = {}) => {
 		deviceFields: clisitefPinPadDeviceFields,
 		errors: clisitefPinPadErrors,
 		capabilities: clisitefPinPadCapabilities,
-		start: (ctx) => lock(() => charge(ctx)),
-		query: (ctx, result) => lock(() => query(ctx, result)),
-		cancel: (ctx, result) => lock(() => cancel(ctx, result)),
+		policy: { timeout_ms: timeoutMs },
+		start: (ctx) => {
+			const run = () => charge(ctx);
+			const traced = () => clisitefDebugCall("pinpad.start", debugContext(ctx), run);
+			return lock(traced);
+		},
+		query: (ctx, result) => {
+			const input = {
+				ctx: debugContext(ctx),
+				result
+			};
+			const run = () => query(ctx, result);
+			return lock(() => clisitefDebugCall("pinpad.query", input, run));
+		},
+		cancel: (ctx, result) => {
+			const input = {
+				ctx: debugContext(ctx),
+				result
+			};
+			const run = () => cancel(ctx, result);
+			return lock(() => clisitefDebugCall("pinpad.cancel", input, run));
+		},
 		reversalFor: (result) => result.status === "PAID" ? "manual" : "cancel",
 		terminal
 	};
 };
 //#endregion
-export { CLISITEF_CANCEL_CODES, CLISITEF_CAPTURE_FIELDS, CLISITEF_COMMAND, CLISITEF_CONFIRMATION_TIMEOUT_MS, CLISITEF_DEFAULT_OPERATOR, CLISITEF_FIELD, CLISITEF_INCONCLUSIVE_CODES, CLISITEF_NO, CLISITEF_PINPAD_TYPES, CLISITEF_STORAGE_KEY, CLISITEF_YES, clisitefDetails, clisitefLast4, clisitefMetadata, clisitefPinPadCapabilities, clisitefPinPadDeviceFields, clisitefPinPadErrors, clisitefPinPadPayments, isOpen, readClisitefPinPadSettings, readTransaction, runClisitefTransaction, writeTransaction };
+export { CLISITEF_CANCEL_CODES, CLISITEF_CAPTURE_FIELDS, CLISITEF_COMMAND, CLISITEF_CONFIRMATION_TIMEOUT_MS, CLISITEF_DEFAULT_OPERATOR, CLISITEF_FIELD, CLISITEF_INCONCLUSIVE_CODES, CLISITEF_NO, CLISITEF_PAYMENT_TIMEOUT_MS, CLISITEF_PINPAD_TYPES, CLISITEF_STORAGE_KEY, CLISITEF_YES, clisitefDetails, clisitefLast4, clisitefMetadata, clisitefPinPadCapabilities, clisitefPinPadDeviceFields, clisitefPinPadErrors, clisitefPinPadPayments, isOpen, readClisitefPinPadSettings, readTransaction, runClisitefTransaction, writeTransaction };

package/package.json

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