Instalação
npm i @getenginex/sdk
# or
pnpm add @getenginex/sdkRequisitos: browsers com fetch e AbortController (o SDK não depende de AbortSignal.any nem de AbortSignal.timeout), Node 20+, Edge runtimes ou Bun. A única dependência é zod (4.x).
zod: uma cópia só
O zod é dependência comum (não peer) do core e dos pacotes de produto: o gerenciador de pacotes instala uma cópia para todos quando as faixas de versão se cruzam. Se o app também usa zod numa versão fora dessa faixa (ex.: zod@3), podem ficar duas cópias no node_modules e no bundle. O SDK continua funcionando (cada schema é validado pelo zod que o criou), mas o bundle pesa mais e uma configuração global do app (z.config(...), ex.: um locale de mensagens) vale só para a cópia dele. Para ter uma cópia só, instale um único zod 4 no topo do projeto:
npm i zod@^4.6.5
npm ls zod # should list a single versionPacotes de produto
O @getenginex/sdk é o core (cliente, sessão, perfil, carteira, PIX e realtime). Os fluxos de cada produto vêm em pacotes à parte, instalados junto com o core, que é peer dependency deles.
Escolha o produto
# 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-predictionsUm operador que usa os dois produtos instala os dois pacotes de produto, com um único core. O @getenginex/sdk-igaming (0.4.0) e o @getenginex/sdk-predictions (0.2.0) aceitam o core >=0.6.0 <1.0.0 (a 0.5.0 foi a primeira com o entry @getenginex/sdk/query). Veja Core, iGaming e Predictions.
React e Next.js
Para apps React ou Next.js com TanStack Query, instale também o adapter:
# 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-queryVue usa o @getenginex/sdk-vue (npm i @getenginex/sdk @getenginex/sdk-vue @tanstack/vue-query vue); Svelte e Solid usam as fábricas de @getenginex/sdk/query com o TanStack Query do framework. Veja a trilha Frameworks.
Proxy para o gateway
Por padrão o SDK chama /api/v1/... na mesma origem da página. Encaminhe /api para o gateway do EngineX no seu servidor. Veja o motivo em Tenant e domínios.
Next.js (next.config.ts):
export default {
async rewrites() {
return [{ source: '/api/:path*', destination: 'https://gateway.operador.com/api/:path*' }]
},
}Vite (desenvolvimento):
export default {
server: { proxy: { '/api': { target: 'https://gateway.operador.com', changeOrigin: true } } },
}Nginx:
location /api/ {
proxy_pass https://gateway.operador.com;
proxy_set_header Host gateway.operador.com;
}Desenvolvimento local
Com o proxy do Vite (ou next dev), a página roda em localhost:5173 e o SDK envia esse host como identificação do operador (X-Original-Host: localhost:5173), que não pertence a nenhum operador. Em desenvolvimento informe o domínio do operador com tenantHost:
import { createEnginexClient } from '@getenginex/sdk'
export const enginex = createEnginexClient({
tenantHost: import.meta.env.VITE_ENGINEX_TENANT, // e.g. casino.operador.com (dev only)
})# .env.development
VITE_ENGINEX_TENANT=casino.operador.comEm produção não defina a variável (o valor tem de ficar undefined, não string vazia): sem tenantHost o SDK usa o domínio real do site (location.host). O tenantHost vale para chamadas same-origin, isto é, através do proxy /api. Se algo não funcionar, veja Troubleshooting.
Exemplos
O repositório do SDK tem três apps pequenos em examples/, cada um um projeto independente (fora do workspace pnpm) que instala os pacotes como um app de verdade:
| Exemplo | O que mostra |
|---|---|
examples/vanilla-vite | @getenginex/sdk com Vite e TypeScript puro: um cliente com createMockFetch, a configuração do operador e um login mockado, sem framework |
examples/vue-vite | @getenginex/sdk-vue com Vue 3: login, saldo com useEnginexQuery, depósito PIX com useEnginexMutation e o saldo atualizado pelo useRealtimeSync, tudo em modo mock (createMockFetch e createMockRealtime) |
examples/next | @getenginex/sdk-next com o App Router: getEnginexServer e prefetchEnginex no layout, hidratação, login, saldo, depósito PIX, realtime e o rewrite do withEnginex; roda com um gateway ou em modo mock |
A partir de um checkout do repositório, cada um roda como qualquer projeto npm:
cd examples/vue-vite
npm install
npm run devEnquanto os pacotes não estiverem publicados no npm, o npm install dentro de um exemplo não os encontra. Para conferi-los antes disso, use os testes de consumidor: eles empacotam os pacotes do repositório, instalam os tarballs locais em cada exemplo e fazem o build dele (checagem de tipos e build de produção; o examples/next roda next build). Eles não sobem um servidor de desenvolvimento: para navegar por um exemplo, rode-o com npm run dev quando os pacotes estiverem no npm.
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 nextO examples/next tem dois modos: com NEXT_PUBLIC_ENGINEX_MOCK=1 o cliente do navegador usa os mocks (login com ana@exemplo.com / Senha@123); com ENGINEX_GATEWAY_URL, o servidor lê o gateway e o tenant é o host do request:
# 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