---
url: https://game-engine-io.github.io/enginex-frontend-sdk/guide/upgrading.md
---
# 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](/changelog).

## From core 0.5 to 0.6

| Package | Version with core 0.6 | Breaking for the app |
| --- | --- | --- |
| `@getenginex/sdk` | `0.6.0` | `baseUrl`, idempotency of the mutations, strict money, mock PIX key id |
| `@getenginex/sdk-igaming` | `0.5.0` | requires core `>=0.6.0`; strict money; referrals list |
| `@getenginex/sdk-predictions` | `0.3.0` | requires core `>=0.6.0`; strict money; batch keys; error without Web Crypto |
| `@getenginex/sdk-react`, `@getenginex/sdk-next` | `0.2.0` | requires core `>=0.6.0`; idempotency per hook instance |
| `@getenginex/sdk-vue` | first version | requires 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](/concepts/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](/concepts/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](/concepts/session)),
`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](/concepts/extensibility#custom-mutation)).

### 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](/frameworks/react#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 })
```
