react-native-pos-pagseguro 1.0.0

package/package.json

@@ -0,0 +1,179 @@
+{
+  "name": "react-native-pos-pagseguro",
+  "version": "1.0.0",
+  "description": "Integration of plugpag for React Native",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "nitrogen",
+    "nitro.json",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-pos-pagseguro-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepublishOnly": "bob build",
+    "nitrogen": "nitrogen",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "test": "jest",
+    "release": "release-it --only-version"
+  },
+  "keywords": [
+    "react-native",
+    "pagseguro",
+    "pos",
+    "payment",
+    "plugpag",
+    "moderninha",
+    "terminal",
+    "android",
+    "nitro-modules",
+    "pix",
+    "credit-card",
+    "debit",
+    "voucher",
+    "point-of-sale",
+    "mpos",
+    "react-native-pos",
+    "pagamento",
+    "maquininha",
+    "pagseguro-pos"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CECSMH/react-native-pos-pagseguro.git"
+  },
+  "author": "CECSMH (https://github.com/CECSMH)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/CECSMH/react-native-pos-pagseguro/issues"
+  },
+  "homepage": "https://github.com/CECSMH/react-native-pos-pagseguro#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.8.1",
+    "@react-native/babel-preset": "0.83.0",
+    "@react-native/eslint-config": "0.83.0",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "del-cli": "^6.0.0",
+    "nitrogen": "^0.32.0",
+    "prettier": "^2.8.8",
+    "react": "19.2.0",
+    "react-native": "0.83.0",
+    "react-native-builder-bob": "^0.40.13",
+    "react-native-nitro-modules": "^0.32.0",
+    "release-it": "^19.0.4",
+    "turbo": "^2.5.6",
+    "typescript": "^5.9.2"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-nitro-modules": "^0.32.0"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "custom",
+        {
+          "script": "nitrogen",
+          "clean": "nitrogen/"
+        }
+      ],
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "jest": {
+    "preset": "react-native",
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "create-react-native-library": {
+    "type": "nitro-module",
+    "languages": "kotlin-swift",
+    "tools": [
+      "eslint",
+      "jest",
+      "lefthook",
+      "release-it"
+    ],
+    "version": "0.56.0"
+  }
+}

package/src/PosPagseguro.nitro.ts

@@ -0,0 +1,32 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+
+import type { CustomError } from './types/exceptions';
+import type { PaymentData, TransactionResult, VoidPayData } from './types/payments';
+import type { Capabilities, SubAcquirer, UserData } from './types/device';
+
+export interface PosPagseguro extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  getModel(): string;
+  getSerialNumber(): string;
+  getSubAcquirerData(): SubAcquirer | undefined;
+  getUserData(): UserData;
+
+  reboot(): void;
+
+  reprintCustomerReceipt(): Promise<number | CustomError>;
+  reprintStablishmentReceipt(): Promise<number | CustomError>;
+
+  printFromFile(file_path: string, quality: number, bottomPad?: number): Promise<number | CustomError>;
+  printFromBase64(base_64: string, quality: number, bottomPad?: number): Promise<number | CustomError>;
+
+  abort(): CustomError | undefined;
+
+  isServiceBusy(): boolean;
+  isAuthenticated(): boolean;
+  hasCapability(capability: Capabilities): boolean;
+  initialize(activation_code: string): void;
+
+  doPayment(payment_data: PaymentData, process_callback: (event: string) => void): Promise<TransactionResult | CustomError>;
+  voidPayment(void_data: VoidPayData, process_callback: (event: string) => void): Promise<TransactionResult | CustomError>;
+
+  getLastApprovedTransaction(): TransactionResult | CustomError;
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+import PagSeguro from './pag_seguro';
+import { PaymentError, PrintError } from './types/exceptions';
+import { InstallmentTypes, PaymentTypes, VoidType } from './types/payments';
+import type { PaymentData, TransactionResult, VoidPayData } from './types/payments';
+
+
+export type {
+  PaymentData,
+  VoidPayData,
+  TransactionResult
+}
+export {
+  PagSeguro as default,
+  VoidType,
+  PrintError,
+  PaymentError,
+  PaymentTypes,
+  InstallmentTypes,
+}

