@provable-games/budokan-sdk 0.1.0 → 0.1.1

package/dist/client-BtC3ngNe.d.cts

@@ -0,0 +1,448 @@
+type DataSource = "api" | "rpc";
+interface BudokanClientConfig {
+    apiBaseUrl: string;
+    wsUrl?: string;
+    rpcUrl?: string;
+    chain?: "mainnet" | "sepolia";
+    provider?: unknown;
+    viewerAddress?: string;
+    budokanAddress?: string;
+    primarySource?: DataSource;
+    retryAttempts?: number;
+    retryDelay?: number;
+    timeout?: number;
+    health?: {
+        initialCheckDelay?: number;
+        checkInterval?: number;
+        checkTimeout?: number;
+    };
+}
+
+interface Tournament {
+    id: string;
+    /** @deprecated Use `id` instead */
+    tournamentId: string;
+    gameAddress: string;
+    createdAt: string;
+    createdBy: string;
+    creatorTokenId: string | null;
+    name: string;
+    description: string;
+    registrationStartDelay: number | null;
+    registrationEndDelay: number | null;
+    gameStartDelay: number | null;
+    gameEndDelay: number | null;
+    submissionDuration: number | null;
+    createdAtOnchain: string | null;
+    registrationStartTime: string | null;
+    registrationEndTime: string | null;
+    gameStartTime: string | null;
+    gameEndTime: string | null;
+    submissionEndTime: string | null;
+    settingsId: number | null;
+    soulbound: boolean | null;
+    paymaster: boolean | null;
+    clientUrl: string | null;
+    renderer: string | null;
+    leaderboardAscending: boolean | null;
+    leaderboardGameMustBeOver: boolean | null;
+    entryFeeToken: string | null;
+    entryFeeAmount: string | null;
+    hasEntryRequirement: boolean | null;
+    schedule: Schedule | null;
+    gameConfig: GameConfig | null;
+    entryFee: EntryFee | null;
+    entryRequirement: unknown | null;
+    leaderboardConfig: LeaderboardConfig | null;
+    entryCount: number;
+    prizeCount: number;
+    submissionCount: number;
+    paidPlaces?: number;
+    prizeAggregation?: Array<{
+        tokenAddress: string;
+        tokenType: string;
+        totalAmount: string;
+        nftCount: number;
+    }>;
+    metadata: unknown | null;
+}
+interface Schedule {
+    registrationStartDelay: number;
+    registrationEndDelay: number;
+    gameStartDelay: number;
+    gameEndDelay: number;
+    submissionDuration: number;
+}
+interface GameConfig {
+    gameAddress: string;
+    settingsId: number;
+    soulbound: boolean;
+    paymaster: boolean;
+    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;
+}
+type Phase = "scheduled" | "registration" | "staging" | "live" | "submission" | "finalized";
+interface TournamentListParams {
+    gameAddress?: string;
+    creator?: string;
+    phase?: Phase;
+    limit?: number;
+    offset?: number;
+    sort?: "start_time" | "end_time" | "players" | "created_at";
+    fromId?: string;
+    excludeIds?: string[];
+    whitelistedExtensions?: string[];
+    includePrizeSummary?: "summary" | boolean;
+}
+interface QualificationEntry {
+    tournamentId: string;
+    qualificationProof: unknown;
+    entryCount: number;
+}
+
+interface LeaderboardEntry {
+    position: number;
+    tokenId: string;
+}
+
+interface Registration {
+    tournamentId: string;
+    gameTokenId: string;
+    gameAddress: string;
+    playerAddress: string;
+    entryNumber: number;
+    hasSubmitted: boolean;
+    isBanned: boolean;
+}
+
+interface Prize {
+    prizeId: string;
+    tournamentId: string;
+    payoutPosition: number;
+    tokenAddress: string;
+    tokenType: "erc20" | "erc721";
+    amount: string | null;
+    tokenId: string | null;
+    distributionType: string | null;
+    distributionWeight: number | null;
+    distributionCount: number | null;
+    sponsorAddress: string;
+}
+interface RewardClaim {
+    tournamentId: string;
+    rewardType: unknown;
+    claimed: boolean;
+}
+interface PrizeAggregation {
+    tokenAddress: string;
+    tokenType: string;
+    totalAmount: string;
+    nftCount: number;
+}
+interface RewardClaimSummary {
+    totalPrizes: number;
+    totalClaimed: number;
+    totalUnclaimed: number;
+}
+
+interface PlayerStats {
+    totalTournaments: number;
+    totalSubmissions: number;
+}
+interface PlayerTournament extends Tournament {
+    registration: Registration;
+}
+interface PlayerTournamentParams {
+    phase?: Phase;
+    gameTokenIds?: string[];
+    limit?: number;
+    offset?: number;
+}
+
+interface ActivityEvent {
+    id: string;
+    eventType: string;
+    tournamentId: string | null;
+    playerAddress: string | null;
+    data: unknown;
+    blockNumber: string;
+    txHash: string;
+    eventIndex: number;
+}
+interface ActivityParams {
+    eventType?: string;
+    tournamentId?: string;
+    playerAddress?: string;
+    limit?: number;
+    offset?: number;
+}
+interface PlatformStats {
+    totalTournaments: number;
+    totalPrizes: number;
+    totalRegistrations: number;
+    totalSubmissions: number;
+}
+interface PrizeStats {
+    tokenTotals: Array<{
+        tokenAddress: string;
+        totalPrizes: number;
+        totalAmount: string;
+    }>;
+    totalNftPrizes: number;
+}
+
+interface PaginatedResult<T> {
+    data: T[];
+    total?: number;
+    limit: number;
+    offset: number;
+}
+
+type WSChannel = "tournaments" | "registrations" | "leaderboards" | "prizes" | "rewards" | "metrics";
+interface WSSubscribeMessage {
+    type: "subscribe";
+    channels: WSChannel[];
+    tournamentIds?: string[];
+}
+interface WSUnsubscribeMessage {
+    type: "unsubscribe";
+    channels: WSChannel[];
+}
+interface WSEventMessage {
+    type: "event";
+    channel: WSChannel;
+    data: unknown;
+    timestamp: string;
+}
+type WSMessage = WSSubscribeMessage | WSUnsubscribeMessage | WSEventMessage;
+interface WSSubscribeOptions {
+    channels: WSChannel[];
+    tournamentIds?: string[];
+}
+type WSEventHandler = (message: WSEventMessage) => void;
+
+type ConnectionMode = "api" | "rpc-fallback" | "offline";
+interface ServiceStatus {
+    available: boolean;
+    lastChecked: number;
+    latency: number | null;
+    error: string | null;
+}
+interface ConnectionStatusState {
+    api: ServiceStatus;
+    rpc: ServiceStatus;
+    mode: ConnectionMode;
+    initialCheckComplete: boolean;
+}
+type StatusListener = (status: ConnectionStatusState) => void;
+interface HealthTimingConfig {
+    initialCheckDelay?: number;
+    checkInterval?: number;
+    checkTimeout?: number;
+}
+declare class ConnectionStatus {
+    private status;
+    private listeners;
+    private checkInterval;
+    private initialCheckTimeout;
+    private apiUrl;
+    private rpcUrl;
+    private readonly initialCheckDelay;
+    private readonly checkIntervalMs;
+    private readonly checkTimeoutMs;
+    constructor(apiUrl: string, rpcUrl: string, config?: HealthTimingConfig);
+    getStatus(): ConnectionStatusState;
+    get mode(): ConnectionMode;
+    subscribe(listener: StatusListener): () => void;
+    startMonitoring(): void;
+    stopMonitoring(): void;
+    markApiUnavailable(error?: string): void;
+    markRpcUnavailable(error?: string): void;
+    checkNow(): Promise<void>;
+    destroy(): void;
+    private performHealthCheck;
+    private checkApi;
+    private checkRpc;
+    private updateStatus;
+}
+
+/**
+ * Main client for interacting with the Budokan tournament system.
+ *
+ * Provides methods for querying tournaments, registrations, leaderboards,
+ * prizes, player stats, and activity events. Supports real-time updates
+ * via WebSocket subscriptions and automatic RPC fallback when the API is
+ * unavailable.
+ *
+ * @example
+ * ```ts
+ * // API-only (default, backward compatible)
+ * const client = new BudokanClient({
+ *   apiBaseUrl: "https://budokan-api.provable.games",
+ * });
+ *
+ * // With RPC fallback
+ * const client = new BudokanClient({
+ *   chain: "mainnet",
+ *   apiBaseUrl: "https://budokan-api.provable.games",
+ *   viewerAddress: "0x...",
+ * });
+ *
+ * // RPC-only (bypass API entirely)
+ * const client = new BudokanClient({
+ *   primarySource: "rpc",
+ *   rpcUrl: "https://api.cartridge.gg/x/starknet/mainnet/rpc/v0_10",
+ *   viewerAddress: "0x...",
+ * });
+ * ```
+ */
+declare class BudokanClient {
+    private readonly resolvedConfig;
+    private readonly wsManager;
+    private readonly connectionStatus;
+    private cachedProvider;
+    private cachedViewerContract;
+    constructor(config: BudokanClientConfig);
+    /** Returns the resolved configuration. */
+    get clientConfig(): BudokanClientConfig;
+    /** Whether the WebSocket is currently connected. */
+    get wsConnected(): boolean;
+    /** Returns the current connection status (API, RPC, mode). */
+    getConnectionStatus(): ConnectionStatusState;
+    /** Subscribe to connection status changes. Returns an unsubscribe function. */
+    onConnectionStatusChange(listener: (status: ConnectionStatusState) => void): () => void;
+    private getProvider;
+    private getViewerContract;
+    private get apiCtx();
+    /**
+     * Fetch a paginated list of tournaments with optional filtering.
+     * Supports RPC fallback when API is unavailable.
+     */
+    getTournaments(params?: TournamentListParams): Promise<PaginatedResult<Tournament>>;
+    /**
+     * Fetch a single tournament by its ID.
+     * Supports RPC fallback when API is unavailable.
+     */
+    getTournament(tournamentId: string): Promise<Tournament>;
+    /**
+     * Fetch the leaderboard for a tournament.
+     * Supports RPC fallback when API is unavailable.
+     */
+    getTournamentLeaderboard(tournamentId: string): Promise<LeaderboardEntry[]>;
+    /**
+     * Fetch registrations for a tournament.
+     * Supports RPC fallback when API is unavailable.
+     * Note: In RPC mode, `playerAddress` and `gameAddress` fields will be empty strings.
+     */
+    getTournamentRegistrations(tournamentId: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResult<Registration>>;
+    /**
+     * Fetch prizes for a tournament.
+     * Supports RPC fallback when API is unavailable.
+     */
+    getTournamentPrizes(tournamentId: string): Promise<Prize[]>;
+    /**
+     * Fetch tournaments that a player has registered for.
+     * API-only — no RPC fallback available.
+     */
+    getPlayerTournaments(address: string, params?: PlayerTournamentParams): Promise<PaginatedResult<PlayerTournament>>;
+    /**
+     * Fetch stats for a player.
+     * API-only — no RPC fallback available.
+     */
+    getPlayerStats(address: string): Promise<PlayerStats>;
+    /**
+     * Fetch tournaments for a specific game.
+     * Supports RPC fallback when API is unavailable.
+     */
+    getGameTournaments(gameAddress: string, params?: Omit<TournamentListParams, "gameAddress">): Promise<PaginatedResult<Tournament>>;
+    /**
+     * Fetch tournament stats for a specific game.
+     * API-only — no RPC fallback available.
+     */
+    getGameStats(gameAddress: string): Promise<PlatformStats>;
+    /**
+     * Fetch reward claims for a tournament.
+     * API-only -- no RPC fallback available.
+     */
+    getTournamentRewardClaims(tournamentId: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResult<RewardClaim>>;
+    /**
+     * Fetch reward claims summary for a tournament.
+     * API-only -- no RPC fallback available.
+     */
+    getTournamentRewardClaimsSummary(tournamentId: string): Promise<RewardClaimSummary>;
+    /**
+     * Fetch qualifications for a tournament.
+     * API-only -- no RPC fallback available.
+     */
+    getTournamentQualifications(tournamentId: string, params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResult<QualificationEntry>>;
+    /**
+     * Fetch prize aggregation for a tournament.
+     * API-only -- no RPC fallback available.
+     */
+    getTournamentPrizeAggregation(tournamentId: string): Promise<PrizeAggregation[]>;
+    /**
+     * Fetch activity events with optional filtering.
+     * API-only — no RPC fallback available.
+     */
+    getActivity(params?: ActivityParams): Promise<PaginatedResult<ActivityEvent>>;
+    /**
+     * Fetch platform-wide activity stats.
+     * API-only — no RPC fallback available.
+     */
+    getActivityStats(): Promise<PlatformStats>;
+    /**
+     * Fetch platform-wide prize stats.
+     * API-only — no RPC fallback available.
+     */
+    getPrizeStats(): Promise<PrizeStats>;
+    /**
+     * Open a WebSocket connection for real-time updates.
+     */
+    connect(): void;
+    /**
+     * Close the WebSocket connection.
+     */
+    disconnect(): void;
+    /**
+     * Stop health monitoring and close all connections.
+     */
+    destroy(): void;
+    /**
+     * Subscribe to WebSocket channels with optional tournament filtering.
+     * Returns an unsubscribe function.
+     */
+    subscribe(channels: WSChannel[], handler: WSEventHandler, tournamentIds?: string[]): () => void;
+    /**
+     * Register a listener for WebSocket connection state changes.
+     * Returns an unsubscribe function.
+     */
+    onWsConnectionChange(listener: (connected: boolean) => void): () => void;
+}
+/**
+ * Factory function for creating a BudokanClient instance.
+ */
+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 };