@fire-spark/payments-clisitef-pinpad-rn 0.0.0-stage → 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+import { DeviceField, PaymentAdapter, PaymentAdapterCapabilities, PaymentErrorEntry, PaymentMetadata, PaymentStorage, PaymentUI, StandardPaymentError } from "@fire-spark/payments";
+import { CLISITEF_MODALITY, ClisitefClient, ClisitefConfigureParams, ClisitefFinishParams, ClisitefStartParams } from "@fire-spark/payments-clisitef-client";
+import { TenderDetails } from "@fire-spark/types";
+//#region src/adapter.d.ts
+/** Confirmed in the act (`finishTransaction(1)`), never captured later. */
+declare const clisitefPinPadCapabilities: PaymentAdapterCapabilities;
+type ClisitefPinPadOptions = {
+  /** Defaults to the shared client bound to the native module. */
+  client?: ClisitefClient;
+  /**
+   * Device-wide storage for the pending-transaction record. Defaults to
+   * `ctx.storage`, which is scoped per payment: a transaction left open by
+   * the DEBIT payment is then not seen by the CREDIT one.
+   */
+  storage?: PaymentStorage;
+  /** Store time zone for the fiscal date; defaults to `America/Sao_Paulo`. */
+  timeZone?: string;
+  now?: () => Date;
+  confirmationTimeoutMs?: 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).
+ */
+declare const clisitefPinPadPayments: (options?: ClisitefPinPadOptions) => PaymentAdapter;
+//#endregion
+//#region src/constants.d.ts
+/**
+ * `onData` commands handled by the adapter (Fiserv "Tabela de códigos de
+ * comando"). Not handled, so they abort the transaction: 29 (silent field),
+ * 31 (check), 35 (barcode), 42 (identified menu, only with
+ * `ItemMenuIdentificado`) and 50/51 (QR, PIX only).
+ */
+declare const CLISITEF_COMMAND: {
+  readonly STORE_FIELD: 0;
+  readonly MESSAGE_OPERATOR: 1;
+  readonly MESSAGE_CUSTOMER: 2;
+  readonly MESSAGE_BOTH: 3;
+  readonly MENU_TITLE: 4;
+  readonly CLEAR_OPERATOR: 11;
+  readonly CLEAR_CUSTOMER: 12;
+  readonly CLEAR_BOTH: 13;
+  readonly CLEAR_MENU_TITLE: 14;
+  readonly HEADER: 15;
+  readonly CLEAR_HEADER: 16;
+  readonly CONFIRM: 20;
+  readonly MENU: 21;
+  readonly PRESS_KEY: 22;
+  readonly CHECK_ABORT: 23;
+  readonly READ_FIELD: 30;
+  readonly READ_AMOUNT: 34;
+  readonly READ_MASKED: 41;
+  readonly FOOTER: 52;
+};
+/** `continueTransaction` answers to `CONFIRM` (20). */
+declare const CLISITEF_YES = "0";
+declare const CLISITEF_NO = "1";
+/** `TipoCampo` ids stored with `STORE_FIELD` (Fiserv "Tabela TipoCampo"). */
+declare const CLISITEF_FIELD: {
+  readonly TRANSACTION_DATE: 105;
+  readonly CUSTOMER_RECEIPT: 121;
+  readonly MERCHANT_RECEIPT: 122;
+  readonly INSTITUTION_CODE: 131;
+  readonly CARD_TYPE_CODE: 132;
+  readonly SITEF_NSU: 133;
+  readonly HOST_NSU: 134;
+  readonly AUTHORIZATION_CODE: 135;
+  readonly CARD_BIN: 136;
+  readonly INSTITUTION_NAME: 156;
+  readonly LAST4: 1190;
+  readonly ENTRY_MODE: 2090;
+};
+/** Fields that prove the card was read: an error after them is ambiguous. */
+declare const CLISITEF_CAPTURE_FIELDS: ReadonlySet<number>;
+/** Operator, pinpad or automation cancelled (ficha §11). */
+declare const CLISITEF_CANCEL_CODES: ReadonlySet<number>;
+/** Inconclusive when the card was already read (ficha §4). */
+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;
+/** 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. */
+declare const CLISITEF_STORAGE_KEY = "clisitef:transaction:v1";
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Ficha §11 (Fiserv "Tabela de códigos de retorno"); other positive codes
+ * (authorizer) fall back to `CARD_DECLINED`, other negatives to `UNKNOWN`.
+ */
+declare const clisitefPinPadErrors: Readonly<Record<string, PaymentErrorEntry>> & {
+  "-1": PaymentErrorEntry;
+  "-2": PaymentErrorEntry;
+  "-3": PaymentErrorEntry;
+  "-4": PaymentErrorEntry;
+  "-5": PaymentErrorEntry;
+  "-6": PaymentErrorEntry;
+  "-8": PaymentErrorEntry;
+  "-9": PaymentErrorEntry;
+  "-10": PaymentErrorEntry;
+  "-12": PaymentErrorEntry;
+  "-13": PaymentErrorEntry;
+  "-15": PaymentErrorEntry;
+  "-20": PaymentErrorEntry;
+  "-21": PaymentErrorEntry;
+  "-24": PaymentErrorEntry;
+  "-30": PaymentErrorEntry;
+  "-40": PaymentErrorEntry;
+  "-41": PaymentErrorEntry;
+  "-43": PaymentErrorEntry;
+  "-50": PaymentErrorEntry;
+  "-100": PaymentErrorEntry;
+  CLISITEF_TIMEOUT: PaymentErrorEntry;
+};
+//#endregion
+//#region src/settings.d.ts
+declare const CLISITEF_PINPAD_TYPES: readonly ["ANDROID_USB", "ANDROID_BT", "ANDROID_AUTO"];
+/** Ficha §6: filled per kiosk in the device settings. */
+declare const clisitefPinPadDeviceFields: DeviceField[];
+type ClisitefModality = keyof typeof CLISITEF_MODALITY;
+type ClisitefPinPadSettings = {
+  configure: ClisitefConfigureParams;
+  modality: Exclude<ClisitefModality, "PIX">;
+  operator: string;
+  restrictions: string;
+  terminalNumber: string;
+};
+/** `payments.config` (merchant) + device settings; throws when incomplete. */
+declare const readClisitefPinPadSettings: (config: Record<string, unknown>, device: Record<string, unknown>) => ClisitefPinPadSettings;
+//#endregion
+//#region src/metadata.d.ts
+type ClisitefFields = ReadonlyMap<number, string>;
+/** Last 4 digits of the masked PAN printed on the receipt. */
+declare const clisitefLast4: (receipt: string | null) => string | null;
+type MetadataInput = {
+  attemptReference: string;
+  fields: ClisitefFields;
+  modality: ClisitefModality;
+  terminalNumber: string;
+  fiscalCoupon: string;
+  fiscalDate: string;
+};
+declare const clisitefMetadata: (input: MetadataInput) => PaymentMetadata;
+/** PIN_PAD tender details; `null` without brand and last 4 (schema minimum). */
+declare const clisitefDetails: (metadata: PaymentMetadata) => TenderDetails | null;
+//#endregion
+//#region src/store.d.ts
+/**
+ * `started`: `startTransaction` called. `approved`: `finishTransaction(1)`
+ * called, no `stage 2` yet. `confirmed` / `undone`: closed either way.
+ * `review`: approved, then lost, and no longer pending in CliSiTef: it may
+ * have been charged.
+ */
+type ClisitefTransactionState = "started" | "approved" | "confirmed" | "undone" | "review";
+type ClisitefTransactionRecord = {
+  attemptReference: string;
+  fiscalCoupon: string;
+  fiscalDate: string;
+  time: string;
+  startedAt: number;
+  state: ClisitefTransactionState;
+  amount: number;
+  metadata?: PaymentMetadata;
+  details?: TenderDetails | null;
+  error?: StandardPaymentError;
+};
+declare const readTransaction: (storage: PaymentStorage) => Promise<ClisitefTransactionRecord | null>;
+declare const writeTransaction: (storage: PaymentStorage, record: ClisitefTransactionRecord) => Promise<void>;
+declare const isOpen: (record: ClisitefTransactionRecord) => boolean;
+//#endregion
+//#region src/transaction.d.ts
+/**
+ * `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.
+ */
+type ClisitefOutcomeStatus = "confirmed" | "declined" | "undone" | "unresolved";
+type ClisitefOutcome = {
+  status: ClisitefOutcomeStatus;
+  /** Provider code: `resultCode`, a client error code, or `null`. */
+  code: number | string | null;
+  message: string | null;
+  fields: ClisitefFields;
+  aborted: boolean;
+  /** Error thrown by `ctx.ui` (e.g. the customer did not answer). */
+  error?: unknown;
+};
+type ClisitefTransactionInput = {
+  client: ClisitefClient;
+  ui: PaymentUI;
+  signal: AbortSignal;
+  start: ClisitefStartParams;
+  finish: Omit<ClisitefFinishParams, "confirm">;
+  confirmationTimeoutMs: number;
+  /** Runs before `finishTransaction(1)`, to persist the approval. */
+  onApproved: (fields: ClisitefFields) => Promise<void>;
+};
+/**
+ * One CliSiTef transaction: `startTransaction`, the `onData` loop answered
+ * through `ui`, `finishTransaction(1)` on approval (`stage 1` = 0) and
+ * success only when `stage 2` closes with 0. Never rejects.
+ */
+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 };

