@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/getMissions.md

@@ -0,0 +1,253 @@
+# getMissions — API (TMissionOrBadge)
+
+> Returns all missions visible to the current user, scoped server-side to what the user is qualified to see.
+> Import: `import { TMissionOrBadge } from '@smartico/public-api'`
+> Search terms: getMissions, missions, getUserMissions, achievements, TMissionOrBadge, TMissionOrBadgeTask, AchRelatedGame, TRibbon, AchievementAvailabilityStatus, AchievementClaimPeriodTypeId, BadgesTimeLimitStates, onUpdate, subscription, id, name, image, is_completed, is_locked, is_requires_optin, is_opted_in, time_limit_ms
+
+## Signature
+```ts
+_smartico.api.getMissions({ onUpdate }: { onUpdate?: (data: TMissionOrBadge[]) => void } = {}): Promise<TMissionOrBadge[]>
+```
+
+## Parameters
+- `params` — Optional. Omit to fetch without subscribing.
+- `params.onUpdate` — Callback invoked with the full refreshed mission array on every server-pushed update (after opt-in / claim-reward calls, or when the server pushes an asynchronous mission-state change). Each call to `getMissions` overwrites the prior callback. Never fires in visitor mode.
+
+## Returns — `Promise<TMissionOrBadge[]>`
+Array of `TMissionOrBadge`. Each item:
+- `id` (number) — ID of the mission or badge
+- `type` ('mission' | 'badge') — Type of entity. Can be 'mission' or 'badge'
+- `name` (string) — Name of the mission or badge, translated to the user language
+- `sub_header` (string) — Sub-header of the mission, translated to the user language
+- `description` (string) — Description of the mission or badge, translated to the user language
+- `reward` (string) — Description of the mission reward if defined
+- `image` (string) — URL of the image of the mission or badge, 256x256px
+- `is_completed` (boolean) — Indicator if the mission is completed or badge is granted
+- `is_locked` (boolean) — Indicator if the mission is locked. Means that it's visible to the user, but he cannot progress in it until it's unlocked. Mission may optionally contain the explanation of what should be done to unlock it in the unlock_mission_description property
+- `unlock_mission_description` (string) — Optional explaination of what should be done to unlock the mission
+- `is_requires_optin` (boolean) — Indicator if the mission requires opt-in. Means that user should explicitly opt-in to the mission in order to start progressing in it
+- `is_opted_in` (boolean) — Indicator if the user opted-in to the mission
+- `time_limit_ms` (number) — The amount of time in milliseconds that user has to complete the mission
+- `active_from_ts` (number) — Holds time from which mission will become available, for the missions that are targeted to be available from specific date/time
+- `active_till_ts` (number) — Holds time till mission will become unavailable, for the missions that are targeted to be available from specific date/time
+- `dt_start` (number) — The date when the mission was started, relevant for the time limited missions, also indicating opt-it date for mission that requires opt-in and unlock date for Locked mission.
+- `progress` (number) — The progress of the mission in percents calculated as the aggregated relative percentage of all tasks
+- `cta_action` (string) — The action that should be performed when user clicks on the mission or badge Can be URL or deep link, e.g. 'dp:deposit'. The most safe to execute CTA is to pass it to _smartico.dp(cta_action); The 'dp' function will handle the CTA and will execute it in the most safe way
+- `cta_text` (string) — The text of the CTA button, e.g. 'Make a deposit'
+- `custom_section_id` (number) — The ID of the custom section where the mission or badge is assigned. Resolve to section metadata via `_smartico.api.getCustomSections()`.
+- `only_in_custom_section` (boolean) — The indicator if the mission or badge is visible only in the custom section and should be hidden from the main overview of missions/badges
+- `custom_data` (any) — The custom data of the mission or badge defined by operator. Can be a JSON object, string or number
+- `tasks` (TMissionOrBadgeTask[]) — The list of tasks of the mission or badge
+  - `id` (number) — ID of the task
+  - `name` (string) — Name of the task, translated to the user language
+  - `is_completed` (boolean) — Indicator if the task is completed
+  - `progress` (number) — The progress of the task in percents
+  - `points_reward` (number) — Reward for completing the task in points
+  - `gems_reward` (number) — Reward for completing the task in gems
+  - `diamonds_reward` (number) — Reward for completing the task in diamonds
+  - `execution_count_expected` (number) — This is the total number of times the user needs to execute to complete task. e.g. he needs to bet 100 times. Here will be 100
+  - `execution_count_actual` (number) — This is the number of times the user has executed 'activity' of the task. e.g. he bet 5 times out of 100. Here will be 5
+- `related_games` (AchRelatedGame[]) — List of casino games (or other types of entities) related to the mission or badge
+  - `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
+- `category_ids` (number[]) — The list of IDs of the categories where the badge item is assigned, information about categories can be retrieved with getAchCategories method
+- `hint_text` (string) — The T&C text for the missions
+- `position` (number) — Priority (or position) of the mission in the UI. Low value indicates higher position in the UI
+- `ribbon` (TRibbon) — The ribbon of the mission/badge item. Can be 'sale', 'hot', 'new', 'vip' or URL to the image in case of custom ribbon, 250x300px
+- `ach_completed_id` (number) — Stable identifier of this specific mission completion. Undefined for badges and for missions that have not yet completed.
+- `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
+- `complete_date` (string) — Date-time the mission/badge was completed, as a `"dd/MM/yyyy HH:mm:ss"` string (server local — NOT ISO-8601, so `new Date(complete_date)` will not parse it). Prefer the epoch-ms `complete_date_ts` for date math.
+- `complete_date_ts` (number) — Time of mission/badge being completed, this property shows the epoch time in UTC
+- `completed_today` (boolean) — Flag for mission/badge indicating that mission/badge completed today
+- `completed_this_week` (boolean) — Flag for mission/badge indicating that mission/badge completed this week
+- `completed_this_month` (boolean) — Flag for mission/badge indicating that mission/badge completed this month
+- `custom_section_type_id` (number) — ID of specific Custom Section type
+- `max_completion_count` (number) — Max number of times the user can complete a mission in case if mission type is Recurring upon completion. NULL equals infinite.
+- `completion_count` (number) — Current completion count for Recurring upon completion missions
+- `next_recurrence_date_ts` (number) — The date/timestamp for recurring missions, which indicating the time remaining until the next recurrence of the mission. Note that if a mission has an "Active till" date defined, this field is not relevant after that date.
+- `availability_status` (AchievementAvailabilityStatus) — Availability status of the mission depends on the defined time limits
+- `claim_button_title` (string) — Title for the claim reward button
+- `claim_button_action` (string) — Action for the claim reward button
+- `prize_claim_expiration_date` (number) — The date/timestamp indicating when the mission claim will expire
+- `prize_claim_period_type_id` (AchievementClaimPeriodTypeId) — The type of the prize claim period (Relative or Exact time and date)
+- `badgeTimeLimitState` (BadgesTimeLimitStates) — Badge time limit state for badges with time restrictions
+- `hide_locked_mission` (boolean) — Flag from achievement if the mission should be hidden when it is locked, until it's unlocked
+
+## Behavioral contract
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed mission array (never a
+diff/patch). Each subsequent call to `getMissions({ onUpdate })`
+REPLACES the prior callback — only one active subscriber at a time.
+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. **Mutation responses**: `requestMissionOptIn(...)` or
+ `requestMissionClaimReward(...)` resolves (any `err_code`).
+2. **Asynchronous server pushes**: a user activity (deposit, bet,
+ login, etc.) advances task progress on a task configured to push
+ updates, or completes a mission.
+3. **Visibility changes**: the user's level changes, or other
+ gamification visibility tags change.
+
+Operator-side BO mission-config edits do NOT push to connected
+clients — those changes surface only on the next cache miss (after
+the 30 s TTL) or alongside the next trigger from (1)–(3).
+
+**What's in the returned list / what's filtered server-side**
+The response is pre-filtered by the server. Missions EXCLUDED before
+reaching the SDK:
+- Missions in `DRAFT` or `ARCHIVED` status (see `AchievementStatus`).
+- Missions where the user fails visibility conditions. Exception:
+ completed missions may remain visible after the user no longer
+ qualifies (configurable per-brand).
+- `FEATURED_MANUALLY` missions that are still locked — they appear
+ only after the user unlocks them.
+- Locked missions configured to hide while locked — UNLESS the
+ mission is configured to expose immediately on unlock (then the
+ locked mission is included as a teaser).
+- `RECURRING` missions between cycles, until the next cycle starts.
+- `RECURRING_QUANTITY` missions outside their `active_from_ts` /
+ `active_till_ts` window.
+
+Client-side filtering you may still want: missions with
+`only_in_custom_section: true` are intended for their custom-section
+view only and should be hidden from the main mission list.
+
+**Reading state from the returned mission**
+Drive availability chips ("missed", "coming soon", "needs opt-in",
+"in progress", "expired") from `availability_status` (enum
+`AchievementAvailabilityStatus`) — it's the canonical derived
+state and reflects all server-side timing/visibility rules in one
+field. For time-limited and recurring missions, `dt_start` doubles
+as the opt-in timestamp (for opt-in missions) or unlock timestamp
+(for previously-locked missions); the expiration of a time-limited
+mission is `dt_start + time_limit_ms`. `next_recurrence_date_ts`
+is populated for `RECURRING` / `RECURRING_QUANTITY` missions but
+is no longer meaningful once the mission's `active_till_ts` has
+passed.
+
+**Refresh after a mutation**
+After `requestMissionOptIn(...)` or `requestMissionClaimReward(...)`
+resolves, the SDK auto-refreshes the mission cache; the `onUpdate`
+callback fires with the new array shortly after. `is_opted_in`,
+`progress`, and `is_completed` flip on the refreshed mission — do
+NOT mutate them optimistically while the round-trip is pending.
+Render any pending state from your own loading flag.
+
+**UI guidance**: see [UI Guide — `getMissions`](../../docs/ui/missions/UIGuide_getMissions.md).
+
+## Example
+```ts
+// 1. Initial fetch + subscribe to live updates
+const missions = await window._smartico.api.getMissions({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] mission list refreshed — re-render the entire mission list UI from this array, do not merge with prior state:', refreshed);
+
+    // 2. onUpdate fires for: opt-in/claim responses, task-progress
+    //    pushes that complete a mission or move a "pushToClient" task,
+    //    and user-level changes. Treat each call as authoritative.
+    const claimable = refreshed.filter(m =>
+      m.is_completed && m.requires_prize_claim && !m.prize_claimed_date_ts,
+    );
+    if (claimable.length > 0) {
+      console.log('[smartico] there are unclaimed mission prizes — surface a "Claim" CTA on each of these missions:', claimable.map(m => m.id));
+    }
+  },
+});
+
+// 3. Filter/render from the returned list. The server already excludes
+//    DRAFT/ARCHIVED missions and ones the user can't see. You may need
+//    client-side filters for view-specific concerns (custom sections,
+//    completed/missed tabs).
+const generalView = missions
+  .filter(m => !m.only_in_custom_section)
+  .sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+
+console.log('[smartico] initial mission list ready — render', generalView.length, 'missions sorted by position');
+
+// 4. Visitor-mode equivalent: onUpdate is accepted but never fires.
+//    Re-poll if you need fresh data.
+// const visitorMissions = await window._smartico.vapi('EN').getMissions();
+// console.log('[smartico] visitor missions are the brand proxy user\'s — per-user fields are not meaningful');
+```
+
+### 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": 4015,
+    "name": "Looking good!",
+    "image": "https://cdn.example/be339e036eea69ecef4246-Mission4.png",
+    "is_completed": true,
+    "is_locked": false,
+    "is_requires_optin": false,
+    "is_opted_in": true,
+    "time_limit_ms": null,
+    "active_from_ts": null,
+    "active_till_ts": null,
+    "dt_start": 1780586690767,
+    "reward": "10 pt",
+    "progress": 100,
+    "type": "mission",
+    "cta_action": "dp:gf_change_avatar",
+    "cta_text": "Pick an avatar",
+    "only_in_custom_section": false,
+    "custom_data": {},
+    "position": 1,
+    "tasks": [
+      {
+        "id": 9107,
+        "name": "Change your avatar",
+        "points_reward": 10,
+        "gems_reward": null,
+        "diamonds_reward": null,
+        "is_completed": true,
+        "progress": 100,
+        "execution_count_expected": 1,
+        "execution_count_actual": 1
+      }
+    ],
+    "related_games": [],
+    "category_ids": [],
+    "ach_completed_id": 3407657653,
+    "requires_prize_claim": false,
+    "prize_claimed_date_ts": null,
+    "complete_date": "08/06/2026 14:52:48",
+    "complete_date_ts": 1780930368099,
+    "completed_today": false,
+    "completed_this_week": false,
+    "completed_this_month": true,
+    "availability_status": 2,
+    "hide_locked_mission": true,
+    "prize_claim_expiration_date": null,
+    "prize_claim_period_type_id": null
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `AchievementStatus`
+- `AchievementAvailabilityStatus`

