Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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çaHojeArquivo
Next^16.3, App Router, src/proxy.tspackage.json
React e TanStackReact ^19.2, @tanstack/react-query ^5.101package.json
Tokenszustand persist no localStorage (chave auth-storage); o servidor nunca vê o tokensrc/shared-modules/auth/ui/stores/useAuthStore.ts
QueryClientsingleton no browser (staleTime 5 min, retry 1, sem refetch no foco); limpeza das chaves de usuário por lista manual no logoutsrc/app/(server-pages)/ClientProviders.tsx
SSRanô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 servidorhost com fallback para x-forwarded-hostos mesmos layouts
GatewayNEXT_PUBLIC_API_URL; rewrites /api/:path* e /dev/:path*next.config.ts
x-original-hosto proxy.ts grava o header só em /api e /devsrc/proxy.ts
Saldopolling 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 ​

bash
pnpm add @getenginex/sdk @getenginex/sdk-next
pnpm add @getenginex/sdk-igaming      # casino/sportsbook player
pnpm add @getenginex/sdk-predictions  # predictions player

O @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):

bash
NEXT_PUBLIC_API_URL=https://gateway.operador.com   # stays: rewrites and the current code
ENGINEX_GATEWAY_URL=https://gateway.operador.com   # new: getEnginexServer

Alternativa 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 getEnginexServer usa host → x-forwarded-host, a mesma ordem que os layouts usam hoje (headersList.get('host') || headersList.get('x-forwarded-host')). Não precisa de trustOriginalHost.

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); ou
  • trustOriginalHost: true com um proxy.ts que sobrescreve o x-original-host em toda request que renderiza, não só em /api e /dev:
ts
// 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.

ts
// 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/logout do store mudam os tokens e o subscribe avisa 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 pelo set, e o user do store continua sendo do player.
  • No servidor esse módulo não tem tokens (o persist não acha localStorage), então importá-lo num Client Component renderizado no SSR é seguro. Para dados no servidor, use sempre o getEnginexServer.
  • 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 o nextCookieTokenStore só faz sentido para SSR com dados do jogador, e traz os custos da tabela de comparação (HTTPS obrigatório fora de localhost, 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.

ts
// 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:

tsx
// 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:

tsx
// 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 QueryClient do player é usado como veio: o staleTime de 5 minutos continua valendo para as queries do SDK e evita a nova busca depois da hidratação. O staleTime de 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 do clearUserScopedQueries até 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):

tsx
'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:

tsx
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:

tsx
// 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 do getEnginexServer; o layout não precisa mais ler o host.
  • 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 em tags. A resposta já é separada por tenant na chave do Data Cache (o X-Original-Host do request entra nela).
  • O prefetch continua anônimo: nada de dados do jogador no SSR, como hoje.
  • Não liste o sdk-next em serverExternalPackages: fora do bundle do servidor, o import de server-only do entry /server falha e o next build para com o erro do server-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:

  1. tire do wsService (useRealTimeUpdates) a assinatura de saldo e de notificações do usuário;
  2. ligue useRealtimeSync() uma vez, no shell do app;
  3. leia o saldo da query (useBalance acima), não do store alimentado pelo WebSocket;
  4. com o realtime estável, o refetchInterval de 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_URL definida em todo ambiente, com o valor de NEXT_PUBLIC_API_URL.
  • [ ] Tenant do SSR conferido em cada ambiente (o Host chega com o domínio público?).
  • [ ] trustOriginalHost só com o proxy.ts que cobre toda request que renderiza.
  • [ ] EnginexProvider com o QueryClient do player (staleTime 5 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).
  • [ ] wsService sem saldo e notificações antes do useRealtimeSync.
  • [ ] Nada de tokenStore com next.revalidate, nem dados do jogador no prefetch.
  • [ ] Exatamente um dono do refresh: fase A com sessionOwner: 'app' e onAccessTokenRejected no SDK; fase B com sessionOwner: 'sdk' e o refresh do interceptor antigo removido.
  • [ ] baseUrl/ENGINEX_GATEWAY_URL só com a origem (sem /api).
  • [ ] Idempotência manual removida onde o useEnginexMutation já cuida dela.