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:
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:
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:
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:
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)yonResponse(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 conauth: 'none'o'current'(p. ej.,logout) nunca tienen un segundoattempt.onError(error, ctx)se dispara una sola vez por llamada pública que falle — nunca por intento — con elEnginexErrorfinal: el mismo error con el que rechaza laPromisedel método. EnonError,ctx.attemptpuede venir0cuando la llamada falló antes de cualquier intento de red (p. ej.,CONFIGURATION_ERRORen la resolución debaseUrl/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 paraonRequest,onResponseyonError— 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_REQUIREDenlogin, 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 disparaonError. ctxnunca 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 enonResponsetambiénstatus,durationMsyrequestId(elX-Request-IDde la respuesta, cuando exista).urlypathnunca traen la query string.- En requests multipart (p. ej.,
kyc.uploadDocument),ctx.bodytrae 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 enctx. - 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 paraonSessionChange/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.
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,validationydispose()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 porcreateEnginexClient(incluida una copia{ ...client }) lanzaCONFIGURATION_ERROR.request(spec)yrequestPage(spec)reciben un spec conmethod,path,query,body,auth('none','optional'o'required'),idempotent,schema/item,page/perPage/perPageParam,validation: 'strict'yoptions(lasCallOptionsrecibidas por el método público, pasadas tal cual).idempotent: trueenvía unaIdempotency-Keygenerada por llamada y reutilizada en el retry tras un 401 renovado. Unauth,validationoperPageParamfuera de esos valores rechaza conCONFIGURATION_ERRORantes de cualquierfetch; un segmento depathque sea.o..(p. ej., un id que viene de la app) rechaza conINVALID_ARGUMENT(status: 0), también antes delfetch, porque la URL lo normalizaría hacia otra ruta.- Identifica los errores con
isEnginexError(error, code), no coninstanceof 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 enEnginexError, llama aonErroruna sola vez y devuelve el error para lanzarlo.wire,mapOfylazyson los mismos helpers de schema del core (formato de red ensnake_case, salida encamelCase, 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.
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 HTTPprefixes el nombre del tópico en el gateway, sin el:final. Conprivate: falsela fábrica exige el id; conprivate: trueno recibe ninguno, ysubscribelanzaUNAUTHENTICATEDsin sesión.messageTypees 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 (
strictlo descarta,warnlo recupera campo por campo y avisa poronValidationIssue) y llega al handler encamelCase. Envuelve el schema enlazypara que solo se construya en la primera suscripción. snapshots: 'ignore'omite lossnapshotdel modo secuenciado cuando tienen otro formato (como encoreTopics.balance()).- Una definición inválida (prefijo vacío, prefijo fuera del formato del gateway,
messageTypevacío, un schema que no es de Zod) o un id inválido lanzaCONFIGURATION_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:
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)
}
}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) oundefinedpara 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 confingerprint), o abre uno nuevo;settle(input, error?)solo lo mantiene después de una falla para la queisAmbiguousFailure(error)estrue.runMutation(call, attempts, input)envía la clave (o laidempotencyKeyfija de la fábrica), cierra el intento con el resultado y siempre rechaza con unEnginexError.
La regla del lado de la app está en Idempotencia; los adapters de React y Vue ya lo hacen (consulta Idempotencia en mutations).