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

Actualizar versiones ​

Mientras la versión major sea 0, una versión minor (0.x.0) puede traer cambios incompatibles y un patch (0.x.y) no. Para recibir solo correcciones, fija un rango con tilde en la minor que usas (~0.6.0 acepta 0.6.y, no 0.7.0). Las interfaces que devuelve el SDK no están hechas para que la app las implemente (salvo TokenStore y StorageLike), así que los campos o métodos nuevos no rompen nada.

Actualiza el core y los paquetes que dependen de él juntos: los paquetes de producto y los adapters declaran el core como peer dependency con una versión mínima, y una copia del core con un contrato de transporte incompatible hace que createIgaming/createPredictions lancen CONFIGURATION_ERROR. Todos los cambios, versión por versión, están en el changelog.

Del core 0.5 al 0.6 ​

PaqueteVersión con el core 0.6Qué se rompe en la app
@getenginex/sdk0.6.0baseUrl, idempotencia de las mutations, dinero estricto, id de la clave PIX del mock
@getenginex/sdk-igaming0.5.0exige core >=0.6.0; dinero estricto; lista de referidos
@getenginex/sdk-predictions0.3.0exige core >=0.6.0; dinero estricto; claves del lote; error sin Web Crypto
@getenginex/sdk-react, @getenginex/sdk-next0.2.0exige core >=0.6.0; idempotencia por instancia del hook
@getenginex/sdk-vueprimera versiónexige core >=0.6.0 desde el inicio
bash
npm i @getenginex/sdk@^0.6.0
# and, with them, the product packages and the adapter you use
npm i @getenginex/sdk-igaming@^0.5.0 @getenginex/sdk-predictions@^0.3.0
npm i @getenginex/sdk-react@^0.2.0 # or @getenginex/sdk-next@^0.2.0

Core: baseUrl acepta solo el origen ​

