This version (v0.7) has not been published to npm yet.
Skip to content

Getting started ​

Choose the product ​

The SDK is split by product. Every app installs the core (@getenginex/sdk); each of the operator's products comes in a separate package that uses the core client (the same session, tenant and configuration):

The app needsInstallTrack
sign-up, login and 2FA, password, profile, wallet, PIX deposit and withdrawal, PIX keys, KYC, responsible gaming, notifications@getenginex/sdkCore
everything above + casino (lobby, launch a game, history), bonuses (campaigns, promo codes), missions, loyalty and referrals@getenginex/sdk + @getenginex/sdk-igamingiGaming
bash
npm i @getenginex/sdk                           # core only
npm i @getenginex/sdk @getenginex/sdk-igaming   # core + casino, bonuses and engagement

The core is a peer dependency of the product packages: always install it alongside, once. Whoever does not use the casino does not install (or load) casino code. The steps below apply to any product; iGaming only adds step 6.

1. Create the client ​

Create one client per app in the browser and export it:

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

export const enginex = createEnginexClient({
  locale: 'pt-BR',
  tokenStore: localStorageTokenStore(),
  onSessionExpired: () => location.assign('/login'),
})

On the server (SSR, scripts, tests), create one client per request, passing the gateway URL and the operator's domain:

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

2. Read the operator configuration ​

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

3. Log in ​

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. React to the session ​

ts
enginex.session.subscribe((session) => {
  renderHeader(session.status === 'authenticated')
})

5. Language and disposal ​

Change the language at any time with setLocale — the next requests already go out with the new Accept-Language:

ts
enginex.setLocale('en-US')

A client per request (SSR, scripts, tests) does not need dispose() — it is already discarded along with the rest of the request. A short-lived client outside that case (e.g. a test that creates several clients), however, should call dispose() when done, to release the session subscription on the tokenStore (the storage listener, if it is the last one, in the case of localStorageTokenStore). After dispose(), every method rejects with EnginexError CONFIGURATION_ERROR:

ts
const enginex = createEnginexClient({ baseUrl, tenantHost })
try {
  await enginex.config.get()
} finally {
  enginex.dispose()
}

6. Products (iGaming) ​

With @getenginex/sdk-igaming installed, create the casino and bonus namespaces on top of the same client:

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 does not create a session or make a request: the login done with enginex.auth.login applies to the casino, and enginex.dispose() also shuts down iGaming. See the iGaming track.

Next.js / SSR ​

React and Next.js adapters

With React or Next.js, the adapters do what this section shows by hand: @getenginex/sdk-react brings EnginexProvider, useSession (the useSyncExternalStore below) and query hooks on top of TanStack Query; @getenginex/sdk-next also brings the server's per-request client (getEnginexServer, with the tenant taken from the headers) and the prefetch for HydrationBoundary. See the Frameworks track. The rest of this section applies to those who use the core directly.

createEnginexClient never throws on creation, even without location, tenantHost or an absolute baseUrl — the configuration is only resolved (and memoized) on the first request. This makes it safe to import a singleton client in a top-level module that also runs during SSR: if it is never used on the server, nothing breaks; if it is used without the server configuration, the error (EnginexError CONFIGURATION_ERROR) only shows up on that first request, without calling fetch.

On the client (browser), a singleton in lib/enginex.ts, used from a 'use client' component:

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
}

Note that you cannot use useState(() => enginex.session.get().status): with a tokenStore such as localStorageTokenStore(), the server renders 'anonymous' (there is no localStorage in SSR) and useState initializes the browser already as 'authenticated' for anyone who was logged in — the markup of the client's first render does not match the server's, and React discards the hydration (a "hydration mismatch" error). useSyncExternalStore solves this: on the client's first render it also uses getServerSnapshot (the ANON above), just like the server, and only switches to the real session after hydrating.

On the server (Server Components, Route Handlers), create one client per request, with explicit baseUrl and tenantHost — outside the browser there is no location to discover them:

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>
}

Next steps ​