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

Extensibilidad ​

Dos puntos de extensión para integrar el SDK con el runtime de tu app: fetchOptions por llamada y hooks en el cliente. Para quien escribe paquetes de producto del SDK, existe además el contrato de extensión.

fetchOptions: opciones de fetch por llamada ​

Todo método acepta options.fetchOptions, mezcladas en el fetch de todos los intentos del request (el inicial y el retry tras un 401 renovado). Úsalo para recursos específicos del runtime, como la caché de datos de Next.js:

ts
const config = await enginex.config.get(undefined, {
  fetchOptions: { next: { revalidate: 60, tags: ['config'] } },
})

También puedes ajustar cache, credentials y otras opciones estándar de RequestInit:

ts
await enginex.config.getBranding(undefined, { fetchOptions: { cache: 'no-store' } })

method, body y signal son siempre los del SDK: aunque se indiquen en fetchOptions, se ignoran — usa options.signal para cancelar. En headers, los nombres que el SDK controla (authorization, x-original-host, idempotency-key, content-type, accept, accept-language) siempre se eliminan y se reemplazan por los del SDK — incluso cuando este request en particular no define alguno de ellos (p. ej., un Authorization no sobrevive a un retry sin token, en el modo optional) — comparando nombres sin distinguir mayúsculas de minúsculas, y valiendo para las tres formas de HeadersInit (objeto, Headers, arreglo de pares). Cualquier otro header extra pasa normalmente:

ts
await enginex.config.get(undefined, {
  fetchOptions: { headers: { 'x-my-trace-id': traceId } }, // reaches the gateway
})

hooks: observabilidad del cliente ​

createEnginexClient({ hooks }) llama a onRequest/onResponse en cada intento y a onError una vez por llamada que falle, para logging, métricas o tracing:

ts
const enginex = createEnginexClient({
  hooks: {
    onRequest(ctx) {
      span.addEvent('request', ctx)
    },
    onResponse(ctx) {
      metrics.timing('enginex.request', ctx.durationMs, { status: String(ctx.status) })
    },
    onError(error, ctx) {
      logger.warn('enginex request failed', { code: error.code, ...ctx })
    },
  },
})
  • onRequest(ctx) y onResponse(ctx) se disparan en cada intento: el inicial (attempt: 1) y, si el gateway responde 401 y la sesión se renueva, el retry (attempt: 2). Los requests con auth: 'none' o 'current' (p. ej., logout) nunca tienen un segundo attempt.
  • onError(error, ctx) se dispara una sola vez por llamada pública que falle — nunca por intento — con el EnginexError final: el mismo error con el que rechaza la Promise del método. En onError, ctx.attempt puede venir 0 cuando la llamada falló antes de cualquier intento de red (p. ej., CONFIGURATION_ERROR en la resolución de baseUrl/tenantHost/fetch).
  • Los requests internos del SDK nunca disparan ningún hook: la renovación de sesión (POST /auth/refresh, disparada por un 401) es completamente invisible para onRequest, onResponse y onError — solo se reporta el request público que originó el 401. Del mismo modo, un error que forma parte del flujo normal de un método (p. ej., 2FA_REQUIRED en login, que pasa a ser el retorno { status: '2fa_required' }) o que el método se traga por contrato (p. ej., logout, que nunca rechaza) no dispara onError.
  • ctx nunca incluye headers, tokens, cuerpo ni la query string (que podría llevar secretos, p. ej., el token de un enlace de restablecimiento de contraseña): solo { method, path, url, attempt }, y en onResponse también status, durationMs y requestId (el X-Request-ID de la respuesta, cuando exista). url y path nunca traen la query string.
  • En requests multipart (p. ej., kyc.uploadDocument), ctx.body trae solo un resumen: { kind: 'form-data', fields: [{ name, type?, size? }] } — el nombre de cada campo (p. ej., file) y, para archivos, tipo y tamaño. Nunca el nombre original ni el contenido del archivo, ni el valor de los campos de texto. Los cuerpos JSON nunca aparecen en ctx.
  • Todo hook se llama vía safeCall: un hook que lanza no afecta al request ni a los otros hooks — el mismo aislamiento de Sesión y tokens para onSessionChange/onSessionExpired/onValidationIssue.

