@doughmination/react-api

Typed client and React hooks for the Doughmination API — Discord presence, Minecraft & Hypixel stats, the plural system (fronters, members, mental state), devices and the guestbook — all backed by a single shared WebSocket for live updates.

• Zero-config reads. Every public read works with no auth. Construct the provider with nothing but a QueryClient and you're live.
• One connection. <DoughminationProvider> owns exactly one socket for the whole tree. Presence subscriptions are ref-counted, so unmounting one component never kills another's feed.
• Fully typed from the source. Response types are hand-written from the API handlers, not a spec.
• ESM + CJS + types, React 18/19, TanStack Query v5.

Install

npm i @doughmination/react-api @tanstack/react-query react
# or: bun add @doughmination/react-api @tanstack/react-query react

react and @tanstack/react-query are peer dependencies — the package uses your app's copies.

Quick start

Wrap your app in a TanStack QueryClientProvider, then DoughminationProvider:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { DoughminationProvider } from "@doughmination/react-api";

const queryClient = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <DoughminationProvider>
        <Dashboard />
      </DoughminationProvider>
    </QueryClientProvider>
  );
}

That's the whole setup for public reads and live updates. Auth and captcha are only needed for writes (see Authentication and Turnstile).

Provider options

<DoughminationProvider
  baseUrl="https://doughmination.uk/v2"   // default
  token={() => localStorage.getItem("token")}  // JWT for writes; function or string
  batteryKey={process.env.BATTERY_KEY}    // X-Battery-Key for device/guestbook admin
  turnstile={() => turnstileTokenRef.current}   // supplies captcha tokens (see below)
  realtime                                 // default true; set false to disable the socket
  onError={(e) => console.error(e)}
>
  {children}
</DoughminationProvider>

token, batteryKey and botToken each accept a string or a (sync/async) function, so you can read from your own auth store on every request without rebuilding the client.

Query hooks

Every read hook is a thin TanStack Query wrapper — you get data, isLoading, error, refetch and can pass through any query option.

import {
  useDiscordUser,
  useDiscordUsers,
  useMinecraftProfile,
  useHypixelStats,
  useFronters,
  useMembers,
  useMentalState,
  useDevices,
  useGuestbook,
} from "@doughmination/react-api";

useDiscordUser("209830981060788225");        // merged profile + badges + presence
useGenshinRoster("691386457");               // Genshin Impact roster
useMinecraftProfile("79ef438d69ea473c99cd6a5ec34c6736"); // skin, capes, render URLs
useHypixelStats(uuid);                        // Hypixel + SkyBlock (allowlisted UUIDs only)
useFronters();                                // current front — live (see below)
useMembers();                                 // all members, with tags + status
useMentalState();                             // current mental state — live
useDevices();                                 // all device battery/state — live
useGuestbook({ limit: 20, offset: 0 });       // newest first, keeps previous page while loading

Example:

function ProfileCard({ id }: { id: string }) {
  const { data, isLoading, error } = useDiscordUser(id);
  if (isLoading) return <Spinner />;
  if (error) return <p>{error.message}</p>;
  return (
    <div>
      <img src={data.user.avatar_url} alt="" />
      <strong>{data.user.display_name ?? data.user.username}</strong>
      <span>{data.presence?.status ?? "offline"}</span>
    </div>
  );
}

Hypixel helpers

player and skyblock come back as raw upstream blobs (the API defines no schema for them). Typed accessors read the common fields defensively:

import { useHypixelStats, getPlayerSummary, getSkyblockProfiles } from "@doughmination/react-api";

function Stats({ uuid }: { uuid: string }) {
  const { data } = useHypixelStats(uuid);
  const player = getPlayerSummary(data);   // { rank, networkLevel, karma, firstLogin, ... }
  const profiles = getSkyblockProfiles(data);
  return <p>{player.rank ?? "Unranked"} · level {Math.floor(player.networkLevel ?? 0)}</p>;
}

useHypixelStats returns 403 for any UUID that isn't one of the operator's own accounts — that's by design (Hypixel's API policy forbids proxying arbitrary players). An allowlisted player who's never joined Hypixel still resolves 200; check data.source.player to tell the cases apart.

