@sportsbroker/firebase-structure 9.0.0 → 9.1.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.
package/README.md
CHANGED
|
@@ -209,3 +209,66 @@ In queries section besides logical types sections level there is introduced also
|
|
|
209
209
|
## Firestore
|
|
210
210
|
|
|
211
211
|
In **firestore** directory, we keep types for document structures that are used in **Firestore** DB which is more efficient than RealtimeDB. Convention is one file for one Firestore collection that exports types for this collection document.
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
## Prepared release: 9.1.0 Power Cards
|
|
215
|
+
|
|
216
|
+
This additive contract adds an optional public `powerCards` offer to prediction events and an optional owner-only `entryData` proof to prediction bets. Existing documents remain valid. Final prediction answers may include `basePoints`, `effectDelta` and `cardId`; pending answers have no final score breakdown. Cards stay in the prediction namespace, not in generic event/bet types.
|
|
217
|
+
|
|
218
|
+
Validate with `npx tsc --noEmit`. The compilation includes `tests/prediction-power-cards.contract.ts`, which verifies backward compatibility and prevents private assignments from becoming event fields. Prepare the artifact with `npm pack --ignore-scripts --pack-destination release-artifacts`; `.npmignore` excludes executable JavaScript and test fixtures. Every consumer import/re-export must use `import type` / `export type`.
|
|
219
|
+
|
|
220
|
+
Publication is deferred. Once the release review and npm authentication are available, publish version 9.1.0, update backend's exact dependency and lockfile from the registry, then replace its temporary `PredictionCardEventSnapshot` bridge with the package `Event` type. Run backend typecheck, unit tests and a compiled process startup before deploying the backend. Do not replace the lockfile dependency with a local tarball path.
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
Prepared artifact: `release-artifacts/sportsbroker-firebase-structure-9.1.0.tgz`.
|
|
224
|
+
Verify it with `shasum -a 256 -c release-artifacts/SHA256SUMS`. After authentication and release review, publish this exact artifact with `npm publish ./release-artifacts/sportsbroker-firebase-structure-9.1.0.tgz`. Verify `npm view @sportsbroker/firebase-structure@9.1.0 version` before updating consumers. The artifact directory is local and ignored by Git; regenerate it from the reviewed sources when necessary.
|
|
225
|
+
|
|
226
|
+
### Configurable prediction clients
|
|
227
|
+
|
|
228
|
+
Keep `engine: "prediction"` for Match Predictor, Edge, Beat the Ref and other configurations.
|
|
229
|
+
Choose the interaction flow from the frozen event offer: no `powerCards` means ordinary prediction;
|
|
230
|
+
`hand.mode === "choose"` adds selection of `hand.count` copies; `"use-all"` skips selection and assigns
|
|
231
|
+
all offered copies. Card identity is `cardId` (a copy), not its name or `definitionId`. Branding is separate
|
|
232
|
+
from these rules. Do not infer a game identity from its effect types.
|
|
233
|
+
|
|
234
|
+
`PredictionPowerCardEffect` is a discriminated union of supported effect/version pairs. In version 1,
|
|
235
|
+
boost uses `multiplier`, shield uses `floorPct`, and outcome-points uses `exact`, `correct`, `wrong`.
|
|
236
|
+
The catalog's shield `percent` field is not the Firestore parameter. Handle unknown effects/versions as
|
|
237
|
+
unsupported data rather than falling back to an ordinary predictor. Adding a game that reuses existing
|
|
238
|
+
effects needs no new union member; adding a new mechanic needs a reviewed contract and client support.
|
|
239
|
+
|
|
240
|
+
`PredictionAnswer` separates pending answers from settled answers. A settled card breakdown supplies
|
|
241
|
+
both `basePoints` and `effectDelta`; `cardId` identifies the applied copy when present. Older settled
|
|
242
|
+
answers without a breakdown remain supported. Missing points are pending, not zero.
|
|
243
|
+
|
|
244
|
+
This remains a types-only package. Use `import type` / `export type`; it supplies no executable enums,
|
|
245
|
+
validators or scoring functions. Treat network/Firestore input as unknown until runtime-validated.
|
|
246
|
+
TypeScript cannot check point ranges, valid copy/target assignments or the uniqueness of IDs.
|
|
247
|
+
|
|
248
|
+
New event projections include `powerCards.play`. With `status: "ready"`, each copy has explicit
|
|
249
|
+
eligible `eventQuestionId` targets and server-computed `exact`, optional `correct` (partial-result), and
|
|
250
|
+
`wrong` potential points. Missing targets are not selectable. `status: "unavailable"` blocks new card
|
|
251
|
+
submission but does not hide event status, existing bets or refunds. Older documents can omit `play`;
|
|
252
|
+
show a loading/unavailable state until refreshed instead of guessing eligibility or silently skipping cards.
|
|
253
|
+
The offer's `hand` determines how many different copies/targets must be chosen. Backend admission
|
|
254
|
+
remains authoritative, including one card per target. `play` is read-only presentation and is not part
|
|
255
|
+
of the bet request or accepted card proof.
|
|
256
|
+
|
|
257
|
+
For a chosen placement, potential maximum is the sum of the largest reachable reward per question:
|
|
258
|
+
use the target's point table for carded questions and the question's own point table otherwise. Only
|
|
259
|
+
`occurrence-count-for-sides` has a partial-result tier; other question types use exact/wrong. Values are
|
|
260
|
+
potential points, never money or awarded totals. Final awarded points come from the settled bet.
|
|
261
|
+
The event's `resultsData` supplies typed current answers and `isFinal`; a non-final value is provisional,
|
|
262
|
+
not a confirmed negative answer. There is no server-certified live per-player points block in this release.
|
|
263
|
+
A live result screen can compare an accepted prediction with the typed result, then look up the
|
|
264
|
+
corresponding potential points in the frozen target table. For booleans, totals and home/draw/away,
|
|
265
|
+
compare values directly; for score pairs compare both sides first, then the home/draw/away result if
|
|
266
|
+
a distinct partial tier exists. Card-free questions use their base point table. A missing result stays
|
|
267
|
+
pending; any computed running score must be labelled provisional and is never a payout authority.
|
|
268
|
+
Final score and payout follow settlement. No dynamic
|
|
269
|
+
layout contract is promised: use game identity for branding and the offer for interaction behavior.
|
|
270
|
+
|
|
271
|
+
The outcome-key enum includes the canonical soccer fields actually emitted by the backend, including
|
|
272
|
+
`scoring_teams`. This identifies a question's source; it does not guarantee provider coverage for every
|
|
273
|
+
competition or implement unsupported referee signals. Firestore security rules, not these types,
|
|
274
|
+
enforce owner-only access to accepted card assignments.
|
|
@@ -16,6 +16,13 @@ export type Bet = {
|
|
|
16
16
|
fixtureKickOffTime: ISODate;
|
|
17
17
|
/** The ENGINE key, never a game slug. The discriminant every bet union narrows on. */
|
|
18
18
|
engine: GameEngineEnum;
|
|
19
|
+
/**
|
|
20
|
+
* Catalogue slug of the GAME the bet was placed in (`match-predictor`, `golden-coin`), the same value
|
|
21
|
+
* the pool carries in `event.gameSlug`. One engine runs many games, so a client grouping a player's bets
|
|
22
|
+
* by game cannot get there from `engine` alone. Optional for wire back-compat: docs projected before
|
|
23
|
+
* this field existed omit it. New projections always set it.
|
|
24
|
+
*/
|
|
25
|
+
gameSlug?: string;
|
|
19
26
|
status: BetStatusEnum;
|
|
20
27
|
betEventId: UUID;
|
|
21
28
|
/**
|
|
@@ -1,5 +1,7 @@
|
|
|
1
|
+
import type { PredictionPowerCards, PredictionPowerCardEntryData, PredictionCardScoreBreakdown } from "./power-cards";
|
|
2
|
+
export type { PredictionPowerCardPlay, PredictionPowerCardTarget, PredictionPowerCards, PredictionPowerCardCopy, PredictionPowerCardEffect, PredictionPowerCardAssignment, PredictionPowerCardEntryData, PredictionCardScoreBreakdown } from "./power-cards";
|
|
1
3
|
import type { PredictionFamilyEngine } from "../../bet-events";
|
|
2
|
-
import type { Bet,
|
|
4
|
+
import type { Bet, PendingPrediction, SettledPrediction } from "../../bets/bets.model";
|
|
3
5
|
import type { UUID } from "../../common";
|
|
4
6
|
import type { EventBase, EventQuestion, EventResultsData } from "../../events/events.model";
|
|
5
7
|
import type { Pool } from "../../pools/pools.model";
|
|
@@ -24,6 +26,8 @@ export type Event = EventBase & {
|
|
|
24
26
|
questionSetId: UUID;
|
|
25
27
|
questions: EventQuestion[];
|
|
26
28
|
resultsData: EventResultsData;
|
|
29
|
+
/** Omitted on pre-card and card-free event documents. */
|
|
30
|
+
powerCards?: PredictionPowerCards;
|
|
27
31
|
};
|
|
28
32
|
|
|
29
33
|
export type PredictionEvent = Event;
|
|
@@ -37,8 +41,16 @@ export type PredictionPool = Pool & {
|
|
|
37
41
|
* A prediction bet: the player's answers, and what each one scored once the pool settled. Required here
|
|
38
42
|
* while optional on the generic `Bet`, because only this family carries them.
|
|
39
43
|
*/
|
|
44
|
+
/** Final breakdowns are atomic. Old settled documents remain valid without them. */
|
|
45
|
+
type WithoutCardScoreBreakdown = { basePoints?: never; effectDelta?: never; cardId?: never };
|
|
46
|
+
export type PredictionAnswer =
|
|
47
|
+
| (PendingPrediction & WithoutCardScoreBreakdown)
|
|
48
|
+
| (SettledPrediction & (PredictionCardScoreBreakdown | WithoutCardScoreBreakdown));
|
|
49
|
+
|
|
40
50
|
export type PredictionBet = Bet & {
|
|
41
51
|
engine: PredictionFamilyEngine;
|
|
42
52
|
questionSetId: UUID;
|
|
43
|
-
predictions:
|
|
53
|
+
predictions: PredictionAnswer[];
|
|
54
|
+
/** Owner-only, never part of the public event offer. */
|
|
55
|
+
entryData?: PredictionPowerCardEntryData;
|
|
44
56
|
};
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/** Immutable, public offer frozen when a prediction event is created. */
|
|
2
|
+
export type PredictionPowerCards = {
|
|
3
|
+
schemaVersion: 1;
|
|
4
|
+
packId: string;
|
|
5
|
+
packRevisionId: string;
|
|
6
|
+
name: string;
|
|
7
|
+
offer: { kind: "all"; version: 1 };
|
|
8
|
+
hand: { mode: "choose"; count: number } | { mode: "use-all" };
|
|
9
|
+
cards: PredictionPowerCardCopy[];
|
|
10
|
+
/** New projections provide server-derived targets and potential points; older documents may omit them. */
|
|
11
|
+
play?: PredictionPowerCardPlay;
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
/** Supported wire effects. Catalog shield `percent` is projected as `floorPct`.
|
|
15
|
+
* New mechanics add an explicit effect/version branch; game names never select behavior.
|
|
16
|
+
* Validate unknown Firestore data at the consumer boundary before narrowing this union.
|
|
17
|
+
*/
|
|
18
|
+
export type PredictionPowerCardEffect =
|
|
19
|
+
| { effect: "boost"; effectVersion: 1; params: { multiplier: number } }
|
|
20
|
+
| { effect: "shield"; effectVersion: 1; params: { floorPct: number } }
|
|
21
|
+
| { effect: "outcome-points"; effectVersion: 1; params: { exact: number; correct: number; wrong: number } };
|
|
22
|
+
|
|
23
|
+
export type PredictionPowerCardCopy = {
|
|
24
|
+
cardId: string;
|
|
25
|
+
definitionId: string;
|
|
26
|
+
cardRevisionId: string;
|
|
27
|
+
name: string;
|
|
28
|
+
description?: string;
|
|
29
|
+
assetId?: string;
|
|
30
|
+
imageUrl?: string;
|
|
31
|
+
} & PredictionPowerCardEffect;
|
|
32
|
+
|
|
33
|
+
/** Accepted server-enriched assignment. Private to the owning player's bet document. */
|
|
34
|
+
export type PredictionPowerCardAssignment = PredictionPowerCardCopy & {
|
|
35
|
+
packId: string;
|
|
36
|
+
packRevisionId: string;
|
|
37
|
+
eventQuestionId: string;
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
/** Absent on old and card-free bets. Never publish on event/pool/leaderboard documents. */
|
|
41
|
+
export type PredictionPowerCardEntryData = {
|
|
42
|
+
powerCardsVersion: 1;
|
|
43
|
+
cards: PredictionPowerCardAssignment[];
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
/** Present only for final answers of settled bets using the versioned card rules. */
|
|
47
|
+
export type PredictionCardScoreBreakdown = {
|
|
48
|
+
basePoints: number;
|
|
49
|
+
effectDelta: number;
|
|
50
|
+
cardId?: string;
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
/** Potential points, not awarded points. Omitted correct means no distinct partial-result tier. */
|
|
54
|
+
export type PredictionPowerCardTarget = {
|
|
55
|
+
eventQuestionId: string;
|
|
56
|
+
exact: number;
|
|
57
|
+
correct?: number;
|
|
58
|
+
wrong: number;
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
/** Eligibility is engine-owned. Never offer targets that are missing from this list. */
|
|
62
|
+
export type PredictionPowerCardPlay =
|
|
63
|
+
| { status: "ready"; cards: { cardId: string; targets: PredictionPowerCardTarget[] }[] }
|
|
64
|
+
| { status: "unavailable"; reason: "unsupported-configuration" };
|
|
@@ -83,6 +83,11 @@ export enum QuestionTypeEnum {
|
|
|
83
83
|
|
|
84
84
|
export enum InGameEventKey {
|
|
85
85
|
SCORE = "score",
|
|
86
|
+
SCORING_TEAMS = "scoring_teams",
|
|
87
|
+
RED_CARDS = "red_cards",
|
|
88
|
+
YELLOW_CARDS = "yellow_cards",
|
|
89
|
+
PENALTIES_TAKEN = "penalties_taken",
|
|
90
|
+
TACKLES_WON = "tackles_won",
|
|
86
91
|
GOAL = "goal",
|
|
87
92
|
CORNERS = "corners",
|
|
88
93
|
CORNERS_TOTAL = "corners_total",
|