Query helpers
TanStack Query helpers exported by @tetherto/mdk-ui-foundation.
| Helper | Category | Signature | Description |
|---|---|---|---|
actionsQuery | query | (client: QueryClient, params: ActionsParams = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "actions", … | `GET /auth/actions` — pending/voting actions list (the review-tray source). Array params serialize comma-separated. |
addThingCommentMutation | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "thing", "comment", "add"]; mutationFn: (body: … | 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. |
appendCommaQuery | query | (url: string, params: Record<string, unknown>) => string | 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… |
authQuery | query | (client: QueryClient, fetcher: Fetcher = defaultFetcher) => { queryKey: readonly ["auth"]; queryFn: ({ signal }?: … | TanStack Query factory for the `/auth` session lookup. Pass into `useQuery(authQuery(client))` to fetch the current session. |
authTokenMutation | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "token"]; mutationFn: (body?: … | TanStack Mutation factory for `POST /auth/token`. Used by `useTokenPolling` to refresh the session token every 250 s. |
cancelActionsMutation | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "actions", "cancel"]; mutationFn: ({ type, ids }: … | `DELETE /auth/actions/:type/cancel?ids=<comma>` — cancel pending actions. |
containerPoolStatsQuery | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pools", "stats", "containers"]; queryFn: ({ signal }?: … | `GET /auth/pools/stats/containers` — per-container override counts. |
containerSettingsQuery | query | (client: QueryClient, options: { model?: string; overwriteCache?: boolean } = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "global", "data", … | 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. |
createBearerFetcher | query | (options: { /** Override the token source — defaults to `authStore.getState().token`. */ getToken?: () => string | null /** Override `fetch` — pass a stub in tests. */ fetchImpl?: typeof fetch } = {}… | 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. |
createGetQueryFn | query | (fetcher: Fetcher, url: string) => ({ signal }?: QueryFnContext) => Promise<T> | 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… |
createMdkQueryClient | query | (options: CreateMdkQueryClientOptions = {}) => QueryClient | 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. |
deleteThingCommentMutation | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "thing", "comment", "delete"]; mutationFn: (body: … | 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). |
deviceQuery | query | (client: QueryClient, id: string, fetcher: Fetcher = defaultFetcher) => { queryKey: readonly ["devices", string]; queryFn: ({ signal }?: … | TanStack Query factory for a single device by id (`/devices/:id`). |
devicesQuery | query | (client: QueryClient, fetcher: Fetcher = defaultFetcher) => { queryKey: readonly ["devices"]; queryFn: ({ signal }?: … | TanStack Query factory for the full `/devices` inventory listing. |
editThingCommentMutation | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "thing", "comment", "edit"]; mutationFn: (body: … | TanStack Mutation factory for `PUT /auth/thing/comment` — edit an existing device comment (`body.id` identifies it). |
extDataQuery | query | (client: QueryClient, params: ExtDataParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "ext-data", … | 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… |
featureConfigQuery | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "featureConfig"]; queryFn: ({ signal }?: … | 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… |
getApiBaseUrl | query | (client: QueryClient) => string | Read the configured base URL back from a `QueryClient` produced by `createMdkQueryClient`. Falls back to the default if metadata is absent. |
globalConfigQuery | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "global-config"]; queryFn: ({ signal }?: … | 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. |
globalDataQuery | query | (client: QueryClient, params: GlobalDataParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "global", "data", … | TanStack Query factory for `GET /auth/global/data`. Generic in the row type — see `containerSettingsQuery` for the canonical narrowing. |
historyLogQuery | query | (client: QueryClient, params: HistoryLogParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "history-log", … | TanStack Query factory for `GET /auth/history-log`. `logType` is required (`'alerts' | 'info'`). |
listRacksQuery | query | (client: QueryClient, params: ListRacksParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "list-racks", … | 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. |
listThingsQuery | query | (client: QueryClient, params: ListThingsParams = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "list-things", … | TanStack Query factory for `GET /auth/list-things`. `query` and `fields` are Mongo-style selectors passed as already-stringified JSON. |
liveActionsQuery | query | (client: QueryClient, queries: ActionTypeQuery[] = [ { type: 'voting', opts: { reverse: true, limit: LIVE_ACTIONS_LIMIT } }, { type: 'ready', opts: { reverse: true, limit: LIVE_ACTIONS_LIMIT } }, { t… | `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 }`. |
mdkFetch | query | Fetcher | Module-level singleton bearer fetcher reading from the global `authStore`. Used as the default by the mining query factories (`tailLogQuery`, etc.). |
minerpoolStatsQuery | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "ext-data", … | 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. |
minersQuery | query | (client: QueryClient, params: MinersParams = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "miners", … | `GET /auth/miners` — miners with their assigned `poolConfig` (Miner Explorer rows). `filter` / `fields` / `sort` are JSON-stringified selectors. Returns the paginated {@link MinersResponse} envelope. |
pduLayoutQuery | query | (client: QueryClient, params: PduLayoutParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pdu-layout", … | 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… |
poolBalanceHistoryQuery | query | (client: QueryClient, pool: string, params: PoolBalanceHistoryParams = {}, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pools", string, "balance-history", … | `GET /auth/pools/:pool/balance-history` — per-pool revenue/hashrate history for the chart view. |
poolConfigForDeviceQuery | query | (client: QueryClient, minerId: string, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pools", "config", string]; queryFn: ({ signal }?: … | `GET /auth/pools/config/:minerId` — pool config + override count for a single device/miner. |
poolConfigsQuery | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "configs", "pool"]; queryFn: ({ signal }?: … | `GET /auth/configs/pool` — raw pool configurations. The shape the devkit `usePoolConfigs` transform consumes. |
poolsQuery | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "pools"]; queryFn: ({ signal }?: … | `GET /auth/pools` — aggregated pools (hashrate / workers / balance / revenue). Feeds the Dashboard pool panel. |
resolveApiBaseUrl | query | (override?: string) => string | Resolves the Gateway API base URL using the priority order described in HLD §2.4 / §5: |
siteQuery | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "site"]; queryFn: ({ signal }?: … | TanStack Query factory for `GET /auth/site` — the configured site label. |
siteStatusLiveQuery | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "site", "status", "live"]; queryFn: ({ signal }?: … | `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… |
submitActionMutation | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "actions", "submit"]; mutationFn: (payload: … | `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… |
submitBatchActionMutation | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "actions", "submit", "batch"]; mutationFn: (payload: … | `POST /auth/actions/voting/batch` — submit a batch of staged actions in one request. Expects the {@link SubmitBatchActionsPayload} body (`{ batchActionsPayload, batchActionUID, suffix? }`). |
tailLogMultiQuery | query | (client: QueryClient, params: TailLogMultiParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "tail-log", "multi", … | 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. |
tailLogQuery | query | (client: QueryClient, params: TailLogParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "tail-log", … | 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). |
telemetryQuery | query | (client: QueryClient, deviceId: string, fetcher: Fetcher = defaultFetcher) => { queryKey: readonly ["telemetry", string]; queryFn: ({ signal }?: … | TanStack Query factory for live telemetry of a device (`/telemetry/:deviceId`). |
thingConfigQuery | query | (client: QueryClient, params: ThingConfigParams, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "thing-config", … | 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. |
userInfoQuery | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { queryKey: readonly ["auth", "userinfo"]; queryFn: ({ signal }?: … | `GET /auth/userinfo` — current authenticated user's profile. Used to resolve the caller's email for partitioning live actions into "mine vs others". |
voteActionMutation | query | (client: QueryClient, fetcher: Fetcher = mdkFetch) => { mutationKey: readonly ["auth", "actions", "vote"]; mutationFn: ({ id, approve }: … | `PUT /auth/actions/voting/:id/vote` — approve or reject a pending action. |