package/src/pag_seguro.ts

@@ -0,0 +1,306 @@
+import { NitroModules } from "react-native-nitro-modules";
+
+import type { PosPagseguro } from "./PosPagseguro.nitro";
+import { InstallmentTypes, PaymentTypes, VoidType, type PaymentData, type TransactionResult, type VoidPayData } from "./types/payments";
+
+import { AbordError, PaymentError, PrintError } from "./types/exceptions";
+import { Capabilities, type SubAcquirer, type UserData } from "./types/device";
+
+const PosPagseguroHybridObject = NitroModules.createHybridObject<PosPagseguro>('PosPagseguro');
+
+/**
+ * PagSeguro POS SDK para React Native
+ *
+ * Biblioteca de alto desempenho para integração com terminais PagSeguro (Moderninha, Smart, Pro, etc.)
+ * utilizando react-native-nitro-modules para comunicação nativa direta em Swift (iOS) e Kotlin (Android).
+ *
+ * ### Funcionalidades principais
+ * - Inicialização e ativação do terminal
+ * - Pagamentos: Crédito, Débito, Voucher e PIX
+ * - Parcelamento (à vista, lojista sem juros, comprador com juros)
+ * - Cancelamento/estorno de transações
+ * - Consulta da última transação aprovada
+ * - Reimpressão de vias (cliente e estabelecimento)
+ * - Impressão personalizada (arquivo ou Base64)
+ * - Aborto de operações em andamento
+ * - Reinício do terminal
+ * - Consulta de informações do dispositivo e estabelecimento
+ * - Verificação de recursos (impressora, NFC, chip, tarja, etc.)
+ *
+ * ### Tratamento de erros
+ * A maioria dos métodos assíncronos lança exceções específicas:
+ * - {@link PaymentError} → Erros de pagamento, validação ou comunicação
+ * - {@link PrintError}   → Falhas na impressão ou reimpressão
+ * - {@link AbordError}  → Erro ao tentar abortar operação
+ *
+ * ### Exemplo básico de uso
+ * ```ts
+ * await PagSeguro.initialize("SEU_CODIGO");
+ *
+ * const resultado = await PagSeguro.do_payment({
+ *   amount: 1000, // R$ 10.00
+ *   type: PaymentTypes.CREDIT,
+ *   installment_type: InstallmentTypes.SELLER_INSTALLMENT,
+ *   installments: 3,
+ *   print_receipt: true
+ * });
+ *
+ * console.log("NSU:", resultado.transaction_code);
+ * ```
+ *
+ * @module PagSeguro
+ */
+export default class PagSeguro {
+    /**
+     * Inicializa o terminal PagSeguro com o código de ativação fornecido.
+     *
+     * Deve ser chamado antes de qualquer outra operação.
+     * Após a inicialização bem-sucedida, o terminal fica autenticado e pronto para pagamentos.
+     *
+     * @param activation_code Código de ativação do terminal (fornecido pelo PagSeguro)
+     * @throws PaymentError Caso o código seja inválido ou ocorra falha na comunicação
+     *
+     * @example
+     * await PagSeguro.initialize("ABC123456");
+     */
+    static initialize(activation_code: string): void {
+        PosPagseguroHybridObject.initialize(activation_code);
+    };
+
+    /**
+     * Reinicia o terminal PagSeguro.
+     */
+    static reboot() { PosPagseguroHybridObject.reboot() }
+
+    /**
+     * Realiza um pagamento no terminal PagSeguro.
+     *
+     * Suporta todos os tipos de pagamento disponíveis (crédito, débito, voucher, PIX)
+     * e diferentes modalidades de parcelamento.
+     *
+     * @param data Dados do pagamento
+     * @param process_callback Callback opcional chamado com mensagens de progresso (ex: "APROXIME, INSIRA OU PASSE O CARTÃO")
+     * @returns Resultado completo da transação aprovada
+     * @throws PaymentError Em caso de erro de validação, rejeição ou falha na comunicação
+     *
+     * @example
+     * const tx = await PagSeguro.do_payment({
+     *   amount: 2500, // R$ 25.00
+     *   type: PaymentTypes.PIX,
+     *   installment_type: InstallmentTypes.NO_INSTALLMENT,
+     *   installments: 1,
+     *   print_receipt: true
+     * });
+     */
+    static async do_payment(data: PaymentData, process_callback: (message: string) => void = () => { }): Promise<TransactionResult> {
+        validate_payment_data(data);
+        const r = await PosPagseguroHybridObject.doPayment(data, process_callback);
+        if ("message" in r && "code" in r) throw new PaymentError(r.code, r.message);
+        return r;
+    };
+
+    /**
+     * Realiza o cancelamento ou estorno de uma transação previamente aprovada.
+     *
+     * Funciona apenas para transações realizadas no mesmo dia (regra PagSeguro).
+     * Para cancelamentos administrativos de dias anteriores, usar o portal.
+     *
+     * @param data Dados necessários para identificar a transação a ser cancelada
+     * @param process_callback Callback opcional com mensagens de progresso
+     * @returns Resultado da operação de cancelamento
+     * @throws PaymentError Em caso de erro de validação ou rejeição
+     */
+    static async void_payment(data: VoidPayData, process_callback: (message: string) => void = () => { }): Promise<TransactionResult> {
+        validate_void_pay_data(data);
+        const r = await PosPagseguroHybridObject.voidPayment(data, process_callback);
+        if ("message" in r && "code" in r) throw new PaymentError(r.code, r.message);
+        return r;
+    }
+
+    /**
+     * Aborta imediatamente qualquer operação em andamento no terminal
+     *
+     * @throws AbordError Caso o aborto não seja possível ou falhe
+     */
+    static abort_current_operation(): void {
+        const r = PosPagseguroHybridObject.abort();
+        if (r == undefined) return;
+        if ("message" in r && "code" in r) throw new AbordError(r.code, r.message);
+    }
+
+    /**
+     * Obtém os dados da última transação aprovada realizada no terminal.
+     *
+     * @returns Dados completos da transação (valor, NSU, bandeira, etc.)
+     * @throws PaymentError Se não houver transação aprovada ou em caso de erro
+     */
+    static get_last_approved_transaction(): TransactionResult{
+        const r = PosPagseguroHybridObject.getLastApprovedTransaction();
+        if ("message" in r && "code" in r) throw new PaymentError(r.code, r.message);
+        return r;
+    };
+
+    /**
+     * Reimprime a via do cliente da última transação aprovada.
+     *
+     * @returns Linhas impressas
+     * @throws PrintError Em caso de falha na impressora
+     */
+    static async reprint_customer_receipt(): Promise<number> {
+        const r = await PosPagseguroHybridObject.reprintCustomerReceipt();
+        if (typeof r === "number") return r;
+        throw new PrintError(r.code, r.message);
+    }
+
+    /**
+     * Reimprime a via do estabelecimento da última transação aprovada.
+     *
+     * @returns Linhas impressas
+     * @throws PrintError Em caso de falha
+     */
+    static async reprint_stablishment_receipt(): Promise<number> {
+        const r = await PosPagseguroHybridObject.reprintStablishmentReceipt();
+        if (typeof r === "number") return r;
+        throw new PrintError(r.code, r.message);
+    }
+
+    /**
+     * Verifica se há usuário autenticado.
+     */
+    static is_authenticated(): boolean {
+        return PosPagseguroHybridObject.isAuthenticated();
+    };
+
+    /**
+     * Verifica se o terminal está executando alguma operação no momento.
+     */
+    static is_busy(): boolean {
+        return PosPagseguroHybridObject.isServiceBusy();
+    };
+
+    /**
+     * Retorna o modelo do terminal PagSeguro.
+     */
+    static get_model(): string {
+        return PosPagseguroHybridObject.getModel();
+    };
+
+    /**
+     * Retorna os dados do usuário logado no terminal (vendedor).
+     */
+    static get_userdata(): UserData {
+        return PosPagseguroHybridObject.getUserData();
+    };
+
+    /**
+     * Retorna o número de série do terminal.
+     */
+    static get_serial_number(): string {
+        return PosPagseguroHybridObject.getSerialNumber();
+    };
+
+    /**
+     * Retorna os dados do estabelecimento cadastrado no terminal (subadquirente).
+     */
+    static get_sub_acquirer_data(): SubAcquirer | undefined {
+        return PosPagseguroHybridObject.getSubAcquirerData();
+    };
+
+    /**
+     * Imprime um arquivo de imagem armazenado no dispositivo.
+     *
+     * @param path Caminho completo do arquivo no filesystem
+     * @param quality Qualidade da impressão. Padrão: 1
+     * @param bottomPad Número de linhas em branco ao final. Padrão: 70
+     * @returns Linhas impressas
+     * @throws PrintError Em caso de falha
+     */
+    static async print_from_filepath(path: string, quality: number = 1, bottomPad = 70): Promise<number> {
+        const r = await PosPagseguroHybridObject.printFromFile(path, quality, bottomPad);
+        if (typeof r === "number") return r;
+        throw new PrintError(r.code, r.message);
+    };
+
+    /**
+     * Imprime uma imagem a partir de uma string Base64.
+     * @param base64str String no formato Base64 (sem prefixo data:image/...)
+     * @param quality Qualidade da impressão. Padrão: 1
+     * @param bottomPad Linhas em branco ao final. Padrão: 70
+     * @returns Linhas impressas
+     * @throws PrintError Em caso de falha
+     */
+    static async print_from_base64(base64str: string, quality: number = 1, bottomPad = 70): Promise<number> {
+        const r = await PosPagseguroHybridObject.printFromBase64(base64str, quality, bottomPad);
+        if (typeof r === "number") return r;
+        throw new PrintError(r.code, r.message);
+    };
+
+    /**
+     * Verificação de recursos disponíveis no terminal.
+     *
+     * Permite adaptar a UI conforme os módulos presentes.
+     */
+    static readonly capabilities = {
+        /** Verifica presença de módulo Bluetooth */
+        has_bluetooth() {
+            return PosPagseguroHybridObject.hasCapability(Capabilities.BLUETOOTH);
+        },
+
+        /** Verifica leitor de tarja magnética */
+        has_mag() {
+            return PosPagseguroHybridObject.hasCapability(Capabilities.MAG);
+        },
+
+        /** Verifica leitor de chip (EMV) */
+        has_icc() {
+            return PosPagseguroHybridObject.hasCapability(Capabilities.ICC);
+        },
+
+        /** Verifica suporte a Contactless/NFC */
+        has_picc() {
+            return PosPagseguroHybridObject.hasCapability(Capabilities.PICC);
+        },
+
+        /** Verifica presença de impressora térmica */
+        has_printer() {
+            return PosPagseguroHybridObject.hasCapability(Capabilities.PRINTER);
+        },
+
+        /** Verifica conexão Ethernet */
+        has_ethernet() {
+            return PosPagseguroHybridObject.hasCapability(Capabilities.ETHERNET);
+        },
+
+        /** Verifica modem 3G/4G */
+        has_modem() {
+            return PosPagseguroHybridObject.hasCapability(Capabilities.MODEM);
+        }
+    }
+}
+
+function validate_payment_data(data: PaymentData): void {
+    if (data.amount <= 0) throw new PaymentError("INVALID_ARG", "O valor deve ser maior que zero.");
+    if (data.installments < 1) throw new PaymentError("INVALID_ARG", "O número de parcelas deve ser pelo menos 1.");
+    if (!Object.values(PaymentTypes).includes(data.type)) throw new PaymentError("INVALID_ARG", "O tipo de pagamento informado não é válido.");
+    if (!Object.values(InstallmentTypes).includes(data.installment_type)) throw new PaymentError("INVALID_ARG", `O tipo de parcelamento informado não é válido.`);
+    if (data.user_reference !== undefined) {
+        const ref = String(data.user_reference);
+        const regex = /^[a-zA-Z0-9]+$/;
+        if (!regex.test(ref)) throw new PaymentError("INVALID_ARG", "A referência do usuário deve conter apenas letras ou números.");
+    };
+};
+
+function validate_void_pay_data(data: VoidPayData): void {
+    if (!data.transaction_code || typeof data.transaction_code !== 'string' || data.transaction_code.trim() === '') {
+        throw new PaymentError("INVALID_ARG", "O transaction_code é obrigatório e deve ser uma string não vazia.");
+    }
+    if (!data.transaction_id || typeof data.transaction_id !== 'string' || data.transaction_id.trim() === '') {
+        throw new PaymentError("INVALID_ARG", "O transaction_id é obrigatório e deve ser uma string não vazia.");
+    }
+    if (data.print_receipt !== undefined && typeof data.print_receipt !== 'boolean') {
+        throw new PaymentError("INVALID_ARG", "O print_receipt deve ser do tipo boolean.");
+    }
+    if (data.void_type !== undefined && !Object.values(VoidType).includes(data.void_type)) {
+        throw new PaymentError("INVALID_ARG", "O void_type informado não é válido.");
+    }
+}

