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

Installation ​

bash
npm i @getenginex/sdk
# or
pnpm add @getenginex/sdk

Requirements: browsers with fetch and AbortController (the SDK depends on neither AbortSignal.any nor AbortSignal.timeout), Node 20+, Edge runtimes or Bun. The only dependency is zod (4.x).

zod: a single copy ​

zod is a regular dependency (not a peer) of the core and the product packages: the package manager installs one copy for all of them when the version ranges overlap. If the app also uses zod at a version outside that range (e.g. zod@3), two copies can end up in node_modules and in the bundle. The SDK keeps working (each schema is validated by the zod that created it), but the bundle gets heavier and a global app configuration (z.config(...), e.g. a message locale) applies only to the app's own copy. To have a single copy, install a single zod 4 at the top of the project:

bash
npm i zod@^4.6.5
npm ls zod # should list a single version

Product packages ​

@getenginex/sdk is the core (client, session, profile, wallet, PIX and realtime). The flows of each product come in separate packages, installed alongside the core, which is their peer dependency.

Choose the product ​

bash
# core only: session, profile, wallet, PIX and realtime
npm i @getenginex/sdk

# iGaming: casino, bonuses and sportsbook FIRST
npm i @getenginex/sdk @getenginex/sdk-igaming

# Predictions: markets, orders, portfolio and live orderbook
npm i @getenginex/sdk @getenginex/sdk-predictions

An operator that uses both products installs both product packages, with a single core. @getenginex/sdk-igaming (0.4.0) and @getenginex/sdk-predictions (0.2.0) accept core >=0.6.0 <1.0.0 (0.5.0 was the first with the @getenginex/sdk/query entry). See Core, iGaming and Predictions.

React and Next.js ​

For React or Next.js apps with TanStack Query, also install the adapter:

bash
# React (Vite etc.)
npm i @getenginex/sdk @getenginex/sdk-react @tanstack/react-query

# Next.js (App Router): sdk-next already brings sdk-react
npm i @getenginex/sdk @getenginex/sdk-next @tanstack/react-query

Vue uses @getenginex/sdk-vue (npm i @getenginex/sdk @getenginex/sdk-vue @tanstack/vue-query vue); Svelte and Solid use the factories from @getenginex/sdk/query with the framework's TanStack Query. See the Frameworks track.

Proxy to the gateway ​

By default the SDK calls /api/v1/... on the same origin as the page. Forward /api to the EngineX gateway on your server. See the reason in Tenant and domains.

Next.js (next.config.ts):

ts
export default {
  async rewrites() {
    return [{ source: '/api/:path*', destination: 'https://gateway.operador.com/api/:path*' }]
  },
}

Vite (development):

ts
export default {
  server: { proxy: { '/api': { target: 'https://gateway.operador.com', changeOrigin: true } } },
}

Nginx:

nginx
location /api/ {
  proxy_pass https://gateway.operador.com;
  proxy_set_header Host gateway.operador.com;
}

Local development ​

With the Vite proxy (or next dev), the page runs on localhost:5173 and the SDK sends that host as the operator identifier (X-Original-Host: localhost:5173), which does not belong to any operator. In development, provide the operator's domain with tenantHost:

ts
import { createEnginexClient } from '@getenginex/sdk'

export const enginex = createEnginexClient({
  tenantHost: import.meta.env.VITE_ENGINEX_TENANT, // e.g. casino.operador.com (dev only)
})
bash
# .env.development
VITE_ENGINEX_TENANT=casino.operador.com

In production do not set the variable (the value must stay undefined, not an empty string): without tenantHost the SDK uses the site's real domain (location.host). tenantHost applies to same-origin calls, that is, through the /api proxy. If something does not work, see Troubleshooting.

Examples ​

The SDK repository has three small apps in examples/, each a standalone project (outside the pnpm workspace) that installs the packages as a real app would:

ExampleWhat it shows
examples/vanilla-vite@getenginex/sdk with Vite and plain TypeScript: a client with createMockFetch, the operator configuration and a mocked login, no framework
examples/vue-vite@getenginex/sdk-vue with Vue 3: login, balance with useEnginexQuery, PIX deposit with useEnginexMutation and the balance updated by useRealtimeSync, all in mock mode (createMockFetch and createMockRealtime)
examples/next@getenginex/sdk-next with the App Router: getEnginexServer and prefetchEnginex in the layout, hydration, login, balance, PIX deposit, realtime and the withEnginex rewrite; runs against a gateway or in mock mode

From a checkout of the repository, each one runs like any npm project:

bash
cd examples/vue-vite
npm install
npm run dev

Until the packages are published on npm, npm install inside an example does not resolve them. To check them before that, use the consumer tests: they pack the repository's packages, install the local tarballs in each example and build it (type check and production build; examples/next runs next build). They do not start a dev server: to click through an example, run it with npm run dev once the packages are on npm.

bash
pnpm install && pnpm build
pnpm test:consumers                          # every consumer, the three examples included
ENGINEX_CONSUMERS=next pnpm test:consumers   # only one: vanilla-vite, vue-vite or next

examples/next has two modes: with NEXT_PUBLIC_ENGINEX_MOCK=1 the browser client uses the mocks (log in with ana@exemplo.com / Senha@123); with ENGINEX_GATEWAY_URL, the server reads the gateway and the tenant is the request's host:

bash
# examples/next, mock mode (no gateway)
NEXT_PUBLIC_ENGINEX_MOCK=1 npm run dev

# examples/next, with a gateway
ENGINEX_GATEWAY_URL=https://gateway.operador.com npm run build
ENGINEX_GATEWAY_URL=https://gateway.operador.com npm start