@sportsbroker/firebase-structure 8.1.0 → 8.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -19,7 +19,9 @@ export enum GameEngineEnum {
19
19
  MATCH_PREDICTOR = "match-predictor",
20
20
  EDGE = "edge",
21
21
  /** Golden Coin: an in-play table game, settled once at full time. Question-less. */
22
- COIN_PASS = "coin-pass"
22
+ COIN_PASS = "coin-pass",
23
+ /** Bingo: an in-play card game. Tiles cross off the live feed; settled at full time. */
24
+ BINGO = "bingo"
23
25
  }
24
26
 
25
27
  /**
@@ -23,6 +23,19 @@ export type Bet = {
23
23
  * bets are immutable once placed, so a single placement timestamp is enough.
24
24
  */
25
25
  betPlaceDate: ISODate;
26
+ /**
27
+ * What this bet was PAID when its pool settled, in the pool's currency. Present only once the bet is
28
+ * settled (`won` / `lost`), which is the only time it means anything: a bet still being played has
29
+ * not been paid, and publishing 0 for it would be indistinguishable from a bet that won nothing.
30
+ *
31
+ * It is here rather than on the leaderboard because a leaderboard shows a handful of positions while
32
+ * every player needs to be told what THEY got - including a player who took a prize without finishing
33
+ * anywhere near the top, which is exactly what a line prize is.
34
+ *
35
+ * A refunded pool pays each entry its own stake back and is reported the same way, so a client always
36
+ * has one number to show and never has to work out which case it is in.
37
+ */
38
+ prize?: number;
26
39
  };
27
40
 
