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

Instalação ​

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

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

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

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

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

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

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

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

Vite (desenvolvimento):

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

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:

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

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

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

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

Enquanto 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.

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

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

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