@smartico/public-api 0.0.380 → 0.0.382

package/docs/ui/raffles/UIGuide_requestRaffleOptin.md

@@ -0,0 +1,114 @@
+# UI Guide — `requestRaffleOptin`
+
+## Overview
+- Action-focused mutation. The user is on a draw card / detail
+  page for a draw with `requires_optin === true`, and they click
+  "Opt in".
+- Success (`err_code === 0`) means the user is registered for this
+  run. Tickets earned within the run's eligibility window will
+  participate in the draw.
+- Opt-in is **per-run** — recurring draws require a fresh opt-in
+  for each new run.
+
+## Argument mapping
+
+The three IDs come from different fields on the embedded draw:
+
+| Argument | Source |
+|---|---|
+| `raffle_id` | `TRaffle.id` (the parent raffle) |
+| `draw_id` | `TRaffleDraw.id` (schedule_id, **stable** across recurring runs) |
+| `raffle_run_id` | `TRaffleDraw.run_id` (per-execution instance ID) |
+
+Don't confuse `draw.id` with `draw.run_id` — both are needed.
+
+## Loading state
+
+- **Trigger**: set an in-flight flag (`optingIn = true`)
+  immediately on click.
+- **Visual**: replace the button label with animated dots; disable
+  the button.
+- **Reset**: clear the flag on response.
+
+## Idempotency UI guard
+
+The SDK does NOT prevent double-clicks. A second call on the same
+`raffle_run_id` returns `err_code === 1` with `err_message`
+indicating the user is already opted in. Guard the call site:
+
+```ts
+const [optingIn, setOptingIn] = useState(false);
+
+const onOptIn = async (draw: TRaffleDraw) => {
+  if (optingIn) return;                        // in-flight guard
+  if (draw.user_opted_in) return;              // already opted in
+  setOptingIn(true);
+  const r = await window._smartico.api.requestRaffleOptin({
+    raffle_id: raffleId,
+    draw_id: draw.id,        // schedule_id, NOT run_id
+    raffle_run_id: draw.run_id,
+  });
+  setOptingIn(false);
+  handleResponse(r);
+};
+```
+
+Treat `err_code === 1` with an "already opted in" message as
+**idempotent success** in the UI.
+
+## Action button decision matrix
+
+CTA label per state on the draw card (evaluate in priority order):
+
+| Condition | CTA |
+|---|---|
+| `current_state === Executed` (3) | No opt-in CTA (draw is finished) |
+| `current_state === WinnerSelection` (2) | No opt-in CTA (drawing in progress) |
+| `!requires_optin` | No opt-in CTA (tickets participate automatically) |
+| `requires_optin && user_opted_in` | Disabled "Fully opted in" pill (informational) |
+| `requires_optin && !user_opted_in && is_active && current_state !== Executed` | Enabled "Opt in" button |
+| `requires_optin && !is_active` | No opt-in CTA (draw is inactive) |
+
+After opt-in success, `user_opted_in` flips to `true` on the next
+`getRaffles` refresh (which fires automatically via `onUpdate`).
+
+## Per-error-code handling
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Show "Fully opted in" pill; success toast optional |
+| `1` + "already opted in" | Treat as success — same UI as above |
+| `1` + "no need to opt-in" | Hide the opt-in CTA — the draw doesn't actually require it |
+| `1` + "raffle id does not match" | Show a generic error toast; this is a programming bug — verify the IDs being passed |
+| `1` + control-group message | Show a gating message ("Not eligible") |
+| Other non-zero | Generic error toast with `err_message`. Allow retry. |
+
+## Refresh after response
+
+The SDK auto-refreshes the raffles cache on every opt-in response
+(success OR failure). The `onUpdate` callback registered via
+[`getRaffles`](../../api/classes/WSAPIRaffles.md#getraffles) fires
+with the refreshed list — `user_opted_in` reflects the new state.
+**Don't manually call `getRaffles()` after the opt-in response.**
+
+## Animations / transitions
+
+- **Loading dots**: 3-dot animation on the button while in flight.
+- **Success state flip**: button transitions from "Opt in" to
+  "Fully opted in" (~150 ms ease-out). The default Smartico UI
+  uses a 500 ms delay before re-fetching, then the state flip is
+  observed on the refreshed list.
+- **No celebration animation** — opt-in is a quiet success.
+
+## Mobile vs desktop
+
+- **Loading state**: identical (dots).
+- **CTA placement**: desktop usually inline on the draw row; mobile
+  may use a sticky CTA at the bottom of the draw detail.
+
+## Performance
+
+- Single round-trip per click.
+- The `getRaffles` auto-refresh after the response is a separate
+  network call (the cache is invalidated). For UIs that already
+  have fresh state, this is redundant but harmless.

package/docs/ui/user/UIGuide_getActivityLog.md

@@ -0,0 +1,130 @@
+# UI Guide — `getActivityLog`
+
+## Overview
+- Returns the user's unified balance-change history — every points / gems /
+  diamonds transaction in the requested window, newest-first.
+- Power an "Activity" / "History" tab showing wins, claims, purchases,
+  level-up rewards, and operator adjustments.
+- 30 s SDK cache + push refresh on every wallet change (with a caveat —
+  see below).
+
+## List view organization
+
+Single flat list, server-sorted newest-first by `create_date`. The default
+Smartico UI groups rows visually by calendar day (e.g. "Today", "Yesterday",
+"24 May").
+
+### Time-period filter chips
+
+The default Smartico UI exposes these filters on top:
+
+| Chip | `startTimeSeconds` | `endTimeSeconds` |
+|---|---|---|
+| Today | today 00:00 local | now + 60 s |
+| This week | Monday 00:00 local | now + 60 s |
+| Previous week | Prev Monday 00:00 | Prev Sunday 23:59:59 |
+| Last 24 h (default) | now − 86400 | now + 60 s |
+
+Custom UIs can pick any window; the server scans the full range.
+
+## Item card / row
+
+Fields rendered per row:
+
+| Field | Source | Notes |
+|---|---|---|
+| Currency icon | `type` (`UserBalanceType`) | points / gems / diamonds icon |
+| Amount | `amount` | Prepend `+` if positive; color green when `>= 0`, red when negative |
+| Balance after | `balance` | Right-aligned column |
+| Source label | `source_type_id` (`PointChangeSourceType`) | See mapping table below |
+| Timestamp | `create_date` (epoch s × 1000) | Relative ("2h ago") or HH:MM |
+
+## Source label mapping
+
+For consistency with the default Smartico UI, group source IDs into these
+display buckets:
+
+| `PointChangeSourceType` | Display label |
+|---|---|
+| `Journey` (1), `ManualAdjustment` (6), `AutomationRule` (12), `API` (18) | "Marketing" |
+| `AchievementTaskCompletion` (2) | "Mission Task" |
+| `AchievementCompletion` (3) | "Mission" |
+| `LevelsStructureChange` (4) | "Level" |
+| `StorePurchase` (5) | "Store" |
+| `Leaderboard` (7) | "Leaderboard" |
+| `Tournament` (11), `TournamentRegistration` (13), `TournamentRegistrationCancellation` (14) | "Tournament" |
+| `RefundPoints` (15) | "Refund" |
+| `PlayMiniGame` (16), `WinMiniGame` (17) | "Mini-Game" |
+| `DynamicFormula` (19) | "Formula" |
+| `Raffle` (21) | "Raffle" |
+| `Avatars` (22) | "Avatar" |
+| *(any unknown)* | "Other" |
+
+## Pagination
+
+`from` and `to` are offset + ceiling, NOT timestamps:
+
+- `offset = from`
+- `limit = min(to - from, 50)` — server hard-caps at 50 rows per request.
+
+For infinite scroll, advance `from` by 50 each page. Detect end of list when
+the returned array length is less than the requested page size.
+
+## Subscription model — `onUpdate` caveat
+
+The `onUpdate` callback fires whenever the user's points / gems / diamonds
+balance changes. **The pushed payload is a FIXED re-fetch** of:
+
+- `startTimeSeconds = now - 600` (last 10 minutes)
+- `endTimeSeconds = now`
+- `from = 0`, `to = 50`
+
+It does NOT use the original call's parameters. Consumers maintaining a long
+historical view (e.g. 30 days) should treat `onUpdate` as a "new transactions
+arrived" hint and re-call `getActivityLog` with their own params:
+
+```ts
+const log = await window._smartico.api.getActivityLog({
+  startTimeSeconds: thirtyDaysAgo,
+  endTimeSeconds:   now,
+  from: 0, to: 50,
+  onUpdate: async (refreshed) => {
+    console.log('[smartico] wallet changed — refreshed last-10-min payload arrived');
+    // To keep the 30-day view current, re-fetch with the original params:
+    const fresh = await window._smartico.api.getActivityLog({
+      startTimeSeconds: thirtyDaysAgo,
+      endTimeSeconds: Math.floor(Date.now() / 1000),
+      from: 0, to: 50,
+    });
+    console.log('[smartico] re-rendered full 30-day list with', fresh.length, 'rows');
+  },
+});
+```
+
+## Empty / loading / error states
+
+- **Empty**: "No activity in this period" — common for new users or
+  narrow time windows.
+- **Loading (cold fetch)**: skeleton list (5 placeholder rows).
+- **Error**: keep prior list if any; non-blocking banner.
+
+## Refresh
+
+- 30 s SDK cache absorbs rapid tab switches.
+- Push triggers fire on every wallet change; the SDK handles invalidation
+  internally.
+- For the user's CURRENT balance (not the activity log), read
+  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile) — the
+  activity log is for historical detail, not for the current balance widget.
+
+## Mobile vs desktop
+
+- **Desktop**: row shows activity icon · source label · amount · balance · time.
+- **Mobile**: row stacks activity + source label on the left, amount + balance
+  on the right.
+
+## Performance
+
+- 30 s cache + push invalidation makes repeated tab opens cheap.
+- 50-row page limit — paginate via `from` for full history.
+- Don't poll — the `onUpdate` callback handles change detection.

