Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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:

ModoComportamento
'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.
ts
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, secret ou backup_codes;
  • dados pessoais: qualquer chave que contenha cpf, email, phone, name ou birth_date/birthDate;
  • dispositivo e rede: chaves com o nome exato ip, device, user_agent ou userAgent (ex.: as sessões de profile.listSessions); device_id ou description não casam;
  • URLs: chaves terminadas em _url ou Url (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.