@pokertools/sdk 1.0.4

package/dist/index.d.ts

@@ -0,0 +1,750 @@
+import * as _pokertools_types from '@pokertools/types';
+import { LoginRequest, LoginResponse, TableListItem, CreateTableRequest, PublicState, BuyInRequest, GameActionRequest, AddChipsRequest, PublicPlayer } from '@pokertools/types';
+export { Action, ActionType, AddChipsRequest, BuyInRequest, ClientMessage, CreateTableRequest, ErrorMessage, GameActionRequest, GameState, JoinTableMessage, LeaveTableMessage, LoginRequest, LoginResponse, NonceResponse, Player, PublicPlayer, PublicState, ServerMessage, SnapshotMessage, StateUpdateMessage, TableConfig, TableListItem } 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;
+}
+/**
+ * Authentication state
+ */
+interface AuthState {
+    token: string | null;
+    user: {
+        id: string;
+        username: string;
+        address: string;
+    } | null;
+    isAuthenticated: 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;
+    };
+}
+/**
+ * SDK error class
+ */
+declare class PokerSDKError extends Error {
+    readonly code: string;
+    readonly statusCode?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: unknown | undefined);
+}
+/**
+ * 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;
+}
+/**
+ * Type-safe event listener
+ */
+type EventListener<T extends keyof PokerSocketEvents> = PokerSocketEvents[T];
+
+/**
+ * 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;
+}
+
+/**
+ * Authentication helpers for SIWE (Sign-In with Ethereum)
+ *
+ * These utilities help construct SIWE messages for wallet signing.
+ */
+/**
+ * SIWE message parameters
+ */
+interface SiweMessageParams {
+    /** Domain making the request (e.g., "poker.example.com") */
+    domain: string;
+    /** Ethereum address (checksummed) */
+    address: string;
+    /** Human-readable statement (optional) */
+    statement?: string;
+    /** URI of the signing resource */
+    uri: string;
+    /** Current version of the message (always "1") */
+    version?: "1";
+    /** Chain ID */
+    chainId?: number;
+    /** Nonce from server */
+    nonce: string;
+    /** Issued at timestamp (ISO 8601) */
+    issuedAt?: string;
+    /** Expiration time (ISO 8601) */
+    expirationTime?: string;
+    /** Not before time (ISO 8601) */
+    notBefore?: string;
+    /** Request ID */
+    requestId?: string;
+    /** Resources (URIs) */
+    resources?: string[];
+}
+/**
+ * Create a SIWE message string for signing
+ *
+ * @example
+ * ```typescript
+ * import { createSiweMessage } from "@pokertools/sdk";
+ *
+ * // Get nonce from server
+ * const nonce = await client.getNonce();
+ *
+ * // Create message
+ * const message = createSiweMessage({
+ *   domain: "poker.example.com",
+ *   address: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+ *   uri: "https://poker.example.com",
+ *   nonce,
+ *   statement: "Sign in to PokerTools",
+ * });
+ *
+ * // Sign with wallet (e.g., wagmi, ethers, viem)
+ * const signature = await signMessage({ message });
+ *
+ * // Login
+ * const { token, user } = await client.login({ message, signature });
+ * ```
+ */
+declare function createSiweMessage(params: SiweMessageParams): string;
+/**
+ * Parse a SIWE message string back into params
+ */
+declare function parseSiweMessage(message: string): Partial<SiweMessageParams>;
+/**
+ * Check if a SIWE message is expired
+ */
+declare function isSiweExpired(message: string): boolean;
+/**
+ * Create a withdrawal message for signing
+ *
+ * @example
+ * ```typescript
+ * const message = createWithdrawalMessage(100, "0x...");
+ * const signature = await signMessage({ message });
+ * await client.withdraw({ amount: 100, address: "0x...", message, signature, ... });
+ * ```
+ */
+declare function createWithdrawalMessage(amount: number, destinationAddress: string): string;
+/**
+ * Generate a random idempotency key
+ * Uses crypto.randomUUID if available, otherwise falls back to timestamp + random
+ */
+declare function generateIdempotencyKey(): string;
+
+/**
+ * Utility functions for the PokerTools SDK
+ */
+
+/**
+ * Format chip amount to display string
+ * @param chips - Amount in cents (1 chip = 1 cent)
+ * @param currency - Currency symbol (default: "$")
+ */
+declare function formatChips(chips: number, currency?: string): string;
+/**
+ * Parse display amount to chips (cents)
+ * @param amount - Display amount string (e.g., "$10.50", "10.50", "1050")
+ */
+declare function parseChips(amount: string): number;
+/**
+ * Get the player whose turn it is
+ */
+declare function getActivePlayer(state: PublicState): PublicPlayer | null;
+/**
+ * Get player by ID
+ */
+declare function getPlayerById(state: PublicState, playerId: string): PublicPlayer | null;
+/**
+ * Get player seat index by ID
+ */
+declare function getPlayerSeat(state: PublicState, playerId: string): number | null;
+/**
+ * Check if it's a specific player's turn
+ */
+declare function isPlayerTurn(state: PublicState, playerId: string): boolean;
+/**
+ * Get the amount needed to call
+ */
+declare function getCallAmount(state: PublicState, playerId: string): number;
+/**
+ * Get minimum raise amount
+ */
+declare function getMinRaise(state: PublicState): number;
+/**
+ * Check if player can check
+ */
+declare function canCheck(state: PublicState, playerId: string): boolean;
+/**
+ * Check if player can bet (no prior bets this round)
+ */
+declare function canBet(state: PublicState, playerId: string): boolean;
+/**
+ * Get total pot size (main pot + side pots)
+ */
+declare function getTotalPot(state: PublicState): number;
+/**
+ * Get number of active players (not folded, has chips)
+ */
+declare function getActivePlayers(state: PublicState): PublicPlayer[];
+/**
+ * Get number of players in hand (not folded)
+ */
+declare function getPlayersInHand(state: PublicState): PublicPlayer[];
+/**
+ * Card suit to emoji
+ */
+declare function suitToEmoji(suit: string): string;
+/**
+ * Format card for display (e.g., "As" -> "A♠")
+ */
+declare function formatCard(card: string): string;
+/**
+ * Format card array for display
+ */
+declare function formatCards(cards: Array<string | null> | null): string;
+/**
+ * Get street display name
+ */
+declare function getStreetName(street: string): string;
+/**
+ * Check if game is in showdown phase
+ */
+declare function isShowdown(state: PublicState): boolean;
+/**
+ * Check if hand is complete (has winners)
+ */
+declare function isHandComplete(state: PublicState): boolean;
+/**
+ * Calculate pot odds as a ratio
+ */
+declare function getPotOdds(state: PublicState, playerId: string): number;
+/**
+ * Abbreviate large numbers (e.g., 1000 -> "1K")
+ */
+declare function abbreviateNumber(num: number): string;
+
+export { type AuthState, type BlockchainInfo, type ConnectionState, type DepositRecord, type DepositSession, type EventListener, type HandHistoryEntry, type PlayerNote, PokerClient, type PokerSDKConfig, PokerSDKError, PokerSocket, type PokerSocketEvents, type SiweMessageParams, type TokenInfo, type UserBalances, type UserProfile, type WithdrawalRecord, type WithdrawalRequest, abbreviateNumber, canBet, canCheck, createSiweMessage, createWithdrawalMessage, formatCard, formatCards, formatChips, generateIdempotencyKey, getActivePlayer, getActivePlayers, getCallAmount, getMinRaise, getPlayerById, getPlayerSeat, getPlayersInHand, getPotOdds, getStreetName, getTotalPot, isHandComplete, isPlayerTurn, isShowdown, isSiweExpired, parseChips, parseSiweMessage, suitToEmoji };