@sudobility/heavymath_indexer_client 0.0.18 → 0.0.19

package/README.md

@@ -1,380 +1,83 @@
-# @heavymath/indexer_client
+# @sudobility/heavymath_indexer_client
 
-TypeScript client library for the Heavymath Prediction Market Indexer API. Provides React hooks, business services, and low-level API clients for querying prediction market data.
-
-## Features
-
-- **Full API Coverage** - All REST endpoints supported
-- **React Hooks** - Built-in hooks using @tanstack/react-query
-- **Business Services** - High-level services with caching
-- **Network Layer** - Low-level API client for custom integrations
-- **TypeScript First** - Full type definitions included
-- **React Native Compatible** - Works in React Native environments
-- **Dependency Injection** - Uses NetworkClient from @sudobility/di
+React and React Native compatible client library for the Heavymath prediction market indexer API. Provides a four-layer architecture (hooks, stores, business, network) with React Query integration, Zustand stores for optimistic updates, and SSE real-time subscriptions.
 
 ## Installation
 
 ```bash
-npm install @heavymath/indexer_client
+bun add @sudobility/heavymath_indexer_client
 ```
 
-## Peer Dependencies
+### Peer Dependencies
 
 ```bash
-npm install react @tanstack/react-query @sudobility/types @sudobility/heavymath_types @sudobility/di
+bun add react @tanstack/react-query zustand @sudobility/types @sudobility/heavymath_types
 ```
 
-## Quick Start
-
-### 1. Setup React Query Provider
+## Usage
 
-```tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+```typescript
+import { IndexerClient, useActiveMarkets, useFavorites } from '@sudobility/heavymath_indexer_client';
 
-const queryClient = new QueryClient();
+// Create client with injected NetworkClient
+const client = new IndexerClient('http://localhost:42069', networkClient);
 
-function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <YourApp />
-    </QueryClientProvider>
-  );
+// Use hooks in React components
+function Dashboard({ wallet }) {
+  const { data: markets } = useActiveMarkets(client, 20);
+  const { favorites, addFavorite, removeFavorite } = useFavorites(client, wallet);
+  // ...
 }
 ```
 
-### 2. Create IndexerClient with NetworkClient
-
-```tsx
-import { useMemo } from 'react';
-import { useNetworkService } from '@sudobility/di'; // Or your DI container
-import { IndexerClient } from '@heavymath/indexer_client';
-
-// Create a hook to provide IndexerClient
-function useIndexerClient() {
-  const networkClient = useNetworkService();
-  return useMemo(
-    () => new IndexerClient('http://localhost:42069', networkClient),
-    [networkClient]
-  );
-}
-```
+## Available Hooks
 
-### 3. Use Hooks in Your Components
+### Markets
+`useMarkets`, `useActiveMarkets`, `useMarket`, `useMarketPredictions`, `useMarketHistory`, `useMarketDetails`
 
-```tsx
-import { useActiveMarkets, useUserPredictions } from '@heavymath/indexer_client';
+### Predictions
+`usePredictions`, `useUserPredictions`, `useActiveBets`, `usePastBets`, `usePrediction`, `useUserBettingHistory`
 
