@provable-games/budokan-sdk 0.1.2 → 0.1.4

package/README.md

@@ -120,26 +120,46 @@ interface BudokanClientConfig {
 
 ## Data Source Fallback
 
-The SDK monitors API and RPC health in the background. When the API goes down, methods with RPC fallback automatically switch to direct contract calls. When the API recovers, it switches back.
-
-| Method | API | RPC | Fallback |
-|--------|-----|-----|----------|
-| `getTournaments(params?)` | Yes | Yes | Yes |
-| `getTournament(id)` | Yes | Yes | Yes |
-| `getTournamentLeaderboard(id)` | Yes | Yes | Yes |
-| `getTournamentRegistrations(id)` | Yes | Yes | Yes |
-| `getTournamentPrizes(id)` | Yes | Yes | Yes |
-| `getGameTournaments(addr)` | Yes | Yes | Yes |
-| `getTournamentRewardClaims(id)` | Yes | — | API only |
-| `getTournamentRewardClaimsSummary(id)` | Yes | — | API only |
-| `getTournamentQualifications(id)` | Yes | — | API only |
-| `getTournamentPrizeAggregation(id)` | Yes | — | API only |
-| `getPlayerTournaments(addr)` | Yes | — | API only |
-| `getPlayerStats(addr)` | Yes | — | API only |
-| `getGameStats(addr)` | Yes | — | API only |
-| `getActivity(params?)` | Yes | — | API only |
-| `getActivityStats()` | Yes | — | API only |
-| `getPrizeStats()` | Yes | — | API only |
+The SDK supports two data sources: **API** (REST indexer) and **RPC** (direct Starknet contract calls via BudokanViewer). Set `primarySource: "api"` (default) or `primarySource: "rpc"` in config. When the API goes down, methods with RPC support automatically fall back to direct contract calls.
+
+### Feature Support
+
+| Method | API | RPC | Notes |
+|--------|:---:|:---:|-------|
+| **Tournaments** | | | |
+| `getTournaments(params?)` | ✅ | ✅ | RPC groups phases: `scheduled` includes Scheduled+Registration+Staging, `live` includes Live+Submission |
+| `getTournament(id)` | ✅ | ✅ | |
+| `getTournamentLeaderboard(id)` | ✅ | ✅ | |
+| `getTournamentRegistrations(id)` | ✅ | ✅ | RPC: `playerAddress` and `gameAddress` fields will be empty |
+| `getTournamentPrizes(id)` | ✅ | ✅ | |
+| `getGameTournaments(addr)` | ✅ | ✅ | |
+| **Prize Aggregation** | | | |
+| `getTournamentPrizeAggregation(id)` | ✅ | ❌ | API only |
+| `includePrizeSummary` param | ✅ | ✅ | RPC fetches prizes per tournament and builds aggregation client-side |
+| **Rewards** | | | |
+| `getTournamentRewardClaims(id)` | ✅ | ✅ | RPC checks `is_prize_claimed` per prize via viewer |
+| `getTournamentRewardClaimsSummary(id)` | ✅ | ✅ | RPC returns totals from viewer |
+| `getTournamentQualifications(id)` | ✅ | ⚠️ | On-chain via `get_qualification_entries` — requires proof input, not yet wired |
+| **Players** | | | |
+| `getPlayerTournaments(addr)` | ✅ | ✅ | RPC iterates tournaments and checks entry ownership via ERC721 |
+| `getPlayerStats(addr)` | ✅ | ❌ | API only — requires aggregated stats |
+| **Games** | | | |
+| `getGameStats(addr)` | ✅ | ❌ | API only — requires aggregated stats |
+| **Activity** | | | |
+| `getActivity(params?)` | ✅ | ❌ | API only — activity is indexed from events |
+| `getActivityStats()` | ✅ | ❌ | API only — requires aggregated stats |
+| `getPrizeStats()` | ✅ | ❌ | API only — requires aggregated stats |
+| **WebSocket** | | | |
+| `subscribe(channels, handler)` | ✅ | ❌ | Requires API WebSocket server |
+
+### RPC Behaviour
+
+When `primarySource: "rpc"`:
+- All tournament queries go directly to the **BudokanViewer** contract — no API calls
+- Phase filtering uses `tournaments_by_phases` for grouped queries (e.g., "scheduled" queries 3 phases in 1 RPC call)
+- Prize aggregation for tournament cards is built client-side from per-tournament prize data
+- API-only methods will throw an error — they require the indexed API
+- Stale data is automatically cleared when switching networks
 
 ## API Reference
 
@@ -193,10 +213,10 @@ Error classes: `BudokanError`, `BudokanApiError`, `BudokanTimeoutError`, `Budoka
 ## Development
 
 ```bash
-npm install
-npm run build        # ESM + CJS to dist/
-npm run typecheck    # TypeScript validation
-npm run dev          # Watch mode
+bun install
+bun run build        # ESM + CJS to dist/
+bun run typecheck    # TypeScript validation
+bun run dev          # Watch mode
 ```
 
 ## Publishing

package/dist/{client-BtC3ngNe.d.cts → client-eg3Ink5N.d.cts}

@@ -1,10 +1,13 @@
+import { RpcProvider } from 'starknet';
+import { EntryFee, EntryRequirement, QualificationProof } from '@provable-games/metagame-sdk';
+
 type DataSource = "api" | "rpc";
 interface BudokanClientConfig {
     apiBaseUrl: string;
     wsUrl?: string;
     rpcUrl?: string;
     chain?: "mainnet" | "sepolia";
-    provider?: unknown;
+    provider?: RpcProvider;
     viewerAddress?: string;
     budokanAddress?: string;
     primarySource?: DataSource;
@@ -52,7 +55,7 @@ interface Tournament {
     schedule: Schedule | null;
     gameConfig: GameConfig | null;
     entryFee: EntryFee | null;
-    entryRequirement: unknown | null;
+    entryRequirement: EntryRequirement | null;
     leaderboardConfig: LeaderboardConfig | null;
     entryCount: number;
     prizeCount: number;
@@ -64,7 +67,7 @@ interface Tournament {
         totalAmount: string;
         nftCount: number;
     }>;
-    metadata: unknown | null;
+    metadata: Record<string, unknown> | null;
 }
 interface Schedule {
     registrationStartDelay: number;
@@ -81,15 +84,6 @@ interface GameConfig {
     clientUrl: string | null;
     renderer: string | null;
 }
-interface EntryFee {
-    tokenAddress: string;
-    amount: string;
-    tournamentCreatorShare: number;
-    gameCreatorShare: number;
-    refundShare: number;
-    distribution: unknown;
-    distributionCount: number;
-}
 interface LeaderboardConfig {
     ascending: boolean;
     gameMustBeOver: boolean;
@@ -109,7 +103,7 @@ interface TournamentListParams {
 }
 interface QualificationEntry {
     tournamentId: string;
-    qualificationProof: unknown;
+    qualificationProof: QualificationProof | null;
     entryCount: number;
 }
 
@@ -128,6 +122,23 @@ interface Registration {
     isBanned: boolean;
 }
 
+type RewardType = {
+    Prize: {
+        tokenAddress: string;
+        tokenType: string;
+    };
+} | {
+    EntryFee: EntryFeeRewardType;
+};
+type EntryFeeRewardType = {
+    Position: number;
+} | {
+    TournamentCreator: Record<string, never>;
+} | {
+    GameCreator: Record<string, never>;
+} | {
+    Refund: string;
+};
 interface Prize {
     prizeId: string;
     tournamentId: string;
@@ -143,7 +154,7 @@ interface Prize {
 }
 interface RewardClaim {
     tournamentId: string;
-    rewardType: unknown;
+    rewardType: RewardType;
     claimed: boolean;
 }
 interface PrizeAggregation {
@@ -177,7 +188,7 @@ interface ActivityEvent {
     eventType: string;
     tournamentId: string | null;
     playerAddress: string | null;
-    data: unknown;
+    data: Record<string, unknown>;
     blockNumber: string;
     txHash: string;
     eventIndex: number;
@@ -224,7 +235,7 @@ interface WSUnsubscribeMessage {
 interface WSEventMessage {
     type: "event";
     channel: WSChannel;
-    data: unknown;
+    data: Record<string, unknown>;
     timestamp: string;
 }
 type WSMessage = WSSubscribeMessage | WSUnsubscribeMessage | WSEventMessage;
@@ -358,7 +369,7 @@ declare class BudokanClient {
     getTournamentPrizes(tournamentId: string): Promise<Prize[]>;
     /**
      * Fetch tournaments that a player has registered for.
-     * API-only — no RPC fallback available.
+     * Supports RPC fallback via viewer contract.
      */
     getPlayerTournaments(address: string, params?: PlayerTournamentParams): Promise<PaginatedResult<PlayerTournament>>;
     /**
@@ -378,7 +389,7 @@ declare class BudokanClient {
     getGameStats(gameAddress: string): Promise<PlatformStats>;
     /**
      * Fetch reward claims for a tournament.
-     * API-only -- no RPC fallback available.
+     * Supports RPC fallback via viewer contract.
      */
     getTournamentRewardClaims(tournamentId: string, params?: {
         limit?: number;
@@ -386,7 +397,7 @@ declare class BudokanClient {
     }): Promise<PaginatedResult<RewardClaim>>;
     /**
      * Fetch reward claims summary for a tournament.
-     * API-only -- no RPC fallback available.
+     * Supports RPC fallback via viewer contract.
      */
     getTournamentRewardClaimsSummary(tournamentId: string): Promise<RewardClaimSummary>;
     /**
@@ -445,4 +456,4 @@ declare class BudokanClient {
  */
 declare function createBudokanClient(config: BudokanClientConfig): BudokanClient;
 
-export { type ActivityParams as A, BudokanClient as B, type ConnectionMode as C, type DataSource as D, type EntryFee as E, type GameConfig as G, type LeaderboardEntry as L, type PrizeAggregation as P, type QualificationEntry as Q, type Registration as R, type Schedule as S, type Tournament as T, type WSSubscribeOptions as W, type Prize as a, type PaginatedResult as b, type RewardClaim as c, type RewardClaimSummary as d, type TournamentListParams as e, type PlayerStats as f, type PlayerTournamentParams as g, type PlayerTournament as h, type PlatformStats as i, type ActivityEvent as j, type PrizeStats as k, type WSEventHandler as l, type BudokanClientConfig as m, ConnectionStatus as n, type ConnectionStatusState as o, type LeaderboardConfig as p, type Phase as q, type WSChannel as r, type WSEventMessage as s, type WSMessage as t, type WSSubscribeMessage as u, type WSUnsubscribeMessage as v, createBudokanClient as w };
+export { type ActivityParams as A, BudokanClient as B, type ConnectionMode as C, type DataSource as D, type GameConfig as G, type LeaderboardEntry as L, type PrizeAggregation as P, type QualificationEntry as Q, type Registration as R, type Schedule as S, type Tournament as T, type WSSubscribeOptions as W, type Prize as a, type PaginatedResult as b, type RewardClaim as c, type RewardClaimSummary as d, type TournamentListParams as e, type PlayerStats as f, type PlayerTournamentParams as g, type PlayerTournament as h, type PlatformStats as i, type ActivityEvent as j, type PrizeStats as k, type WSEventHandler as l, type BudokanClientConfig as m, ConnectionStatus as n, type ConnectionStatusState as o, type LeaderboardConfig as p, type Phase as q, type WSChannel as r, type WSEventMessage as s, type WSMessage as t, type WSSubscribeMessage as u, type WSUnsubscribeMessage as v, createBudokanClient as w };

package/dist/{client-BtC3ngNe.d.ts → client-eg3Ink5N.d.ts}

@@ -1,10 +1,13 @@
+import { RpcProvider } from 'starknet';
+import { EntryFee, EntryRequirement, QualificationProof } from '@provable-games/metagame-sdk';
+
 type DataSource = "api" | "rpc";
 interface BudokanClientConfig {
     apiBaseUrl: string;
     wsUrl?: string;
     rpcUrl?: string;
     chain?: "mainnet" | "sepolia";
-    provider?: unknown;
+    provider?: RpcProvider;
     viewerAddress?: string;
     budokanAddress?: string;
     primarySource?: DataSource;
@@ -52,7 +55,7 @@ interface Tournament {
     schedule: Schedule | null;
     gameConfig: GameConfig | null;
     entryFee: EntryFee | null;
-    entryRequirement: unknown | null;
+    entryRequirement: EntryRequirement | null;
     leaderboardConfig: LeaderboardConfig | null;
     entryCount: number;
     prizeCount: number;
@@ -64,7 +67,7 @@ interface Tournament {
         totalAmount: string;
         nftCount: number;
     }>;
-    metadata: unknown | null;
+    metadata: Record<string, unknown> | null;
 }
 interface Schedule {
     registrationStartDelay: number;
@@ -81,15 +84,6 @@ interface GameConfig {
     clientUrl: string | null;
     renderer: string | null;
 }
-interface EntryFee {
-    tokenAddress: string;
-    amount: string;
-    tournamentCreatorShare: number;
-    gameCreatorShare: number;
-    refundShare: number;
-    distribution: unknown;
-    distributionCount: number;
-}
 interface LeaderboardConfig {
     ascending: boolean;
     gameMustBeOver: boolean;
@@ -109,7 +103,7 @@ interface TournamentListParams {
 }
 interface QualificationEntry {
     tournamentId: string;
-    qualificationProof: unknown;
+    qualificationProof: QualificationProof | null;
     entryCount: number;
 }
 
@@ -128,6 +122,23 @@ interface Registration {
     isBanned: boolean;
 }
 
+type RewardType = {
+    Prize: {
+        tokenAddress: string;
+        tokenType: string;
+    };
+} | {
+    EntryFee: EntryFeeRewardType;
+};
+type EntryFeeRewardType = {
+    Position: number;
+} | {
+    TournamentCreator: Record<string, never>;
+} | {
+    GameCreator: Record<string, never>;
+} | {
+    Refund: string;
+};
 interface Prize {
     prizeId: string;
     tournamentId: string;
@@ -143,7 +154,7 @@ interface Prize {
 }
 interface RewardClaim {
     tournamentId: string;
-    rewardType: unknown;
+    rewardType: RewardType;
     claimed: boolean;
 }
 interface PrizeAggregation {
@@ -177,7 +188,7 @@ interface ActivityEvent {
     eventType: string;
     tournamentId: string | null;
     playerAddress: string | null;
-    data: unknown;
+    data: Record<string, unknown>;
     blockNumber: string;
     txHash: string;
     eventIndex: number;
@@ -224,7 +235,7 @@ interface WSUnsubscribeMessage {
 interface WSEventMessage {
     type: "event";
     channel: WSChannel;
-    data: unknown;
+    data: Record<string, unknown>;
     timestamp: string;
 }
 type WSMessage = WSSubscribeMessage | WSUnsubscribeMessage | WSEventMessage;
@@ -358,7 +369,7 @@ declare class BudokanClient {
     getTournamentPrizes(tournamentId: string): Promise<Prize[]>;
     /**
      * Fetch tournaments that a player has registered for.
-     * API-only — no RPC fallback available.
+     * Supports RPC fallback via viewer contract.
      */
     getPlayerTournaments(address: string, params?: PlayerTournamentParams): Promise<PaginatedResult<PlayerTournament>>;
     /**
@@ -378,7 +389,7 @@ declare class BudokanClient {
     getGameStats(gameAddress: string): Promise<PlatformStats>;
     /**
      * Fetch reward claims for a tournament.
-     * API-only -- no RPC fallback available.
+     * Supports RPC fallback via viewer contract.
      */
     getTournamentRewardClaims(tournamentId: string, params?: {
         limit?: number;
@@ -386,7 +397,7 @@ declare class BudokanClient {
     }): Promise<PaginatedResult<RewardClaim>>;
     /**
      * Fetch reward claims summary for a tournament.
-     * API-only -- no RPC fallback available.
+     * Supports RPC fallback via viewer contract.
      */
     getTournamentRewardClaimsSummary(tournamentId: string): Promise<RewardClaimSummary>;
     /**
@@ -445,4 +456,4 @@ declare class BudokanClient {
  */
 declare function createBudokanClient(config: BudokanClientConfig): BudokanClient;
 
-export { type ActivityParams as A, BudokanClient as B, type ConnectionMode as C, type DataSource as D, type EntryFee as E, type GameConfig as G, type LeaderboardEntry as L, type PrizeAggregation as P, type QualificationEntry as Q, type Registration as R, type Schedule as S, type Tournament as T, type WSSubscribeOptions as W, type Prize as a, type PaginatedResult as b, type RewardClaim as c, type RewardClaimSummary as d, type TournamentListParams as e, type PlayerStats as f, type PlayerTournamentParams as g, type PlayerTournament as h, type PlatformStats as i, type ActivityEvent as j, type PrizeStats as k, type WSEventHandler as l, type BudokanClientConfig as m, ConnectionStatus as n, type ConnectionStatusState as o, type LeaderboardConfig as p, type Phase as q, type WSChannel as r, type WSEventMessage as s, type WSMessage as t, type WSSubscribeMessage as u, type WSUnsubscribeMessage as v, createBudokanClient as w };
+export { type ActivityParams as A, BudokanClient as B, type ConnectionMode as C, type DataSource as D, type GameConfig as G, type LeaderboardEntry as L, type PrizeAggregation as P, type QualificationEntry as Q, type Registration as R, type Schedule as S, type Tournament as T, type WSSubscribeOptions as W, type Prize as a, type PaginatedResult as b, type RewardClaim as c, type RewardClaimSummary as d, type TournamentListParams as e, type PlayerStats as f, type PlayerTournamentParams as g, type PlayerTournament as h, type PlatformStats as i, type ActivityEvent as j, type PrizeStats as k, type WSEventHandler as l, type BudokanClientConfig as m, ConnectionStatus as n, type ConnectionStatusState as o, type LeaderboardConfig as p, type Phase as q, type WSChannel as r, type WSEventMessage as s, type WSMessage as t, type WSSubscribeMessage as u, type WSUnsubscribeMessage as v, createBudokanClient as w };