tg-poker-engine

Shared TypeScript types for a Telegram poker product plus a small Texas Hold’em engine (deck, hand evaluation, and no-limit betting state machine).

Install

npm install tg-poker-engine

Package entry points

| Subpath | Contents | |--------|----------| | tg-poker-engine | Domain types (UserRole, TableStatus, …) and everything from ./tg-poker-engine (re-exported). | | tg-poker-engine/tg-poker-engine | Poker engine only (cards, evaluation, Hold’em). | Both paths resolve to the same compiled modules under dist/.

Card notation

Cards are strings: rank + suit.

• Ranks: 2–9, T (ten), J, Q, K, A (ace high = 14 internally).
• Suits: c clubs, d diamonds, h hearts, s spades.

Example: "Ah" is ace of hearts.

Poker engine API (high level)

Cards

• fullDeck() — 52 cards in rank/suit order.
• shuffle(items, rng?) — Fisher–Yates; optional rng (defaults to Math.random).
• rankOf(card), suitOf(card) — parse a card string.

Hand evaluation

• scoreFiveCards(cards) — score vector for exactly five cards (straight wheel A–5 handled).
• bestScoreFrom7(cards) — best five from seven (Hold’em).
• compareScores(a, b) — lexicographic compare; positive if a wins.
• describeScore(score) — human-readable label.

Hold’em

• startHoldemHand({ seats, buttonSeat, smallBlind, bigBlind, handSeq, rng? }) — new hand: blinds, deal, toActSeat set.
• applyHoldemAction(state, seatIndex, action) — fold / check / call / bet / raise_to; mutates state.
• holdemPublicSnapshot(state) — table-safe view (optionally revealedHoles, awardedPot when complete).
• viewerHoleCards(state, seatIndex) — hole cards for one seat.
• forceFoldPlayer(state, seatIndex) — fold out of turn (e.g. disconnect).
• nextButtonSeat(occupiedSorted, currentButton) — rotate button among occupied seats.

Client actions (HoldemClientAction):

• { type: "fold" }
• { type: "check" } — only when not facing a bet.
• { type: "call" }
• { type: "bet", amount } — first aggression on a street (minimum = big blind when maxStreetBet === 0).
• { type: "raise_to", amount } — total street commitment after the action; must beat current max and satisfy minRaise unless shoving.

Build from source

npm install
npm run build

Output is written to dist/ (CommonJS require / exports, with .d.ts types).

Publishing checklist

1. Set name in package.json to the scoped name you own on npm (or unscope it).
2. Set license (default in this repo is UNLICENSED; use MIT or another SPDX id and add a LICENSE file if you open-source it).
3. Bump version, then run npm publish. Scoped packages default to private on npm; this repo sets publishConfig.access = "public" so a plain npm publish is enough (or use npm publish --access public once if you remove that field). prepublishOnly runs npm run build automatically so dist/ matches sources.
4. The "files" field limits the tarball to dist/; npm still ships README.md and package.json automatically.

Review notes (correctness & limits)

The public functions are internally consistent: five-card scoring, wheel straight, seven-card best hand, and Hold’em blind / deal order (including heads-up) match usual rules.

Limits you should know before production use:

1. Single main pot only — there are no side pots. If multiple players are all-in for different amounts, chip accounting is not split into side pots.
2. No card validation — rankOf / evaluation assume valid "[23456789TJQKA][cdhs]" strings; garbage input can yield NaN or nonsense scores.
3. Mutating state — applyHoldemAction and related helpers mutate the passed HoldemState. Clone first if you need time-travel or optimistic UI rollback.
4. Module format — compiled output is CommonJS; modern bundlers and recent Node versions still consume this fine via the exports map; if you need pure ESM-only publishing, adjust tsconfig / package.json "type" separately.

There is no single “incorrect method” in the sense of a wrong signature; the important caveat is side-pot absence for real-money or full tournament logic.

License

See package.json field "license" (set by the package maintainer).