Custom Data Fetching Hooks

Relevant source files

The following files were used as context for generating this wiki page:

• hooks/useSlackTags.ts
• hooks/useContentSlackTags.ts
• hooks/useCodingPrStatus.ts
• hooks/useAdminSandboxOrgs.ts
• hooks/useAdminSandboxes.ts
• lib/recoup/fetchSlackTags.ts
• lib/recoup/fetchCodingPrStatus.ts
• lib/recoup/fetchContentSlackTags.ts

The Recoup Admin dashboard utilizes a standardized pattern for data fetching, leveraging TanStack Query (React Query) and Privy for authentication. These custom hooks encapsulate the logic for retrieving administrative data from various internal API endpoints, ensuring that requests are only made when the user is authenticated and the necessary access tokens are available.

The hooks are primarily responsible for managing state related to loading, error handling, and data caching for features such as Coding Agent analytics, Content Agent usage, and sandbox environment statistics.

Architecture and Data Flow

The data fetching architecture follows a layered approach: UI components call custom hooks, which in turn use library functions to perform the actual HTTP requests.

Authentication Integration

Every custom data fetching hook integrates with the @privy-io/react-auth package to manage secure access to administrative endpoints. The hooks utilize the usePrivy hook to check the authentication state and retrieve the getAccessToken function.

Key logic included in these hooks:

• Ready State: Checking if the Privy SDK is initialized (ready).
• Authentication Check: Verifying the user is logged in (authenticated).
• Token Retrieval: Calling getAccessToken() to provide a Bearer token for the Authorization header.
• Conditional Execution: The enabled flag in TanStack Query prevents requests from firing until the authentication requirements are met.

Sources: hooks/useAdminSandboxes.ts:12-21, hooks/useAdminSandboxOrgs.ts:12-22

Core Fetching Hooks

The project implements several hooks tailored to specific administrative domains.

Slack Analytics Hooks

These hooks track interactions with AI agents within Slack.

Hook Name	Endpoint	Purpose
useSlackTags	/api/admins/coding/slack	Fetches tagging analytics for the Coding Agent for a specific time period.
useContentSlackTags	/api/admins/content/slack	Retrieves usage statistics for the Content Agent.
useCodingPrStatus	/api/admins/coding/pr	Checks the merged status of GitHub PRs mentioned in Slack tags.

Sources: hooks/useSlackTags.ts:13-23, hooks/useContentSlackTags.ts:8-18, hooks/useCodingPrStatus.ts:13-28

Infrastructure Hooks

These hooks provide insights into the platform's sandbox environments and repository activity.

• useAdminSandboxes: Fetches account sandbox statistics.
  • Source: hooks/useAdminSandboxes.ts:11-23
• useAdminSandboxOrgs: Retrieves repository commit statistics for organization sub-modules.
  • Source: hooks/useAdminSandboxOrgs.ts:11-23

Advanced Data Transformation: useCodingPrStatus

Unlike standard fetching hooks, useCodingPrStatus performs significant client-side data transformation. It accepts an array of SlackTag objects, extracts unique Pull Request URLs, and queries the backend for their status. The resulting data is transformed into a Set of merged PR URLs for $O(1)$ lookup performance in UI components.

Implementation Patterns

Request Parameter Handling

Hooks often pass parameters to library functions to filter data. For example, useSlackTags and useContentSlackTags utilize an AdminPeriod ("all", "daily", "weekly", "monthly") which is appended as a search parameter in the underlying fetch call.

// Example from lib/recoup/fetchContentSlackTags.ts
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}` },
});

Sources: lib/recoup/fetchContentSlackTags.ts:10-18, lib/recoup/fetchSlackTags.ts:16-24

Error Handling

The fetching library functions include robust error handling that attempts to parse error messages from the JSON response body before falling back to a generic HTTP status error.

Sources: lib/recoup/fetchSlackTags.ts:26-29, lib/recoup/fetchCodingPrStatus.ts:31-34

Summary

The custom data fetching hooks in this project provide a consistent, authenticated, and type-safe interface for the Admin dashboard. By abstracting the complexity of token management and query lifecycle via TanStack Query and Privy, they allow UI components to focus on rendering data while maintaining strict security requirements.