@fire-spark/payments-redeban-pinpad 0.0.0-stage → 0.13.0

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { DeviceField, PaymentAdapter, PaymentErrorEntry } from "@fire-spark/payments";
+//#region src/parse.d.ts
+type SipResponse = {
+  code: string;
+  message: string;
+};
+//#endregion
+//#region src/client.d.ts
+type TokenInput = {
+  baseUrl: string;
+  codigoUnico: string;
+  usuario: string;
+  clave: string;
+};
+type SendInput = {
+  baseUrl: string;
+  codigoUnico: string;
+  id: string;
+  data: string;
+  token: string;
+};
+type LookupInput = {
+  baseUrl: string;
+  codigoUnico: string;
+  id: string;
+  token: string;
+};
+type RedebanClient = {
+  token(input: TokenInput): Promise<SipResponse>;
+  send(input: SendInput): Promise<SipResponse>;
+  response(input: LookupInput): Promise<SipResponse>;
+  erase(input: LookupInput): Promise<SipResponse>;
+};
+/** REST client. Every call is POST with an empty body and query params. */
+declare const createRedebanClient: (fetchImpl?: typeof fetch) => RedebanClient;
+//#endregion
+//#region src/errors.d.ts
+/** Anexo 4. Keys are the technical `Cod`, not the financial response. */
+declare const redebanPinPadErrors: Readonly<Record<string, PaymentErrorEntry>> & {
+  "03": PaymentErrorEntry;
+  "04": PaymentErrorEntry;
+  "05": PaymentErrorEntry;
+  "06": PaymentErrorEntry;
+  "07": PaymentErrorEntry;
+  "08": PaymentErrorEntry;
+  "09": PaymentErrorEntry;
+  "10": PaymentErrorEntry;
+  "11": PaymentErrorEntry;
+  "12": PaymentErrorEntry;
+  "14": PaymentErrorEntry;
+  "15": PaymentErrorEntry;
+  "16": PaymentErrorEntry;
+  "17": PaymentErrorEntry;
+  "18": PaymentErrorEntry;
+  "99": PaymentErrorEntry;
+};
+//#endregion
+//#region src/settings.d.ts
+declare const redebanPinPadDeviceFields: DeviceField[];
+//#endregion
+//#region src/poll.d.ts
+type PollClock = {
+  now: () => number;
+  wait: (ms: number, signal: AbortSignal) => Promise<void>;
+};
+//#endregion
+//#region src/adapter.d.ts
+type RedebanPinPadOptions = {
+  client?: RedebanClient;
+  clock?: PollClock;
+  /** Console traces. Off unless this is true. */
+  debug?: boolean;
+  /** Backend info traces. Errors are sent either way. Default on. */
+  traces?: boolean;
+  /** Clock for the trace stamps. The poll clock stays separate. */
+  now?: () => Date;
+};
+declare const redebanPinPadPayments: (options?: RedebanPinPadOptions) => PaymentAdapter;
+//#endregion
+export { type RedebanClient, type RedebanPinPadOptions, createRedebanClient, redebanPinPadDeviceFields, redebanPinPadErrors, redebanPinPadPayments };

package/dist/index.js

