---
url: https://game-engine-io.github.io/enginex-frontend-sdk/changelog.md
---
# Changelog

Release notes of each SDK package. The documentation is versioned by the core version (`@getenginex/sdk`); the notes of the product packages are in the section of each one.

## `@getenginex/sdk`

::: v-pre

### 0.7.0

#### Minor Changes

* 8020869: Align the SDK with the gateway contract in production.

  **Type changes (may need code changes when upgrading):**

  * `@getenginex/sdk`: `PixDeposit.expiresAt` is now optional (`string | undefined`); code such as `new Date(pix.expiresAt)` must handle a missing expiry. New optional fields: `PixDeposit.redirectUrl`, `Deposit.expiresAt` and `Deposit.redirectUrl`.
  * `@getenginex/sdk-igaming`: `GameLaunch` gains the required `launchTarget` (new exported type `LaunchTarget`: `'iframe' | 'redirect' | 'new_tab'` or a future value) and the optional `providerCode` and `expiresAt`. Hand-written `GameLaunch` objects (e.g. test fixtures) need a `launchTarget`.

  **Behavior changes:**

  * `deposits.createPix` no longer throws `VALIDATION_ERROR` after the charge was created when the payment provider reports no expiry.
  * The session is renewed and the request retried only on a 401 that refuses the access token: a 401 without a code (what the gateway's auth middleware answers for a missing, expired or invalid token), `TOKEN_EXPIRED` or `TOKEN_STALE`. A 401 with any other code, such as `INVALID_CREDENTIALS` for a wrong current password in `changePassword` or `disable2fa`, or an explicit `UNAUTHENTICATED`/`TOKEN_INVALID`, is no longer retried and no longer fires `onAccessTokenRejected`. An error body with a top-level `code` (e.g. `TOKEN_STALE`) now keeps that code.
  * `auth.logout` sends the stored refresh token so the gateway revokes it. With an expired access token the gateway refuses the call before revoking, so logout renews once (without storing the new tokens or calling `onSessionExpired`) and revokes the renewed refresh token. The local session is always cleared; if the renewal or the request fails, the refresh token may stay valid on the server until it expires.
  * `casino.launchGame` returns `launchTarget`, so apps can open each game the way its provider requires. A response without it is treated as `iframe`, as before. The testing mock returns `launch_target`, `provider_code` and `expires_at`.
  * `withdrawals.request` docs and the testing mock match the gateway: while an OTP request is pending (until its `expiresAt`, also after its code was confirmed), the same request is replayed and any other request is refused with `FAILED_PRECONDITION` (422) `another withdrawal request is pending`, instead of replacing it. After a confirmed withdrawal, the next one can only be requested once the previous request expires.

#### Patch Changes

* 7be12eb: Code comments, TSDoc and runtime error messages are now in English. Error `code` values are unchanged; if your UI shows `error.message` to players, it now shows English text — map `code` to your own copy instead.
* d330035: READMEs and package metadata in English; docs site now in English, Portuguese and Spanish.

### 0.6.0

#### Minor Changes

* af441d0: **Breaking (antes do 1.0).**

  * Idempotência das mutations: a `Idempotency-Key` só é reaproveitada depois de falha ambígua (`NETWORK_ERROR`, `TIMEOUT`, 5xx, `KEY_IN_USE` e `VALIDATION_ERROR` depois de 2xx, em que a operação pode ter acontecido, ainda está em processamento ou já aconteceu), para a mesma entrada (por conteúdo) e no mesmo objeto de opções; `isAmbiguousFailure` em `/extension` aplica essa regra. `ABORTED` libera a chave: quem cancela e quer repetir a mesma operação passa `idempotencyKey`. **Como migrar:** "tentar de novo" com `mutate({ ...mesmos valores })` já reaproveita a chave; quem dependia de um objeto constante para uma operação nova não precisa mudar nada; quem precisa repetir depois de recarregar a página passa `idempotencyKey`.
  * Dinheiro estrito: valores monetários fora de inteiro seguro, moeda fora de `/^[A-Z]{3}$/` e casas decimais fora de 0-8 rejeitam a resposta inteira com `VALIDATION_ERROR` também em `validation: 'warn'` (inclui itens de listas, mapas e uniões, e o saldo do realtime, `coreTopics.balance`). A lista `config.currencies` segue como texto livre. **Como migrar:** nada no app; um gateway fora do contrato passa a aparecer como erro.
  * `baseUrl` aceita só `''` ou a origem (`https://host[:porta]`); qualquer outro valor, inclusive `'/'`, lança `CONFIGURATION_ERROR` na criação. O throw é síncrono, dentro de `createEnginexClient`: um cliente criado no topo de um módulo derruba o import (inclusive no SSR). **Como migrar:** tire `/api` do `baseUrl`; o SDK acrescenta `/api/v1`.
  * `randomId` com fallback em `getRandomValues` (origem insegura, como HTTP na LAN, volta a funcionar); sem Web Crypto, `CONFIGURATION_ERROR` (antes, `TypeError`).
  * Novos: `sessionOwner: 'app'` (o app grava e renova os tokens; o SDK só lê o `tokenStore`; `auth.login`/`auth.logout` e escritas de sessão lançam `CONFIGURATION_ERROR` antes de enviar; `'app'` com `autoRefresh: true` e `onAccessTokenRejected` sem `'app'` lançam na criação) e `onAccessTokenRejected` (chamado uma vez por access token recusado com 401, também em chamadas `auth: 'optional'`; o `unauthorized` do realtime não o dispara; um 401 de um token que o app já trocou no `tokenStore` durante o request é repetido uma vez com o token atual, sem aviso); `enginexKeys.user(userId, namespace, method?)` (o layout da chave é contrato); `withdrawals.confirmOtp({ otp, requestId })` (o `requestId` de `withdrawals.request` não vai ao gateway e separa os desafios); `createAttempts`/`mutationCallOf`/`runMutation`/`money`/`moneyText`/`currencyCode` (com `{ allowEmpty: true }` para moeda que pode vir `''`)/`decimalPlaces`/`strictValue`/`randomId` em `/extension`.
  * `perPage` continua o nome no SDK e vai como `limit` no fio nas rotas que o gateway pede assim (documentado em `deposits.list` e `notifications.list`).
  * `createMockFetch` (muda o comportamento dos testes): o id da chave PIX criada deixa de ser `mock-pix-key-1`, que colidia com a chave semeada; testes que fixavam esse id devem ler o id devolvido.

### 0.5.0

#### Minor Changes

* 4bc271e: Novo entry `@getenginex/sdk/query`, agnóstico de framework: `createQueries(enginex)` e
  `createMutations(enginex)` devolvem uma fábrica por método de leitura (`{ queryKey, queryFn }`) e uma
  mutation por método de escrita (`{ mutationKey, mutationFn, invalidates }`), com os mesmos nomes e
  entradas dos namespaces e compatíveis com `useQuery`/`useMutation`/`prefetchQuery` do TanStack Query v5,
  sem depender dele. Chaves `['enginex', 'public', namespace, método, input?]` (dados sem sessão) e
  `['enginex', 'user', userId, namespace, método, input?]` (dados do jogador, com o `userId` da sessão no
  momento da chamada; sem sessão, `'anonymous'` e `queryFn` rejeitando com `UNAUTHENTICATED` sem request,
  o mesmo quando a sessão muda de usuário antes do `fetch`); `input` só entra quando informado e nenhuma
  chave contém token ou senha. O `queryFn` repassa o `signal` do contexto ao `fetch`. Só `config.*` traz
  `staleTime` (5 minutos). `invalidates(input, result)` lista os prefixos afetados (depósito/saque →
  carteira e o próprio namespace; `pixKeys.*` → `pixKeys.list`; `notifications.*` → `notifications`;
  `auth.login`/`auth.logout` → `['enginex', 'user']`...). `enginexKeys` traz os prefixos (`all`,
  `public`, `user()`, `user(userId)`). Para pacotes do SDK: `queryScope(cliente ou produto)` (chaves,
  fábricas de leitura pública/de usuário e mutations) em `/query` e `registerProductClient(produto,
  cliente)` em `/extension`, que liga o objeto de um pacote de produto ao cliente do core. Depósito e saque
  (`createPix`, `withdrawals.request`/`confirmOtp`) mandam uma `Idempotency-Key` por objeto de entrada
  (o retry do TanStack não duplica a operação): a chave derivada é descartada depois de um sucesso e
  mantida depois de um erro, inclusive 4xx (tentar de novo com a mesma entrada reusa a chave); também
  aceitam `{ idempotencyKey }` na fábrica; as mutations
  de `auth.*` (exceto `logout`) e `withdrawals.confirmOtp` trazem `gcTime: 0`.

### 0.4.0

#### Minor Changes

* 5cbe27b: Novo namespace `enginex.kyc` (verificação de identidade): `getStatus()` devolve `KycStatus`
  (`level`: `none`/`basic`/`intermediate`/`full`; `status`: `not_started`/`pending`/`in_review`/`approved`/
  `rejected`, uniões abertas sem o prefixo do protobuf; `cpfVerified`, `documentVerified`,
  `selfieVerified`, `addressVerified`; `rejectionReason` e `updatedAt` como `null` quando o gateway manda
  texto vazio ou a data epoch) e `uploadDocument({ documentType, file })` envia o documento
  (`rg_front`, `rg_back`, `cnh_front`, `cnh_back`, `passport`, `selfie`, `proof_address`; `file` é
  `Blob`/`File`) como multipart e devolve `{ documentId }`. `documentType` fora da lista ou `file` que não
  é `Blob` rejeitam com `CONFIGURATION_ERROR` sem request; um 201 sem confirmação (`success: false` ou id
  vazio) rejeita com `UNKNOWN` (`status` 201) e a mensagem do gateway quando vem, senão a do SDK (regra
  documentada: `UNKNOWN` com `status` 2xx = operação não confirmada, releia o estado antes de tentar de
  novo). Nível ou situação desconhecidos chegam crus e vão para `onValidationIssue` em
  `validation: 'warn'`; em `'strict'`, `VALIDATION_ERROR`. `KycLevel` e `KycStatusValue` nomeiam
  `unspecified`.

  O transporte passa a aceitar corpo `FormData` (multipart, sem `Content-Type` JSON: o runtime define o
  boundary; o mesmo `FormData` é reenviado inteiro no retry após um 401 renovado), também para pacotes de
  produto via `@getenginex/sdk/extension`. Os hooks de request (`onRequest`, `onResponse`, `onError`)
  ganham `ctx.body` só nesses requests: um resumo `{ kind: 'form-data', fields: [{ name, type?, size? }] }`
  (tipos `RequestBodySummary`, com `kind` como união aberta, e `FormDataFieldSummary`), nunca o nome original nem o conteúdo do arquivo,
  nem o valor dos campos de texto. Corpos JSON continuam iguais e fora dos hooks.

  `@getenginex/sdk/testing`: `createMockFetch()` responde `GET /api/v1/kyc/status` e aceita o upload
  multipart de `POST /api/v1/kyc/documents` (201, ou 400 `INVALID_ARGUMENT` como o gateway); `MockRequest.body`
  traz o próprio `FormData` em requests multipart.

  Novo namespace `enginex.responsibleGambling` (jogo responsável): `getLimits()` devolve
  `ResponsibleGamblingLimits` (`deposit.daily|weekly|monthly` como `{ limit, used }`, `loss.daily`,
  `sessionTimeLimitMinutes` e `selfExclusion: { until, permanent }`; limite `0` e data epoch viram
  `null`); `setLimits({ dailyDeposit, weeklyDeposit, monthlyDeposit, dailyLoss, sessionTimeMinutes })`
  envia só os campos presentes (`null` envia `0`, "remover limite", inferido) e devolve
  `{ updatedAt }` (o gateway aplica em 24 h); `selfExclude({ duration })` (`24h`, `7d`, `30d`, `6m`,
  `1y`, `permanent`) devolve `{ excludedUntil, permanent }`; `getRealityCheck()` devolve limite de
  sessão, depósito do dia e limite de perda. Valor de limite que não é inteiro ≥ 0, input sem campo
  nenhum e `duration` fora da lista, ausente ou de outro tipo rejeitam com `CONFIGURATION_ERROR` sem
  request. O mock de `@getenginex/sdk/testing` responde as quatro rotas. O 429 do limitador global do
  gateway (corpo fora do envelope) já vira `RESOURCE_EXHAUSTED` com `retryAfter` em segundos; agora há
  teste de regressão. Nova página "Erros de compliance" nos docs.

  Novo namespace `enginex.notifications`: `list({ page?, perPage?, unreadOnly? })` devolve
  `Page<Notification> & { unreadCount }` (envia `page`, `limit` e `unread=true` só com `unreadOnly`; como o
  gateway manda só `total` e `unread_count`, o SDK monta o `Page`: `totalPages` 0 sem notificações,
  `ceil(total / perPage)` nas demais e `items: []` para página além do fim; em `'warn'`, um `total` que
  não é inteiro ≥ 0 vale 0, nunca `NaN`); `Notification` é
  `{ id, type, title, message, read, createdAt }` com `type` em minúsculas sem o prefixo do protobuf
  (`bet_won`, `kyc_approved`, `unspecified`..., união aberta; desconhecido chega cru e vai para `onValidationIssue` em
  `'warn'`) e `createdAt` `null` para a data epoch; `markAsRead({ notificationId })` resolve `void`;
  `getPreferences()` e `updatePreferences({ email?, sms?, push?, marketing? })` trabalham com
  `{ email, sms, push, marketing }` (o `PUT` envia só os campos presentes e devolve o corpo da resposta,
  sem `message`). `perPage` fora de 1–100 ou não inteiro, `page` inválido, `unreadOnly` não booleano,
  `notificationId` vazio e preferências sem campo ou não booleanas rejeitam com `CONFIGURATION_ERROR` sem
  request. O mock de `@getenginex/sdk/testing` responde as quatro rotas. Novas páginas "Notificações" (REST
  × realtime) e "Suporte (widget)" nos docs.

### 0.3.0

#### Minor Changes

* b5f1178: Novo entry `@getenginex/sdk/realtime`: `createRealtime(enginex)` devolve o realtime do cliente (sempre
  a mesma instância; o parâmetro é tipado como `EnginexClient`, então o objeto de um pacote de produto não compila), com uma conexão WebSocket aberta no primeiro `subscribe` e fechada ~1 s após o
  último `off()`; reconexão com backoff exponencial e jitter (1 s → 30 s, sem limite de tentativas),
  ping JSON a cada 30 s (sem resposta em 10 s, reconecta), reinscrição de todos os tópicos e
  `onResync` depois de cada reconexão (`onResync(listener)` para todos os tópicos, recebendo o tópico
  completo, ou `onResync(topic, listener)` para um só, com o mesmo descritor do `subscribe`); token em `?token=` renovado antes de conectar, reconexão
  quando o usuário da sessão muda (tópicos privados do usuário anterior são descartados) e uma única
  renovação + reconexão quando o gateway responde `unauthorized` num tópico privado (se repetir, status
  `closed` para todos os tópicos e `UNAUTHENTICATED` no `onError`; se a própria renovação falhar, a
  tentativa não é gasta e o backoff cresce até 30 s); outros `error` do gateway num `subscribe` (ex.:
  `rate_limited`) vão ao `onError` (`RESOURCE_EXHAUSTED`) e o `subscribe` é reenviado com backoff; modo sequenciado (`snapshot`/`delta`/`heartbeat`, com
  detecção de gap, `snapshot_request` e, após 10 s sem snapshot, `onResync` com o próximo delta como nova
  base); mensagens validadas no modo do cliente. Sem `WebSocket` disponível (runtime antigo; o Node 22+ tem o global), `subscribe` é
  no-op e o status fica `'unavailable'`. Novas opções
  do cliente: `wsUrl` e `webSocket` (tipos `WebSocketLike`/`WebSocketLikeInstance`, sem depender da
  `lib: DOM`). Fora do browser o gateway exige o header `Origin`: passe em `webSocket` um construtor que o
  acrescente (o `WebSocket` do Node ou o pacote `ws` direto não bastam); o realtime assina o `error` do
  socket, então um erro de conexão do `ws` não derruba o processo. `@getenginex/sdk/extension` ganha `defineTopic` (e os tipos `Topic`, `TopicDefinition`,
  `WireSchema`) para os pacotes de produto definirem os próprios tópicos. Para apps, o descritor `Topic`
  é opaco: `Topic.definition` é detalhe interno. O contrato interno do registro
  de clientes passa à versão 2: pacotes de produto que embutam uma cópia antiga do core recebem
  `CONFIGURATION_ERROR`.

  Novos tópicos do core: `coreTopics.balance()` (`BalanceUpdate`: `available`, `change`, `changeType`,
  `description?`, `updatedAt`, sem `reserved`/`bonus`/`total`, que o gateway não preenche) e
  `coreTopics.notification()` (`RealtimeNotification`; `type` é uma união aberta: `info`, `success`,
  `warning`, `error` ou outro valor que o gateway enviar, então trate o caso padrão). O snapshot do modo
  sequenciado de `balance:` (protobuf cru de `GetBalance`) não é entregue; `TopicDefinition` ganha
  `snapshots?: 'deliver' | 'ignore'` para isso.
  `@getenginex/sdk/testing` ganha `createMockRealtime(options?)`: `WebSocket` falso com `emit`, `emitSequenced`, `drop`,
  `rejectPrivate`/`acceptPrivate`, `connections` e `sent`, para testar o realtime sem gateway. Para o `rejectPrivate()`,
  é privado o tópico que termina no `sub` do token da conexão (ou o que a opção `isPrivate` disser).

### 0.2.0

#### Minor Changes

* ffc0bd1: Carteira e PIX no core: novos namespaces `wallet` (`get`, `getBalance`, `listTransactions` paginado
  com `category`), `deposits` (`createPix`, `get`, `list`), `withdrawals` (`request`, `confirmOtp`,
  `get`, `list`, `cancel`) e `pixKeys` (`add`, `list`, `remove`, `setDefault`), todos com login
  obrigatório e valores em unidades menores. `deposits.createPix`, `withdrawals.request` e
  `withdrawals.confirmOtp` são idempotentes (`Idempotency-Key` gerada ou de `options.idempotencyKey`,
  reusada no retry após 401) e validam a resposta sempre em modo estrito. `withdrawals.request` devolve
  a união `{ status: 'otp_required', requestId, expiresAt } | { status: 'created', withdrawal }`;
  `confirmOtp({ otp })` confirma o pedido pendente da própria sessão. Status de depósito/saque chegam
  normalizados (`DEPOSIT_STATUS_COMPLETED` → `'completed'`). Novos códigos de erro do middleware de
  idempotência em `GATEWAY_ERROR_CODES`: `KEY_IN_USE`, `PAYLOAD_MISMATCH` e `INVALID_KEY`. O
  `createMockFetch` de `@getenginex/sdk/testing` ganha rotas padrão com estado em memória para
  carteira, depósito, saque (opção `withdrawalOtp`) e chaves PIX (201 nas rotas de criação, como o
  gateway), rotas com parâmetro (`:nome`, valores no novo campo opcional `req.params`) e um terceiro
  argumento opcional `status` em `ok(data, meta?, status?)`.
* a043c79: Novo entry `@getenginex/sdk/extension`: contrato estável para pacotes de produto do SDK
  (`@getenginex/sdk-igaming`, `@getenginex/sdk-predictions`). `getExtensionTransport(client)` dá acesso
  ao transporte do próprio cliente (sessão, refresh, tenant, hooks, validação e `dispose()`), com um
  `ExtensionRequestSpec` público (`auth`, `idempotent`, `validation: 'strict'`, `options`), além dos
  helpers de schema `wire`, `mapOf` e `lazy`. Os exports do entry principal não mudam.
* d4ebcf2: Novos tipos públicos `CursorPage<T>` (`{ items, nextCursor? }`) e `CursorPageInput`
  (`{ cursor?, pageSize? }`) para listagens paginadas por cursor, ao lado de `Page`, exportados pelo
  entry principal e reexportados por `@getenginex/sdk/extension` (usados pelas campanhas de bônus do
  `@getenginex/sdk-igaming`). Só tipos: nenhum export de runtime muda.
* cbf1a39: Helpers de dinheiro no entry principal: `formatMoney(amountMinor, currency, locale?)`,
  `toMinorUnits(value, currency)` e `fromMinorUnits(amountMinor, currency)`, com as casas decimais de
  `config.currency` e sem erro de ponto flutuante (`toMinorUnits` lê o texto decimal dígito a dígito e
  rejeita negativos). Novo `CallOptions.idempotencyKey`: métodos idempotentes (movimentação de
  dinheiro) a enviam no header `Idempotency-Key` e a reusam no retry após um 401; nos demais é
  ignorada. Também vale para `idempotent: true` no entry `@getenginex/sdk/extension`.
* 826a4d8: `@getenginex/sdk/testing` ganha `markDepositPaid(mockFetch, depositId)`: simula o banco confirmando um
  PIX no estado do `createMockFetch` (o depósito vira `completed` e o saldo sobe o valor dele, uma
  única vez).
* 126ff24: Novo namespace `profile` no cliente: `profile.get()` (`GET /me`), `profile.update({ username?,
  displayName? })` (`PUT /me`), `profile.listSessions()` (`GET /me/sessions`) e
  `profile.revokeSession({ sessionId })` (`DELETE /me/sessions/{id}`), todos com login obrigatório.
  Novos tipos `Profile`, `ProfileSession`, `UpdateProfileInput` e `ProfileApi`. O `createMockFetch` de
  `@getenginex/sdk/testing` ganha rotas padrão para `/me` e `/me/sessions`.
* eb3921a: Ids `.`/`..` num segmento do caminho (ex.: `deposits.get({ depositId: '..' })`), que a URL
  normalizaria para outra rota, agora rejeitam com `INVALID_ARGUMENT` (`status: 0`) antes de qualquer
  `fetch` — inclusive nos requests de pacotes de produto via `@getenginex/sdk/extension`. O `raw`
  entregue a `onValidationIssue` passa a mascarar também as chaves `ip`, `device`,
  `user_agent`/`userAgent` (nome exato) e as terminadas em `_url`/`Url`.
* 7144ada: Modo `validation: 'warn'` agora recupera **por campo**: um campo fora do formato chega como veio (em
  camelCase) e o resto da resposta continua convertido (listas desembrulhadas, enums normalizados,
  dinheiro em `number`, padrões preenchidos, `nextCursor` normalizado), inclusive nos schemas de
  pacotes de produto feitos com `wire`/`mapOf` de `@getenginex/sdk/extension`. Antes, qualquer
  divergência entregava a resposta inteira só em camelCase, sem nenhuma conversão. `onValidationIssue`
  recebe os caminhos completos dos campos. Mudança de comportamento: se a própria raiz da resposta não
  tem o formato esperado (ex.: texto no lugar de objeto), o modo `'warn'` passa a lançar
  `VALIDATION_ERROR`. O modo `'strict'` não muda.

### 0.1.0

#### Minor Changes

A 0.1.0 nunca foi publicada no npm: todo o conteúdo abaixo sai na 0.2.0, a primeira versão publicada
do SDK TypeScript para os fluxos de player do EngineX.

##### Escopo

* **`createEnginexClient`**: um cliente por app (browser) ou por request (servidor).
* **`config`**: `get`, `getBranding`, `getProducts`, `getSportsbook` e `getSupport`.
* **`auth`**: `register`; `login` com 2FA (`{ status: '2fa_required' }` e nova chamada com
  `twoFactorCode`); `forgotPassword`/`resetPassword`; `verifyEmail`/`resendVerificationEmail`;
  `verifyPhone`/`resendPhoneVerification`; `lookupCpf`; `saveLead`; `logout`; `changePassword`;
  `requestPhoneChange`/`confirmPhoneChange`; `enable2fa`/`verify2fa`/`disable2fa`.
* **`session`**: `get()` e `subscribe()`.
* **Onde guardar os tokens**: `memoryTokenStore` (padrão) e `localStorageTokenStore`, com a interface
  pública `StorageLike` (a opção `storage` do `localStorageTokenStore`, sem depender de `lib: DOM`);
  `TokenStore` para stores próprios.
* **Tenant**: o `X-Original-Host` é resolvido automaticamente — no browser, só em chamadas
  same-origin (`tenantHost ?? location.host`); fora do browser, a partir de `tenantHost` (com
  `baseUrl` absoluto).

##### Assinatura uniforme

* Todo método público segue `(input?, options?)`. Métodos sem parâmetros usam `NoParams` e aceitam
  `undefined` no primeiro argumento (ex.: `logout(undefined, { signal })`).
* `CallOptions = { signal, fetchOptions }` em todo método.
* O código do 2FA se chama `twoFactorCode` em `login`, `verify2fa` e `disable2fa`.

##### Configuração e SSR

* `createEnginexClient` nunca lança por configuração ausente: `baseUrl`, `tenantHost` e `fetch` só são
  resolvidos no primeiro request. Se faltar algo, esse request rejeita com `CONFIGURATION_ERROR` sem
  chamar `fetch` — seguro para singletons importados durante o SSR (Next.js, Nuxt).

##### Sessão

* `session.get()` devolve um snapshot congelado e estável: a mesma referência enquanto a sessão não
  muda, pronto para `useSyncExternalStore`. `Session` tem campos `readonly`.
* Refresh proativo (antes de expirar) e reativo (após um 401), single-flight (requests concorrentes
  compartilham um único refresh) e entre abas (o `localStorageTokenStore` reusa tokens renovados por
  outra aba).
* `onSessionExpired` é chamado só quando o refresh é recusado pelo gateway (400/401/403): a sessão é
  limpa e o request original rejeita com o 401 (rotas com sessão opcional repetem sem token). Falha
  de rede no refresh mantém os tokens.

##### Opções e métodos do cliente

* `autoRefresh` (padrão `true`): com `false`, nenhum refresh é feito — para clientes de servidor.
* `hooks`: `onRequest`/`onResponse` a cada tentativa e `onError` uma vez por chamada pública que
  falhar. Nunca recebem headers, tokens, corpo nem query string; o refresh interno da sessão é
  invisível para eles.
* `fetchOptions` por chamada (ex.: `next`, `cache`, `credentials`): `method`, `body` e `signal` são
  sempre os do SDK, e os headers reservados (`authorization`, `x-original-host`, `idempotency-key`,
  `content-type`, `accept`, `accept-language`) são removidos antes de o SDK aplicar os seus.
* `client.setLocale()` troca o `Accept-Language` dos próximos requests.
* `client.dispose()` solta a assinatura no `tokenStore`; depois dele, todo método rejeita com
  `CONFIGURATION_ERROR` e `session.subscribe` vira no-op. Idempotente; não cancela nada em voo.

##### Erros

* `EnginexError` com `toString()`, `toJSON()` e `EnginexError.from()`, que nunca lança e produz uma
  mensagem limitada que não vaza o conteúdo de objetos arbitrários; tipo `EnginexErrorJSON`.
* `ErrorDetailsMap`, extensível por declaration merging, com `CaptchaRequiredDetails`
  (`captcha_required` → `CaptchaRequiredDetails | undefined`: leia com `e.details?.site_key`).
* `isEnginexError(e, code)` estreita `code` e `details`.
* `GATEWAY_ERROR_CODES` e `SDK_ERROR_CODES` listam todos os códigos conhecidos.

##### Validação de respostas

* Modo `'warn'` por padrão: sem `onValidationIssue`, avisa com `console.warn` uma vez por rota, só com
  a rota e os caminhos dos campos.
* `ValidationIssue.raw` vem mascarado: credenciais (`token`, `password`, `secret`, `backup_codes`) e
  dados pessoais (`cpf`, `email`, `phone`, `name`, `birth_date`/`birthDate`) viram `'[REDACTED]'`.
* Rotas que devolvem tokens ou segredos (`login`, refresh da sessão, `enable2fa`) são sempre
  validadas em modo estrito.

##### Dependências e tamanho

* Única dependência: `zod` (via `zod/mini`), com schemas preguiçosos e tree-shakeable: ~12,8 kB
  (brotli) importando o cliente, ~0,5 kB importando só `isEnginexError`/`EnginexError`.
* O SDK não altera a configuração global nem o locale do Zod do app.

##### Testes: `@getenginex/sdk/testing`

* `createMockFetch` com respostas padrão realistas (config, cadastro, login com e sem 2FA, refresh,
  logout), os helpers `ok` e `fail` e os tipos `MockHandler`, `MockRequest` e `MockFetchOptions`.
* Em Node, o cliente ainda precisa de `baseUrl` absoluto e `tenantHost` (valores fictícios servem).

##### Compatibilidade

* `engines.node >= 20`; ESM e CJS; tipos que compilam sem `lib: DOM`, em `moduleResolution`
  `node16` e `bundler`.
* Browsers, Node, Edge (Vercel Edge, Cloudflare Workers) e Bun.
* Licença Apache-2.0.

##### Política de versões

* Enquanto estiver em `0.x`, versões minor (`0.x.0`) podem trazer mudanças incompatíveis; versões
  patch (`0.x.y`) não. As interfaces devolvidas pelo SDK não foram feitas para o app implementar —
  exceto `TokenStore` e `StorageLike` —, então ganhar campos ou métodos novos não é quebra.

##### Para quem usou uma pré-versão

* `code2fa` → `twoFactorCode`.
* `config.*(options)` → `config.*(undefined, options)`.
* `logout(options)` → `logout(undefined, options)`.
* A referência da API mudou de endereço: agora fica em `/referencia/api/@getenginex/sdk/...`.

:::

## `@getenginex/sdk-igaming`

::: v-pre

### 0.6.0

#### Minor Changes

* 8020869: Align the SDK with the gateway contract in production.

  **Type changes (may need code changes when upgrading):**

  * `@getenginex/sdk`: `PixDeposit.expiresAt` is now optional (`string | undefined`); code such as `new Date(pix.expiresAt)` must handle a missing expiry. New optional fields: `PixDeposit.redirectUrl`, `Deposit.expiresAt` and `Deposit.redirectUrl`.
  * `@getenginex/sdk-igaming`: `GameLaunch` gains the required `launchTarget` (new exported type `LaunchTarget`: `'iframe' | 'redirect' | 'new_tab'` or a future value) and the optional `providerCode` and `expiresAt`. Hand-written `GameLaunch` objects (e.g. test fixtures) need a `launchTarget`.

  **Behavior changes:**

  * `deposits.createPix` no longer throws `VALIDATION_ERROR` after the charge was created when the payment provider reports no expiry.
  * The session is renewed and the request retried only on a 401 that refuses the access token: a 401 without a code (what the gateway's auth middleware answers for a missing, expired or invalid token), `TOKEN_EXPIRED` or `TOKEN_STALE`. A 401 with any other code, such as `INVALID_CREDENTIALS` for a wrong current password in `changePassword` or `disable2fa`, or an explicit `UNAUTHENTICATED`/`TOKEN_INVALID`, is no longer retried and no longer fires `onAccessTokenRejected`. An error body with a top-level `code` (e.g. `TOKEN_STALE`) now keeps that code.
  * `auth.logout` sends the stored refresh token so the gateway revokes it. With an expired access token the gateway refuses the call before revoking, so logout renews once (without storing the new tokens or calling `onSessionExpired`) and revokes the renewed refresh token. The local session is always cleared; if the renewal or the request fails, the refresh token may stay valid on the server until it expires.
  * `casino.launchGame` returns `launchTarget`, so apps can open each game the way its provider requires. A response without it is treated as `iframe`, as before. The testing mock returns `launch_target`, `provider_code` and `expires_at`.
  * `withdrawals.request` docs and the testing mock match the gateway: while an OTP request is pending (until its `expiresAt`, also after its code was confirmed), the same request is replayed and any other request is refused with `FAILED_PRECONDITION` (422) `another withdrawal request is pending`, instead of replacing it. After a confirmed withdrawal, the next one can only be requested once the previous request expires.

#### Patch Changes

* 7be12eb: Code comments, TSDoc and runtime error messages are now in English. Error `code` values are unchanged; if your UI shows `error.message` to players, it now shows English text — map `code` to your own copy instead.
* d330035: READMEs and package metadata in English; docs site now in English, Portuguese and Spanish.

### 0.5.0

#### Minor Changes

* af441d0: **Breaking (antes do 1.0).** Exige `@getenginex/sdk >=0.6.0 <1.0.0`.

  * Dinheiro estrito nas respostas: valores monetários (inteiro seguro, em número ou texto), moeda (`/^[A-Z]{3}$/`) e casas decimais (0-8) inválidos rejeitam a resposta inteira com `VALIDATION_ERROR`, também em `validation: 'warn'` (campanhas de bônus, totais do cassino, resgate de fidelidade e indicações). **Como migrar:** nada no app; um gateway fora do contrato passa a aparecer como erro.
  * Indicações (`referrals`): um valor monetário inválido agora rejeita a lista inteira (antes, o item era descartado em silêncio). **Como migrar:** trate o erro da listagem; não há mais itens sumindo.
  * Decisão registrada (desvio do rascunho, que exigia moeda sempre preenchida): a moeda vazia (`''`) é aceita só nos valores de campanha do bônus e no `currency` do resgate de fidelidade, porque o gateway omite a moeda no protojson quando o valor é 0; aceitar o vazio evita derrubar a listagem de campanhas. Em qualquer outro campo, moeda vazia rejeita a resposta. Pontos de fidelidade e progresso de missões não são dinheiro.
  * Idempotência: as mutations (`bonus.optIn/claim/redeemPromoCode`, `loyalty.redeem`) reaproveitam a `Idempotency-Key` só depois de falha ambígua, para a mesma entrada e na mesma mutation; `ABORTED` libera a chave. **Como migrar:** "tentar de novo" com `mutate({ ...mesmos valores })` já reaproveita a chave; para repetir depois de recarregar a página, passe `idempotencyKey`.

### 0.4.0

#### Minor Changes

* ddc9d2c: Novo entry `@getenginex/sdk-igaming/query`: `createIgamingQueries(igaming)` e
  `createIgamingMutations(igaming)` devolvem uma fábrica por método de leitura (`{ queryKey, queryFn }`) e
  uma mutation por método de escrita (`{ mutationKey, mutationFn, invalidates }`), com os mesmos nomes e
  entradas dos namespaces (`casino`, `bonus`, `missions`, `loyalty`, `referrals`, `sportsbook`) e as mesmas
  convenções de chave do `@getenginex/sdk/query`, compatíveis com `useQuery`/`useMutation`/`prefetchQuery`
  do TanStack Query v5 sem depender dele. Catálogo do cassino e ofertas públicas de bônus usam chave
  `public`; o resto das leituras usa a chave do usuário (`userId` da sessão, `'anonymous'` e
  `UNAUTHENTICATED` sem request quando não há sessão). `bonus.optIn/claim/redeemPromoCode` e
  `loyalty.redeem` mandam uma `Idempotency-Key` por objeto de entrada (o retry não duplica a operação) e
  aceitam `{ idempotencyKey }` na fábrica; `loyalty.redeem` e `bonus.optIn/claim/redeemPromoCode` invalidam o namespace e o saldo
  do core (`wallet`), `referrals.register` invalida `referrals` e `casino.launchGame`
  `casino.listSessions`. `bonus.resolvePromoCode`, `bonus.redeemPromoCode`, `casino.launchGame` e
  `sportsbook.createSession` trazem `gcTime: 0` (código promocional, URL do jogo e token do sportsbook).
  `createIgaming` passa a registrar o objeto do produto no cliente do core
  (`registerProductClient`, do core 0.5.0), por isso o peer `@getenginex/sdk` sobe de `>=0.2.0 <1.0.0`
  para `>=0.5.0 <1.0.0`.

### 0.3.0

#### Minor Changes

* bfd181d: Novo namespace `igaming.missions` (missões): `list({ page?, perPage? })` devolve `Page<Mission>` (envia
  `page` e `limit`; o `Page` sai do `meta` do envelope do gateway) e `listMine()` devolve `UserMission[]`
  (o progresso do jogador, lido de `data.missions`). `Mission` é `{ id, name, description, missionType,
  objectiveType, targetValue, targetGameCategory, targetGames, rewardType, rewardValue, validFrom,
  validTo }`; `UserMission` é `{ id, missionId, missionName, currentProgress, targetValue,
  progressPercentage, status, rewardType, rewardValue, periodEnd, completedAt }`. `targetGames` nulo vira
  `[]`; categoria vazia, data epoch (`1970-01-01T00:00:00Z`) e `period_end`/`completed_at` ausentes viram
  `null`; `targetValue`/`rewardValue` são inteiros e `progressPercentage` é número. `missionType`
  (`daily`, `weekly`, `event`, `permanent`), `objectiveType` (`wager`, `bet_count`, `win_amount`,
  `play_game`, `deposit`), `rewardType` (`bonus`, `free_spins`, `points`, `free_bet`) e `status`
  (`in_progress`, `completed`, `expired`, `claimed`) são uniões abertas em minúsculas: valor desconhecido
  chega cru e vai para `onValidationIssue` em `validation: 'warn'`; em `'strict'`, `VALIDATION_ERROR`.
  `page` que não é inteiro ≥ 1 e `perPage` fora de 1–100 rejeitam com `CONFIGURATION_ERROR` sem request.
  Os dois métodos exigem login. Não há `claim()` (o gateway não tem rota de resgate). `withIgamingRoutes`
  (`@getenginex/sdk-igaming/testing`) responde as duas rotas. Nova página "Missões" nos docs. O peer do core
  continua `>=0.2.0 <1.0.0`.

  Novo namespace `igaming.loyalty` (fidelidade): `get()` devolve `LoyaltyStatus` (`totalPointsEarned`,
  `currentPoints`, `pointsRedeemed`, `currentTier`, `tierPoints`, `lifetimeWagered`, `lifetimeDeposited`,
  `tierBenefits`, `tierExpiresAt`) e `redeem({ points, redemptionType })` devolve `{ redeemedPoints, value,
  currency, bonusId }`. `tierBenefits` é o `tier_benefits_json` já convertido em objeto: texto vazio ou
  ausente vira `null` sem aviso; JSON inválido ou que não é um objeto vira `null` e vai para
  `onValidationIssue` (sem o texto no issue; em `'strict'`, `VALIDATION_ERROR`). `tierExpiresAt`, `value`,
  `currency`, `bonusId` e `currentTier` vazios ou ausentes viram `null`. `redemptionType` é uma união aberta (`bonus`, `cash`,
  `free_bet`); `points` não inteiro ou ≤ 0 e `redemptionType` vazio rejeitam com `CONFIGURATION_ERROR` sem
  request. `redeem` manda `Idempotency-Key` (gerada, ou a de `options.idempotencyKey`, mantida no retry após
  401\), mas o gateway ainda não aplica o middleware de idempotência nesta rota: trave o botão, um duplo
  clique pode resgatar duas vezes. Um 200 sem confirmação (`success` diferente de `true`) rejeita com
  `UNKNOWN` (`status` 200) e a mensagem do gateway quando vem, senão a do SDK: releia `get()` antes de
  tentar de novo. `withIgamingRoutes` responde `GET /loyalty` e `POST /loyalty/redeem`.
  Nova página "Fidelidade" nos docs. O peer do core continua `>=0.2.0 <1.0.0`.

  Novo namespace `igaming.referrals` (indicações): `get()` devolve `ReferralInfo` (`code`, `link`,
  `totalReferrals`, `completedReferrals`, `pendingReferrals`, `totalEarned`, `bonusPerReferral`,
  `minDeposit`); `listHistory({ page?, perPage? })` devolve `Page<Referral>` mais `completedCount` e
  `totalEarned` (o gateway manda a paginação dentro do `data`: o SDK monta o `Page`, calcula `totalPages` e
  não deixa `totalItems` ficar abaixo dos itens já vistos); `register({ code })` devolve `{ id, code, status,
  refereeBonus, createdAt }` (HTTP 201). O gateway escreve o dinheiro como float na unidade maior; o SDK
  converte para unidades menores com `Math.round(valor * 100)`, metades para longe do zero (`19.99` → `1999`,
  `0.1 + 0.2` → `30`, `1e-7` → `0`, negativos mantêm o sinal), e valor não finito rejeita com
  `VALIDATION_ERROR` em `strict`. `Referral` traz `refereeName` e `refereeEmailMasked`
  (`ana@exemplo.com` → `a**@exemplo.com`; vazio ou inválido vira `null`); o e-mail cru e o `referee_id`
  nunca são expostos (nem no resultado, nem nos issues, nem nos erros), também em `validation: 'warn'`
  quando um item falha inteiro e o core devolve a lista crua: o SDK refaz cada indicação (máscara, status,
  dinheiro em unidades menores) e descarta o que não é objeto ou cujo dinheiro não vira unidades menores.
  Um `total_items` fora do formato em `'warn'` vale 0 (nunca `NaN`). `status` (`pending`, `qualified`,
  `completed`, `expired`) é uma união aberta; `completedAt`, `expiresAt` e `createdAt` ausentes ou epoch
  viram `null`. `page` e `perPage` inválidos e `code` vazio rejeitam com `CONFIGURATION_ERROR` sem request.
  Quem está se cadastrando usa `auth.register({ referralCode })` do core. `withIgamingRoutes` responde as
  três rotas. Nova página "Indicações" nos docs. O peer do core continua `>=0.2.0 <1.0.0`.

### 0.2.0

#### Minor Changes

* f91eacb: Novo namespace `igaming.sportsbook` com `createSession(params?, options?)` (`GET /first/session`, exige
  login): devolve `{ launchUrl, expiresInSeconds, expiresAt }` para abrir o sportsbook FIRST num iframe.
  `expiresAt` (ms) é calculado no cliente (relógio na resposta + `expiresInSeconds * 1000`); o
  `operator_token` não entra no tipo público. `launchUrl` carrega o token de operador: a resposta é
  sempre validada em modo estrito (`launch_url` http(s) absoluta e `expires_in_seconds` > 0, senão
  `VALIDATION_ERROR`) e nenhum hook nem `onValidationIssue` a recebe. `createIgamingRoutes` /
  `withIgamingRoutes` ganham a rota mock de `/first/session`. Sem cache no SDK: reutilize a sessão até
  `expiresAt - 30 s` e cheque `enginex.config.getSportsbook()` antes.

  Novo entry opcional `@getenginex/sdk-igaming/first-frame` com `connectFirstFrame(iframe, handlers,
  options?)`: ponte tipada para os eventos `postMessage` do iframe do FIRST (`onReady`, `onBetPlaced`,
  `onInsufficientFunds`, `onDepositClick`, `onLoginRequired`, `onHeightChange`, `onRedirect`,
  `onScrollToTop` e `onEvent` genérico) e `send(eventType, eventData)` para comandos. Em `onRedirect`,
  `link` só chega se for texto (um `link` de outro tipo é descartado). Só entrega mensagens
  com `event.source === iframe.contentWindow` e `event.origin` igual à origem do `src`; `send` posta
  sempre para essa origem (nunca `'*'`). Não importa o core em runtime nem exige `lib.dom`
  (`FirstFrameTarget`/`FirstFrameWindow` são estruturais); os erros de configuração são
  `CONFIGURATION_ERROR` reconhecidos por `isEnginexError`. Fora do entry principal: quem importa só
  `createIgaming` não o leva no bundle.

### 0.1.0

#### Minor Changes

* 7be46cc: Namespace `bonus` em `createIgaming(enginex)`: `listPublicOffers` (vitrine pública, sem mandar a
  sessão), `listOffers`, `getOffer`, `listParticipations` e `getParticipation` (paginação por cursor:
  `CursorPage`/`CursorPageInput` do core), `optIn`, `claim` e `redeemPromoCode` (idempotentes: mandam
  `Idempotency-Key`, a do chamador em `options.idempotencyKey` ou uma gerada, reusada no retry após
  401; respostas validadas sempre em modo estrito) e `resolvePromoCode`. As campanhas chegam do formato
  protojson do gateway em camelCase, com enums sem prefixo e em minúsculas, dinheiro em `number`
  (unidades menores), durações em segundos e o estado da participação em `status` (+ `qualifiedAt`,
  `completedAt`, `expiredAt`). `/testing` ganha as rotas mock de bônus (três campanhas, promo code
  `BEMVINDO`, opt-in/claim/resgate com estado e replay por `Idempotency-Key`).
* 6397a2f: Namespace `casino` em `createIgaming(enginex)`: `listGames` (filtros por categoria, provedor, busca,
  `ids` e ordenação, paginado), `listCategories`, `listProviders` e `getGame` (públicos, sem mandar a
  sessão), `launchGame` (exige login; devolve `sessionId` e `gameUrl`, com o idioma vindo do `locale` do
  cliente via `Accept-Language`), `listSessions`, `getHistory` (paginados) e `getBiggestWinners`. A URL
  do jogo carrega o token da sessão de jogo: volta só no resultado — nunca nos hooks nem no
  `onValidationIssue` — e a resposta do launch é validada sempre em modo estrito. Valores do histórico e
  do ranking (int64 em texto no fio) chegam como `number` em unidades menores. `/testing` ganha as rotas
  mock do cassino (catálogo fixo, launch com URL fictícia e sessões em memória).
* eb5d851: Novo pacote `@getenginex/sdk-igaming`: `createIgaming(enginex)` monta os namespaces de iGaming sobre o
  cliente de `@getenginex/sdk` (peer dependency), sem sessão, tenant nem transporte próprios — tudo
  passa pelo contrato `@getenginex/sdk/extension` do core. Um valor que não é um cliente criado por
  `createEnginexClient` é rejeitado com `CONFIGURATION_ERROR`. `@getenginex/sdk-igaming/testing` traz
  `createIgamingRoutes()` e `withIgamingRoutes(options)` para somar as rotas mock de iGaming ao
  `createMockFetch` do core. Cassino e bônus chegam nas próximas versões.
* eb3921a: O core é declarado como peer `@getenginex/sdk@>=0.2.0 <1.0.0` (a primeira versão com o entry
  `@getenginex/sdk/extension`); em tempo de execução, um cliente de uma cópia do core com contrato de
  transporte incompatível faz `createIgaming` lançar `CONFIGURATION_ERROR`.

#### Patch Changes

* Updated dependencies \[ffc0bd1]
* Updated dependencies \[a043c79]
* Updated dependencies \[d4ebcf2]
* Updated dependencies \[cbf1a39]
* Updated dependencies \[826a4d8]
* Updated dependencies \[126ff24]
* Updated dependencies \[eb3921a]
* Updated dependencies \[7144ada]
  * @getenginex/sdk@0.2.0

:::

## `@getenginex/sdk-next`

::: v-pre

### 0.2.1

#### Patch Changes

* 7be12eb: Code comments, TSDoc and runtime error messages are now in English. Error `code` values are unchanged; if your UI shows `error.message` to players, it now shows English text — map `code` to your own copy instead.
* d330035: READMEs and package metadata in English; docs site now in English, Portuguese and Spanish.
* Updated dependencies \[7be12eb]
* Updated dependencies \[d330035]
  * @getenginex/sdk-react@0.2.1

### 0.2.0

#### Minor Changes

* af441d0: Acompanha o `@getenginex/sdk-react` (versão fixa em conjunto): reexporta `useUserKey` e a tentativa de idempotência por instância do `useEnginexMutation`. Exige `@getenginex/sdk >=0.6.0 <1.0.0`. **Como migrar:** nada além de atualizar o core junto; veja as notas do `@getenginex/sdk-react`.

#### Patch Changes

* Updated dependencies \[af441d0]
  * @getenginex/sdk-react@0.2.0

### 0.1.0

#### Minor Changes

* 97610c6: Novo pacote `@getenginex/sdk-next`, adapter do Next.js (App Router). O entry principal reexporta tudo de
  `@getenginex/sdk-react` (dependência do pacote, então o app instala só o `sdk-next`). O entry
  `@getenginex/sdk-next/server` (`server-only`) traz `getEnginexServer(options?)`: um client do core por
  request, memoizado com o `cache()` do React (na mesma request, opções iguais devolvem o mesmo client;
  requests diferentes nunca compartilham client), com o tenant tirado de `headers()` na ordem `host` →
  `x-forwarded-host` (`x-original-host` só com `trustOriginalHost: true`, quando o `proxy.ts` do app o
  sobrescreve em toda request; `resolveHost` troca tudo), o gateway de `baseUrl` ou da
  variável de ambiente `ENGINEX_GATEWAY_URL`, anônimo por padrão (não lê cookies, `autoRefresh: false`) e
  `next: { revalidate, tags }` repassado a todo `fetch`. Sem gateway absoluto ou sem tenant, rejeita com
  `CONFIGURATION_ERROR` antes de qualquer `fetch`. Peers: `next >=15`, `react >=19`,
  `@tanstack/react-query ^5` e `@getenginex/sdk >=0.5.0 <1.0.0`. Sai sempre com a mesma versão do
  `@getenginex/sdk-react` (grupo `fixed` dos changesets).

  `@getenginex/sdk-next/server` traz também `prefetchEnginex(source, select)`: prefetch das
  fábricas do core (com o client do servidor) ou de um pacote de produto (`createIgamingQueries(igaming)`)
  num `QueryClient` novo por chamada, sem retry, devolvendo o `dehydrate` para o `HydrationBoundary`; uma
  fábrica que falha não derruba as outras e fica fora do estado (só queries com sucesso são desidratadas). O
  `staleTime` não viaja no estado: a nova busca no browser depende do `staleTime` do `QueryClient` do browser
  (o que o `EnginexProvider` cria usa 60 s). E `readCookieTokenStore({ name })`, que lê no servidor (só
  leitura, `cookies()` do Next) a sessão gravada pelo `nextCookieTokenStore({ name, maxAge, path })`, o novo
  `TokenStore` em cookie do entry principal (`SameSite=Lax; Secure; Path=/`, sem `HttpOnly`: o refresh e o
  `?token=` do WebSocket precisam do token em JavaScript; fora do browser não guarda nada; um cookie que o
  browser recusa, sem HTTPS ou acima de ~4 KB, gera um `console.warn`; `name`, `path` e `maxAge` inválidos
  lançam `CONFIGURATION_ERROR`). O padrão continua
  o `localStorage`. Novo entry `@getenginex/sdk-next/config` com `withEnginex(nextConfig, { gatewayUrl, paths })`,
  que acrescenta o rewrite `/api/:path*` → gateway preservando os rewrites do app (array ou
  `{ beforeFiles, afterFiles, fallback }`), sem duplicar um `source` que o app já reescreve sem condição
  (`has`/`missing`) e compondo com outros wrappers
  (config em objeto ou função).

#### Patch Changes

* Updated dependencies \[96d4be2]
  * @getenginex/sdk-react@0.1.0

:::

## `@getenginex/sdk-predictions`

::: v-pre

### 0.3.1

#### Patch Changes

* 7be12eb: Code comments, TSDoc and runtime error messages are now in English. Error `code` values are unchanged; if your UI shows `error.message` to players, it now shows English text — map `code` to your own copy instead.
* d330035: READMEs and package metadata in English; docs site now in English, Portuguese and Spanish.

### 0.3.0

#### Minor Changes

* af441d0: **Breaking (antes do 1.0).** Exige `@getenginex/sdk >=0.6.0 <1.0.0`.

  * Dinheiro estrito nas ordens (colateral, taxas e custo), nas posições e no resumo do portfólio: valor monetário fora de inteiro seguro e moeda fora de `/^[A-Z]{3}$/` rejeitam a resposta inteira com `VALIDATION_ERROR`, também em `validation: 'warn'`. Decisão registrada (desvio do rascunho): a moeda vazia (`''`) é aceita só em `settlement_currency`. Preços, quantidades e taxas em bps não são dinheiro e seguem a validação comum; `volume_24h`, `total_volume`, `min_order_size` e `max_position` ficam fora da checagem estrita por decisão (agregados e limites do mercado, em centavos). `settlement_currency` ausente no mercado vira `''` (não rejeita). No realtime, `maker_fee`/`taker_fee` do tópico de trades passam pela mesma checagem: valor monetário inválido descarta a mensagem (como o `coreTopics.balance`). **Como migrar:** nada no app; um gateway fora do contrato passa a aparecer como erro.
  * `orders.placeBatch` por tentativa: as chaves de cada ordem ficam por resultado de `createPredictionsMutations` (no React, memoizado por `useEnginexMutations`), são reaproveitadas depois de falha ambígua (inclusive `KEY_IN_USE` e `VALIDATION_ERROR` depois de 2xx) ou sucesso parcial enquanto o conteúdo do lote for o mesmo, e viram novas depois de sucesso total, erro não ambíguo ou lote diferente. Cada envio fecha só a própria tentativa: um lote que termina depois de outro ter começado não descarta as chaves do outro. **Como migrar:** tire o registro de chaves por objeto; para repetir depois de recarregar a página, passe `idempotencyKey` em cada ordem.
  * Sem Web Crypto, gerar a `idempotencyKey` rejeita com `CONFIGURATION_ERROR` (antes, `UNKNOWN`). **Como migrar:** troque a checagem por `UNKNOWN` por `CONFIGURATION_ERROR`; em HTTP na LAN o SDK usa `getRandomValues` e segue funcionando.

### 0.2.0

#### Minor Changes

* ddc9d2c: Novo entry `@getenginex/sdk-predictions/query`: `createPredictionsQueries(predictions)` e
  `createPredictionsMutations(predictions)` devolvem uma fábrica por método de leitura
  (`{ queryKey, queryFn }`) e uma mutation por método de escrita (`{ mutationKey, mutationFn,
  invalidates }`), com os mesmos nomes e entradas dos namespaces (`markets`, `comments`, `orders`,
  `portfolio`) e as mesmas convenções de chave do `@getenginex/sdk/query`, compatíveis com
  `useQuery`/`useMutation`/`prefetchQuery` do TanStack Query v5 sem depender dele. `markets.*` e
  `comments.list` usam chave `public`; `comments.listMine`, `orders.*` e `portfolio.*` usam a chave do
  usuário (`userId` da sessão, `'anonymous'` e `UNAUTHENTICATED` sem request quando não há sessão).
  `orders.place/placeBatch/cancel/amend` invalidam `orders`, `portfolio` e o saldo do core (`wallet`);
  `comments.create/like/unlike` invalidam `comments.list` e `comments.listMine`. `orders.place` manda uma
  `Idempotency-Key` por objeto de entrada (o retry não duplica a ordem) e aceita `{ idempotencyKey }`;
  `orders.placeBatch` gera uma `idempotencyKey` por ordem do lote, reusada até todas as ordens do lote
  darem certo; sucesso parcial mantém as chaves (reenviar o mesmo lote não duplica as ordens que já
  entraram).
  `createPredictions` passa a registrar o objeto do produto no cliente do core (`registerProductClient`,
  do core 0.5.0), por isso o peer `@getenginex/sdk` sobe de `>=0.3.0 <1.0.0` para `>=0.5.0 <1.0.0`.

### 0.1.0

#### Minor Changes

* 6b14e55: Novo pacote `@getenginex/sdk-predictions` (peer `@getenginex/sdk >=0.3.0 <1.0.0`): `createPredictions(enginex)`
  cria os namespaces de predictions sobre o cliente do core, com a mesma sessão, tenant, hooks, validação e
  `dispose()` (valida o cliente na criação, `CONFIGURATION_ERROR` para um valor que não é um cliente do core, e
  não faz nenhum request). Traz os namespaces `markets` (categorias, eventos, mercados, orderbook e histórico de preços,
  listas como arrays) e `comments` (listar, comentar, curtir e listar os próprios, `{ items, total }`), com enums
  em minúsculas e sem o prefixo do protobuf. Traz também `orders` (colocar uma ordem
  **idempotente**: a mesma chave no header `Idempotency-Key` e em `idempotency_key`, reusada no retry após 401; lote não
  atômico com uma chave por ordem; listar, buscar, cancelar e alterar) e `portfolio` (posições, posição por mercado e
  resumo; `PositionTrade.direction` é `OrderDirection`, normalizada como os demais enums), com ids validados antes do request
  (vazio, com espaço no início ou no fim, com `/`, `.` ou `..` rejeitam com `CONFIGURATION_ERROR`; o SDK não apara ids), preço inteiro (1 a 99 na limitada; opcional na a mercado, que manda 0) e quantidade inteira validados antes do request, e `idempotencyKey` opcional por ordem no lote. O entry `@getenginex/sdk-predictions/realtime` traz `predictionsTopics` (`orderbook`, `trades`, `market` e `orders`, este privado) para o `realtime.subscribe` do core, com enums em minúsculas (aceita `yes` e `ORDER_SIDE_YES` no fio); o snapshot sequenciado de `trades` não é entregue (tem outro formato). O entry `@getenginex/sdk-predictions/testing` traz
  `createPredictionsRoutes()` e `withPredictionsRoutes()` (com o catálogo, os comentários, as ordens e o portfólio mock) para somar ao
  `createMockFetch` do core.

:::

## `@getenginex/sdk-react`

::: v-pre

### 0.2.1

#### Patch Changes

* 7be12eb: Code comments, TSDoc and runtime error messages are now in English. Error `code` values are unchanged; if your UI shows `error.message` to players, it now shows English text — map `code` to your own copy instead.
* d330035: READMEs and package metadata in English; docs site now in English, Portuguese and Spanish.

### 0.2.0

#### Minor Changes

* af441d0: **Breaking (antes do 1.0).** Exige `@getenginex/sdk >=0.6.0 <1.0.0`.

  * `useEnginexMutation` guarda a tentativa de idempotência (entrada e `Idempotency-Key`) **por instância do hook**: ela sobrevive a re-render e ao `retry` do TanStack mesmo com opções novas a cada render, e a chave só é reaproveitada depois de falha ambígua (`NETWORK_ERROR`, `TIMEOUT`, 5xx, `KEY_IN_USE`, `VALIDATION_ERROR` depois de 2xx) para a mesma entrada (por conteúdo). Duas instâncias nunca compartilham chave, e a mesma instância que troca de método (`mutationKey`) também não. Ajustes (`retry`, `onSuccess`...) vão no segundo argumento: espalhar as opções perde a tentativa por instância. **Como migrar:** "tentar de novo" com `mutate({ ...mesmos valores })` já reaproveita a chave, então dá para tirar chaves e objetos guardados à mão; quem precisa repetir depois de recarregar a página passa `idempotencyKey` na fábrica.
  * `orders.placeBatch` (Predictions): a tentativa do lote fica por resultado de `createPredictionsMutations`, memoizado por `useEnginexMutations`.
  * Novo: `useUserKey(namespace?, method?)` devolve o prefixo `['enginex', 'user', userId, namespace?, method?]` da sessão atual para invalidar ou ler do cache (`null` sem sessão).

### 0.1.0

#### Minor Changes

* 96d4be2: Novo pacote `@getenginex/sdk-react`: `EnginexProvider` liga o client do core e o TanStack Query à árvore
  React (usa o `queryClient` do app ou cria um por instância, com `staleTime` de 60 s nas queries e nunca um singleton de módulo), `useEnginex()`
  devolve o client e `useSession()` acompanha login e logout com `useSyncExternalStore` (anônimo no
  servidor e na hidratação). Ao mudar o usuário da sessão (logout ou outro `sub`), o provider remove do
  cache tudo sob `['enginex', 'user']`, mantendo `['enginex', 'public']` e as chaves do app. Bundle com
  `'use client'`. Peers: `react >=18`, `@tanstack/react-query ^5` e `@getenginex/sdk >=0.5.0 <1.0.0`.
  Hooks `useEnginexQueries()` (fábricas do core, ou `(factory, product)` para as de produto, memoizadas por
  client/produto), `useEnginexQuery(options, overrides?)`, `useEnginexMutations()` e
  `useEnginexMutation(options, overrides?)`: erro tipado como `EnginexError`, cancelamento ao desmontar,
  retry que não repete `UNAUTHENTICATED` (os outros erros seguem o `QueryClient` do app) e invalidação de
  `invalidates(input, result)` no sucesso, aguardada antes do `onSuccess` do app e antes de o
  `mutateAsync` resolver. `EnginexProvider` ganha
  `initialSession` (sessão do servidor e da hidratação, para SSR autenticado com cookie, na parte da tela
  que depende só da sessão; queries de usuário em Client Components renderizam só depois da hidratação,
  condicionadas ao `useSession()`).
  Hooks de realtime: `useRealtime(topic, handler)` assina ao montar e cancela ao desmontar (uma assinatura só
  no StrictMode, handler mais recente sem reassinar, tópico comparado pela chave, `null` não assina, tópico
  privado só com usuário e reassinado na troca de usuário), `useRealtimeStatus()` e `useRealtimeSync()`
  (opt-in: invalida o saldo do usuário em `balance_update` sem `setQueryData`, as queries `notifications`
  em cada notificação e as queries `wallet` e `notifications` no `onResync`; tópicos de produto entram em
  `topics: [{ topic, invalidate }]`, com as chaves que cada um alimenta).

:::

## `@getenginex/sdk-vue`

::: v-pre

### 0.1.1

#### Patch Changes

* 7be12eb: Code comments, TSDoc and runtime error messages are now in English. Error `code` values are unchanged; if your UI shows `error.message` to players, it now shows English text — map `code` to your own copy instead.
* d330035: READMEs and package metadata in English; docs site now in English, Portuguese and Spanish.

### 0.1.0

#### Minor Changes

* 1cbfe03: Novo pacote: plugin `EnginexPlugin` e composables Vue (`useSession`, `useUserKey`, `useEnginexQuery`, `useEnginexMutation`, realtime) sobre `@tanstack/vue-query` v5. Queries e mutations recebem um getter das opções.

:::
