This version (v0.7) has not been published to npm yet.
Skip to content

Reference / @getenginex/sdk/query / createMutations

createMutations() ​

createMutations(client): CoreMutations

Creates the core mutations over a client: one per write method, with the same name as the method (m.deposits.createPix()). Each call returns { mutationKey, mutationFn, invalidates }, compatible with TanStack Query v5's useMutation; invalidates(input, result) lists the key prefixes that the write leaves stale (built with the session's userId at call time) and should only be called after success:

  • deposit and withdrawal (createPix, request, confirmOtp, cancel) → wallet (balance and transactions) and the namespace's own list;
  • pixKeys.add/remove/setDefault → pixKeys.list; kyc.uploadDocument → kyc.getStatus;
  • notifications.markAsRead/updatePreferences → notifications;
  • profile.update, auth.verifyEmail/verifyPhone/confirmPhoneChange → profile.get; profile.revokeSession, auth.changePassword → profile.listSessions;
  • responsibleGambling.setLimits → getLimits; selfExclude → responsibleGambling;
  • auth.login and auth.logout → ['enginex', 'user'] (all users); the other auth ones → nothing.

mutationKey is ['enginex', namespace, method], without the input (which may hold a password). Those that carry credentials or personal data (auth.*, except logout, and withdrawals.confirmOtp) have gcTime: 0, so that the input and the result leave the MutationCache (and the devtools) as soon as no component observes the mutation. While useMutation is mounted, they stay: call reset() when you no longer need them (e.g. in the login's onError, keeping the error to display in state).

Idempotency (deposits.createPix, withdrawals.request, withdrawals.confirmOtp): each options object (m.deposits.createPix()) keeps at most one open attempt: the input and the Idempotency-Key. The comparison is by the input's content, not by the object.

  • After an ambiguous failure (NETWORK_ERROR, TIMEOUT or 5xx: the operation may have reached the gateway; KEY_IN_USE: the first is still being processed; VALIDATION_ERROR after a 2xx: it already happened), repeating with the same input, even on a new object (mutate({ amount: 5000 }) again), reuses the key, and the gateway does not duplicate the deposit or the withdrawal. TanStack's retry does too.
  • After a 4xx (e.g. DEPOSIT_LIMIT_EXCEEDED; except KEY_IN_USE) or an ABORTED, the key is discarded: repeating is a new operation. An ABORTED may have reached the gateway; whoever cancels and wants to repeat the same operation passes idempotencyKey.
  • After success the key is discarded: the same value, again, is a new operation.
  • A different input starts a new attempt and discards the previous one. In withdrawals.confirmOtp, pass the requestId returned by request: a new challenge never reuses the previous one's key.
  • Two simultaneous calls with the same input, on the same options object, use the same key.
  • Each call to m.deposits.createPix() has its own attempt. In React, useEnginexMutation (@getenginex/sdk-react) keeps the attempt per hook instance, so it survives the options being recreated on every render.

To control the key yourself (e.g. store it to repeat after reloading the page), pass m.deposits.createPix({ idempotencyKey }): it wins over the attempt and applies to every call of those options. Generate one per operation, not one per screen (see the second example). The key is read when the factory is called and goes into the render's options: call mutate only after the re-render that received the key (in the same handler that stores it in state, the mutation still has the old options, without it).

Parameters ​

client ​

EnginexClient

The client returned by createEnginexClient.

Returns ​

CoreMutations

Examples ​

ts
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { createMutations } from '@getenginex/sdk/query'

const createPix = createMutations(enginex).deposits.createPix()
const mutation = useMutation({
  ...createPix,
  onSuccess: (pix, input) =>
    Promise.all(createPix.invalidates(input, pix).map((queryKey) => queryClient.invalidateQueries({ queryKey }))),
})
ts
// Explicit key, one per operation: generated when the player confirms the amount (not memoized for the
// whole screen) and stored to repeat the same operation after an error or a page reload.
const [operation, setOperation] = useState<{ amount: number; idempotencyKey: string }>()
const confirm = (amount: number) => setOperation({ amount, idempotencyKey: crypto.randomUUID() })
const createPix = useMutation(createMutations(enginex).deposits.createPix({ idempotencyKey: operation?.idempotencyKey }))
// On another click, after the re-render that received the key (not in the same handler as confirm):
const pay = () => operation && createPix.mutate({ amount: operation.amount })
// "try again" calls pay() once more, with the same key; a new amount goes through confirm() and gets
// another key.

Throws ​

CONFIGURATION_ERROR if client has no session.get() (it is not an SDK client).