@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/getRaffleWonPrizes.md

@@ -0,0 +1,153 @@
+# getRaffleWonPrizes — API (GetRaffleWonPrizesResponse)
+
+> Returns every prize the current user has won within a single raffle — across ALL of that raffle's draws, newest-won first — in one paginated call.
+> Import: `import { GetRaffleWonPrizesResponse } from '@smartico/public-api'`
+> Search terms: getRaffleWonPrizes, raffles, GetRaffleWonPrizesResponse, RaffleWonPrizeUser, RaffleWonPrize, RaffleWonPrizePublicMeta
+
+## Signature
+```ts
+_smartico.api.getRaffleWonPrizes(props: { raffle_id: number; offset?: number; limit?: number }): Promise<GetRaffleWonPrizesResponse>
+```
+
+## Parameters
+- `props.raffle_id` — The parent raffle's `id` (from `TRaffle.id`). Required.
+- `props.offset` — Zero-based index of the first row to return. Defaults to `0`.
+- `props.limit` — Page size. Defaults to `20`.
+
+## Returns — `Promise<GetRaffleWonPrizesResponse>`
+`GetRaffleWonPrizesResponse`:
+- `cid` (number)
+- `ts` (number)
+- `uuid` (string)
+- `errCode` (number)
+- `errMsg` (string)
+- `user` (RaffleWonPrizeUser | null) — The user the won prizes belong to; `null` when `won_prizes` is empty.
+  - `user_id` (number) — Internal user ID.
+  - `avatar_id` (string) — Avatar image: a full URL for a system avatar, otherwise an avatar token to resolve against the widget's avatar domain.
+  - `avatar_real_id` (number) — Numeric ID of the user's selected avatar definition.
+  - `public_username` (string) — Public username; server-masked for other users (e.g. `"32:r*****"`).
+  - `avatar_url` (string | null) — Always `null` on the wire — use `avatar_id`.
+- `won_prizes` (RaffleWonPrize[]) — Page of won prizes for the requested raffle, newest-first.
+  - `raf_won_id` (number) — Unique ID of the winning row (pass to `claimRafflePrize` when `requires_claim` is `true`).
+  - `prize_id` (number) — ID of the prize definition.
+  - `raffle_run_id` (number) — Run-instance ID of the draw that awarded this prize.
+  - `draw_id` (number) — Schedule ID of the draw that awarded this prize.
+  - `public_meta` (RaffleWonPrizePublicMeta) — Presentation meta (name / image).
+    - `name` (string) — Name of the prize, e.g. '1 $'.
+    - `hide_chance_to_win` (boolean) — Indicates whether the chance to win should be hidden in the UI.
+    - `image_url` (string) — URL of the image that represents the prize.
+  - `requires_claim` (boolean) — Whether this prize requires a claim action from the user.
+  - `claimed_date` (number | null) — Epoch ms when the prize was claimed; `null` when not yet claimed.
+- `total` (number) — Total number of won prizes for this user/raffle across all draws (for pagination).
+- `offset` (number) — Zero-based offset of this page (echoes the resolved request).
+- `limit` (number) — Page size (echoes the resolved request).
+
+## Behavioral contract
+**Authentication required**
+Works only for an identified (logged-in) user. Visitor / anonymous
+sessions are rejected — call this only after identify.
+
+**Preconditions**
+`raffle_id` is required — the SDK throws synchronously when it is
+missing or falsy.
+
+**Coverage & sort order**
+Includes the user's wins from every draw of the raffle — recurring,
+one-shot, and grand draws, across all historical runs. Rows are ordered
+newest-win first; there is no "unclaimed first" ordering, so sort
+client-side if you want claimable prizes at the top.
+
+**Pagination**
+`offset` / `limit` page the `won_prizes[]` rows (the SDK defaults to
+`0` / `20`). `total` is the authoritative full count of the user's wins
+for this raffle across all draws — drive "load more" from it
+(`offset + won_prizes.length < total`). An `offset` past the end returns
+an empty `won_prizes[]` with the real `total` and `errCode 0` — not an
+error. The server does NOT clamp `limit`, so always pass an explicit,
+sane page size.
+
+**Rate limit**
+The server caps this at roughly 30 calls per minute with a ~5-second
+minimum gap between calls. Fetch on screen open and on explicit "load
+more" — don't poll it on a timer.
+
+
+
+**Reading the result**
+- Null-check `user` before reading it — it is `null` whenever
+ `won_prizes` is empty.
+- For the avatar, use `user.avatar_id` (already a full URL for a system
+ avatar, otherwise an avatar token to resolve against the widget's
+ avatar domain); `user.avatar_url` is always `null`.
+- Render `public_username` as-is (it is server-masked for privacy, e.g.
+ `"32:r*****"`) and substitute a "You" label for the current user.
+- Treat `claimed_date` as the claim flag: `null` until claimed, then
+ epoch ms.
+
+**Idempotency / Side effects**: safe and read-only — one-shot promise,
+no client cache, no subscription. The server caches the response
+briefly; a successful `claimRafflePrize` invalidates that cache,
+so a follow-up call reflects the new `claimed_date`. This method does
+NOT refresh the `getRaffles` list or fire its `onUpdate` — re-call
+manually to pick up newly-won prizes or a `claimed_date` flip.
+
+**UI guidance**: see [UI Guide — `getRaffleWonPrizes`](../../docs/ui/raffles/UIGuide_getRaffleWonPrizes.md).
+
+**Visitor mode**: not supported (see "Authentication required").
+
+## Example
+```ts
+const raffles = await window._smartico.api.getRaffles();
+const raffle = raffles[0];
+
+// First page of the user's won prizes for this raffle.
+const page = await window._smartico.api.getRaffleWonPrizes({
+  raffle_id: raffle.id,
+  offset: 0,
+  limit: 20,
+});
+
+if (page.errCode !== 0) {
+  console.error('[smartico] could not load won prizes — show a retry state:', page.errMsg);
+  return;
+}
+if (page.won_prizes.length === 0) {
+  console.log('[smartico] no wins in this raffle (or not eligible) — render the empty state');
+  return;
+}
+
+console.log('[smartico]', page.user?.public_username, 'won', page.total, 'prizes total');
+for (const prize of page.won_prizes) {
+  console.log('[smartico] render prize card —', prize.public_meta.name, prize.public_meta.image_url);
+  if (prize.requires_claim && !prize.claimed_date) {
+    console.log('[smartico] show a Claim CTA — on click call claimRafflePrize({ won_id:', prize.raf_won_id, '})');
+  }
+}
+
+// Load more.
+if (page.offset + page.won_prizes.length < page.total) {
+  const next = await window._smartico.api.getRaffleWonPrizes({
+    raffle_id: raffle.id,
+    offset: page.offset + page.limit,
+    limit: 20,
+  });
+  console.log('[smartico] appended', next.won_prizes.length, 'more prizes');
+}
+```
+
+## Errors
+**Error codes** (in `errCode`)
+- `0` — success. Also returned with an empty `won_prizes[]` and
+ `total 0` when the user has no wins, or is not eligible to see this
+ raffle.
+- `1` — generic server error; surface `errMsg` if present.
+
+There are no granular codes — an unknown raffle, an ineligible user,
+and "no wins" all surface as `errCode 0` with an empty list.
+
+## Related
+- `getRaffleDrawRunsHistory`
+- `getRaffleDrawRun`
+- `claimRafflePrize`
+- `getRaffles`
+- `GetRaffleWonPrizesResponse`