package/dist/index.js

@@ -0,0 +1,977 @@
+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";
+//#region src/constants.ts
+/**
+* `onData` commands handled by the adapter (Fiserv "Tabela de códigos de
+* comando"). Not handled, so they abort the transaction: 29 (silent field),
+* 31 (check), 35 (barcode), 42 (identified menu, only with
+* `ItemMenuIdentificado`) and 50/51 (QR, PIX only).
+*/
+const CLISITEF_COMMAND = {
+	STORE_FIELD: 0,
+	MESSAGE_OPERATOR: 1,
+	MESSAGE_CUSTOMER: 2,
+	MESSAGE_BOTH: 3,
+	MENU_TITLE: 4,
+	CLEAR_OPERATOR: 11,
+	CLEAR_CUSTOMER: 12,
+	CLEAR_BOTH: 13,
+	CLEAR_MENU_TITLE: 14,
+	HEADER: 15,
+	CLEAR_HEADER: 16,
+	CONFIRM: 20,
+	MENU: 21,
+	PRESS_KEY: 22,
+	CHECK_ABORT: 23,
+	READ_FIELD: 30,
+	READ_AMOUNT: 34,
+	READ_MASKED: 41,
+	FOOTER: 52
+};
+/** `continueTransaction` answers to `CONFIRM` (20). */
+const CLISITEF_YES = "0";
+const CLISITEF_NO = "1";
+/** `TipoCampo` ids stored with `STORE_FIELD` (Fiserv "Tabela TipoCampo"). */
+const CLISITEF_FIELD = {
+	TRANSACTION_DATE: 105,
+	CUSTOMER_RECEIPT: 121,
+	MERCHANT_RECEIPT: 122,
+	INSTITUTION_CODE: 131,
+	CARD_TYPE_CODE: 132,
+	SITEF_NSU: 133,
+	HOST_NSU: 134,
+	AUTHORIZATION_CODE: 135,
+	CARD_BIN: 136,
+	INSTITUTION_NAME: 156,
+	LAST4: 1190,
+	ENTRY_MODE: 2090
+};
+/** Fields that prove the card was read: an error after them is ambiguous. */
+const CLISITEF_CAPTURE_FIELDS = /* @__PURE__ */ new Set([
+	CLISITEF_FIELD.CUSTOMER_RECEIPT,
+	CLISITEF_FIELD.MERCHANT_RECEIPT,
+	CLISITEF_FIELD.CARD_TYPE_CODE,
+	CLISITEF_FIELD.HOST_NSU,
+	CLISITEF_FIELD.AUTHORIZATION_CODE,
+	CLISITEF_FIELD.CARD_BIN,
+	CLISITEF_FIELD.LAST4,
+	CLISITEF_FIELD.ENTRY_MODE
+]);
+/** Operator, pinpad or automation cancelled (ficha §11). */
+const CLISITEF_CANCEL_CODES = /* @__PURE__ */ new Set([
+	-2,
+	-6,
+	-15
+]);
+/** Inconclusive when the card was already read (ficha §4). */
+const CLISITEF_INCONCLUSIVE_CODES = /* @__PURE__ */ new Set([
+	-5,
+	-43,
+	-100
+]);
+/** Approved (`stage 1`) without `stage 2`: undo (legacy `CONFIRMATION_TIMEOUT_MS`). */
+const CLISITEF_CONFIRMATION_TIMEOUT_MS = 6e4;
+/** 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. */
+const CLISITEF_STORAGE_KEY = "clisitef:transaction:v1";
+//#endregion
+//#region src/errors.ts
+const source = "docs/payments/clisitef/pinpad.md#11-errores";
+const entry = (code, extra = {}) => {
+	return {
+		code,
+		source,
+		...extra
+	};
+};
+const invalid = (message) => entry("INVALID_REQUEST", { message });
+/**
+* Ficha §11 (Fiserv "Tabela de códigos de retorno"); other positive codes
+* (authorizer) fall back to `CARD_DECLINED`, other negatives to `UNKNOWN`.
+*/
+const clisitefPinPadErrors = definePaymentErrors({
+	"-1": entry("TERMINAL_NEEDS_INIT", { retryable: true }),
+	"-2": entry("CANCELLED_BY_USER"),
+	"-3": invalid("Invalid CliSiTef function or modality"),
+	"-4": entry("TERMINAL_UNAVAILABLE", { message: "Out of memory" }),
+	"-5": entry("PROVIDER_UNAVAILABLE"),
+	"-6": entry("CANCELLED_BY_USER"),
+	"-8": entry("TERMINAL_NEEDS_INIT", { message: "CliSiTef outdated" }),
+	"-9": invalid("CliSiTef iterative flow not started"),
+	"-10": invalid("Missing mandatory CliSiTef parameter"),
+	"-12": entry("TERMINAL_BUSY"),
+	"-13": entry("UNKNOWN", { message: "Fiscal document not found" }),
+	"-15": entry("CANCELLED_BY_USER"),
+	"-20": invalid("Invalid CliSiTef parameter"),
+	"-21": invalid("Prohibited word in pinpad collection"),
+	"-24": invalid("Digital wallet not enabled"),
+	"-30": entry("TERMINAL_UNAVAILABLE", { message: "File access error" }),
+	"-40": entry("CARD_DECLINED", { message: "Declined by the SiTef server" }),
+	"-41": invalid("Invalid data"),
+	"-43": entry("TERMINAL_UNAVAILABLE", { message: "Pinpad routine failed" }),
+	"-50": entry("FRAUD_SUSPECTED", { message: "Unsecured transaction" }),
+	"-100": entry("UNKNOWN", { message: "CliSiTef internal error" }),
+	[CLISITEF_TIMEOUT_CODE]: entry("TIMEOUT")
+});
+//#endregion
+//#region src/metadata.ts
+const MASKED_PAN = /\d{0,6}[*Xx]{4,}\s*(\d{4})(?!\d)/;
+const field = (fields, id) => {
+	const value = fields.get(id)?.trim();
+	return value ? value : null;
+};
+/** Last 4 digits of the masked PAN printed on the receipt. */
+const clisitefLast4 = (receipt) => {
+	if (!receipt) return null;
+	return MASKED_PAN.exec(receipt)?.[1] ?? null;
+};
+/**
+* Field 132. Fiserv documents it as "a table to be provided"; these codes
+* come from the legacy production catalog (ficha §8).
+*/
+const BRANDS = {
+	"00001": "VISA",
+	"00002": "MASTERCARD",
+	"00004": "AMEX",
+	"00011": "JCB",
+	"10014": "DISCOVER",
+	"20001": "MAESTRO",
+	"20002": "VISA_ELECTRON",
+	"20137": "TELENET"
+};
+/** Field 2090 (Fiserv "Tabela TipoCampo"). */
+const ENTRY_MODES = {
+	"00": "SWIPE",
+	"03": "CHIP",
+	"05": "CONTACTLESS",
+	"06": "CONTACTLESS",
+	"99": "MANUAL"
+};
+const clisitefBrand = (fields) => {
+	const code = field(fields, CLISITEF_FIELD.CARD_TYPE_CODE);
+	if (!code || code === "00000") return null;
+	return BRANDS[code] ?? code;
+};
+const CARD_TYPES = {
+	DEBIT: "DEBIT",
+	CREDIT: "CREDIT",
+	VOUCHER: "PREPAID",
+	PIX: null
+};
+const clisitefMetadata = (input) => {
+	const { fields } = input;
+	const customer = field(fields, CLISITEF_FIELD.CUSTOMER_RECEIPT);
+	const merchant = field(fields, CLISITEF_FIELD.MERCHANT_RECEIPT);
+	const brand = clisitefBrand(fields);
+	const last4 = field(fields, CLISITEF_FIELD.LAST4)?.slice(-4) ?? null;
+	const entry = field(fields, CLISITEF_FIELD.ENTRY_MODE);
+	const institution = field(fields, CLISITEF_FIELD.INSTITUTION_NAME);
+	const p1 = {
+		provider_transaction_id: field(fields, CLISITEF_FIELD.SITEF_NSU),
+		authorization_code: field(fields, CLISITEF_FIELD.AUTHORIZATION_CODE),
+		reference: field(fields, CLISITEF_FIELD.HOST_NSU)
+	};
+	const p2 = {
+		card_type: CARD_TYPES[input.modality] ?? null,
+		brand
+	};
+	const p3 = {
+		last4: last4 ?? clisitefLast4(customer ?? merchant),
+		entry_mode: entry ? ENTRY_MODES[entry] ?? null : null
+	};
+	const p4 = { acquirer: institution ?? field(fields, CLISITEF_FIELD.INSTITUTION_CODE) };
+	const p5 = { terminal_id: input.terminalNumber };
+	const p6 = { ticket_number: input.fiscalCoupon };
+	const p7 = { transaction_date: input.fiscalDate };
+	const payment = {
+		...p1,
+		...p2,
+		...p3,
+		...p4,
+		...p5,
+		...p6,
+		...p7
+	};
+	const receipt = customer !== null || merchant !== null ? {
+		customer,
+		merchant,
+		format: "text"
+	} : void 0;
+	return {
+		attempt_reference: input.attemptReference,
+		payment,
+		receipt
+	};
+};
+/** PIN_PAD tender details; `null` without brand and last 4 (schema minimum). */
+const clisitefDetails = (metadata) => {
+	const payment = metadata.payment;
+	const brand = payment?.brand?.slice(0, 32);
+	const last4 = payment?.last4;
+	const terminal = payment?.terminal_id;
+	if (!brand || !last4 || !terminal) return null;
+	return {
+		method: "PIN_PAD",
+		brand,
+		last4,
+		auth_code: payment.authorization_code ?? void 0,
+		terminal_id: terminal
+	};
+};
+//#endregion
+//#region src/settings.ts
+const CLISITEF_PINPAD_TYPES = [
+	"ANDROID_USB",
+	"ANDROID_BT",
+	"ANDROID_AUTO"
+];
+/** Ficha §6: filled per kiosk in the device settings. */
+const clisitefPinPadDeviceFields = [
+	{
+		key: "sitef_ip",
+		label: "SiTef server IP",
+		type: "text",
+		required: true
+	},
+	{
+		key: "store_code",
+		label: "SiTef store code",
+		type: "text",
+		required: true
+	},
+	{
+		key: "terminal_number",
+		label: "SiTef terminal number",
+		type: "text",
+		required: true
+	},
+	{
+		key: "cnpj_store",
+		label: "Store CNPJ",
+		type: "text",
+		required: true
+	},
+	{
+		key: "pinpad_type",
+		label: "Pinpad connection",
+		type: "select",
+		required: true,
+		options: [...CLISITEF_PINPAD_TYPES]
+	}
+];
+const text = (value) => {
+	return typeof value === "string" ? value.trim() : "";
+};
+const notConfigured = (missing) => {
+	return new PaymentError(createPaymentError("TERMINAL_NOT_CONFIGURED", { message: `CliSiTef is missing ${missing.join(", ")}` }));
+};
+const isModality = (value) => {
+	return value === "DEBIT" || value === "CREDIT" || value === "VOUCHER";
+};
+/** `payments.config` (merchant) + device settings; throws when incomplete. */
+const readClisitefPinPadSettings = (config, device) => {
+	const modality = text(config.modality);
+	const cnpjEnterprise = text(config.cnpj_enterprise);
+	const serverIp = text(device.sitef_ip);
+	const storeCode = text(device.store_code);
+	const terminalNumber = text(device.terminal_number);
+	const cnpjStore = text(device.cnpj_store).replace(/\D/g, "");
+	const pinpadType = text(device.pinpad_type) || void 0;
+	const required = {
+		modality,
+		cnpj_enterprise: cnpjEnterprise
+	};
+	const fromDevice = {
+		sitef_ip: serverIp,
+		store_code: storeCode
+	};
+	const more = {
+		terminal_number: terminalNumber,
+		cnpj_store: cnpjStore
+	};
+	const values = {
+		...required,
+		...fromDevice
+	};
+	Object.assign(values, more);
+	const missing = Object.keys(values).filter((key) => !values[key]);
+	if (missing.length) throw notConfigured(missing);
+	if (!isModality(modality)) throw notConfigured(["a valid modality"]);
+	return {
+		configure: {
+			serverIp,
+			storeCode,
+			terminalNumber,
+			additionalParams: clisitefAdditionalParams({
+				cnpjStore,
+				cnpjEnterprise,
+				pinpadType
+			})
+		},
+		modality,
+		operator: text(config.operator) || "KIOSKO_BR",
+		restrictions: text(config.restrictions),
+		terminalNumber
+	};
+};
+//#endregion
+//#region src/store.ts
+const isRecord = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const record = value;
+	return typeof record.fiscalCoupon === "string" && typeof record.attemptReference === "string";
+};
+const readTransaction = async (storage) => {
+	const raw = await storage.get(CLISITEF_STORAGE_KEY);
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		return isRecord(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+};
+const writeTransaction = async (storage, record) => {
+	await storage.set(CLISITEF_STORAGE_KEY, JSON.stringify(record));
+};
+const isOpen = (record) => {
+	return record.state === "started" || record.state === "approved";
+};
+//#endregion
+//#region src/transaction.ts
+const errorCode = (error) => {
+	if (!error || typeof error !== "object") return null;
+	const code = error.code;
+	return typeof code === "string" || typeof code === "number" ? code : null;
+};
+const errorMessage = (error) => {
+	return error instanceof Error ? error.message : null;
+};
+const inputType = (command) => {
+	if (command === CLISITEF_COMMAND.READ_MASKED) return "password";
+	if (command === CLISITEF_COMMAND.READ_AMOUNT) return "number";
+	return "text";
+};
+const MESSAGES = /* @__PURE__ */ new Set([
+	CLISITEF_COMMAND.MESSAGE_OPERATOR,
+	CLISITEF_COMMAND.MESSAGE_CUSTOMER,
+	CLISITEF_COMMAND.MESSAGE_BOTH,
+	CLISITEF_COMMAND.PRESS_KEY,
+	CLISITEF_COMMAND.FOOTER
+]);
+const SILENT = /* @__PURE__ */ new Set([
+	CLISITEF_COMMAND.CLEAR_OPERATOR,
+	CLISITEF_COMMAND.CLEAR_CUSTOMER,
+	CLISITEF_COMMAND.CLEAR_BOTH,
+	CLISITEF_COMMAND.HEADER,
+	CLISITEF_COMMAND.CLEAR_HEADER,
+	CLISITEF_COMMAND.CHECK_ABORT
+]);
+const READS = /* @__PURE__ */ new Set([
+	CLISITEF_COMMAND.READ_FIELD,
+	CLISITEF_COMMAND.READ_AMOUNT,
+	CLISITEF_COMMAND.READ_MASKED
+]);
+/**
+* One CliSiTef transaction: `startTransaction`, the `onData` loop answered
+* through `ui`, `finishTransaction(1)` on approval (`stage 1` = 0) and
+* success only when `stage 2` closes with 0. Never rejects.
+*/
+const runClisitefTransaction = (input) => {
+	const { client, ui, signal } = input;
+	const fields = /* @__PURE__ */ new Map();
+	const subscriptions = [];
+	let title = "";
+	let captured = false;
+	let approved = false;
+	let closing = false;
+	let aborted = false;
+	let watchdog;
+	let queue = Promise.resolve();
+	let resolve = () => void 0;
+	const done = new Promise((r) => resolve = r);
+	const settle = (status, reason) => {
+		clearTimeout(watchdog);
+		for (const subscription of subscriptions) subscription.remove();
+		signal.removeEventListener("abort", onAbort);
+		resolve({
+			status,
+			...reason,
+			fields,
+			aborted
+		});
+	};
+	const undo = async (reason) => {
+		try {
+			const p1 = {
+				confirm: CLISITEF_CONFIRM.UNDO,
+				...input.finish
+			};
+			await client.finishTransaction(p1);
+			settle("undone", reason);
+		} catch (error) {
+			settle("unresolved", {
+				...reason,
+				message: errorMessage(error)
+			});
+		}
+	};
+	const close = async (reason) => {
+		if (closing) return;
+		closing = true;
+		if (!approved) await client.abortTransaction(CLISITEF_ABORT_FLAG).catch(() => 0);
+		if (captured || approved) return undo(reason);
+		settle("declined", reason);
+	};
+	function onAbort() {
+		aborted = true;
+		close({
+			code: null,
+			message: "Aborted by the payment deadline"
+		});
+	}
+	const reply = async (data) => {
+		if (closing) return;
+		await client.continueTransaction(data);
+	};
+	const onData = async (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;
+			return reply("");
+		}
+		if (MESSAGES.has(command)) {
+			if (text.trim()) ui.message({
+				text: text.trim(),
+				kind: "waiting"
+			});
+			return reply("");
+		}
+		if (command === CLISITEF_COMMAND.MENU_TITLE) {
+			title = text.trim();
+			return reply("");
+		}
+		if (command === CLISITEF_COMMAND.CLEAR_MENU_TITLE) {
+			title = "";
+			return reply("");
+		}
+		if (SILENT.has(command)) return reply("");
+		if (command === CLISITEF_COMMAND.CONFIRM) {
+			const yes = await ui.confirm({ text: text.trim() || title });
+			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({
+				title: label,
+				options
+			}));
+		}
+		if (READS.has(command)) {
+			const label = text.trim() || title || "Informe o dado";
+			const max = event.maxLength > 0 ? event.maxLength : void 0;
+			const p1 = {
+				label,
+				type: inputType(command),
+				maxLength: max
+			};
+			return reply(await ui.input(p1));
+		}
+		const message = `Unsupported CliSiTef command ${command}`;
+		return close({
+			code: `UNSUPPORTED_COMMAND_${command}`,
+			message
+		});
+	};
+	const confirm = () => {
+		const message = "CliSiTef did not close the confirmation";
+		const expire = () => {
+			if (closing) return;
+			closing = true;
+			undo({
+				code: null,
+				message
+			});
+		};
+		watchdog = setTimeout(expire, input.confirmationTimeoutMs);
+		const p1 = {
+			confirm: CLISITEF_CONFIRM.CONFIRM,
+			...input.finish
+		};
+		client.finishTransaction(p1).catch((error) => {
+			if (closing) return;
+			closing = true;
+			clearTimeout(watchdog);
+			undo({
+				code: errorCode(error),
+				message: errorMessage(error)
+			});
+		});
+	};
+	const onResult = async (event) => {
+		const { stage, resultCode: code } = event;
+		if (closing) return;
+		if (stage === 1 && code === CLISITEF_RESULT.OK) {
+			approved = true;
+			await input.onApproved(fields);
+			if (!closing) confirm();
+			return;
+		}
+		if (stage === 1) {
+			closing = true;
+			if (!(captured && CLISITEF_INCONCLUSIVE_CODES.has(code))) return settle("declined", {
+				code,
+				message: null
+			});
+			await client.abortTransaction(CLISITEF_ABORT_FLAG).catch(() => 0);
+			return undo({
+				code,
+				message: null
+			});
+		}
+		if (!approved) return;
+		closing = true;
+		if (code === CLISITEF_RESULT.OK) return settle("confirmed", {
+			code,
+			message: null
+		});
+		return undo({
+			code,
+			message: null
+		});
+	};
+	const enqueue = (handle) => {
+		const run = async () => {
+			await handle();
+		};
+		queue = queue.then(run).catch(async (error) => {
+			const reason = {
+				code: errorCode(error),
+				message: errorMessage(error)
+			};
+			if (closing) return;
+			await close({
+				...reason,
+				error
+			});
+		});
+	};
+	const begin = async () => {
+		if (signal.aborted) {
+			aborted = true;
+			return settle("declined", {
+				code: null,
+				message: "Aborted"
+			});
+		}
+		signal.addEventListener("abort", onAbort);
+		const handleData = (e) => enqueue(() => onData(e));
+		const handleResult = (e) => {
+			enqueue(() => onResult(e));
+		};
+		subscriptions.push(client.onData(handleData));
+		subscriptions.push(client.onTransactionResult(handleResult));
+		try {
+			const code = await client.startTransaction(input.start);
+			if (code === CLISITEF_RESULT.CONTINUE || closing) return;
+			closing = true;
+			settle("declined", {
+				code,
+				message: null
+			});
+		} catch (error) {
+			if (closing) return;
+			closing = true;
+			const reason = {
+				code: errorCode(error),
+				message: errorMessage(error)
+			};
+			settle("declined", reason);
+		}
+	};
+	begin();
+	return done;
+};
+//#endregion
+//#region src/adapter.ts
+/** Confirmed in the act (`finishTransaction(1)`), never captured later. */
+const clisitefPinPadCapabilities = {
+	deferredCapture: false,
+	inPerson: true
+};
+const createLock = () => {
+	let tail = Promise.resolve();
+	return (task) => {
+		const run = tail.then(task, task);
+		tail = run.catch(() => void 0);
+		return run;
+	};
+};
+const failed = (record, reference, error, needsReview = false) => {
+	const base = record.metadata ?? { attempt_reference: reference };
+	const review = needsReview ? { needs_review: true } : {};
+	const metadata = {
+		...base,
+		attempt_reference: reference,
+		error,
+		...review
+	};
+	return {
+		status: "FAILED",
+		amount: record.amount,
+		metadata,
+		error
+	};
+};
+const paid = (record) => {
+	const reference = record.attemptReference;
+	const metadata = record.metadata ?? { attempt_reference: reference };
+	const details = record.details ?? null;
+	return {
+		status: "PAID",
+		amount: record.amount,
+		metadata,
+		details
+	};
+};
+const outcomeError = (outcome, attempt) => {
+	const provider = {
+		provider_message: outcome.message,
+		attempt
+	};
+	const code = outcome.code == null ? null : String(outcome.code);
+	const extra = {
+		...provider,
+		provider_code: code
+	};
+	if (outcome.aborted) return createPaymentError("TIMEOUT", extra);
+	if (outcome.status === "unresolved") return createPaymentError("AMBIGUOUS", extra);
+	if (outcome.code === null) {
+		const message = outcome.message ?? void 0;
+		return createPaymentError("PROVIDER_UNAVAILABLE", {
+			...extra,
+			retryable: false,
+			message
+		});
+	}
+	const fallback = typeof outcome.code === "number" && outcome.code > 0 ? "CARD_DECLINED" : "UNKNOWN";
+	return toPaymentError(clisitefPinPadErrors, {
+		code: outcome.code,
+		message: outcome.message,
+		attempt,
+		fallback
+	});
+};
+const terminalError = (error) => {
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		ok: false,
+		message,
+		error: createPaymentError("TERMINAL_UNAVAILABLE", { message })
+	};
+};
+/**
+* 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).
+*/
+const clisitefPinPadPayments = (options = {}) => {
+	const client = options.client ?? clisitef;
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	const confirmationMs = options.confirmationTimeoutMs ?? 6e4;
+	const lock = createLock();
+	const storageOf = (ctx) => {
+		return options.storage ?? ctx.storage;
+	};
+	const configure = async (settings) => {
+		const code = await client.configure(settings.configure);
+		if (code === 0) return null;
+		client.invalidate();
+		return toPaymentError(clisitefPinPadErrors, {
+			code,
+			fallback: "TERMINAL_NOT_CONFIGURED"
+		});
+	};
+	/** Undoes a transaction a crash or a lost result left open. */
+	const recover = async (storage, record) => {
+		const { fiscalCoupon, fiscalDate, time } = record;
+		const count = client.getQttPendingTransactions;
+		const pending = await count(fiscalDate, fiscalCoupon).catch(() => null);
+		if (pending === null) return record;
+		let next;
+		if (pending > 0) {
+			const p1 = {
+				confirm: CLISITEF_CONFIRM.UNDO,
+				fiscalCoupon,
+				fiscalDate
+			};
+			if (await client.finishTransaction({
+				...p1,
+				time
+			}).catch(() => -1) !== 0) return record;
+			const error = createPaymentError("PROVIDER_UNAVAILABLE", {
+				retryable: false,
+				message: "Pending CliSiTef transaction undone"
+			});
+			next = {
+				...record,
+				state: "undone",
+				error
+			};
+		} else if (record.state === "approved") {
+			const error = createPaymentError("AMBIGUOUS");
+			next = {
+				...record,
+				state: "review",
+				error
+			};
+		} else {
+			const error = createPaymentError("PROVIDER_UNAVAILABLE", {
+				retryable: false,
+				message: "CliSiTef transaction never approved"
+			});
+			next = {
+				...record,
+				state: "undone",
+				error
+			};
+		}
+		await writeTransaction(storage, next);
+		return next;
+	};
+	/** Configures and resolves the open record of the device, if any. */
+	const prepare = async (ctx) => {
+		const settings = readClisitefPinPadSettings(ctx.config, ctx.deviceSettings);
+		const error = await configure(settings);
+		const storage = storageOf(ctx);
+		let record = await readTransaction(storage);
+		if (!error && record && isOpen(record)) record = await recover(storage, record);
+		return {
+			settings,
+			error,
+			storage,
+			record
+		};
+	};
+	const fromRecord = (record, ctx) => {
+		const reference = ctx.attemptReference;
+		if (record.state === "confirmed") return paid(record);
+		if (record.state === "review") {
+			const error = record.error ?? createPaymentError("AMBIGUOUS");
+			return failed(record, reference, error, true);
+		}
+		if (record.state === "undone") {
+			const fallback = createPaymentError("UNKNOWN", { retryable: false });
+			return failed(record, reference, record.error ?? fallback);
+		}
+		const error = createPaymentError("TIMEOUT", { attempt: ctx.attempt });
+		return failed(record, reference, error);
+	};
+	const charge = async (ctx) => {
+		const amount = ctx.amount.value;
+		const reference = ctx.attemptReference;
+		const empty = { amount };
+		if (!client.available) {
+			const error = createPaymentError("TERMINAL_UNAVAILABLE");
+			return failed(empty, reference, error);
+		}
+		const prepared = await prepare(ctx);
+		const { settings, storage, record: previous } = prepared;
+		if (prepared.error) return failed(empty, reference, prepared.error);
+		if (previous?.attemptReference === reference && previous?.state === "confirmed") return paid(previous);
+		if (previous && isOpen(previous)) {
+			const error = createPaymentError("TERMINAL_BUSY", { attempt: ctx.attempt });
+			return failed(empty, reference, error);
+		}
+		const date = now();
+		const fiscal = clisitefFiscalDateTime(date, options.timeZone);
+		const fiscalCoupon = String(date.getTime());
+		const finish = {
+			fiscalCoupon,
+			...fiscal
+		};
+		const record = {
+			attemptReference: reference,
+			...finish,
+			amount,
+			startedAt: date.getTime(),
+			state: "started"
+		};
+		await writeTransaction(storage, record);
+		const s1 = {
+			modality: CLISITEF_MODALITY[settings.modality],
+			value: formatClisitefAmount(amount),
+			...finish
+		};
+		const s2 = { operator: settings.operator };
+		const start = {
+			...s1,
+			...s2,
+			restrictions: settings.restrictions
+		};
+		const meta = {
+			modality: settings.modality,
+			fiscalCoupon
+		};
+		const m1 = {
+			terminalNumber: settings.terminalNumber,
+			...meta
+		};
+		const metadataOf = (fields) => {
+			const m2 = {
+				attemptReference: reference,
+				fields
+			};
+			return clisitefMetadata({
+				...m1,
+				...m2,
+				fiscalDate: fiscal.fiscalDate
+			});
+		};
+		const onApproved = async (fields) => {
+			const metadata = metadataOf(fields);
+			await writeTransaction(storage, {
+				...record,
+				state: "approved",
+				metadata
+			});
+		};
+		const t1 = {
+			client,
+			ui: ctx.ui,
+			signal: ctx.signal,
+			start,
+			finish
+		};
+		const t2 = {
+			confirmationTimeoutMs: confirmationMs,
+			onApproved
+		};
+		const outcome = await runClisitefTransaction({
+			...t1,
+			...t2
+		});
+		const metadata = metadataOf(outcome.fields);
+		if (outcome.status === "confirmed") {
+			const details = clisitefDetails(metadata);
+			const confirmed = {
+				...record,
+				metadata,
+				details,
+				state: "confirmed"
+			};
+			await writeTransaction(storage, confirmed);
+			return paid(confirmed);
+		}
+		if (outcome.code === -1) client.invalidate();
+		const error = outcomeError(outcome, ctx.attempt);
+		const unresolved = outcome.status === "unresolved";
+		const state = unresolved ? "approved" : "undone";
+		const closed = {
+			...record,
+			state,
+			metadata,
+			error
+		};
+		await writeTransaction(storage, closed);
+		if (outcome.error) throw outcome.error;
+		return failed(closed, reference, error, unresolved);
+	};
+	const query = async (ctx, result) => {
+		const reference = result.metadata.attempt_reference;
+		const scoped = {
+			...ctx,
+			attemptReference: reference
+		};
+		const { record, error } = await prepare(scoped);
+		if (record?.attemptReference !== reference) {
+			const missing = createPaymentError("UNKNOWN", {
+				retryable: false,
+				message: "No CliSiTef transaction for this attempt"
+			});
+			return failed(result, reference, missing);
+		}
+		if (error && isOpen(record)) return failed(record, reference, error);
+		return fromRecord(record, scoped);
+	};
+	const cancel = async (ctx, result) => {
+		const next = await query(ctx, result);
+		if (next.status === "PAID") {
+			const error = createPaymentError("REVERSAL_NOT_ALLOWED");
+			return {
+				...next,
+				status: "FAILED",
+				error
+			};
+		}
+		const code = next.error?.code;
+		if (!(code !== "AMBIGUOUS" && code !== "TIMEOUT")) return next;
+		return {
+			...next,
+			status: "CANCELLED",
+			error: void 0
+		};
+	};
+	const operation = (run) => {
+		return (ctx) => {
+			const task = async () => {
+				try {
+					const data = await run(ctx);
+					return {
+						ok: true,
+						message: typeof data === "string" ? data : null,
+						data: data && typeof data === "object" ? data : void 0
+					};
+				} catch (error) {
+					return terminalError(error);
+				}
+			};
+			return lock(task);
+		};
+	};
+	const terminal = {
+		init: operation(async (ctx) => {
+			client.invalidate();
+			const s1 = readClisitefPinPadSettings(ctx.config, ctx.deviceSettings);
+			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() ?? {}),
+		extra: [{
+			key: "submit_pending_messages",
+			label: "Send pending messages",
+			run: operation(async () => {
+				return `Pending messages sent (${await client.submitPendingMessages()})`;
+			})
+		}, {
+			key: "release_pinpad",
+			label: "Release pinpad",
+			run: operation(async () => {
+				await client.closePinPad();
+				await client.disconnectSitef();
+				client.invalidate();
+				return "Pinpad released";
+			})
+		}]
+	};
+	return {
+		provider: "clisitef",
+		method: "PIN_PAD",
+		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)),
+		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 };

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@fire-spark/payments-clisitef-pinpad-rn",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0",
+  "description": "Fire Spark CliSiTef (Software Express) pinpad adapter for Brazil: debit, credit and voucher on Android kiosks",
+  "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/payments": "^0.7.0",
+    "@fire-spark/payments-clisitef-client": "^0.7.0",
+    "@fire-spark/types": "^0.7.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/payments",
+        "@fire-spark/payments-clisitef-client",
+        "@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.