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

Atualizando versões ​

Enquanto a versão major for 0, uma versão minor (0.x.0) pode trazer mudanças incompatíveis e um patch (0.x.y) não. Para receber só correções, fixe uma faixa com til na minor que você usa (~0.6.0 aceita 0.6.y, não 0.7.0). As interfaces que o SDK devolve não são feitas para o app implementar (exceto TokenStore e StorageLike), então campos ou métodos novos não quebram nada.

Atualize o core e os pacotes que dependem dele juntos: os pacotes de produto e os adapters declaram o core como peer dependency com uma versão mínima, e uma cópia do core com um contrato de transporte incompatível faz createIgaming/createPredictions lançar CONFIGURATION_ERROR. Todas as mudanças, versão por versão, estão no changelog.

Do core 0.5 para o 0.6 ​

PacoteVersão com o core 0.6O que quebra no app
@getenginex/sdk0.6.0baseUrl, idempotência das mutations, dinheiro estrito, id da chave PIX do mock
@getenginex/sdk-igaming0.5.0exige core >=0.6.0; dinheiro estrito; lista de indicações
@getenginex/sdk-predictions0.3.0exige core >=0.6.0; dinheiro estrito; chaves do lote; erro sem Web Crypto
@getenginex/sdk-react, @getenginex/sdk-next0.2.0exige core >=0.6.0; idempotência por instância do hook
@getenginex/sdk-vueprimeira versãoexige core >=0.6.0 desde o início
bash
npm i @getenginex/sdk@^0.6.0
# and, with them, the product packages and the adapter you use
npm i @getenginex/sdk-igaming@^0.5.0 @getenginex/sdk-predictions@^0.3.0
npm i @getenginex/sdk-react@^0.2.0 # or @getenginex/sdk-next@^0.2.0

Core: baseUrl aceita só a origem ​

