@provable-games/metagame-sdk 0.1.0 → 0.1.2

package/dist/react.d.ts

@@ -0,0 +1,300 @@
+import { s as Token, S as StatusTimestamps, a as StatusResult, l as Participant, P as Prize, m as PositionPrizeGroup, j as EntryFeeShares, D as DistributionType, h as EntryFeeBreakdown, g as QualificationProof, f as EntryRequirementVariant, T as TournamentValidatorConfig, e as QualificationResult, O as OpusTrovesValidatorConfig } from './prizeAggregation-CHwIJzXr.js';
+import { S as StarknetCallProvider } from './extensions-BskkhEHk.js';
+import 'starknet';
+
+declare function useDebounce<T>(value: T, delay: number): T;
+
+interface UsePaginationOptions {
+    totalItems: number;
+    pageSize?: number;
+}
+interface UsePaginationReturn {
+    currentPage: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+    next: () => void;
+    prev: () => void;
+    reset: () => void;
+    startIndex: number;
+    endIndex: number;
+}
+declare function usePagination({ totalItems, pageSize, }: UsePaginationOptions): UsePaginationReturn;
+
+interface UseSearchFilterOptions<T> {
+    items: T[];
+    searchFields: (keyof T)[];
+    debounceMs?: number;
+}
+interface UseSearchFilterReturn<T> {
+    search: string;
+    setSearch: (q: string) => void;
+    filteredItems: T[];
+    resultCount: number;
+}
+declare function useSearchFilter<T>({ items, searchFields, debounceMs, }: UseSearchFilterOptions<T>): UseSearchFilterReturn<T>;
+
+interface UseTokenSelectorOptions {
+    tokens: Token[];
+    tokenType?: "erc20" | "erc721";
+    pageSize?: number;
+    debounceMs?: number;
+}
+interface UseTokenSelectorReturn {
+    search: string;
+    setSearch: (q: string) => void;
+    filteredTokens: Token[];
+    selectedToken: Token | null;
+    select: (token: Token) => void;
+    clear: () => void;
+    isSelected: (token: Token) => boolean;
+    pagination: UsePaginationReturn;
+    getTokenProps: (token: Token) => {
+        onClick: () => void;
+        "data-selected": boolean;
+        role: "option";
+        "aria-selected": boolean;
+    };
+}
+declare function useTokenSelector({ tokens, tokenType, pageSize, debounceMs, }: UseTokenSelectorOptions): UseTokenSelectorReturn;
+
+declare function useStatusIndicator(timestamps: StatusTimestamps, refreshMs?: number): StatusResult;
+
+type SortField = "rank" | "score" | "name";
+type SortDirection = "asc" | "desc";
+interface UseScoreTableOptions {
+    participants: Participant[];
+    pageSize?: number;
+    sortField?: SortField;
+    sortDirection?: SortDirection;
+}
+interface UseScoreTableReturn {
+    rows: Participant[];
+    pagination: UsePaginationReturn;
+    sort: {
+        field: SortField;
+        direction: SortDirection;
+    };
+    setSort: (field: string) => void;
+    search: string;
+    setSearch: (q: string) => void;
+}
+declare function useScoreTable({ participants, pageSize, sortField, sortDirection, }: UseScoreTableOptions): UseScoreTableReturn;
+
+interface UsePrizeTableOptions {
+    prizes: Prize[];
+    positionsPerPage?: number;
+}
+interface UsePrizeTableReturn {
+    /** Prize groups for the current page, sorted by position */
+    rows: PositionPrizeGroup[];
+    /** Total number of positions across all prizes */
+    totalPositions: number;
+    /** Pagination state and controls */
+    pagination: UsePaginationReturn;
+}
+/**
+ * Headless hook for displaying a paginated prize table.
+ *
+ * Aggregates prizes by position (summing ERC20 amounts, grouping ERC721 IDs),
+ * then paginates the position groups. Metagame UIs render each position group
+ * however they like — the hook only manages data and pagination state.
+ */
+declare function usePrizeTable({ prizes, positionsPerPage, }: UsePrizeTableOptions): UsePrizeTableReturn;
+
+interface UseEntryFeePreviewOptions {
+    /** Fee per entry in smallest token units (as bigint) */
+    feePerEntry: bigint;
+    /** Expected number of entries (for preview) */
+    entryCount: number;
+    /** Share percentages in basis points */
+    shares: EntryFeeShares;
+    /** Number of positions to distribute prizes across */
+    distributionPositions: number;
+    /** Distribution curve type */
+    distributionType: DistributionType;
+    /** Weight for linear/exponential curves */
+    distributionWeight: number;
+}
+interface UseEntryFeePreviewReturn {
+    /** Breakdown of total fees into creator/game/refund/pool buckets */
+    breakdown: EntryFeeBreakdown;
+    /** Per-position prize amounts from the pool */
+    positionPrizes: Array<{
+        position: number;
+        amount: bigint;
+    }>;
+    /** Distribution percentages per position (0-100 scale) */
+    percentages: number[];
+}
+/**
+ * Headless hook for live entry fee breakdown preview.
+ *
+ * As form values change (fee amount, shares, distribution curve),
+ * this hook recomputes the full breakdown and per-position prizes.
+ * Useful for "create tournament/quest" forms where you want to show
+ * the user a live preview of how entry fees will be distributed.
+ */
+declare function useEntryFeePreview({ feePerEntry, entryCount, shares, distributionPositions, distributionType, distributionWeight, }: UseEntryFeePreviewOptions): UseEntryFeePreviewReturn;
+
+/**
+ * A potential qualification the user has — e.g., an owned NFT, a tournament
+ * they won.
+ */
+interface QualificationMethod {
+    /** Unique ID for deduplication */
+    id: string;
+    /** The proof to submit if this method is used */
+    proof: QualificationProof;
+    /** Human-readable label */
+    label?: string;
+    /** Additional display metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Pre-checked extension result from calling the extension contract.
+ * Each metagame calls `entries_left` on-chain and passes results here.
+ */
+interface CheckedExtensionQualification {
+    id: string;
+    entriesLeft: number;
+    proof: string[];
+    label?: string;
+    metadata?: Record<string, unknown>;
+}
+interface UseEntryQualificationOptions {
+    /** The type of entry requirement */
+    variant: EntryRequirementVariant;
+    /** NFT token IDs owned by the player */
+    ownedTokenIds?: string[];
+    /** How many times each token has been used (tokenId → count) */
+    tokenEntryCounts?: Record<string, number>;
+    /** The player's address */
+    playerAddress?: string;
+    /** Pre-checked results from calling extension contract */
+    extensionQualifications?: CheckedExtensionQualification[];
+    /** For tournament validator: the parsed config */
+    tournamentValidatorConfig?: TournamentValidatorConfig | null;
+    /** For generic extensions: whether the contract says entry is valid */
+    extensionValidEntry?: boolean;
+    /** For generic extensions: entries left from contract */
+    extensionEntriesLeft?: number | null;
+    /** Max entries allowed (0 = unlimited) */
+    entryLimit?: number;
+}
+interface UseEntryQualificationReturn {
+    /** Whether the user meets the entry requirements */
+    meetsRequirements: boolean;
+    /** The best proof to use for entering */
+    bestProof: QualificationProof | null;
+    /** All valid qualification methods */
+    qualifications: QualificationResult["qualifications"];
+    /** Total entries remaining */
+    totalEntriesLeft: number;
+    /** Entries remaining grouped by source (tournament ID, token address, etc.) */
+    entriesLeftBySource: Array<{
+        sourceId?: string;
+        sourceType?: string;
+        entriesLeft: number;
+    }>;
+}
+/**
+ * Headless hook that evaluates whether a user qualifies to enter a
+ * metagame event. Works for all requirement types (token, extension).
+ *
+ * Each metagame fetches the data through their own SDK (owned NFTs,
+ * registrations, extension contract calls), then passes it here.
+ * The evaluation logic is the same across all metagames.
+ *
+ * @example
+ * ```tsx
+ * const { meetsRequirements, bestProof, entriesLeftBySource } = useEntryQualification({
+ *   variant: "token",
+ *   ownedTokenIds: ["123", "456"],
+ *   tokenEntryCounts: { "123": 2, "456": 0 },
+ *   entryLimit: 3,
+ * });
+ *
+ * // To enter, serialize the proof:
+ * const onChainProof = buildQualificationProof(bestProof);
+ * ```
+ */
+declare function useEntryQualification(options: UseEntryQualificationOptions): UseEntryQualificationReturn;
+
+/**
+ * Hook to check extension qualification and entries left for multiple proofs.
+ *
+ * Ported from budokan — accepts a provider instead of relying on app-specific hooks.
+ */
+
+/** A single qualification method for an extension */
+interface ExtensionQualification {
+    id: string;
+    proof: string[];
+    entriesLeft: number;
+    label?: string;
+    metadata?: {
+        tournamentId?: string;
+        tournamentName?: string;
+        tokenId?: string;
+        position?: number;
+        [key: string]: unknown;
+    };
+}
+/** Result from extension qualification check */
+interface ExtensionQualificationResult {
+    qualifications: ExtensionQualification[];
+    totalEntriesLeft: number;
+    bestQualification: ExtensionQualification | null;
+    loading: boolean;
+    error: Error | null;
+}
+/** Input for building qualifications — tournament validator specific */
+interface TournamentValidatorInput {
+    tournamentId: string;
+    tokenId: string;
+    position: number;
+    tournamentName?: string;
+}
+/**
+ * Check extension qualification and entries left for multiple proofs.
+ *
+ * @param provider - Starknet RPC provider (or null to disable)
+ * @param extensionAddress - The extension contract address
+ * @param contextId - The metagame event ID (tournament ID, etc.)
+ * @param playerAddress - The player's address
+ * @param qualificationInputs - Potential qualifications to check
+ * @param enabled - Whether to run the check (default: true)
+ */
+declare const useExtensionQualification: (provider: StarknetCallProvider | null, extensionAddress: string | undefined, contextId: string | undefined, playerAddress: string | undefined, qualificationInputs: TournamentValidatorInput[], enabled?: boolean) => ExtensionQualificationResult;
+
+/**
+ * Hook to calculate bannable entries for Opus Troves extension.
+ *
+ * Ported from budokan — accepts a provider instead of relying on app-specific hooks.
+ */
+
+interface Game {
+    tokenId: number | bigint;
+    owner?: string;
+}
+interface UseOpusTrovesBannableEntriesResult {
+    bannableEntries: Set<string>;
+    troveDebts: Map<string, bigint>;
+    isLoading: boolean;
+    playerGroups: Map<string, Game[]>;
+}
+/**
+ * Calculate bannable entries for Opus Troves extension.
+ *
+ * @param provider - Starknet RPC provider (or null to disable)
+ * @param games - Array of game entries with tokenId and owner
+ * @param config - Opus Troves validator config (or undefined to disable)
+ * @param enabled - Whether to run the check
+ */
+declare const useOpusTrovesBannableEntries: (provider: StarknetCallProvider | null, games: Array<{
+    tokenId: number | bigint;
+    owner?: string;
+}>, config: OpusTrovesValidatorConfig | undefined, enabled: boolean) => UseOpusTrovesBannableEntriesResult;
+
+export { type CheckedExtensionQualification, type ExtensionQualification, type ExtensionQualificationResult, type QualificationMethod, type TournamentValidatorInput, type UseEntryFeePreviewOptions, type UseEntryFeePreviewReturn, type UseEntryQualificationOptions, type UseEntryQualificationReturn, type UseOpusTrovesBannableEntriesResult, type UsePaginationOptions, type UsePaginationReturn, type UsePrizeTableOptions, type UsePrizeTableReturn, type UseScoreTableOptions, type UseScoreTableReturn, type UseSearchFilterOptions, type UseSearchFilterReturn, type UseTokenSelectorOptions, type UseTokenSelectorReturn, useDebounce, useEntryFeePreview, useEntryQualification, useExtensionQualification, useOpusTrovesBannableEntries, usePagination, usePrizeTable, useScoreTable, useSearchFilter, useStatusIndicator, useTokenSelector };