npm package: @ferreira-dev/validation-core
Description: Biblioteca TypeScript completa para desenvolvimento de aplicações de validação bancária, incluindo funcionalidades essenciais para internet banking, PIX e transferências bancárias no Brasil.
Author: Ferreira Dev
Latest version: 1.1.0

# Banking Core - Biblioteca de Internet Banking

Uma biblioteca TypeScript completa para desenvolvimento de aplicações de internet banking, com validações, formatações, segurança e funcionalidades bancárias essenciais.

## 🚀 Características

- **Validações robustas**: CPF, CNPJ, email, telefone, senha, contas bancárias e chaves PIX
- **Formatação de dados**: Moeda, datas e números no padrão brasileiro
- **Segurança**: Criptografia AES-256, hash de senhas e mascaramento de dados sensíveis
- **Funcionalidades bancárias**: Transferências PIX, TED, DOC e internas
- **Compatibilidade**: Funciona tanto em React quanto React Native
- **TypeScript**: Totalmente tipado para melhor experiência de desenvolvimento

## 📦 Instalação

```bash
npm install @ferreira-dev/banking-core
```

## 🔧 Configuração

```typescript
import { 
  isValidCPF, 
  formatCurrency, 
  transferService,
  encryptionService 
} from '@ferreira-dev/banking-core';

// Configure a URL da API (opcional)
process.env.API_URL = 'https://sua-api-bancaria.com';
```

## 📚 Uso

### Validações

#### CPF
```typescript
import { isValidCPF, formatCPF } from '@ferreira-dev/banking-core';

const cpf = '123.456.789-09';
if (isValidCPF(cpf)) {
  console.log('CPF válido');
  const formatted = formatCPF(cpf); // 123.456.789-09
}
```

#### CNPJ
```typescript
import { isValidCNPJ, formatCNPJ } from '@ferreira-dev/banking-core';

const cnpj = '12.345.678/0001-90';
if (isValidCNPJ(cnpj)) {
  console.log('CNPJ válido');
  const formatted = formatCNPJ(cnpj); // 12.345.678/0001-90
}
```

#### Email
```typescript
import { isValidEmail, normalizeEmail } from '@ferreira-dev/banking-core';

const email = 'usuario@exemplo.com';
if (isValidEmail(email)) {
  const normalized = normalizeEmail(email); // usuario@exemplo.com
}
```

#### Telefone
```typescript
import { isValidPhone, formatPhone, isMobile } from '@ferreira-dev/banking-core';

const phone = '11987654321';
if (isValidPhone(phone)) {
  const formatted = formatPhone(phone); // (11) 98765-4321
  const isMobilePhone = isMobile(phone); // true
}
```

#### Senha
```typescript
import { validatePassword, generatePasswordSuggestions } from '@ferreira-dev/banking-core';

const password = 'MinhaSenha123!';
const result = validatePassword(password);

if (result.isValid) {
  console.log(`Senha forte! Score: ${result.score}/100`);
} else {
  console.log('Erros:', result.errors);
  const suggestions = generatePasswordSuggestions();
}
```

#### Conta Bancária
```typescript
import { isValidBankAccount, getBankName } from '@ferreira-dev/banking-core';

const account = {
  bankCode: '001',
  agency: '1234',
  account: '12345-6',
  accountType: 'corrente'
};

if (isValidBankAccount(account)) {
  const bankName = getBankName(account.bankCode); // 'Banco do Brasil'
}
```

#### Chave PIX
```typescript
import { isValidPixKey, detectPixKeyType, generateRandomPixKey } from '@ferreira-dev/banking-core';

const pixKey = {
  type: 'cpf',
  value: '123.456.789-09'
};

if (isValidPixKey(pixKey)) {
  console.log('Chave PIX válida');
}

// Detecta automaticamente o tipo
const detectedType = detectPixKeyType('usuario@email.com'); // 'email'

// Gera chave aleatória
const randomKey = generateRandomPixKey();
```

### Formatação

