# 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 (narrowing recomendado)

Para o TypeScript, o narrowing mais robusto costuma ser usando `cod`:

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

function handle<T>(res: tipoResposta<T>) {
  if (res.cod !== codigosResposta.sucesso) {
    // aqui o TS entende tipoRespostaErro (na maioria dos setups)
    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 }
}
```

> Nota: em alguns setups, checar somente `res.eErro` pode não eliminar completamente `undefined` em `res.valor`.
> Se isso acontecer, prefira checar `cod` como no exemplo acima.

## 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" })
```

## Validação com Zod (`zRespostas`)

Para validar payloads de resposta recebidos de APIs ou serviços com [Zod](https://zod.dev):

```ts
import z from "zod"
import { zRespostas, type tipoZResposta } from "p-respostas"

// 1. Validando payload com tipo específico de sucesso
const schemaUsuario = zRespostas(
  z.object({
    id: z.string(),
    nome: z.string(),
  })
)

const resposta = schemaUsuario.parse(jsonRecebidoDaApi)

if (resposta.eCerto) {
  // TypeScript sabe que resposta.valor tem { id: string; nome: string }
  console.log("Dados do usuário:", resposta.valor.nome)
} else {
  // TypeScript sabe que resposta.mensagem é string e cod é um dos códigos de erro
  console.error("Falha:", resposta.mensagem, "Código:", resposta.cod)
}

// 2. Aceitando qualquer valor no sucesso (default z.any())
const schemaGenerico = zRespostas()

// 3. Schemas e tipos auxiliares exportados:
// - zResposta (alias idêntico a zRespostas)
// - zRespostaSucesso(zValor?)
// - zRespostaErro
// - zCodigosRespostaErro
// - tipoZResposta<T>
```

## 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.