package/docs/capabilities/getRaffles.md

@@ -0,0 +1,249 @@
+# getRaffles — API (TRaffle)
+
+> Returns all raffles visible to the current user, each carrying an embedded `draws[]` array with per-draw state (current state, ticket counts, opt-in status, prize structure).
+> Import: `import { TRaffle } from '@smartico/public-api'`
+> Search terms: getRaffles, raffles, TRaffle, TRaffleDraw, TRafflePrize, RaffleDrawInstanceState, RaffleDrawTypeExecution, TRaffleTicket, RaffleTicketCapVisualization, onUpdate, subscription, id, name, description, custom_section_id, image_url, image_url_mobile, start_date, end_date
+
+## Signature
+```ts
+_smartico.api.getRaffles({ onUpdate }: { onUpdate?: (data: TRaffle[]) => void } = {}): Promise<TRaffle[]>
+```
+
+## Parameters
+- `params` — Optional. Omit to fetch without subscribing.
+- `params.onUpdate` — Callback invoked with the full refreshed raffles list after every `claimRafflePrize` or `requestRaffleOptin` round-trip on this connection.
+
+## Returns — `Promise<TRaffle[]>`
+Array of `TRaffle`. Each item:
+- `id` (number) — ID of the Raffle template
+- `name` (string) — Name of the raffle
+- `description` (string) — Description of the raffle
+- `custom_section_id` (number) — ID of the custom section that is linked to the raffle in the Gamification widget
+- `image_url` (string) — URL of the image that represents the raffle, 890x193px
+- `image_url_mobile` (string) — URL of the mobile image that represents the raffle, 300x142px
+- `custom_data` (string) — Custom data as string or JSON string that can be used in API to build custom UI You can request from Smartico to define fields for your specific case that will be managed from Smartico BackOffice Read more here - https://help.smartico.ai/welcome/products/general-concepts/custom-fields-attributes
+- `start_date` (number) — Date of start
+- `end_date` (number) — Date of end
+- `max_tickets_count` (number) — Maximum numer of tickets that can be given to all users for the whole period of raffle
+- `current_tickets_count` (number) — Number of tickets that are already given to all users for this raffle
+- `draws` (TRaffleDraw[]) — List of draws that are available for this raffle. For example, if the raffle is containg one hourly draw, one daily draw and one draw on fixed date like 01/01/2022, Then the list will always return 3 draws, no matter if the draws are already executed or they are in the future.
+  - `id` (number) — Id of the Draw definition, for the repetative draws (e.g. daily), this number will be the same for all draws that are repeating daily (internal name: schedule_id)
+  - `name` (string) — Name of the draw, e.g. 'Daily draw'
+  - `description` (string) — Description of the draw
+  - `image_url` (string) — URL of the image that represents the draw, 365x175px
+  - `image_url_mobile` (string) — URL of the moible image that represents the draw, 300x145px
+  - `icon_url` (string) — URL of the icon that represents the draw
+  - `background_image_url` (string) — URL of the background image that will be used in the draw list item
+  - `background_image_url_mobile` (string) — URL of the moible background image that will be used in the draw list item
+  - `is_grand` (boolean) — Show if the draw is grand and is marked as special
+  - `prizes` (TRafflePrize[]) — Information about prizes in the draw
+    - `id` (string) — The unique identifier for the prize definition
+    - `name` (string) — Name of the prize
+    - `description` (string) — Description of the prize
+    - `image_url` (string) — URL of the image that represents the prize, 256x256px
+    - `custom_data` (string) — Custom data field set in the backoffice prize setup. Can be used to build custom UI for gamification.
+    - `prizes_per_run` (number) — The number of prizes available per run of the draw. E.g. if the draw is run daily, this is the number of prizes available each day, for example 3 iPhones.
+    - `prizes_per_run_actual` (number) — The actual number of prizes for the current instance. This value is taking into account follwing values: - min_required_total_tickets, - add_one_prize_per_each_x_tickets - stock_items_per_draw - total_tickets_count (from Draw instance) - cap_prizes_per_run For example: - prizes_per_run = 1 - min_required_total_tickets = 1000 - add_one_prize_per_each_x_tickets = 1000 - stock_items_per_draw = 5 - total_tickets_count = 7000 - cap_prizes_per_run = 6 prizes_per_run_actual will be 5, because 7000 tickets are collected, so 7 iPhones are available, but the cap is 6 and the stock is 5.
+    - `chances_to_win_perc` (number) — The chances to win the prize by current player. Calculated as the ratio of the number of tickets collected by the current player to the total number of tickets collected by all players and multiplied by number of actual prizes of this kind.
+    - `min_required_total_tickets` (number) — The minimum number of total tickets collected during draw period required to unlock the prize. If the number of tickets collected is less than this value, the prize is not available. Under total tickets we understand the number of tickets collected by all users. The 'draw period' is the time between the ticket_start_date value of the draw and the current time.
+    - `add_one_prize_per_each_x_tickets` (number) — One additional prize will be awarded for each X tickets. E.g. if the prize is 1 iPhone and the value is set to 1000, then for every 1000 tickets collected, an additional iPhone is awarded. If min_required_total_tickets is set to 1000, then next iPhone is awarded when 2000 tickets are collected, and so on. If min_required_total_tickets is not set, then the next iPhone will be awarded when 1000 tickets are collected.
+    - `requires_claim` (boolean) — Indicates whether the prize requires a claim action from the user.
+    - `min_required_tickets_for_user` (number) — The minimum number of tickets a user must have to be eligible for the prize. For example iPhone prize may require 10 tickets to be collected, only users with 10 or more tickets will be eligible for the prize. More tickets are better, as they increase the chances of winning.
+    - `cap_prizes_per_run` (number) — The maximum number of prizes that can be given withing one instance/run of draw. For example the prize is iPhone and add_one_prize_per_each_x_tickets is set to 1000, cap_prizes_per_run is set to 3, and the total number of tickets collected is 7000. In this case, the prizes_per_run_actual will be limitted by 3
+    - `priority` (number) — The priority of the prize. The low number means higher priority (e.g. 1 is higher priority than 2). If there are multiple prizes available, the prize with the highest priority (lowest number) will be awarded first.
+    - `stock_items_per_draw` (number) — Optional field that indicates total remaining number of the prize for all draws of the type. For example, the Daily draw has 1 iPhone daily, and the total number of iPhones is 10. the stock_items_per_draw will be decreasing by 1 each day (assuming there is enough tickets and it is won every day), and when it reaches 0, the prize is not available anymore.
+    - `should_claim` (boolean) — Shows if the prize has been claimed
+    - `winners` (TRafflePrizeWinner[])
+      - `id` (number) — Id of the winner definition, for the repetative winners (e.g. same winner won two prizes), this number will be the same for all winner that are repeating (internal name: schedule_id)
+      - `username` (string) — Winner user name
+      - `avatar_url` (string) — URL of the image of user avatar
+      - `ticket` (TRaffleTicket) — Ticket information (number string and integer)
+        - `ticekt_id` (number) — Int presentation of the ticket
+        - `ticket_id_string` (string) — String presentation of the ticket
+      - `raf_won_id` (number) — Unique ID of winning
+      - `claimed_date` (number) — Date when the prize was claimed
+  - `current_state` (RaffleDrawInstanceState) — State of current instance of Draw
+  - `run_id` (number) — Field indicates the ID of the latest instance/run of draw
+  - `execution_type` (RaffleDrawTypeExecution) — Type of the draw execution, indicating how and when the draw is executed. - ExecDate: Draw is executed only once at a specific date and time. - Recurring: Draw is executed on a recurring basis (e.g., daily, weekly). - Grand: Draw is executed once and is marked as grand, often with larger prizes or more importance.
+  - `execution_ts` (number) — Date/time of the draw execution
+  - `previous_run_ts` (number) — Date of the previously executed draw (if there is such)
+  - `previous_run_id` (number) — Unique ID of the previusly executed draw (if there is such)
+  - `ticket_start_ts` (number) — Date/time starting from which the tickets will participate in the upcoming draw This value need to be taken into account with next_execute_ts field value, for example Next draw is at 10:00, ticket_start_date is 9:00, so all tickets that are collected after 9:00 will participate in the draw at 10:00 (internally this value is calculated as next_execute_ts - ticket_start_date)
+  - `allow_multi_prize_per_ticket` (boolean) — Field is indicating if same ticket can win multiple prizes in the same draw For example there are 3 types of prizes in the draw - iPhone, iPad, MacBook If this field is true, then one ticket can win all 3 prizes (depending on the chances of course), if false, then one ticket can win only one prize. The distribution of the prizes is start from top (assuming on top are the most valuable prizes) to bottom (less valuable prizes) If specific prize has multiple values, e.g. we have 3 iPhones, then the same ticket can win only one prize of a kind, but can win multiple prizes of different kind (if allow_multi_prize_per_ticket is true)
+  - `total_tickets_count` (number) — The number of tickets that are already given to all users for this instance of draw. In other words tickets that are collected between ticket_start_date and current time (or till current_execution_ts is the instance is executed).
+  - `my_tickets_count` (number) — The number of tickets collected by current user for this instance of draw.
+  - `my_last_tickets` (TRaffleTicket[])
+    - `ticekt_id` (number) — Int presentation of the ticket
+    - `ticket_id_string` (string) — String presentation of the ticket
+  - `user_opted_in` (boolean) — If true, the user has opted-in to the raffle.
+  - `requires_optin` (boolean) — If true, the user needs to opt-in to the raffle before they can participate.
+  - `is_active` (boolean) — If true, the draw is active and can be participated in.
+  - `winners_limit` (number) — The number of winners to return
+  - `winners_offset` (number) — The offset of the winners to return
+  - `winners_total` (number) — The total number of winners
+- `ticket_cap_visualization` (RaffleTicketCapVisualization) — Ticket cap visualization
+
+## Behavioral contract
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed raffle list (never a
+diff/patch). Each subsequent call to `getRaffles({ onUpdate })`
+REPLACES the prior callback. Pass `onUpdate: undefined` (or omit
+it) to keep the prior callback in place; the callback is never
+auto-cleared.
+
+**Update triggers** — the callback fires when:
+
+1. `claimRafflePrize` resolves on this connection (any
+ response code) — the refreshed list reflects the new
+ `has_unclaimed_prize` / `claimed_date` state.
+2. `requestRaffleOptin` resolves on this connection (any
+ response code) — the refreshed list reflects the new
+ `user_opted_in` state on the affected draw.
+
+Does NOT fire for: server-side draw executions, ticket increments
+(other users earning tickets), or operator-side raffle/draw config
+changes. Those changes surface only on the next cache miss (after
+the 30 s TTL) — poll manually if your UI needs sub-30s freshness
+during an in-progress draw.
+
+**Reading state from the returned raffle**
+- `current_tickets_count` vs `max_tickets_count` drives the
+ `ticket_cap_visualization` banner (enum
+ `RaffleTicketCapVisualization`: `Empty` = no banner,
+ `Counter` = show "X tickets remaining", `Message` = show
+ sold-out message).
+- Within each draw, `current_state`
+ (`RaffleDrawInstanceState`) buckets the draw into Open
+ (accepting tickets), WinnerSelection (currently drawing), or
+ Executed (winners selected).
+- `execution_type` (`RaffleDrawTypeExecution`) distinguishes
+ one-shot (`ExecDate`), repeating (`Recurring`), or special
+ one-shot (`Grand`) draws. Recurring draws share a stable
+ `draws[i].id` (the schedule definition) across runs — `run_id`
+ is the per-execution instance.
+
+**Cache TTL**: the SDK caches the response for 30 seconds. Cache
+is fully cleared on login / logout. The server also invalidates
+the SDK cache when a draw executes on the server side.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getRaffles`](../../docs/ui/raffles/UIGuide_getRaffles.md).
+
+**Visitor mode**: supported. The same shape is returned, scoped
+to the brand's public raffles. Per-user fields (`my_tickets_count`,
+`my_last_tickets`, `user_opted_in`) are not meaningful for
+visitors. The `onUpdate` callback is accepted but never fires
+because the mutation methods that trigger it
+(`claimRafflePrize`, `requestRaffleOptin`) are not
+available / not effective in visitor mode.
+
+## Example
+```ts
+const raffles = await window._smartico.api.getRaffles({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] raffles refreshed (after claim/optin) — re-render from this array:', refreshed);
+  },
+});
+
+for (const raffle of raffles) {
+  console.log('[smartico] render raffle', raffle.id, '—', raffle.name, ':', raffle.draws.length, 'draws');
+
+  // Bucket draws: active/upcoming first (sorted by execution_ts ASC), then executed last.
+  const sorted = [...raffle.draws].sort((a, b) => {
+    const aDone = a.current_state === 3;  // Executed
+    const bDone = b.current_state === 3;
+    if (aDone !== bDone) return aDone ? 1 : -1;  // executed sink to the bottom
+    return a.execution_ts - b.execution_ts;
+  });
+
+  for (const d of sorted) {
+    if (d.requires_optin && !d.user_opted_in && d.is_active && d.current_state !== 3) {
+      console.log('[smartico] draw', d.run_id, '— show OPT IN CTA (requires_optin + not yet opted in + still active)');
+    }
+    if (d.current_state === 3) {
+      console.log('[smartico] draw', d.run_id, 'executed — fetch winner details via getRaffleDrawRun');
+    }
+  }
+}
+
+// For winner detail on an executed draw, call getRaffleDrawRun separately.
+```
+
+### 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
+[
+  {
+    "id": 158,
+    "name": "ICE Raffle 3.0",
+    "description": "<h2>🎉 Join the Excitement – Enter Our Raffle Draws Today! 🎟️</h2>\n\n<p>Get ready to dive into the thrill of <b>winning amazing prizes</b>! 🏆 Don’t miss you…",
+    "custom_section_id": 1621,
+    "image_url": "https://cdn.example/14077931496fd2091ac794-RaffleLobbyImage.png",
+    "image_url_mobile": "https://cdn.example/330ba5ab6c0aa2e74d203d-Rafflelobbyimagemobile.png",
+    "start_date": 1780669800000,
+    "end_date": 1796157059000,
+    "max_tickets_count": 2000000,
+    "current_tickets_count": 13198,
+    "draws": [
+      {
+        "id": 322,
+        "name": "Daily draw",
+        "description": "🎟️🔥Hot Daily Raffle Alert!🔥🎟️ Spin your way to amazing prizes every single day! Don't miss out!",
+        "image_url": "https://cdn.example/0e61ee7d31eea85ea1e2e5-DailyDraw-Promoimage.png",
+        "image_url_mobile": "https://cdn.example/7da52af5814e089897b470-DailyDraw-Promoimagemobile.png",
+        "icon_url": "https://cdn.example/c681faad98ec20cf94c6cf-DailyDraw-Drawicon.png",
+        "background_image_url": "https://cdn.example/e17b7d69c350b47ae0878f-DrawBackground.png",
+        "background_image_url_mobile": "https://cdn.example/9ec0cc0bcf58d038ab59f9-DrawBackgroundMobilecopy.png",
+        "is_grand": false,
+        "prizes": [
+          {
+            "id": 1244,
+            "name": "16\" Lenovo laptop",
+            "image_url": "https://cdn.example/6b4690ea0429208b244f7c-DailyDraw-516inchLaptopLenovoPrizeimage.png",
+            "prizes_per_run": 1,
+            "prizes_per_run_actual": 1,
+            "chances_to_win_perc": 0,
+            "min_required_total_tickets": 100,
+            "cap_prizes_per_run": 3,
+            "priority": 1,
+            "stock_items_per_draw": 9991,
+            "should_claim": false,
+            "winners": [],
+            "requires_claim": false,
+            "min_required_tickets_for_user": 10
+          }
+        ],
+        "current_state": 1,
+        "run_id": 775459,
+        "execution_type": 2,
+        "execution_ts": 1782378000000,
+        "previous_run_ts": 1782291600000,
+        "previous_run_id": 771353,
+        "ticket_start_ts": 1782291600000,
+        "allow_multi_prize_per_ticket": false,
+        "total_tickets_count": 93,
+        "my_tickets_count": 0,
+        "my_last_tickets": [],
+        "user_opted_in": true,
+        "requires_optin": false,
+        "is_active": true,
+        "winners_limit": 20,
+        "winners_offset": 0,
+        "winners_total": 0
+      }
+    ]
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getRaffleDrawRun`
+- `claimRafflePrize`
+- `requestRaffleOptin`
+- `RaffleTicketCapVisualization`
+- `RaffleDrawInstanceState`
+- `RaffleDrawTypeExecution`

