# p-respostas

Contrato simples e tipado de respostas para APIs e serviços (sucesso/erro), com suporte a:

- **ESM** (`import`) via `dist-front/index.mjs`
- **CommonJS** (`require`) via `dist-back/index.js`
- **TypeScript** com tipos publicados em `dist-front/index.d.mts`

> Importante: os diretórios `dist-*` são gerados automaticamente no build. Este repositório deve manter **compatibilidade** e **não alterar funcionalidades**.

## Instalação

```bash
pnpm add p-respostas
# ou
npm i p-respostas
```

## Uso rápido

```ts
import { respostaComuns, gerarRespostas, codigosResposta, type tipoResposta } from "p-respostas"

const r1 = respostaComuns.valor({ ok: true })
// r1.cod === 200

const r2 = respostaComuns.erro("Falha ao processar")
// r2.eErro === true

// Exemplo com logger/observabilidade
const respostas = gerarRespostas(({ erro, mensagem, local }) => {
  console.error("erroInterno:", { erro, mensagem, local })
  // pode sobrescrever parcialmente a resposta final
  return { detalhes: ["contate o suporte" as const] }
})

const r3: tipoResposta<string> = respostas.valor("ok")
const r4: tipoResposta<string> = respostas.erroInterno({ erro: new Error("boom"), local: "serviceX" })
```

## API

### `codigosResposta`

Enum com os códigos HTTP usados pelo contrato:

- `sucesso = 200`
- `erroConhecido = 400`
- `erroPermissao = 401`
- `erroNaoEncontrado = 404`
- `erroDesconhecido = 500`
- `tempoEsgotado = 504`

### Tipos

- `tipoRespostaSucesso<T>`
- `tipoRespostaErro`
- `tipoResposta<T> = tipoRespostaSucesso<T> | tipoRespostaErro`
- `tipoPrErroInterno`

### `gerarRespostas(registrarErroInterno)`

Cria um conjunto de funções padronizadas para gerar respostas.

`registrarErroInterno(op)` recebe `{ erro, mensagem?, local, __filename? }` e pode retornar um `Partial<tipoRespostaErro>` para complementar a resposta final.

### `respostaComuns`

Instância default de `gerarRespostas(() => ({}))`.

## Compatibilidade

- Node: `>=20`
- Exporta ESM e CJS via `package.json#exports`