@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/gamePickGetActiveRounds.md

@@ -0,0 +1,259 @@
+# gamePickGetActiveRounds — API (GamePickRound)
+
+> Returns every open round for a MatchX or Quiz game template, with the full event list (matches / questions) and the current user's selections per event.
+> Import: `import { GamePickRound } from '@smartico/public-api'`
+> Search terms: gamePickGetActiveRounds, gamepick, GamePickRound, GPRoundStatus, GamePickScoreType, GameRoundOrderType, GamePickRoundPublicMeta, GamePickEvent, SAWGPMarketType, GamePickEventMeta, QuizAnswersValueType, GamePickResolutionType, errCode, data
+
+## Signature
+```ts
+_smartico.api.gamePickGetActiveRounds(props: GamePickRequestParams): Promise<GamesApiResponse<GamePickRound[]>>
+```
+
+## Parameters
+- `props.saw_template_id` — ID of the MatchX or Quiz game template.
+
+## Returns — `Promise<GamesApiResponse<GamePickRound[]>>`
+Wrapped in `GamesApiResponse`: `errCode` (number — `0` = success), `errMessage?` (string), `data?` — the payload:
+
+Array of `GamePickRound`. Each item:
+- `round_id` (number) — Unique round identifier
+- `round_row_id` (number) — Sequential row ID used for ordering rounds
+- `round_name` (string) — Localized display name of the round
+- `round_description` (string) — Localized description of the round
+- `final_screen_cta_button_title` (string) — Label for the CTA button on the final/results screen
+- `final_screen_message` (string) — Message displayed on the final/results screen
+- `final_screen_image_desktop` (string) — URL of the final screen image (desktop)
+- `final_screen_image_mobile` (string) — URL of the final screen image (mobile)
+- `promo_image` (string) — URL of the promotional image for the round
+- `promo_text` (string) — Promotional text displayed with the round
+- `open_date` (number) — Timestamp (ms) when the round opens for participation
+- `last_bet_date` (number) — Timestamp (ms) of the last moment bets are accepted
+- `resolution_date` (number) — Timestamp (ms) when the round is expected to be resolved
+- `score_full_win` (number) — Points awarded for a fully correct prediction
+- `score_part_win` (number) — Points awarded for a partially correct prediction
+- `score_lost` (number) — Points awarded (or deducted) for an incorrect prediction
+- `is_active_now` (boolean) — Whether the round is currently active for participation
+- `is_resolved` (boolean) — Whether the round has been fully resolved and scored
+- `round_status_id` (GPRoundStatus) — Current lifecycle status of the round
+- `events_total` (number) — Total number of events in the round
+- `events_resolved` (number) — Number of events that have been resolved
+- `score_type_id` (GamePickScoreType) — Scoring method used for this round
+- `order_events` (GameRoundOrderType) — How events are ordered for display
+- `board_users_count` (number) — Maximum number of users shown on the leaderboard
+- `hide_users_predictions` (boolean) — Whether other users' predictions are hidden until resolution
+- `public_meta` (GamePickRoundPublicMeta) — Public metadata including translations and display settings from the BackOffice
+  - `round_name` (string) — Localized round name
+  - `round_description` (string) — Localized round description
+  - `promo_image` (string) — URL of the promotional image for the round
+  - `promo_text` (string) — Promotional text displayed with the round
+  - `hide_resolved_round` (boolean) — Whether to hide the round from the UI after it has been resolved
+  - `final_screen_image_desktop` (string) — URL of the final screen image for desktop
+  - `final_screen_image_mobile` (string) — URL of the final screen image for mobile
+  - `final_screen_message` (string) — Message displayed on the final/results screen
+  - `final_screen_cta_button_title` (string) — Label for the CTA button on the final screen
+  - `final_screen_cta_dp` (string) — Deep link triggered by the CTA button on the final screen
+  - `allow_edit_answers` (boolean) — Whether users can edit their answers after initial submission (within betting window)
+  - `_translations` ({
+		[key: string]: {
+			round_name: string;
+			round_description: string;
+			promo_image: string;
+			promo_text: string;
+			final_screen_image_desktop: string;
+			final_screen_image_mobile: string;
+			final_screen_message: string;
+			final_screen_cta_button_title: string;
+		};
+	}) — Per-language overrides for round display content
+- `next_round_open_date` (number) — Timestamp (ms) when the next round opens, if available
+- `show_users_preference` (boolean) — Whether to show aggregated user preference percentages for each outcome
+- `events` (GamePickEvent[]) — List of events (matches/questions) in this round
+  - `gp_event_id` (number) — Unique identifier of the event
+  - `event_resolution_date` (string) — ISO 8601 date-time string when the event was resolved; null until resolved.
+  - `match_date` (string) — ISO 8601 date-time string of the match/event start time.
+  - `market_type_id` (SAWGPMarketType) — Market type defining the prediction format (e.g. two-team score, quiz question, custom)
+  - `event_meta` (GamePickEventMeta) — Event metadata containing team names, images, sport type, and question details
+    - `answers` ({
+		/** Answer identifier value sent on submission */
+		value: string;
+		/** Localized display text of the answer */
+		text: string;
+		/** Per-language overrides for the answer text */
+		_translations: {
+			[key: string]: {
+				text: string;
+			};
+		};
+	}[]) — List of possible answer options for the quiz question
+    - `question_image` (string) — URL of an image associated with the question
+    - `result` (QuizAnswersValueType) — Correct answer value after resolution
+    - `custom_question` (string) — Custom question text displayed to the user
+    - `event_name` (string) — Display name of the event/match
+    - `team1_name` (string) — Name of the first team (home)
+    - `team1_image` (string) — URL of the first team's logo image
+    - `team2_name` (string) — Name of the second team (away)
+    - `team2_image` (string) — URL of the second team's logo image
+    - `team1_result` (number) — Actual result score for team 1 after resolution
+    - `team2_result` (number) — Actual result score for team 2 after resolution
+    - `sport_type_id` (number) — Betradar sport type ID for the event
+    - `is_canceled` (boolean) — Whether the event has been canceled
+    - `auto_resolve_enabled` (boolean) — Whether auto-resolution from live data feed is enabled
+    - `auto_resolve_date` (string) — ISO date string for when auto-resolution is expected
+    - `team1_auto_result` (number) — Auto-resolved score for team 1 from live data feed
+    - `team2_auto_result` (number) — Auto-resolved score for team 2 from live data feed
+    - `auto_result` (string) — Auto-resolved answer value from live data feed (for quiz events)
+    - `_translations` ({
+		[key: string]: {
+			team1_name: string;
+			team2_name: string;
+			event_name: string;
+			custom_question: string;
+		};
+	}) — Per-language overrides for team names, event name, and custom question
+  - `user_placed_bet` (boolean) — Whether the current user has submitted a prediction for this event
+  - `team1_user_selection` (number | { from: number; to: number }) — User's predicted score for team 1 (MatchX only). Can be a number or a range object
+  - `team2_user_selection` (number | { from: number; to: number }) — User's predicted score for team 2 (MatchX only). Can be a number or a range object
+  - `user_selection` (QuizAnswersValueType) — User's selected answer (Quiz only). Value depends on market type (e.g. '1', '2', 'x', 'yes', 'no')
+  - `resolution_type_id` (GamePickResolutionType) — How the user's prediction was scored after resolution
+  - `resolution_score` (number) — Points awarded for this event based on prediction accuracy
+  - `is_open_for_bets` (boolean) — Whether this event is still accepting predictions
+  - `odds_details` ({ odd_value: { [key: string]: number } }) — Betting odds details for the event outcomes
+  - `question_image` (string) — URL of a question-specific image (quiz events)
+- `user_score` (number) — Current user's total score in this round
+- `user_placed_bet` (boolean) — Whether the current user has submitted any predictions in this round
+- `has_open_for_bet_events` (boolean) — Whether there are events still open for betting
+- `has_not_submitted_changes` (boolean) — Whether the user has unsaved changes to their predictions
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated.
+- `saw_template_id` must reference a MatchX or Quiz game template. The SDK
+ throws synchronously if it's missing.
+
+**Transport**
+Game Pick methods are HTTP REST calls to a separate Game Pick games server
+(not the main WebSocket). One consequence: there is no SDK cache and no push
+subscription — every call is a fresh server roundtrip.
+
+**Round status**
+Each round's `round_status_id` is a `GPRoundStatus` value. Rounds with
+status `NoEventsDefined` (1) are filtered out server-side and never appear
+here. Other values: `Other` (-1, normally open), `NoMoreBetsAllowed` (2),
+`AllEventsResolved_ButNotRound` (3), `RoundResolved` (4 — appears here only
+briefly during transition; use `gamePickGetHistory` for resolved rounds).
+
+
+
+**Refresh**
+- No cache; every call is live.
+- No push subscription. Poll while the user is on the screen if you need
+ live round-status changes (typically every 30–60 s is enough).
+
+**Visitor mode**: not supported. The SDK throws synchronously on visitor
+sessions.
+
+**UI guidance**: see [UI Guide — `gamePickGetActiveRounds`](../../docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md).
+
+## Example
+```ts
+const r = await window._smartico.api.gamePickGetActiveRounds({ saw_template_id: 1083 });
+
+if (r.errCode !== 0) {
+    console.error('[smartico] active rounds fetch failed — show empty rounds lobby:', r.errMessage);
+    return;
+}
+
+for (const round of r.data ?? []) {
+    console.log('[smartico] render a round card:', round.round_name, '— events:', round.events.length, 'user has placed bet:', round.user_placed_bet);
+}
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+{
+  "errCode": 0,
+  "data": [
+    {
+      "round_id": 42115,
+      "round_row_id": 2,
+      "public_meta": {
+        "round_name": "Group stage 15-28 June",
+        "_translations": {
+          "BR": {},
+          "TH": {}
+        },
+        "allow_edit_answers": true,
+        "final_screen_cta_dp": "dp:ok",
+        "hide_resolved_round": false
+      },
+      "score_type_id": 1,
+      "open_date": 1782200297406,
+      "last_bet_date": 1782691140000,
+      "is_active_now": true,
+      "is_resolved": false,
+      "round_status_id": -1,
+      "score_full_win": 0,
+      "score_part_win": 0,
+      "score_lost": 0,
+      "events_total": "28",
+      "events_resolved": "1",
+      "show_users_preference": true,
+      "order_events": 1,
+      "board_users_count": 20,
+      "hide_users_predictions": false,
+      "round_name": "Group stage 15-28 June",
+      "user_score": 0,
+      "user_placed_bet": false,
+      "events": [
+        {
+          "gp_event_id": 147400,
+          "market_type_id": 4,
+          "event_meta": {
+            "event_name": "World Cup",
+            "team1_name": "Czech Republic",
+            "team2_name": "Mexico",
+            "is_canceled": false,
+            "team1_image": "https://cdn.example/games/teams-images/1299262.png",
+            "team2_image": "https://cdn.example/games/teams-images/4781.png",
+            "sport_type_id": 1,
+            "question_image": "https://cdn.example/5ff1fc35b419e43886d227-Artboard3.png",
+            "scores_manually_adjusted": false
+          },
+          "event_resolution_date": null,
+          "match_date": "2026-06-25T01:00:00.000Z",
+          "odds_details": {
+            "odd_value": {
+              "1": 22,
+              "2": 35,
+              "x": 43
+            }
+          },
+          "user_placed_bet": false,
+          "resolution_score": 0,
+          "is_open_for_bets": true,
+          "resolution_type_id": 0
+        }
+      ],
+      "has_open_for_bet_events": true,
+      "has_not_submitted_changes": false
+    }
+  ]
+}
+```
+
+## Errors
+**Error codes** (in `errCode`)
+- `0` — success.
+- `100002` — template not found (the `saw_template_id` doesn't reference a
+ MatchX/Quiz game).
+- `100003` — no open rounds available for this template right now.
+- `100000` — auth hash invalid; SDK session needs re-initialization.
+- `100004` — generic server error.
+
+## Related
+- `gamePickGetActiveRound`
+- `GPRoundStatus`
+- `gamePickGetHistory`
+- `GamesApiResponse`
+- `GamePickRound`

