Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

Instalación ​

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

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

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

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

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

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

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

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

Vite (desarrollo):

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

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:

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

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

EjemploQué 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:

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

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

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

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