[SDK] Add React hooks package (@stellarmind/react)

[IyanuOluwaJesuloba]

Title: [SDK] Add React hooks package (@stellarmind/react)

Summary

dashboard/src/hooks/ exists but is completely empty. There are no React hooks for consuming the StellarMind SDK. This issue creates a @stellarmind/react package with production-ready hooks that make it trivial for any React developer to integrate StellarMind into their app.

Current State

dashboard/src/hooks/
├── useRegistry.ts    ← DOES NOT EXIST
└── usePolicy.ts      ← DOES NOT EXIST

These are referenced in the README architecture section but have never been created.

What Needs to Be Built

Create a new package at packages/react/ (or add to sdk/src/react/) with the following hooks:

useAgent(id: string)

ts

const { agent, loading, error, refetch } = useAgent('flux-image-gen-v1')

Fetches a single agent by ID on mount

Returns loading state while fetching

Returns typed Agent | null

refetch() re-fetches from chain

useAgentSearch(params: FindAgentsParams)

ts

const { agents, loading, error } = useAgentSearch({
  capability: 'image-generation',
  maxPrice: '0.05',
  activeOnly: true,
})

Re-fetches automatically when params changes

Returns Agent[]

useAgentCount()

ts

const { count, loading } = useAgentCount()
// count: bigint

usePolicy(policyId: bigint)

ts

const { policy, loading, error, refetch } = usePolicy(1n)

Fetches a single policy by ID

Returns typed SpendingPolicy | null

useRemainingAllowance(policyId: bigint)

ts

const { allowance, display, loading } = useRemainingAllowance(1n)
// allowance: bigint (in stroops)
// display: "8.5000000 USDC"

Auto-refreshes every 30 seconds

useStellarMind(config: StellarMindConfig)

ts

const mind = useStellarMind({ network: 'testnet' })

Returns a memoized StellarMind instance

Recreates the instance only when config changes

Use React context so all hooks share one instance

Context Provider

All hooks should read from a shared context. Create a StellarMindProvider:

tsx

// In the app root:
<StellarMindProvider config={{ network: 'testnet' }}>
  <App />
</StellarMindProvider>

// Then in any component:
const { agents } = useAgentSearch({ capability: 'text-generation' })

Relevant Files

• dashboard/src/hooks/useRegistry.ts: Create — export useAgent, useAgentSearch,
• useAgentCountdashboard/src/hooks/usePolicy.ts: Create — export usePolicy, useRemainingAllowance
• dashboard/src/lib/stellarmind.ts: Create — export StellarMindProvider, useStellarMind
• dashboard/src/App.tsx: Wrap app in StellarMindProvider
• dashboard/src/components/AgentExplorer.tsx: Refactor to use useAgentSearch hook

Acceptance Criteria

All 6 hooks implemented with correct TypeScript types

StellarMindProvider and useStellarMind context implemented

All hooks handle loading, error, and success states

useRemainingAllowance auto-refreshes every 30 seconds

AgentExplorer.tsx refactored to use useAgentSearch (removes mock data)

Each hook is documented with a JSDoc comment and usage example

No any types anywhere

Estimated Effort

Medium (6–10 hours)

[BeisenbekAbai]

Hey @IyanuOluwaJesuloba! I'd love to take ownership of this issue.

I took a look at the current implementation in dashboard/src/hooks/useRegistry.ts. I see the internal hooks are currently relying on a global getProxima() and are tightly coupled with dashboard mock data (MockAgent).

I can extract this logic into a clean, standalone React package (using Context/Provider as requested, dropping the internal mocks, and adding the 30s polling for useRemainingAllowance).

Two quick architecture questions before I draft the PR:

The repo is named Proxima, but the issue mentions @stellarmind/react and StellarMindProvider. Should I stick to the Proxima naming convention (e.g., ProximaProvider)?

Should I scaffold the new package inside a new packages/react/ workspace directory, or inside sdk/src/react/?

Let me know and I'll get started!