@sportsbroker/firebase-structure 9.0.1 → 9.2.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.
@@ -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, BetPredictionType } from "../../bets/bets.model";
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: BetPredictionType[];
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",
@@ -28,8 +28,27 @@ export type Pool = {
28
28
  payoutStructure: PoolPayoutStructure;
29
29
  prizeDistributionStrategy: PrizeDistributionStrategyEnum;
30
30
  track?: PoolTrack;
31
+ teamKits?: PoolTeamKits;
31
32
  };
32
33
 
34
+ /**
35
+ * The shirt to draw for a team taking part in this pool, by team id.
36
+ *
37
+ * A MAP rather than two fields on the embedded fixture, because a pool is not one match. A
38
+ * prediction or score-predictor pool runs over several fixtures and therefore over several teams,
39
+ * and one map answers for two teams as well as for twenty. The ids are the same ones the `Fixtures`
40
+ * documents named under `matchIds`, so a client joins what it already read.
41
+ *
42
+ * It lives on the POOL and not on the fixture because a shirt is one operator's choice: a fixture
43
+ * document is shared by every operator running that match, and could not carry a per-operator
44
+ * answer. The pool is the only document that knows whose it is.
45
+ *
46
+ * Optional at every level, by design. A team with no shirt is absent from the map, a pool whose
47
+ * teams have none carries no map at all, and a client that finds nothing draws what it drew before.
48
+ * Nothing here is a promise that a team has a shirt.
49
+ */
50
+ export type PoolTeamKits = Record<UUID, string>;
51
+
33
52
  export type PoolPayoutStructure = { [position: string]: number };
34
53
 
35
54
  export type PoolTrack = "real" | "demo";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sportsbroker/firebase-structure",
3
- "version": "9.0.1",
3
+ "version": "9.2.0",
4
4
  "description": "Firebase structure typings",
5
5
  "main": "index.d.ts",
6
6
  "repository": {