Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

Dinero ​

El SDK transporta todo valor monetario en unidades menores, como enteros: 1999 es R$ 19,99 (una moneda con 2 decimales). Nunca hay un number con decimales en la API, así que los saldos y límites suman sin error de punto flotante. La moneda del operador (con decimalPlaces) viene de config.get().

Qué se valida en la respuesta ​

Los campos monetarios que vienen del gateway (en el core y en los paquetes de producto) pasan por una verificación estricta:

  • el valor es un entero seguro (hasta Number.MAX_SAFE_INTEGER), en número o en texto; un valor de 2^53 en adelante nunca llega redondeado;
  • la moneda es un código ISO de tres letras mayúsculas (/^[A-Z]{3}$/);
  • decimalPlaces es un entero de 0 a 8.

Un campo fuera de eso rechaza la respuesta completa con VALIDATION_ERROR, incluso en validation: 'warn' (el valor por defecto): aplica también a ítems dentro de listas, mapas y uniones, y para el saldo que llega por realtime. En 'warn' los demás campos siguen siendo tolerantes (un enum nuevo pasa a ser onValidationIssue), pero el dinero erróneo nunca se entrega a la app. Un gateway fuera del contrato aparece como error, no como un saldo incorrecto. Los paquetes de producto reutilizan las mismas verificaciones mediante money, moneyText, currencyCode y decimalPlaces de @getenginex/sdk/extension.

No todo es dinero. Precio, cantidad y porcentaje no se validan como dinero: los precios y las cantidades de Predictions, las tasas en puntos básicos (bps), los puntos de fidelización y el progreso de misiones siguen la validación común. Los agregados y límites del mercado en Predictions (volume_24h, total_volume, min_order_size, max_position) quedan fuera de la verificación estricta por decisión (agregados y límites del mercado, en centavos) y también siguen la validación común.

La moneda vacía ('') se acepta solo donde el gateway la omite por ser cero: en los valores de campaña de bono, en el currency del canje de fidelización y en el settlement_currency de Predictions. En cualquier otro campo monetario, '' rechaza la respuesta. La lista config.currencies es texto libre y no pasa por esta verificación.

Helpers de conversión ​

Tres helpers convierten desde y hacia lo que el usuario ve y escribe:

ts
import { formatMoney, fromMinorUnits, toMinorUnits } from '@getenginex/sdk'

const { currency } = await enginex.config.get() // { code: 'BRL', symbol: 'R$', decimalPlaces: 2, ... }

formatMoney(123456, currency, 'pt-BR') // 'R$ 1.234,56'
toMinorUnits('1.234,56', currency) // 123456
toMinorUnits(19.99, currency) // 1999 (19.99 * 100 would give 1998.9999999999998)
fromMinorUnits(1999, currency) // 19.99

formatMoney(amountMinor, currency, locale?) ​

Usa Intl.NumberFormat con el código ISO de la moneda y los decimales de decimalPlaces. Acepta negativos (extracto). Sin locale, se usa el del runtime; en SSR (Next.js, Nuxt), pasa el mismo locale en el servidor y en el browser para no generar diferencias en la hidratación.

toMinorUnits(value, currency) ​

Convierte el texto de un campo ('12,50', '1.234,56', '1,234.56') o un number en unidades menores. El texto se lee dígito a dígito, sin multiplicar un number, y:

  • con más decimales de los que tiene la moneda, redondea hacia arriba en la mitad sobre el valor indicado ('1.0050' pasa a 101);
  • con . y , juntos, el último es el separador decimal ('1.234,56'); un único separador que aparece una vez es el decimal ('1.5', '12,50'); repetido, es separador de miles ('1.234.567');
  • un separador único seguido de exactamente 3 dígitos ('1.000', '1,000', '10.500') es ambiguo y lanza RangeError, excepto en monedas de 3 decimales (ahí es decimal);
  • rechaza negativos, texto vacío o no numérico, NaN, infinito y valores por encima del mayor entero seguro, lanzando RangeError.

Valores como '1.000' se rechazan

En pt-BR 1.000 es mil y en en-US es uno: convertir en silencio podría subvalorar por un factor de 1000. Por eso el SDK lanza en lugar de adivinar. Pasa un number, o una cadena sin ambigüedad: con los dos separadores ('1.000,00') o sin miles ('1000'). Si la app lee un campo de texto, normalízalo (o usa un input numérico) antes de llamar a toMinorUnits.

Un number nunca es ambiguo, pero solo carga lo que JavaScript puede representar.

fromMinorUnits(amountMinor, currency) ​

Devuelve la unidad principal como number (1999 pasa a 19.99), útil para rellenar un campo de edición. Para mostrar dinero al usuario, usa formatMoney. Como es un number, por encima de ~15 dígitos significativos los decimales dejan de ser representables.

Los tres lanzan RangeError con entrada fuera del contrato (un valor no entero en unidades menores o un decimalPlaces inválido).