refactor: Centralize Admin authenticated JSON transport

README.md

@@ -30,6 +30,17 @@ pnpm build
 pnpm start
 ```
 
+## API transport and checks
+
+Resource adapters live in `lib/recoup/` and share `requestAdminJson` for Bearer
+requests and JSON errors. Each adapter owns its URL/query and response projection;
+sandbox endpoints retain their message-only error contract. `useIsAdmin` keeps its
+separate false-on-denial policy.
+
+Run `pnpm test` with Node 22.15+ (or Node 24+) for mocked-network transport regression
+checks. The suite loads the real TypeScript adapters and never contacts the API.
+Run `pnpm exec tsc --noEmit` and `pnpm build` for application checks.
+
 ## Project Structure
 
 ```text

hooks/useAdminSandboxes.ts

@@ -2,7 +2,7 @@
 
 import { useQuery } from "@tanstack/react-query";
 import { usePrivy } from "@privy-io/react-auth";
-import { fetchAdminSandboxes } from "@/lib/fetchAdminSandboxes";
+import { fetchAdminSandboxes } from "@/lib/recoup/fetchAdminSandboxes";
 
 /**
  * Fetches account sandbox statistics from GET /api/admins/sandboxes

lib/recoup/fetchAccountPulseEmails.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 
 /**
@@ -35,15 +36,9 @@ export async function fetchAccountPulseEmails(
   const url = new URL(`${API_BASE_URL}/api/admins/emails`);
   url.searchParams.set("account_id", accountId);
 
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
-  }
-
-  const data = await res.json();
+  const data = await requestAdminJson<{ emails?: PulseEmail[] }>(
+    url.toString(),
+    accessToken,
+  );
   return data.emails ?? [];
 }

lib/recoup/fetchAccountTaskRuns.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { TaskRun } from "@/types/sandbox";
 
@@ -19,15 +20,9 @@ export async function fetchAccountTaskRuns(
   url.searchParams.set("account_id", accountId);
   url.searchParams.set("limit", String(limit));
 
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
-  }
-
-  const data = await res.json();
+  const data = await requestAdminJson<{ runs?: TaskRun[] }>(
+    url.toString(),
+    accessToken,
+  );
   return data.runs ?? [];
 }

lib/recoup/fetchAdminSandboxOrgs.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { OrgRepoRow } from "@/types/sandbox";
 
@@ -11,15 +12,10 @@ import type { OrgRepoRow } from "@/types/sandbox";
 export async function fetchAdminSandboxOrgs(
   accessToken: string,
 ): Promise<OrgRepoRow[]> {
-  const res = await fetch(`${API_BASE_URL}/api/admins/sandboxes/orgs`, {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.message ?? `HTTP ${res.status}`);
-  }
-
-  const data = await res.json();
+  const data = await requestAdminJson<{ repos?: OrgRepoRow[] }>(
+    `${API_BASE_URL}/api/admins/sandboxes/orgs`,
+    accessToken,
+    ["message"],
+  );
   return data.repos ?? [];
 }

lib/fetchAdminSandboxes.ts → lib/recoup/fetchAdminSandboxes.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { AccountSandboxRow } from "@/types/sandbox";
 
@@ -11,15 +12,10 @@ import type { AccountSandboxRow } from "@/types/sandbox";
 export async function fetchAdminSandboxes(
   accessToken: string,
 ): Promise<AccountSandboxRow[]> {
-  const res = await fetch(`${API_BASE_URL}/api/admins/sandboxes`, {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.message ?? `HTTP ${res.status}`);
-  }
-
-  const data = await res.json();
+  const data = await requestAdminJson<{ accounts?: AccountSandboxRow[] }>(
+    `${API_BASE_URL}/api/admins/sandboxes`,
+    accessToken,
+    ["message"],
+  );
   return data.accounts ?? [];
 }

lib/recoup/fetchCodingPrStatus.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { CodingPrStatusResponse } from "@/types/coding-agent";
 
@@ -20,14 +21,5 @@ export async function fetchCodingPrStatus(
   const url = new URL(`${API_BASE_URL}/api/admins/coding/pr`);
   pullRequests.forEach((pr) => url.searchParams.append("pull_requests", pr));
 
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
-  }
-
-  return res.json();
+  return requestAdminJson<CodingPrStatusResponse>(url.toString(), accessToken);
 }

lib/recoup/fetchContentSlackTags.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { AdminPeriod } from "@/types/admin";
 import type { ContentSlackResponse } from "@/types/contentSlack";
@@ -9,14 +10,5 @@ export async function fetchContentSlackTags(
   const url = new URL(`${API_BASE_URL}/api/admins/content/slack`);
   url.searchParams.set("period", period);
 
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
-  }
-
-  return res.json();
+  return requestAdminJson<ContentSlackResponse>(url.toString(), accessToken);
 }

lib/recoup/fetchCreditsEvents.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { CreditsPeriod, CreditsEventsResponse } from "@/types/credits";
 
@@ -29,14 +30,5 @@ export async function fetchCreditsEvents({
   url.searchParams.set("page", String(page));
   url.searchParams.set("limit", String(limit));
 
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
-  }
-
-  return res.json();
+  return requestAdminJson<CreditsEventsResponse>(url.toString(), accessToken);
 }

lib/recoup/fetchCreditsRollup.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { CreditsPeriod, CreditsRollupResponse } from "@/types/credits";
 
@@ -23,14 +24,5 @@ export async function fetchCreditsRollup({
   url.searchParams.set("page", "1");
   url.searchParams.set("limit", "500");
 
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
-  }
-
-  return res.json();
+  return requestAdminJson<CreditsRollupResponse>(url.toString(), accessToken);
 }

lib/recoup/fetchPrivyLogins.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { PrivyLoginsPeriod, PrivyLoginsResponse } from "@/types/privy";
 
@@ -16,14 +17,5 @@ export async function fetchPrivyLogins(
   const url = new URL(`${API_BASE_URL}/api/admins/privy`);
   url.searchParams.set("period", period);
 
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
-  }
-
-  return res.json();
+  return requestAdminJson<PrivyLoginsResponse>(url.toString(), accessToken);
 }

lib/recoup/fetchPulseEmailById.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { PulseEmail } from "./fetchAccountPulseEmails";
 
@@ -15,15 +16,9 @@ export async function fetchPulseEmailById(
   const url = new URL(`${API_BASE_URL}/api/admins/emails`);
   url.searchParams.set("email_id", emailId);
 
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
-  }
-
-  const data = await res.json();
+  const data = await requestAdminJson<{ emails?: PulseEmail[] }>(
+    url.toString(),
+    accessToken,
+  );
   return data.emails?.[0] ?? null;
 }

lib/recoup/fetchSlackTags.ts

@@ -1,3 +1,4 @@
+import { requestAdminJson } from "@/lib/recoup/requestAdminJson";
 import { API_BASE_URL } from "@/lib/consts";
 import type { SlackTagsPeriod, SlackTagsResponse } from "@/types/coding-agent";
 
@@ -16,14 +17,5 @@ export async function fetchSlackTags(
   const url = new URL(`${API_BASE_URL}/api/admins/coding/slack`);
   url.searchParams.set("period", period);
 
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
-  }
-
-  return res.json();
+  return requestAdminJson<SlackTagsResponse>(url.toString(), accessToken);
 }

lib/recoup/requestAdminJson.ts

@@ -0,0 +1,24 @@
+/** Authenticated JSON transport; resource adapters own paths and response shapes. */
+export async function requestAdminJson<T>(
+  url: string | URL,
+  accessToken: string,
+  errorFields: readonly string[] = ["error", "message"],
+): Promise<T> {
+  const response = await fetch(url.toString(), {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!response.ok) {
+    const body: unknown = await response.json().catch(() => null);
+    const errorBody =
+      typeof body === "object" && body !== null && !Array.isArray(body)
+        ? (body as Record<string, unknown>)
+        : undefined;
+    const message = errorFields
+      .map((field) => errorBody?.[field])
+      .find((value) => value !== null && value !== undefined);
+    throw new Error(String(message ?? `HTTP ${response.status}`));
+  }
+
+  return response.json();
+}

package.json

@@ -6,7 +6,8 @@
     "dev": "next dev --turbopack",
     "build": "next build",
     "start": "next start",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "test": "node --experimental-strip-types --import ./tests/register-paths.mjs --test tests/*.test.mjs"
   },
   "dependencies": {
     "@privy-io/react-auth": "^1.88.4",