Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

Migrando un player Next ​

Esta guía lleva un player Next que ya existe (como enginex-frontend-player, -igaming y -predictions) a @getenginex/sdk-next poco a poco: el SDK entra junto al código actual, y cada pantalla cambia de datos cuando esté lista. Nada tiene que cambiar de una sola vez.

El punto de partida son los players de hoy:

PiezaHoyArchivo
Next^16.3, App Router, src/proxy.tspackage.json
React y TanStackReact ^19.2, @tanstack/react-query ^5.101package.json
Tokenszustand persist en localStorage (clave auth-storage); el servidor nunca ve el tokensrc/shared-modules/auth/ui/stores/useAuthStore.ts
QueryClientsingleton en el navegador (staleTime 5 min, retry 1, sin refetch al enfocar); limpieza de las claves de usuario con una lista manual al cerrar sesiónsrc/app/(server-pages)/ClientProviders.tsx
SSRanónimo y por tenant; prefetch con new QueryClient() → prefetchQuery → dehydrate → <HydrationBoundary>src/app/(server-pages)/(igaming)/layout.tsx, src/subapps/igaming/ui/pages/lobby-prefetch.server.ts
Tenant en el servidorhost con fallback a x-forwarded-hostlos mismos layouts
GatewayNEXT_PUBLIC_API_URL; rewrites /api/:path* y /dev/:path*next.config.ts
x-original-hostproxy.ts escribe el header solo en /api y /devsrc/proxy.ts
Saldopolling de 10 s en React Query y store alimentado por el WebSocket propio (wsService)src/shared-modules/wallet/ui/hooks/useBalanceSync.ts, src/shared-modules/realtime/

1. Instala ​

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

El @tanstack/react-query, el react y el next del player ya sirven (peers ^5, >=19 y >=15).

2. Gateway: NEXT_PUBLIC_API_URL → ENGINEX_GATEWAY_URL ​

El cliente del servidor lee la URL del gateway de ENGINEX_GATEWAY_URL (solo del servidor, leída en cada request). Defínela con el mismo valor de NEXT_PUBLIC_API_URL en todos los ambientes (.env.local, el deploy, 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 sin variable nueva: getEnginexServer({ baseUrl: process.env.NEXT_PUBLIC_API_URL }). Recuerda que NEXT_PUBLIC_* se incrusta en el build; ENGINEX_GATEWAY_URL se lee en runtime.

baseUrl es solo el origen

El SDK acepta '' (mismo origen) o el origen del gateway (https://host[:puerto]) y agrega /api/v1 por su cuenta. Un valor con ruta (https://gateway.operador.com/api), barra final, query o credenciales lanza CONFIGURATION_ERROR al crear el cliente. Si el NEXT_PUBLIC_API_URL del player lleva /api, quítalo en el valor de ENGINEX_GATEWAY_URL.

3. Rewrites y proxy.ts: déjalos como están ​

El next.config.ts de los players ya reescribe /api y /dev hacia el gateway antes de los rewrites de locale (un orden que importa), y src/proxy.ts ya escribe x-original-host en esas rutas. Es todo lo que el cliente del navegador necesita: llama a /api/v1/... en el mismo origen.

  • withEnginex es opcional. Agrega el rewrite del gateway después de los de la app; como el player ya tiene /api/:path* y /dev/:path* sin condición, el helper no agregaría nada. Cámbialo solo si quieres quitar el rewrite manual, y comprueba el orden con los rewrites de locale.
  • Tenant en el servidor: getEnginexServer usa host → x-forwarded-host, el mismo orden que usan hoy los layouts (headersList.get('host') || headersList.get('x-forwarded-host')). No necesita trustOriginalHost.

Ingress que reescribe el Host

Si en algún ambiente el ingress reescribe el Host a un nombre interno (p. ej. el nombre del Service), getEnginexServer tomaría ese nombre como tenant. En ese caso, elige una de las dos opciones:

  • resolveHost, leyendo el header en el que el ingress guarda el dominio público (consulta Tenant); o
  • trustOriginalHost: true con un proxy.ts que sobrescriba x-original-host en todo request que renderiza, no solo en /api y /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).*)'],
}

Sin ese proxy.ts, no actives trustOriginalHost: en una página el x-original-host viene del navegador, y cualquiera elegiría el operador del SSR. El proxy.ts de hoy tiene un atajo que no clona los headers cuando el navegador ya envía x-original-host igual al host; eso sigue siendo correcto, pero el matcher actual (/api, /dev) no cubre las páginas.

4. Tokens: un TokenStore sobre zustand ​

