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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { DeviceField, PaymentAdapter, PaymentAdapterCapabilities, PaymentErrorEntry, PaymentMetadata, PaymentResult, PaymentStorage, PaymentUI, StandardPaymentError } from "@fire-spark/payments";
+import { CLISITEF_MODALITY, ClisitefClient, ClisitefConfigureParams, ClisitefFinishParams, ClisitefMenuOption, 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. */
@@ -24,10 +24,11 @@ type ClisitefPinPadOptions = {
   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, so the deadline is `timeoutMs` instead of
- * the 30 s library default.
+ * CliSiTef (Software Express) on the kiosk pinpad, Brazil. The payment lists
+ * its `modalities` (DEBIT / CREDIT / VOUCHER); with more than one the
+ * customer picks it before the pinpad starts. The pinpad waits on the
+ * customer, so the deadline is `timeoutMs` instead of the 30 s library
+ * default.
  */
 declare const clisitefPinPadPayments: (options?: ClisitefPinPadOptions) => PaymentAdapter;
 //#endregion
@@ -35,8 +36,8 @@ declare const clisitefPinPadPayments: (options?: ClisitefPinPadOptions) => Payme
 /**
  * `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).
+ * 31 (check), 35 (barcode) and 42 (identified menu, only with
+ * `ItemMenuIdentificado`).
  */
 declare const CLISITEF_COMMAND: {
   readonly STORE_FIELD: 0;
@@ -57,6 +58,9 @@ declare const CLISITEF_COMMAND: {
   readonly READ_FIELD: 30;
   readonly READ_AMOUNT: 34;
   readonly READ_MASKED: 41;
+  /** PIX: show the QR (`fieldId` 584 carries the copy-and-paste payload). */
+  readonly QR_SHOW: 50;
+  readonly QR_HIDE: 51;
   readonly FOOTER: 52;
 };
 /** `continueTransaction` answers to `CONFIRM` (20). */
@@ -74,9 +78,17 @@ declare const CLISITEF_FIELD: {
   readonly AUTHORIZATION_CODE: 135;
   readonly CARD_BIN: 136;
   readonly INSTITUTION_NAME: 156;
+  readonly QR_PAYLOAD: 584;
   readonly LAST4: 1190;
   readonly ENTRY_MODE: 2090;
 };
+/** Fields a void asks for (`READ_*` commands), answered without the UI. */
+declare const CLISITEF_VOID_FIELD: {
+  readonly AMOUNT: 146;
+  readonly SUPERVISOR_PASSWORD: 500;
+  readonly ORIGINAL_DATE: 515;
+  readonly ORIGINAL_HOST_NSU: 516;
+};
 /** 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). */
@@ -94,6 +106,12 @@ declare const CLISITEF_PAYMENT_TIMEOUT_MS = 180000;
 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";
+/** Device-wide record of the last refund, apart from the charge one. */
+declare const CLISITEF_REFUND_STORAGE_KEY = "clisitef:refund:v1";
+/** Device-wide queue of voids that did not complete, retried later. */
+declare const CLISITEF_REVERSALS_KEY = "clisitef:reversals:v1";
+/** Device-wide record of completed voids, by attempt reference. */
+declare const CLISITEF_REFUNDS_KEY = "clisitef:refunds:v1";
 //#endregion
 //#region src/errors.d.ts
 /**
@@ -123,23 +141,55 @@ declare const clisitefPinPadErrors: Readonly<Record<string, PaymentErrorEntry>>
   "-50": PaymentErrorEntry;
   "-100": PaymentErrorEntry;
   CLISITEF_TIMEOUT: PaymentErrorEntry;
+  FINANCING_ONLY: 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. */
+/**
+ * Ficha §6: filled per kiosk in the device settings. SiTef IP, store code
+ * and store CNPJ come from the payment's store settings (`config.stores`);
+ * the device values only override them.
+ */
 declare const clisitefPinPadDeviceFields: DeviceField[];
+declare const redactSecrets: (values?: Record<string, unknown>) => {
+  [k: string]: unknown;
+};
 type ClisitefModality = keyof typeof CLISITEF_MODALITY;
+declare const CLISITEF_MODALITIES: readonly ClisitefModality[];
 type ClisitefPinPadSettings = {
   configure: ClisitefConfigureParams;
-  modality: Exclude<ClisitefModality, "PIX">;
+  /** Asked to the customer when there is more than one. */
+  modalities: ClisitefModality[];
   operator: string;
-  restrictions: string;
+  restrictions: Partial<Record<ClisitefModality, string>>;
   terminalNumber: string;
+  /** Field 500 of a void: device secret, else the store one. */
+  supervisorPassword: string;
 };
+declare const isClisitefModality: (value: unknown) => value is ClisitefModality;
 /** `payments.config` (merchant) + device settings; throws when incomplete. */
 declare const readClisitefPinPadSettings: (config: Record<string, unknown>, device: Record<string, unknown>) => ClisitefPinPadSettings;
 //#endregion
+//#region src/menu.d.ts
+type ClisitefMenuPurpose = "charge" | "void";
+type ClisitefMenuDecision = {
+  kind: "pick";
+  value: string;
+} | {
+  kind: "ask";
+  options: ClisitefMenuOption[];
+} | {
+  kind: "abort";
+  message: string;
+};
+/**
+ * Command 21. Labels compare without accents and in upper case. A void
+ * picks the original modality when one option matches it; a charge does it
+ * only for debit and credit, then drops the financing options.
+ */
+declare const resolveClisitefMenu: (options: ClisitefMenuOption[], modality: ClisitefModality, purpose: ClisitefMenuPurpose) => ClisitefMenuDecision;
+//#endregion
 //#region src/metadata.d.ts
 type ClisitefFields = ReadonlyMap<number, string>;
 /** Last 4 digits of the masked PAN printed on the receipt. */
@@ -152,10 +202,81 @@ type MetadataInput = {
   fiscalCoupon: string;
   fiscalDate: string;
 };
+/** `provider` section: the Spark modality and the CliSiTef function used. */
+type ClisitefProviderMetadata = {
+  modality: ClisitefModality;
+  function: number;
+};
 declare const clisitefMetadata: (input: MetadataInput) => PaymentMetadata;
+type VoidMetadataInput = {
+  fields: ClisitefFields;
+  function: number;
+  fiscalCoupon: string;
+  fiscalDate: string;
+};
+/** Void data kept under `provider.void`, next to the charge's metadata. */
+declare const clisitefVoidMetadata: (input: VoidMetadataInput) => {
+  function: number;
+  provider_transaction_id: string | null;
+  reference: string | null;
+  ticket_number: string;
+  transaction_date: string;
+  receipt: {
+    customer: string | null;
+    merchant: string | null;
+    format: "text";
+  } | null;
+};
+/** Spark modality of a charge; older charges only kept `card_type`. */
+declare const clisitefModalityOf: (metadata: PaymentMetadata) => ClisitefModality | null;
 /** PIN_PAD tender details; `null` without brand and last 4 (schema minimum). */
 declare const clisitefDetails: (metadata: PaymentMetadata) => TenderDetails | null;
 //#endregion
+//#region src/refund.d.ts
+type ClisitefVoidDeps = {
+  client: ClisitefClient;
+  now: () => Date;
+  timeZone?: string;
+  confirmationTimeoutMs: number;
+};
+type ClisitefVoidContext = {
+  ui: PaymentUI;
+  signal: AbortSignal;
+  storage: PaymentStorage;
+  settings: ClisitefPinPadSettings;
+  attempt: number;
+  /** The pinpad could not be prepared: queue the void without starting it. */
+  unavailable?: StandardPaymentError | null;
+};
+/**
+ * Voids a confirmed charge with its cancellation function (credit 210,
+ * debit and voucher 211, PIX 123). `REFUNDED` only after `stage 2` = 0;
+ * any other end keeps the charge `PAID` with `needs_review`, and a
+ * retryable one goes to the pending queue.
+ */
+declare const runClisitefVoid: (deps: ClisitefVoidDeps, ctx: ClisitefVoidContext, result: PaymentResult) => Promise<PaymentResult>;
+//#endregion
+//#region src/reversals.d.ts
+/** A void that did not complete; retried from the operator panel. */
+type ClisitefPendingReversal = {
+  attemptReference: string;
+  amount: number;
+  transactionDate: string;
+  hostNsu: string;
+  modality: ClisitefModality;
+  reason: string;
+  attempts: number;
+  createdAt: number;
+  /** The `PAID` result to void again. */
+  result: PaymentResult;
+};
+declare const readPendingReversals: (storage: PaymentStorage) => Promise<ClisitefPendingReversal[]>;
+/** Adds the void or bumps its attempts. */
+declare const queueReversal: (storage: PaymentStorage, entry: Omit<ClisitefPendingReversal, "attempts" | "createdAt">, now: number) => Promise<void>;
+declare const dropReversal: (storage: PaymentStorage, attemptReference: string) => Promise<void>;
+declare const readRefund: (storage: PaymentStorage, attemptReference: string) => Promise<PaymentResult | null>;
+declare const writeRefund: (storage: PaymentStorage, attemptReference: string, result: PaymentResult) => Promise<void>;
+//#endregion
 //#region src/store.d.ts
 /**
  * `started`: `startTransaction` called. `approved`: `finishTransaction(1)`
@@ -176,8 +297,8 @@ type ClisitefTransactionRecord = {
   details?: TenderDetails | null;
   error?: StandardPaymentError;
 };
-declare const readTransaction: (storage: PaymentStorage) => Promise<ClisitefTransactionRecord | null>;
-declare const writeTransaction: (storage: PaymentStorage, record: ClisitefTransactionRecord) => Promise<void>;
+declare const readTransaction: (storage: PaymentStorage, key?: string) => Promise<ClisitefTransactionRecord | null>;
+declare const writeTransaction: (storage: PaymentStorage, record: ClisitefTransactionRecord, key?: string) => Promise<void>;
 declare const isOpen: (record: ClisitefTransactionRecord) => boolean;
 //#endregion
 //#region src/transaction.d.ts
@@ -194,6 +315,8 @@ type ClisitefOutcome = {
   message: string | null;
   fields: ClisitefFields;
   aborted: boolean;
+  /** The card was read, a receipt arrived or the PIX QR was shown. */
+  evidence: boolean;
   /** Error thrown by `ctx.ui` (e.g. the customer did not answer). */
   error?: unknown;
 };
@@ -204,8 +327,13 @@ type ClisitefTransactionInput = {
   start: ClisitefStartParams;
   finish: Omit<ClisitefFinishParams, "confirm">;
   confirmationTimeoutMs: number;
+  /** Spark modality of the charge, or of the charge a void undoes. */
+  modality: ClisitefModality;
+  purpose: ClisitefMenuPurpose;
   /** Runs before `finishTransaction(1)`, to persist the approval. */
   onApproved: (fields: ClisitefFields) => Promise<void>;
+  /** Answer for a `READ_*` field without the UI; `null` asks `ui.input`. */
+  answerField?: (fieldId: number) => string | null;
 };
 /**
  * One CliSiTef transaction: `startTransaction`, the `onData` loop answered
@@ -214,4 +342,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_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 };
+export { CLISITEF_CANCEL_CODES, CLISITEF_CAPTURE_FIELDS, CLISITEF_COMMAND, CLISITEF_CONFIRMATION_TIMEOUT_MS, CLISITEF_DEFAULT_OPERATOR, CLISITEF_FIELD, CLISITEF_INCONCLUSIVE_CODES, CLISITEF_MODALITIES, CLISITEF_NO, CLISITEF_PAYMENT_TIMEOUT_MS, CLISITEF_PINPAD_TYPES, CLISITEF_REFUNDS_KEY, CLISITEF_REFUND_STORAGE_KEY, CLISITEF_REVERSALS_KEY, CLISITEF_STORAGE_KEY, CLISITEF_VOID_FIELD, CLISITEF_YES, ClisitefFields, ClisitefMenuDecision, ClisitefMenuPurpose, ClisitefModality, ClisitefOutcome, ClisitefOutcomeStatus, ClisitefPendingReversal, ClisitefPinPadOptions, ClisitefPinPadSettings, ClisitefProviderMetadata, ClisitefTransactionInput, ClisitefTransactionRecord, ClisitefTransactionState, ClisitefVoidContext, ClisitefVoidDeps, clisitefDetails, clisitefLast4, clisitefMetadata, clisitefModalityOf, clisitefPinPadCapabilities, clisitefPinPadDeviceFields, clisitefPinPadErrors, clisitefPinPadPayments, clisitefVoidMetadata, dropReversal, isClisitefModality, isOpen, queueReversal, readClisitefPinPadSettings, readPendingReversals, readRefund, readTransaction, redactSecrets, resolveClisitefMenu, runClisitefTransaction, runClisitefVoid, writeRefund, writeTransaction };