@smartico/public-api 0.0.411 → 0.0.413

package/docs/api/classes/WSAPIMissions.md

@@ -85,18 +85,46 @@ 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](../enumerations/AchievementAvailabilityStatus.md)) — 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.
+**Status bucketing (which tab / section a mission belongs to)**
+There is no pre-computed bucket field — assign each mission to exactly
+ONE section reading the raw state fields directly (NOT `availability_status`;
+see "Timers" below). Priority order, FIRST match wins:
+1. **Missed / Expired** — not completed and the window has closed:
+   `!is_completed && ((time_limit_ms && dt_start && dt_start + time_limit_ms < Date.now())`
+   `|| (active_till_ts && active_till_ts < Date.now()))`. Do NOT gate this on
+   opt-in — an opt-in mission whose window closed before the user ever
+   opted in is still Missed. Sort by `position` ASC.
+2. **Completed** — `is_completed === true`, OR (recurring-upon-completion
+   missions) at least one cycle done / the cap reached — see the recurring
+   caveats below. Sort by `complete_date_ts` DESC.
+3. **Locked** — `is_locked === true`, OR not yet started
+   (`active_from_ts > Date.now()`). Sort by `position` ASC.
+4. **In-progress** — `is_opted_in === true`, OR (no opt-in required and
+   `progress > 0`). Sort by `position` ASC.
+5. **Available** — everything else (opt-in required but not yet joined, or
+   an unrestricted mission not yet started). Sort by `position` ASC.
+
+**Recurring-upon-completion caveats** (the common mis-bucketing trap):
+- `is_completed` NEVER flips true for a recurring-upon-completion mission
+  (only for one-shot missions) — detect a completed cycle from
+  `completion_count > 0`, not `is_completed`.
+- A non-null `completion_count` is what identifies a recurring-upon-completion
+  mission. `max_completion_count === null` means an INFINITE cap (still
+  recurring — never read null as "not recurring"), so only test
+  `completion_count >= max_completion_count` when `max_completion_count` is set.
+
+**Timers & timestamps** (display only — NOT bucketing)
+`availability_status` (enum [AchievementAvailabilityStatus](../enumerations/AchievementAvailabilityStatus.md)) is the
+timer/window signal: use it to pick WHICH countdown to show and whether the
+window has elapsed — NOT to choose the section. It does not read
+`completion_count`, and between cycles the server may keep reporting the
+just-elapsed cycle's `Missed*` value even after `dt_start` / `active_till_ts`
+are cleared for the next attempt, so bucketing by it sends recurring missions
+to the wrong tab. For time-limited / opt-in missions `dt_start` is the opt-in
+timestamp (or unlock timestamp for previously-locked missions), and a
+time-limited mission expires at `dt_start + time_limit_ms`.
+`next_recurrence_date_ts` is populated for `RECURRING` / `RECURRING_QUANTITY`
+missions but is no longer meaningful once `active_till_ts` has passed.
 
 **Refresh after a mutation**
 After `requestMissionOptIn(...)` or `requestMissionClaimReward(...)`

package/docs/api/interfaces/JackpotPublicMeta.md

@@ -64,4 +64,4 @@ custom value of placeholder2 defined by operator and can be used in the HTML tem
 
 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>
+Read more here - <https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes>

package/docs/api/interfaces/LevelPublicMeta.md

@@ -64,4 +64,4 @@ X & Y coordinates of level on the visual mission map, for desktop and mobile
 
 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
+Read more here - https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes

package/docs/api/interfaces/RafflePublicMeta.md

@@ -56,7 +56,7 @@ Text for Terms and Conditions
 
 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>
+Read more here - <https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes>
 
 ***
 

package/docs/api/interfaces/SAWTemplate.md

@@ -210,6 +210,14 @@ Prize Drop only: when true, the pushed prize requires an explicit claim by the u
 
 ***
 
+### requires\_manual\_claim?
+
+> `optional` **requires\_manual\_claim?**: `boolean`
+
+Prize Drop only: when true, the pushed prize requires a manual claim by the user before it is credited. The difference between this and `requires_prize_claim` is that requires_manual_claim gives the user the ability to cancel the claim.
+
+***
+
 ### relative\_period\_timezone?
 
 > `optional` **relative\_period\_timezone?**: `number`

package/docs/api/interfaces/TMissionOrBadge.md