package/docs/capabilities/getRaffleDrawRun.md

@@ -0,0 +1,210 @@
+# getRaffleDrawRun — API (TRaffleDraw)
+
+> Returns the full detail of a single raffle draw run — same shape as the embedded `TRaffleDraw` in `getRaffles`, but populated with paginated `prizes[].winners[]` rows including usernames and avatars.
+> Import: `import { TRaffleDraw } from '@smartico/public-api'`
+> Search terms: getRaffleDrawRun, raffles, TRaffleDraw, TRafflePrize, TRafflePrizeWinner, RaffleDrawInstanceState, RaffleDrawTypeExecution, TRaffleTicket, id, name, description, image_url, image_url_mobile, icon_url, background_image_url, background_image_url_mobile
+
+## Signature
+```ts
+_smartico.api.getRaffleDrawRun(props: { raffle_id: number; run_id: number; winners_from?: number; winners_to?: number }): Promise<TRaffleDraw>
+```
+
+## Parameters
+- `props.raffle_id` — The parent raffle's `id` (from `TRaffle.id`).
+- `props.run_id` — The draw run instance ID (from `TRaffleDraw.run_id`, not `TRaffleDraw.id`).
+- `props.winners_from` — First winner index to return (0-based). Defaults to `0`.
+- `props.winners_to` — Last winner index (exclusive). Defaults to `20`. Server caps the window at 50 rows per call.
+
+## Returns — `Promise<TRaffleDraw>`
+`TRaffleDraw`:
+- `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
+
+## Behavioral contract
+**Preconditions**
+Pass `raffle_id` (the parent raffle's `id`) and `run_id` (the
+specific run instance — `TRaffleDraw.run_id` from
+`getRaffles`'s embedded draws). Note that
+`TRaffleDraw.id` is the *schedule_id* (stable across runs of a
+recurring draw) — that's NOT what this method takes; it takes the
+per-instance `run_id`.
+
+**Refresh model**
+- **No subscription.** One-shot promise.
+- **No client cache.** Every call sends a network request.
+- **No push event** refreshes the response. Live winner-list
+ updates require a fresh call.
+- The default Smartico UI polls this method on a variable cadence
+ while a draw is in flight: every 3 s during `WinnerSelection`,
+ every 10 s when the countdown is under 5 minutes, every 30 s
+ otherwise.
+
+**Winner pagination**
+`winners_from` / `winners_to` define a half-open range of winner
+indices. The default window is `0–20` (20 winners). The server
+caps the window at 50 rows per call — passing a larger range
+silently truncates. For "load more" pagination, advance
+`winners_from` by the prior page size and pass the same
+`winners_to` offset. `winners_total` on the returned
+`TRaffleDraw` is the authoritative total count for pagination.
+
+The current user's own winning rows (if any) are server-sorted
+to the top of the result.
+
+**Throws**
+Both `raffle_id` and `run_id` are required — the SDK throws
+synchronously when either is missing or falsy.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getRaffleDrawRun`](../../docs/ui/raffles/UIGuide_getRaffleDrawRun.md).
+
+**Visitor mode**: supported.
+
+## Example
+```ts
+const raffles = await window._smartico.api.getRaffles();
+const raffle = raffles[0];
+const draw = raffle.draws.find(d => d.current_state === 3);  // Executed
+
+if (!draw) {
+  console.log('[smartico] no executed draw — skip detail view');
+  return;
+}
+
+// First page of winners.
+const detail = await window._smartico.api.getRaffleDrawRun({
+  raffle_id: raffle.id,
+  run_id: draw.run_id,   // NOTE: run_id, NOT draw.id
+  winners_from: 0,
+  winners_to: 20,
+});
+
+for (const prize of detail.prizes) {
+  console.log('[smartico] prize', prize.name, '— winners on this page:', prize.winners.length);
+  const myWin = prize.winners.find(w => w.username === currentUsername);  // or another match
+  if (myWin) {
+    console.log('[smartico] current user won this prize — surface a Claim CTA if not yet claimed');
+  }
+}
+
+// Load more — pagination via winners_from / winners_to.
+if ((detail.winners_total ?? 0) > 20) {
+  const next = await window._smartico.api.getRaffleDrawRun({
+    raffle_id: raffle.id,
+    run_id: draw.run_id,
+    winners_from: 20,
+    winners_to: 40,
+  });
+  console.log('[smartico] page 2 loaded — append', next.prizes.flatMap(p => p.winners).length, 'winners');
+}
+```
+
+### 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": 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
+- `getRaffles`

