Extensibilidade
Dois pontos de extensão para integrar o SDK com o runtime do seu app: fetchOptions por chamada e hooks no cliente. Para quem escreve pacotes de produto do SDK, há ainda o contrato de extensão.
fetchOptions: opções de fetch por chamada
Todo método aceita options.fetchOptions, mescladas no fetch de todas as tentativas do request (a inicial e o retry após um 401 renovado). Use para recursos específicos do runtime, como o cache de dados do Next.js:
const config = await enginex.config.get(undefined, {
fetchOptions: { next: { revalidate: 60, tags: ['config'] } },
})Também dá para ajustar cache, credentials e outras opções padrão de RequestInit:
await enginex.config.getBranding(undefined, { fetchOptions: { cache: 'no-store' } })method, body e signal são sempre os do SDK: mesmo se informados em fetchOptions, são ignorados — use options.signal para cancelamento. Em headers, os nomes que o SDK controla (authorization, x-original-host, idempotency-key, content-type, accept, accept-language) são sempre removidos e substituídos pelos do SDK — mesmo quando este request em particular não define um deles (ex.: um Authorization não sobrevive a um retry sem token, no modo optional) — comparando nomes sem diferenciar maiúsculas de minúsculas, e valendo para as três formas de HeadersInit (objeto, Headers, array de pares). Qualquer outro header extra passa normalmente:
await enginex.config.get(undefined, {
fetchOptions: { headers: { 'x-my-trace-id': traceId } }, // reaches the gateway
})hooks: observabilidade do cliente
createEnginexClient({ hooks }) chama onRequest/onResponse a cada tentativa e onError uma vez por chamada que falhar, para logging, métricas ou 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)eonResponse(ctx)disparam em cada tentativa: a inicial (attempt: 1) e, se o gateway responder 401 e a sessão for renovada, o retry (attempt: 2). Requests comauth: 'none'ou'current'(ex.:logout) nunca têm um segundoattempt.onError(error, ctx)dispara uma única vez por chamada pública que falhar — nunca por tentativa — com oEnginexErrorfinal: o mesmo erro que aPromisedo método rejeita. EmonError,ctx.attemptpode vir0quando a chamada falhou antes de qualquer tentativa de rede (ex.:CONFIGURATION_ERRORna resolução debaseUrl/tenantHost/fetch).- Requests internos do SDK nunca disparam nenhum hook: a renovação de sessão (
POST /auth/refresh, disparada por um 401) é completamente invisível aonRequest,onResponseeonError— só o request público que originou o 401 é reportado. Da mesma forma, um erro que faz parte do fluxo normal de um método (ex.:2FA_REQUIREDnologin, que vira o retorno{ status: '2fa_required' }) ou que o método engole por contrato (ex.:logout, que nunca rejeita) não disparaonError. ctxnunca inclui headers, tokens, corpo nem a query string (que poderia carregar segredos, ex.: o token de um link de reset de senha): só{ method, path, url, attempt }, e emonResponsetambémstatus,durationMserequestId(oX-Request-IDda resposta, quando houver).urlepathnunca trazem a query string.- Em requests multipart (ex.:
kyc.uploadDocument),ctx.bodytraz só um resumo:{ kind: 'form-data', fields: [{ name, type?, size? }] }— o nome de cada campo (ex.:file) e, para arquivos, tipo e tamanho. Nunca o nome original nem o conteúdo do arquivo, nem o valor dos campos de texto. Corpos JSON nunca aparecem noctx. - Todo hook é chamado via
safeCall: um hook que lança não afeta o request nem os outros hooks — o mesmo isolamento de Sessão e tokens paraonSessionChange/onSessionExpired/onValidationIssue.
Pacotes de produto
Os pacotes de produto (@getenginex/sdk-igaming, @getenginex/sdk-predictions) se montam sobre o cliente do core pelo entry @getenginex/sdk/extension. É API pública estável (versionada e com snapshot no CI), mas destinada a pacotes do SDK, não a apps: um app só cria o cliente e o passa ao pacote do produto.
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)devolve o transporte do próprio cliente: sessão, renovação de tokens após 401, tenant, locale, timeout,hooks,validationedispose()são sempre os do cliente do app — um pacote de produto nunca cria sessão, tenant nem transporte próprios. O transporte não fica exposto no objeto do cliente; um valor que não seja um cliente criado porcreateEnginexClient(inclusive uma cópia{ ...client }) lançaCONFIGURATION_ERROR.request(spec)erequestPage(spec)recebem um spec commethod,path,query,body,auth('none','optional'ou'required'),idempotent,schema/item,page/perPage/perPageParam,validation: 'strict'eoptions(asCallOptionsrecebidas pelo método público, repassadas como estão).idempotent: trueenvia umaIdempotency-Keygerada por chamada e reusada no retry após um 401 renovado. Umauth,validationouperPageParamfora desses valores rejeita comCONFIGURATION_ERRORantes de qualquerfetch; um segmento depathque seja.ou..(ex.: um id vindo do app) rejeita comINVALID_ARGUMENT(status: 0), também antes dofetch, porque a URL o normalizaria para outra rota.- Identifique erros com
isEnginexError(error, code), não cominstanceof EnginexError: no CommonJS, o entry principal e o de extensão são arquivos separados, cada um com a sua cópia da classe. reportError(error, ctx)é para falhas que o pacote detecta depois de uma resposta bem-sucedida: normaliza emEnginexError, chamaonErroruma única vez e devolve o erro para lançar.wire,mapOfelazysão os mesmos helpers de schema do core (fio emsnake_case, saída emcamelCase, schemas construídos só no primeiro uso para não pesar no bundle de quem não os usa).
Tópico realtime próprio
Um pacote de produto que publica tópicos próprios os define com defineTopic e valida o payload com wire (o mesmo helper de schema das respostas HTTP). O tópico abaixo é ilustrativo: o gateway precisa publicá-lo para que as mensagens cheguem.
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 HTTPprefixé o nome do tópico no gateway, sem o:final. Comprivate: falsea fábrica exige o id; comprivate: trueela não recebe nenhum, e osubscribelançaUNAUTHENTICATEDsem sessão.messageTypeé o tipo das mensagens de dados do tópico no fio; as outras são ignoradas.- A mensagem é validada no modo do cliente (
stricta descarta,warna recupera campo a campo e avisa poronValidationIssue) e chega ao handler emcamelCase. Envolva o schema emlazypara que ele só seja montado na primeira assinatura. snapshots: 'ignore'pula ossnapshots do modo sequenciado quando eles têm outro formato (como emcoreTopics.balance()).- Uma definição inválida (prefixo vazio, prefixo fora do formato do gateway,
messageTypevazio, schema que não é do Zod) ou um id inválido lançaCONFIGURATION_ERROR.
Exporte as fábricas numa entrada própria (como faz @getenginex/sdk-predictions/realtime), para que um app que não usa realtime não carregue os schemas. A conexão, a reconexão e o onResync são os do core: veja Realtime.
Mutation própria
Cada objeto de opções que uma fábrica de mutation devolve (m.deposits.createPix(), ou um montado com queryScope) carrega a própria tentativa de idempotência: depois de uma falha ambígua (NETWORK_ERROR, TIMEOUT, 5xx, KEY_IN_USE, VALIDATION_ERROR depois de 2xx), uma nova chamada com a mesma entrada reaproveita a Idempotency-Key. Um adapter que recria as opções a cada render precisa guardar a tentativa num lugar que viva mais, como o useEnginexMutation faz por instância do hook. @getenginex/sdk/extension traz as peças:
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)devolve a chamada do SDK (call,idempotent,fixedKey) ouundefinedpara uma mutation que não veio de uma fábrica. É uma propriedade não enumerável: leia-a das opções originais, nunca de uma cópia.createAttempts()guarda no máximo uma tentativa aberta.keyFor(input)devolve a chave dela quando a entrada tem o mesmo conteúdo (comparado comfingerprint), ou abre uma nova;settle(input, error?)só a mantém depois de uma falha para a qualisAmbiguousFailure(error)étrue.runMutation(call, attempts, input)envia a chave (ou aidempotencyKeyfixa da fábrica), fecha a tentativa com o resultado e sempre rejeita com umEnginexError.
A regra do lado do app está em Idempotência; os adapters de React e Vue já fazem isso (veja Idempotência em mutations).