@@ -64,7 +64,9 @@ URL of the image of the mission or badge, 256x256px
 
 > **is\_completed**: `boolean`
 
-Indicator if the mission is completed or badge is granted
+Indicator if the mission is completed or badge is granted. Stays `false` for
+Recurring-upon-completion missions even after cycles complete — use `completion_count`
+to detect completed cycles (see `getMissions` bucketing).
 
 ***
 
@@ -311,7 +313,7 @@ ID of specific Custom Section type
 
 > `optional` **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.
+Max number of times the user can complete a mission in case if mission type is Recurring upon completion. NULL equals infinite (still recurring — not "no cap disables recurring").
 
 ***
 
@@ -319,7 +321,7 @@ Max number of times the user can complete a mission in case if mission type is R
 
 > `optional` **completion\_count?**: `number`
 
-Current completion count for Recurring upon completion missions
+Current completion count for Recurring-upon-completion missions. Non-null ONLY for that mission type, so its presence identifies one; `> 0` means at least one cycle completed.
 
 ***
 
@@ -336,7 +338,7 @@ Note that if a mission has an "Active till" date defined, this field is not rele
 
 > `optional` **availability\_status?**: [`AchievementAvailabilityStatus`](../enumerations/AchievementAvailabilityStatus.md)
 
-Availability status of the mission depends on the defined time limits
+Timer/window state derived from the mission's time limits (which countdown to show / whether the window elapsed). NOT a tab-bucketing signal — it ignores `completion_count`, so bucket sections from the raw fields instead (see `getMissions`).
 
 ***
 

package/docs/api/interfaces/TRaffle.md

@@ -56,7 +56,7 @@ URL of the mobile image that represents the raffle, 300x142px
 
 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
+Read more here - https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes
 
 ***
 

package/docs/capabilities/getBadges.md

@@ -21,7 +21,7 @@ Array of `TMissionOrBadge`. Each item:
 - `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_completed` (boolean) — Indicator if the mission is completed or badge is granted. Stays `false` for Recurring-upon-completion missions even after cycles complete — use `completion_count` to detect completed cycles (see `getMissions` bucketing).
 - `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
@@ -79,10 +79,10 @@ Array of `TMissionOrBadge`. Each item:
 - `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
+- `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 (still recurring — not "no cap disables recurring").
+- `completion_count` (number) — Current completion count for Recurring-upon-completion missions. Non-null ONLY for that mission type, so its presence identifies one; `> 0` means at least one cycle completed.
 - `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
+- `availability_status` (AchievementAvailabilityStatus) — Timer/window state derived from the mission's time limits (which countdown to show / whether the window elapsed). NOT a tab-bucketing signal — it ignores `completion_count`, so bucket sections from the raw fields instead (see `getMissions`).
 - `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

package/docs/capabilities/getMissions.md

@@ -22,7 +22,7 @@ Array of `TMissionOrBadge`. Each item:
 - `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_completed` (boolean) — Indicator if the mission is completed or badge is granted. Stays `false` for Recurring-upon-completion missions even after cycles complete — use `completion_count` to detect completed cycles (see `getMissions` bucketing).
 - `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
@@ -80,10 +80,10 @@ Array of `TMissionOrBadge`. Each item:
 - `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
+- `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 (still recurring — not "no cap disables recurring").
+- `completion_count` (number) — Current completion count for Recurring-upon-completion missions. Non-null ONLY for that mission type, so its presence identifies one; `> 0` means at least one cycle completed.
 - `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
+- `availability_status` (AchievementAvailabilityStatus) — Timer/window state derived from the mission's time limits (which countdown to show / whether the window elapsed). NOT a tab-bucketing signal — it ignores `completion_count`, so bucket sections from the raw fields instead (see `getMissions`).
 - `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
