Query helpers

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

Import the public APIs on this page from @tetherto/mdk-ui-foundation.

createMdkQueryClient

Build the TanStack QueryClient an MDK app talks to its Gateway with.

The Gateway base URL and an auth-aware fetcher are stashed on defaultOptions.{queries,mutations}.meta, readable via getApiBaseUrl / getFetcher. A session the Gateway ends (401) is cleared on the spot.

createMdkQueryClient({ apiBaseUrl, auth: gatewayRedirectAuth({ oauthBaseUrl }) })

(options: CreateMdkQueryClientOptions = {}) => QueryClient

getApiBaseUrl

Read the configured base URL back from a QueryClient. Falls back to the default when the client was not produced by createMdkQueryClient.

(client: QueryClient) => string

getFetcher

Read the client's auth-aware fetcher, or undefined for a client MDK did not build. Use it to call your Gateway routes with the session's token.

(client: QueryClient) => Fetcher | undefined

getMdkRuntime

Read the whole runtime at once. baseUrl is always resolved.

(client: QueryClient) => MdkRuntime

mdkFetch

Module-level singleton bearer fetcher reading from the global authStore. Used as the default by the mining query factories (tailLogQuery, etc.).

Fetcher

resolveApiBaseUrl

Resolves the API base URL:

1. Explicit override (caller-supplied, typically from MdkProvider). An explicit empty string ('') is honoured as "use relative URLs" — the canonical signal that requests should go through a reverse proxy (the Vite dev-server proxy in development, an ingress in production).
2. VITE_MDK_API_URL (bundler) or MDK_API_URL (Node).
3. The deprecated VITE_API_BASE_URL / API_BASE_URL, which warn once.
4. Hardcoded default (http://localhost:3000).

(override?: string) => string

API helpers

Import the public APIs on this page from @tetherto/mdk-ui-foundation.

describeRequestError

A one-line, operator-facing reason a request to url failed. An app's own ERR_ message wins; otherwise the HTTP status says whether nothing serves the route (404), the Gateway refused it (401/403) or nothing answered (5xx). Any other error gives its own message.

(error: unknown, url: string, { unreachableHint }: DescribeRequestErrorOptions = {}) => string