# Providers

Um **provider** é o adaptador de um serviço de CEP. A unicep traz quatro, todos funcionam direto
no navegador (os serviços liberam CORS) e devolvem o mesmo `Address`.

| Função | Serviço | Traz `complement` | Traz `ibgeCode` |
| --- | --- | --- | --- |
| `viaCep()` | [ViaCEP](https://viacep.com.br) | sim | sim |
| `brasilApi()` | [BrasilAPI](https://brasilapi.com.br) (CEP v2) | não | sim |
| `openCep()` | [OpenCEP](https://opencep.com) | sim | sim |
| `awesomeApi()` | [AwesomeAPI](https://docs.awesomeapi.com.br/api-cep) | não | sim |

O `defaultProviders()` devolve os quatro, nessa ordem.

## Escolhendo e ordenando

A ordem da lista é a prioridade. Passe só os que quiser, na ordem que preferir:

```ts
import { Unicep, brasilApi, openCep, viaCep } from '@unicep/core';

const unicep = new Unicep({
  providers: [brasilApi(), viaCep(), openCep()],
});
```

## Configurando um provider

Todos os providers embutidos aceitam as mesmas opções:

| Opção | O que faz |
| --- | --- |
| `fetch` | Sua própria implementação de `fetch` (padrão: `globalThis.fetch`). Útil para testes e proxies. |
| `baseUrl` | Troca o endereço do serviço, para usar um proxy ou uma instância própria. |

```ts
import { Unicep, brasilApi, viaCep } from '@unicep/core';

const unicep = new Unicep({
  providers: [
    viaCep({ baseUrl: 'https://meu-proxy.exemplo.com/viacep' }),
    brasilApi({ fetch: meuFetch }),
  ],
});
```

Para aplicar as mesmas opções a todos de uma vez: `defaultProviders({ fetch: meuFetch })`.

**Note:** No navegador, cada provider só envia o cabeçalho `Accept`, então não há preflight de CORS. Se
  usar um proxy seu, mantenha assim.

## Criando o seu provider

Para usar um serviço que a unicep não tem, implemente a interface `CepProvider`:

```ts
import { CepNotFoundError, ProviderError, type CepProvider } from '@unicep/core';

const meuProvider: CepProvider = {
  name: 'minha-api',
  async lookup(cep, { signal }) {
    const response = await fetch(`https://minha-api.exemplo.com/cep/${cep}`, { signal });
    if (response.status === 404) throw new CepNotFoundError(cep);
    if (!response.ok) throw new ProviderError('minha-api', `HTTP ${response.status}`);

    const data = await response.json();
    return {
      cep,
      street: data.rua,
      neighborhood: data.bairro,
      city: data.cidade,
      state: data.uf,
    };
  },
};
```

Regras:

- Devolva o endereço **sem** o campo `provider`; a unicep preenche com o `name`.
- Lance `CepNotFoundError` quando o CEP não existe e outro erro (de preferência `ProviderError`)
  para falhas do serviço. Só falhas contam para o circuit breaker.
- Repasse o `signal` ao `fetch`, para o timeout e o cancelamento funcionarem.
- O `name` precisa ser único na instância.

## Usando com responsabilidade

A unicep **não fornece, hospeda nem é dona** de nenhum dado ou API de CEP. Ela só consulta
serviços públicos independentes, cada um com seus termos, limites e disponibilidade, e não é
afiliada a nenhum deles.

**Boas práticas:** - Ligue o [cache](/docs/core#cache) para não repetir a mesma consulta.
  - Não use a unicep para varrer ou validar bases inteiras: alguns serviços avisam que uso
    automatizado intenso pode bloquear o acesso. Para volume, use uma base baixável (o OpenCEP
    publica uma) ou hospede a sua.
  - Leia os termos de cada serviço. Em uso comercial crítico, fale com os mantenedores ou rode
    uma instância própria pela opção `baseUrl`.