# AI / LLM usage notes (p-respostas)

Este pacote fornece um **contrato estável** de respostas para operações (principalmente APIs), representando:

- sucesso (`cod: 200`, `eCerto: true`, `eErro: false`, `mensagem: undefined`, `valor: T`)
- erro conhecido/permissão/não encontrado/timeout/erro interno (`cod` diferente de 200, `eErro: true`, `eCerto: false`, `valor: undefined`, `mensagem: string`)

## Imports

### TypeScript / ESM

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

### CommonJS

```js
const { respostaComuns, gerarRespostas, codigosResposta } = require("p-respostas")
```

## Como interpretar uma `tipoResposta<T>`

Regras úteis para checagem:

- Se `res.eCerto === true` então:
  - `res.cod === codigosResposta.sucesso`
  - `res.valor` existe (tipo `T`)
  - `res.mensagem` é `undefined`

- Se `res.eErro === true` então:
  - `res.valor` é sempre `undefined`
  - `res.mensagem` é sempre `string`
  - `res.cod` é um dos códigos de erro

Exemplo:

```ts
function handle<T>(res: tipoResposta<T>) {
  if (res.eErro) {
    // aqui o TS entende tipoRespostaErro
    return { ok: false as const, status: res.cod, message: res.mensagem }
  }

  // aqui o TS entende tipoRespostaSucesso<T>
  return { ok: true as const, value: res.valor }
}
```

## Como gerar respostas com log de erro interno

```ts
const respostas = gerarRespostas((op) => {
  // op.erro: qualquer coisa lançada
  // op.local: string (obrigatória)
  // op.mensagem: string opcional
  // op.__filename: opcional
  console.error("Erro interno", op)

  // Pode retornar complementos não-destrutivos
  return { detalhes: ["id de rastreio: ..."] }
})

const r = respostas.erroInterno({ erro: new Error("boom"), local: "user.service" })
```

## Garantias / restrições

- Este pacote é amplamente importado por outros projetos.
- Os arquivos em `dist-*` são gerados automaticamente.
- Mudanças aqui devem focar em **melhorar o consumo (exports/tipos/docs)** sem alterar comportamento.