@@ -132,18 +132,46 @@ 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.
+**Status bucketing (which tab / section a mission belongs to)**
+There is no pre-computed bucket field — assign each mission to exactly
+ONE section reading the raw state fields directly (NOT `availability_status`;
+see "Timers" below). Priority order, FIRST match wins:
+1. **Missed / Expired** — not completed and the window has closed:
+ `!is_completed && ((time_limit_ms && dt_start && dt_start + time_limit_ms < Date.now())`
+ `|| (active_till_ts && active_till_ts < Date.now()))`. Do NOT gate this on
+ opt-in — an opt-in mission whose window closed before the user ever
+ opted in is still Missed. Sort by `position` ASC.
+2. **Completed** — `is_completed === true`, OR (recurring-upon-completion
+ missions) at least one cycle done / the cap reached — see the recurring
+ caveats below. Sort by `complete_date_ts` DESC.
+3. **Locked** — `is_locked === true`, OR not yet started
+ (`active_from_ts > Date.now()`). Sort by `position` ASC.
+4. **In-progress** — `is_opted_in === true`, OR (no opt-in required and
+ `progress > 0`). Sort by `position` ASC.
+5. **Available** — everything else (opt-in required but not yet joined, or
+ an unrestricted mission not yet started). Sort by `position` ASC.
+
+**Recurring-upon-completion caveats** (the common mis-bucketing trap):
+- `is_completed` NEVER flips true for a recurring-upon-completion mission
+ (only for one-shot missions) — detect a completed cycle from
+ `completion_count > 0`, not `is_completed`.
+- A non-null `completion_count` is what identifies a recurring-upon-completion
+ mission. `max_completion_count === null` means an INFINITE cap (still
+ recurring — never read null as "not recurring"), so only test
+ `completion_count >= max_completion_count` when `max_completion_count` is set.
+
+**Timers & timestamps** (display only — NOT bucketing)
+`availability_status` (enum `AchievementAvailabilityStatus`) is the
+timer/window signal: use it to pick WHICH countdown to show and whether the
+window has elapsed — NOT to choose the section. It does not read
+`completion_count`, and between cycles the server may keep reporting the
+just-elapsed cycle's `Missed*` value even after `dt_start` / `active_till_ts`
+are cleared for the next attempt, so bucketing by it sends recurring missions
+to the wrong tab. For time-limited / opt-in missions `dt_start` is the opt-in
+timestamp (or unlock timestamp for previously-locked missions), and a
+time-limited mission expires at `dt_start + time_limit_ms`.
+`next_recurrence_date_ts` is populated for `RECURRING` / `RECURRING_QUANTITY`
+missions but is no longer meaningful once `active_till_ts` has passed.
 
 **Refresh after a mutation**
 After `requestMissionOptIn(...)` or `requestMissionClaimReward(...)`

package/docs/capabilities/getRaffles.md

@@ -21,7 +21,7 @@ Array of `TRaffle`. Each item:
 - `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
+- `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/tools-and-guides/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

package/docs/capabilities/jackpotGet.md

@@ -30,7 +30,7 @@ Array of `JackpotDetails`. Each item:
     - `content` (string)
   - `placeholder1` (string) — custom value of placeholder1 defined by operator and can be used in the HTML templates
   - `placeholder2` (string) — custom value of placeholder2 defined by operator and can be used in the HTML templates
-  - `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>
+  - `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/tools-and-guides/custom-fields-attributes>
 - `jp_currency` (string) — Native jackpot currency (ISO 4217). Used for winner-history amounts.
 - `user_currency` (string) — Current user's wallet currency. Used to display the pot via `pot.current_pot_amount_user_currency`.
 - `contribution_type` (JackpotContributionType) — Whether the contribution is a fixed amount or a percentage of the bet; see `JackpotContributionType`.

package/docs/ui/jackpots/UIGuide_getJackpotWinners.md

@@ -4,7 +4,7 @@
 - Paginated list of past winners of a specific jackpot template.
 - Powers the "Recent Winners" / "Win History" tab inside the jackpot
   detail modal.
-- 30 s cache per template.
+- 30 s cache per page (template + `limit`/`offset`).
 - Gated by the operator's `expose_winners_over_api` flag — but only on
   the client side. Custom UIs must check this flag before calling.
 
@@ -59,7 +59,8 @@ client-side using the exchange rate available on the platform.
 
 ## Refresh
 
-- 30 s SDK cache per `jp_template_id`.
+- 30 s SDK cache per page — keyed by `jp_template_id` + `limit` +
+  `offset`, so each page is cached independently.
 - Cache clears on jackpot-win push events — when the pot explodes, the
   new winner row appears on the next call.
 - Cache also clears on opt-in / opt-out.

package/docs/ui/missions/UIGuide_getMissions.md

@@ -13,31 +13,43 @@
   field. Consumers apply the bucketing filter chain below themselves.
 
 ## Status bucketing
