# Game Platform Adapter Contract

The `GamePlatformAdapter` defines the integration points that casino hosts must
implement so the original games package can interact with their wallet,
database, and notification stack without depending on the legacy
`Users/Rule` module.

## Usage

```js
const OriginalGames = require('path-to-packages/original-games');
const { GamePlatformAdapter } = OriginalGames;

class MyPlatformAdapter extends GamePlatformAdapter {
  // ... implement abstract methods ...
}

OriginalGames.setGamePlatformAdapter(new MyPlatformAdapter());
```

If no adapter is injected, the games package automatically falls back to a
`UsersRuleAdapter` that proxies every call to `backend/Users/Rule` for backward
compatibility.

## Methods

All methods are asynchronous and accept Node-style callbacks. Hosts can choose
whether the implementation performs direct database work, proxies to remote
services, or enqueues background jobs.

| Method | Purpose |
| ------ | ------- |
| `getClientCoinCredit(userId, coin, callback)` | Fetch spendable balance for the requested currency. Return `false` when the currency is unsupported. |
| `makeBetBeforePlay(data, userId, game, callback)` | Persist a bet stub and resolve with a game instance identifier. |
| `reduceBalance(userId, amount, coin, callback)` | Debit the player's wallet before gameplay. |
| `rakeAmount(userId, amount, coin)` | Apply rake or fee logic. Fire-and-forget. |
| `addBankRoll(game, amount, coin, context, callback)` | Move funds into the house bankroll for the game round. `context` forwards extra metadata such as sockets or bot flags. |
| `updateBetAfterFinish(gid, userId, profit, result, hash, callback)` | Finalise bet records with round outcomes. |
| `getNameById(userId, callback)` | Resolve the public name for UI broadcasts. |
| `updateProfit(isBot, isWin, userId, amount, coin, callback)` | Track per-round profitability for real users and seeded bots. |
| `addBalance(userId, amount, coin, callback)` | Credit the player's wallet after a win. |
| `reduceBankRoll(game, amount, coin, callback)` | Remove funds from the bankroll after payouts. |
| `updateMaxProfit(userId, profit, coin, callback)` | Update high-water mark for user profit. |
| `updateMaxProfitinr(userId, profit, coin, callback)` | INR-specific variant of the max profit tracker. |
| `getUserLastProfit(userId, callback)` | Retrieve the most recent profit entry for streak checks. |
| `checkMaxProfit(userId, coin, callback)` | Validate whether the user can continue to profit in the requested currency. |
| `getBots(game, hour, callback)` | Provide bot definitions for automatic seeding during off-hours. |
| `getUserInfo(userId, callback)` | Fetch core profile information (name, avatar, two-factor status, etc.). |
| `getUserOrBot(userId, botInfo, callback)` | Resolve an in-memory bot or a real user row prior to joining a table. |

Implementations must always invoke the supplied callbacks. Throwing inside these
methods will bubble up to the game server and may interrupt rounds.

## Migration Guidance

1. Implement a class that extends `GamePlatformAdapter` and plug it in via
   `OriginalGames.setGamePlatformAdapter()` during your service bootstrap.
2. Wire each method to your own persistence or wallet systems.
3. Optional: remove the legacy `Users/Rule` dependency after the adapter covers
   every needed capability.

The adapter is also exported as `OriginalGames.UsersRuleAdapter` for hosts that
wish to decorate the default behaviour instead of re-implementing everything
from scratch.