package/docs/capabilities/getRaffleDrawRunsHistory.md

@@ -0,0 +1,116 @@
+# getRaffleDrawRunsHistory — API (TRaffleDrawRun)
+
+> Returns the history of past-executed draw runs for a raffle — optionally scoped to a single recurring draw schedule.
+> Import: `import { TRaffleDrawRun } from '@smartico/public-api'`
+> Search terms: getRaffleDrawRunsHistory, raffles, TRaffleDrawRun, id, run_id, name, description, image_url, image_url_mobile, icon_url, background_image_url
+
+## Signature
+```ts
+_smartico.api.getRaffleDrawRunsHistory(props: { raffle_id: number; draw_id?: number }): Promise<TRaffleDrawRun[]>
+```
+
+## Parameters
+- `props.raffle_id` — The parent raffle's `id` (from `TRaffle.id`). Required.
+- `props.draw_id` — Optional — the draw's schedule_id (`TRaffleDraw.id`). When set, scopes the history to that one draw's runs. When omitted, includes all draws of the raffle.
+
+## Returns — `Promise<TRaffleDrawRun[]>`
+Array of `TRaffleDrawRun`. Each item:
+- `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)
+- `run_id` (number) — Field indicates the ID of the latest instance/run of draw
+- `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
+- `image_url_mobile` (string) — URL of the moible image that represents the draw
+- `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
+- `execution_ts` (number) — Date/time of the draw execution
+- `actual_execution_ts` (number) — Actual Date/time of the draw execution
+- `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)
+- `is_winner` (boolean) — Shows if user has won a prize in a current run
+- `has_unclaimed_prize` (boolean) — Shows if user has unclaimed prize
+
+## Behavioral contract
+**Preconditions**
+`raffle_id` is required. `draw_id` is optional — when omitted,
+the response includes history for ALL draws of the raffle; when
+supplied, it scopes to that one draw's recurring history. The
+`draw_id` to pass is `TRaffleDraw.id` (the schedule_id, stable
+across runs), not `run_id`.
+
+**Server-side filtering**
+Draws configured by the operator to hide their history are
+excluded from the response automatically. Cancelled runs are
+also excluded.
+
+**Sort order**
+Server returns rows by scheduled `execution_ts` descending
+(newest first). No client-side sort required.
+
+**Refresh model**
+- **No subscription.** One-shot promise.
+- **No client cache.** Every call hits the server.
+- **No push event** refreshes the response. Re-call manually to
+ pick up newly-executed runs or `has_unclaimed_prize` flips
+ after a `claimRafflePrize` call.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getRaffleDrawRunsHistory`](../../docs/ui/raffles/UIGuide_getRaffleDrawRunsHistory.md).
+
+**Visitor mode**: supported. The same shape is returned with
+`is_winner` and `has_unclaimed_prize` always `false` for visitors.
+
+## Example
+```ts
+const raffles = await window._smartico.api.getRaffles();
+const raffle = raffles[0];
+
+// History across all draws of the raffle.
+const allHistory = await window._smartico.api.getRaffleDrawRunsHistory({
+  raffle_id: raffle.id,
+});
+
+// Highlight rows where the user has an unclaimed prize.
+const unclaimed = allHistory.filter(r => r.has_unclaimed_prize);
+if (unclaimed.length > 0) {
+  console.log('[smartico] surface a "Claim" CTA on these', unclaimed.length, 'history rows:', unclaimed.map(r => r.run_id));
+}
+
+// Scoped history of one recurring draw (use draw.id, the schedule_id).
+const oneDrawHistory = await window._smartico.api.getRaffleDrawRunsHistory({
+  raffle_id: raffle.id,
+  draw_id: raffle.draws[0].id,   // schedule_id (stable across recurring runs)
+});
+console.log('[smartico] render history rows for the daily draw — newest first:', oneDrawHistory.length, 'rows');
+```
+
+### 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": 323,
+    "run_id": 688934,
+    "name": "Hourly draw",
+    "description": "💰 Every hour, the luck could be yours! 🍀 Participate in our hourly draw for a chance to WIN BIG! 💸 Don't miss out!",
+    "image_url": "https://cdn.example/5bcd2fd9bf96f3709d96b5-HourlyDraw-Promoimage.png",
+    "image_url_mobile": "https://cdn.example/5bcd2fd9bf96f3709d96b5-HourlyDraw-Promoimage.png",
+    "icon_url": "https://cdn.example/c20dcc73645e365a387dc2-HourlyDraw-Drawicon.png",
+    "background_image_url": "https://cdn.example/867db7f6791f0a45039608-DrawBackground.png",
+    "background_image_url_mobile": "https://cdn.example/d31a8d4708a17723d57b4b-DrawBackgroundMobilecopy.png",
+    "is_grand": false,
+    "execution_ts": 1780876800000,
+    "ticket_start_ts": 1780873200000,
+    "is_winner": false,
+    "has_unclaimed_prize": false
+  }
+]
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `claimRafflePrize`