Query Helpers
TanStack Query helpers for data fetching and mutations
TanStack Query helper functions for fetching API data, managing mutations, and configuring the query client. These utilities streamline integration with the MDK Gateway API.
Package
@tetherto/mdk-ui-foundation
Query Helpers
@tetherto/mdk-ui-foundation
Import the public APIs on this page from @tetherto/mdk-ui-foundation.
actionsQuery
GET /auth/actions — pending/voting actions list (the review-tray source). Array params serialize comma-separated.
(client: QueryClient, params: ActionsParams = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "actions", ActionsParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<unknown>; }addThingCommentMutation
TanStack Mutation factory for POST /auth/thing/comment — add a device comment. Requires the comments:write permission; the backend stamps the author from the session token.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "thing", "comment", "add"]; mutationFn: (body: ThingCommentBody) => Promise<unknown>; }appendCommaQuery
Append query params to a URL, serializing array values comma-separated (e.g. { ids: ['a', 'b'] } → ?ids=a,b). Mirrors the qs arrayFormat: 'comma' convention MiningOS expects, without the extra dependency. undefined / null and e…
(url: string, params: Record<string, unknown>) => stringauthQuery
TanStack Query factory for the /auth session lookup. Pass into useQuery(authQuery(client)) to fetch the current session.
(client: QueryClient, fetcher: Fetcher = defaultFetcher) => { queryKey: readonly ["auth"]; queryFn: ({ signal }?: QueryFnContext) => Promise<unknown>; }authTokenMutation
TanStack Mutation factory for POST /auth/token. Used by useTokenPolling to refresh the session token every 250 s.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "token"]; mutationFn: (body?: AuthTokenRequest) => Promise<AuthTokenResponse>; }cancelActionsMutation
DELETE /auth/actions/:type/cancel?ids=<comma> — cancel pending actions.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "actions", "cancel"]; mutationFn: ({ type, ids }: CancelActionsPayload) => Promise<unknown>; }containerPoolStatsQuery
GET /auth/pools/stats/containers — per-container override counts.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pools", "stats", "containers"]; queryFn: ({ signal }?: QueryFnContext) => Promise<ContainerPoolStat[]>; }containerSettingsQuery
Convenience wrapper around globalDataQuery pinned to type=containerSettings — per-model container thresholds/parameters. Verified live: the response is a flat ContainerSettingsEntry[], not the per-Kernel envelope.
(client: QueryClient, options: { model?: string; overwriteCache?: boolean } = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "global", "data", GlobalDataParams]; queryFn: ({ signal…createBearerFetcher
Build a Fetcher that injects Authorization: Bearer <token> from the supplied token getter (defaults to authStore). Non-2xx responses throw an MdkFetchError carrying the HTTP status and parsed body.
(options: { /** Override the token source — defaults to `authStore.getState().token`. */ getToken?: () => string | null /** Override `fetch` — pass a stub in tests. */ fetchImpl?: typeof fetch } = {}…createGetQueryFn
Build a signal-aware GET queryFn for an already-resolved url. This is the single place the AbortSignal is threaded into the fetcher: TanStack cancels a query (firing the signal) when its last observer unmounts on navigation, or when…
(fetcher: Fetcher, url: string) => ({ signal }?: QueryFnContext) => Promise<T>createMdkQueryClient
Build a TanStack QueryClient configured with the resolved API base URL. The base URL is exposed via client.getDefaultOptions().queries.meta so callers can read it without importing the resolveApiBaseUrl helper.
(options: CreateMdkQueryClientOptions = {}) => QueryClientdeleteThingCommentMutation
TanStack Mutation factory for DELETE /auth/thing/comment — remove an existing device comment (body.id identifies it; the schema still requires the full body on delete).
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "thing", "comment", "delete"]; mutationFn: (body: ThingCommentBody) => Promise<unknown>; }deviceQuery
TanStack Query factory for a single device by id (/devices/:id).
(client: QueryClient, id: string, fetcher: Fetcher = defaultFetcher) => { queryKey: readonly ["devices", string]; queryFn: ({ signal }?: QueryFnContext) => Promise<unknown>; }devicesQuery
TanStack Query factory for the full /devices inventory listing.
(client: QueryClient, fetcher: Fetcher = defaultFetcher) => { queryKey: readonly ["devices"]; queryFn: ({ signal }?: QueryFnContext) => Promise<unknown>; }editThingCommentMutation
TanStack Mutation factory for PUT /auth/thing/comment — edit an existing device comment (body.id identifies it).
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "thing", "comment", "edit"]; mutationFn: (body: ThingCommentBody) => Promise<unknown>; }extDataQuery
TanStack Query factory for GET /auth/ext-data. Generic in the response row type so adapters can pin the result to a typed envelope (see minerpoolStatsQuery for the canonical narrowing). query is a JSON-stringified provider-specific s…
(client: QueryClient, params: ExtDataParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "ext-data", ExtDataParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<TRow[][]>; }featureConfigQuery
TanStack Query factory for GET /auth/featureConfig — deployment feature flags, including the multi-site mode switch. Note the camelCase path: there is no /auth/feature-config route (a kebab-case request falls through to the SPA fallbac…
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "featureConfig"]; queryFn: ({ signal }?: QueryFnContext) => Promise<FeatureConfigResponse>; }getApiBaseUrl
Read the configured base URL back from a QueryClient produced by createMdkQueryClient. Falls back to the default if metadata is absent.
(client: QueryClient) => stringglobalConfigQuery
TanStack Query factory for GET /auth/global-config — the global system config document. Shape is deployment-specific (not yet captured live), so callers narrow via the generic.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "global-config"]; queryFn: ({ signal }?: QueryFnContext) => Promise<TConfig>; }globalDataQuery
TanStack Query factory for GET /auth/global/data. Generic in the row type — see containerSettingsQuery for the canonical narrowing.
(client: QueryClient, params: GlobalDataParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "global", "data", GlobalDataParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<TR…historyLogQuery
TanStack Query factory for GET /auth/history-log. logType is required ('alerts' | 'info').
(client: QueryClient, params: HistoryLogParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "history-log", HistoryLogParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<Recor…listRacksQuery
TanStack Query factory for GET /auth/list-racks. type (worker type, e.g. miner / container) is required — the backend 400s with ERR_TYPE_INVALID without it. Response is the per-Kernel nested envelope.
(client: QueryClient, params: ListRacksParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "list-racks", ListRacksParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<Rack[][]…listThingsQuery
TanStack Query factory for GET /auth/list-things. query and fields are Mongo-style selectors passed as already-stringified JSON.
(client: QueryClient, params: ListThingsParams = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "list-things", ListThingsParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<…liveActionsQuery
GET /auth/actions?queries=… — polls all action types in a single request using the multi-type query format. Returns the typed response map { voting, ready, executing, done }.
(client: QueryClient, queries: ActionTypeQuery[] = [ { type: 'voting', opts: { reverse: true, limit: LIVE_ACTIONS_LIMIT } }, { type: 'ready', opts: { reverse: true, limit: LIVE_ACTIONS_LIMIT } }, { t…mdkFetch
Module-level singleton bearer fetcher reading from the global authStore. Used as the default by the mining query factories (tailLogQuery, etc.).
FetcherminerpoolStatsQuery
Convenience wrapper around extDataQuery pinned to type=minerpool and query={"key":"stats"}. Returns the canonical MinerpoolExtDataEntry[][] envelope so the pool counts hook can _head(_head(...)) without casts.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "ext-data", ExtDataParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<MinerpoolExtDataEntry[][]>; }minersQuery
GET /auth/miners — miners with their assigned poolConfig (Miner Explorer rows). filter / fields / sort are JSON-stringified selectors. Returns the paginated MinersResponse envelope.
(client: QueryClient, params: MinersParams = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "miners", MinersParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<MinersRespons…pduLayoutQuery
TanStack Query factory for GET /auth/pdu-layout — the static PDU socket grid for a container type. The backend sources it from the container worker's pduGridLayout config keyed by the exact type string, and 400s with `ERR_PDU_LAYOUT_NO…
(client: QueryClient, params: PduLayoutParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pdu-layout", PduLayoutParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<PduLayou…poolBalanceHistoryQuery
GET /auth/pools/:pool/balance-history — per-pool revenue/hashrate history for the chart view.
(client: QueryClient, pool: string, params: PoolBalanceHistoryParams = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pools", string, "balance-history", PoolBalanceHistoryParams];…poolConfigForDeviceQuery
GET /auth/pools/config/:minerId — pool config + override count for a single device/miner.
(client: QueryClient, minerId: string, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pools", "config", string]; queryFn: ({ signal }?: QueryFnContext) => Promise<PoolConfigForDeviceR…poolConfigsQuery
GET /auth/configs/pool — raw pool configurations. The shape the devkit usePoolConfigs transform consumes.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "configs", "pool"]; queryFn: ({ signal }?: QueryFnContext) => Promise<PoolConfigEntry[]>; }poolsQuery
GET /auth/pools — aggregated pools (hashrate / workers / balance / revenue). Feeds the Dashboard pool panel.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pools"]; queryFn: ({ signal }?: QueryFnContext) => Promise<PoolsResponse>; }resolveApiBaseUrl
Resolves the Gateway API base URL using the priority order described in HLD §2.4 / §5:
(override?: string) => stringsiteQuery
TanStack Query factory for GET /auth/site — the configured site label.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "site"]; queryFn: ({ signal }?: QueryFnContext) => Promise<SiteResponse>; }siteStatusLiveQuery
GET /auth/site/status/live?overwriteCache=true — composite live site-status snapshot (hashrate / power / efficiency / miner, alert & pool counts). Polled on a short interval by useSiteStatusLive; overwriteCache bypasses the server-si…
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "site", "status", "live"]; queryFn: ({ signal }?: QueryFnContext) => Promise<SiteStatusLive>; }submitActionMutation
POST /auth/actions/voting — submit a single staged action. The backend exposes a fixed voting path, so the client-only type field is stripped from the body; the remaining fields (query, action, params, rackType, …) form the r…
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "actions", "submit"]; mutationFn: (payload: VotingActionPayload) => Promise<unknown>; }submitBatchActionMutation
POST /auth/actions/voting/batch — submit a batch of staged actions in one request. Expects the SubmitBatchActionsPayload body ({ batchActionsPayload, batchActionUID, suffix? }).
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "actions", "submit", "batch"]; mutationFn: (payload: SubmitBatchActionsPayload) => Promise<unknown>; }tailLogMultiQuery
TanStack Query factory for GET /auth/tail-log/multi — the batched variant of tail-log (keys is a comma-separated list of stat-* keys). Returns the same per-worker nested envelope as tailLogQuery, one series per requested key.
(client: QueryClient, params: TailLogMultiParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "tail-log", "multi", TailLogMultiParams]; queryFn: ({ signal }?: QueryFnContext) => Pro…tailLogQuery
TanStack Query factory for GET /auth/tail-log. Returns the raw nested response shape (Array<Array<TailLogEntry>>) — callers unwrap with _head(response) (or a typed select projection).
(client: QueryClient, params: TailLogParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "tail-log", TailLogParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<TailLogEntry[]…telemetryQuery
TanStack Query factory for live telemetry of a device (/telemetry/:deviceId).
(client: QueryClient, deviceId: string, fetcher: Fetcher = defaultFetcher) => { queryKey: readonly ["telemetry", string]; queryFn: ({ signal }?: QueryFnContext) => Promise<unknown>; }thingConfigQuery
TanStack Query factory for GET /auth/thing-config — a thing type's config document (Settings tab). Both params are required by the backend schema. Response shape is worker-specific, so callers narrow via the generic.
(client: QueryClient, params: ThingConfigParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "thing-config", ThingConfigParams]; queryFn: ({ signal }?: QueryFnContext) => Promise<TC…userInfoQuery
GET /auth/userinfo — current authenticated user's profile. Used to resolve the caller's email for partitioning live actions into "mine vs others".
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "userinfo"]; queryFn: ({ signal }?: QueryFnContext) => Promise<UserInfoResponse>; }voteActionMutation
PUT /auth/actions/voting/:id/vote — approve or reject a pending action.
(client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "actions", "vote"]; mutationFn: ({ id, approve }: VoteActionPayload) => Promise<unknown>; }