Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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:

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

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

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

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) e onResponse(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 com auth: 'none' ou 'current' (ex.: logout) nunca têm um segundo attempt.
  • onError(error, ctx) dispara uma única vez por chamada pública que falhar — nunca por tentativa — com o EnginexError final: o mesmo erro que a Promise do método rejeita. Em onError, ctx.attempt pode vir 0 quando a chamada falhou antes de qualquer tentativa de rede (ex.: CONFIGURATION_ERROR na resolução de baseUrl/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 a onRequest, onResponse e onError — 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_REQUIRED no login, que vira o retorno { status: '2fa_required' }) ou que o método engole por contrato (ex.: logout, que nunca rejeita) não dispara onError.
  • ctx nunca 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 em onResponse também status, durationMs e requestId (o X-Request-ID da resposta, quando houver). url e path nunca trazem a query string.
  • Em requests multipart (ex.: kyc.uploadDocument), ctx.body traz 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 no ctx.
  • 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 para onSessionChange/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.

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) devolve o transporte do próprio cliente: sessão, renovação de tokens após 401, tenant, locale, timeout, hooks, validation e dispose() 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 por createEnginexClient (inclusive uma cópia { ...client }) lança CONFIGURATION_ERROR.
  • request(spec) e requestPage(spec) recebem um spec com method, path, query, body, auth ('none', 'optional' ou 'required'), idempotent, schema/item, page/perPage/perPageParam, validation: 'strict' e options (as CallOptions recebidas pelo método público, repassadas como estão). idempotent: true envia uma Idempotency-Key gerada por chamada e reusada no retry após um 401 renovado. Um auth, validation ou perPageParam fora desses valores rejeita com CONFIGURATION_ERROR antes de qualquer fetch; um segmento de path que seja . ou .. (ex.: um id vindo do app) rejeita com INVALID_ARGUMENT (status: 0), também antes do fetch, porque a URL o normalizaria para outra rota.
  • Identifique erros com isEnginexError(error, code), não com instanceof 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 em EnginexError, chama onError uma única vez e devolve o erro para lançar.
  • wire, mapOf e lazy são os mesmos helpers de schema do core (fio em snake_case, saída em camelCase, 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.

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 é o nome do tópico no gateway, sem o : final. Com private: false a fábrica exige o id; com private: true ela não recebe nenhum, e o subscribe lança UNAUTHENTICATED sem 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 (strict a descarta, warn a recupera campo a campo e avisa por onValidationIssue) e chega ao handler em camelCase. Envolva o schema em lazy para que ele só seja montado na primeira assinatura.
  • snapshots: 'ignore' pula os snapshots do modo sequenciado quando eles têm outro formato (como em coreTopics.balance()).
  • Uma definição inválida (prefixo vazio, prefixo fora do formato do gateway, messageType vazio, schema que não é do Zod) ou um id inválido lança CONFIGURATION_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:

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) devolve a chamada do SDK (call, idempotent, fixedKey) ou undefined para 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 com fingerprint), ou abre uma nova; settle(input, error?) só a mantém depois de uma falha para a qual isAmbiguousFailure(error) é true.
  • runMutation(call, attempts, input) envia a chave (ou a idempotencyKey fixa da fábrica), fecha a tentativa com o resultado e sempre rejeita com um EnginexError.

A regra do lado do app está em Idempotência; os adapters de React e Vue já fazem isso (veja Idempotência em mutations).