-Partition the array using this **priority order — first match wins**:
+Partition the array using this **priority order — first match wins** —
+reading the raw state fields directly (NOT `availability_status`; see the
+note below):
 
-  1. **Missed** — time window passed before completion. Test:
-     `(!is_completed) && ((is_requires_optin && is_opted_in || !is_requires_optin)`
-     ` && time_limit_ms && dt_start && (dt_start + time_limit_ms) < Date.now())`
-     `|| (active_till_ts && active_till_ts < Date.now())`.
-     Sort: `position` ASC.
-  2. **Completed** — `is_completed === true`, OR for missions of type
-     `AchievementStatus.RecurringUponCompletion`,
-     `max_completion_count === completion_count` (cap reached) OR
-     `completion_count > 0` (at least one cycle completed).
+  1. **Missed / Expired** — not completed and the window has closed:
+     `(!is_completed) && ((time_limit_ms && dt_start && (dt_start + time_limit_ms) < Date.now())`
+     `|| (active_till_ts && active_till_ts < Date.now()))`.
+     Do NOT gate this on opt-in — an opt-in mission whose window closed
+     before the user ever opted in still belongs in Missed. Sort: `position` ASC.
+  2. **Completed** — `is_completed === true`, OR (recurring-upon-completion
+     missions) at least one cycle done / the cap reached:
+     `completion_count > 0`, or `max_completion_count != null && completion_count >= max_completion_count`.
+     `is_completed` NEVER flips for recurring-upon-completion missions, so use
+     `completion_count`; a non-null `completion_count` is what identifies the
+     type, and `max_completion_count === null` means an INFINITE cap (still
+     recurring), so only compare against it when it is set.
      Sort: `complete_date_ts` DESC (most recent first).
   3. **Locked** — `is_locked === true`, OR not yet available
      (`active_from_ts > Date.now()`). Sort: `position` ASC.
-  4. **Available (in-progress)** — none of the above.
-     Sort: `position` ASC.
+  4. **In progress** — `is_opted_in === true`, OR (no opt-in required and
+     `progress > 0`). Sort: `position` ASC.
+  5. **Available** — everything else: opt-in required but not yet joined, or
+     an unrestricted mission not yet started. Sort: `position` ASC.
 
 Each mission belongs to exactly ONE bucket. Many UIs render these as
-status tabs / sections. The `availability_status` field
-([AchievementAvailabilityStatus](../../api/enumerations/AchievementAvailabilityStatus.md)) is authoritative for **timer /
-window state** (which countdown to show, whether the window has
-elapsed) — but it is NOT a substitute for bucketing: distinguishing
-"locked" from "opt-in required" requires reading `is_locked` and
-`is_opted_in` directly. An "Overview" tab curating featured +
-in-progress + a sample locked is a common pattern.
+status tabs / sections; an "Overview" tab curating featured + in-progress +
+a sample locked is a common pattern.
+
+**Do not bucket by `availability_status`.** That field
+([AchievementAvailabilityStatus](../../api/enumerations/AchievementAvailabilityStatus.md))
+is the **timer / window** signal only — which countdown to show, whether the
+window elapsed. It does NOT read `completion_count`, so for
+recurring-upon-completion missions it reports a stale `Missed*` value from the
+just-elapsed cycle even after `dt_start` / `active_till_ts` are cleared for the
+next attempt — using it to bucket sends recurring missions to the wrong tab.
+Distinguishing "locked" from "opt-in required" likewise needs `is_locked` /
+`is_opted_in` read directly.
 
 ## Mission card / tile (list view)
 
@@ -53,7 +65,10 @@ Fields to render on the card:
 - Description (fallback chain): `description` → `unlock_mission_description`
   (when `is_locked`) → `tasks[0].name` (when no description and tasks
   exist).
-- Progress bar — render only when `progress > 0` (the 0–100 integer).
+- Progress bar — render only when `progress > 0` (the 0–100 integer),
+  with one exception: a mission that requires opt-in and isn't opted in
+  yet (`is_requires_optin && !is_opted_in`) shows the bar at 0%, so the
+  card/modal signals it has a progress track waiting behind opt-in.
   Hide for completed recurring missions (`AchievementStatus.RecurringUponCompletion`
   on the Completed tab) to avoid showing residual percentage from a
   prior cycle.
@@ -103,8 +118,11 @@ Top-to-bottom structure (omit sections whose source field is empty):
       list is redundant). Each task row: completion indicator
       (checkbox/circle) + `task.name`. Append "N / M" using
       `execution_count_actual / execution_count_expected` when the