Realtime

The API exposes one socket at /v2/ws. The provider opens it once and fans events out to every hook. It handles reconnect (exponential backoff + jitter), keepalive (ping→pong), and re-sends subscriptions after a reconnect.

Three event types are pushed to every client automatically — no subscription needed:

• fronters_update → useFronters() stays live
• mental_state_update → useMentalState() stays live
• device_update → useDevices() / useDeviceState() stay live

So useFronters() seeds from REST and then updates itself on every switch, including switches made in other browsers:

function FrontList() {
  const { data } = useFronters();     // updates live, no extra wiring
  return (
    <ul>
      {data?.members?.map((m) => (
        <li key={m.id}>
          {m.display_name ?? m.name}
          {m.tags?.includes("Host") && " · Host"}
          {m.status && ` — ${m.status.text}`}
        </li>
      ))}
    </ul>
  );
}

Note: the fronters_update event carries PluralKit's raw object, which is missing the tags/status enrichment the REST route adds. This package merges live payloads over the cached data per member, so those fields survive a switch. You don't need to do anything.

Live presence

Presence is the one opt-in feed. usePresence sends the subscribe frame, receives the init_state snapshot, then live presence_update events — for the users you asked for only. Subscriptions are ref-counted, so several components can watch overlapping ids safely.

import { usePresence } from "@doughmination/react-api";

function LivePresence({ ids }: { ids: string[] }) {
  const { presences, isLive, isReady } = usePresence(ids);
  // ids can be a fresh array each render — subscriptions are keyed by sorted ids.

  if (!isReady) return <p>{isLive ? "Loading…" : "Connecting…"}</p>;

  return (
    <ul>
      {ids.map((id) => {
        const p = presences[id];
        return (
          <li key={id}>
            {id}: {p?.status ?? "offline"}
            {p?.listening_to_spotify && ` · ♫ ${p.spotify?.song}`}
          </li>
        );
      })}
    </ul>
  );
}

Pass "all" to follow every tracked user: usePresence("all"). For a single user, useUserPresence(id) returns just that UnifiedPresence | undefined. useConnectionStatus() gives the socket lifecycle (idle | connecting | open | reconnecting | closed).

Live device state

import { useDeviceState } from "@doughmination/react-api";

function Battery() {
  const { device, isLive } = useDeviceState("iphone");
  if (!device) return <span>—</span>;
  return (
    <span>
      {device.level}%{device.charging ? " ⚡" : ""}
      {device.wifi && ` · ${device.wifi}`}
      {!isLive && " (stale)"}
    </span>
  );
}

Any raw event

import { useDoughminationEvent } from "@doughmination/react-api";

useDoughminationEvent("force_refresh", () => toast("Data refreshed"));

By default the provider also invalidates all package queries when it receives force_refresh (toggle with invalidateOnForceRefresh).

Authentication

Reads need nothing. Writes (switching fronters, setting mental state, device reports, guestbook moderation) need a credential on the provider.

import { useLogin, useSetFronters } from "@doughmination/react-api";

function LoginForm() {
  const login = useLogin();
  async function onSubmit(username: string, password: string, turnstileToken: string) {
    const { access_token } = await login.mutateAsync({ username, password, turnstileToken });
    localStorage.setItem("token", access_token);   // you store it; feed it back via provider `token`
  }
}

// Once the provider has the token, writes just work:
function SwitchButton({ ids }: { ids: string[] }) {
  const setFronters = useSetFronters();
  return <button onClick={() => setFronters.mutate(ids)}>Switch</button>;
  // No manual refetch — the API broadcasts fronters_update and useFronters() updates itself.
}

The package never stores your token — put it wherever your app keeps auth state and pass it back through the provider's token prop.

Unverified accounts. New signups must confirm their email before login. A blocked login rejects with a DoughminationError where status === 403 and code === "email_unverified" — use that to offer a "resend confirmation" action rather than "wrong password".

Account recovery