baseUrl acepta solo '' o el origen del gateway (https://host[:puerto]). Cualquier otro valor, incluidos '/' o una ruta como /api, lanza CONFIGURATION_ERROR al crear el cliente. El throw es síncrono, dentro de createEnginexClient: un cliente creado en la parte superior de un módulo hace fallar el import (también en SSR).

Cómo migrar: quita /api (o cualquier ruta) de baseUrl; el SDK agrega /api/v1.

ts
// 0.5: a path in baseUrl
createEnginexClient({ baseUrl: 'https://gateway.operador.com/api' })

// 0.6: the origin only; the SDK appends /api/v1
createEnginexClient({ baseUrl: 'https://gateway.operador.com' })

Core: idempotencia de las mutations ​

La Idempotency-Key de las mutations (createMutations, las mutations de producto, useEnginexMutation) solo se reutiliza después de una falla ambigua (NETWORK_ERROR, TIMEOUT, 5xx, KEY_IN_USE o VALIDATION_ERROR después de un 2xx), para la misma entrada comparada por contenido y en el mismo objeto de opciones. El éxito, los demás 4xx y ABORTED liberan la clave: quien cancela y quiere repetir la misma operación pasa idempotencyKey.

Cómo migrar: un "intentar de nuevo" con mutate({ ...mismos valores }) ya reutiliza la clave; el código que dependía de un objeto constante para una operación nueva no necesita cambios; para repetir después de recargar la página, pasa idempotencyKey. Consulta Idempotencia.

ts
const m = createMutations(enginex)

// "Try again" with the same values: after an ambiguous failure, the key is reused on its own.
const createPix = m.deposits.createPix()
await createPix.mutationFn({ amount: 5000 })

// Repeating the same operation after a page reload: keep the key (one per operation) and pass it.
const retried = m.deposits.createPix({ idempotencyKey: savedKey })

Core: dinero estricto ​

Los montos fuera de un entero seguro, una moneda fuera de /^[A-Z]{3}$/ y los decimales fuera de 0-8 rechazan la respuesta completa con VALIDATION_ERROR, también con validation: 'warn' (incluidos ítems de listas, mapas y uniones, y el saldo del realtime, coreTopics.balance). config.currencies sigue siendo texto libre.

Cómo migrar: nada en la app; un gateway fuera del contrato pasa a aparecer como error. Consulta Dinero.

Core: cambios menores ​

  • Generación de claves: sin crypto.randomUUID (un origen inseguro, como HTTP en la red local) el SDK usa crypto.getRandomValues; sin Web Crypto, rechaza con CONFIGURATION_ERROR (antes, un TypeError).
  • createMockFetch: el id de la clave PIX creada ya no es mock-pix-key-1, que chocaba con la clave precargada. Las pruebas que fijaban ese id deben leer el id que devuelve pixKeys.add.
  • perPage mantiene su nombre en el SDK y va como limit en la red en las rutas que lo piden así (deposits.list, notifications.list); nada cambia en la app.

Novedades que no rompen nada: sessionOwner: 'app' y onAccessTokenRejected (consulta Sesión y tokens), enginexKeys.user(userId, namespace, method?), el requestId opcional en withdrawals.confirmOtp y, en /extension, createAttempts, mutationCallOf, runMutation, money, moneyText, currencyCode, decimalPlaces, strictValue y randomId (consulta Extensibilidad).

iGaming 0.5 ​

  • Dinero estricto en las campañas de bonos, los totales del casino, el canje de fidelización y los referidos, como en el core. Una moneda vacía ('') solo se acepta en los montos de campaña del bono y en el currency del canje de fidelización, porque el gateway la omite cuando el monto es 0.
  • Referidos: un monto inválido ahora rechaza la lista completa (antes, el ítem se descartaba en silencio). Cómo migrar: maneja el error del listado; ya no desaparecen ítems.
  • Idempotencia: bonus.optIn/claim/redeemPromoCode y loyalty.redeem siguen la regla del core de arriba.

Predictions 0.3 ​

  • Dinero estricto en las órdenes (colateral, comisiones y costo), las posiciones y el resumen del portafolio; una moneda vacía solo se acepta en settlementCurrency. En el tópico de trades, un makerFee/takerFee inválido descarta el mensaje.
  • orders.placeBatch: las claves de cada orden viven en el resultado de createPredictionsMutations (memoizado por useEnginexMutations en React) y se reutilizan después de una falla ambigua o un éxito parcial mientras el contenido del lote sea el mismo. Cómo migrar: quita cualquier registro de claves por objeto; para repetir después de recargar, pasa idempotencyKey en cada orden.
  • Sin Web Crypto: generar la idempotencyKey rechaza con CONFIGURATION_ERROR (antes, UNKNOWN). Cómo migrar: cambia la comprobación de UNKNOWN por CONFIGURATION_ERROR.
ts
try {
  await predictions.orders.place(input)
} catch (error) {
  // 0.2 rejected with UNKNOWN when there was no Web Crypto to generate the key; 0.3 uses CONFIGURATION_ERROR.
  if (isEnginexError(error, 'CONFIGURATION_ERROR')) showUnsupportedBrowser()
  else throw error
}

React y Next.js 0.2 ​

useEnginexMutation guarda el intento de idempotencia (entrada y clave) por instancia del hook: sobrevive a los re-renders y al retry de TanStack aun con opciones nuevas en cada render. Dos instancias nunca comparten clave, y una instancia que cambia de método nunca reutiliza la clave del otro método. useUserKey(namespace?, method?) es nuevo.

Cómo migrar: quita las claves y los objetos guardados a mano para el "intentar de nuevo"; pasa los ajustes (retry, onSuccess...) en el segundo argumento, no esparcidos en las opciones. sdk-next sigue a sdk-react (misma versión) y no pide nada más que actualizar el core junto con él. Consulta Idempotencia en mutations.

tsx
// Avoid: the spread copy loses the SDK call, and with it the attempt kept per hook instance
// const pix = useEnginexMutation({ ...m.deposits.createPix(), retry: 1 })

// 0.2: adjustments go in the second argument
const pix = useEnginexMutation(m.deposits.createPix(), { retry: 1 })