-      operator has enabled count display. Show a points stamp for
-      tasks with `points_reward > 0`.
+      operator has enabled count display. A single task can grant MORE
+      THAN ONE reward type — render one reward badge per non-zero amount
+      among `points_reward`, `gems_reward` and `diamonds_reward` (stack
+      them when a task grants several), each with that reward type's icon.
+      Don't assume points-only.
   13. Progress bar (conditional, same rule as card).
   14. Reward block (`reward`).
   15. Related games — only games where `game_public_meta.enabled === true`.
@@ -193,8 +211,10 @@ on click — it does NOT wait for the claim RPC to succeed. Consequences:
   Missions stay visible in the Missed bucket unless an operator
   config hides expired missions after N days.
 - **In progress**: default styling.
-- **Opt-in required**: same as in-progress; the status chip alone
-  signals "opt-in required".
+- **Opt-in required** (`is_requires_optin && !is_opted_in`): styled like
+  in-progress, but the status chip carries a "Requires opt-in" label
+  (not "Available") to signal the mission needs opt-in before progress
+  starts; pair it with the 0%-progress bar noted above.
 - **Featured**: replace the ribbon (when no `ribbon` is set) with a
   "featured" modifier; some brands use a gold border / glow.
 - **Claimable** (claim button visible): add a "claimable" modifier

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartico/public-api",
-	"version": "0.0.411",
+	"version": "0.0.413",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/src/Jackpots/JackpotPublicMeta.ts

@@ -17,7 +17,7 @@ interface JackpotPublicMeta {
 	/**
 	 * 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>
+	 * Read more here - <https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes>
 	*/
 	custom_data: string;
 }

package/src/Level/LevelPublicMeta.ts

@@ -17,7 +17,7 @@ export interface LevelPublicMeta {
 	/**
 	 * 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
+	 * Read more here - https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes
 	*/
 	custom_data?: string;
 }

package/src/MiniGames/SAWTemplate.ts

