npm package: @mutualbank/pay-utils
Description: MutualbankUtils - Queue adapters, shared utilities and domain entities
Latest version: 0.1.3

# MutualbankUtils

Biblioteca compartilhada para os microsserviços do Motor de Pagamento. Contém adaptadores de fila, entidades de domínio, utilitários e integrações com provedores de pagamento.

## Stack

- **Runtime:** Node.js
- **Linguagem:** TypeScript 5
- **Validação:** Zod
- **Logging:** Winston
- **Database:** PostgreSQL (pg)
- **Mensageria:** RabbitMQ (amqplib), AWS SQS (@aws-sdk/client-sqs)
- **HTTP Client:** Axios

## Estrutura

```
shared/
├── aplication/
│   ├── @types/              # Tipagens de provedores
│   ├── factory/             # Factories para Queue e Payment
│   └── interfaces/          # Contratos de serviços
├── domain/
│   ├── enums/               # Enums de filas e eventos
│   ├── errors/              # Classes de erro customizadas
│   ├── BaseDomain.ts        # Classe base para entidades
│   ├── Transaction.ts       # Entidade de transação
│   ├── ReceivedWebhookProvider.ts
│   └── RoutingAttempts.ts
├── infra/
│   ├── database/            # Conexão PostgreSQL
│   ├── queue/adapters/      # Adaptadores RabbitMQ e SQS
│   └── services/            # Serviços de pagamento e eventos
├── utils/                   # Utilitários (Logger, Document, PixKey)
└── index.ts                 # Exports públicos
```

## Módulos

### Queue Adapters

Suporte para RabbitMQ e AWS SQS com interface unificada.

```typescript
import { QueueFactory } from 'mutualbankutils';

// Criação automática baseada em env vars
const queue = QueueFactory.createQueue();

// Ou configuração manual
const rabbitQueue = QueueFactory.create({
  type: 'rabbitmq',
  host: 'localhost',
  port: 5672,
  username: 'guest',
  password: 'guest',
  vhost: '/'
});

// Conexão
await queue.connect();

// Publicar mensagem
await queue.publish(EnumQueueName.PAYMENT_ORCHESTRATOR_PIX_IN, {
  externalId: 'tx-123',
  providerCode: 'A55',
  callbackUrls: ['https://callback.url'],
  payload: { /* dados */ }
});

// Consumir mensagens
await queue.consume(EnumQueueName.PAYMENT_ORCHESTRATOR_PIX_OUT, async (message) => {
  console.log(message.body);
  await queue.ack(message);
});
```

### Filas Disponíveis

| Fila | Descrição |
|------|-----------|
| `PAYMENT_ORCHESTRATOR_PIX_IN` | Transações PIX de entrada |
| `PAYMENT_ORCHESTRATOR_PIX_OUT` | Transações PIX de saída |
| `PAYMENT_ORCHESTRATOR_PIX_SEND_WEBHOOK` | Envio de webhooks |
| `PAYMENT_ORCHESTRATOR_TRANSACTION_UPDATED` | Atualizações de transação |

### Domain Entities

#### Transaction

```typescript
import { Transaction, TransactionType, PaymentMethod } from 'mutualbankutils';

const transaction = Transaction.create({
  amount: 10000,
  type: TransactionType.PIX_IN,
  providerCode: 'A55',
  externalId: 'ext-123',
  method: PaymentMethod.PIX,
  client: 'client-id'
});

// Status transitions
transaction.pending();
transaction.processing();
transaction.completed();
transaction.failed();
transaction.cancelled();
transaction.refunded();

// Acesso aos dados
const status = transaction.get('status');
const payload = transaction.payload();
```

#### Status de Transação

| Status | Descrição |
|--------|-----------|
| `created` | Transação criada |
| `pending` | Aguardando processamento |
| `processing` | Em processamento |
| `completed` | Concluída com sucesso |
| `failed` | Falha no processamento |
| `cancelled` | Cancelada |
| `refunded` | Estornada |

### Payment Processors

Factory para criar processadores de pagamento por provedor.

```typescript
import { PaymentProcessorFactory } from 'mutualbankutils';

const processor = PaymentProcessorFactory.create('A55');
// ou
const processor = PaymentProcessorFactory.create('PAYZU');
```

Provedores suportados:
- **A55** - Integração com A55
- **PAYZU** - Integração com Payzu
- **FAKE** - Mock para testes

### Errors

Classes de erro customizadas para tratamento padronizado.

```typescript
import { NotFound, NotSupported, UnauthorizedAccess, BaseError } from 'mutualbankutils';

throw new NotFound('Transaction not found');
throw new NotSupported('Feature not supported');
throw new UnauthorizedAccess('Invalid credentials');
```

### Utils

#### Logger

```typescript
import { Logger } from 'mutualbankutils/shared/utils/Logger';

Logger.info('Mensagem informativa', { transactionId: '123' });
Logger.warn('Aviso', { context: 'webhook' });
Logger.error('Erro crítico', { error: err });
Logger.debug('Debug info', { data: payload });
```

#### Document

Validação de CPF e CNPJ.

```typescript
import { Document } from 'mutualbankutils/shared/utils/Document';

Document.validateCPF('123.456.789-09'); // true/false
Document.validateCNPJ('12.345.678/0001-90'); // true/false
```

#### PixKey

Identificação e formatação de chaves PIX.

```typescript
import { PixKey } from 'mutualbankutils/shared/utils/PixKey';

// Identificar tipo da chave
PixKey.identifyPixKey('123.456.789-09'); // 'cpf'
PixKey.identifyPixKey('email@teste.com'); // 'email'
PixKey.identifyPixKey('11999999999'); // 'phone'

// Formatar chave
PixKey.formatPixKey('(11) 99999-9999'); // '5511999999999'
```

## Variáveis de Ambiente

### Queue

| Variável | Descrição | Default |
|----------|-----------|---------|
| `QUEUE_TYPE` | Tipo de fila (rabbitmq, sqs) | `sqs` |

### RabbitMQ

| Variável | Descrição | Default |
|----------|-----------|---------|
| `RABBITMQ_HOST` | Host do RabbitMQ | `localhost` |
| `RABBITMQ_PORT` | Porta | `5672` |
| `RABBITMQ_USER` | Usuário | `guest` |
| `RABBITMQ_PASSWORD` | Senha | `guest` |
| `RABBITMQ_VHOST` | Virtual Host | `/` |

### AWS SQS

| Variável | Descrição | Default |
|----------|-----------|---------|
| `SQS_ENDPOINT` | Endpoint SQS | - |
| `SQS_REGION` | Região AWS | `us-east-1` |
| `SQS_ACCESS_KEY` | Access Key | - |
| `SQS_SECRET_KEY` | Secret Key | - |

### Logger

| Variável | Descrição | Default |
|----------|-----------|---------|
| `SERVICE_NAME` | Nome do serviço para logs | - |
| `LOG_LEVEL` | Nível de log | `info` |

## Instalação

```bash
npm install
npm run build
```

## Scripts

| Comando | Descrição |
|---------|-----------|
| `npm run build` | Compila TypeScript para dist/ |

## Uso nos Microsserviços

```typescript
// Import direto do dist
import { 
  Transaction, 
  QueueFactory, 
  NotFound,
  EnumQueueName 
} from '../lib/MutualbankUtils/dist';

// Import de utils específicos
import { Logger } from '../lib/MutualbankUtils/shared/utils/Logger';
```