baseUrl aceita só '' ou a origem do gateway (https://host[:porta]). Qualquer outro valor, inclusive '/' ou um caminho como /api, lança CONFIGURATION_ERROR na criação do cliente. O throw é síncrono, dentro de createEnginexClient: um cliente criado no topo de um módulo derruba o import (inclusive no SSR).

Como migrar: tire /api (ou qualquer caminho) do baseUrl; o SDK acrescenta /api/v1.

ts
// 0.5: a path in baseUrl
createEnginexClient({ baseUrl: 'https://gateway.operador.com/api' })

// 0.6: the origin only; the SDK appends /api/v1
createEnginexClient({ baseUrl: 'https://gateway.operador.com' })

Core: idempotência das mutations ​

A Idempotency-Key das mutations (createMutations, as mutations de produto, useEnginexMutation) só é reaproveitada depois de uma falha ambígua (NETWORK_ERROR, TIMEOUT, 5xx, KEY_IN_USE ou VALIDATION_ERROR depois de 2xx), para a mesma entrada comparada por conteúdo e no mesmo objeto de opções. Sucesso, os outros 4xx e ABORTED liberam a chave: quem cancela e quer repetir a mesma operação passa idempotencyKey.

Como migrar: "tentar de novo" com mutate({ ...mesmos valores }) já reaproveita a chave; código que dependia de um objeto constante para uma operação nova não precisa mudar; para repetir depois de recarregar a página, passe idempotencyKey. Veja Idempotência.

ts
const m = createMutations(enginex)

// "Try again" with the same values: after an ambiguous failure, the key is reused on its own.
const createPix = m.deposits.createPix()
await createPix.mutationFn({ amount: 5000 })

// Repeating the same operation after a page reload: keep the key (one per operation) and pass it.
const retried = m.deposits.createPix({ idempotencyKey: savedKey })

Core: dinheiro estrito ​

Valores monetários fora de inteiro seguro, moeda fora de /^[A-Z]{3}$/ e casas decimais fora de 0-8 rejeitam a resposta inteira com VALIDATION_ERROR, também com validation: 'warn' (inclusive itens de listas, mapas e uniões, e o saldo do realtime, coreTopics.balance). config.currencies segue como texto livre.

Como migrar: nada no app; um gateway fora do contrato passa a aparecer como erro. Veja Dinheiro.

Core: mudanças menores ​

  • Geração de chaves: sem crypto.randomUUID (origem insegura, como HTTP na rede local) o SDK usa crypto.getRandomValues; sem Web Crypto nenhum, rejeita com CONFIGURATION_ERROR (antes, um TypeError).
  • createMockFetch: o id da chave PIX criada deixa de ser mock-pix-key-1, que colidia com a chave semeada. Testes que fixavam esse id devem ler o id devolvido por pixKeys.add.
  • perPage continua com esse nome no SDK e vai como limit no fio nas rotas que pedem assim (deposits.list, notifications.list); nada muda no app.

Novidades que não quebram: sessionOwner: 'app' e onAccessTokenRejected (veja Sessão e tokens), enginexKeys.user(userId, namespace, method?), o requestId opcional em withdrawals.confirmOtp e, em /extension, createAttempts, mutationCallOf, runMutation, money, moneyText, currencyCode, decimalPlaces, strictValue e randomId (veja Extensibilidade).

iGaming 0.5 ​

  • Dinheiro estrito nas campanhas de bônus, nos totais do cassino, no resgate de fidelidade e nas indicações, como no core. Moeda vazia ('') só é aceita nos valores de campanha do bônus e no currency do resgate de fidelidade, porque o gateway a omite quando o valor é 0.
  • Indicações: um valor monetário inválido agora rejeita a lista inteira (antes, o item era descartado em silêncio). Como migrar: trate o erro da listagem; não há mais itens sumindo.
  • Idempotência: bonus.optIn/claim/redeemPromoCode e loyalty.redeem seguem a regra do core acima.

Predictions 0.3 ​

  • Dinheiro estrito nas ordens (colateral, taxas e custo), nas posições e no resumo do portfólio; moeda vazia só é aceita em settlementCurrency. No tópico de trades, um makerFee/takerFee inválido descarta a mensagem.
  • orders.placeBatch: as chaves de cada ordem ficam no resultado de createPredictionsMutations (memoizado por useEnginexMutations no React) e são reaproveitadas depois de falha ambígua ou sucesso parcial enquanto o conteúdo do lote for o mesmo. Como migrar: tire qualquer registro de chaves por objeto; para repetir depois de recarregar, passe idempotencyKey em cada ordem.
  • Sem Web Crypto: gerar a idempotencyKey rejeita com CONFIGURATION_ERROR (antes, UNKNOWN). Como migrar: troque a checagem de UNKNOWN por CONFIGURATION_ERROR.
ts
try {
  await predictions.orders.place(input)
} catch (error) {
  // 0.2 rejected with UNKNOWN when there was no Web Crypto to generate the key; 0.3 uses CONFIGURATION_ERROR.
  if (isEnginexError(error, 'CONFIGURATION_ERROR')) showUnsupportedBrowser()
  else throw error
}

React e Next.js 0.2 ​

useEnginexMutation guarda a tentativa de idempotência (entrada e chave) por instância do hook: ela sobrevive a re-renders e ao retry do TanStack mesmo com opções novas a cada render. Duas instâncias nunca compartilham chave, e uma instância que troca de método nunca reaproveita a chave do outro método. useUserKey(namespace?, method?) é novo.

Como migrar: tire chaves e objetos guardados à mão para o "tentar de novo"; passe os ajustes (retry, onSuccess...) no segundo argumento, não espalhados nas opções. O sdk-next acompanha o sdk-react (mesma versão) e não pede nada além de atualizar o core junto. Veja Idempotência em mutations.

tsx
// Avoid: the spread copy loses the SDK call, and with it the attempt kept per hook instance
// const pix = useEnginexMutation({ ...m.deposits.createPix(), retry: 1 })

// 0.2: adjustments go in the second argument
const pix = useEnginexMutation(m.deposits.createPix(), { retry: 1 })