Migrando um player Next
Este guia leva um player Next que já existe (como o enginex-frontend-player, o -igaming e o -predictions) para o @getenginex/sdk-next aos poucos: o SDK entra ao lado do código atual, e cada tela troca de dados quando estiver pronta. Nada precisa mudar de uma vez.
O ponto de partida são os players de hoje:
| Peça | Hoje | Arquivo |
|---|---|---|
| Next | ^16.3, App Router, src/proxy.ts | package.json |
| React e TanStack | React ^19.2, @tanstack/react-query ^5.101 | package.json |
| Tokens | zustand persist no localStorage (chave auth-storage); o servidor nunca vê o token | src/shared-modules/auth/ui/stores/useAuthStore.ts |
QueryClient | singleton no browser (staleTime 5 min, retry 1, sem refetch no foco); limpeza das chaves de usuário por lista manual no logout | src/app/(server-pages)/ClientProviders.tsx |
| SSR | anônimo e por tenant; prefetch com new QueryClient() → prefetchQuery → dehydrate → <HydrationBoundary> | src/app/(server-pages)/(igaming)/layout.tsx, src/subapps/igaming/ui/pages/lobby-prefetch.server.ts |
| Tenant no servidor | host com fallback para x-forwarded-host | os mesmos layouts |
| Gateway | NEXT_PUBLIC_API_URL; rewrites /api/:path* e /dev/:path* | next.config.ts |
x-original-host | o proxy.ts grava o header só em /api e /dev | src/proxy.ts |
| Saldo | polling de 10 s em React Query e store alimentado pelo WebSocket próprio (wsService) | src/shared-modules/wallet/ui/hooks/useBalanceSync.ts, src/shared-modules/realtime/ |
1. Instale
pnpm add @getenginex/sdk @getenginex/sdk-next
pnpm add @getenginex/sdk-igaming # casino/sportsbook player
pnpm add @getenginex/sdk-predictions # predictions playerO @tanstack/react-query, o react e o next do player já servem (peers ^5, >=19 e >=15).
2. Gateway: NEXT_PUBLIC_API_URL → ENGINEX_GATEWAY_URL
O client do servidor lê a URL do gateway de ENGINEX_GATEWAY_URL (só do servidor, lida a cada request). Defina-a com o mesmo valor de NEXT_PUBLIC_API_URL em todo ambiente (.env.local, o deploy, o Amplify/Kubernetes):
NEXT_PUBLIC_API_URL=https://gateway.operador.com # stays: rewrites and the current code
ENGINEX_GATEWAY_URL=https://gateway.operador.com # new: getEnginexServerAlternativa sem variável nova: getEnginexServer({ baseUrl: process.env.NEXT_PUBLIC_API_URL }). Lembre que NEXT_PUBLIC_* é embutida no build; a ENGINEX_GATEWAY_URL é lida em runtime.
baseUrl é só a origem
O SDK aceita '' (mesma origem) ou a origem do gateway (https://host[:porta]) e acrescenta /api/v1 sozinho. Um valor com caminho (https://gateway.operador.com/api), barra final, query ou credenciais lança CONFIGURATION_ERROR na criação do client. Se o NEXT_PUBLIC_API_URL do player carrega /api, tire-o no valor da ENGINEX_GATEWAY_URL.
3. Rewrites e proxy.ts: deixe como estão
O next.config.ts dos players já reescreve /api e /dev para o gateway antes dos rewrites de locale (ordem que importa), e o src/proxy.ts já grava o x-original-host nessas rotas. É tudo o que o client do browser precisa: ele chama /api/v1/... na mesma origem.
withEnginexé opcional. Ele acrescenta o rewrite do gateway depois dos do app; como o player já tem/api/:path*e/dev/:path*sem condição, o helper não acrescentaria nada. Só troque se quiser tirar o rewrite manual, e confira a ordem com os rewrites de locale.- Tenant no servidor: o
getEnginexServerusahost→x-forwarded-host, a mesma ordem que os layouts usam hoje (headersList.get('host') || headersList.get('x-forwarded-host')). Não precisa detrustOriginalHost.
Ingress que reescreve o Host
Se em algum ambiente o ingress reescrever o Host para um nome interno (ex.: o nome do Service), o getEnginexServer pegaria esse nome como tenant. Nesse caso, escolha um dos dois:
resolveHost, lendo o header em que o ingress guarda o domínio público (veja Tenant); outrustOriginalHost: truecom umproxy.tsque sobrescreve ox-original-hostem toda request que renderiza, não só em/apie/dev:
// src/proxy.ts
import { NextResponse, type NextRequest } from 'next/server'
export function proxy(request: NextRequest) {
const headers = new Headers(request.headers)
// The public domain comes from the header where the ingress stores it, since `Host` arrives rewritten. Here,
// `x-forwarded-host`: swap in your ingress's header (check in production which one it is).
const host =
request.headers.get('x-forwarded-host')?.split(',')[0]?.trim() || request.headers.get('host')
// Always overwrite (or delete): the value the browser sent never reaches SSR or the gateway.
if (host) headers.set('x-original-host', host)
else headers.delete('x-original-host')
return NextResponse.next({ request: { headers } })
}
export const config = {
// Every request that renders (pages, /api, /dev), except Next's static files.
matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}Sem esse proxy.ts, não ligue trustOriginalHost: numa página o x-original-host vem do browser, e qualquer um escolheria o operador do SSR. O proxy.ts de hoje tem um atalho que não clona os headers quando o browser já manda x-original-host igual ao host; isso continua correto, mas o matcher atual (/api, /dev) não cobre as páginas.
4. Tokens: um TokenStore sobre o zustand
O SDK não precisa de outro lugar para a sessão: um TokenStore sobre o useAuthStore faz o SDK ler e gravar os mesmos tokens que o resto do player, no mesmo auth-storage do localStorage.
// src/shared/lib/enginex.ts
import { createEnginexClient, type TokenStore } from '@getenginex/sdk'
import { createIgaming } from '@getenginex/sdk-igaming'
import { useAuthStore } from '@/shared-modules/auth/ui/stores/useAuthStore'
const authStoreTokens: TokenStore = {
get() {
const { accessToken, refreshToken } = useAuthStore.getState()
return accessToken && refreshToken ? { accessToken, refreshToken } : null
},
set({ accessToken, refreshToken }) {
useAuthStore.getState().updateTokens(accessToken, refreshToken)
useAuthStore.setState({ isAuthenticated: true })
},
clear() {
useAuthStore.getState().logout()
},
subscribe(listener) {
return useAuthStore.subscribe((state, prev) => {
if (state.accessToken !== prev.accessToken || state.refreshToken !== prev.refreshToken) listener()
})
},
}
export const enginex = createEnginexClient({ locale: 'pt-BR', tokenStore: authStoreTokens })
export const igaming = createIgaming(enginex)- O login e o logout do player continuam funcionando: o
setAuth/logoutdo store mudam os tokens e osubscribeavisa o SDK. Na fase A (abaixo) o login e o logout são só do player; na fase B, um login feito pelo SDK (enginex.auth.login) grava os tokens peloset, e ouserdo store continua sendo do player. - No servidor esse módulo não tem tokens (o
persistnão achalocalStorage), então importá-lo num Client Component renderizado no SSR é seguro. Para dados no servidor, use sempre ogetEnginexServer. - Exatamente um dono do refresh: veja a seção abaixo antes de ligar o client em produção.
- Cookie é opcional: a sessão pode continuar no
localStorage. Mover para onextCookieTokenStoresó faz sentido para SSR com dados do jogador, e traz os custos da tabela de comparação (HTTPS obrigatório fora delocalhost, refresh token nos logs, cuidado com cache e HTML).
Um dono só para o refresh
Com os dois clientes lendo o mesmo store, os dois sabem renovar a sessão: o SDK renova antes de o access token vencer (faltando 2 minutos) e depois de um 401; o cliente HTTP do player (http-client.api.browser.ts) renova depois de um 401. O SDK costuma chegar primeiro, mas nada garante isso (abas em segundo plano, relógio, um 401 dos dois ao mesmo tempo). Se os dois trocarem o mesmo refresh token, o segundo refresh pode ser recusado e a sessão cai. Por isso a migração tem um dono do refresh por vez:
Fase A, convivência: o player renova, o SDK não. O client do SDK sobe com sessionOwner: 'app': usa o access token que está no store, nunca chama /auth/refresh e não grava nem limpa tokens (auth.login e auth.logout lançam CONFIGURATION_ERROR antes de enviar). O cliente atual continua dono do refresh e grava os tokens novos no useAuthStore, e o subscribe do TokenStore avisa o SDK. Quando o gateway recusa o token (401), o SDK chama o onAccessTokenRejected uma vez por token, mesmo numa rajada de queries; é o lugar de pedir o refresh ao dono dele. Veja Sessão e tokens.
// src/shared/lib/enginex.ts (fase A)
export const enginex = createEnginexClient({
locale: 'pt-BR',
tokenStore: authStoreTokens,
sessionOwner: 'app', // the player's HTTP client is the only one that refreshes
// An SDK 401 (expired token) asks its owner for the refresh, which already avoids duplicate refreshes.
onAccessTokenRejected: () => {
if (useAuthStore.getState().refreshToken) void refreshPlayerSession() // e.g. the current client's refreshOnce/sessionProvider.refreshToken()
},
})O custo: uma chamada do SDK feita entre o vencimento do access token e o próximo refresh do player falha com UNAUTHENTICATED (o 401 do gateway, sem refresh nem nova tentativa). O useEnginexQuery não repete esse erro. Refaça as queries com erro quando o token mudar:
// in a component inside the EnginexProvider (e.g. ClientProviders)
import { enginexKeys } from '@getenginex/sdk/query'
import { useQueryClient } from '@tanstack/react-query'
import { useEffect } from 'react'
const queryClient = useQueryClient()
useEffect(
() =>
useAuthStore.subscribe((state, prev) => {
if (state.accessToken && state.accessToken !== prev.accessToken) {
void queryClient.refetchQueries({
queryKey: enginexKeys.user(),
predicate: (query) => query.state.status === 'error',
})
}
}),
[queryClient],
)Uma mutation que falhou assim não é repetida sozinha: mostre o erro com "tentar de novo", ou, num mutateAsync, espere o refresh do player e chame de novo uma vez. Um 401 libera a chave de idempotência (não é falha ambígua): a nova chamada é uma operação nova, e não duplica nada porque o gateway recusou a primeira antes de processar.
Fase B, o SDK é o dono. Quando o login e as chamadas autenticadas já passam pelo SDK, inverta: troque para sessionOwner: 'sdk' (o padrão; tire o sessionOwner e o onAccessTokenRejected acima, que juntos só valem na fase A), e remova o refresh do interceptor antigo (o que sobrar do cliente HTTP do player só lê o token do store; um 401 nele vira erro ou chama uma query do SDK). A partir daí o SDK renova antes de vencer e depois de um 401, e grava no store pelo set.
Nunca deixe os dois renovando ao mesmo tempo, nem por um deploy.
5. Provider com o QueryClient existente
No ClientProviders.tsx, envolva a árvore com o EnginexProvider passando o mesmo QueryClient:
// src/app/(server-pages)/ClientProviders.tsx (excerpt)
'use client'
import { EnginexProvider } from '@getenginex/sdk-next'
import { QueryClientProvider } from '@tanstack/react-query'
import { enginex } from '@/shared/lib/enginex'
export default function ClientProviders({ children }: ClientProvidersProps) {
const queryClient = getQueryClient() // the same one as today: staleTime 5 min, retry 1
return (
<EnginexProvider client={enginex} queryClient={queryClient}>
{/* the current QueryClientProvider can go: the EnginexProvider already renders it with the same client */}
{children}
</EnginexProvider>
)
}- O
QueryClientdo player é usado como veio: ostaleTimede 5 minutos continua valendo para as queries do SDK e evita a nova busca depois da hidratação. OstaleTimede 60 s do SDK só vale quando o app não passa o seu. - Na troca de usuário o provider remove
['enginex', 'user']. As chaves antigas do player (['wallet'],['campaignOffers']...) continuam na lista doclearUserScopedQueriesaté a última tela que as usa migrar.
6. Troque as queries uma tela por vez
As chaves do SDK (['enginex', 'user', userId, 'wallet', 'getBalance']) são diferentes das do player (['balance']). Migre leitores e escritores de um mesmo dado juntos: se o saldo vem do SDK mas o depósito ainda invalida ['balance'], o saldo novo não é atualizado depois do depósito.
Exemplo, o saldo (useBalanceSync.ts):
'use client'
import { useEnginexQueries, useEnginexQuery } from '@getenginex/sdk-next'
export function useBalance() {
const q = useEnginexQueries()
return useEnginexQuery(q.wallet.getBalance(), { refetchInterval: 10_000 })
}E o depósito, que invalida saldo, transações e depósitos sozinho:
import { useEnginexMutation, useEnginexMutations } from '@getenginex/sdk-next'
const m = useEnginexMutations()
const pix = useEnginexMutation(m.deposits.createPix())Tire a idempotência manual. Os crypto.randomUUID() e os Maps de chave que o player guarda para depósito, saque e bônus saem junto: com useEnginexMutation, a Idempotency-Key só é reaproveitada depois de falha ambígua (rede, timeout, 5xx, KEY_IN_USE ou VALIDATION_ERROR depois de 2xx), para a mesma entrada, e fica guardada por instância do hook. Um "tentar de novo" com pix.mutate({ amount }) literal já reaproveita a chave. Só mantenha uma chave sua (m.deposits.createPix({ idempotencyKey })) onde a operação precisa sobreviver a um reload. Veja React.
Chaves do usuário. Para invalidar os dados do SDK de dentro de um componente, useUserKey('wallet') (do @getenginex/sdk-next) devolve o prefixo do jogador logado, ou null sem sessão; fora de componente, enginexKeys.user(userId, 'wallet').
Uma ordem que funciona bem: configuração e catálogo (públicos, sem risco), depois saldo e carteira (leitura e depósito/saque juntos), depois o resto. Os hooks do player que já chamam o gateway continuam funcionando enquanto isso.
7. Prefetch no servidor
O prefetchCatalog de hoje cria um QueryClient, chama prefetchQuery com as chaves próprias e devolve o dehydrate. Com o SDK:
// src/app/(server-pages)/(igaming)/layout.tsx (excerpt)
import { HydrationBoundary } from '@tanstack/react-query'
import { createIgaming } from '@getenginex/sdk-igaming'
import { createIgamingQueries } from '@getenginex/sdk-igaming/query'
import { getEnginexServer, prefetchEnginex } from '@getenginex/sdk-next/server'
const enginex = await getEnginexServer({ next: { revalidate: 300, tags: ['catalog'] } })
const catalog = await prefetchEnginex(createIgamingQueries(createIgaming(enginex)), (ig) => [
ig.casino.listCategories(),
ig.casino.listProviders(),
])
return (
<HydrationBoundary state={catalog}>
<IGamingLayout>{children}</IGamingLayout>
</HydrationBoundary>
)- O tenant sai do
headers()dentro dogetEnginexServer; o layout não precisa mais ler ohost. - Troque o componente junto: o rail precisa ler com
useEnginexQuery(ig.casino.listCategories()), ou o dado hidratado (com a chave do SDK) fica sem uso e o componente busca o dele. - As tags são fixas por chamada. O player hoje usa uma tag por host (
catalog-${host}) para invalidar um tenant só; para manter isso, leia o host você mesmo e passe-o emtags. A resposta já é separada por tenant na chave do Data Cache (oX-Original-Hostdo request entra nela). - O prefetch continua anônimo: nada de dados do jogador no SSR, como hoje.
- Não liste o
sdk-nextemserverExternalPackages: fora do bundle do servidor, o import deserver-onlydo entry/serverfalha e onext buildpara com o erro doserver-only. Se o player já tem essa lista, confira que o SDK não está nela.
8. Realtime: desligue o WebSocket próprio antes do useRealtimeSync
O useRealtimeSync() abre a conexão do SDK e invalida saldo e notificações a cada mensagem. Com o wsService do player ainda ligado para os mesmos eventos, ficam duas conexões e cada balance_update é tratado duas vezes (store zustand e cache). Por tópico:
- tire do
wsService(useRealTimeUpdates) a assinatura de saldo e de notificações do usuário; - ligue
useRealtimeSync()uma vez, no shell do app; - leia o saldo da query (
useBalanceacima), não do store alimentado pelo WebSocket; - com o realtime estável, o
refetchIntervalde 10 s pode subir ou sair.
A URL do WebSocket vem de wsUrl no createEnginexClient (sem ela, da origem da página + /ws, pelo mesmo proxy). Tópicos de predictions (orderbook, ordens) entram em useRealtimeSync({ topics }) ou useRealtime, veja React.
Checklist
- [ ]
ENGINEX_GATEWAY_URLdefinida em todo ambiente, com o valor deNEXT_PUBLIC_API_URL. - [ ] Tenant do SSR conferido em cada ambiente (o
Hostchega com o domínio público?). - [ ]
trustOriginalHostsó com oproxy.tsque cobre toda request que renderiza. - [ ]
EnginexProvidercom oQueryClientdo player (staleTime5 min). - [ ] Cada dado migrado com leitores e escritores juntos; chaves antigas ainda no
clearUserScopedQueries. - [ ] Componentes hidratados lendo com as fábricas do SDK (mesma chave do prefetch).
- [ ]
wsServicesem saldo e notificações antes douseRealtimeSync. - [ ] Nada de
tokenStorecomnext.revalidate, nem dados do jogador no prefetch. - [ ] Exatamente um dono do refresh: fase A com
sessionOwner: 'app'eonAccessTokenRejectedno SDK; fase B comsessionOwner: 'sdk'e o refresh do interceptor antigo removido. - [ ]
baseUrl/ENGINEX_GATEWAY_URLsó com a origem (sem/api). - [ ] Idempotência manual removida onde o
useEnginexMutationjá cuida dela.