El SDK no necesita otro lugar para la sesión: un TokenStore sobre useAuthStore hace que el SDK lea y escriba los mismos tokens que el resto del player, en el mismo auth-storage de 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)
  • El inicio y el cierre de sesión del player siguen funcionando: el setAuth/logout del store cambian los tokens y subscribe avisa al SDK. En la fase A (abajo) el inicio y el cierre de sesión son solo del player; en la fase B, un inicio de sesión hecho por el SDK (enginex.auth.login) escribe los tokens con set, y el user del store sigue siendo del player.
  • En el servidor este módulo no tiene tokens (persist no encuentra localStorage), así que importarlo en un Client Component renderizado en el SSR es seguro. Para datos en el servidor, usa siempre getEnginexServer.
  • Exactamente un dueño del refresh: consulta la sección de abajo antes de activar el cliente en producción.
  • La cookie es opcional: la sesión puede seguir en localStorage. Pasar a nextCookieTokenStore solo tiene sentido para SSR con datos del jugador, y trae los costos de la tabla de comparación (HTTPS obligatorio fuera de localhost, refresh token en los logs, cuidado con el caché y el HTML).

Un solo dueño del refresh ​

Con los dos clientes leyendo el mismo store, ambos saben renovar la sesión: el SDK renueva antes de que venza el access token (faltando 2 minutos) y después de un 401; el cliente HTTP del player (http-client.api.browser.ts) renueva después de un 401. El SDK suele llegar primero, pero nada lo garantiza (pestañas en segundo plano, reloj, un 401 de los dos al mismo tiempo). Si los dos cambian el mismo refresh token, el segundo refresh puede ser rechazado y la sesión se cae. Por eso la migración tiene un dueño del refresh a la vez:

Fase A, convivencia: el player renueva, el SDK no. El cliente del SDK arranca con sessionOwner: 'app': usa el access token que está en el store, nunca llama a /auth/refresh y no escribe ni limpia tokens (auth.login y auth.logout lanzan CONFIGURATION_ERROR antes de enviar). El cliente actual sigue siendo dueño del refresh y escribe los tokens nuevos en useAuthStore, y el subscribe del TokenStore avisa al SDK. Cuando el gateway rechaza el token (401), el SDK llama a onAccessTokenRejected una vez por token, incluso en una ráfaga de queries; es el lugar para pedir el refresh a su dueño. Consulta Sesión y 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()
  },
})

El costo: una llamada del SDK hecha entre el vencimiento del access token y el próximo refresh del player falla con UNAUTHENTICATED (el 401 del gateway, sin refresh ni nuevo intento). useEnginexQuery no reintenta ese error. Rehaz las queries con error cuando el token cambie:

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],
)

Una mutation que falló así no se reintenta sola: muestra el error con "reintentar", o, en un mutateAsync, espera el refresh del player y vuelve a llamar una vez. Un 401 libera la clave de idempotencia (no es una falla ambigua): la nueva llamada es una operación nueva, y no duplica nada porque el gateway rechazó la primera antes de procesarla.

Fase B, el SDK es el dueño. Cuando el inicio de sesión y las llamadas autenticadas ya pasan por el SDK, invierte: cambia a sessionOwner: 'sdk' (el valor por defecto; quita el sessionOwner y el onAccessTokenRejected de arriba, que juntos solo valen en la fase A), y elimina el refresh del interceptor antiguo (lo que quede del cliente HTTP del player solo lee el token del store; un 401 en él se convierte en un error o llama a una query del SDK). A partir de ahí el SDK renueva antes de vencer y después de un 401, y escribe en el store con set.

Nunca dejes a los dos renovando al mismo tiempo, ni siquiera por un deploy.

5. Provider con el QueryClient existente ​

En ClientProviders.tsx, envuelve el árbol con EnginexProvider pasando el mismo 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>
  )
}
  • El QueryClient del player se usa tal como viene: el staleTime de 5 minutos sigue valiendo para las queries del SDK y evita un nuevo request después de la hidratación. El staleTime de 60 s del SDK solo vale cuando la app no pasa el suyo.
  • Al cambiar de usuario el provider elimina ['enginex', 'user']. Las claves antiguas del player (['wallet'], ['campaignOffers']...) siguen en la lista de clearUserScopedQueries hasta que migre la última pantalla que las usa.

6. Cambia las queries una pantalla a la vez ​

Las claves del SDK (['enginex', 'user', userId, 'wallet', 'getBalance']) son distintas de las del player (['balance']). Migra los lectores y escritores de un mismo dato juntos: si el saldo viene del SDK pero el depósito todavía invalida ['balance'], el saldo nuevo no se actualiza después del depósito.

Ejemplo, el 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 })
}

Y el depósito, que invalida saldo, transacciones y depósitos solo:

