@dueheads/citi-bank-boleto-sdk/README.md

SDK para registro de boletos na API do Citibank via mTLS.

# SDK para Integração de Boletos com CitiBank

Este é um SDK para Node.js, escrito em TypeScript, que facilita a integração com a API de registro de boletos do CitiBank. Ele abstrai a complexidade da comunicação SOAP e da construção do XML, oferecendo uma interface moderna e fluida para o desenvolvedor.

## Funcionalidades

* **Padrão Builder:** Crie boletos de forma legível e segura, encadeando métodos (`setBeneficiario`, `setPagador`, etc.).
* **Suporte a Payload Direto:** Para flexibilidade, permite o envio do objeto completo do boleto de uma só vez.
* **Tratamento de Respostas com Hooks:** Utilize `onSuccess`, `onError` e `onFail` para lidar com os diferentes cenários de resposta da API de forma assíncrona.
* **Tipagem Forte com TypeScript:** Aproveite a segurança e o autocompletar do TypeScript com interfaces bem definidas para todas as estruturas de dados.
* **Modo de Depuração:** Ative logs detalhados para facilitar a identificação de problemas durante a integração.

## Instalação

```bash
npm install @dueheads/citi-bank-boleto-sdk --save
```

## Configuração

Primeiro, importe e instancie o SDK, fornecendo a configuração necessária, incluindo os caminhos para seus certificados de segurança.

```typescript
import { CitiBankBoletoSDK } from '@dueheads/citi-bank-boleto-sdk';

const sdk = new CitiBankBoletoSDK({
    certPath: './certs/cert.crt',
    keyPath: './certs/private.key',
    rejectUnauthorized: false, // Em produção, use 'true'.
    debug: true, // Ativa logs detalhados no console.
});
```

## Como Usar

Existem duas maneiras principais de registrar um boleto.

### Exemplo 1: Usando o Padrão Builder (Recomendado)

Este método é mais verboso, porém mais seguro e legível, pois utiliza métodos específicos para cada parte do boleto.

```typescript
import { 
    CitiBankBoletoSDK,
    SuccessResponse, 
    ErrorResponse, 
    SoapFaultResponse,
    BeneficiarioData,
    PagadorData,
    SacadorData,
    DocumentoData
} from '@dueheads/citi-bank-boleto-sdk';

// 1. Defina os dados do boleto
const beneficiario: BeneficiarioData = { /* ... */ };
const pagador: PagadorData = { /* ... */ };
const sacador: SacadorData = { /* ... */ };
const documento: DocumentoData = { /* ... */ };

// 2. Registre os hooks e encadeie os métodos para construir e enviar o boleto
try {
    await sdk
        .onSuccess((res: SuccessResponse) => {
            console.log('SUCESSO (Builder):', res);
        })
        .onError((res: ErrorResponse) => {
            console.error('ERRO DE NEGÓCIO (Builder):', res);
        })
        .onFail((error: SoapFaultResponse | Error) => {
            console.error('FALHA GERAL (Builder):', error);
        })
        .setBeneficiario(beneficiario)
        .setPagador(pagador)
        .setSacador(sacador)
        .setDocumento(documento)
        .registraBoleto(); // O método send() dispara o processo

} catch (error) {
    console.error('Ocorreu um erro fatal na execução do SDK (Builder):', error);
}
```

### Exemplo 2: Usando o Payload Completo

Este método é útil se você já possui o objeto completo do boleto.

```typescript
import { 
    CitiBankBoletoSDK,
    BoletoPayload 
} from '@dueheads/citi-bank-boleto-sdk';

// 1. Monte o objeto completo do boleto
const boletoCompleto: BoletoPayload = {
    dadosBeneficiario: { /* ... */ },
    dados: {
        pagador: { /* ... */ },
        sacador: { /* ... */ },
        documento: { /* ... */ }
    }
};

// 2. Registre os hooks e chame o método de registro
try {
    sdk.onSuccess((res) => { /* ... */ })
       .onError((res) => { /* ... */ })
       .onFail((err) => { /* ... */ });

    await sdk.registraBoletoWithPayload(boletoCompleto);

} catch (error) {
    console.error('Ocorreu um erro fatal na execução do SDK (Payload):', error);
}
```

## Tratamento de Respostas (Hooks)

* `.onSuccess(callback)`: É chamado quando o boleto é registrado com sucesso. A callback recebe um objeto `SuccessResponse`.
* `.onError(callback)`: É chamado quando a API retorna um erro de negócio, como um campo inválido. A callback recebe um objeto `ErrorResponse` com um array de erros detalhados.
* `.onFail(callback)`: É chamado em caso de falha na comunicação (ex: erro de certificado, timeout, SOAP Fault) ou exceção interna do SDK.

## Interfaces

Todas as estruturas de dados (`BoletoPayload`, `PagadorData`, `SuccessResponse`, etc.) são tipadas e exportadas pelo pacote para garantir a consistência e segurança do seu código.