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

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 deInstaleTrilha
cadastro, login e 2FA, senha, perfil, carteira, depósito e saque PIX, chaves PIX, KYC, jogo responsável, notificações@getenginex/sdkCore
tudo acima + cassino (lobby, abrir jogo, histórico), bônus (campanhas, promo codes), missões, fidelidade e indicações@getenginex/sdk + @getenginex/sdk-igamingiGaming
bash
npm i @getenginex/sdk                           # core only
npm i @getenginex/sdk @getenginex/sdk-igaming   # core + casino, bonuses and engagement

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

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

ts
const enginex = createEnginexClient({
  baseUrl: 'https://gateway.operador.com',
  tenantHost: 'casino.operador.com',
})

2. Leia a configuração do operador ​

ts
const config = await enginex.config.get()
console.log(config.currency.code, config.paymentMethods.map((m) => m.code))

3. Faça login ​

ts
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 ​

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

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

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

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

tsx
// lib/enginex.ts
import { createEnginexClient, localStorageTokenStore } from '@getenginex/sdk'

export const enginex = createEnginexClient({
  locale: 'pt-BR',
  tokenStore: localStorageTokenStore(),
})
tsx
// 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:

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