This version (v0.7) has not been published to npm yet.
Skip to content

Response validation ​

The SDK validates every gateway response with a schema and converts snake_case to camelCase. With validation, you choose what happens when the response deviates from what is expected:

ModeBehavior
'warn' (default)Calls onValidationIssue and delivers the converted response; only the diverging fields arrive as they came.
'strict'Throws an EnginexError with code VALIDATION_ERROR.
ts
createEnginexClient({
  validation: import.meta.env.DEV ? 'strict' : 'warn',
  onValidationIssue: (issue) => reportToSentry('enginex-contract', issue),
})

What 'warn' mode delivers ​

Recovery is per field: a field outside the format arrives as it came (with keys in camelCase), and the whole rest of the response goes through the normal conversions — unwrapped lists (pixKeys.list() still returns an array), normalized enums ('pending', not 'WITHDRAWAL_STATUS_PENDING'), money as number, protobuf defaults filled in, empty nextCursor omitted. A required field that did not come is left absent. onValidationIssue receives the full paths of the diverging fields (e.g. ['keys', 0, 'verified']).

If the response's root does not have the expected format (e.g. text or a list in place of an object, or none of the possible shapes of a response that has more than one), there is nothing to recover: 'warn' mode also throws VALIDATION_ERROR (with the problems in error.details), and onValidationIssue is not called.

The issue.raw delivered to onValidationIssue is a copy of the body with the values of sensitive keys replaced by '[REDACTED]', at any level and case-insensitively:

  • credentials: any key that contains token, password, secret or backup_codes;
  • personal data: any key that contains cpf, email, phone, name or birth_date/birthDate;
  • device and network: keys with the exact name ip, device, user_agent or userAgent (e.g. the sessions from profile.listSessions); device_id or description do not match;
  • URLs: keys ending in _url or Url (e.g. avatar_url, gameUrl), which may carry tokens in the query string.

This way you can send the whole issue to Sentry without leaking tokens or passwords. The data delivered to the app is not altered.

LGPD

Sending a response body to a third-party service (Sentry, Datadog, a centralized log) is processing of personal data. The masking above covers the most common personal fields in the gateway's responses, but it matches by key name: personal data under a key with another name (e.g. an address) goes through as it came. If your log destination cannot receive any personal data, send only issue.route and the path/code of issue.issues — without issue.raw.

Default warning (without onValidationIssue) ​

Without onValidationIssue, 'warn' mode (the default) still warns: once per route per client, via console.warn, with the route and the paths of the fields that did not match — never the response values. Configure onValidationIssue to replace this warning (e.g. send it to Sentry instead of the console).

Responses that carry tokens or secrets (login, session refresh and enable2fa) are always validated in 'strict' mode, whatever the client's validation is: a response outside the schema becomes VALIDATION_ERROR and nothing is written to the session.

New fields the gateway starts sending are discarded until the SDK declares them.