refatoração para ia

README.md

@@ -1 +1,74 @@
-# drivers
+# 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`