Validación de respuestas
El SDK valida cada respuesta del gateway con un schema y convierte snake_case en camelCase. Con validation, eliges qué ocurre cuando la respuesta se aparta de lo esperado:
| Modo | Comportamiento |
|---|---|
'warn' (por defecto) | Llama a onValidationIssue y entrega la respuesta convertida; solo los campos divergentes llegan como vinieron. |
'strict' | Lanza EnginexError con el código VALIDATION_ERROR. |
createEnginexClient({
validation: import.meta.env.DEV ? 'strict' : 'warn',
onValidationIssue: (issue) => reportToSentry('enginex-contract', issue),
})Qué entrega el modo 'warn'
La recuperación es por campo: un campo fuera del formato llega como vino (con las claves en camelCase), y todo el resto de la respuesta pasa por las conversiones normales — listas desenvueltas (pixKeys.list() sigue devolviendo un arreglo), enums normalizados ('pending', no 'WITHDRAWAL_STATUS_PENDING'), dinero como number, valores por defecto de protobuf rellenados, nextCursor vacío omitido. Un campo obligatorio que no vino queda ausente. onValidationIssue recibe las rutas completas de los campos divergentes (p. ej., ['keys', 0, 'verified']).
Si la raíz de la respuesta no tiene el formato esperado (p. ej., texto o una lista en lugar de un objeto, o ninguna de las formas posibles de una respuesta que tiene más de una), no hay nada que recuperar: el modo 'warn' también lanza VALIDATION_ERROR (con los problemas en error.details), y onValidationIssue no se llama.
El issue.raw entregado a onValidationIssue es una copia del cuerpo con los valores de claves sensibles reemplazados por '[REDACTED]', en cualquier nivel y sin distinguir mayúsculas de minúsculas:
- credenciales: cualquier clave que contenga
token,password,secretobackup_codes; - datos personales: cualquier clave que contenga
cpf,email,phone,nameobirth_date/birthDate; - dispositivo y red: claves con el nombre exacto
ip,device,user_agentouserAgent(p. ej., las sesiones deprofile.listSessions);device_idodescriptionno coinciden; - URLs: claves terminadas en
_urloUrl(p. ej.,avatar_url,gameUrl), que pueden llevar tokens en la query string.
Así puedes enviar el issue completo a Sentry sin filtrar tokens ni contraseñas. El dato entregado a la app no se altera.
LGPD
Enviar el cuerpo de una respuesta a un servicio de terceros (Sentry, Datadog, un log centralizado) es tratamiento de datos personales. El enmascaramiento de arriba cubre los campos personales más comunes de las respuestas del gateway, pero coincide por el nombre de la clave: un dato personal en una clave con otro nombre (p. ej., una dirección) pasa como vino. Si tu destino de logs no puede recibir ningún dato personal, envía solo issue.route y los path/code de issue.issues — sin issue.raw.
Aviso por defecto (sin onValidationIssue)
Sin onValidationIssue, el modo 'warn' (el predeterminado) igualmente avisa: una vez por ruta por cliente, vía console.warn, con la ruta y las rutas de los campos que no coincidieron — nunca los valores de la respuesta. Configura onValidationIssue para reemplazar este aviso (p. ej., enviarlo a Sentry en lugar de la consola).
Las respuestas que cargan tokens o secretos (login, refresh de la sesión y enable2fa) se validan siempre en el modo 'strict', sea cual sea el validation del cliente: una respuesta fuera del schema pasa a ser VALIDATION_ERROR y no se escribe nada en la sesión.
Los campos nuevos que el gateway empiece a enviar se descartan hasta que el SDK los declare.