28
41
  export enum BetStatusEnum {
@@ -10,7 +10,7 @@ import type { ISODate, UUID } from "../common";
10
10
  * An event document, in whichever shape its engine projects. Narrow on `engine` before reading:
11
11
  * a Golden Coin event carries no questions and a prediction event carries no coin state.
12
12
  */
13
- export type AnyEvent = Event | CoinEvent;
13
+ export type AnyEvent = Event | CoinEvent | BingoEvent;
14
14
 
15
15
  export type Event = {
16
16
  id: UUID;
@@ -46,19 +46,23 @@ export type CoinEvent = {
46
46
 
47
47
  export type CoinEventState = {
48
48
  /** Seats per table. A full table opens the next one. */
49
- tableSize: number;
49
+ maxTableSize: number;
50
50
  /**
51
51
  * Fewest occupied seats for a table to be played. A table that stays below it when the match ends
52
52
  * refunds every stake in full instead of paying a coin holder, so a player can see the threshold
53
- * before paying. Together with `tableSize` this is the min and max of a table.
53
+ * before paying. Together with `maxTableSize` this is the min and max of a table.
54
54
  */
55
55
  minTableSize: number;
56
56
  /** The live stats that pass the coin. Any confirmed increment across them advances it. */
57
57
  triggerStats: string[];
58
- /** Seats the coin advances per confirmed trigger. */
59
- advanceStep: number;
60
58
  /** Percent of the pot the half-time holder takes; the full-time holder takes the remainder. */
61
59
  halfTimeSplitPercent: number;
60
+ /**
61
+ * What the half-time share is worth when no trigger fired before the interval, so a player can see the
62
+ * rule before paying. `pay-holder` pays the seat the coin was drawn onto; `roll-to-full-time` adds that
63
+ * share to the full-time holder instead.
64
+ */
65
+ halfTimeShareWithoutTrigger: "pay-holder" | "roll-to-full-time";
62
66
  /** Confirmed triggers so far in the match. */
63
67
  passCount: number;
64
68
  /** The count captured at half time, or null until the half-time fact arrives. */
@@ -67,6 +71,76 @@ export type CoinEventState = {
67
71
  fullTimePassCount: number | null;
68
72
  };
69
73
 
74
+ /**
75
+ * A Bingo event document. Everything here is a MATCH-level fact shared by every pool of the match: the
76
+ * shape of the card the game deals, how the pot is cut, and what the live feed has confirmed so far.
77
+ * The per-player card lives on the bet document and the per-pool claims on the pool document, so a
78
+ * client reads this one to know what the game IS and what the match has done.
79
+ */
80
+ export type BingoEvent = {
81
+ id: UUID;
82
+ startDate: ISODate;
83
+ status: BetEventStatusType;
84
+ bettingStatus: BetEventBettingStatusType;
85
+ engine: GameEngineEnum.BINGO;
86
+ name: string;
87
+ resultsUpdateReason: string | null;
88
+ matchIds?: UUID[];
89
+ bingo: BingoEventState;
90
+ };
91
+
92
+ export type BingoEventState = {
93
+ /** Cards are `gridSize` x `gridSize`. */
94
+ gridSize: number;
95
+ /** Which runs of crossed tiles count as a line. */
96
+ linesRule: string;
97
+ /** How many tiles of each rarity every card holds. The three add up to the card exactly. */
98
+ rarityMixture: BingoRarityMixture;
99
+ /** Fewest players for the game to be played; below it every stake goes back in full. */
100
+ minCardsPerPool: number;
101
+ /** A cap on entries per pool, or null for no cap. */
102
+ maxCardsPerPool: number | null;
103
+ /**
104
+ * What completing lines pays, cheapest first: one entry per prize, each naming how many lines it is
105
+ * for and its share of the pot. A game with a single entry is the classic one-line game; two entries
106
+ * give the hall game everybody knows (one line, two lines, full house).
107
+ */
108
+ linePrizes: BingoLinePrize[];
109
+ /** Percent of the pot for the full house. The leaderboard takes whatever is left after all of it. */
110
+ fullHousePrizePercent: number;
111
+ /** Where the full house prize goes when nobody fills a card. */
112
+ unclaimedHouseShare: "closest-card" | "roll-to-leaderboard";
113
+ /**
114
+ * How many confirmed feed snapshots have moved the match on. Every crossing on every card is
115
+ * judged against this sequence, so a client can tell a stale view from a settled one.
116
+ */
117
+ seq: number;
118
+ /**
119
+ * What the feed has confirmed for each stat this game's tiles are written against, keyed by the
120
+ * stat's own key. A tile crosses when its rule is met by these numbers, so the same values explain
121
+ * every card on screen.
122
+ */
123
+ stats: Record<string, BingoSidedCount>;
124
+ };
125
+
126
+ export type BingoLinePrize = {
127
+ /** How many completed lines this prize is for. */
128
+ lines: number;
129
+ /** Its share of the pot, as a percentage. */
130
+ percent: number;
131
+ };
132
+
133
+ export type BingoRarityMixture = {
134
+ common: number;
135
+ uncommon: number;
136
+ rare: number;
137
+ };
138
+
139
+ export type BingoSidedCount = {
140
+ home: number;
141
+ away: number;
142
+ };
143
+
70
144
  export type EventQuestion = {
71
145
  eventQuestionId: UUID;
72
146
  questionType: QuestionTypeEnum;
@@ -14,6 +14,13 @@ export enum PrizeDistributionStrategyEnum {
14
14
  WINNER_TAKES_ALL = "winner-takes-all",
15
15
  TOP_3 = "top-3",
16
16
  TOP_5 = "top-5",
17
+ /**
18
+ * Golden Coin's only distribution: the half-time holder takes a configured percent of the pot and the
19
+ * full-time holder takes the remainder. Never operator-selectable - the split is a game setting, and
20
+ * which positions it pays is fixed by the engine. `payoutStructure` carries the two amounts, position
21
+ * `"1"` being the half-time share and `"2"` the full-time one.
22
+ */
23
+ COIN_HT_FT_SPLIT = "coin-ht-ft-split",
17
24
  }
18
25
 
19
26
  export type PoolEvent = {
@@ -59,10 +66,42 @@ export type CoinPool = Pool & { coin: CoinTable };
59
66
  * reprojects the pool document, so both stay live and can never disagree with the seats a player is
60
67
  * shown on a table.
61
68
  */
69
+ /**
70
+ * How a Golden Coin round ended, stated by the engine so no client works it out from pass counts.
71
+ * `running` = not settled yet; `paid` = the pot went to its holders; `refunded` = every stake went back
72
+ * in full (the coin never moved, or the table stayed below `minTableSize`); `no-payout` = there was
73
+ * nobody to pay.
74
+ */
75
+ export type CoinRoundOutcome = "running" | "paid" | "refunded" | "no-payout";
76
+
77
+ /**
78
+ * A Golden Coin table's provable-fairness record. The three values a player needs to check the draw:
79
+ *
80
+ * 1. `commitHash` is published when the table opens, before anybody pays. It is `sha256(serverSeed)`.
81
+ * 2. `serverSeed` appears only once the round has settled. Hash it and it must equal `commitHash`.
82
+ * 3. Re-run `algorithm` over the seed, the pool id and `seatCountBasis`; the index it yields must be the
83
+ * position of `startSeatNumber` in `seats`.
84
+ *
85
+ * Both steps run in a browser with WebCrypto (`crypto.subtle.digest` and `crypto.subtle.sign` with HMAC),
86
+ * so verification needs no library and no call back to us.
87
+ */
88
+ export type CoinFairness = {
89
+ /** Which ruleset this table was drawn under. Pinned per table, so an old table stays verifiable. */
90
+ version: string;
91
+ /** The formula to re-run, spelled out. */
92
+ algorithm: string;
93
+ /** The commitment. Null only on a table created before this record existed. */
94
+ commitHash: string | null;
95
+ /** How many occupied seats the draw ran against: the modulo base. Null until the draw is taken. */
96
+ seatCountBasis: number | null;
97
+ /** The revealed seed. Null while the round is running - revealing it early would give the draw away. */
98
+ serverSeed: string | null;
99
+ };
100
+
62
101
  export type CoinTable = {
63
102
  /** Which table of this operator and event this is, counting from 1. */
64
103
  tableNumber: number;
65
- tableSize: number;
104
+ maxTableSize: number;
66
105
  /** Fewest occupied seats for this table to pay a holder; below it every stake is refunded in full. */
67
106
  minTableSize: number;
68
107
  /**
@@ -73,14 +112,27 @@ export type CoinTable = {
73
112
  meetsMinimum: boolean;
74
113
  /** Confirmed triggers so far in the match, mirrored from the event for a self-contained table view. */
75
114
  passCount: number;
76
- /** Occupied seats in join order. Seat numbers count from 1 and never leave a gap. */
115
+ /**
116
+ * Occupied seats in join order. Seat numbers count from 1 and MAY leave a gap: the number a player
117
+ * joined on is theirs for the round, so a seat given up before kickoff goes missing from this list
118
+ * rather than renumbering the players behind it. Render by `seatNumber`, not by array position.
119
+ */
77
120
  seats: CoinSeat[];
78
- /** The seat holding the coin right now, or null while the table has no bet. */
121
+ /**
122
+ * The seat the coin was drawn onto, or null until the match starts. The draw is taken at the first
123
+ * whistle and written down, so this value never changes afterwards.
124
+ */
125
+ startSeatNumber: number | null;
126
+ /** The seat holding the coin right now, or null while the coin has not been drawn or nobody sits. */
79
127
  holdingSeatNumber: number | null;
80
128
  /** Who held the coin at half time, or null until the half-time fact arrives. */
81
129
  halfTimeHolder: CoinHolder | null;
82
130
  /** Who held the coin at full time, or null until the match finishes. */
83
131
  fullTimeHolder: CoinHolder | null;
132
+ /** How the round ended. `running` until the table settles. */
133
+ outcome: CoinRoundOutcome;
134
+ /** Everything needed to verify the draw. */
135
+ fairness: CoinFairness;
84
136
  };
85
137
 
86
138
  export type CoinSeat = {
@@ -94,6 +146,12 @@ export type CoinHolder = {
94
146
  seatNumber: number;
95
147
  betId: UUID;
96
148
  userId: UUID;
149
+ /**
150
+ * What this share is worth, in the pool's currency. Before the match ends it is the live answer ("you
151
+ * are holding a share worth this much"); once the table has settled it is exactly what was credited.
152
+ * Null when the amount is not resolvable yet.
153
+ */
154
+ prize: number | null;
97
155
  };
98
156
 
99
157
  export type Pool = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sportsbroker/firebase-structure",
3
- "version": "8.1.0",
3
+ "version": "8.3.0",
4
4
  "description": "Firebase structure typings",
5
5
  "main": "index.d.ts",
6
6
  "repository": {