@dryinov8/zumbopay-ts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Salvador Matavele
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+# @salvamatavele/zumbopay-ts
+
+[![NPM Version](https://img.shields.io/npm/v/@salvamatavele/zumbopay-ts?color=blue)](https://www.npmjs.com/package/@salvamatavele/zumbopay-ts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+SDK oficial em **TypeScript / JavaScript** e componentes **React** para integração do gateway de pagamentos **[ZumboPay](https://zumbopay.com)** em Moçambique.
+
+Compatível com **Node.js**, **Next.js** (App Router & Pages), **React**, **Vite**, **Remix** e **Express**.
+
+---
+
+## 🚀 Funcionalidades
+
+* 🇲🇿 **Suporte a Carteiras Móveis Moçambicanas:**
+  * **Vodacom M-Pesa** (prefixos `84`, `85`)
+  * **Movitel e-Mola** (prefixos `86`, `87`)
+  * **Tmcel mKesh** (prefixos `82`, `83`)
+* 💳 **Cartões Bancários:** Checkout hospedado com suporte a cartões **Visa** e **Mastercard** (nacionais e internacionais).
+* 🎛️ **Interruptor Global / Kill-Switch (`enabled: boolean`):** Ative ou silencie o gateway dinamicamente via código (`enabled: false`) ou variável de ambiente (`ZUMBOPAY_ENABLED=false`).
+* ⚛️ **Componentes & Hooks React Prontos:** Componente `<ZumboPayModal />` acessível com abas e deteção visual de operadora, e hook `useZumboPay()`.
+* 🛡️ **Segurança & Webhooks:** Validação criptográfica de assinaturas HMAC-SHA256 em tempo constante contra *timing attacks*.
+* 📦 **Dual Build:** Suporta módulos **ESM** (`import`) e **CommonJS** (`require`), com tipos TypeScript completos (`.d.ts`).
+
+---
+
+## 📦 Instalação
+
+```bash
+# npm
+npm install @salvamatavele/zumbopay-ts
+
+# pnpm
+pnpm add @salvamatavele/zumbopay-ts
+
+# yarn
+yarn add @salvamatavele/zumbopay-ts
+```
+
+*(Se pretender utilizar os componentes React, certifique-se de que tem `react` e `react-dom` instalados no seu projeto).*
+
+---
+
+## ⚙️ Configuração e Variáveis de Ambiente
+
+Crie ou adicione ao seu ficheiro `.env`:
+
+```env
+# Credenciais Principais
+ZUMBOPAY_API_KEY=sua_chave_secreta_aqui
+ZUMBOPAY_MERCHANT_ID=seu_merchant_id_aqui
+ZUMBOPAY_WEBHOOK_SECRET=seu_webhook_secret_aqui
+
+# Carteiras Pré-configuradas (UUIDs) - Opcional
+# (Se deixar vazio, o SDK descobre automaticamente os UUIDs via GET /wallets)
+ZUMBOPAY_WALLET_MPESA=uuid-carteira-mpesa
+ZUMBOPAY_WALLET_EMOLA=uuid-carteira-emola
+ZUMBOPAY_WALLET_MKESH=uuid-carteira-mkesh
+ZUMBOPAY_WALLET_CARD=uuid-carteira-cartao
+
+# Gatilho de silenciamento global / Kill-Switch (Opcional - padrão: true)
+ZUMBOPAY_ENABLED=true
+```
+
+---
+
+## 💼 Como Configurar e Passar as Carteiras (Wallets)
+
+O `zumbopay-ts` oferece total flexibilidade para passar os UUIDs das suas carteiras do painel ZumboPay:
+
+### Forma 1: Automática via `.env` (Recomendado para Node.js / Next.js)
+Basta definir as variáveis no `.env` como mostrado acima. O cliente lê-as automaticamente:
+```typescript
+const zumboPay = new ZumboPayClient({
+  apiKey: process.env.ZUMBOPAY_API_KEY!,
+  merchantId: process.env.ZUMBOPAY_MERCHANT_ID!,
+  // As carteiras MPESA, EMOLA, MKESH e CARD são lidas automaticamente do .env!
+});
+```
+
+### Forma 2: No Construtor do Cliente
+Pode passar o objeto `wallets` explicitamente no código:
+```typescript
+const zumboPay = new ZumboPayClient({
+  apiKey: '...',
+  merchantId: '...',
+  wallets: {
+    mpesa: 'd1a2b3c4-....', // UUID carteira Vodacom M-Pesa
+    emola: 'e5f6a7b8-....', // UUID carteira Movitel e-Mola
+    mkesh: 'c9d0e1f2-....', // UUID carteira Tmcel mKesh
+    card:  'a3b4c5d6-....', // UUID carteira Cartão Bancário
+  },
+});
+```
+
+### Forma 3: No Componente React (`<ZumboPayModal />`)
+```tsx
+<ZumboPayModal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  config={{
+    apiKey: 'pk_live_...',
+    merchantId: 'mer_...',
+    wallets: {
+      mpesa: 'uuid-mpesa',
+      emola: 'uuid-emola',
+      mkesh: 'uuid-mkesh',
+      card:  'uuid-card',
+    },
+  }}
+  amount={1500}
+/>
+```
+
+### Forma 4: Por Transação Pontual (Sobrescrita Ad-hoc)
+```typescript
+await zumboPay.stkPush({
+  amount: 250,
+  phone: '841234567',
+  walletId: 'uuid-especifico-desta-transacao', // Força este UUID
+});
+```
+
+### Forma 5: Auto-descoberta Dinâmica
+Se **não** passar nenhum UUID de carteira, o SDK consulta automaticamente a rota `GET /wallets` da sua conta ZumboPay e mapeia a carteira correta para M-Pesa, e-Mola, mKesh ou Cartão (com cache em memória de 10 minutos).
+
+
+---
+
+## 📖 Guia de Utilização Rápida
+
+### 1. Iniciar STK Push (M-Pesa, e-Mola ou mKesh) no Backend
+
+```typescript
+import { ZumboPayClient } from 'zumbopay-ts';
+
+const zumboPay = new ZumboPayClient({
+  apiKey: process.env.ZUMBOPAY_API_KEY!,
+  merchantId: process.env.ZUMBOPAY_MERCHANT_ID!,
+  // Ativação / Kill-Switch (lê automaticamente process.env.ZUMBOPAY_ENABLED)
+  enabled: process.env.ZUMBOPAY_ENABLED !== 'false',
+});
+
+// Envia prompt STK para o telemóvel do cliente
+const response = await zumboPay.stkPush({
+  amount: 250.00,
+  phone: '841234567', // Detecta automaticamente Vodacom M-Pesa
+  reference: 'PROP-2026-001',
+  customerName: 'Manuel Cossa',
+  description: 'Pagamento de Propina Escolar',
+});
+
+if (response.success) {
+  console.log('Status:', response.status); // 'pending' | 'success'
+  console.log('Mensagem:', response.message);
+} else {
+  console.error('Falha:', response.message);
+}
+```
+
+---
+
+### 2. Criar Checkout Hospedado (Cartão Visa/Mastercard)
+
+```typescript
+const checkout = await zumboPay.createCheckout({
+  amount: 1500.00,
+  title: 'Matrícula Anual',
+  reference: 'MAT-2026-890',
+  returnUrl: 'https://seu-sistema.ac.mz/pagamento/sucesso',
+  cancelUrl: 'https://seu-sistema.ac.mz/pagamento/cancelado',
+  channels: ['card', 'mpesa', 'emola', 'mkesh'],
+});
+
+if (checkout.success && checkout.checkoutUrl) {
+  // Redirecionar o cliente para a página de pagamento
+  console.log('URL de pagamento:', checkout.checkoutUrl);
+}
+```
+
+---
+
+### 3. Consultar Estado da Transação
+
+```typescript
+const status = await zumboPay.getStatus('PROP-2026-001');
+
+console.log('Está pago?', status.paid); // true | false
+console.log('Estado:', status.status);   // 'success' | 'pending' | 'failed'
+```
+
+---
+
+## 🎛️ Gatilho de Silenciamento / Kill-Switch
+
+Pode desativar ou suspender o gateway a qualquer momento sem necessidade de alterar o código dos seus endpoints:
+
+```typescript
+// 1. Via variável de ambiente:
+// ZUMBOPAY_ENABLED=false
+
+// 2. Via inicialização:
+const client = new ZumboPayClient({
+  apiKey: '...',
+  merchantId: '...',
+  enabled: false, // Silencia STK e checkouts
+});
+
+// 3. Via controlo dinâmico em tempo de execução:
+client.setEnabled(false);
+
+const res = await client.stkPush({ amount: 100, phone: '841234567' });
+// Retorna imediatamente:
+// { success: false, status: 'disabled', message: 'O gateway de pagamento ZumboPay está temporariamente desativado.' }
+// Nenhuma chamada externa é feita!
+```
+
+---
+
+## ⚛️ Utilização com React / Next.js
+
+Importe o componente ou o hook através do submódulo `zumbopay-ts/react`:
+
+### Opção A: Modal Completo (`<ZumboPayModal />`)
+
+```tsx
+import React, { useState } from 'react';
+import { ZumboPayModal } from 'zumbopay-ts/react';
+
+export function CheckoutButton() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button 
+        onClick={() => setIsOpen(true)}
+        className="px-4 py-2 bg-blue-600 text-white rounded-lg font-bold"
+      >
+        Pagar com ZumboPay
+      </button>
+
+      <ZumboPayModal
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        config={{
+          apiKey: 'pk_live_...',
+          merchantId: 'mer_...',
+          enabled: true,
+        }}
+        amount={1500}
+        reference="PEDIDO-994"
+        title="Inscrição em Exame"
+        onPaymentSuccess={(payment) => {
+          alert('Pagamento recebido com sucesso!');
+          setIsOpen(false);
+        }}
+      />
+    </>
+  );
+}
+```
+
+### Opção B: Hook Personalizado (`useZumboPay`)
+
+```tsx
+import { useZumboPay } from 'zumbopay-ts/react';
+
+export function CustomPaymentForm() {
+  const {
+    phone,
+    setPhone,
+    operator,
+    isLoading,
+    status,
+    errorMessage,
+    initiateStk,
+  } = useZumboPay({
+    config: {
+      apiKey: '...',
+      merchantId: '...',
+    },
+    onSuccess: (res) => console.log('Sucesso!', res),
+  });
+
+  return (
+    <div>
+      <input
+        type="tel"
+        value={phone}
+        onChange={(e) => setPhone(e.target.value)}
+        placeholder="84 / 86 / 82..."
+      />
+      <span>Operadora detectada: {operator}</span>
+
+      <button
+        disabled={isLoading}
+        onClick={() => initiateStk({ amount: 500 })}
+      >
+        {isLoading ? 'A processar...' : 'Pagar 500 MZN'}
+      </button>
+
+      {errorMessage && <p className="text-red-500">{errorMessage}</p>}
+    </div>
+  );
+}
+```
+
+---
+
+## 🔐 Validação de Webhook (Node.js / Express / Next.js)
+
+Para garantir que as notificações de pagamento recebidas no seu servidor provêm legitimamente do ZumboPay:
+
+### Exemplo em Next.js (App Router: `app/api/webhooks/zumbopay/route.ts`)
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { verifyWebhookSignature } from 'zumbopay-ts';
+
+export async function POST(req: NextRequest) {
+  const rawBody = await req.text();
+  const signature = req.headers.get('x-signature') || req.headers.get('x-zumbopay-signature') || '';
+  const secret = process.env.ZUMBOPAY_WEBHOOK_SECRET!;
+
+  // Validação criptográfica HMAC-SHA256
+  const isValid = verifyWebhookSignature(rawBody, signature, secret);
+
+  if (!isValid) {
+    return NextResponse.json({ error: 'Assinatura inválida' }, { status: 401 });
+  }
+
+  const event = JSON.parse(rawBody);
+
+  if (event.event === 'payment.succeeded') {
+    const { reference, amount } = event.data;
+    // Liquidar fatura na base de dados
+  }
+
+  return NextResponse.json({ received: true });
+}
+```
+
+---
+
+## 🛠️ Utilitários de Telefonia de Moçambique
+
+```typescript
+import { normalizePhone, detectOperator, isValidMozPhone } from 'zumbopay-ts';
+
+normalizePhone('+258 (84) 123-4567'); // '258841234567'
+detectOperator('841234567');           // 'mpesa'
+detectOperator('861234567');           // 'emola'
+detectOperator('821234567');           // 'mkesh'
+isValidMozPhone('841234567');          // true
+isValidMozPhone('12345');              // false
+```
+
+---
+
+## 🏷️ Versionamento e Política de Releases
+
+Este projeto segue rigorosamente o padrão **[Semantic Versioning (SemVer)](https://semver.org/)**:
+- **MAJOR (`X.0.0`)**: Mudanças incompatíveis na API.
+- **MINOR (`0.X.0`)**: Adição de novas funcionalidades retrocompatíveis (ex: novos canais ou carteiras).
+- **PATCH (`0.0.X`)**: Correções de bugs e otimizações retrocompatíveis.
+
+Consulte o histórico de alterações em `CHANGELOG.md`.
+
+---
+
+## 📄 Licença
+
+Distribuído sob a licença MIT. Consulte `LICENSE` para mais detalhes.
+
+Desenvolvido por **[Salvador Matavele](https://github.com/salvamatavele)**.