Signup now requires an email and returns a one-time correction_token (for fixing a typo'd address without a password). The full flow is covered:

import {
  useSignup, useVerifyEmail, useResendVerification, useCorrectEmail,
  useForgotPassword, useForgotUsername, useResetPassword, useResetTokenValid,
  useUsernameAvailable, useEmailAvailable,
} from "@doughmination/react-api";

const signup = useSignup();
const { correction_token } = await signup.mutateAsync({ username, password, email });

useVerifyEmail().mutate(tokenFromUrl);              // confirm the address (no captcha)
useResetTokenValid(tokenFromUrl);                   // check a reset link before showing the form
useForgotPassword().mutate({ username });           // email a reset link
useResetPassword().mutate({ token, newPassword });  // set the new password

Turnstile

Login, signup, guestbook posts and the recovery endpoints are Cloudflare Turnstile–gated. This package cannot generate a captcha token — it comes from the widget you render. Supply it one of two ways:

Per call — pass turnstileToken in the mutation variables:

login.mutate({ username, password, turnstileToken });

Provider-wide — give the provider a turnstile callback that returns the current token; every gated mutation uses it as the fallback:

const tokenRef = useRef<string>("");

<DoughminationProvider turnstile={() => tokenRef.current}>
  {/* render Turnstile's widget somewhere and set tokenRef.current in its callback */}
</DoughminationProvider>

Guestbook post

import { useGuestbook, useGuestbookPost } from "@doughmination/react-api";

function Guestbook() {
  const { data } = useGuestbook({ limit: 20 });
  const post = useGuestbookPost();   // turnstile from provider, or pass turnstileToken here

  async function sign(name: string, message: string) {
    const res = await post.mutateAsync({ name, message });
    if (res.skipped) return;         // honeypot tripped — API fakes success and drops it
  }

  return <>{data?.entries.map((e) => <p key={e.id}><b>{e.name}</b>: {e.message}</p>)}</>;
}

Guestbook posts are rate limited to one per 60s per IP — that surfaces as a DoughminationError with isRateLimited === true.

Error handling

Both of the API's error conventions ({success:false, error:{code,message}} from the Worker routes and {detail} from the system routes) are normalised into one DoughminationError:

import { isDoughminationError } from "@doughmination/react-api";

try {
  await post.mutateAsync({ name, message });
} catch (err) {
  if (isDoughminationError(err)) {
    if (err.isRateLimited) show("Slow down a moment.");
    else if (err.isAuthError) show("Please log in again.");
    else show(err.message);         // err.status, err.code, err.body also available
  }
}

Using the client without React

The typed client is exported on its own — handy for scripts, SSR loaders, or route handlers:

import { DoughminationClient } from "@doughmination/react-api";

const client = new DoughminationClient();               // reads need no config
const fronters = await client.getFronters();
const record = await client.getDiscordUser("209830981060788225");

CORS

The public read routes (/discord/*, /minecraft/*) allow any origin. The system routes (/plural/*, /devices, /guestbook) use an allowlist with credentials — by default doughmination.uk, doughmination.co.uk, c.stupid.cat, and any localhost port. If you host your frontend elsewhere, add its origin to the API's CORS_ORIGINS, or those calls will fail in the browser.

API surface

| Area | Hooks | |------|-------| | Discord | useDiscordUser, useDiscordUsers, useDiscordStatus | | Minecraft | useMinecraftProfile, useHypixelStats, useMinecraftCapes | | Plural | useFronters, useMembers, useMember, useMentalState, useSystem, useMemberStatus, useUserInfo | | Devices | useDevices, useDeviceState | | Guestbook | useGuestbook, useGuestbookPost, useDeleteGuestbookEntry | | Presence / realtime | usePresence, useUserPresence, useConnectionStatus, useDoughminationEvent | | Auth & writes | useLogin, useSignup, useSetFronters, useSwitchFront, useSetMentalState, useReportDevice | | Account recovery | useVerifyEmail, useResendVerification, useCorrectEmail, useForgotPassword, useForgotUsername, useResetPassword, useResetTokenValid, useUsernameAvailable, useEmailAvailable |

Escape hatches: useDoughminationClient() (the client), useDoughminationSocket() (the raw socket), queryKeys (for manual cache work).

Development

bun install
bun run typecheck
bun run build    # tsup → dist/ (ESM + CJS + .d.ts)

Licence

ESAL-2.3