@idealic/poker-engine/API.md

Professional poker game engine and hand evaluator with built-in iterator utilities

# Poker Engine API Reference

## Poker.Game

### Main methods

- `Poker.Game.create(hand: Poker.Hand): Poker.Game`

  Creates a new Game state from a Hand.

- `Poker.Game.applyAction(game: Poker.Game, action: string): Poker.Game`

  Applies an action to a Game state and returns the _mutated_ state

- `Poker.Game.advance(game: Poker.Game): Poker.Game`

  Executes any pending dealer actions if needed (dealing flop, turn, river, or determining winners). This method automatically handles the progression of the game when betting rounds are complete.

- `Poker.Game.export(game: Poker.Game, playerId?: string): Poker.Hand`

  Exports a Hand from a Game state. If a `playerId` is provided, the Hand is sanitized to only include information that is visible to that player. Otherwise, the full Hand is exported.

### Helpers

- `Poker.Game.getTimeLeft(game: Poker.Game): number`
  Indicates how much time the current player has to finish their action. This can be called periodically (e.g., every second) to update a timer in the UI.

- `Poker.Game.getAuthorPlayerIndex(game: Poker.Game): number`

  Returns the index of the player who is the author of the hand.

- `Poker.Game.can(game: Poker.Game, command: Poker.CommandName, ...args: any[]): boolean`

  A catch-all method for the validation functions. Takes the game state, the command name (e.g., "fold"), and any additional arguments.

- `Poker.Game.act(game: Poker.Game, command: Poker.CommandName, ...args: any[]): Action`

  A catch-all method for the command functions. Takes the game state, the command name (e.g., "fold"), and any additional arguments.

## Poker.Hand

- `Poker.Hand.export(hand: Poker.Hand, playerId: string): Poker.Hand`

  An alias for `Poker.Game.export(Poker.Game.create(hand), playerId)`.

- `Poker.Hand.merge(hand1: Poker.Hand, hand2: Poker.Hand): Poker.Hand`

  Merges two Hands into a single Hand. This is useful for combining the views of different players into a single source of truth.

- `Poker.Hand.parse(input: string, format: 'pokerstars' | 'json' = 'pokerstars'): Poker.Hand`

  Parses a string representation of a Hand into a Hand object. The `json` format is equivalent to PHH.

- `Poker.Hand.serialize(input: Poker.Hand, format: 'pokerstars' | 'json' = 'pokerstars'): string`

  Serializes a Hand object into a string representation.

## Poker.Command

This section lists the commands that can be used with the `Poker.Game.act` and `Poker.Game.can` methods. Each command accepts specific arguments to control betting actions.

- `Poker.Command.fold(game: Poker.Game, playerIndex: number): Action`

  Player folds their hand and forfeits the current round. No additional arguments needed.

- `Poker.Command.call(game: Poker.Game, playerIndex: number): Action`

  Player matches the current bet amount. The engine automatically calculates the amount to call based on the current bet and player's stack.

- `Poker.Command.check(game: Poker.Game, playerIndex: number): Action`

  Player passes the action when no bet is required. Only available when the current bet equals the player's contribution.

- `Poker.Command.bet(game: Poker.Game, playerIndex: number, amount: number): Action`

  Player makes an initial bet in a betting round. The amount specifies the total bet size (not the amount above the current bet).

- `Poker.Command.raise(game: Poker.Game, playerIndex: number, amount: number): Action`

  Player increases the current bet. The amount specifies the total raise size (not the amount above the current bet).

- `Poker.Command.allIn(game: Poker.Game, playerIndex: number): Action`

  Player bets their entire remaining stack. This action needs to be implemented as a special case of bet/raise.

## Poker.Hand Notation

For a detailed explanation of the `Poker.Hand` notation, please refer to the [spec.md](spec.md) file.