Paquetes de producto ​

Los paquetes de producto (@getenginex/sdk-igaming, @getenginex/sdk-predictions) se montan sobre el cliente del core mediante el entry @getenginex/sdk/extension. Es una API pública estable (versionada y con snapshot en el CI), pero destinada a paquetes del SDK, no a apps: una app solo crea el cliente y se lo pasa al paquete del producto.

ts
import type { CallOptions, EnginexClient } from '@getenginex/sdk'
import { getExtensionTransport, lazy, wire } from '@getenginex/sdk/extension'
import { z } from 'zod/mini'

const gameSchema = /* @__PURE__ */ lazy(() => wire({ game_id: z.string(), name: z.string() }))

export function createIgaming(client: EnginexClient) {
  const transport = getExtensionTransport(client)
  return {
    casino: {
      getGame: ({ gameId }: { gameId: string }, options?: CallOptions) =>
        transport.request({
          method: 'GET',
          path: `/casino/games/${encodeURIComponent(gameId)}`,
          auth: 'optional',
          schema: gameSchema(),
          options,
        }),
    },
  }
}
  • getExtensionTransport(client) devuelve el transporte del propio cliente: sesión, renovación de tokens tras un 401, tenant, locale, timeout, hooks, validation y dispose() son siempre los del cliente de la app — un paquete de producto nunca crea sesión, tenant ni transporte propios. El transporte no queda expuesto en el objeto del cliente; un valor que no sea un cliente creado por createEnginexClient (incluida una copia { ...client }) lanza CONFIGURATION_ERROR.
  • request(spec) y requestPage(spec) reciben un spec con method, path, query, body, auth ('none', 'optional' o 'required'), idempotent, schema/item, page/perPage/perPageParam, validation: 'strict' y options (las CallOptions recibidas por el método público, pasadas tal cual). idempotent: true envía una Idempotency-Key generada por llamada y reutilizada en el retry tras un 401 renovado. Un auth, validation o perPageParam fuera de esos valores rechaza con CONFIGURATION_ERROR antes de cualquier fetch; un segmento de path que sea . o .. (p. ej., un id que viene de la app) rechaza con INVALID_ARGUMENT (status: 0), también antes del fetch, porque la URL lo normalizaría hacia otra ruta.
  • Identifica los errores con isEnginexError(error, code), no con instanceof EnginexError: en CommonJS, el entry principal y el de extensión son archivos separados, cada uno con su copia de la clase.
  • reportError(error, ctx) es para fallas que el paquete detecta después de una respuesta exitosa: normaliza en EnginexError, llama a onError una sola vez y devuelve el error para lanzarlo.
  • wire, mapOf y lazy son los mismos helpers de schema del core (formato de red en snake_case, salida en camelCase, schemas construidos solo en el primer uso para no pesar en el bundle de quien no los usa).

Tópico realtime propio ​

Un paquete de producto que publica sus propios tópicos los define con defineTopic y valida el payload con wire (el mismo helper de schema de las respuestas HTTP). El tópico de abajo es ilustrativo: el gateway tiene que publicarlo para que lleguen los mensajes.

ts
import { defineTopic, lazy, wire } from '@getenginex/sdk/extension'
import { createRealtime } from '@getenginex/sdk/realtime'
import { z } from 'zod/mini'

// The wire payload is snake_case; the handler receives camelCase ({ tournamentId, rank, points }).
const leaderboardSchema = /* @__PURE__ */ lazy(() =>
  wire({ tournament_id: z.string(), rank: z.number(), points: z.number() }),
)

// Public topic: the factory takes the id and builds `tournament:<id>`.
export const tournamentLeaderboard = defineTopic({
  prefix: 'tournament',
  private: false,
  messageType: 'leaderboard_update',
  schema: leaderboardSchema,
})

// Private topic: no id; realtime uses the session's `sub` (`tournament-rewards:<sub>`).
export const myTournamentRewards = defineTopic({
  prefix: 'tournament-rewards',
  private: true,
  messageType: 'reward_granted',
  schema: lazy(() => wire({ tournament_id: z.string(), amount: z.number() })),
})

