@sportsbroker/firebase-structure 8.2.0 → 9.0.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.
@@ -15,18 +15,36 @@ export type BetEvent = {
15
15
 
16
16
  export type ResultsData = EventResultsData;
17
17
 
18
+ /**
19
+ * The ENGINE keys, exactly as the projection writes them. An engine is the machine that runs a game;
20
+ * many games run on one engine (a dozen prediction games ship today), so these are never game slugs.
21
+ */
18
22
  export enum GameEngineEnum {
23
+ /** The prediction family: a question set, one answer per question, scored onto a leaderboard. */
24
+ PREDICTION = "prediction",
25
+ /** Golden Coin: an in-play table game, settled once at full time. Question-less. */
26
+ COIN_PASS = "coin-pass",
27
+ /** Bingo: an in-play card game. Tiles cross off the live feed; settled at full time. */
28
+ BINGO = "bingo",
29
+ /**
30
+ * @deprecated A GAME slug, not an engine, from before engines and games were separated. No document
31
+ * has ever carried it in `engine`; the prediction games it named all project `PREDICTION`. Kept only
32
+ * so existing imports still compile.
33
+ */
19
34
  MATCH_PREDICTOR = "match-predictor",
35
+ /** @deprecated A game slug, not an engine - see {@link GameEngineEnum.MATCH_PREDICTOR}. */
20
36
  EDGE = "edge",
21
- /** Golden Coin: an in-play table game, settled once at full time. Question-less. */
22
- COIN_PASS = "coin-pass"
23
37
  }
24
38
 
25
39
  /**
26
- * The engines whose documents are question-and-prediction shaped. Golden Coin is deliberately not one
27
- * of them: its event document is a separate type, discriminated by `engine`.
40
+ * The engines whose documents are question-and-prediction shaped. The in-play engines are deliberately
41
+ * not among them: each has its own document type, discriminated by `engine`.
42
+ *
43
+ * The two deprecated slugs remain in the union so code written against them still compiles; only
44
+ * `PREDICTION` is ever written.
28
45
  */
29
46
  export type PredictionFamilyEngine =
47
+ | GameEngineEnum.PREDICTION
30
48
  | GameEngineEnum.MATCH_PREDICTOR
31
49
  | GameEngineEnum.EDGE;
32
50
 
@@ -1,18 +1,23 @@
1
1
  import type { GameEngineEnum } from "../bet-events";
2
- import type { QuestionResultValue } from "../events";
3
- import type { PoolTrack } from "../pools";
2
+ import type { QuestionResultValue } from "../events/events.model";
3
+ import type { PoolTrack } from "../pools/pools.model";
4
4
  import type { ISODate, UUID } from "../common";
5
5
 
6
+ /**
7
+ * The engine-blind part of a bet document: who staked, on which pool, and what it was paid.
8
+ *
9
+ * An engine's own state is added as a BLOCK named after the engine (`bingo`) in that engine's folder under
10
+ * `firestore/engines`. Golden Coin adds nothing - a coin bet is a seat, and the seat lives on the table.
11
+ */
6
12
  export type Bet = {
7
13
  id: string;
8
14
  userId: UUID;
9
15
  poolId: UUID;
10
16
  fixtureKickOffTime: ISODate;
17
+ /** The ENGINE key, never a game slug. The discriminant every bet union narrows on. */
11
18
  engine: GameEngineEnum;
12
- questionSetId: UUID;
13
19
  status: BetStatusEnum;
14
20
  betEventId: UUID;
15
- predictions: BetPredictionType[];
16
21
  /**
17
22
  * Cohort of this bet, inherited from its pool. Optional for wire back-compat: docs projected
18
23
  * before this field existed omit it and MUST be treated as `"real"`. New projections always set it.
@@ -23,6 +28,30 @@ export type Bet = {
23
28
  * bets are immutable once placed, so a single placement timestamp is enough.
24
29
  */
25
30
  betPlaceDate: ISODate;
31
+ /**
32
+ * What this bet was PAID when its pool settled, in the pool's currency. Present only once the bet is
33
+ * settled (`won` / `lost`), which is the only time it means anything: a bet still being played has
34
+ * not been paid, and publishing 0 for it would be indistinguishable from a bet that won nothing.
35
+ *
36
+ * It is here rather than on the leaderboard because a leaderboard shows a handful of positions while
37
+ * every player needs to be told what THEY got - including a player who took a prize without finishing
38
+ * anywhere near the top, which is exactly what a line prize is.
39
+ *
40
+ * A refunded pool pays each entry its own stake back and is reported the same way, so a client always
41
+ * has one number to show and never has to work out which case it is in.
42
+ */
43
+ prize?: number;
44
+ /**
45
+ * The question set the answers below belong to. OPTIONAL because only the prediction family projects
46
+ * it: a Golden Coin or Bingo bet has no questions, and declaring it required here made this type claim
47
+ * a field two of three engines have never written. `PredictionBet` requires it.
48
+ */
49
+ questionSetId?: UUID;
50
+ /**
51
+ * The player's answers. OPTIONAL for the same reason as `questionSetId` - see `PredictionBet`, which
52
+ * requires both.
53
+ */
54
+ predictions?: BetPredictionType[];
26
55
  };
27
56
 
28
57
  export enum BetStatusEnum {
@@ -34,13 +63,8 @@ export enum BetStatusEnum {
34
63
  LOCKED = "locked",
35
64
  }
36
65
 
37
- export type BetPredictionType = Prediction;
66
+ export type BetPredictionType = Prediction;
38
67
 
39
- /**
40
- * A prediction is in exactly one of two shapes: pending or settled.
41
- * Pending = no final result yet, or a doc projected before the settlement fields existed.
42
- * Consumers MUST treat the pending shape as pending, never as "wrong".
43
- */
44
68
  export type Prediction = PendingPrediction | SettledPrediction;
45
69
 
46
70
  export type BasePrediction = {
@@ -54,9 +78,7 @@ export type PendingPrediction = BasePrediction & {
54
78
  };
55
79
 
56
80
  export type SettledPrediction = BasePrediction & {
57
- /** Whether this answer was correct. Set only once the bet is settled (won/lost). */
58
81
  correct: boolean;
59
- /** Points this answer contributed to the bet score. */
60
82
  pointsAwarded: number;
61
83
  };
62
84
 
@@ -65,11 +87,11 @@ export enum MatchSideResultEnum {
65
87
  AWAY = "away",
66
88
  DRAW = "draw",
67
89
  }
90
+
68
91
  export enum YesNoResultEnum {
69
92
  YES = "yes",
70
93
  NO = "no",
71
94
  }
95
+
72
96
  export type BothSidesPositiveInteger = { home: number; away: number };
73
97
  export type PositiveInteger = number;
74
-
75
-
@@ -1 +1,17 @@
1
+ import type { BingoBet } from "../engines/bingo";
2
+ import type { CoinBet } from "../engines/coin";
3
+ import type { PredictionBet } from "../engines/prediction";
4
+
1
5
  export * from "./bets.model";
6
+ export * from "../engines/prediction";
7
+ export * from "../engines/coin";
8
+ export * from "../engines/bingo";
9
+
10
+ /**
11
+ * A bet document, in whichever shape its engine projects. Narrow on the ROOT `engine` field before reading
12
+ * the engine's block.
13
+ *
14
+ * The generic `Bet` is deliberately NOT a member: a union containing the unpinned parent matches
15
+ * everything and narrows to nothing.
16
+ */
17
+ export type AnyBet = PredictionBet | CoinBet | BingoBet;
@@ -0,0 +1,208 @@
1
+ import type { GameEngineEnum } from "../../bet-events";
2
+ import type { Bet } from "../../bets/bets.model";
3
+ import type { UUID } from "../../common";
4
+ import type { EventBase } from "../../events/events.model";
5
+ import type { Pool } from "../../pools/pools.model";
6
+
7
+ /**
8
+ * Bingo: every player gets a card of claims about the match, dealt from the pool's committed seed. Tiles
9
+ * cross themselves off the live feed, and prizes go to whoever completes lines - and the full house -
10
+ * first.
11
+ *
12
+ * The state splits by scope. What the GAME IS and what the MATCH has confirmed are match-level facts, so
13
+ * they live on the event. What has been CLAIMED is per pool. The CARD is per player, so it lives on the
14
+ * bet - which is also why nothing about a card is stored: it is derived from the seed and the bet's own
15
+ * id, and can be replayed by anyone once the seed is published.
16
+ */
17
+
18
+ /** A Bingo event document: the shape of the card, how the pot is cut, and what the feed has confirmed. */
19
+ export type BingoEvent = EventBase & {
20
+ engine: GameEngineEnum.BINGO;
21
+ bingo: BingoEventState;
22
+ };
23
+
24
+ export type BingoEventState = {
25
+ /** Cards are `gridSize` x `gridSize`. */
26
+ gridSize: number;
27
+ /** Which runs of crossed tiles count as a line. */
28
+ linesRule: BingoLinesRule;
29
+ /** How many tiles of each rarity every card holds. The three add up to the card exactly. */
30
+ rarityMixture: BingoRarityMixture;
31
+ /** Fewest players for the game to be played; below it every stake goes back in full. */
32
+ minCardsPerPool: number;
33
+ /** A cap on entries per pool, or null for no cap. */
34
+ maxCardsPerPool: number | null;
35
+ /**
36
+ * What completing lines pays, cheapest first: one entry per prize, each naming how many lines it is
37
+ * for and its share of the pot. A game with a single entry is the classic one-line game; two entries
38
+ * give the hall game everybody knows (one line, two lines, full house).
39
+ */
40
+ linePrizes: BingoLinePrize[];
41
+ /** Percent of the pot for the full house. The leaderboard takes whatever is left after all of it. */
42
+ fullHousePrizePercent: number;
43
+ /** Where the full house prize goes when nobody fills a card. */
44
+ unclaimedHouseShare: BingoUnclaimedHouseShare;
45
+ /**
46
+ * How many confirmed feed snapshots have moved the match on. Every crossing on every card is
47
+ * judged against this sequence, so a client can tell a stale view from a settled one.
48
+ */
49
+ seq: number;
50
+ /**
51
+ * What the feed has confirmed for each stat this game's tiles are written against, keyed by the
52
+ * stat's own key. A tile crosses when its rule is met by these numbers, so the same values explain
53
+ * every card on screen.
54
+ */
55
+ stats: Record<string, BingoSidedCount>;
56
+ };
57
+
58
+ /** Which runs of crossed tiles count as a line. */
59
+ export type BingoLinesRule = "rows-cols" | "rows-cols-diagonals";
60
+
61
+ /** Where the full house prize goes when nobody fills a card. */
62
+ export type BingoUnclaimedHouseShare = "closest-card" | "roll-to-leaderboard";
63
+
64
+ export type BingoLinePrize = {
65
+ /** How many completed lines this prize is for. */
66
+ lines: number;
67
+ /** Its share of the pot, as a percentage. */
68
+ percent: number;
69
+ };
70
+
71
+ export type BingoRarityMixture = {
72
+ common: number;
73
+ uncommon: number;
74
+ rare: number;
75
+ };
76
+
77
+ export type BingoSidedCount = {
78
+ home: number;
79
+ away: number;
80
+ };
81
+
82
+ /** A Bingo pool document: how many cards are in play, what has been claimed, and the fairness record. */
83
+ export type BingoPool = Pool & {
84
+ engine: GameEngineEnum.BINGO;
85
+ bingo: BingoBoard;
86
+ };
87
+
88
+ /**
89
+ * The board a player watches. The cards themselves are NOT here - each rides on its own bet document,
90
+ * because a pool of thousands of entries would otherwise publish a document nobody can read.
91
+ */
92
+ export type BingoBoard = {
93
+ /** Cards in the pool. */
94
+ cardCount: number;
95
+ /** Fewest cards for the pool to be played; below it every stake goes back in full. */
96
+ minCardsPerPool: number;
97
+ /** Whether the pool has reached that minimum. */
98
+ meetsMinimum: boolean;
99
+ gridSize: number;
100
+ linesRule: BingoLinesRule;
101
+ /** How this pool cuts its pot, as the game was configured when the pool opened. */
102
+ prizeSplit: BingoPrizeSplit;
103
+ /** What has been claimed so far, derived from the same cards and ledger the settlement pays from. */
104
+ claims: BingoClaims;
105
+ fairness: BingoFairness;
106
+ };
107
+
108
+ export type BingoPrizeSplit = {
109
+ /** One entry per rung of the ladder, in the game's order. */
110
+ lineTiers: BingoLinePrize[];
111
+ fullHousePercent: number;
112
+ unclaimedHouseShare: BingoUnclaimedHouseShare;
113
+ };
114
+
115
+ export type BingoClaims = {
116
+ /** One entry per rung of the ladder, in the same order as `prizeSplit.lineTiers`. */
117
+ lineTiers: BingoLineTierClaim[];
118
+ /** The full house, or null while nobody has filled a card. */
119
+ fullHouse: BingoClaim | null;
120
+ };
121
+
122
+ export type BingoLineTierClaim = {
123
+ lines: number;
124
+ percent: number;
125
+ /** Who claimed this rung, or null while it is unclaimed. */
126
+ claim: BingoClaim | null;
127
+ };
128
+
129
+ /**
130
+ * A claim as a screen needs it: when it was completed, how many cards share it, and a few of them to name.
131
+ * Never the whole list - a prize everybody completes would put thousands of identifiers in one document.
132
+ * The count is the part that matters anyway, because it decides what each winner takes.
133
+ */
134
+ export type BingoClaim = {
135
+ /** The feed sequence the claim was completed at, comparable with `BingoEventState.seq`. */
136
+ atSeq: number;
137
+ /** How many cards share this claim. */
138
+ count: number;
139
+ /** A few of the claiming bet ids - a sample, never the full set. */
140
+ sample: UUID[];
141
+ };
142
+
143
+ export type BingoFairness = {
144
+ version: string;
145
+ algorithm: string;
146
+ commitHash: string | null;
147
+ /** Published only once the pool has settled; null while the match runs. */
148
+ serverSeed: string | null;
149
+ };
150
+
151
+ /** A Bingo bet document: the player's own card. */
152
+ export type BingoBet = Bet & {
153
+ engine: GameEngineEnum.BINGO;
154
+ bingo: BingoCard;
155
+ };
156
+
157
+ /**
158
+ * One player's card, derived from the pool's seed and this bet's own id - nothing about it is stored, so
159
+ * nothing about it can go stale, and anyone can replay it once the seed is published.
160
+ */
161
+ export type BingoCard = {
162
+ /**
163
+ * Whether the card has been dealt. False only before the pool commits its seed, which is the one case
164
+ * where an entry has no card; `tiles` is then empty.
165
+ */
166
+ dealt: boolean;
167
+ gridSize: number;
168
+ linesRule: BingoLinesRule;
169
+ /** The tiles in grid order: cell `n` is row `n / gridSize`, column `n % gridSize`. */
170
+ tiles: BingoCardTile[];
171
+ /**
172
+ * How many tiles are crossed, present only once the bet is SETTLED. While the match runs this document
173
+ * is not rewritten, so a count written now would freeze at whatever was true when the entry was made -
174
+ * a card reading 0 all match. Until then a screen crosses the tiles itself from each tile's rule and
175
+ * the event's published stats; both sides read the same ledger, so they cannot disagree.
176
+ */
177
+ crossedCount?: number;
178
+ /** Completed lines, present only once the bet is settled. */
179
+ completedLines?: number;
180
+ /** The card's score with rarer tiles weighted higher, present only once the bet is settled. */
181
+ weightedScore?: number;
182
+ fairness: BingoFairness;
183
+ };
184
+
185
+ export type BingoCardTile = {
186
+ /** What the tile claims, in the words the player reads. */
187
+ prompt: string;
188
+ rarity: BingoTileRarity;
189
+ /** The match stat this tile is judged on, matching a key of `BingoEventState.stats`. */
190
+ statKey: string;
191
+ /** The rule that crosses the tile, so a screen can light it from the event's stats without a re-read. */
192
+ rule: BingoTileRule;
193
+ /** Whether the tile ended up crossed, present only once the bet is settled. */
194
+ crossed?: boolean;
195
+ };
196
+
197
+ export type BingoTileRarity = "common" | "uncommon" | "rare";
198
+
199
+ /**
200
+ * The claim a tile carries: an aggregate over one live stat, compared with a threshold. Only RISING
201
+ * operators are ever dealt, because a tile that could stop being true cannot be crossed off for good.
202
+ */
203
+ export type BingoTileRule = {
204
+ /** Which side of the stat is read: one team's count, or both added together. */
205
+ aggregate: "sum" | "home" | "away";
206
+ operator: ">=" | ">";
207
+ threshold: number;
208
+ };
@@ -0,0 +1,118 @@
1
+ import type { GameEngineEnum } from "../../bet-events";
2
+ import type { Bet } from "../../bets/bets.model";
3
+ import type { UUID } from "../../common";
4
+ import type { EventBase } from "../../events/events.model";
5
+ import type { Pool } from "../../pools/pools.model";
6
+
7
+ /**
8
+ * Golden Coin: a coin travels around a table of seats, advancing on every confirmed trigger in the match.
9
+ * Whoever holds it at half time and at full time takes the pot.
10
+ *
11
+ * The state splits by scope. The coin's TRAVEL is a match-level fact - every table of the match advances
12
+ * on the same pass count - so it lives on the event. The SEATING is per table, and a pool IS a table, so
13
+ * it lives on the pool. A bet is just a seat, so it carries no block of its own.
14
+ */
15
+
16
+ /** A Golden Coin event document: the config in force and what the match has confirmed. */
17
+ export type CoinEvent = EventBase & {
18
+ engine: GameEngineEnum.COIN_PASS;
19
+ coin: CoinEventState;
20
+ };
21
+
22
+ export type CoinEventState = {
23
+ /** Seats per table. A full table opens the next one. */
24
+ maxTableSize: number;
25
+ /**
26
+ * Fewest occupied seats for a table to be played. A table that stays below it when the match ends
27
+ * refunds every stake in full instead of paying a coin holder, so a player can see the threshold
28
+ * before paying. Together with `maxTableSize` this is the min and max of a table.
29
+ */
30
+ minTableSize: number;
31
+ /** The live stats that pass the coin. Any confirmed increment across them advances it. */
32
+ triggerStats: string[];
33
+ /** Percent of the pot the half-time holder takes; the full-time holder takes the remainder. */
34
+ halfTimeSplitPercent: number;
35
+ /**
36
+ * What the half-time share is worth when no trigger fired before the interval, so a player can see the
37
+ * rule before paying. `pay-holder` pays the seat the coin was drawn onto; `roll-to-full-time` adds that
38
+ * share to the full-time holder instead.
39
+ */
40
+ halfTimeShareWithoutTrigger: "pay-holder" | "roll-to-full-time";
41
+ /** Confirmed triggers so far in the match. */
42
+ passCount: number;
43
+ /** The count captured at half time, or null until the half-time fact arrives. */
44
+ halfTimePassCount: number | null;
45
+ /** The count captured at full time, or null until the match finishes. */
46
+ fullTimePassCount: number | null;
47
+ };
48
+
49
+ /** A Golden Coin pool document: the pool IS one table, and `coin` is that table. */
50
+ export type CoinPool = Pool & {
51
+ engine: GameEngineEnum.COIN_PASS;
52
+ coin: CoinTable;
53
+ };
54
+
55
+ /**
56
+ * A Golden Coin table. The pool IS the table: seats are taken in join order, the coin starts on a seat
57
+ * drawn from the committed seed, and it advances one seat per confirmed trigger.
58
+ */
59
+ export type CoinTable = {
60
+ tableNumber: number;
61
+ maxTableSize: number;
62
+ minTableSize: number;
63
+ meetsMinimum: boolean;
64
+ passCount: number;
65
+ seats: CoinSeat[];
66
+ /**
67
+ * The seat the coin was drawn onto, or null until the match starts. The draw is taken at the first
68
+ * trigger, from the committed seed.
69
+ */
70
+ startSeatNumber: number | null;
71
+ /** The seat holding the coin right now, or null while the coin has not been drawn or nobody sits. */
72
+ holdingSeatNumber: number | null;
73
+ /** Who held the coin at half time, or null until the half-time fact arrives. */
74
+ halfTimeHolder: CoinHolder | null;
75
+ /** Who held the coin at full time, or null until the match finishes. */
76
+ fullTimeHolder: CoinHolder | null;
77
+ outcome: CoinRoundOutcome;
78
+ fairness: CoinFairness;
79
+ };
80
+
81
+ /**
82
+ * How the round ended. `running` = still being played; `paid` = a holder took the pot; `refunded` = every
83
+ * stake went back in full (the coin never moved, or the table stayed below `minTableSize`); `no-payout` =
84
+ * there was nothing to pay.
85
+ */
86
+ export type CoinRoundOutcome = "running" | "paid" | "refunded" | "no-payout";
87
+
88
+ export type CoinFairness = {
89
+ version: string;
90
+ algorithm: string;
91
+ commitHash: string | null;
92
+ seatCountBasis: number | null;
93
+ /** Published only once the table has settled; null while the match runs. */
94
+ serverSeed: string | null;
95
+ };
96
+
97
+ export type CoinSeat = {
98
+ seatNumber: number;
99
+ betId: UUID;
100
+ userId: UUID;
101
+ displayName: string;
102
+ };
103
+
104
+ export type CoinHolder = {
105
+ seatNumber: number;
106
+ betId: UUID;
107
+ userId: UUID;
108
+ prize: number | null;
109
+ };
110
+
111
+ /**
112
+ * A Golden Coin bet: a seat at the table and nothing more. Everything about the seat - its number, whether
113
+ * it holds the coin - is on the pool document, because it is the TABLE that moves, not the bet. What this
114
+ * bet was paid is the generic `prize`.
115
+ */
116
+ export type CoinBet = Bet & {
117
+ engine: GameEngineEnum.COIN_PASS;
118
+ };
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Every engine's wire contract. One folder per engine; see README.md for the three rules an engine
3
+ * document follows and what adding an engine costs.
4
+ */
5
+ export * from "./prediction";
6
+ export * from "./coin";
7
+ export * from "./bingo";
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Compile-time proof that the document unions actually NARROW. No runtime, no test runner: if any of
3
+ * these stops narrowing, `tsc --noEmit` fails.
4
+ *
5
+ * This file exists because the previous `AnyPool = Pool | CoinPool` did not narrow at all - its
6
+ * discriminant sat at `event.engine`, and TypeScript does not narrow a union through a nested field, so
7
+ * every client had to cast. That was invisible until someone tried to read a pool.
8
+ */
9
+ import { GameEngineEnum } from "../bet-events";
10
+ import type { AnyBet } from "../bets";
11
+ import type { AnyEvent } from "../events";
12
+ import type { AnyPool } from "../pools";
13
+
14
+ /** Fails to compile if `T` is not exactly `true`. */
15
+ type Assert<T extends true> = T;
16
+ type Extends<A, B> = A extends B ? true : false;
17
+
18
+ export function narrowsEvent(event: AnyEvent): number {
19
+ if (event.engine === GameEngineEnum.BINGO) return event.bingo.gridSize;
20
+ if (event.engine === GameEngineEnum.COIN_PASS) return event.coin.passCount;
21
+ // The remaining arm is the prediction family, and only it has questions.
22
+ return event.questions.length;
23
+ }
24
+
25
+ export function narrowsPool(pool: AnyPool): number {
26
+ if (pool.engine === GameEngineEnum.BINGO) return pool.bingo.cardCount;
27
+ if (pool.engine === GameEngineEnum.COIN_PASS) return pool.coin.seats.length;
28
+ return pool.participants;
29
+ }
30
+
31
+ export function narrowsBet(bet: AnyBet): number {
32
+ if (bet.engine === GameEngineEnum.BINGO) return bet.bingo.tiles.length;
33
+ if (bet.engine === GameEngineEnum.COIN_PASS) return bet.prize ?? 0;
34
+ return bet.predictions.length;
35
+ }
36
+
37
+ /**
38
+ * The engine block never leaks into the generic type: a `Pool` is not assignable to a `BingoPool`, which
39
+ * is what stops one engine's vocabulary being read off another engine's document.
40
+ */
41
+ type BlocksStayEngineOwned = Assert<Extends<AnyPool, { engine: GameEngineEnum }>>;
42
+
43
+ export type { BlocksStayEngineOwned };
@@ -0,0 +1,44 @@
1
+ import type { PredictionFamilyEngine } from "../../bet-events";
2
+ import type { Bet, BetPredictionType } from "../../bets/bets.model";
3
+ import type { UUID } from "../../common";
4
+ import type { EventBase, EventQuestion, EventResultsData } from "../../events/events.model";
5
+ import type { Pool } from "../../pools/pools.model";
6
+
7
+ /**
8
+ * The prediction family: a question set, one prediction per question, and a leaderboard built from what
9
+ * each answer scored.
10
+ *
11
+ * This is the ENGINE THAT PREDATES the block convention, and it is the one exception to it: its fields sit
12
+ * at the document root rather than under an `prediction` block, because live clients already read them
13
+ * there. Typed exactly as it is written; new engines use a block instead (see the folder README).
14
+ */
15
+
16
+ /**
17
+ * A prediction event document.
18
+ *
19
+ * Kept under the name `Event` because that is what consumers import today. `PredictionEvent` is the same
20
+ * type under the name the other engines use.
21
+ */
22
+ export type Event = EventBase & {
23
+ engine: PredictionFamilyEngine;
24
+ questionSetId: UUID;
25
+ questions: EventQuestion[];
26
+ resultsData: EventResultsData;
27
+ };
28
+
29
+ export type PredictionEvent = Event;
30
+
31
+ /** A prediction pool: an engine-blind prize pot with a leaderboard, so there is no block to add. */
32
+ export type PredictionPool = Pool & {
33
+ engine: PredictionFamilyEngine;
34
+ };
35
+
36
+ /**
37
+ * A prediction bet: the player's answers, and what each one scored once the pool settled. Required here
38
+ * while optional on the generic `Bet`, because only this family carries them.
39
+ */
40
+ export type PredictionBet = Bet & {
41
+ engine: PredictionFamilyEngine;
42
+ questionSetId: UUID;
43
+ predictions: BetPredictionType[];
44
+ };
@@ -1,76 +1,30 @@
1
- import type {
2
- BetEventBettingStatusType,
3
- BetEventStatusType,
4
- GameEngineEnum,
5
- PredictionFamilyEngine,
6
- } from "../bet-events";
1
+ import type { BetEventBettingStatusType, BetEventStatusType, GameEngineEnum } from "../bet-events";
7
2
  import type { ISODate, UUID } from "../common";
8
3
 
9
4
  /**
10
- * An event document, in whichever shape its engine projects. Narrow on `engine` before reading:
11
- * a Golden Coin event carries no questions and a prediction event carries no coin state.
5
+ * The engine-blind part of an event document: what every engine's event carries, whatever game it runs.
6
+ *
7
+ * An engine's own state is added as a BLOCK named after the engine (`coin`, `bingo`) in that engine's
8
+ * folder under `firestore/engines`. Nothing engine-specific belongs here - see the engines README for why
9
+ * the discriminant has to stay at the root and the state has to stay out of it.
12
10
  */
13
- export type AnyEvent = Event | CoinEvent;
14
-
15
- export type Event = {
11
+ export type EventBase = {
16
12
  id: UUID;
17
13
  startDate: ISODate;
18
14
  status: BetEventStatusType;
19
15
  bettingStatus: BetEventBettingStatusType;
20
- /** Pinned to the prediction family so `AnyEvent` narrows on this field. */
21
- engine: PredictionFamilyEngine;
22
- questionSetId: UUID;
16
+ /** The ENGINE key, never a game slug. The discriminant every event union narrows on. */
17
+ engine: GameEngineEnum;
23
18
  name: string;
24
- questions: EventQuestion[];
25
- resultsData: EventResultsData;
26
19
  resultsUpdateReason: string | null;
27
20
  matchIds?: UUID[];
28
21
  };
29
22
 
30
23
  /**
31
- * A Golden Coin event document. The coin is a MATCH-level fact: every table of the match advances on
32
- * the same pass count, each from its own starting seat, so this document carries the counts and the
33
- * config in force while the per-table seating lives on the pool document (`Pool.coin`).
24
+ * The questions a prediction event asks. These live here rather than in the prediction folder because the
25
+ * taxonomy (question types, the stat keys a question can be written against) is shared vocabulary that
26
+ * other surfaces read; only the prediction DOCUMENT is engine-specific.
34
27
  */
35
- export type CoinEvent = {
36
- id: UUID;
37
- startDate: ISODate;
38
- status: BetEventStatusType;
39
- bettingStatus: BetEventBettingStatusType;
40
- engine: GameEngineEnum.COIN_PASS;
41
- name: string;
42
- resultsUpdateReason: string | null;
43
- matchIds?: UUID[];
44
- coin: CoinEventState;
45
- };
46
-
47
- export type CoinEventState = {
48
- /** Seats per table. A full table opens the next one. */
49
- maxTableSize: number;
50
- /**
51
- * Fewest occupied seats for a table to be played. A table that stays below it when the match ends
52
- * refunds every stake in full instead of paying a coin holder, so a player can see the threshold
53
- * before paying. Together with `maxTableSize` this is the min and max of a table.
54
- */
55
- minTableSize: number;
56
- /** The live stats that pass the coin. Any confirmed increment across them advances it. */
57
- triggerStats: string[];
58
- /** Percent of the pot the half-time holder takes; the full-time holder takes the remainder. */
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";
66
- /** Confirmed triggers so far in the match. */
67
- passCount: number;
68
- /** The count captured at half time, or null until the half-time fact arrives. */
69
- halfTimePassCount: number | null;
70
- /** The count captured at full time, or null until the match finishes. */
71
- fullTimePassCount: number | null;
72
- };
73
-
74
28
  export type EventQuestion = {
75
29
  eventQuestionId: UUID;
76
30
  questionType: QuestionTypeEnum;
@@ -86,6 +40,18 @@ export type EventQuestion = {
86
40
  pointsForExactHit: number;
87
41
  pointsForCorrectResult: number;
88
42
  pointsForWrongAnswer: number;
43
+ /**
44
+ * How the question is decided, for the types that need a rule. Present on `occurred-or-not`, which is
45
+ * settled by comparing a stat against a threshold; absent on the types whose answer IS the stat.
46
+ */
47
+ questionConfig?: EventQuestionConfig;
48
+ };
49
+
50
+ /** An aggregate over one live stat, compared with a threshold. */
51
+ export type EventQuestionConfig = {
52
+ aggregate: "sum" | "home" | "away";
53
+ operator: ">=" | ">" | "===" | "<=" | "<";
54
+ threshold: number;
89
55
  };
90
56
 
91
57
  export type EventResultsData = {
@@ -1 +1,18 @@
1
+ import type { BingoEvent } from "../engines/bingo";
2
+ import type { CoinEvent } from "../engines/coin";
3
+ import type { Event } from "../engines/prediction";
4
+
1
5
  export * from "./events.model";
6
+ export * from "../engines/prediction";
7
+ export * from "../engines/coin";
8
+ export * from "../engines/bingo";
9
+
10
+ /**
11
+ * An event document, in whichever shape its engine projects. Narrow on the ROOT `engine` field before
12
+ * reading: a Golden Coin event carries no questions and a prediction event carries no coin state.
13
+ *
14
+ * Every member pins `engine` to its own literal, which is what makes the narrowing work. The generic
15
+ * `EventBase` is deliberately NOT a member: a union containing the unpinned parent matches everything and
16
+ * narrows to nothing.
17
+ */
18
+ export type AnyEvent = Event | CoinEvent | BingoEvent;
@@ -1 +1,17 @@
1
+ import type { BingoPool } from "../engines/bingo";
2
+ import type { CoinPool } from "../engines/coin";
3
+ import type { PredictionPool } from "../engines/prediction";
4
+
1
5
  export * from "./pools.model";
6
+ export * from "../engines/prediction";
7
+ export * from "../engines/coin";
8
+ export * from "../engines/bingo";
9
+
10
+ /**
11
+ * A pool document, in whichever shape its engine projects. Narrow on the ROOT `engine` field before
12
+ * reading the engine's block.
13
+ *
14
+ * The generic `Pool` is deliberately NOT a member: a union containing the unpinned parent matches
15
+ * everything and narrows to nothing, which is what the previous `Pool | CoinPool` did.
16
+ */
17
+ export type AnyPool = PredictionPool | CoinPool | BingoPool;
@@ -1,34 +1,51 @@
1
- import { BetEventStatusType, GameEngineEnum } from "../bet-events";
1
+ import type { BetEventStatusType, GameEngineEnum } from "../bet-events";
2
2
  import type { ISODate, UUID } from "../common";
3
3
 
4
- export type PoolPayoutStructure = { [position: string]: number };
5
-
6
4
  /**
7
- * Which cohort a pool serves. `real` = real-money play (operator currency);
8
- * `demo` = play-money (currency `XTS`). Extensible (e.g. a future `freeroll`).
9
- * A player only ever sees pools whose track matches their session mode.
5
+ * The engine-blind part of a pool document: one operator's participation in one game on one match, with
6
+ * the money terms and the leaderboard.
7
+ *
8
+ * An engine's own state is added as a BLOCK named after the engine (`coin`, `bingo`) in that engine's
9
+ * folder under `firestore/engines` - never spilled into this document's root.
10
10
  */
11
+ export type Pool = {
12
+ id: UUID;
13
+ betEventId: UUID;
14
+ operatorId: UUID;
15
+ operatorCode: string;
16
+ payoutAmount?: number;
17
+ participants: number; // active bets count
18
+ entryFee: number;
19
+ currency: string;
20
+ /**
21
+ * The ENGINE key, never a game slug. Repeated here from `event.engine` because TypeScript narrows a
22
+ * union only on a discriminant at the ROOT: with the engine reachable solely through `event`, a client
23
+ * has to cast instead of narrow.
24
+ */
25
+ engine: GameEngineEnum;
26
+ event: PoolEvent;
27
+ leaderboard: PoolLeaderboard;
28
+ payoutStructure: PoolPayoutStructure;
29
+ prizeDistributionStrategy: PrizeDistributionStrategyEnum;
30
+ track?: PoolTrack;
31
+ };
32
+
33
+ export type PoolPayoutStructure = { [position: string]: number };
34
+
11
35
  export type PoolTrack = "real" | "demo";
12
36
 
13
37
  export enum PrizeDistributionStrategyEnum {
14
38
  WINNER_TAKES_ALL = "winner-takes-all",
15
39
  TOP_3 = "top-3",
16
40
  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
41
  COIN_HT_FT_SPLIT = "coin-ht-ft-split",
24
42
  }
25
43
 
44
+ /** A summary of the event the pool belongs to, so a pool renders without a second read. */
26
45
  export type PoolEvent = {
27
- /** Absent for engines that carry no question set (Golden Coin). */
28
46
  questionSetId?: UUID;
29
47
  status: BetEventStatusType;
30
48
  engine: GameEngineEnum;
31
- /** Slug of the game this pool's event belongs to (sports-games `games.slug`). */
32
49
  gameSlug: string;
33
50
  startDate?: ISODate;
34
51
  matchIds?: UUID[];
@@ -45,131 +62,3 @@ export type PoolLeaderboard = {
45
62
  prize: number | null;
46
63
  }[];
47
64
  };
48
-
49
- /**
50
- * A pool document, in whichever shape its engine projects. Narrow on `event.engine` before reading an
51
- * engine's own block: `Pool` carries only what EVERY engine has.
52
- */
53
- export type AnyPool = Pool | CoinPool;
54
-
55
- /** A Golden Coin pool: the generic pool plus the table state, which only this engine has. */
56
- export type CoinPool = Pool & { coin: CoinTable };
57
-
58
- /**
59
- * A Golden Coin table. The pool IS the table: seats are taken in join order, the coin starts on a seat
60
- * drawn from the table's own seed, and each confirmed trigger advances it. Present only on pools of the
61
- * `coin-pass` engine.
62
- *
63
- * How many tables an operator has open on an event, and how many players sit at them across all of
64
- * them, is read from these documents: query `Pools` by `betEventId` and `operatorId`, and the result
65
- * count is the number of tables while the sum of `participants` is the number of players. Every join
66
- * reprojects the pool document, so both stay live and can never disagree with the seats a player is
67
- * shown on a table.
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
-
101
- export type CoinTable = {
102
- /** Which table of this operator and event this is, counting from 1. */
103
- tableNumber: number;
104
- maxTableSize: number;
105
- /** Fewest occupied seats for this table to pay a holder; below it every stake is refunded in full. */
106
- minTableSize: number;
107
- /**
108
- * Does the table meet `minTableSize` right now? Decided by the engine, not by the client, so every
109
- * screen states the same verdict: false means that as things stand this table refunds instead of
110
- * paying a coin holder.
111
- */
112
- meetsMinimum: boolean;
113
- /** Confirmed triggers so far in the match, mirrored from the event for a self-contained table view. */
114
- passCount: number;
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
- */
120
- seats: CoinSeat[];
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. */
127
- holdingSeatNumber: number | null;
128
- /** Who held the coin at half time, or null until the half-time fact arrives. */
129
- halfTimeHolder: CoinHolder | null;
130
- /** Who held the coin at full time, or null until the match finishes. */
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;
136
- };
137
-
138
- export type CoinSeat = {
139
- seatNumber: number;
140
- betId: UUID;
141
- userId: UUID;
142
- displayName: string;
143
- };
144
-
145
- export type CoinHolder = {
146
- seatNumber: number;
147
- betId: UUID;
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;
155
- };
156
-
157
- export type Pool = {
158
- id: UUID;
159
- betEventId: UUID;
160
- operatorId: UUID;
161
- operatorCode: string;
162
- payoutAmount?: number;
163
- participants: number; // active bets count
164
- entryFee: number;
165
- currency: string;
166
- event: PoolEvent;
167
- leaderboard: PoolLeaderboard;
168
- payoutStructure: PoolPayoutStructure;
169
- prizeDistributionStrategy: PrizeDistributionStrategyEnum;
170
- /**
171
- * Cohort of this pool. Optional for wire back-compat: docs projected before this
172
- * field existed omit it and MUST be treated as `"real"`. New projections always set it.
173
- */
174
- track?: PoolTrack;
175
- };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sportsbroker/firebase-structure",
3
- "version": "8.2.0",
3
+ "version": "9.0.0",
4
4
  "description": "Firebase structure typings",
5
5
  "main": "index.d.ts",
6
6
  "repository": {