@@ -0,0 +1,1189 @@
+import { PaymentError, createPaymentError, definePaymentErrors, isPaymentError, toPaymentError } from "@fire-spark/payments";
+import { log, logError } from "@fire-spark/core";
+//#region src/constants.ts
+/** First four polls, then a shorter gap. Matches the KIOSCOS client. */
+const REDEBAN_POLL_INTERVALS_MS = [
+	1e4,
+	1e4,
+	1e4,
+	1e4
+];
+/** Covers both poll phases so the orchestrator does not cut at 30s. */
+const REDEBAN_TIMEOUT_MS = 37e4;
+const REDEBAN_ERROR_SOURCE = "docs/payments/redeban/pinpad.md#11-errores";
+//#endregion
+//#region src/parse.ts
+const CODE = /^Cod:\s*([^,]*)\s*,\s*Msj:\s*([\s\S]*)$/;
+/** `Cod:00,Msj:...`. The message keeps its commas. */
+const parseSipBody = (body) => {
+	const match = CODE.exec(body.trim());
+	if (!match) return null;
+	const code = match[1]?.trim() ?? "";
+	return {
+		code: /^\d{1,2}$/.test(code) ? code.padStart(2, "0") : code,
+		message: (match[2] ?? "").trim()
+	};
+};
+/** EnviarDatos success. A financial reply never starts with OK. */
+const isTechnicalOk = (message) => {
+	return message.trim().toUpperCase().startsWith("OK");
+};
+/** Respuesta finished: Cod 00 and a financial message, not a bare OK. */
+const isFinancialMessage = (message) => {
+	const text = message.trim();
+	if (!text) return false;
+	if (isTechnicalOk(text)) return false;
+	if (text.toUpperCase().startsWith("ERROR")) return false;
+	return true;
+};
+const at = (fields, index) => fields[index]?.trim() ?? "";
+/** Anexo 2, in order, taken from the `Msj` of a finished Respuesta. */
+const parseFinancial = (message) => {
+	const fields = message.split(",").map((field) => field.trim());
+	return {
+		responseCode: at(fields, 0),
+		approvalCode: at(fields, 1),
+		total: at(fields, 2),
+		iva: at(fields, 3),
+		receipt: at(fields, 4),
+		rrn: at(fields, 5),
+		terminal: at(fields, 6),
+		date: at(fields, 7),
+		time: at(fields, 8),
+		franchise: at(fields, 9),
+		accountType: at(fields, 10),
+		installments: at(fields, 11),
+		bin: at(fields, 12),
+		establishment: at(fields, 13),
+		address: at(fields, 14),
+		register: at(fields, 15),
+		cardName: at(fields, 16),
+		expiry: at(fields, 28),
+		fields
+	};
+};
+const isApprovedCode = (code) => {
+	return code === "00" || code === "0";
+};
+/** Pinpad receipt is 6 characters. */
+const padReceipt = (value) => {
+	const clean = value.trim();
+	if (!clean) return "000000";
+	return clean.padStart(6, "0").slice(-6);
+};
+const integerField = (value) => {
+	const digits = value.replace(/\D/g, "");
+	if (!digits) return null;
+	return Number(digits);
+};
+/** Last four from a masked PAN, else from the BIN field. */
+const lastFour = (financial) => {
+	const digits = (financial.fields.find((field) => field.includes("*")) || financial.bin || financial.cardName).replace(/\D/g, "");
+	if (digits.length < 4) return null;
+	return digits.slice(-4);
+};
+//#endregion
+//#region src/client.ts
+const joinUrl = (baseUrl, path) => {
+	const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+	return new URL(path.replace(/^\//, ""), base);
+};
+const post = async (fetchImpl, url) => {
+	const response = await fetchImpl(url, { method: "POST" });
+	const body = await response.text();
+	if (!response.ok) throw new Error(body || `SIPConnector HTTP ${response.status}`);
+	const parsed = parseSipBody(body);
+	if (!parsed) throw new Error("SIPConnector response has no Cod/Msj");
+	return parsed;
+};
+/** REST client. Every call is POST with an empty body and query params. */
+const createRedebanClient = (fetchImpl = fetch) => {
+	return {
+		token: (input) => {
+			const url = joinUrl(input.baseUrl, "api/Token");
+			url.searchParams.set("CodigoUnico", input.codigoUnico);
+			url.searchParams.set("Usuario", input.usuario);
+			url.searchParams.set("Clave", input.clave);
+			return post(fetchImpl, url);
+		},
+		send: (input) => {
+			const url = joinUrl(input.baseUrl, "api/EnviarDatos");
+			url.searchParams.set("CodigoUnico", input.codigoUnico);
+			url.searchParams.set("IdTransaccion", input.id);
+			url.searchParams.set("Data", input.data);
+			url.searchParams.set("token", input.token);
+			url.searchParams.set("Sobreescribir", "S");
+			url.searchParams.set("Red", "0");
+			return post(fetchImpl, url);
+		},
+		response: (input) => {
+			const url = joinUrl(input.baseUrl, "api/Respuesta");
+			url.searchParams.set("CodigoUnico", input.codigoUnico);
+			url.searchParams.set("IdTransaccion", input.id);
+			url.searchParams.set("token", input.token);
+			url.searchParams.set("Red", "0");
+			return post(fetchImpl, url);
+		},
+		erase: (input) => {
+			const url = joinUrl(input.baseUrl, "api/Borrar");
+			url.searchParams.set("CodigoUnico", input.codigoUnico);
+			url.searchParams.set("IdTransaccion", input.id);
+			url.searchParams.set("Token", input.token);
+			url.searchParams.set("Red", "0");
+			return post(fetchImpl, url);
+		}
+	};
+};
+//#endregion
+//#region src/errors.ts
+const entry = (code, message, retryable = false) => {
+	return {
+		code,
+		message,
+		retryable,
+		source: REDEBAN_ERROR_SOURCE,
+		since: "1.5"
+	};
+};
+/** Anexo 4. Keys are the technical `Cod`, not the financial response. */
+const redebanPinPadErrors = definePaymentErrors({
+	"03": entry("INVALID_REQUEST", "Incorrect parameters"),
+	"04": entry("INVALID_CREDENTIALS", "Token is not valid", true),
+	"05": entry("INVALID_REQUEST", "Transaction id is incorrect"),
+	"06": entry("TERMINAL_BUSY", "Terminal already has a transaction", true),
+	"07": entry("INVALID_CREDENTIALS", "Unique code is invalid"),
+	"08": entry("INVALID_REQUEST", "Incomplete data structure"),
+	"09": entry("INVALID_REQUEST", "Transaction id already exists"),
+	"10": entry("PROVIDER_UNAVAILABLE", "Could not insert the transaction", true),
+	"11": entry("PROVIDER_UNAVAILABLE", "Could not insert the transaction", true),
+	"12": entry("INVALID_REQUEST", "Structure or LRC error"),
+	"14": entry("PROVIDER_UNAVAILABLE", "Internal process error", true),
+	"15": entry("INVALID_CREDENTIALS", "Token data is invalid", true),
+	"16": entry("INVALID_CREDENTIALS", "Authentication failed"),
+	"17": entry("UNKNOWN", "Record to delete was not found"),
+	"18": entry("INVALID_REQUEST", "Transaction is already resolved"),
+	"99": entry("PROVIDER_UNAVAILABLE", "Technical error", true)
+});
+//#endregion
+//#region src/settings.ts
+const redebanPinPadDeviceFields = [
+	{
+		key: "terminal_id",
+		label: "Terminal code",
+		type: "text",
+		required: true
+	},
+	{
+		key: "register_number",
+		label: "Register number",
+		type: "text",
+		required: true
+	},
+	{
+		key: "cashier_code",
+		label: "Cashier code",
+		type: "text",
+		required: true
+	}
+];
+const text = (value) => {
+	return typeof value === "string" ? value.trim() : "";
+};
+const clip$1 = (value, max) => value.slice(0, max);
+/** Merchant keys live on `config`. Terminal keys live on the device. */
+const readRedebanSettings = (config, device) => {
+	const baseUrl = text(config.base_url);
+	const codigoUnico = text(config.codigo_unico);
+	const usuario = text(config.usuario);
+	const clave = text(config.secret_clave);
+	const supervisorPassword = text(config.secret_supervisor_password);
+	const terminalId = text(device.terminal_id);
+	const registerNumber = text(device.register_number);
+	const cashierCode = text(device.cashier_code);
+	const missing = [
+		["base_url", baseUrl],
+		["codigo_unico", codigoUnico],
+		["usuario", usuario],
+		["secret_clave", clave],
+		["secret_supervisor_password", supervisorPassword],
+		["terminal_id", terminalId],
+		["register_number", registerNumber],
+		["cashier_code", cashierCode]
+	].filter(([, value]) => !value).map(([key]) => key);
+	if (missing.length) return {
+		ok: false,
+		missing
+	};
+	return {
+		ok: true,
+		settings: {
+			baseUrl,
+			codigoUnico,
+			usuario,
+			clave,
+			supervisorPassword,
+			terminalId: clip$1(terminalId, 10),
+			registerNumber: clip$1(registerNumber, 10),
+			cashierCode: clip$1(cashierCode, 10)
+		}
+	};
+};
+//#endregion
+//#region src/trace.ts
+/** One in-call trace. Discarded when the operation is not reported. */
+const DETAIL_MAX = 2e3;
+const MARK = "\n…\n";
+/** 14–19 digits. Amounts, dates and short ids stay as-is. */
+const PAN = /\d{14,19}/g;
+/** Track 1/2 sentinels. The payload is not a field we record on purpose. */
+const TRACK = /[%;][\dA-Za-z=^]{12,}/g;
+/** Query values that can carry the service key, the token or the frame. */
+const SECRET_QUERY = /([?&](?:Clave|token|Token|Data)=)[^&\s"')]+/gi;
+const pad = (value, width) => {
+	return String(value).padStart(width, "0");
+};
+/** Local kiosk time of the step, not the time the log is posted. */
+const redebanStamp = (date) => {
+	return `${pad(date.getHours(), 2)}:${pad(date.getMinutes(), 2)}:${pad(date.getSeconds(), 2)}.${pad(date.getMilliseconds(), 3)}`;
+};
+/** PAN and track data only. Amounts and short ids stay. */
+const maskCardData = (value) => {
+	return value.replace(TRACK, "<track>").replace(PAN, (digits) => {
+		return `************${digits.slice(-4)}`;
+	});
+};
+/** PAN, track data, and secrets that arrived inside a URL. */
+const redactSecrets = (value) => {
+	return maskCardData(value).replace(SECRET_QUERY, "$1<redacted>");
+};
+/** Keeps the start and the end when `detail` would pass 2000 characters. */
+const fitDetail = (text) => {
+	if (text.length <= DETAIL_MAX) return text;
+	const head = Math.ceil((DETAIL_MAX - 3) / 2);
+	return `${text.slice(0, head)}${MARK}${text.slice(-998)}`;
+};
+const createRedebanTrace = (now = () => /* @__PURE__ */ new Date()) => {
+	const lines = [];
+	const push = (body) => {
+		const stamp = redebanStamp(now());
+		lines.push(`${stamp} ${redactSecrets(body)}`);
+	};
+	return {
+		call: (body) => push(`→ ${body}`),
+		result: (body) => push(`← ${body}`),
+		note: (body) => push(body),
+		detail: () => fitDetail(lines.join("\n"))
+	};
+};
+//#endregion
+//#region src/debug.ts
+const TAG = "[REDEBAN_DEBUG]";
+/** Keys whose values are a token, a password, or the raw SIP message. */
+const HIDDEN = /* @__PURE__ */ new Set([
+	"message",
+	"token",
+	"clave",
+	"data",
+	"password",
+	"supervisorPassword",
+	"secret",
+	"secret_clave",
+	"secret_supervisor_password",
+	"Msj",
+	"Clave",
+	"Token",
+	"Data"
+]);
+let enabled = false;
+const elapsed = (startedAt) => Date.now() - startedAt;
+const safe = (value) => {
+	if (typeof value === "string") return redactSecrets(value);
+	if (value instanceof Map) return safe(Object.fromEntries(value));
+	if (value instanceof Error) {
+		const code = value.code;
+		const message = redactSecrets(value.message);
+		return {
+			name: value.name,
+			message,
+			code
+		};
+	}
+	if (Array.isArray(value)) return value.map((item) => safe(item));
+	if (!value || typeof value !== "object") return value;
+	const out = {};
+	for (const [name, item] of Object.entries(value)) {
+		if (HIDDEN.has(name)) continue;
+		out[name] = safe(item);
+	}
+	return out;
+};
+/** Turns console traces on or off. Default is off. */
+const setRedebanLogs = (value) => {
+	enabled = value;
+};
+/** Logs one step: `[REDEBAN_DEBUG] scope › event { data }`. */
+const redebanDebug = (scope, event, data) => {
+	if (!enabled) return;
+	const time = (/* @__PURE__ */ new Date()).toISOString();
+	const line = `${scope} › ${event}`;
+	if (data === void 0) {
+		console.log(TAG, time, line);
+		return;
+	}
+	console.log(TAG, time, line, safe(data));
+};
+/** Logs the input, the output or the error, and the duration of a call. */
+const redebanDebugCall = async (scope, input, call) => {
+	const startedAt = Date.now();
+	redebanDebug(scope, "→ in", input);
+	try {
+		const output = await call();
+		const ms = elapsed(startedAt);
+		redebanDebug(scope, "← out", {
+			output,
+			ms
+		});
+		return output;
+	} catch (error) {
+		const ms = elapsed(startedAt);
+		redebanDebug(scope, "✕ error", {
+			error,
+			ms
+		});
+		throw error;
+	}
+};
+//#endregion
+//#region src/frame.ts
+const clip = (value, max) => value.trim().slice(0, max);
+/** Integer pesos. SIPConnector rejects separators and decimals. */
+const pesos = (value) => {
+	if (!Number.isFinite(value)) return "0";
+	return String(Math.round(value));
+};
+const shared = (input) => {
+	const amount = pesos(input.amount);
+	const iva = pesos(input.iva);
+	const invoice = clip(input.invoice, 10);
+	const head = [
+		amount,
+		iva,
+		"0",
+		"0",
+		amount,
+		invoice
+	];
+	const tail = [
+		clip(input.cashierCode, 10),
+		"0",
+		"0",
+		"0",
+		clip(input.terminalId, 10),
+		clip(input.registerNumber, 10)
+	];
+	return {
+		amount,
+		iva,
+		invoice,
+		fields: [...head, ...tail]
+	};
+};
+/** Compra, Anexo 1.1. Twenty fields. Multicommerce repeats the unique code. */
+const saleFrame = (input) => {
+	const { invoice, fields } = shared(input);
+	const codigo = clip(input.codigoUnico, 10);
+	const rest = [
+		"0",
+		"0",
+		invoice,
+		"3"
+	];
+	const end = [
+		"N",
+		codigo,
+		" "
+	];
+	return [
+		"0",
+		...fields,
+		...rest,
+		...end
+	].join(",");
+};
+/**
+* Anulación total, Anexo 1.2. Eighteen fields.
+* Without multicommerce the last field stays empty.
+*/
+const voidFrame = (input) => {
+	const { fields } = shared(input);
+	const rest = [
+		padReceipt(input.receipt),
+		clip(input.supervisorPassword, 4),
+		"3"
+	];
+	const end = ["N", ""];
+	return [
+		"1",
+		...fields,
+		...rest,
+		...end
+	].join(",");
+};
+//#endregion
+//#region src/metadata.ts
+const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+/** SIPConnector ids are 1 to 10 alphanumeric characters. */
+const transactionId = (attemptReference) => {
+	const clean = attemptReference.replace(/[^0-9A-Za-z]/g, "");
+	if (clean.length >= 1 && clean.length <= 10) return clean;
+	let hash = 2166136261;
+	for (let i = 0; i < attemptReference.length; i += 1) {
+		hash ^= attemptReference.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	let value = hash >>> 0;
+	let out = "";
+	for (let i = 0; i < 10; i += 1) {
+		out += ALPHABET[value % 62] ?? "0";
+		value = Math.floor(value / 62);
+		value += hash >>> i % 16;
+	}
+	return out.slice(0, 10);
+};
+const ivaOf = (taxes) => {
+	const sum = taxes.reduce((total, tax) => total + tax.tax, 0);
+	return Number(pesos(sum));
+};
+const cardTypeOf = (account) => {
+	if (account === "CR") return "CREDIT";
+	if (account === "AH" || account === "CC") return "DEBIT";
+	return null;
+};
+const providerOf = (snapshot, financial) => {
+	const base = {
+		id_transaccion: snapshot.id,
+		valor_venta: snapshot.amount,
+		valor_iva: snapshot.iva,
+		valor_total: snapshot.total,
+		numero_recibo: snapshot.receipt
+	};
+	if (!financial) return base;
+	return {
+		...base,
+		codigo_respuesta: financial.responseCode,
+		codigo_aprobacion: financial.approvalCode,
+		rrn: financial.rrn,
+		numero_recibo: financial.receipt || snapshot.receipt,
+		raw_message: financial.fields.join(",")
+	};
+};
+const paymentOf = (financial) => {
+	const count = integerField(financial.installments) ?? 0;
+	const installments = count > 0 ? {
+		count,
+		type: null
+	} : null;
+	const date = financial.date ? `20${financial.date}` : null;
+	return {
+		provider_transaction_id: financial.approvalCode || null,
+		authorization_code: financial.approvalCode || null,
+		reference: financial.rrn || null,
+		card_type: cardTypeOf(financial.accountType),
+		brand: financial.franchise || null,
+		last4: lastFour(financial),
+		installments,
+		terminal_id: financial.terminal || null,
+		merchant_id: financial.establishment || null,
+		ticket_number: financial.receipt || null,
+		transaction_date: date,
+		account_type: financial.accountType || null
+	};
+};
+const snapshotOf = (result) => {
+	const provider = result.metadata.provider;
+	if (!provider) return null;
+	const id = provider.id_transaccion;
+	const amount = provider.valor_venta;
+	const iva = provider.valor_iva;
+	const total = provider.valor_total;
+	const receipt = provider.numero_recibo;
+	if (typeof id !== "string" || !id) return null;
+	if (typeof amount !== "number" || typeof iva !== "number") return null;
+	if (typeof total !== "number") return null;
+	return {
+		id,
+		amount,
+		iva,
+		total,
+		receipt: typeof receipt === "string" ? receipt : ""
+	};
+};
+const metadataOf = (attemptReference, snapshot, financial) => {
+	const provider = providerOf(snapshot, financial);
+	return {
+		attempt_reference: attemptReference,
+		payment: financial ? paymentOf(financial) : void 0,
+		provider
+	};
+};
+//#endregion
+//#region src/poll.ts
+const defaultPollClock = () => {
+	return {
+		now: () => Date.now(),
+		wait: (ms, signal) => {
+			return new Promise((resolve) => {
+				if (signal.aborted) {
+					resolve();
+					return;
+				}
+				const onAbort = () => {
+					clearTimeout(timer);
+					resolve();
+				};
+				const timer = setTimeout(() => {
+					signal.removeEventListener("abort", onAbort);
+					resolve();
+				}, ms);
+				signal.addEventListener("abort", onAbort, { once: true });
+			});
+		}
+	};
+};
+const intervalAt = (index) => {
+	return REDEBAN_POLL_INTERVALS_MS[index] ?? 5e3;
+};
+/**
+* Polls Respuesta. Cod 01 or 02 refreshes the token and resets the
+* deadline once. Cod 02 ignores abort: the card is already in the pinpad.
+*/
+const pollRespuesta = async (input) => {
+	const { client, settings, id, signal, clock, refreshToken, trace } = input;
+	let token = input.token;
+	let start = clock.now();
+	let reset = false;
+	let last = "";
+	let seen = "";
+	let polls = 0;
+	const lookup = () => {
+		const baseUrl = settings.baseUrl;
+		const codigoUnico = settings.codigoUnico;
+		return client.response({
+			baseUrl,
+			codigoUnico,
+			id,
+			token
+		});
+	};
+	while (true) {
+		const waiting = last === "" || last === "00" || last === "01";
+		if (signal.aborted && waiting) return {
+			kind: "cancelled",
+			token
+		};
+		const response = await redebanDebugCall("redeban.poll", {
+			id,
+			index: polls
+		}, async () => {
+			const body = await lookup();
+			const done = body.code === "00" && isFinancialMessage(body.message);
+			const length = body.message.length;
+			return {
+				...body,
+				financial: done,
+				length
+			};
+		});
+		if (response.code !== seen) {
+			trace?.result(`respuesta ${response.code}`);
+			seen = response.code;
+		}
+		last = response.code;
+		if (response.code === "04") {
+			trace?.note("token refresh");
+			token = await refreshToken(true);
+			continue;
+		}
+		if (response.code === "01" || response.code === "02") {
+			token = await refreshToken(false);
+			if (!reset) {
+				reset = true;
+				start = clock.now();
+			}
+		} else if (response.code === "00" && isFinancialMessage(response.message)) return {
+			kind: "done",
+			message: response.message,
+			token
+		};
+		else if (response.code !== "00") return {
+			kind: "technical",
+			response,
+			token
+		};
+		if (clock.now() - start >= 184e3) return {
+			kind: "timeout",
+			started: reset,
+			token,
+			last
+		};
+		await clock.wait(intervalAt(polls), signal);
+		polls += 1;
+	}
+};
+//#endregion
+//#region src/report.ts
+/** Reports one pinpad step to the merchant dashboard. */
+const CHARGE_DID_NOT_START = "Redeban charge did not start";
+const CHARGE_DECLINED = "Redeban charge declined";
+const CHARGE_DID_NOT_FINISH = "Redeban charge did not finish";
+const VOID_DECLINED = "Redeban void declined";
+const VOID_DID_NOT_FINISH = "Redeban void did not finish";
+const redactedCause = (error) => {
+	if (error instanceof Error) {
+		const cause = new Error(redactSecrets(error.message));
+		cause.name = error.name;
+		if (error.stack) cause.stack = redactSecrets(error.stack);
+		return cause;
+	}
+	if (typeof error === "string") return redactSecrets(error);
+	return error;
+};
+/** Fixed phrase as the message. The thrown value keeps its name and stack. */
+const reportedError = (message, error) => {
+	const wrapped = new Error(message);
+	const cause = redactedCause(error);
+	if (cause instanceof Error) {
+		wrapped.name = cause.name;
+		if (cause.stack) wrapped.stack = cause.stack;
+	}
+	wrapped.cause = cause;
+	return wrapped;
+};
+/** One backend log. `info` is skipped when `traces` is off. Never throws. */
+const reportRedeban = (input) => {
+	if (input.level === "info" && !input.traces) return;
+	const options = {
+		alias: input.alias,
+		status: input.status,
+		detail: input.detail
+	};
+	if (!(input.level === "error" && input.error != null)) {
+		log(input.level, input.message, options);
+		return;
+	}
+	logError(reportedError(input.message, input.error), options);
+};
+const statusOf = (result) => {
+	const code = result.error?.code;
+	if (!code) return "failed";
+	return code.toLowerCase();
+};
+const send = (input, level, alias, status, message) => {
+	const thrown = level === "error" ? input.thrown : void 0;
+	reportRedeban({
+		level,
+		alias,
+		status,
+		message,
+		detail: input.trace.detail(),
+		traces: input.traces,
+		error: thrown
+	});
+};
+const reportCharge = (input) => {
+	const { result, opened } = input;
+	if (result.status === "PAID") return;
+	const cancelled = result.status === "CANCELLED";
+	const declined = result.error?.code === "CARD_DECLINED";
+	if (cancelled || declined) {
+		send(input, "info", "redeban.charge", "declined", CHARGE_DECLINED);
+		return;
+	}
+	const message = opened ? CHARGE_DID_NOT_FINISH : CHARGE_DID_NOT_START;
+	send(input, "error", "redeban.charge", statusOf(result), message);
+};
+const reportQuery = (input) => {
+	const { result } = input;
+	if (result.status === "PAID") return;
+	if (result.error?.code === "AMBIGUOUS") return;
+	if (result.error?.code === "CARD_DECLINED") {
+		send(input, "info", "redeban.charge", "declined", CHARGE_DECLINED);
+		return;
+	}
+	const status = statusOf(result);
+	send(input, "error", "redeban.charge", status, CHARGE_DID_NOT_FINISH);
+};
+const reportVoid = (input) => {
+	const { result, wasPaid } = input;
+	if (result.status === "CANCELLED") return;
+	if (wasPaid && result.error?.code === "CARD_DECLINED") {
+		send(input, "info", "redeban.void", "declined", VOID_DECLINED);
+		return;
+	}
+	const status = statusOf(result);
+	send(input, "error", "redeban.void", status, VOID_DID_NOT_FINISH);
+};
+/** Decides the single backend log for one adapter call. Success stays quiet. */
+const reportOperation = (input) => {
+	if (input.kind === "charge") {
+		reportCharge(input);
+		return;
+	}
+	if (input.kind === "query") {
+		reportQuery(input);
+		return;
+	}
+	reportVoid(input);
+};
+//#endregion
+//#region src/adapter.ts
+const baseResult = (ctx, amount, snapshot, extra = {}) => {
+	const reference = ctx.attemptReference;
+	return {
+		status: "FAILED",
+		amount,
+		metadata: snapshot ? metadataOf(reference, snapshot) : { attempt_reference: reference },
+		...extra
+	};
+};
+const withError = (ctx, amount, snapshot, error, needsReview = false) => {
+	const result = baseResult(ctx, amount, snapshot);
+	const review = needsReview ? { needs_review: true } : {};
+	const metadata = {
+		...result.metadata,
+		error,
+		...review
+	};
+	return {
+		...result,
+		metadata,
+		error
+	};
+};
+const technicalError = (ctx, response) => {
+	return toPaymentError(redebanPinPadErrors, {
+		code: response.code,
+		message: response.message,
+		attempt: ctx.attempt,
+		fallback: "UNKNOWN"
+	});
+};
+const loggedSettings = (settings) => {
+	return {
+		baseUrl: settings.baseUrl,
+		codigoUnico: settings.codigoUnico,
+		usuario: settings.usuario,
+		terminalId: settings.terminalId,
+		registerNumber: settings.registerNumber,
+		cashierCode: settings.cashierCode
+	};
+};
+const issueToken = async (client, settings, ctx, trace) => {
+	const baseUrl = settings.baseUrl;
+	const codigoUnico = settings.codigoUnico;
+	const usuario = settings.usuario;
+	const clave = settings.clave;
+	const shown = {
+		codigoUnico,
+		usuario
+	};
+	trace?.call("token");
+	try {
+		const response = await redebanDebugCall("redeban.token", shown, () => {
+			return client.token({
+				baseUrl,
+				codigoUnico,
+				usuario,
+				clave
+			});
+		});
+		if (response.code === "00" && response.message) {
+			trace?.result("token 00");
+			return {
+				ok: true,
+				token: response.message
+			};
+		}
+		trace?.result(`token ${response.code}`);
+		return {
+			ok: false,
+			error: technicalError(ctx, response)
+		};
+	} catch (error) {
+		trace?.result("token error");
+		throw error;
+	}
+};
+const erase = async (client, settings, id, token, trace) => {
+	const baseUrl = settings.baseUrl;
+	const codigoUnico = settings.codigoUnico;
+	trace.call(`borrar id=${id}`);
+	try {
+		const response = await redebanDebugCall("redeban.erase", { id }, () => {
+			return client.erase({
+				baseUrl,
+				codigoUnico,
+				id,
+				token
+			});
+		});
+		trace.result(`borrar ${response.code}`);
+	} catch {
+		trace.result("borrar error");
+	}
+};
+const noteFinancial = (trace, message) => {
+	const financial = parseFinancial(message);
+	const code = `code=${financial.responseCode}`;
+	const total = `total=${financial.total}`;
+	const receipt = `receipt=${financial.receipt}`;
+	const rrn = `rrn=${financial.rrn}`;
+	trace.note(`financial ${code} ${total} ${receipt} ${rrn}`);
+	return financial;
+};
+const finishFinancial = (ctx, amount, snapshot, message, trace) => {
+	const financial = noteFinancial(trace, message);
+	const next = {
+		...snapshot,
+		receipt: financial.receipt || snapshot.receipt
+	};
+	const metadata = metadataOf(ctx.attemptReference, next, financial);
+	if (!isApprovedCode(financial.responseCode)) {
+		const error = toPaymentError(redebanPinPadErrors, {
+			code: financial.responseCode,
+			message: "Card declined",
+			attempt: ctx.attempt,
+			fallback: "CARD_DECLINED"
+		});
+		return {
+			status: "FAILED",
+			amount,
+			metadata: {
+				...metadata,
+				error
+			},
+			error
+		};
+	}
+	const approved = integerField(financial.total);
+	if (approved !== amount) {
+		trace.note(`amount order=${amount} approved=${approved}`);
+		const error = createPaymentError("INVALID_REQUEST", {
+			message: "Approved amount does not match the order",
+			attempt: ctx.attempt
+		});
+		return {
+			status: "FAILED",
+			amount,
+			metadata: {
+				...metadata,
+				error,
+				needs_review: true
+			},
+			error
+		};
+	}
+	const payment = metadata.payment;
+	return {
+		status: "PAID",
+		amount,
+		metadata: {
+			...metadata,
+			payment
+		}
+	};
+};
+const finishPoll = async (ctx, client, settings, amount, snapshot, polled, trace) => {
+	if (polled.kind === "cancelled") {
+		await erase(client, settings, snapshot.id, polled.token, trace);
+		const error = createPaymentError("CANCELLED_BY_USER", { attempt: ctx.attempt });
+		return {
+			...withError(ctx, amount, snapshot, error),
+			status: "CANCELLED"
+		};
+	}
+	if (polled.kind === "timeout") {
+		const started = polled.started ? "yes" : "no";
+		trace.note(`timeout started=${started} last=${polled.last}`);
+		if (!polled.started) await erase(client, settings, snapshot.id, polled.token, trace);
+		const error = createPaymentError(polled.started ? "AMBIGUOUS" : "TIMEOUT", { attempt: ctx.attempt });
+		const result = withError(ctx, amount, snapshot, error, polled.started);
+		const provider = {
+			...result.metadata.provider,
+			last_code: polled.last
+		};
+		const metadata = {
+			...result.metadata,
+			provider
+		};
+		return {
+			...result,
+			metadata
+		};
+	}
+	if (polled.kind === "technical") {
+		const error = technicalError(ctx, polled.response);
+		return withError(ctx, amount, snapshot, error);
+	}
+	return finishFinancial(ctx, amount, snapshot, polled.message, trace);
+};
+const redebanPinPadPayments = (options = {}) => {
+	setRedebanLogs(options.debug === true);
+	const traces = options.traces !== false;
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	const client = options.client ?? createRedebanClient();
+	const clock = options.clock ?? defaultPollClock();
+	const refresh = async (settings, ctx, trace) => {
+		const issued = await issueToken(client, settings, ctx, trace);
+		if (!issued.ok) throw new PaymentError(issued.error);
+		return issued.token;
+	};
+	const poll = (ctx, settings, id, token, trace) => {
+		const signal = ctx.signal;
+		const refreshToken = (record) => {
+			return refresh(settings, ctx, record ? trace : void 0);
+		};
+		return pollRespuesta({
+			client,
+			settings,
+			id,
+			token,
+			signal,
+			clock,
+			refreshToken,
+			trace
+		});
+	};
+	const runLogged = async (scope, ctx, amount, snapshot, trace, kind, opened, wasPaid, run) => {
+		let thrown;
+		let result;
+		try {
+			result = await run();
+		} catch (error) {
+			thrown = error;
+			trace.result("error");
+			if (isPaymentError(error)) result = withError(ctx, amount, snapshot, error.error);
+			else {
+				const network = createPaymentError("NETWORK_ERROR", {
+					message: error instanceof Error ? error.message : "Network error",
+					attempt: ctx.attempt
+				});
+				result = withError(ctx, amount, snapshot, network);
+			}
+		}
+		const code = result.error?.code ?? null;
+		redebanDebug(scope, "outcome", {
+			status: result.status,
+			code
+		});
+		reportOperation({
+			kind,
+			traces,
+			trace,
+			result,
+			opened: opened(),
+			wasPaid,
+			thrown
+		});
+		return result;
+	};
+	const readSettings = (ctx, trace) => {
+		const read = readRedebanSettings(ctx.config, ctx.deviceSettings);
+		if (!read.ok) {
+			const message = read.missing.join(", ");
+			trace.note(`missing ${message}`);
+			redebanDebug("redeban.settings", "missing", { missing: read.missing });
+			return {
+				ok: false,
+				error: createPaymentError("TERMINAL_NOT_CONFIGURED", {
+					message,
+					attempt: ctx.attempt
+				})
+			};
+		}
+		redebanDebug("redeban.settings", "read", loggedSettings(read.settings));
+		return {
+			ok: true,
+			settings: read.settings
+		};
+	};
+	const start = (ctx) => {
+		const amount = Math.round(ctx.amount.value);
+		const trace = createRedebanTrace(now);
+		const state = { opened: false };
+		trace.note(`reference=${ctx.attemptReference}`);
+		return runLogged("redeban.start", ctx, amount, null, trace, "charge", () => state.opened, false, async () => {
+			const read = readSettings(ctx, trace);
+			if (!read.ok) return withError(ctx, amount, null, read.error);
+			const { settings } = read;
+			ctx.ui.message({
+				text: "Present the card on the pinpad",
+				kind: "waiting"
+			});
+			const issued = await issueToken(client, settings, ctx, trace);
+			if (!issued.ok) return withError(ctx, amount, null, issued.error);
+			const id = transactionId(ctx.attemptReference);
+			const iva = ivaOf(ctx.taxes);
+			const invoice = id;
+			const cashierCode = settings.cashierCode;
+			const terminalId = settings.terminalId;
+			const registerNumber = settings.registerNumber;
+			const codigoUnico = settings.codigoUnico;
+			const frame = {
+				amount,
+				iva,
+				invoice,
+				cashierCode,
+				terminalId,
+				registerNumber,
+				codigoUnico
+			};
+			const snapshot = {
+				id,
+				amount,
+				iva,
+				total: amount,
+				receipt: id
+			};
+			const reference = ctx.attemptReference;
+			const sale = `id=${id} amount=${amount}`;
+			const who = `reference=${reference} terminal=${terminalId}`;
+			trace.call(`enviar ${sale} ${who}`);
+			const sent = await redebanDebugCall("redeban.send", { id }, () => {
+				return client.send({
+					baseUrl: settings.baseUrl,
+					codigoUnico,
+					id,
+					data: saleFrame(frame),
+					token: issued.token
+				});
+			});
+			trace.result(`enviar ${sent.code}`);
+			if (sent.code !== "00") return withError(ctx, amount, snapshot, technicalError(ctx, sent));
+			state.opened = true;
+			const polled = await poll(ctx, settings, id, issued.token, trace);
+			return finishPoll(ctx, client, settings, amount, snapshot, polled, trace);
+		});
+	};
+	const query = (ctx, result) => {
+		const amount = result.amount;
+		const snapshot = snapshotOf(result);
+		const trace = createRedebanTrace(now);
+		trace.note(`reference=${ctx.attemptReference}`);
+		return runLogged("redeban.query", ctx, amount, snapshot, trace, "query", () => false, false, async () => {
+			if (!snapshot) {
+				trace.note("missing id");
+				const error = createPaymentError("INVALID_REQUEST", {
+					attempt: ctx.attempt,
+					message: "Missing transaction id"
+				});
+				return withError(ctx, amount, null, error);
+			}
+			const read = readSettings(ctx, trace);
+			if (!read.ok) return withError(ctx, amount, snapshot, read.error);
+			const token = await refresh(read.settings, ctx, trace);
+			const id = snapshot.id;
+			trace.call(`query id=${id}`);
+			const response = await redebanDebugCall("redeban.query", { id }, () => {
+				return client.response({
+					baseUrl: read.settings.baseUrl,
+					codigoUnico: read.settings.codigoUnico,
+					id,
+					token
+				});
+			});
+			trace.result(`respuesta ${response.code}`);
+			const moving = response.code === "00" || response.code === "01" || response.code === "02";
+			const financial = isFinancialMessage(response.message);
+			if (response.code === "00" && financial) return finishFinancial(ctx, amount, snapshot, response.message, trace);
+			if (moving) {
+				trace.note(`pending ${response.code}`);
+				const error = createPaymentError("AMBIGUOUS", { attempt: ctx.attempt });
+				return withError(ctx, amount, snapshot, error, true);
+			}
+			return withError(ctx, amount, snapshot, technicalError(ctx, response));
+		});
+	};
+	const cancel = (ctx, result) => {
+		const amount = result.amount;
+		const snapshot = snapshotOf(result);
+		const wasPaid = result.status === "PAID";
+		const trace = createRedebanTrace(now);
+		trace.note(`reference=${ctx.attemptReference}`);
+		return runLogged("redeban.cancel", ctx, amount, snapshot, trace, "void", () => false, wasPaid, async () => {
+			const read = readSettings(ctx, trace);
+			if (!read.ok || !snapshot) {
+				trace.note("reversal not allowed");
+				const error = createPaymentError("REVERSAL_NOT_ALLOWED", { attempt: ctx.attempt });
+				return withError(ctx, amount, snapshot, error);
+			}
+			const { settings } = read;
+			if (result.status !== "PAID") {
+				if (result.metadata.provider?.last_code === "02") {
+					trace.note("last=02");
+					const error = createPaymentError("AMBIGUOUS", { attempt: ctx.attempt });
+					return withError(ctx, amount, snapshot, error, true);
+				}
+				const token = await refresh(settings, ctx, trace);
+				await erase(client, settings, snapshot.id, token, trace);
+				const error = createPaymentError("CANCELLED_BY_USER", { attempt: ctx.attempt });
+				return {
+					...withError(ctx, amount, snapshot, error),
+					status: "CANCELLED"
+				};
+			}
+			const id = transactionId(`${snapshot.id}V`);
+			const receipt = snapshot.receipt;
+			const voidAmount = snapshot.amount;
+			const frame = {
+				amount: snapshot.amount,
+				iva: snapshot.iva,
+				invoice: id,
+				cashierCode: settings.cashierCode,
+				terminalId: settings.terminalId,
+				registerNumber: settings.registerNumber,
+				codigoUnico: settings.codigoUnico,
+				receipt: snapshot.receipt,
+				supervisorPassword: settings.supervisorPassword
+			};
+			const token = await refresh(settings, ctx, trace);
+			const voidLine = `id=${id} receipt=${receipt} amount=${voidAmount}`;
+			trace.call(`void ${voidLine}`);
+			const sent = await redebanDebugCall("redeban.send", { id }, () => {
+				return client.send({
+					baseUrl: settings.baseUrl,
+					codigoUnico: settings.codigoUnico,
+					id,
+					data: voidFrame(frame),
+					token
+				});
+			});
+			trace.result(`enviar ${sent.code}`);
+			if (sent.code !== "00") return withError(ctx, amount, snapshot, technicalError(ctx, sent));
+			const polled = await poll(ctx, settings, id, token, trace);
+			const done = await finishPoll(ctx, client, settings, amount, snapshot, polled, trace);
+			if (done.status !== "PAID") return done;
+			return {
+				...done,
+				status: "CANCELLED"
+			};
+		});
+	};
+	return {
+		provider: "redeban",
+		method: "PIN_PAD",
+		deviceFields: redebanPinPadDeviceFields,
+		errors: redebanPinPadErrors,
+		capabilities: {
+			deferredCapture: false,
+			inPerson: true
+		},
+		policy: { timeout_ms: REDEBAN_TIMEOUT_MS },
+		reversalFor: () => "cancel",
+		start,
+		query,
+		cancel
+	};
+};
+//#endregion
+export { createRedebanClient, redebanPinPadDeviceFields, redebanPinPadErrors, redebanPinPadPayments };

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@fire-spark/payments-redeban-pinpad",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.13.0",
+  "description": "Fire Spark Redeban pinpad adapter. SIPConnector V1.5 sale, full void, polling and delete.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@fire-spark/core": "^0.13.0",
+    "@fire-spark/payments": "^0.13.0",
+    "@fire-spark/types": "^0.13.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "tsdown": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "platform": "neutral",
+    "dts": {
+      "tsconfig": "tsconfig.build.json"
+    },
+    "clean": true,
+    "deps": {
+      "neverBundle": [
+        "@fire-spark/core",
+        "@fire-spark/payments",
+        "@fire-spark/types"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "check-types": "tsc --noEmit",
+    "test:utils": "vitest run",
+    "lint": "oxlint ./src --max-warnings=0",
+    "format": "oxfmt ./src",
+    "check-format": "oxfmt --check ./src"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.