package/docs/capabilities/gamePickGetBoard.md

@@ -0,0 +1,202 @@
+# gamePickGetBoard — API (GamePickRoundBoard)
+
+> Returns the leaderboard for a MatchX or Quiz game round — ranked list of players plus the current user's entry (`my_user`).
+> Import: `import { GamePickRoundBoard } from '@smartico/public-api'`
+> Search terms: gamePickGetBoard, gamepick, GamePickRoundBoard, GPRoundStatus, GamePickScoreType, GameRoundOrderType, GamePickRoundPublicMeta, GamePickBoardUser, errCode, data
+
+## Signature
+```ts
+_smartico.api.gamePickGetBoard(props: GamePickRoundRequestParams): Promise<GamesApiResponse<GamePickRoundBoard>>
+```
+
+## Parameters
+- `props.saw_template_id` — ID of the MatchX or Quiz game template.
+- `props.round_id` — Round ID, or `-1` for the season leaderboard.
+
+## Returns — `Promise<GamesApiResponse<GamePickRoundBoard>>`
+Wrapped in `GamesApiResponse`: `errCode` (number — `0` = success), `errMessage?` (string), `data?` — the payload:
+
+`GamePickRoundBoard`:
+- `round_id` (number) — Unique round identifier
+- `round_row_id` (number) — Sequential row ID used for ordering rounds
+- `round_name` (string) — Localized display name of the round
+- `round_description` (string) — Localized description of the round
+- `final_screen_cta_button_title` (string) — Label for the CTA button on the final/results screen
+- `final_screen_message` (string) — Message displayed on the final/results screen
+- `final_screen_image_desktop` (string) — URL of the final screen image (desktop)
+- `final_screen_image_mobile` (string) — URL of the final screen image (mobile)
+- `promo_image` (string) — URL of the promotional image for the round
+- `promo_text` (string) — Promotional text displayed with the round
+- `open_date` (number) — Timestamp (ms) when the round opens for participation
+- `last_bet_date` (number) — Timestamp (ms) of the last moment bets are accepted
+- `resolution_date` (number) — Timestamp (ms) when the round is expected to be resolved
+- `score_full_win` (number) — Points awarded for a fully correct prediction
+- `score_part_win` (number) — Points awarded for a partially correct prediction
+- `score_lost` (number) — Points awarded (or deducted) for an incorrect prediction
+- `is_active_now` (boolean) — Whether the round is currently active for participation
+- `is_resolved` (boolean) — Whether the round has been fully resolved and scored
+- `round_status_id` (GPRoundStatus) — Current lifecycle status of the round
+- `events_total` (number) — Total number of events in the round
+- `events_resolved` (number) — Number of events that have been resolved
+- `score_type_id` (GamePickScoreType) — Scoring method used for this round
+- `order_events` (GameRoundOrderType) — How events are ordered for display
+- `board_users_count` (number) — Maximum number of users shown on the leaderboard
+- `hide_users_predictions` (boolean) — Whether other users' predictions are hidden until resolution
+- `public_meta` (GamePickRoundPublicMeta) — Public metadata including translations and display settings from the BackOffice
+  - `round_name` (string) — Localized round name
+  - `round_description` (string) — Localized round description
+  - `promo_image` (string) — URL of the promotional image for the round
+  - `promo_text` (string) — Promotional text displayed with the round
+  - `hide_resolved_round` (boolean) — Whether to hide the round from the UI after it has been resolved
+  - `final_screen_image_desktop` (string) — URL of the final screen image for desktop
+  - `final_screen_image_mobile` (string) — URL of the final screen image for mobile
+  - `final_screen_message` (string) — Message displayed on the final/results screen
+  - `final_screen_cta_button_title` (string) — Label for the CTA button on the final screen
+  - `final_screen_cta_dp` (string) — Deep link triggered by the CTA button on the final screen
+  - `allow_edit_answers` (boolean) — Whether users can edit their answers after initial submission (within betting window)
+  - `_translations` ({
+		[key: string]: {
+			round_name: string;
+			round_description: string;
+			promo_image: string;
+			promo_text: string;
+			final_screen_image_desktop: string;
+			final_screen_image_mobile: string;
+			final_screen_message: string;
+			final_screen_cta_button_title: string;
+		};
+	}) — Per-language overrides for round display content
+- `next_round_open_date` (number) — Timestamp (ms) when the next round opens, if available
+- `show_users_preference` (boolean) — Whether to show aggregated user preference percentages for each outcome
+- `my_user` (GamePickBoardUser) — Current user's leaderboard entry, or null if user hasn't participated
+  - `ext_user_id` (string) — External user ID (Smartico numeric user ID)
+  - `int_user_id` (number) — Internal user ID within the games system
+  - `public_username` (string) — Display name shown on the leaderboard
+  - `avatar_url` (string) — URL of the user's avatar image
+  - `gp_position` (number) — User's rank position on the leaderboard, null if not yet ranked
+  - `resolution_score` (number) — User's total score in this round/season
+  - `full_wins_count` (number) — Number of fully correct predictions
+  - `part_wins_count` (number) — Number of partially correct predictions
+  - `lost_count` (number) — Number of incorrect predictions
+- `users` (GamePickBoardUser[]) — Ranked list of users on the leaderboard
+  - `ext_user_id` (string) — External user ID (Smartico numeric user ID)
+  - `int_user_id` (number) — Internal user ID within the games system
+  - `public_username` (string) — Display name shown on the leaderboard
+  - `avatar_url` (string) — URL of the user's avatar image
+  - `gp_position` (number) — User's rank position on the leaderboard, null if not yet ranked
+  - `resolution_score` (number) — User's total score in this round/season
+  - `full_wins_count` (number) — Number of fully correct predictions
+  - `part_wins_count` (number) — Number of partially correct predictions
+  - `lost_count` (number) — Number of incorrect predictions
+
+## Behavioral contract
+**Preconditions**
+- User must be authenticated. Visitor mode not supported.
+
+**`round_id` semantics**
+- Positive `round_id` — per-round leaderboard scoped to that round's events.
+- `-1` — season / overall leaderboard aggregating scores across every round
+  of the template.
+
+**`my_user`**
+The current user's entry is returned separately from the `users[]` array
+— `my_user` may be `null` if the user has never made a prediction on this
+round / template. Use it to render the user's rank in a sticky footer or
+"you are here" highlight regardless of pagination.
+
+**Username masking**
+`public_username` on other players may be masked / anonymized by operator
+label settings. Always pair with `avatar_url` so the user can recognize
+themselves in the ranking by avatar even when usernames are hidden.
+
+
+
+**Refresh**
+- No cache.
+- No push subscription. Poll while the leaderboard is visible
+  (every 30–60 s) if you want live rank updates after match
+  resolution.
+
+**Visitor mode**: not supported.
+
+**UI guidance**: see [UI Guide — `gamePickGetBoard`](../../docs/ui/gamepick/UIGuide_gamePickGetBoard.md).
+
+## Example
+```ts
+const r = await window._smartico.api.gamePickGetBoard({
+    saw_template_id: 1083,
+    round_id:        -1, // season leaderboard
+});
+
+if (r.errCode === 0 && r.data) {
+    console.log('[smartico] render leaderboard rows for top', r.data.users.length, 'players');
+    if (r.data.my_user) {
+        console.log('[smartico] pin "you are rank #' + r.data.my_user.gp_position + '" footer to bottom');
+    } else {
+        console.log('[smartico] user not ranked — render "Play a round to join the leaderboard" CTA');
+    }
+}
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+{
+  "errCode": 0,
+  "data": {
+    "round_id": 42115,
+    "round_row_id": 2,
+    "public_meta": {
+      "round_name": "Group stage 15-28 June",
+      "_translations": {
+        "BR": {},
+        "TH": {}
+      },
+      "allow_edit_answers": true,
+      "final_screen_cta_dp": "dp:ok",
+      "hide_resolved_round": false
+    },
+    "score_type_id": 1,
+    "open_date": 1782200297406,
+    "last_bet_date": 1782691140000,
+    "is_active_now": true,
+    "is_resolved": false,
+    "round_status_id": -1,
+    "score_full_win": 0,
+    "score_part_win": 0,
+    "score_lost": 0,
+    "events_total": "28",
+    "events_resolved": "1",
+    "show_users_preference": true,
+    "order_events": 1,
+    "board_users_count": 20,
+    "hide_users_predictions": false,
+    "round_name": "Group stage 15-28 June",
+    "users": [
+      {
+        "ext_user_id": "222849599",
+        "int_user_id": "228975556",
+        "public_username": "Alex*****",
+        "avatar_url": "https://cdn.example/d58c99035fadf00dcfe638-Dragongenderless.webp",
+        "gp_position": null,
+        "resolution_score": 0,
+        "full_wins_count": 0,
+        "part_wins_count": 0,
+        "lost_count": 0
+      }
+    ],
+    "my_user": null
+  }
+}
+```
+
+## Errors
+**Error codes** (in `errCode`)
+- `0` — success.
+- `100002` — template not found.
+- `100000` — auth hash invalid.
+- `100004` — generic server error.
+
+## Related
+- `GamesApiResponse`
+- `GamePickRoundBoard`