Validação de respostas
O SDK valida cada resposta do gateway com um schema e converte snake_case em camelCase. Com validation, você escolhe o que acontece quando a resposta foge do esperado:
| Modo | Comportamento |
|---|---|
'warn' (padrão) | Chama onValidationIssue e entrega a resposta convertida; só os campos divergentes chegam como vieram. |
'strict' | Lança EnginexError com código VALIDATION_ERROR. |
createEnginexClient({
validation: import.meta.env.DEV ? 'strict' : 'warn',
onValidationIssue: (issue) => reportToSentry('enginex-contract', issue),
})O que o modo 'warn' entrega
A recuperação é por campo: um campo fora do formato chega como veio (com as chaves em camelCase), e todo o resto da resposta passa pelas conversões normais — listas desembrulhadas (pixKeys.list() continua devolvendo um array), enums normalizados ('pending', não 'WITHDRAWAL_STATUS_PENDING'), dinheiro em number, padrões do protobuf preenchidos, nextCursor vazio omitido. Um campo obrigatório que não veio fica ausente. onValidationIssue recebe os caminhos completos dos campos divergentes (ex.: ['keys', 0, 'verified']).
Se a raiz da resposta não tem o formato esperado (ex.: texto ou lista no lugar de um objeto, ou nenhuma das formas possíveis de uma resposta que tem mais de uma), não há o que recuperar: o modo 'warn' também lança VALIDATION_ERROR (com os problemas em error.details), e onValidationIssue não é chamado.
O issue.raw entregue a onValidationIssue é uma cópia do corpo com os valores de chaves sensíveis trocados por '[REDACTED]', em qualquer nível e sem diferenciar maiúsculas:
- credenciais: qualquer chave que contenha
token,password,secretoubackup_codes; - dados pessoais: qualquer chave que contenha
cpf,email,phone,nameoubirth_date/birthDate; - dispositivo e rede: chaves com o nome exato
ip,device,user_agentouuserAgent(ex.: as sessões deprofile.listSessions);device_idoudescriptionnão casam; - URLs: chaves terminadas em
_urlouUrl(ex.:avatar_url,gameUrl), que podem carregar tokens na query string.
Assim dá para mandar o issue inteiro para o Sentry sem vazar tokens ou senhas. O dado entregue ao app não é alterado.
LGPD
Mandar o corpo de uma resposta para um serviço de terceiros (Sentry, Datadog, um log centralizado) é tratamento de dados pessoais. O mascaramento acima cobre os campos pessoais mais comuns das respostas do gateway, mas casa pelo nome da chave: um dado pessoal numa chave com outro nome (ex.: um endereço) passa como veio. Se o seu destino de logs não pode receber dado pessoal nenhum, envie só issue.route e os path/code de issue.issues — sem issue.raw.
Aviso padrão (sem onValidationIssue)
Sem onValidationIssue, o modo 'warn' (o padrão) ainda avisa: uma vez por rota por cliente, via console.warn, com a rota e os caminhos dos campos que não bateram — nunca os valores da resposta. Configure onValidationIssue para substituir esse aviso (ex.: mandar para o Sentry em vez do console).
Respostas que carregam tokens ou segredos (login, refresh da sessão e enable2fa) são sempre validadas no modo 'strict', qualquer que seja o validation do cliente: uma resposta fora do schema vira VALIDATION_ERROR e nada é gravado na sessão.
Campos novos que o gateway passar a enviar são descartados até o SDK declará-los.