package/docs/ui/user/UIGuide_getLevels.md

@@ -1,13 +1,14 @@
 # UI Guide — `getLevels`
 
 ## Overview
+
 - Returns the full level ladder for the label — one `TLevel` per
-  active level, server-sorted by `required_points` ASC.
+active level, server-sorted by `required_points` ASC.
 - Use as a lookup table to resolve `ach_level_current_id` from
-  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)
-  into a richer level object, or as the source for a level map UI.
+`[getUserProfile](../../api/classes/WSAPIUser.md#getuserprofile)`
+into a richer level object, or as the source for a level map UI.
 - Loading indicator: skip on cache hit (30 s); show a brief shimmer
-  on cold fetch (typically 100–300 ms).
+on cold fetch (typically 100–300 ms).
 
 ## List view organization
 
@@ -41,23 +42,25 @@ of filtering them out.
 
 Fields rendered per tile:
 
-| Field | Use |
-|---|---|
-| `image` | Tile icon (square, 256×256 px source). |
-| `name` | Tile heading. |
-| `description` | Optional sub-text under the heading; the default UI shows this in the detail modal, not on the tile. |
-| `required_points` | Threshold display: `"{N} pts to reach"` or progress bar. |
-| `ordinal_position` | Tile order; matches array order. |
+
+| Field              | Use                                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------------------- |
+| `image`            | Tile icon (square, 256×256 px source).                                                               |
+| `name`             | Tile heading.                                                                                        |
+| `description`      | Optional sub-text under the heading; the default UI shows this in the detail modal, not on the tile. |
+| `required_points`  | Threshold display: `"{N} pts to reach"` or progress bar.                                             |
+| `ordinal_position` | Tile order; matches array order.                                                                     |
+
 
 **Locked vs unlocked treatment** — apply a `disabled` class to tiles
 where the user hasn't met the threshold:
 
 - Points-only leveling (most labels): `disabled = ach_points_ever < required_points`
 - Sliding-window leveling: also check