package/src/types/device.ts

@@ -0,0 +1,97 @@
+
+export type SubAcquirer = {
+    name: string;
+    address: string;
+    city: string;
+    uf: string;
+    country: string;
+    zip_code: string;
+    mcc: string;
+    cnpj_cpf: string;
+    doc_type: string;
+    telephone: string;
+    full_name: string;
+    merchant_id: string;
+}
+
+export type UserData = {
+    address?: string;
+    city?: string;
+    cnpj_cpf?: string;
+    address_complement?: string;
+    company_name?: string;
+    nick_name?: string;
+    address_state?: string;
+    email?: string;
+}
+
+
+enum Capabilities {
+    /**
+     * Módulo de leitor de tarja magnética.
+     */
+    MAG = 1,
+    /**
+     * Módulo de leitor de chip.
+     */
+    ICC = 2,
+    /**
+     * Módulo de leitura por aproximação (Contactless).
+     */
+    PICC = 3,
+    /**
+     * Módulo de teclado seguro.
+     */
+    PED = 4,
+    /**
+     * Módulo de teclado externo.
+    */
+    KEYBOARD = 5,
+    /**
+     * Módulo de impressora.
+     */
+    PRINTER = 6,
+    /**
+     * Módulo de bluetooth.
+     */
+    BLUETOOTH = 7,
+    /**
+     * Módulo de caixa registradora.
+     */
+    CASH_BOX = 8,
+    /**
+     * Módulo de tela auxiliar.
+     */
+    CUSTOMER_DISPLAY = 9,
+    /**
+     * Módulo de rede.
+     */
+    ETHERNET = 10,
+    /**
+     * Módulo de leitor de digital.
+     */
+    FINGERPRINT_READER = 11,
+    /**
+     * Módulo de acelerômetro.
+     */
+    G_SENSOR = 12,
+    /**
+     * Módulo de saída HDMI.
+     */
+    HDMI = 13,
+    /**
+     * Módulo de leitor de cartões.
+     */
+    ID_CARD_READER = 14,
+    /**
+     * Módulo de SM.
+     */
+    SM = 15,
+    /**
+     * Módulo de modem.
+     */
+    MODEM = 16
+}
+
+
+export { Capabilities }

package/src/types/exceptions.ts

@@ -0,0 +1,19 @@
+
+
+export type CustomError = {
+    code: string,
+    message: string
+}
+
+class CustomException extends Error {
+    code: string;
+    constructor(code: string, message: string) {
+        super(message);
+        this.code = code;
+    }
+};
+
+
+export class PaymentError extends CustomException{};
+export class PrintError extends CustomException{};
+export class AbordError extends CustomException{};