Instalación
npm i @getenginex/sdk
# or
pnpm add @getenginex/sdkRequisitos: browsers con fetch y AbortController (el SDK no depende de AbortSignal.any ni de AbortSignal.timeout), Node 20+, Edge runtimes o Bun. La única dependencia es zod (4.x).
zod: una sola copia
zod es una dependencia común (no peer) del core y de los paquetes de producto: el gestor de paquetes instala una copia para todos cuando los rangos de versión se cruzan. Si la app también usa zod en una versión fuera de ese rango (p. ej., zod@3), pueden quedar dos copias en node_modules y en el bundle. El SDK sigue funcionando (cada schema lo valida el zod que lo creó), pero el bundle pesa más y una configuración global de la app (z.config(...), p. ej., un locale de mensajes) afecta solo a su propia copia. Para tener una sola copia, instala un único zod 4 en la raíz del proyecto:
npm i zod@^4.6.5
npm ls zod # should list a single versionPaquetes de producto
@getenginex/sdk es el core (cliente, sesión, perfil, billetera, PIX y realtime). Los flujos de cada producto vienen en paquetes aparte, que se instalan junto con el core, que es peer dependency de ellos.
Elige el producto
# 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-predictionsUn operador que usa los dos productos instala los dos paquetes de producto, con un único core. @getenginex/sdk-igaming (0.4.0) y @getenginex/sdk-predictions (0.2.0) aceptan el core >=0.6.0 <1.0.0 (la 0.5.0 fue la primera con el entry @getenginex/sdk/query). Consulta Core, iGaming y Predictions.
React y Next.js
Para apps React o Next.js con TanStack Query, instala también el 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 @getenginex/sdk-vue (npm i @getenginex/sdk @getenginex/sdk-vue @tanstack/vue-query vue); Svelte y Solid usan las fábricas de @getenginex/sdk/query con el TanStack Query del framework. Consulta la sección Frameworks.
Proxy hacia el gateway
Por defecto el SDK llama a /api/v1/... en el mismo origen que la página. Reenvía /api al gateway de EngineX en tu servidor. Consulta el motivo en Tenant y dominios.
Next.js (next.config.ts):
export default {
async rewrites() {
return [{ source: '/api/:path*', destination: 'https://gateway.operador.com/api/:path*' }]
},
}Vite (desarrollo):
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;
}Desarrollo local
Con el proxy de Vite (o next dev), la página corre en localhost:5173 y el SDK envía ese host como identificación del operador (X-Original-Host: localhost:5173), que no pertenece a ningún operador. En desarrollo indica el dominio del operador con 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.comEn producción no definas la variable (el valor debe quedar undefined, no una cadena vacía): sin tenantHost el SDK usa el dominio real del sitio (location.host). tenantHost aplica a llamadas same-origin, es decir, a través del proxy /api. Si algo no funciona, consulta Troubleshooting.
Ejemplos
El repositorio del SDK tiene tres apps pequeñas en examples/, cada una un proyecto independiente (fuera del workspace de pnpm) que instala los paquetes como lo haría una app real:
| Ejemplo | Qué muestra |
|---|---|
examples/vanilla-vite | @getenginex/sdk con Vite y TypeScript puro: un cliente con createMockFetch, la configuración del operador y un inicio de sesión mockeado, sin framework |
examples/vue-vite | @getenginex/sdk-vue con Vue 3: inicio de sesión, saldo con useEnginexQuery, depósito PIX con useEnginexMutation y el saldo actualizado por useRealtimeSync, todo en modo mock (createMockFetch y createMockRealtime) |
examples/next | @getenginex/sdk-next con el App Router: getEnginexServer y prefetchEnginex en el layout, hidratación, inicio de sesión, saldo, depósito PIX, realtime y el rewrite de withEnginex; corre con un gateway o en modo mock |
Desde un checkout del repositorio, cada uno se ejecuta como cualquier proyecto npm:
cd examples/vue-vite
npm install
npm run devMientras los paquetes no estén publicados en npm, npm install dentro de un ejemplo no los encuentra. Para verificarlos antes, usa las pruebas de consumidor: empaquetan los paquetes del repositorio, instalan los tarballs locales en cada ejemplo y hacen su build (verificación de tipos y build de producción; examples/next ejecuta next build). No levantan un servidor de desarrollo: para recorrer un ejemplo, ejecútalo con npm run dev cuando los paquetes estén en 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 nextexamples/next tiene dos modos: con NEXT_PUBLIC_ENGINEX_MOCK=1 el cliente del navegador usa los mocks (inicio de sesión con ana@exemplo.com / Senha@123); con ENGINEX_GATEWAY_URL, el servidor lee el gateway y el tenant es el host del 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