@octane-rgs/live

SDK for live/dealer games on Octane RGS. Handles sessions, betting, round management, settlement, and queries.

Install

npm install @octane-rgs/live

Quick Start

import { OctaneLiveClient } from "@octane-rgs/live";

const rgs = new OctaneLiveClient({
  baseUrl: "https://staging.octanestudios.ai",
  apiKey: "your-api-key",
});

const { sessionToken, tableSessionId } = await rgs.launch({
  externalPlayerId: "player-123",
  tableSessionId: crypto.randomUUID(),
  tableGameCode: "baccarat",
  currency: "USD",
});

const { roundId } = await rgs.createRound({
  tableSessionId,
  bettingOpenAt: new Date().toISOString(),
  bettingClosedAt: new Date(Date.now() + 30_000).toISOString(),
});

await rgs.placeBet({
  sessionToken,
  roundId,
  bets: [{ betOption: "player", amount: 1000 }],
  requestId: crypto.randomUUID(),
});

await rgs.settle({
  roundId,
  gameType: "baccarat",
  multipliers: [
    { betOption: "player", multiplier: 2 },
    { betOption: "banker", multiplier: 0 },
  ],
});

API

Sessions

| Method | Description | |--------|-------------| | launch(params, apiKey?) | Create a player session | | operatorInfo(apiKey) | Get operator details and bet config | | getBalance(sessionToken) | Get player balance from operator wallet | | getPlayerSession(sessionToken) | Get session details | | redeemLaunch({ sessionToken }) | Single-use exchange of a launch URL token for the session; throws LaunchRedeemError (LAUNCH_ALREADY_REDEEMED, LAUNCH_EXPIRED) | | markStarted(sessionToken) | Mark session as started | | realityCheck(sessionToken) | Session duration, total wagered, net position |

Table Sessions

| Method | Description | |--------|-------------| | upsertTable(params) | Create or update a table session | | endTable(tableSessionId, endedAt) | End a table session | | getTableSession(tableSessionId) | Get table session details | | lobbies(publicOnly?) | List active table sessions | | activeByGame(gameCode) | Find active table by game code | | activeByTableCode(tableCode) | Find active table by table code | | activeByAvatar(slug) | Deprecated: use activeByTableCode | | activeByAvatarGame(avatarName, gameName) | Find active table by avatar + game | | updateRoomStates(params) | Batch update room states (active/dormant) | | cleanup(params) | Find and mark stale sessions as dead |

Rounds

| Method | Description | |--------|-------------| | createRound(params) | Create a new betting round with betting window | | listRounds(tableSessionId, order?) | List rounds for a table session | | findRound(params) | Find a round by ID or number | | updateRoundOutcome(roundId, data) | Store game outcome data on a round |

Betting

Requests must be serialized per player per round. placeBet, doubleBet, and undoBet read-then-write the player's action stack without server-side locking. Concurrent requests with different requestId values will produce undefined financial outcomes (double refunds, misordered operations). Queue mutations client-side and await each response before sending the next request.

| Method | Description | |--------|-------------| | placeBet(params) | Place a bet on an open round | | doubleBet(params) | Double existing bets on a round | | undoBet(params) | Undo the last bet action | | settle(params) | Settle a round with integer multipliers. Returns payouts: SettlementPayoutRow[] for status === "settled", with one row per (player, betOption). | | voidRound(roundId) | Void a round and refund all bets |

Live Actions

Used by Pragmatic-style live games where each seated player makes independent decisions inside a single shared round (e.g. Infinite Blackjack). The bet itself goes through placeBet; subsequent decisions go through liveAction. For double, RGS runs the financial side through the regular double pipeline with the betting-window check suppressed — same idempotency / operator integration as doubleBet, but without the wall-clock check (live decisions happen during dealing, past bettingClosedAt). Retries with the same requestId are safe across both halves. Endpoint always returns HTTP 200; branch on the status field.

| Method | Description | |--------|-------------| | liveAction(params) | Record hit / stand / double on an open round. Idempotent on requestId. | | closeDecisionStep({ roundId, step }) | Table owner closes a decision step when its window ends; returns { hit } to say whether to draw. |

The community card draw lives on the streamer's video feed and is fanned out via the video:start Ably broadcast — RGS never sees per-player cards. The local resolver reconstructs each player's hand from the round's gameRoundData.community[] array plus the persisted (step, action) log alone.

Actions are accepted only for the step the table owner currently has open, and a player must hit on every earlier step; skipping a step counts as standing. The result discriminates on status: recorded, duplicate, round_not_open, no_bet, already_finalised, double_not_first, or step_not_open. See the main RGS README's "Live Games with Per-Player Outcomes" section for the full settlement flow including local per-player resolver modules.

Queries

| Method | Description | |--------|-------------| | roundWinners(roundId) | Get winners for a round | | lastPayout(sessionToken) | Get last payout amount | | betStatistics(roundId, sides) | Get bet distribution stats | | playerHistory(sessionToken, limit?, offset?) | Get player bet/payout history | | roundHistory(tableSessionId, limit?) | Get round history for a table |

Free Rounds

| Method | Description | |--------|-------------| | getFreeRounds(playerId, gameCode?) | Get active free round grant |

Self-Exclusion

| Method | Description | |--------|-------------| | excludePlayer(params) | Self-exclude a player for a duration | | getExclusionStatus(externalPlayerId) | Check exclusion status |

Changes

• 1.3.0: core 1.3.0. redeemLaunch({ sessionToken }) and LaunchRedeemError for single-use, time-boxed launch tokens.
• 1.2.0 (breaking): core 1.2.0. roundWinners entries and roundDetails players replace playerSessionId with playerRef, a stable pseudonym. The session id is the player's sessionToken, a bearer credential, so it is no longer returned by query endpoints.
• 1.1.6: core 1.1.4
• 1.1.0: remainingBalance is now optional on bet results (omitted when the wallet confirmed the debit but its balance could not be read; refresh the balance), and balance fields may be null.