const realtime = createRealtime(enginex)
const off = realtime.subscribe(tournamentLeaderboard('t-1'), (update, meta) => {
  console.log(update.tournamentId, update.rank, update.points, meta.kind)
})
realtime.onResync(tournamentLeaderboard('t-1'), () => reloadLeaderboard()) // reload the baseline over HTTP
  • prefix es el nombre del tópico en el gateway, sin el : final. Con private: false la fábrica exige el id; con private: true no recibe ninguno, y subscribe lanza UNAUTHENTICATED sin sesión.
  • messageType es el tipo de los mensajes de datos del tópico en la red; los demás se ignoran.
  • El mensaje se valida en el modo del cliente (strict lo descarta, warn lo recupera campo por campo y avisa por onValidationIssue) y llega al handler en camelCase. Envuelve el schema en lazy para que solo se construya en la primera suscripción.
  • snapshots: 'ignore' omite los snapshot del modo secuenciado cuando tienen otro formato (como en coreTopics.balance()).
  • Una definición inválida (prefijo vacío, prefijo fuera del formato del gateway, messageType vacío, un schema que no es de Zod) o un id inválido lanza CONFIGURATION_ERROR.

Exporta las fábricas en una entrada propia (como hace @getenginex/sdk-predictions/realtime), para que una app que no usa realtime no cargue los schemas. La conexión, la reconexión y onResync son los del core: consulta Realtime.

Mutation propia ​

Cada objeto de opciones que devuelve una fábrica de mutation (m.deposits.createPix(), o uno construido con queryScope) lleva su propio intento de idempotencia: después de una falla ambigua (NETWORK_ERROR, TIMEOUT, 5xx, KEY_IN_USE, VALIDATION_ERROR después de un 2xx), una nueva llamada con la misma entrada reutiliza la Idempotency-Key. Un adapter que recrea las opciones en cada render debe guardar el intento en un lugar que viva más, como hace useEnginexMutation por instancia del hook. @getenginex/sdk/extension incluye las piezas:

ts
import { createAttempts, mutationCallOf, runMutation, type Attempts } from '@getenginex/sdk/extension'
import type { EnginexMutationOptions } from '@getenginex/sdk/query'

/** One attempt per component instance, created once (not on every render). */
export function createMutationRunner() {
  const shared = createAttempts()
  return function mutationFnOf<I, R>(options: EnginexMutationOptions<I, R>): (input: I) => Promise<R> {
    // Read the call from the original options: a `{ ...options }` copy does not carry it.
    const call = mutationCallOf<I, R>(options)
    if (call === undefined) return options.mutationFn // not an SDK mutation: keep its own mutationFn
    // The method is part of the fingerprint: switching from deposit to withdrawal never reuses a key.
    const method = options.mutationKey
    const attempts: Attempts = {
      keyFor: (input) => shared.keyFor({ method, input }),
      settle: (input, error) => shared.settle({ method, input }, error),
    }
    return (input) => runMutation(call, attempts, input)
  }
}
ts
import { createMutations } from '@getenginex/sdk/query'

const mutationFnOf = createMutationRunner() // when the component is created
const m = createMutations(enginex)

// On every render: new options, the same attempt.
const createPix = m.deposits.createPix()
const input = { amount: 5000 }
const deposit = await mutationFnOf(createPix)(input) // a retry after NETWORK_ERROR reuses the key
for (const queryKey of createPix.invalidates(input, deposit)) {
  await queryClient.invalidateQueries({ queryKey })
}
  • mutationCallOf(options) devuelve la llamada del SDK (call, idempotent, fixedKey) o undefined para una mutation que no vino de una fábrica. Es una propiedad no enumerable: léela de las opciones originales, nunca de una copia.
  • createAttempts() guarda como máximo un intento abierto. keyFor(input) devuelve su clave cuando la entrada tiene el mismo contenido (comparado con fingerprint), o abre uno nuevo; settle(input, error?) solo lo mantiene después de una falla para la que isAmbiguousFailure(error) es true.
  • runMutation(call, attempts, input) envía la clave (o la idempotencyKey fija de la fábrica), cierra el intento con el resultado y siempre rechaza con un EnginexError.

La regla del lado de la app está en Idempotencia; los adapters de React y Vue ya lo hacen (consulta Idempotencia en mutations).