@@ -69,6 +69,8 @@ export interface SAWTemplate {
 
 	/** Prize Drop only: when true, the pushed prize requires an explicit claim by the user before it is credited */
 	requires_prize_claim?: boolean;
+	/** Prize Drop only: when true, the pushed prize requires a manual claim by the user before it is credited. The difference between this and `requires_prize_claim` is that requires_manual_claim gives the user the ability to cancel the claim. */
+	requires_manual_claim?: boolean;
 
 	/** Timezone offset in minutes used to evaluate the template's period-based rules (UTC minus local, as in JS `Date.getTimezoneOffset()`) */
 	relative_period_timezone?: number;

package/src/Raffle/Raffle.ts

@@ -25,7 +25,7 @@ interface RafflePublicMeta {
     /** 
 	 * 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>
+	 * Read more here - <https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes>
      */
 	custom_data: string;
 

package/src/SmarticoLib/index.ts

@@ -873,21 +873,21 @@ export interface TLevel {
 	/**
 	 * The counter of 1st metric used to reach the Level.
 	 * Relevant in case of using advanced leveling logic
-	 * https://help.smartico.ai/welcome/more/release-notes/september-2022#new-logic-for-leveling-users
+	 * https://help.smartico.ai/welcome/products/release-notes/september-2022#new-logic-for-leveling-users
 	 *
 	 */
 	required_level_counter_1: number;
 	/**
 	 * The counter of 2nd metric used to reach the Level.
 	 * Relevant in case of using advanced leveling logic
-	 * https://help.smartico.ai/welcome/more/release-notes/september-2022#new-logic-for-leveling-users
+	 * https://help.smartico.ai/welcome/products/release-notes/september-2022#new-logic-for-leveling-users
 	 *
 	 */
 	required_level_counter_2: number;
 	/** 
 	 * 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
+	 * Read more here - https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes
 	 */
 	custom_data: string;
 }

package/src/WSAPI/WSAPIJackpots.ts

@@ -332,7 +332,9 @@ export class WSAPIJackpots extends WSAPIClans {
 	 * user-currency display is needed, the consumer must convert client-side.
 	 *
 	 * **Refresh**
-	 * - The SDK caches per `jp_template_id` for 30 seconds.
+	 * - The SDK caches each page separately (per `jp_template_id` +
+	 *   `limit` + `offset`) for 30 seconds, so paging back and forth is
+	 *   served from cache and each page keeps its own fresh copy.
 	 * - Caches clear on jackpot-win push events and on opt-in / opt-out.
 	 *
 	 * **Error handling**
@@ -375,8 +377,11 @@ export class WSAPIJackpots extends WSAPIClans {
 		/** Jackpot template ID (required). */
 		jp_template_id?: number;
 	}): Promise<JackpotWinnerHistory[]> {
+		// Cache per (jp_template_id, limit, offset) so paging or switching
+		// jackpot within the TTL doesn't return a colliding winners list.
+		const cacheKey = `${onUpdateContextKey.JackpotWinners}${jp_template_id}:${limit}:${offset}`;
 		return OCache.use(
-			onUpdateContextKey.JackpotWinners + jp_template_id,
+			cacheKey,
 			ECacheContext.WSAPI,
 			() => this.api.getJackpotWinnersT(this.userExtId, limit, offset, jp_template_id),
 			JACKPOT_WINNERS_CACHE_SEC,

package/src/WSAPI/WSAPIMissions.ts

@@ -66,18 +66,46 @@ export class WSAPIMissions extends WSAPIGeneral {
 	 * `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
-	 * {@link 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.
+	 * **Status bucketing (which tab / section a mission belongs to)**
+	 * There is no pre-computed bucket field — assign each mission to exactly
+	 * ONE section reading the raw state fields directly (NOT `availability_status`;
+	 * see "Timers" below). Priority order, FIRST match wins:
+	 * 1. **Missed / Expired** — not completed and the window has closed:
+	 *    `!is_completed && ((time_limit_ms && dt_start && dt_start + time_limit_ms < Date.now())`
+	 *    `|| (active_till_ts && active_till_ts < Date.now()))`. Do NOT gate this on
+	 *    opt-in — an opt-in mission whose window closed before the user ever
+	 *    opted in is still Missed. Sort by `position` ASC.
+	 * 2. **Completed** — `is_completed === true`, OR (recurring-upon-completion
+	 *    missions) at least one cycle done / the cap reached — see the recurring
+	 *    caveats below. Sort by `complete_date_ts` DESC.
+	 * 3. **Locked** — `is_locked === true`, OR not yet started
+	 *    (`active_from_ts > Date.now()`). Sort by `position` ASC.
+	 * 4. **In-progress** — `is_opted_in === true`, OR (no opt-in required and
+	 *    `progress > 0`). Sort by `position` ASC.
+	 * 5. **Available** — everything else (opt-in required but not yet joined, or
+	 *    an unrestricted mission not yet started). Sort by `position` ASC.
+	 *
+	 * **Recurring-upon-completion caveats** (the common mis-bucketing trap):
+	 * - `is_completed` NEVER flips true for a recurring-upon-completion mission
+	 *   (only for one-shot missions) — detect a completed cycle from
+	 *   `completion_count > 0`, not `is_completed`.
+	 * - A non-null `completion_count` is what identifies a recurring-upon-completion
+	 *   mission. `max_completion_count === null` means an INFINITE cap (still
+	 *   recurring — never read null as "not recurring"), so only test
+	 *   `completion_count >= max_completion_count` when `max_completion_count` is set.
+	 *
+	 * **Timers & timestamps** (display only — NOT bucketing)
+	 * `availability_status` (enum {@link AchievementAvailabilityStatus}) is the
+	 * timer/window signal: use it to pick WHICH countdown to show and whether the
+	 * window has elapsed — NOT to choose the section. It does not read
+	 * `completion_count`, and between cycles the server may keep reporting the
+	 * just-elapsed cycle's `Missed*` value even after `dt_start` / `active_till_ts`
+	 * are cleared for the next attempt, so bucketing by it sends recurring missions
+	 * to the wrong tab. For time-limited / opt-in missions `dt_start` is the opt-in
+	 * timestamp (or unlock timestamp for previously-locked missions), and a
+	 * time-limited mission expires at `dt_start + time_limit_ms`.
+	 * `next_recurrence_date_ts` is populated for `RECURRING` / `RECURRING_QUANTITY`
+	 * missions but is no longer meaningful once `active_till_ts` has passed.
 	 *
 	 * **Refresh after a mutation**
 	 * After `requestMissionOptIn(...)` or `requestMissionClaimReward(...)`