package/docs/capabilities/getRelatedItemsForGame.md

@@ -0,0 +1,236 @@
+# getRelatedItemsForGame — API (GetRelatedAchTourResponse)
+
+> Returns the missions and tournaments associated with a casino / sportsbook game in the operator's games catalog — the reverse of "given this mission, which games count for it" — so you can surface "play this game to progress mission X" / "tournament Y features this game" badges on game tiles or detail screens.
+> Import: `import { GetRelatedAchTourResponse } from '@smartico/public-api'`
+> Search terms: getRelatedItemsForGame, general, GetRelatedAchTourResponse, UserAchievement, AchievementType, AchievementPublicMeta, UserAchievementTask, AchievementStatus, ScheduledMissionType, AchRelatedGame, BadgesTimeLimitStates, Tournament, TournamentType, TournamentPublicMeta, TournamentRegistrationType
+
+## Signature
+```ts
+_smartico.api.getRelatedItemsForGame(related_game_id: string): Promise<GetRelatedAchTourResponse>
+```
+
+## Parameters
+- `related_game_id` — External Games Catalog ID of the game (e.g. `"gold-slot2"`).
+
+## Returns — `Promise<GetRelatedAchTourResponse>`
+`GetRelatedAchTourResponse`:
+- `cid` (number)
+- `ts` (number)
+- `uuid` (string)
+- `errCode` (number)
+- `errMsg` (string)
+- `achievements` (UserAchievement[])
+  - `ach_id` (number)
+  - `ach_type_id` (AchievementType)
+  - `ach_public_meta` (AchievementPublicMeta)
+    - `description` (string)
+    - `unlock_mission_description` (string)
+    - `custom_data` (string)
+    - `cta_text` (string)
+    - `cta_action` (string)
+    - `label_tag` (string)
+    - `custom_label_tag` (string)
+    - `reward` (string)
+    - `image_url` (string)
+    - `name` (string)
+    - `position` (number)
+    - `hide_tasks` (boolean)
+    - `hide_locked_mission` (boolean)
+    - `custom_section_id` (number)
+    - `only_in_custom_section` (boolean)
+    - `hint_text` (string)
+    - `hide_badge_from_ui` (boolean)
+    - `show_badge_first_task_completed` (boolean)
+  - `isCompleted` (boolean)
+  - `isLocked` (boolean)
+  - `requiresOptin` (boolean)
+  - `isOptedIn` (boolean)
+  - `start_date` (string) — time when mission unlocked or opted-in. Needed to calculated "remaining time" in case time_limit_ms is set
+  - `start_date_ts` (number)
+  - `time_limit_ms` (number)
+  - `progress` (number)
+  - `complete_date` (string)
+  - `complete_date_ts` (number)
+  - `unlock_date` (string)
+  - `milliseconds_till_available` (number)
+  - `completed_tasks` (number)
+  - `achievementTasks` (UserAchievementTask[])
+    - `task_id` (number)
+    - `task_public_meta` (AchievementTaskPublicMeta)
+      - `name` (string)
+    - `points_reward` (number)
+    - `task_type_id` (AchievementTaskType)
+    - `isCompleted` (boolean)
+    - `userExecutedCount` (number)
+    - `userProgress` (number)
+    - `lastExecutionDate` (string)
+    - `unlocked_by_mission_id` (number)
+    - `unlocked_by_level_id` (number)
+  - `next_recurrence_date_ts` (number)
+  - `ach_status_id` (AchievementStatus)
+  - `scheduledMissionType` (ScheduledMissionType)
+  - `related_games` (AchRelatedGame[])
+    - `ext_game_id` (string) — The ID of the related game
+    - `game_public_meta` ({
+		/** The name of the game */
+		name: string;
+		/** The URL to the game */
+		link: string;
+		/** The URL to the image of the game, 1:1 aspect ratio */
+		image: string;
+		/** The indicator if the game is enabled */
+		enabled: boolean;
+		/** The list of categories of the game */
+		game_categories: string[];
+		/** The name of the game provider */
+		game_provider: string;
+		/** The URL to the mobile game */
+		mobile_spec_link: string;
+		/** The priority of the game */
+		priority?: number;
+	}) — Game public meta information
+  - `active_from_ts` (number) — indicates when 'scheduled' mission is active from,
+  - `active_till_ts` (number) — indicates when 'scheduled' mission is active till,
+  - `ach_categories` (number[])
+  - `recurring_quantity` (number) — max completion count for Recurring upon completion
+  - `completed_count` (number) — completion count for Recurring upon completion
+  - `ach_completed_id` (number) — ID of the completion fact from ach_completed or ach_completed_recurring tables
+  - `requires_prize_claim` (boolean) — flag from achievement if the mission prize will be given only after user claims it
+  - `prize_claimed_date_ts` (number) — the date/timestamp indicating when the prize was claimed by the user
+  - `completed_today` (boolean)
+  - `completed_this_week` (boolean)
+  - `completed_this_month` (boolean)
+  - `custom_section_type_id` (number)
+  - `badgeTimeLimitState` (BadgesTimeLimitStates)
+- `tournaments` (Tournament[])
+  - `tournamentId` (number) — ID of tournament template
+  - `tournamentInstanceId` (number) — ID of tournament instance. Generated every time when tournament based on specific template is scheduled for run
+  - `tournamentType` (TournamentType) — Type of the tournament. For now only SCHEDULED is support
+  - `publicMeta` (TournamentPublicMeta) — Meta information about tournament that should be used to build UI
+    - `name` (string) — Name of tournament
+    - `image_url` (string) — 1st image
+    - `image_url2` (string) — 2nd image
+    - `image_url2_mobile` (string) — 2nd image for mobile
+    - `description` (string) — Description, html capable
+    - `prize_pool_short` (string) — Short explanation of prize pool
+    - `segment_dont_match_message` (string) — Message to show when user is not matching to the segment allowed to register (error code 30005 in registration response)
+    - `custom_price_text` (string) — Short explanation of registration price
+    - `show_other_users_score` (boolean) — Indicator if the scores of other users should be shown in the leaderboard of tournament
+    - `custom_section_id` (number)
+    - `only_in_custom_section` (boolean)
+    - `label_tag` (string)
+    - `custom_label_tag` (string)
+    - `featured` (boolean)
+    - `position` (number)
+    - `custom_data` (string)
+  - `buyInAmount` (number) — Cost of registration in the tournament in gamification points
+  - `prizePool` (number) — Not in use
+  - `startTime` (string) — The time when tournament is going to start
+  - `endTime` (string) — The time when tournament is going to finish
+  - `startTimeTs` (number) — The time when tournament is going to start, epoch
+  - `endTimeTs` (number) — The time when tournament is going to finish, epoch
+  - `registrationCount` (number) — Number of users registered in the tournament
+  - `totalCount` (number) — Not in use
+  - `registrationType` (TournamentRegistrationType) — Type of registration in the tournament
+  - `tournamentRegistrationStatus` (TournamentRegistrationStatus) — Status of registration in the tournament for current user
+  - `tournamentInstanceStatus` (TournamentInstanceStatus) — Status of tournament instance
+  - `isUserRegistered` (boolean) — flag indicating if current user is registered in the tournament
+  - `allowLateRegistration` (boolean) — Indicator if tournament allows later registration, when tournament is already started
+  - `playersMinCount` (number) — Minimum number of participant for this tournament. If tournament doesnt have enough registrations, it will not start
+  - `playersMaxCount` (number) — Maximum number of participant for this tournament. When reached, new users won't be able to register
+  - `durationMs` (number) — Tournament duration in millisecnnds
+  - `prizeStructure` ({
+		prizes: TournamentPrize[];
+	}) — prizes structure
+    - `name` (string)
+    - `description` (string)
+    - `image_url` (string)
+    - `place_from` (number)
+    - `place_to` (number)
+    - `type` (ActivityTypeLimited)
+    - `points` (number)
+    - `gems` (number)
+    - `diamonds` (number)
+  - `tournamentPlayer` (TournamentPlayer) — Information about current user
+    - `userAltName` (string)
+    - `cleanExtUserId` (string)
+    - `crmBrandId` (number)
+    - `position` (number)
+    - `scores` (number)
+    - `isMe` (boolean)
+    - `userId` (number)
+    - `avatar_id` (string)
+    - `avatar_url` (string)
+  - `related_games` (AchRelatedGame[]) — List of casino games (or other types of entities) related to the tournament
+    - `ext_game_id` (string) — The ID of the related game
+    - `game_public_meta` ({
+		/** The name of the game */
+		name: string;
+		/** The URL to the game */
+		link: string;
+		/** The URL to the image of the game, 1:1 aspect ratio */
+		image: string;
+		/** The indicator if the game is enabled */
+		enabled: boolean;
+		/** The list of categories of the game */
+		game_categories: string[];
+		/** The name of the game provider */
+		game_provider: string;
+		/** The URL to the mobile game */
+		mobile_spec_link: string;
+		/** The priority of the game */
+		priority?: number;
+	}) — Game public meta information
+  - `minScoreToWin` (number) — The minimum amount of score points that the user should get in order to be qualified for the prize
+  - `hideLeaderboardsMinScores` (boolean) — When enabled, users who don't meet the minimum qualifying score will be hidden from the Leaderboard.
+  - `totalScores` (number) — Total scores across all participants in the tournament
+  - `isClanBased` (boolean) — Indicates if the tournament is clan-based
+
+## Behavioral contract
+**Preconditions**
+- `related_game_id` must be a Games Catalog ID (the same external string the
+ operator uses in the catalog at
+ `https` ://help.smartico.ai/welcome/technical-guides/games-catalog-api).
+
+**Server-side eligibility filtering**
+Missions and tournaments are filtered by the user's segments / level / brand
+before being returned. A user who is ineligible for a mission segment will
+NOT see that mission in the result even if it lists the game. The same
+filtering applies to tournaments. Treat the response as "what this user
+should see" — no client-side eligibility pass needed.
+
+**No cache**
+Every call is a live server round-trip. Missions/tournaments are operator-
+mutated state (opt-in, completion, expiry) that changes during a session;
+caching staler than the user's last action would mis-render eligibility.
+Avoid building a consumer-side cache for UI-critical paths.
+
+**Refresh**
+- Re-call when the user navigates to a new game tile / detail surface.
+- Re-call after the user opts into / completes a related mission to refresh
+ the "play this game" badge.
+
+**Visitor mode**: supported via `_smartico.vapi(lang).getRelatedItemsForGame(...)`.
+
+**UI guidance**: see [UI Guide — `getRelatedItemsForGame`](../../docs/ui/general/UIGuide_getRelatedItemsForGame.md).
+
+## Example
+```ts
+const r = await window._smartico.api.getRelatedItemsForGame('gold-slot2');
+
+const missions = r.achievements ?? [];
+const tournaments = r.tournaments ?? [];
+
+if (missions.length === 0 && tournaments.length === 0) {
+    console.log('[smartico] no related missions / tournaments — hide the related badge on the game tile');
+} else {
+    console.log('[smartico] related entities:', missions.length, 'missions /', tournaments.length, 'tournaments — show a "X missions / Y tournaments" badge');
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `https`
+- `GetRelatedAchTourResponse`