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

Upgrading ​

While the major version is 0, a minor version (0.x.0) may contain breaking changes and a patch (0.x.y) does not. To take only fixes, pin a tilde range on the minor you use (~0.6.0 accepts 0.6.y, not 0.7.0). Interfaces the SDK returns are not meant to be implemented by the app (except TokenStore and StorageLike), so new fields or methods are not breaking.

Upgrade the core and the packages that depend on it together: the product packages and the adapters declare the core as a peer dependency with a minimum version, and a core copy with an incompatible transport contract makes createIgaming/createPredictions throw CONFIGURATION_ERROR. Every change, version by version, is in the changelog.

From core 0.5 to 0.6 ​

PackageVersion with core 0.6Breaking for the app
@getenginex/sdk0.6.0baseUrl, idempotency of the mutations, strict money, mock PIX key id
@getenginex/sdk-igaming0.5.0requires core >=0.6.0; strict money; referrals list
@getenginex/sdk-predictions0.3.0requires core >=0.6.0; strict money; batch keys; error without Web Crypto
@getenginex/sdk-react, @getenginex/sdk-next0.2.0requires core >=0.6.0; idempotency per hook instance
@getenginex/sdk-vuefirst versionrequires core >=0.6.0 from the start
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 accepts only the origin ​

baseUrl accepts only '' or the gateway origin (https://host[:port]). Any other value, including '/' or a path such as /api, throws CONFIGURATION_ERROR when the client is created. The throw is synchronous, inside createEnginexClient: a client created at the top of a module breaks the import (also during SSR).

How to migrate: remove /api (or any path) from baseUrl; the SDK appends /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: idempotency of the mutations ​

The Idempotency-Key of the mutations (createMutations, the product mutations, useEnginexMutation) is only reused after an ambiguous failure (NETWORK_ERROR, TIMEOUT, 5xx, KEY_IN_USE, or VALIDATION_ERROR after a 2xx), for the same input compared by content, and on the same options object. Success, the other 4xx and ABORTED release it: whoever cancels and wants to repeat the same operation passes idempotencyKey.

How to migrate: a "try again" with mutate({ ...same values }) already reuses the key; code that relied on a constant object for a new operation needs no change; to repeat after reloading the page, pass idempotencyKey. See Idempotency.

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: strict money ​

Money values outside a safe integer, a currency outside /^[A-Z]{3}$/ and decimal places outside 0-8 reject the whole response with VALIDATION_ERROR, also with validation: 'warn' (list items, maps and unions included, and the realtime balance, coreTopics.balance). config.currencies stays free text.

How to migrate: nothing in the app; a gateway outside the contract now shows up as an error. See Money.

Core: smaller changes ​

  • Key generation: without crypto.randomUUID (an insecure origin, such as HTTP on the LAN) the SDK falls back to crypto.getRandomValues; with no Web Crypto at all, it rejects with CONFIGURATION_ERROR (before, a TypeError).
  • createMockFetch: the id of a created PIX key is no longer mock-pix-key-1, which collided with the seeded key. Tests that hard-coded that id must read the id returned by pixKeys.add.
  • perPage keeps its name in the SDK and goes on the wire as limit on the routes that ask for it (deposits.list, notifications.list); nothing changes in the app.

New, not breaking: sessionOwner: 'app' and onAccessTokenRejected (see Session and tokens), enginexKeys.user(userId, namespace, method?), the optional requestId in withdrawals.confirmOtp, and in /extension createAttempts, mutationCallOf, runMutation, money, moneyText, currencyCode, decimalPlaces, strictValue and randomId (see Extensibility).

iGaming 0.5 ​

  • Strict money in bonus campaigns, casino totals, loyalty redemption and referrals, as in the core. An empty currency ('') is accepted only in the bonus campaign values and in the loyalty redemption currency, because the gateway omits it when the value is 0.
  • Referrals: an invalid money value now rejects the whole list (before, the item was silently dropped). How to migrate: handle the error of the listing; no more items go missing.
  • Idempotency: bonus.optIn/claim/redeemPromoCode and loyalty.redeem follow the core rule above.

Predictions 0.3 ​

  • Strict money in orders (collateral, fees and cost), positions and the portfolio summary; an empty currency is accepted only in settlementCurrency. On the trades topic, an invalid makerFee/takerFee discards the message.
  • orders.placeBatch: the per-order keys live on the result of createPredictionsMutations (memoized by useEnginexMutations in React) and are reused after an ambiguous failure or a partial success while the batch content is the same. How to migrate: remove any registry of keys per object; to repeat after a reload, pass idempotencyKey in each order.
  • No Web Crypto: generating the idempotencyKey rejects with CONFIGURATION_ERROR (before, UNKNOWN). How to migrate: change the check from UNKNOWN to 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 and Next.js 0.2 ​

useEnginexMutation keeps the idempotency attempt (input and key) per hook instance: it survives re-renders and TanStack's retry even with new options on every render. Two instances never share a key, and an instance that switches method never reuses the other method's key. useUserKey(namespace?, method?) is new.

How to migrate: remove keys and objects kept by hand for "try again"; pass the adjustments (retry, onSuccess...) in the second argument, not spread into the options. sdk-next follows sdk-react (same version) and needs nothing beyond upgrading the core with it. See Idempotency in 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 })