@provable-games/budokan-sdk 0.1.22 → 0.1.24

package/dist/react.d.cts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { i as BudokanClientConfig, B as BudokanClient, T as Tournament, b as PaginatedResult, e as TournamentListParams, m as Phase, l as LeaderboardEntry, R as Registration, c as RewardClaim, d as RewardClaimSummary, g as PrizeStats, a as Prize, P as PrizeAggregation, Q as QualificationEntry, f as PlatformStats, o as WSEventMessage, n as WSChannel, C as ConnectionMode } from './client-DlXvzneQ.cjs';
+import { i as BudokanClientConfig, B as BudokanClient, T as Tournament, b as PaginatedResult, e as TournamentListParams, m as Phase, l as LeaderboardEntry, R as Registration, c as RewardClaim, d as RewardClaimSummary, g as PrizeStats, a as Prize, P as PrizeAggregation, Q as QualificationEntry, f as PlatformStats, o as PlayerRewards, q as WSEventMessage, p as WSChannel, C as ConnectionMode } from './player-C2GE9Lop.cjs';
 import 'starknet';
 import '@provable-games/metagame-sdk';
 
@@ -200,6 +200,49 @@ interface UseActivityStatsResult {
  */
 declare function useActivityStats(): UseActivityStatsResult;
 
+interface UsePlayerRewardsResult {
+    rewards: PlayerRewards | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Aggregate a player's placement/earnings data across finalized Budokan
+ * tournaments they currently hold tokens in.
+ *
+ * Composition:
+ *
+ *   denshokan useTokens (current ownership)
+ *     ↓ group by contextId (= tournament id)
+ *   budokan useTournaments({ tournamentIds })
+ *     ↓ filter to finalized
+ *   for each finalized tournament (parallel):
+ *     budokan getTournamentPrizes        — full prize records
+ *     budokan getTournamentRewardClaims  — paginated, all pages
+ *     denshokan getTokenRanks (bulk)     — final ranks for owned tokens
+ *     ↓ filter ranks to paid positions  (max position derived from prizes
+ *       + entry-fee distribution_count)
+ *
+ * Per-tournament failures are tolerated: a 5xx on one tournament's prize/
+ * claim/rank fetch skips that tournament and continues, rather than
+ * failing the whole hook. Failures are logged via `console.warn`.
+ *
+ * Why source ownership from denshokan: PR #243 dropped
+ * `registrations.player_address` because the indexed value goes stale on
+ * transfer. The contract keys registrations by token_id only, so the only
+ * trustworthy answer to "what tournaments has this wallet placed in" is
+ * to ask denshokan who currently holds Budokan-minted tokens.
+ *
+ * Staleness: the hook only re-fetches when the player's owned token set
+ * changes (transfers/new mints) or when the underlying tournament list
+ * changes. It does *not* observe time-based finalization transitions on
+ * its own — if a tournament's submission window closes while the
+ * consumer is mounted, call `refetch()` to pick up the new placement.
+ *
+ * Pass `undefined` to skip fetching.
+ */
+declare function usePlayerRewards(address: string | undefined): UsePlayerRewardsResult;
+
 interface UseSubscriptionResult {
     lastMessage: WSEventMessage | null;
     isConnected: boolean;
@@ -223,4 +266,4 @@ declare function useConnectionStatus(): {
     datasourceMode: ConnectionMode;
 };
 
-export { BudokanProvider, type BudokanProviderProps, type UseActivityStatsResult, type UseLeaderboardResult, type UsePrizeAggregationResult, type UsePrizeStatsResult, type UsePrizesResult, type UseQualificationsResult, type UseRegistrationsResult, type UseRewardClaimsResult, type UseRewardClaimsSummaryResult, type UseSubscriptionResult, type UseTournamentCountResult, type UseTournamentResult, type UseTournamentsResult, useActivityStats, useBudokanClient, useConnectionStatus, useLeaderboard, usePrizeAggregation, usePrizeStats, usePrizes, useQualifications, useRegistrations, useRegistrationsByOwner, useRewardClaims, useRewardClaimsSummary, useSubscription, useTournament, useTournamentCount, useTournaments, useTournamentsByOwner, useTournamentsByOwnerCount };
+export { BudokanProvider, type BudokanProviderProps, type UseActivityStatsResult, type UseLeaderboardResult, type UsePlayerRewardsResult, type UsePrizeAggregationResult, type UsePrizeStatsResult, type UsePrizesResult, type UseQualificationsResult, type UseRegistrationsResult, type UseRewardClaimsResult, type UseRewardClaimsSummaryResult, type UseSubscriptionResult, type UseTournamentCountResult, type UseTournamentResult, type UseTournamentsResult, useActivityStats, useBudokanClient, useConnectionStatus, useLeaderboard, usePlayerRewards, usePrizeAggregation, usePrizeStats, usePrizes, useQualifications, useRegistrations, useRegistrationsByOwner, useRewardClaims, useRewardClaimsSummary, useSubscription, useTournament, useTournamentCount, useTournaments, useTournamentsByOwner, useTournamentsByOwnerCount };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { i as BudokanClientConfig, B as BudokanClient, T as Tournament, b as PaginatedResult, e as TournamentListParams, m as Phase, l as LeaderboardEntry, R as Registration, c as RewardClaim, d as RewardClaimSummary, g as PrizeStats, a as Prize, P as PrizeAggregation, Q as QualificationEntry, f as PlatformStats, o as WSEventMessage, n as WSChannel, C as ConnectionMode } from './client-DlXvzneQ.js';
+import { i as BudokanClientConfig, B as BudokanClient, T as Tournament, b as PaginatedResult, e as TournamentListParams, m as Phase, l as LeaderboardEntry, R as Registration, c as RewardClaim, d as RewardClaimSummary, g as PrizeStats, a as Prize, P as PrizeAggregation, Q as QualificationEntry, f as PlatformStats, o as PlayerRewards, q as WSEventMessage, p as WSChannel, C as ConnectionMode } from './player-C2GE9Lop.js';
 import 'starknet';
 import '@provable-games/metagame-sdk';
 
@@ -200,6 +200,49 @@ interface UseActivityStatsResult {
  */
 declare function useActivityStats(): UseActivityStatsResult;
 
+interface UsePlayerRewardsResult {
+    rewards: PlayerRewards | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Aggregate a player's placement/earnings data across finalized Budokan
+ * tournaments they currently hold tokens in.
+ *
+ * Composition:
+ *
+ *   denshokan useTokens (current ownership)
+ *     ↓ group by contextId (= tournament id)
+ *   budokan useTournaments({ tournamentIds })
+ *     ↓ filter to finalized
+ *   for each finalized tournament (parallel):
+ *     budokan getTournamentPrizes        — full prize records
+ *     budokan getTournamentRewardClaims  — paginated, all pages
+ *     denshokan getTokenRanks (bulk)     — final ranks for owned tokens
+ *     ↓ filter ranks to paid positions  (max position derived from prizes
+ *       + entry-fee distribution_count)
+ *
+ * Per-tournament failures are tolerated: a 5xx on one tournament's prize/
+ * claim/rank fetch skips that tournament and continues, rather than
+ * failing the whole hook. Failures are logged via `console.warn`.
+ *
+ * Why source ownership from denshokan: PR #243 dropped
+ * `registrations.player_address` because the indexed value goes stale on
+ * transfer. The contract keys registrations by token_id only, so the only
+ * trustworthy answer to "what tournaments has this wallet placed in" is
+ * to ask denshokan who currently holds Budokan-minted tokens.
+ *
+ * Staleness: the hook only re-fetches when the player's owned token set
+ * changes (transfers/new mints) or when the underlying tournament list
+ * changes. It does *not* observe time-based finalization transitions on
+ * its own — if a tournament's submission window closes while the
+ * consumer is mounted, call `refetch()` to pick up the new placement.
+ *
+ * Pass `undefined` to skip fetching.
+ */
+declare function usePlayerRewards(address: string | undefined): UsePlayerRewardsResult;
+
 interface UseSubscriptionResult {
     lastMessage: WSEventMessage | null;
     isConnected: boolean;
@@ -223,4 +266,4 @@ declare function useConnectionStatus(): {
     datasourceMode: ConnectionMode;
 };
 
-export { BudokanProvider, type BudokanProviderProps, type UseActivityStatsResult, type UseLeaderboardResult, type UsePrizeAggregationResult, type UsePrizeStatsResult, type UsePrizesResult, type UseQualificationsResult, type UseRegistrationsResult, type UseRewardClaimsResult, type UseRewardClaimsSummaryResult, type UseSubscriptionResult, type UseTournamentCountResult, type UseTournamentResult, type UseTournamentsResult, useActivityStats, useBudokanClient, useConnectionStatus, useLeaderboard, usePrizeAggregation, usePrizeStats, usePrizes, useQualifications, useRegistrations, useRegistrationsByOwner, useRewardClaims, useRewardClaimsSummary, useSubscription, useTournament, useTournamentCount, useTournaments, useTournamentsByOwner, useTournamentsByOwnerCount };
+export { BudokanProvider, type BudokanProviderProps, type UseActivityStatsResult, type UseLeaderboardResult, type UsePlayerRewardsResult, type UsePrizeAggregationResult, type UsePrizeStatsResult, type UsePrizesResult, type UseQualificationsResult, type UseRegistrationsResult, type UseRewardClaimsResult, type UseRewardClaimsSummaryResult, type UseSubscriptionResult, type UseTournamentCountResult, type UseTournamentResult, type UseTournamentsResult, useActivityStats, useBudokanClient, useConnectionStatus, useLeaderboard, usePlayerRewards, usePrizeAggregation, usePrizeStats, usePrizes, useQualifications, useRegistrations, useRegistrationsByOwner, useRewardClaims, useRewardClaimsSummary, useSubscription, useTournament, useTournamentCount, useTournaments, useTournamentsByOwner, useTournamentsByOwnerCount };