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
| Paquete | Versión con el core 0.6 | Qué se rompe en la app |
|---|---|---|
@getenginex/sdk | 0.6.0 | baseUrl, idempotencia de las mutations, dinero estricto, id de la clave PIX del mock |
@getenginex/sdk-igaming | 0.5.0 | exige core >=0.6.0; dinero estricto; lista de referidos |
@getenginex/sdk-predictions | 0.3.0 | exige core >=0.6.0; dinero estricto; claves del lote; error sin Web Crypto |
@getenginex/sdk-react, @getenginex/sdk-next | 0.2.0 | exige core >=0.6.0; idempotencia por instancia del hook |
@getenginex/sdk-vue | primera versión | exige core >=0.6.0 desde el inicio |
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.0Core: 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.
// 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.
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 usacrypto.getRandomValues; sin Web Crypto, rechaza conCONFIGURATION_ERROR(antes, unTypeError). createMockFetch: el id de la clave PIX creada ya no esmock-pix-key-1, que chocaba con la clave precargada. Las pruebas que fijaban ese id deben leer el id que devuelvepixKeys.add.perPagemantiene su nombre en el SDK y va comolimiten 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 elcurrencydel 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/redeemPromoCodeyloyalty.redeemsiguen 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, unmakerFee/takerFeeinválido descarta el mensaje. orders.placeBatch: las claves de cada orden viven en el resultado decreatePredictionsMutations(memoizado poruseEnginexMutationsen 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, pasaidempotencyKeyen cada orden.- Sin Web Crypto: generar la
idempotencyKeyrechaza conCONFIGURATION_ERROR(antes,UNKNOWN). Cómo migrar: cambia la comprobación deUNKNOWNporCONFIGURATION_ERROR.
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.
// 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 })