-  `level_counter_1 < required_level_counter_1` (and `_2`) from
-  [`getUserLevelExtraCounters`](../../api/classes/WSAPIUser.md#getuserlevelextracounters).
+`level_counter_1 < required_level_counter_1` (and `_2`) from
+`[getUserLevelExtraCounters](../../api/classes/WSAPIUser.md#getuserlevelextracounters)`.
 - Manual-only leveling: `disabled` unless the level matches the
-  user's current `ach_level_current_id`.
+user's current `ach_level_current_id`.
 
 The default Smartico UI uses CSS-only treatment for locked tiles —
 no padlock icon, no greyscale by default. Brands can add those via
@@ -70,8 +73,8 @@ When the user taps a tile, open a modal showing:
 - Hero image (`image`)
 - Title (`name`), description (`description`)
 - Progress block: for the user's current level, three stacked
-  progress bars (points / counter 1 / counter 2) — see "Sliding-window
-  leveling" below. For other levels, just the requirement display.
+progress bars (points / counter 1 / counter 2) — see "Sliding-window
+leveling" below. For other levels, just the requirement display.
 - Custom fields rendered from `custom_data` (operator-defined).
 
 `custom_data` is typed as `string` but at runtime is `any` — the SDK
@@ -95,7 +98,7 @@ The operator names the counters via translation keys
 (`levelsCounter1Name`, `levelsCounter2Name`) — typical values are
 "Total Deposits", "Total Wagering", etc. The SDK does not expose the
 operator's chosen labels; resolve them via
-[`getTranslations`](../../api/classes/WSAPIGeneral.md#gettranslations).
+`[getTranslations](../../api/classes/WSAPIGeneral.md#gettranslations)`.
 
 On points-only labels, both `required_level_counter_*` fields are
 `null` — skip rendering the counter rows.
@@ -105,58 +108,60 @@ On points-only labels, both `required_level_counter_*` fields are
 Two formulas are in use; pick whichever fits your design:
 
 - **From-zero (default Smartico UI uses this)**:
-  `ach_points_ever / next_level.required_points × 100`. Shows
-  "absolute" progress; never decreases as the user gains points.
+`ach_points_ever / next_level.required_points × 100`. Shows
+"absolute" progress; never decreases as the user gains points.
 - **From-current-level-floor (SDK uses this in
-  [`getCurrentLevel`](../../api/classes/WSAPIUser.md#getcurrentlevel))**:
-  `(ach_points_ever − current.required_points) / (next.required_points
-  − current.required_points) × 100`. Resets to 0 when the user levels
-  up; better for "how far through this level" UX.
+`[getCurrentLevel](../../api/classes/WSAPIUser.md#getcurrentlevel)`)**:
+`(ach_points_ever − current.required_points) / (next.required_points − current.required_points) × 100`. Resets to 0 when the user levels
+up; better for "how far through this level" UX.
 
 Both bound at 100; at the max level the bar shows full.
 
 ## Image / asset specs
 
-| Field | Aspect | Notes |
-|---|---|---|
+
+| Field   | Aspect                                     | Notes                                                                                                  |
+| ------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
 | `image` | 1:1 (square), 256×256 px documented source | Render in a square tile container; fallback: text-only tile with the level name if `image` is missing. |
 
+
 ## Empty / loading / error states
 
 - **Loading (cold fetch)**: render a skeleton grid (3–6 placeholder
-  tiles) sized to the eventual layout.
+tiles) sized to the eventual layout.
 - **Loading (cache hit)**: do not render a loading state — the
-  promise resolves within a microtask.
+promise resolves within a microtask.
 - **Empty result**: `[]` means no levels are configured for the
-  label. Hide the level UI entirely (or render a neutral
-  "no levels configured" placeholder).
+label. Hide the level UI entirely (or render a neutral
+"no levels configured" placeholder).
 - **Error**: keep the prior list visible if any; show a small
-  non-blocking error banner; retry on next user-driven action.
+non-blocking error banner; retry on next user-driven action.
 
 ## Animations / transitions
 
 - **Tile entry**: stagger fade-in (~30 ms per tile) on first render.
 - **Level-up celebration**: when `ach_level_current_id` flips on a
-  push (detect via [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)'s
-  `props_change`), animate the newly-reached tile (scale-up,
-  shine sweep). The default Smartico UI does this on the header
-  badge, not on the level-map tiles.
+push (detect via `[getUserProfile](../../api/classes/WSAPIUser.md#getuserprofile)`'s
+`props_change`), animate the newly-reached tile (scale-up,
+shine sweep). The default Smartico UI does this on the header
+badge, not on the level-map tiles.
 
 ## Mobile vs desktop
 
 - **Grid columns**: desktop responsive (3–5 columns depending on
-  viewport); mobile 2 columns.
+viewport); mobile 2 columns.
 - **Detail view**: desktop opens as a centered modal with backdrop
-  dim; mobile opens as a full-screen sheet.
+dim; mobile opens as a full-screen sheet.
 - **Counter rows in detail**: identical on both — three stacked
-  progress bars on Logic 2 labels.
+progress bars on Logic 2 labels.
 
 ## Performance
 
 - The 30 s cache deduplicates rapid refetches; a poll loop hitting
-  `getLevels()` every 5 s effectively translates to one network
-  round-trip per 30 s.
+`getLevels()` every 5 s effectively translates to one network
+round-trip per 30 s.
 - `getLevels` is suitable to call once at app boot and cache the
-  array in your own state (re-fetch only when the user's level
-  changes per `props_change`, since the operator-driven ladder
-  rarely changes mid-session).
+array in your own state (re-fetch only when the user's level
+changes per `props_change`, since the operator-driven ladder
+rarely changes mid-session).
+

package/package.json

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

package/src/Base/ClassId.ts

@@ -185,6 +185,8 @@ export enum ClassId {
 	RAF_CLAIM_PRIZE_RESPONSE = 909,
 	RAF_OPTIN_REQUEST = 916,
 	RAF_OPTIN_RESPONSE = 917,
+	RAF_GET_WON_PRIZES_REQUEST = 920,
+	RAF_GET_WON_PRIZES_RESPONSE = 921,
 	/*
 	RAF_GET_TICKETS_REQUEST = 902,
 	RAF_GET_TICKETS_RESPONSE = 903,

package/src/Jackpots/JackpotDetails.ts

@@ -4,34 +4,33 @@ import { JackpotPublicMeta } from './JackpotPublicMeta';
 import { JackpotType } from './JackpotType';
 
 /**
- * JackpotDetails the information about Jackpot template
- * It also includes JackpotPot object that holds the current value of the jackpot
- * Flag is_opted_in indicates if the current user is opted in to the jackpot
+ * One jackpot template the user is eligible for, with its live pot snapshot.
+ * Returned by `jackpotGet()`.
  */
 interface JackpotDetails {
-	/** ID of the jackpot template */
+	/** Stable numeric ID of the template; pass to opt-in / opt-out / winners / eligible-games methods. */
 	jp_template_id: number;
-	/** Type of jackpot logic */
+	/** Whether the jackpot has a shared pot or one independent per user; see {@link JackpotType}. */
 	jp_type_id: JackpotType;
-	/** UI information of jackpot, like name, description, etc. */
+	/** Display data: name, description, image_url, winner / not-winner HTML templates, custom_data (JSON-parsed). */
 	jp_public_meta: JackpotPublicMeta;
-	/** Base currency of the jackpot */
+	/** Native jackpot currency (ISO 4217). Used for winner-history amounts. */
 	jp_currency: string;
-	/** Wallet currency of currently logged in user */
+	/** Current user's wallet currency. Used to display the pot via `pot.current_pot_amount_user_currency`. */
 	user_currency: string;
-	/** Type of the user contribution to the jackpot */
+	/** Whether the contribution is a fixed amount or a percentage of the bet; see {@link JackpotContributionType}. */
 	contribution_type: JackpotContributionType;
-	/** Value of the user contribution. Fixed amount or percentage of bet depending on the contribution type */
+	/** Amount of contribution per qualifying bet — fixed value or percentage depending on `contribution_type`. */
 	contribution_value: number;
-	/** Information of current value of the jackpot */
+	/** Live pot snapshot (amount, temperature, last explosion timestamp). */
 	pot: JackpotPot;
-	/** Indication if the current user is opted in to the jackpot */
+	/** `true` when the current user is currently opted in. */
 	is_opted_in: boolean;
-	/** Indicates whether all games are eligible for the jackpot */
+	/** `true` when every game in the operator catalog contributes; if `true`, skip `getJackpotEligibleGames`. */
 	ach_related_game_allow_all: boolean;
-	/** The number of users who have opted in to participate in the jackpot */
+	/** Number of users currently opted in; always `1` for `JackpotType.Personal`. */
 	registration_count: number;
-	/** Show winners in widget and over API */
+	/** Operator flag: whether the winners list should be displayed. Enforced client-side only — gate `getJackpotWinners` calls on this. */
 	expose_winners_over_api: boolean;
 }
 

package/src/Jackpots/JackpotPot.ts

@@ -9,18 +9,22 @@ enum JackPotTemparature {
 	BURNING = 3,
 }
 
+/**
+ * Live snapshot of one jackpot pot's value and temperature.
+ * Embedded on `JackpotDetails.pot`; refreshed at the 1 s SDK cache TTL.
+ */
 interface JackpotPot {
-	/** ID of the jackpot template */
+	/** Template ID this pot belongs to. */
 	jp_template_id: number;
-	/** ID of the jackpot pot */
+	/** Stable numeric ID of the current pot instance (rotates when the pot explodes). */
 	jp_pot_id: number;
-	/** currency of the jackpot pot in the Jackput base currency */
+	/** Current pot amount in the jackpot's native currency (`jp_currency`). */
 	current_pot_amount: number;
-	/** currency of the jackpot pot in the user wallet currency */
+	/** Current pot amount converted to the user's wallet currency (`user_currency`). */
 	current_pot_amount_user_currency: number;
-	/** the date/time when this pot exploded */
+	/** Unix ms timestamp of when this pot last exploded; `0` if it has never exploded. */
 	explode_date_ts: number;
-	/** current pot temperature */
+	/** Heat band of the pot relative to its explosion range; see {@link JackPotTemparature}. */
 	current_pot_temperature: JackPotTemparature;
 }
 

package/src/MiniGames/SAWGameType.ts

@@ -11,6 +11,7 @@ export enum SAWGameType {
 	Voyager = 10,
 	Plinko = 11,
 	CoinFlip = 12,
+	CustomMinigame = 13,
 }
 
 export enum SAWGameTypeName {
@@ -26,6 +27,7 @@ export enum SAWGameTypeName {
 	Voyager = 'voyager',
 	Plinko = 'plinko',
 	CoinFlip = 'coin_flip',
+	CustomMinigame = 'custom_minigame',
 	Unknown = 'unknown',
 }
 
@@ -45,6 +47,7 @@ export const SAWGameTypeNamed = (type: SAWGameType): SAWGameTypeName => {
 			[SAWGameType.Voyager]: SAWGameTypeName.Voyager,
 			[SAWGameType.Plinko]: SAWGameTypeName.Plinko,
 			[SAWGameType.CoinFlip]: SAWGameTypeName.CoinFlip,
+			[SAWGameType.CustomMinigame]: SAWGameTypeName.CustomMinigame,
 		}[type] || SAWGameTypeName.Unknown
 	);
 };

package/src/MiniGames/SAWTemplateUI.ts

@@ -455,6 +455,16 @@ export interface SAWTemplateUI {
      */
     game_difficulty?: SAWGameDifficultyType;
 
+    // ─── Custom Minigame specific ─────────────────────────────────────────────
+
+    /**
+     * URL of the operator-hosted custom mini-game, loaded inside an iframe by
+     * the widget for `SAWGameType.CustomMinigame`.  The operator is trusted, so
+     * the iframe is rendered without a sandbox.
+     * Back-Office label: _"Game URL"_.
+     */
+    custom_game_url?: string;
+
 	/**
 	 * Minutes for the Voyager seed window.
 	 * The seed window is the range of seeds that can be used to generate the map.

package/src/Raffle/GetRaffleWonPrizesRequest.ts

@@ -0,0 +1,12 @@
+import { ProtocolMessage } from "../Base/ProtocolMessage";
+
+export interface GetRaffleWonPrizesRequest extends ProtocolMessage {
+    /** ID of the raffle to fetch the current user's won prizes for. */
+    raffle_id: number;
+
+    /** Zero-based index of the first won-prize row to return (pagination). */
+    offset: number;
+
+    /** Maximum number of won-prize rows to return (pagination). */
+    limit: number;
+}

package/src/Raffle/GetRaffleWonPrizesResponse.ts

@@ -0,0 +1,56 @@
+import { ProtocolResponse } from '../Base/ProtocolResponse';
+
+/** Presentation meta for a won prize. */
+export interface RaffleWonPrizePublicMeta {
+	/** Name of the prize, e.g. '1 $'. */
+	name: string;
+	/** Indicates whether the chance to win should be hidden in the UI. */
+	hide_chance_to_win: boolean;
+	/** URL of the image that represents the prize. */
+	image_url: string;
+}
+
+/** A single prize the user won within the raffle. */
+export interface RaffleWonPrize {
+	/** Unique ID of the winning row (pass to `claimRafflePrize` when `requires_claim` is `true`). */
+	raf_won_id: number;
+	/** ID of the prize definition. */
+	prize_id: number;
+	/** Run-instance ID of the draw that awarded this prize. */
+	raffle_run_id: number;
+	/** Schedule ID of the draw that awarded this prize. */
+	draw_id: number;
+	/** Presentation meta (name / image). */
+	public_meta: RaffleWonPrizePublicMeta;
+	/** Whether this prize requires a claim action from the user. */
+	requires_claim: boolean;
+	/** Epoch ms when the prize was claimed; `null` when not yet claimed. */
+	claimed_date: number | null;
+}
+
+/** The user the won-prizes list belongs to. */
+export interface RaffleWonPrizeUser {
+	/** Internal user ID. */
+	user_id: number;
+	/** Avatar image: a full URL for a system avatar, otherwise an avatar token to resolve against the widget's avatar domain. */
+	avatar_id: string;
+	/** Numeric ID of the user's selected avatar definition. */
+	avatar_real_id: number;
+	/** Public username; server-masked for other users (e.g. `"32:r*****"`). */
+	public_username?: string;
+	/** Always `null` on the wire — use `avatar_id`. */
+	avatar_url?: string | null;
+}
+
+export interface GetRaffleWonPrizesResponse extends ProtocolResponse {
+	/** The user the won prizes belong to; `null` when `won_prizes` is empty. */
+	user: RaffleWonPrizeUser | null;
+	/** Page of won prizes for the requested raffle, newest-first. */
+	won_prizes: RaffleWonPrize[];
+	/** Total number of won prizes for this user/raffle across all draws (for pagination). */
+	total: number;
+	/** Zero-based offset of this page (echoes the resolved request). */
+	offset: number;
+	/** Page size (echoes the resolved request). */
+	limit: number;
+}

package/src/Raffle/index.ts

@@ -14,4 +14,6 @@ export * from './RaffleClaimPrizeRequest';
 export * from './RaffleClaimPrizeResponse';
 export * from './RaffleDrawPublicMeta';
 export * from './RaffleOptinRequest';
-export * from './RaffleOptinResponse';
+export * from './RaffleOptinResponse';
+export * from './GetRaffleWonPrizesRequest';
+export * from './GetRaffleWonPrizesResponse';

package/src/SmarticoAPI.ts

@@ -139,7 +139,7 @@ import { GetRafflesRequest } from './Raffle/GetRafflesRequest';
 import { GetActivityLogRequest, GetActivityLogResponse, ActivityLogTransform } from './ActivityLog';
 import { GetClanListRequest, GetClanListResponse, GetClanInfoRequest, GetClanInfoResponse, JoinClanRequest, JoinClanResponse } from './Clans';
 import { InboxCategories } from './Inbox/InboxCategories';
-import { GetDrawRunRequest, GetDrawRunResponse, GetRaffleDrawRunsHistoryRequest, GetRaffleDrawRunsHistoryResponse, RaffleClaimPrizeRequest, RaffleClaimPrizeResponse, RaffleOptinRequest, RaffleOptinResponse, drawRunTransform } from './Raffle';
+import { GetDrawRunRequest, GetDrawRunResponse, GetRaffleDrawRunsHistoryRequest, GetRaffleDrawRunsHistoryResponse, RaffleClaimPrizeRequest, RaffleClaimPrizeResponse, RaffleOptinRequest, RaffleOptinResponse, drawRunTransform, GetRaffleWonPrizesRequest, GetRaffleWonPrizesResponse } from './Raffle';
 import { GetAvatarsListResponse, avatarDefinitionTransform } from './Avatars/GetAvatarsListResponse';
 import { GetAvatarsCustomizedResponse, avatarCustomizedTransform } from './Avatars/GetAvatarsCustomizedResponse';
 import { GetAvatarPromptsResponse, avatarPromptTransform } from './Avatars/GetAvatarPromptsResponse';
@@ -1641,6 +1641,19 @@ class SmarticoAPI {
 
 	}
 
+	public async getRaffleWonPrizes(
+		user_ext_id: string,
+		props: { raffle_id: number; offset: number; limit: number },
+	): Promise<GetRaffleWonPrizesResponse> {
+		const message = this.buildMessage<GetRaffleWonPrizesRequest, GetRaffleWonPrizesResponse>(
+			user_ext_id,
+			ClassId.RAF_GET_WON_PRIZES_REQUEST,
+			props,
+		);
+
+		return await this.send<GetRaffleWonPrizesResponse>(message, ClassId.RAF_GET_WON_PRIZES_RESPONSE);
+	}
+
 	public async getActivityLog(
 		user_ext_id: string,
 		startTimeSeconds: number,