tsx
import { useEnginexMutation, useEnginexMutations } from '@getenginex/sdk-next'

const m = useEnginexMutations()
const pix = useEnginexMutation(m.deposits.createPix())

Quita la idempotencia manual. Los crypto.randomUUID() y los Maps de claves que el player guarda para depósito, retiro y bono salen junto con ella: con useEnginexMutation, la Idempotency-Key solo se reutiliza después de una falla ambigua (red, timeout, 5xx, KEY_IN_USE o VALIDATION_ERROR después de un 2xx), para la misma entrada, y queda guardada por instancia del hook. Un "reintentar" con un pix.mutate({ amount }) literal ya reutiliza la clave. Mantén una clave propia (m.deposits.createPix({ idempotencyKey })) solo donde la operación necesite sobrevivir a una recarga. Consulta React.

Claves del usuario. Para invalidar los datos del SDK desde dentro de un componente, useUserKey('wallet') (de @getenginex/sdk-next) devuelve el prefijo del jugador con sesión iniciada, o null sin sesión; fuera de un componente, enginexKeys.user(userId, 'wallet').

Un orden que funciona bien: configuración y catálogo (públicos, sin riesgo), después saldo y billetera (lectura y depósito/retiro juntos), después el resto. Los hooks del player que ya llaman al gateway siguen funcionando mientras tanto.

7. Prefetch en el servidor ​

El prefetchCatalog de hoy crea un QueryClient, llama a prefetchQuery con las claves propias y devuelve el dehydrate. Con el 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>
)
  • El tenant sale de headers() dentro de getEnginexServer; el layout ya no necesita leer el host.
  • Cambia el componente junto con esto: el rail necesita leer con useEnginexQuery(ig.casino.listCategories()), o el dato hidratado (con la clave del SDK) queda sin uso y el componente pide el suyo.
  • Las tags son fijas por llamada. Hoy el player usa una tag por host (catalog-${host}) para invalidar un solo tenant; para mantenerlo, lee el host tú mismo y pásalo en tags. La respuesta ya está separada por tenant en la clave del Data Cache (el X-Original-Host del request entra en ella).
  • El prefetch sigue siendo anónimo: nada de datos del jugador en el SSR, como hoy.
  • No incluyas sdk-next en serverExternalPackages: fuera del bundle del servidor, el import de server-only del entry /server falla y next build se detiene con el error de server-only. Si el player ya tiene esa lista, comprueba que el SDK no esté en ella.

8. Realtime: apaga el WebSocket propio antes de useRealtimeSync ​

useRealtimeSync() abre la conexión del SDK e invalida saldo y notificaciones en cada mensaje. Con el wsService del player todavía activo para los mismos eventos, quedan dos conexiones y cada balance_update se procesa dos veces (store de zustand y caché). Por tópico:

  1. quita de wsService (useRealTimeUpdates) la suscripción de saldo y de notificaciones del usuario;
  2. activa useRealtimeSync() una vez, en el shell de la app;
  3. lee el saldo de la query (useBalance de arriba), no del store alimentado por el WebSocket;
  4. con el realtime estable, el refetchInterval de 10 s puede subir o eliminarse.

La URL del WebSocket viene de wsUrl en createEnginexClient (sin ella, del origen de la página + /ws, por el mismo proxy). Los tópicos de predictions (orderbook, órdenes) entran en useRealtimeSync({ topics }) o useRealtime, consulta React.

Checklist ​

  • [ ] ENGINEX_GATEWAY_URL definida en todos los ambientes, con el valor de NEXT_PUBLIC_API_URL.
  • [ ] Tenant del SSR comprobado en cada ambiente (¿el Host llega con el dominio público?).
  • [ ] trustOriginalHost solo con el proxy.ts que cubre todo request que renderiza.
  • [ ] EnginexProvider con el QueryClient del player (staleTime 5 min).
  • [ ] Cada dato migrado con lectores y escritores juntos; claves antiguas todavía en clearUserScopedQueries.
  • [ ] Componentes hidratados leyendo con las fábricas del SDK (misma clave del prefetch).
  • [ ] wsService sin saldo ni notificaciones antes de useRealtimeSync.
  • [ ] Nada de tokenStore con next.revalidate, ni datos del jugador en el prefetch.
  • [ ] Exactamente un dueño del refresh: fase A con sessionOwner: 'app' y onAccessTokenRejected en el SDK; fase B con sessionOwner: 'sdk' y el refresh del interceptor antiguo eliminado.
  • [ ] baseUrl/ENGINEX_GATEWAY_URL solo con el origen (sin /api).
  • [ ] Idempotencia manual eliminada donde useEnginexMutation ya se encarga de ella.