@pokertools/sdk 1.0.4

package/dist/react/index.d.cts

@@ -0,0 +1,683 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as _pokertools_types from '@pokertools/types';
+import { LoginRequest, LoginResponse, TableListItem, CreateTableRequest, PublicState, BuyInRequest, GameActionRequest, AddChipsRequest } from '@pokertools/types';
+
+/**
+ * SDK-specific types and configuration
+ */
+/**
+ * SDK configuration options
+ */
+interface PokerSDKConfig {
+    /** Base URL of the PokerTools API (e.g., "https://api.poker.example.com") */
+    baseUrl: string;
+    /** WebSocket URL (defaults to baseUrl with ws:// protocol) */
+    wsUrl?: string;
+    /** JWT token for authentication */
+    token?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Retry configuration */
+    retry?: {
+        /** Number of retries for failed requests (default: 3) */
+        count?: number;
+        /** Delay between retries in ms (default: 1000) */
+        delay?: number;
+        /** Exponential backoff multiplier (default: 2) */
+        backoff?: number;
+    };
+    /** Custom fetch implementation (for React Native or custom environments) */
+    fetch?: typeof fetch;
+    /** Custom WebSocket implementation (for React Native or Node.js) */
+    WebSocket?: typeof WebSocket;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * User balance information
+ */
+interface UserBalances {
+    main: number;
+    inPlay: number;
+}
+/**
+ * User profile with balances
+ */
+interface UserProfile {
+    id: string;
+    username: string;
+    address: string;
+    role: "PLAYER" | "ADMIN" | "BOT";
+    createdAt: string;
+    balances: UserBalances;
+}
+/**
+ * Blockchain configuration
+ */
+interface BlockchainInfo {
+    id: string;
+    name: string;
+    chainId: number;
+    tokens: TokenInfo[];
+}
+/**
+ * Token configuration
+ */
+interface TokenInfo {
+    id: string;
+    symbol: string;
+    name: string;
+    decimals: number;
+    minDeposit: string;
+}
+/**
+ * Deposit session info
+ */
+interface DepositSession {
+    address: string;
+    expiresAt: string;
+    message: string;
+}
+/**
+ * Deposit record
+ */
+interface DepositRecord {
+    id: string;
+    txHash: string | null;
+    chain: string;
+    token: string;
+    amountRaw: string;
+    amountCredit: number;
+    status: "PENDING" | "PROCESSING" | "CONFIRMED" | "FAILED";
+    createdAt: string;
+    confirmedAt: string | null;
+    explorerUrl: string;
+}
+/**
+ * Withdrawal request
+ */
+interface WithdrawalRequest {
+    amount: number;
+    blockchainId: string;
+    tokenId: string;
+    address: string;
+    message: string;
+    signature: `0x${string}`;
+}
+/**
+ * Withdrawal record
+ */
+interface WithdrawalRecord {
+    id: string;
+    txHash: string | null;
+    chain: string;
+    token: string;
+    address: string;
+    amountRaw: string;
+    amountUSD: number;
+    status: "PENDING" | "PROCESSING" | "CONFIRMED" | "FAILED" | "REJECTED" | "CANCELLED";
+    createdAt: string;
+    confirmedAt: string | null;
+    explorerUrl: string | null;
+}
+/**
+ * Hand history entry (simplified)
+ */
+interface HandHistoryEntry {
+    id: string;
+    amount: number;
+    type: "HAND_WIN" | "HAND_LOSS";
+    referenceId: string | null;
+    createdAt: string;
+}
+/**
+ * Player note
+ */
+interface PlayerNote {
+    id: string;
+    targetId: string;
+    content: string;
+    label: string | null;
+    createdAt: string;
+    updatedAt: string;
+    target?: {
+        id: string;
+        username: string;
+    };
+}
+/**
+ * WebSocket connection state
+ */
+type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting";
+/**
+ * Event emitter types
+ */
+interface PokerSocketEvents {
+    connect: () => void;
+    disconnect: (reason?: string) => void;
+    reconnect: (attempt: number) => void;
+    error: (error: Error) => void;
+    stateUpdate: (tableId: string, state: _pokertools_types.PublicState) => void;
+    snapshot: (tableId: string, state: _pokertools_types.PublicState) => void;
+    action: (tableId: string, playerId: string, actionType: string, amount?: number) => void;
+}
+
+/**
+ * PokerClient - HTTP client for PokerTools REST API
+ *
+ * Provides type-safe methods for all API endpoints with automatic
+ * retry, authentication, and error handling.
+ */
+
+/**
+ * PokerClient - Main HTTP client for PokerTools API
+ *
+ * @example
+ * ```typescript
+ * const client = new PokerClient({
+ *   baseUrl: "https://api.poker.example.com",
+ *   token: "jwt-token",
+ * });
+ *
+ * // Get tables
+ * const tables = await client.getTables();
+ *
+ * // Create a table
+ * const tableId = await client.createTable({
+ *   name: "My Table",
+ *   mode: "CASH",
+ *   smallBlind: 5,
+ *   bigBlind: 10,
+ *   maxPlayers: 6,
+ * });
+ *
+ * // Buy in
+ * await client.buyIn(tableId, {
+ *   amount: 500,
+ *   seat: 3,
+ *   idempotencyKey: crypto.randomUUID(),
+ * });
+ * ```
+ */
+declare class PokerClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retry;
+    private readonly fetchFn;
+    private readonly debug;
+    private token;
+    constructor(config: PokerSDKConfig);
+    /**
+     * Set the authentication token
+     */
+    setToken(token: string | null): void;
+    /**
+     * Get current token
+     */
+    getToken(): string | null;
+    /**
+     * Check if client is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get a nonce for SIWE authentication
+     */
+    getNonce(): Promise<string>;
+    /**
+     * Login with SIWE signature
+     */
+    login(request: LoginRequest): Promise<LoginResponse>;
+    /**
+     * Logout and revoke session
+     */
+    logout(): Promise<void>;
+    /**
+     * Get list of active tables
+     */
+    getTables(): Promise<TableListItem[]>;
+    /**
+     * Create a new table
+     */
+    createTable(config: CreateTableRequest): Promise<string>;
+    /**
+     * Get table state
+     * @param tableId - Table ID
+     * @param since - Optional version for conditional fetch (returns null if unchanged)
+     */
+    getTableState(tableId: string, since?: number): Promise<PublicState | null>;
+    /**
+     * Buy in to a table
+     */
+    buyIn(tableId: string, request: BuyInRequest): Promise<void>;
+    /**
+     * Execute a game action
+     */
+    action(tableId: string, request: GameActionRequest): Promise<PublicState>;
+    /**
+     * Add chips to stack (rebuy/top-up)
+     */
+    addChips(tableId: string, request: AddChipsRequest): Promise<void>;
+    /**
+     * Stand from table (leave and cash out)
+     */
+    stand(tableId: string): Promise<void>;
+    /**
+     * Fold hand
+     */
+    fold(tableId: string): Promise<PublicState>;
+    /**
+     * Check (pass action)
+     */
+    check(tableId: string): Promise<PublicState>;
+    /**
+     * Call current bet
+     */
+    call(tableId: string): Promise<PublicState>;
+    /**
+     * Place a bet
+     */
+    bet(tableId: string, amount: number): Promise<PublicState>;
+    /**
+     * Raise the current bet
+     */
+    raise(tableId: string, amount: number): Promise<PublicState>;
+    /**
+     * Deal new hand
+     */
+    deal(tableId: string): Promise<PublicState>;
+    /**
+     * Show cards at showdown
+     */
+    show(tableId: string, cardIndices?: number[]): Promise<PublicState>;
+    /**
+     * Muck cards at showdown
+     */
+    muck(tableId: string): Promise<PublicState>;
+    /**
+     * Use time bank
+     */
+    timeBank(tableId: string): Promise<PublicState>;
+    /**
+     * Get current user profile and balances
+     */
+    getProfile(): Promise<UserProfile>;
+    /**
+     * Get hand history
+     */
+    getHandHistory(): Promise<HandHistoryEntry[]>;
+    /**
+     * Request a withdrawal
+     */
+    withdraw(request: WithdrawalRequest): Promise<{
+        id: string;
+        status: string;
+        amount: number;
+        destination: string;
+        blockchain: string;
+        token: string;
+    }>;
+    /**
+     * Get withdrawal history
+     */
+    getWithdrawals(): Promise<WithdrawalRecord[]>;
+    /**
+     * Get supported blockchains and tokens
+     */
+    getChains(): Promise<BlockchainInfo[]>;
+    /**
+     * Start deposit monitoring session
+     */
+    startDeposit(): Promise<DepositSession>;
+    /**
+     * Get deposit address
+     */
+    getDepositAddress(): Promise<string>;
+    /**
+     * Get deposit history
+     */
+    getDeposits(): Promise<DepositRecord[]>;
+    /**
+     * Get all notes by current user
+     */
+    getNotes(): Promise<PlayerNote[]>;
+    /**
+     * Get note for specific player
+     */
+    getNote(targetId: string): Promise<PlayerNote | null>;
+    /**
+     * Save or update note
+     */
+    saveNote(targetId: string, content: string, label?: string): Promise<PlayerNote>;
+    /**
+     * Delete note
+     */
+    deleteNote(targetId: string): Promise<void>;
+    /**
+     * Health check
+     */
+    health(): Promise<{
+        status: string;
+        timestamp: number;
+    }>;
+    /**
+     * Make HTTP request with retry logic
+     */
+    private request;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+}
+
+/**
+ * PokerSocket - WebSocket client for real-time game updates
+ *
+ * Provides automatic reconnection, heartbeat, and typed event handling
+ * for real-time poker game state synchronization.
+ */
+
+/**
+ * WebSocket configuration
+ */
+interface SocketConfig {
+    /** WebSocket URL */
+    url: string;
+    /** JWT token for authentication */
+    token: string;
+    /** Heartbeat interval in ms (default: 25000) */
+    heartbeatInterval?: number;
+    /** Reconnection attempts (default: 10) */
+    reconnectAttempts?: number;
+    /** Base reconnection delay in ms (default: 1000) */
+    reconnectDelay?: number;
+    /** Max reconnection delay in ms (default: 30000) */
+    maxReconnectDelay?: number;
+    /** Custom WebSocket implementation */
+    WebSocket?: typeof WebSocket;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * PokerSocket - Real-time WebSocket client
+ *
+ * @example
+ * ```typescript
+ * const socket = new PokerSocket({
+ *   url: "wss://api.poker.example.com/ws/play",
+ *   token: "jwt-token",
+ * });
+ *
+ * // Listen for events
+ * socket.on("connect", () => console.log("Connected!"));
+ * socket.on("stateUpdate", (tableId, state) => {
+ *   console.log("State updated:", state);
+ * });
+ *
+ * // Connect
+ * await socket.connect();
+ *
+ * // Join a table
+ * await socket.join("table-123");
+ *
+ * // Later: disconnect
+ * socket.disconnect();
+ * ```
+ */
+declare class PokerSocket {
+    private readonly url;
+    private readonly token;
+    private readonly heartbeatInterval;
+    private readonly reconnectAttempts;
+    private readonly reconnectDelay;
+    private readonly maxReconnectDelay;
+    private readonly WebSocketImpl;
+    private readonly debug;
+    private ws;
+    private connectionState;
+    private reconnectCount;
+    private heartbeatTimer;
+    private pendingRequests;
+    private joinedTables;
+    private listeners;
+    private shouldReconnect;
+    private stateCache;
+    constructor(config: SocketConfig);
+    /**
+     * Create a PokerSocket from SDK config
+     */
+    static fromConfig(config: PokerSDKConfig): PokerSocket;
+    /**
+     * Connect to the WebSocket server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the WebSocket server
+     */
+    disconnect(): void;
+    /**
+     * Get current connection state
+     */
+    getState(): ConnectionState;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Join a table to receive real-time updates
+     */
+    join(tableId: string): Promise<PublicState>;
+    /**
+     * Leave a table
+     */
+    leave(tableId: string): void;
+    /**
+     * Get currently joined tables
+     */
+    getJoinedTables(): string[];
+    /**
+     * Get cached state for a table
+     */
+    getCachedState(tableId: string): PublicState | undefined;
+    /**
+     * Subscribe to an event
+     */
+    on<E extends keyof PokerSocketEvents>(event: E, listener: PokerSocketEvents[E]): () => void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<E extends keyof PokerSocketEvents>(event: E, listener: PokerSocketEvents[E]): void;
+    /**
+     * Subscribe to an event (once)
+     */
+    once<E extends keyof PokerSocketEvents>(event: E, listener: PokerSocketEvents[E]): () => void;
+    /**
+     * Send application-level ping (not WebSocket ping)
+     */
+    ping(): Promise<number>;
+    /**
+     * Send a message to the server
+     */
+    private send;
+    /**
+     * Handle incoming message
+     */
+    private handleMessage;
+    /**
+     * Handle disconnect
+     */
+    private handleDisconnect;
+    /**
+     * Attempt to reconnect
+     */
+    private reconnect;
+    /**
+     * Rejoin previously joined tables
+     */
+    private rejoinTables;
+    /**
+     * Start heartbeat timer
+     */
+    private startHeartbeat;
+    /**
+     * Stop heartbeat timer
+     */
+    private stopHeartbeat;
+    /**
+     * Clear all pending requests
+     */
+    private clearPendingRequests;
+    /**
+     * Emit event to listeners
+     */
+    private emit;
+    /**
+     * Generate unique request ID
+     */
+    private generateRequestId;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+    /**
+     * Debug logger
+     */
+    private log;
+}
+
+interface PokerContextValue {
+    client: PokerClient;
+    socket: PokerSocket | null;
+    isAuthenticated: boolean;
+    connectionState: ConnectionState;
+    connect: () => Promise<void>;
+    disconnect: () => void;
+}
+/**
+ * Props for PokerProvider
+ */
+interface PokerProviderProps {
+    /** SDK configuration */
+    config: PokerSDKConfig;
+    /** Children to render */
+    children: ReactNode;
+    /** Auto-connect WebSocket when authenticated (default: true) */
+    autoConnect?: boolean;
+}
+/**
+ * PokerProvider - Context provider for PokerTools SDK
+ *
+ * @example
+ * ```tsx
+ * import { PokerProvider } from "@pokertools/sdk/react";
+ *
+ * function App() {
+ *   return (
+ *     <PokerProvider config={{ baseUrl: "https://api.poker.example.com", token }}>
+ *       <Game />
+ *     </PokerProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function PokerProvider({ config, children, autoConnect }: PokerProviderProps): react.JSX.Element;
+/**
+ * Hook to access PokerTools context
+ */
+declare function usePoker(): PokerContextValue;
+/**
+ * Hook to get the PokerClient instance
+ */
+declare function usePokerClient(): PokerClient;
+/**
+ * Hook to get the PokerSocket instance
+ */
+declare function usePokerSocket(): PokerSocket | null;
+interface UseTableOptions {
+    /** Polling interval for state updates (ms, default: disabled) */
+    pollInterval?: number;
+    /** Auto-join via WebSocket (default: true) */
+    autoJoin?: boolean;
+}
+interface UseTableResult {
+    /** Current table state */
+    state: PublicState | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Refresh state from server */
+    refresh: () => Promise<void>;
+    /** Execute an action */
+    action: (type: string, amount?: number) => Promise<void>;
+    /** Leave the table */
+    leave: () => Promise<void>;
+}
+/**
+ * Hook to manage a poker table
+ *
+ * @example
+ * ```tsx
+ * function Table({ tableId }: { tableId: string }) {
+ *   const { state, isLoading, error, action } = useTable(tableId);
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!state) return <div>Table not found</div>;
+ *
+ *   return (
+ *     <div>
+ *       <div>Pot: {state.pot}</div>
+ *       <button onClick={() => action("FOLD")}>Fold</button>
+ *       <button onClick={() => action("CALL")}>Call</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useTable(tableId: string, options?: UseTableOptions): UseTableResult;
+interface UseUserResult {
+    /** User profile */
+    profile: UserProfile | null;
+    /** User balances */
+    balances: UserBalances | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Refresh profile */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook to get current user profile and balances
+ */
+declare function useUser(): UseUserResult;
+interface UseTablesResult {
+    /** List of tables */
+    tables: Awaited<ReturnType<PokerClient["getTables"]>>;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Refresh tables list */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook to get list of active tables
+ */
+declare function useTables(): UseTablesResult;
+/**
+ * Hook to manage WebSocket connection
+ */
+declare function useConnection(): {
+    state: ConnectionState;
+    isConnected: boolean;
+    isConnecting: boolean;
+    isReconnecting: boolean;
+    latency: number | null;
+    connect: () => Promise<void>;
+    disconnect: () => void;
+    ping: () => Promise<number | null>;
+};
+
+export { type PokerContextValue, PokerProvider, type PokerProviderProps, type UseTableOptions, type UseTableResult, type UseTablesResult, type UseUserResult, useConnection, usePoker, usePokerClient, usePokerSocket, useTable, useTables, useUser };