Primeiros passos
Escolha o produto
O SDK é dividido por produto. Todo app instala o core (@getenginex/sdk); cada produto do operador vem num pacote à parte, que usa o cliente do core (a mesma sessão, tenant e configuração):
| O app precisa de | Instale | Trilha |
|---|---|---|
| cadastro, login e 2FA, senha, perfil, carteira, depósito e saque PIX, chaves PIX, KYC, jogo responsável, notificações | @getenginex/sdk | Core |
| tudo acima + cassino (lobby, abrir jogo, histórico), bônus (campanhas, promo codes), missões, fidelidade e indicações | @getenginex/sdk + @getenginex/sdk-igaming | iGaming |
npm i @getenginex/sdk # core only
npm i @getenginex/sdk @getenginex/sdk-igaming # core + casino, bonuses and engagementO core é peer dependency dos pacotes de produto: instale-o sempre junto, uma única vez. Quem não usa cassino não instala (nem carrega) código de cassino. Os passos abaixo valem para qualquer produto; o de iGaming só acrescenta o passo 6.
1. Crie o cliente
Crie um cliente por app no browser e exporte-o:
// enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
export const enginex = createEnginexClient({
locale: 'pt-BR',
tokenStore: localStorageTokenStore(),
onSessionExpired: () => location.assign('/login'),
})No servidor (SSR, scripts, testes), crie um cliente por request, informando a URL do gateway e o domínio do operador:
const enginex = createEnginexClient({
baseUrl: 'https://gateway.operador.com',
tenantHost: 'casino.operador.com',
})2. Leia a configuração do operador
const config = await enginex.config.get()
console.log(config.currency.code, config.paymentMethods.map((m) => m.code))3. Faça login
import { isEnginexError } from '@getenginex/sdk'
try {
const result = await enginex.auth.login({ email, password })
if (result.status === '2fa_required') {
// see /flows/login
}
} catch (e) {
if (isEnginexError(e, 'INVALID_CREDENTIALS')) showError('Incorrect email or password')
else throw e
}4. Reaja à sessão
enginex.session.subscribe((session) => {
renderHeader(session.status === 'authenticated')
})5. Idioma e descarte
Troque o idioma a qualquer momento com setLocale — os próximos requests já saem com o Accept-Language novo:
enginex.setLocale('en-US')Um cliente por request (SSR, scripts, testes) não precisa de dispose() — ele já é descartado com o resto do request. Já um cliente de vida curta fora desse caso (ex.: um teste que cria vários clientes) deve chamar dispose() ao terminar, para soltar a assinatura de sessão no tokenStore (o listener de storage, se for o último, no caso do localStorageTokenStore). Depois de dispose(), todo método rejeita com EnginexError CONFIGURATION_ERROR:
const enginex = createEnginexClient({ baseUrl, tenantHost })
try {
await enginex.config.get()
} finally {
enginex.dispose()
}6. Produtos (iGaming)
Com @getenginex/sdk-igaming instalado, crie os namespaces de cassino e bônus sobre o mesmo cliente:
// enginex.ts
import { createIgaming } from '@getenginex/sdk-igaming'
export const igaming = createIgaming(enginex)
const lobby = await igaming.casino.listGames({ category: 'slots', perPage: 24 })createIgaming não cria sessão nem faz request: o login feito com enginex.auth.login vale para o cassino, e enginex.dispose() desliga também o iGaming. Veja a trilha iGaming.
Next.js / SSR
Adapters React e Next.js
Com React ou Next.js, os adapters fazem o que esta seção mostra à mão: @getenginex/sdk-react traz o EnginexProvider, useSession (o useSyncExternalStore abaixo) e hooks de query sobre o TanStack Query; @getenginex/sdk-next traz ainda o client por request do servidor (getEnginexServer, com o tenant tirado dos headers) e o prefetch para o HydrationBoundary. Veja a trilha Frameworks. O resto desta seção vale para quem usa o core direto.
createEnginexClient nunca lança na criação, mesmo sem location, tenantHost ou baseUrl absoluto — a configuração só é resolvida (e memoizada) no primeiro request. Isso torna seguro importar um cliente singleton num módulo top-level que também roda durante o SSR: se ele nunca for usado no servidor, nada quebra; se for usado sem a configuração de servidor, o erro (EnginexError CONFIGURATION_ERROR) só aparece nesse primeiro request, sem chamar fetch.
No cliente (browser), um singleton em lib/enginex.ts, usado a partir de um componente 'use client':
// lib/enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'
export const enginex = createEnginexClient({
locale: 'pt-BR',
tokenStore: localStorageTokenStore(),
})// app/components/wallet.tsx
'use client'
import { useSyncExternalStore } from 'react'
import { enginex } from '@/lib/enginex'
// Stable snapshot for SSR: there is no localStorage on the server, so the real session is only
// known in the browser. Always using the same object here (instead of a literal `{ status: 'anonymous' }`
// on every call) avoids React's "getServerSnapshot should be cached" warning.
const ANON = { status: 'anonymous' } as const
export function Wallet() {
const session = useSyncExternalStore(enginex.session.subscribe, enginex.session.get, () => ANON)
return session.status === 'authenticated' ? <p>Authenticated</p> : null
}Repare que não dá para usar useState(() => enginex.session.get().status): com um tokenStore como localStorageTokenStore(), o servidor renderiza 'anonymous' (não há localStorage no SSR) e o useState inicializa o browser já com 'authenticated' para quem estava logado — a marcação da primeira renderização do cliente não bate com a do servidor, e o React descarta a hidratação (erro de "hydration mismatch"). useSyncExternalStore resolve isso: na primeira renderização do cliente ele também usa getServerSnapshot (o ANON acima), igual ao servidor, e só troca para a sessão real depois de hidratar.
No servidor (Server Components, Route Handlers), crie um cliente por request, com baseUrl e tenantHost explícitos — fora do browser não existe location para descobri-los:
// app/page.tsx (Server Component)
import { createEnginexClient } from '@getenginex/sdk'
export default async function Page() {
const enginex = createEnginexClient({
baseUrl: 'https://gateway.operador.com',
tenantHost: 'casino.operador.com',
})
const config = await enginex.config.get()
return <main>{config.currency.code}</main>
}Próximos passos
- Core: cadastro, login e 2FA, depósito PIX, saque com OTP, chaves PIX e verificação de identidade (KYC).
- iGaming: cassino e abrir jogo e bônus e promo codes.
- React e Next.js: provider e hooks, App Router e o guia Migrando um player Next.
- Referência: a API completa de todos os pacotes, gerada do código, em Referência.