#### Moeda
```typescript
import { formatCurrency } from '@ferreira-dev/banking-core';

const value = 1234.56;
const formatted = formatCurrency(value); // R$ 1.234,56
const usd = formatCurrency(value, 'en-US', 'USD'); // $1,234.56
```

#### Data
```typescript
import { formatDate, formatDateTime, formatRelativeTime } from '@ferreira-dev/banking-core';

const date = new Date();
const shortDate = formatDate(date); // 15/12/2024
const longDate = formatDate(date, 'long'); // domingo, 15 de dezembro de 2024
const dateTime = formatDateTime(date); // 15/12/2024 14:30
const relative = formatRelativeTime(date); // agora mesmo
```

### Segurança

#### Criptografia
```typescript
import { encryptionService } from '@ferreira-dev/banking-core';

// Gera chave de criptografia
const key = await encryptionService.generateKey();

// Criptografa dados
const encrypted = await encryptionService.encrypt('dados sensíveis', key);

// Descriptografa dados
const decrypted = await encryptionService.decrypt(
  encrypted.encrypted, 
  key, 
  encrypted.iv
);

// Mascara dados sensíveis
const maskedCard = encryptionService.maskCardNumber('1234567890123456'); // ************3456
const maskedCPF = encryptionService.maskCPF('123.456.789-09'); // ***.***.***-09
```

#### Hash de Senha
```typescript
import { encryptionService } from '@ferreira-dev/banking-core';

// Gera hash da senha
const { hash, salt } = await encryptionService.hashPassword('minhaSenha123');

// Verifica senha
const isValid = await encryptionService.verifyPassword('minhaSenha123', hash, salt);
```

### Funcionalidades Bancárias

#### Transferências
```typescript
import { transferService } from '@ferreira-dev/banking-core';

const transferRequest = {
  fromAccount: 'conta-origem',
  toAccount: 'conta-destino',
  amount: 100.00,
  description: 'Pagamento de serviço',
  transferType: 'pix'
};

try {
  const result = await transferService.executeTransfer(transferRequest);
  console.log(`Transferência ${result.status}: ${result.id}`);
} catch (error) {
  console.error('Erro na transferência:', error.message);
}

// Verifica limites
const limits = await transferService.getTransferLimits('conta-id', 'pix');
console.log(`Limite diário: R$ ${limits.dailyLimit}`);
```

### Autenticação

#### Login
```typescript
import { login } from '@ferreira-dev/banking-core';

try {
  const response = await login('usuario', 'senha');
  console.log('Token:', response.token);
  console.log('Expira em:', response.expiresIn);
} catch (error) {
  console.error('Erro no login:', error.message);
}
```

#### Refresh Token
```typescript
import { refreshToken } from '@ferreira-dev/banking-core';

try {
  const response = await refreshToken('refresh-token-atual');
  console.log('Novo token:', response.token);
} catch (error) {
  console.error('Erro no refresh:', error.message);
}
```

## 🏗️ Estrutura do Projeto

```
src/
├── auth/           # Autenticação e tokens
├── validation/     # Validações de dados
├── formatting/     # Formatação de dados
├── security/       # Criptografia e segurança
├── banking/        # Funcionalidades bancárias
├── http/           # Cliente HTTP
└── index.ts        # Exportações principais
```

## 🔒 Segurança

- Criptografia AES-256-GCM para dados sensíveis
- Hash SHA-256 com salt para senhas
- Validações rigorosas de entrada
- Mascaramento automático de dados sensíveis
- Verificação de limites de transferência

## 📱 Compatibilidade

- ✅ React (Web)
- ✅ React Native
- ✅ Node.js
- ✅ TypeScript
- ✅ JavaScript (ES6+)

## 🧪 Testes

```bash
# Em desenvolvimento - adicione testes unitários
npm test
```

## 📄 Licença

MIT

## 🤝 Contribuição

Contribuições são bem-vindas! Por favor, abra uma issue ou pull request.

## 📞 Suporte

Para dúvidas ou suporte, entre em contato através das issues do GitHub.

---

**Desenvolvido com ❤️ para o sistema bancário brasileiro**