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.loginandauth.logout→['enginex', 'user'](all users); the otherauthones → 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,TIMEOUTor 5xx: the operation may have reached the gateway;KEY_IN_USE: the first is still being processed;VALIDATION_ERRORafter 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'sretrydoes too. - After a 4xx (e.g.
DEPOSIT_LIMIT_EXCEEDED; exceptKEY_IN_USE) or anABORTED, the key is discarded: repeating is a new operation. AnABORTEDmay have reached the gateway; whoever cancels and wants to repeat the same operation passesidempotencyKey. - 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 therequestIdreturned byrequest: 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
The client returned by createEnginexClient.
Returns
Examples
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 }))),
})// 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).