-function BettorDashboard({ wallet }: { wallet: string }) {
-  const client = useIndexerClient();
+### Dealers
+`useDealers`, `useIsDealer`, `useDealerNFTs`, `useDealer`, `useDealerPermissions`, `useDealerMarkets`, `useDealerDashboard`
 
-  const { data: markets, isLoading: marketsLoading } = useActiveMarkets(client, 20);
-  const { data: myBets, isLoading: betsLoading } = useUserPredictions(client, wallet);
+### Withdrawals / Oracle
+`useWithdrawals`, `useDealerWithdrawals`, `useSystemWithdrawals`, `useMarketWithdrawals`, `useOracleRequests`, `useOracleRequest`, `useMarketOracle`
 
-  if (marketsLoading || betsLoading) return <div>Loading...</div>;
+### Favorites (with Zustand optimistic updates)
+`useFavorites`, `useCategoryFavorites`, `useIsFavorite`
 
-  return (
-    <div>
-      <h2>Active Markets</h2>
-      {markets?.data?.map(market => (
-        <MarketCard key={market.id} market={market} />
-      ))}
+### SSE (real-time)
+`useSSE`, `useMarketUpdates`, `useAllMarketUpdates`, `useUserPredictionUpdates`
 
-      <h2>My Bets</h2>
-      {myBets?.data?.map(bet => (
-        <BetCard key={bet.id} bet={bet} />
-      ))}
-    </div>
-  );
-}
-```
+### Stats
+`useMarketStats`, `useHealth`
 
 ## Architecture
 
-The library is organized into three layers:
-
-### 1. Network Layer
-
-Low-level API client that accepts a `NetworkClient` instance.
-
-```tsx
-import type { NetworkClient } from '@sudobility/types';
-import { IndexerClient } from '@heavymath/indexer_client';
-
-// Get NetworkClient from your DI container
-const networkClient: NetworkClient = getNetworkService();
-
-const client = new IndexerClient('http://localhost:42069', networkClient);
-
-// Direct API calls
-const markets = await client.getMarkets({ status: 'Active', limit: 10 });
-const market = await client.getMarket('1-market-123');
-```
-
-### 2. Business Layer
-
-High-level services with caching and business logic.
-
-```tsx
-import type { NetworkClient } from '@sudobility/types';
-import { IndexerService } from '@heavymath/indexer_client';
-
-const networkClient: NetworkClient = getNetworkService();
-
-const service = new IndexerService({
-  indexerUrl: 'http://localhost:42069',
-  networkClient,
-  cacheTTL: 5 * 60 * 1000, // 5 minutes (optional)
-});
-
-// Business methods with caching
-const activeMarkets = await service.getActiveMarkets(20);
-const userPredictions = await service.getUserPredictions('0x123...');
-const dealerDashboard = await service.getDealerDashboard('0x123...');
-```
-
-### 3. Hooks Layer
-
-React hooks using @tanstack/react-query for data fetching.
-
-```tsx
-import { useActiveMarkets, useUserPredictions, useDealerDashboard } from '@heavymath/indexer_client';
-
-// All hooks take IndexerClient as first parameter
-const { data, isLoading, error, refetch } = useActiveMarkets(client, 20);
-```
-
-## Common Use Cases
-
-### Dealer Dashboard
-
-```tsx
-import { useDealerDashboard, useIsDealer } from '@heavymath/indexer_client';
-
-function DealerDashboard({ wallet }: { wallet: string }) {
-  const client = useIndexerClient();
-
-  const { data: isDealer, isLoading: checkingDealer } = useIsDealer(client, wallet);
-  const { nfts, markets, isLoading } = useDealerDashboard(client, wallet);
-
-  if (checkingDealer) return <div>Checking dealer status...</div>;
-  if (!isDealer) return <div>You are not a dealer</div>;
-  if (isLoading) return <div>Loading dashboard...</div>;
-
-  return (
-    <div>
-      <h2>My Dealer NFTs</h2>
-      {nfts.data?.map(nft => (
-        <div key={nft.id}>Token #{nft.tokenId}</div>
-      ))}
-
-      <h2>My Markets</h2>
-      {markets.data?.map(market => (
-        <MarketCard key={market.id} market={market} />
-      ))}
-    </div>
-  );
-}
-```
-
-### Market Details Page
-
-```tsx
-import { useMarketDetails } from '@heavymath/indexer_client';
-
-function MarketPage({ marketId }: { marketId: string }) {
-  const client = useIndexerClient();
-
-  const { market, predictions, history, isLoading, isError } = useMarketDetails(client, marketId);
-
-  if (isLoading) return <div>Loading...</div>;
-  if (isError) return <div>Error loading market</div>;
-
-  return (
-    <div>
-      <h1>{market.data?.data?.title}</h1>
-      <p>{market.data?.data?.description}</p>
-      <p>Status: {market.data?.data?.status}</p>
-
-      <h2>Predictions ({predictions.data?.data?.length || 0})</h2>
-      {predictions.data?.data?.map(pred => (
-        <div key={pred.id}>
-          {pred.userAddress}: {pred.percentage}%
-        </div>
-      ))}
-
-      <h2>State History</h2>
-      {history.data?.data?.map(state => (
-        <div key={state.id}>
-          {state.fromState} → {state.toState}
-        </div>
-      ))}
-    </div>
-  );
-}
 ```
-
-### Wallet Favorites
-
-```tsx
-import { useFavorites } from '@heavymath/indexer_client';
-
-function FavoritesPage({ wallet }: { wallet: string }) {
-  const client = useIndexerClient();
-
-  const { favorites, isLoading, addFavorite, removeFavorite, refresh } = useFavorites(
-    client,
-    wallet
-  );
-
-  const handleAddFavorite = async () => {
-    await addFavorite.mutateAsync({
-      category: 'sports',
-      subcategory: 'soccer',
-      type: 'team',
-      id: 'team-123',
-    });
-  };
-
-  const handleRemoveFavorite = async (id: number) => {
-    await removeFavorite.mutateAsync(id);
-  };
-
-  if (isLoading) return <div>Loading...</div>;
-
-  return (
-    <div>
-      <h2>My Favorites</h2>
-      {favorites.map(fav => (
-        <div key={fav.id}>
-          {fav.category}/{fav.subcategory}: {fav.itemId}
-          <button onClick={() => handleRemoveFavorite(fav.id)}>Remove</button>
-        </div>
-      ))}
-      <button onClick={handleAddFavorite}>Add Favorite</button>
-    </div>
-  );
-}
+Hooks (React Query)  -->  Zustand Stores  -->  Business Layer (caching)  -->  Network Layer (HTTP)
 ```
 
-## Available Hooks
-
-### Market Hooks
-- `useMarkets(client, filters?)` - Get all markets with filtering
-- `useActiveMarkets(client, limit?)` - Get active markets only
-- `useMarket(client, marketId)` - Get specific market
-- `useMarketPredictions(client, marketId)` - Get market's predictions
-- `useMarketHistory(client, marketId)` - Get market's state history
-- `useMarketDetails(client, marketId)` - Get complete market details
-
-### Prediction Hooks
-- `usePredictions(client, filters?)` - Get predictions with filtering
-- `useUserPredictions(client, wallet, filters?)` - Get user's predictions
-- `useActiveBets(client, wallet)` - Get user's active bets
-- `usePastBets(client, wallet)` - Get user's claimed bets
-- `usePrediction(client, predictionId)` - Get specific prediction
-- `useUserBettingHistory(client, wallet)` - Get complete betting history
-
-### Dealer Hooks
-- `useDealers(client, filters?)` - Get dealer NFTs with filtering
-- `useIsDealer(client, wallet)` - Check if wallet is a dealer
-- `useDealerNFTs(client, wallet)` - Get wallet's dealer NFTs
-- `useDealer(client, dealerId)` - Get specific dealer NFT
-- `useDealerPermissions(client, dealerId)` - Get dealer's permissions
-- `useDealerMarkets(client, dealerId)` - Get dealer's markets
-- `useDealerDashboard(client, wallet)` - Get complete dealer dashboard
-
-### Withdrawal Hooks
-- `useWithdrawals(client, filters?)` - Get withdrawals with filtering
-- `useDealerWithdrawals(client, dealer)` - Get dealer's withdrawals
-- `useSystemWithdrawals(client)` - Get system withdrawals
-- `useMarketWithdrawals(client, marketId)` - Get market's withdrawals
-
-### Oracle Hooks
-- `useOracleRequests(client, filters?)` - Get oracle requests with filtering
-- `useOracleRequest(client, requestId)` - Get specific oracle request
-- `useMarketOracle(client, marketId)` - Get market's oracle request
-- `useTimedOutOracleRequests(client)` - Get timed out requests
-- `usePendingOracleRequests(client)` - Get pending requests
-
-### Favorites Hooks
-- `useFavorites(client, wallet, filters?)` - Get favorites with add/remove/refresh
-- `useCategoryFavorites(client, wallet, category)` - Get favorites by category
-- `useIsFavorite(client, wallet, item)` - Check if item is favorited with toggle
-
-### Stats Hooks
-- `useMarketStats(client)` - Get market statistics
-- `useHealth(client)` - Get indexer health status
-
-## API Endpoints
-
-The client supports all REST endpoints:
-
-- **Markets**: `/api/markets`, `/api/markets/:id`, `/api/markets/:id/predictions`, `/api/markets/:id/history`
-- **Predictions**: `/api/predictions`, `/api/predictions/:id`
-- **Dealers**: `/api/dealers`, `/api/dealers/:id`, `/api/dealers/:id/permissions`, `/api/dealers/:id/markets`
-- **Withdrawals**: `/api/withdrawals`
-- **Oracle**: `/api/oracle/requests`, `/api/oracle/requests/:id`
-- **Favorites**: `/api/wallet/:address/favorites` (GET, POST, DELETE)
-- **Analytics**: `/api/stats/markets`, `/api/health`
-
-## TypeScript Support
-
-Full TypeScript definitions included:
-
-```tsx
-import type {
-  // Core types (from @sudobility/heavymath_types)
-  MarketData,
-  PredictionData,
-  DealerNftData,
-  DealerPermissionData,
-  MarketStateHistoryData,
-  FeeWithdrawalData,
-  OracleRequestData,
-  WalletFavoriteData,
-  CreateFavoriteRequest,
-  // Enums
-  MarketStatus,
-  ClaimType,
-  WithdrawalType,
-  // Response wrappers (from @sudobility/types)
-  ApiResponse,
-  PaginatedResponse,
-  NetworkClient,
-  // Filter types
-  MarketFilters,
-  PredictionFilters,
-  DealerFilters,
-  WithdrawalFilters,
-  OracleFilters,
-  WalletFavoritesFilters,
-} from '@heavymath/indexer_client';
-```
+All hooks accept `IndexerClient` as their first parameter. SSE hooks accept an endpoint URL.
 
 ## Development
 
 ```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Type check
-npm run typecheck
+bun run build        # Compile TypeScript to dist/
+bun run typecheck    # Type validation
+bun run test:run     # Run tests once
+bun run lint         # ESLint check
+bun run check-all    # Lint + typecheck + tests
+```
 
-# Lint
-npm run lint
+## Related Packages
 
-# Format
-npm run format
-
-# Run all checks
-npm run check-all
-```
+- `@sudobility/heavymath_types` -- shared type definitions
+- `@sudobility/heavymath_indexer` -- the backend indexer this client connects to
+- `@sudobility/heavymath_lib` -- business logic hooks
+- `heavymath_app` -- frontend web application
 
 ## License
 
-BUSL 1.1 - Business Use Source License
-
-Copyright (c) 2025 Sudobility Inc.
+BUSL-1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudobility/heavymath_indexer_client",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "description": "React and React Native compatible client library for Heavymath prediction market indexer API with TypeScript support",
   "type": "module",
   "main": "dist/index.js",
@@ -42,15 +42,15 @@
   "author": "John Huang",
   "license": "BUSL-1.1",
   "peerDependencies": {
-    "@sudobility/heavymath_types": "^0.0.10",
-    "@sudobility/types": "^1.9.55",
+    "@sudobility/heavymath_types": "^0.0.11",
+    "@sudobility/types": "^1.9.57",
     "@tanstack/react-query": ">=5.0.0",
     "react": ">=18.0.0",
     "zustand": "^5.0.0"
   },
   "devDependencies": {
-    "@sudobility/heavymath_types": "^0.0.10",
-    "@sudobility/types": "^1.9.55",
+    "@sudobility/heavymath_types": "^0.0.11",
+    "@sudobility/types": "^1.9.57",
     "@tanstack/react-query": "^5.90.5",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",