@smartico/public-api 0.0.380 → 0.0.381

package/docs/api/classes/WSAPIRaffles.md

@@ -3,64 +3,145 @@
 
 ### getRaffles()
 
-> **getRaffles**(`__namedParameters?`): `Promise`\<[`TRaffle`](../interfaces/TRaffle.md)[]\>
+> **getRaffles**(`params?`): `Promise`\<[`TRaffle`](../interfaces/TRaffle.md)[]\>
 
-Returns the list of Raffles available for user
-The returned list of Raffles is cached for 30 seconds. But you can pass the onUpdate callback as a parameter. Note that each time you call getRaffles with a new onUpdate callback, the old one will be overwritten by the new one.
-The onUpdate callback will be called on claiming prize.  Updated Raffles will be passed to onUpdate callback.
+Returns all raffles visible to the current user, each carrying an
+embedded `draws[]` array with per-draw state (current state, ticket
+counts, opt-in status, prize structure). Use this to power a
+raffles lobby screen and to drive per-draw CTAs (opt-in, view
+winners, claim).
 
-**Example**:
-
-```
-_smartico.api.getRaffles().then((result) => {
-     console.log(result);
-});
-```
-
-**Example in the Visitor mode**:
-
-```
-_smartico.vapi('EN').getRaffles().then((result) => {
-     console.log(result);
-});
-```
+The embedded `draws[i]` objects are sufficient for rendering all
+draw cards — winner details with usernames / avatars require a
+follow-up [getRaffleDrawRun](#getraffledrawrun) call (the embedded form carries
+only `winners_total` / `winners_limit` / `winners_offset` metadata,
+not individual winner rows).
 
 #### Parameters
 
-##### \_\_namedParameters?
+##### params?
+
+Optional. Omit to fetch without subscribing.
 
 ###### onUpdate?
 
 (`data`) => `void`
 
+Callback invoked with the full refreshed
+                           raffles list after every
+                           [claimRafflePrize](#claimraffleprize) or
+                           [requestRaffleOptin](#requestraffleoptin) round-trip
+                           on this connection.
+
 #### Returns
 
 `Promise`\<[`TRaffle`](../interfaces/TRaffle.md)[]\>
 
+Promise resolving to the raffles list.
+
+#### Remarks
+
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed raffle list (never a
+diff/patch). Each subsequent call to `getRaffles({ onUpdate })`
+REPLACES the prior callback. Pass `onUpdate: undefined` (or omit
+it) to keep the prior callback in place; the callback is never
+auto-cleared.
+
+**Update triggers** — the callback fires when:
+
+1. [claimRafflePrize](#claimraffleprize) resolves on this connection (any
+   response code) — the refreshed list reflects the new
+   `has_unclaimed_prize` / `claimed_date` state.
+2. [requestRaffleOptin](#requestraffleoptin) resolves on this connection (any
+   response code) — the refreshed list reflects the new
+   `user_opted_in` state on the affected draw.
+
+Does NOT fire for: server-side draw executions, ticket increments
+(other users earning tickets), or operator-side raffle/draw config
+changes. Those changes surface only on the next cache miss (after
+the 30 s TTL) — poll manually if your UI needs sub-30s freshness
+during an in-progress draw.
+
+**Reading state from the returned raffle**
+- `current_tickets_count` vs `max_tickets_count` drives the
+  `ticket_cap_visualization` banner (enum
+  [RaffleTicketCapVisualization](../enumerations/RaffleTicketCapVisualization.md): `Empty` = no banner,
+  `Counter` = show "X tickets remaining", `Message` = show
+  sold-out message).
+- Within each draw, `current_state`
+  ([RaffleDrawInstanceState](../enumerations/RaffleDrawInstanceState.md)) buckets the draw into Open
+  (accepting tickets), WinnerSelection (currently drawing), or
+  Executed (winners selected).
+- `execution_type` ([RaffleDrawTypeExecution](../enumerations/RaffleDrawTypeExecution.md)) distinguishes
+  one-shot (`ExecDate`), repeating (`Recurring`), or special
+  one-shot (`Grand`) draws. Recurring draws share a stable
+  `draws[i].id` (the schedule definition) across runs — `run_id`
+  is the per-execution instance.
+
+**Cache TTL**: the SDK caches the response for 30 seconds. Cache
+is fully cleared on login / logout. The server also invalidates
+the SDK cache when a draw executes on the server side.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getRaffles`](../_media/UIGuide_getRaffles.md).
+
+**Visitor mode**: supported. The same shape is returned, scoped
+to the brand's public raffles. Per-user fields (`my_tickets_count`,
+`my_last_tickets`, `user_opted_in`) are not meaningful for
+visitors. The `onUpdate` callback is accepted but never fires
+because the mutation methods that trigger it
+([claimRafflePrize](#claimraffleprize), [requestRaffleOptin](#requestraffleoptin)) are not
+available / not effective in visitor mode.
+
+#### Example
+
+```ts
+const raffles = await window._smartico.api.getRaffles({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] raffles refreshed (after claim/optin) — re-render from this array:', refreshed);
+  },
+});
+
+for (const raffle of raffles) {
+  console.log('[smartico] render raffle', raffle.id, '—', raffle.name, ':', raffle.draws.length, 'draws');
+
+  // Bucket draws: active/upcoming first (sorted by execution_ts ASC), then executed last.
+  const sorted = [...raffle.draws].sort((a, b) => {
+    const aDone = a.current_state === 3;  // Executed
+    const bDone = b.current_state === 3;
+    if (aDone !== bDone) return aDone ? 1 : -1;  // executed sink to the bottom
+    return a.execution_ts - b.execution_ts;
+  });
+
+  for (const d of sorted) {
+    if (d.requires_optin && !d.user_opted_in && d.is_active && d.current_state !== 3) {
+      console.log('[smartico] draw', d.run_id, '— show OPT IN CTA (requires_optin + not yet opted in + still active)');
+    }
+    if (d.current_state === 3) {
+      console.log('[smartico] draw', d.run_id, 'executed — fetch winner details via getRaffleDrawRun');
+    }
+  }
+}
+
+// For winner detail on an executed draw, call getRaffleDrawRun separately.
+```
+
 ***
 
 ### getRaffleDrawRun()
 
 > **getRaffleDrawRun**(`props`): `Promise`\<[`TRaffleDraw`](../interfaces/TRaffleDraw.md)\>
 
-Returns draw run for provided raffle_id and run_id.
-You can pass winners_from and winners_to parameters to get a specific range of winners. Default is 0-20.
-
-**Example**:
-
-```javascript
-_smartico.api.getRaffleDrawRun({raffle_id: 156, run_id: 145}).then((result) => {
-     console.log(result);
-});
-```
-
-**Example in the Visitor mode**:
+Returns the full detail of a single raffle draw run — same shape
+as the embedded `TRaffleDraw` in [getRaffles](#getraffles), but populated
+with paginated `prizes[].winners[]` rows including usernames and
+avatars. Use this to render a draw detail / winners screen, or to
+page through the winner list of an executed draw.
 
-```javascript
-_smartico.vapi('EN').getRaffleDrawRun({ raffle_id: 156, run_id: 145 }).then((result) => {
-     console.log(result);
-});
-```
+Each call is a fresh server round-trip — there is no client cache.
+Re-call to refresh.
 
 #### Parameters
 
@@ -70,45 +151,131 @@ _smartico.vapi('EN').getRaffleDrawRun({ raffle_id: 156, run_id: 145 }).then((res
 
 `number`
 
+The parent raffle's `id` (from `TRaffle.id`).
+
 ###### run_id
 
 `number`
 
+The draw run instance ID (from
+                            `TRaffleDraw.run_id`, not `TRaffleDraw.id`).
+
 ###### winners_from?
 
 `number`
 
+First winner index to return (0-based).
+                            Defaults to `0`.
+
 ###### winners_to?
 
 `number`
 
+Last winner index (exclusive).
+                            Defaults to `20`. Server caps the
+                            window at 50 rows per call.
+
 #### Returns
 
 `Promise`\<[`TRaffleDraw`](../interfaces/TRaffleDraw.md)\>
 
+Promise resolving to `TRaffleDraw`
+                            with `prizes[].winners[]` populated
+                            and `winners_total` set.
+
+#### Remarks
+
+**Preconditions**
+Pass `raffle_id` (the parent raffle's `id`) and `run_id` (the
+specific run instance — `TRaffleDraw.run_id` from
+[getRaffles](#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`](../_media/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');
+}
+```
+
 ***
 
 ### getRaffleDrawRunsHistory()
 
 > **getRaffleDrawRunsHistory**(`props`): `Promise`\<[`TRaffleDrawRun`](../interfaces/TRaffleDrawRun.md)[]\>
 
-Returns history of draw runs for the provided raffle_id and draw_id, if the draw_id is not provided will return history of all the draws for the provided raffle_id
-
-**Example**:
-
-```javascript
-_smartico.api.getRaffleDrawRunsHistory({ raffle_id: 156, draw_id: 432 }).then((result) => {
-     console.log(result);
-});
-```
-
-**Example in the Visitor mode**:
-
-```javascript
-_smartico.vapi('EN').getRaffleDrawRunsHistory({ raffle_id: 156, draw_id: 432 }).then((result) => {
-     console.log(result);
-});
-```
+Returns the history of past-executed draw runs for a raffle —
+optionally scoped to a single recurring draw schedule. Each row
+is a previously-executed run with its scheduled and
+actual-execution timestamps, the user's win status, and an
+unclaimed-prize flag for surfacing a Claim CTA on history rows.
 
 #### Parameters
 
@@ -118,38 +285,100 @@ _smartico.vapi('EN').getRaffleDrawRunsHistory({ raffle_id: 156, draw_id: 432 }).
 
 `number`
 
+The parent raffle's `id` (from `TRaffle.id`).
+                        Required.
+
 ###### draw_id?
 
 `number`
 
+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`](../interfaces/TRaffleDrawRun.md)[]\>
 
-***
+Promise resolving to a `TRaffleDrawRun[]`
+                        ordered newest-first. Empty if no executed
+                        runs exist.
 
-### claimRafflePrize()
+#### Remarks
 
-> **claimRafflePrize**(`props`): `Promise`\<[`TransformedRaffleClaimPrizeResponse`](../interfaces/TransformedRaffleClaimPrizeResponse.md)\>
+**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](#claimraffleprize) call.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getRaffleDrawRunsHistory`](../_media/UIGuide_getRaffleDrawRunsHistory.md).
+
+**Visitor mode**: supported. The same shape is returned with
+`is_winner` and `has_unclaimed_prize` always `false` for visitors.
 
-Returns `err_code` and `err_message` after the call; `err_code` 0 means the request succeeded.
+#### Example
 
-**Example**:
+```ts
+const raffles = await window._smartico.api.getRaffles();
+const raffle = raffles[0];
 
-```javascript
-_smartico.api.claimRafflePrize({won_id:251}).then((result) => {
-     console.log(result);
+// History across all draws of the raffle.
+const allHistory = await window._smartico.api.getRaffleDrawRunsHistory({
+  raffle_id: raffle.id,
 });
-```
 
-**Example in the Visitor mode**:
+// 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));
+}
 
-```javascript
-_smartico.vapi('EN').claimRafflePrize({ won_id: 251 }).then((result) => {
-     console.log(result);
+// 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');
 ```
 
+***
+
+### claimRafflePrize()
+
+> **claimRafflePrize**(`props`): `Promise`\<[`TransformedRaffleClaimPrizeResponse`](../interfaces/TransformedRaffleClaimPrizeResponse.md)\>
+
+Claims a raffle prize the user has won. Call this when the user
+has a winning row with `should_claim === true` and an unclaimed
+`won_id` (read from a `TRafflePrizeWinner` on a
+[getRaffleDrawRun](#getraffledrawrun) result, or surfaced by `has_unclaimed_prize`
+on a [getRaffleDrawRunsHistory](#getraffledrawrunshistory) row that the consumer drills
+into).
+
+On success (`errorCode === 0`), the server records the claim and
+triggers prize delivery through the operator's integration —
+delivery is server-side, not part of this response.
+
 #### Parameters
 
 ##### props
@@ -158,19 +387,124 @@ _smartico.vapi('EN').claimRafflePrize({ won_id: 251 }).then((result) => {
 
 `number`
 
+The winning row's `raf_won_id` (from
+                     `TRafflePrizeWinner` returned by
+                     [getRaffleDrawRun](#getraffledrawrun)).
+
 #### Returns
 
 `Promise`\<[`TransformedRaffleClaimPrizeResponse`](../interfaces/TransformedRaffleClaimPrizeResponse.md)\>
 
+`{ errorCode, errorMessage? }`; success when
+         `errorCode === 0`. Note camelCase keys (see "Result
+         shape note" above).
+
+#### Remarks
+
+**Result shape note**: this method returns
+`TransformedRaffleClaimPrizeResponse` with `errorCode` /
+`errorMessage` (camelCase full-word) — different from most other
+SDK result types which use `err_code` / `err_message` (snake_case
+short-word). Branch on the camelCase keys when reading this
+method's result.
+
+**Preconditions**
+Pass a `won_id` that identifies an unclaimed winning row for the
+current user. The `won_id` comes from
+`TRafflePrizeWinner.raf_won_id` returned by
+[getRaffleDrawRun](#getraffledrawrun).
+
+**Error codes** (in `errorCode`)
+- `0` — success; the claim is recorded and prize delivery is
+  queued server-side.
+- `1` — generic claim failure. The `errorMessage` distinguishes
+  the specific cause (the server uses one error code for several
+  distinct conditions): the prize has already been claimed, the
+  `won_id` doesn't match a winning row for this user, or the user
+  is in a control group for this raffle. Treat `1` as a retryable
+  error if the message suggests a transient condition; treat as
+  idempotent success if the message indicates already-claimed
+  (the underlying state is what the consumer wants either way —
+  the prize is claimed).
+- other non-zero — generic server error. Surface `errorMessage`
+  if any.
+
+**Claim window**
+There is no server-enforced claim deadline. Won prizes remain
+claimable indefinitely until the operator archives them.
+
+**Idempotency**: NOT idempotent. A second call on the same
+`won_id` returns `errorCode === 1` with `errorMessage` indicating
+the prize has already been claimed. The SDK does NOT enforce an
+in-flight lock. Guard the call site against double-clicks (set
+a local "claiming" flag on click, clear it on response).
+
+**Refresh after success (and after failure)**
+The SDK automatically refreshes the raffles cache on every
+response — both success and failure paths fire the `onUpdate`
+callback registered via [getRaffles](#getraffles). After `errorCode === 0`,
+the affected `TRaffleDrawRun.has_unclaimed_prize` (in history)
+and the winner row's `claimed_date` reflect the claim on the next
+refresh.
+
+**Side effects** (on `errorCode === 0`)
+- The winner row's `claimed_date` is set server-side.
+- Prize delivery is queued for the operator's integration to
+  process. Balance / bonus / inbox updates that result from the
+  delivery arrive through their own channels — not in this
+  response.
+
+**Throws**
+`won_id` is required — the SDK throws synchronously when missing
+or falsy.
+
+**UI guidance**: see [UI Guide — `claimRafflePrize`](../_media/UIGuide_claimRafflePrize.md).
+
+**Visitor mode**: not meaningfully supported. The SDK does not
+block the call, but visitor sessions have no win history and the
+server will reject it.
+
+#### Example
+
+```ts
+const detail = await window._smartico.api.getRaffleDrawRun({
+  raffle_id: raffleId,
+  run_id: runId,
+});
+const myWin = detail.prizes.flatMap(p => p.winners).find(w => /* user match here */ true);
+
+if (!myWin || !myWin.raf_won_id || myWin.claimed_date) {
+  console.log('[smartico] nothing to claim — keep CTA hidden');
+  return;
+}
+
+console.log('[smartico] claim starting — set in-flight flag, show loading dots on the Claim button, keep the modal open');
+const r = await window._smartico.api.claimRafflePrize({ won_id: myWin.raf_won_id });
+console.log('[smartico] claim response received — clear in-flight flag');
+
+if (r.errorCode === 0) {
+  console.log('[smartico] claim succeeded — show a success toast; getRaffles onUpdate above will fire with refreshed state; prize delivery happens server-side');
+} else if (r.errorCode === 1 && r.errorMessage?.toLowerCase().includes('already claimed')) {
+  console.log('[smartico] prize was already claimed (perhaps from another tab) — treat as success, hide the Claim CTA');
+} else {
+  console.error('[smartico] claim failed — surface this error message to the user and allow retry:', r.errorMessage);
+}
+```
+
 ***
 
 ### requestRaffleOptin()
 
 > **requestRaffleOptin**(`props`): `Promise`\<[`TRaffleOptinResponse`](../interfaces/TRaffleOptinResponse.md)\>
 
-Requests an opt-in for the specified raffle. Returns the err_code.
+Opts the current user into a specific raffle draw run. Required
+for draws where `TRaffleDraw.requires_optin === true` — without
+opt-in, the user's tickets do NOT participate in that run, even
+if they hold tickets for the raffle.
 
-**Visitor mode: not supported**
+Opt-in is per-run: a recurring draw's next run requires a fresh
+opt-in. The user's `TRaffleDraw.user_opted_in` flag reflects the
+current state for the current run only.
 
 #### Parameters
 
@@ -180,16 +514,260 @@ Requests an opt-in for the specified raffle. Returns the err_code.
 
 `number`
 
+The parent raffle's `id`.
+
 ###### draw_id
 
 `number`
 
+The draw's schedule_id (`TRaffleDraw.id`).
+
 ###### raffle_run_id
 
 `number`
 
+The run instance ID (`TRaffleDraw.run_id`).
+
 #### Returns
 
 `Promise`\<[`TRaffleOptinResponse`](../interfaces/TRaffleOptinResponse.md)\>
 
+`{ err_code, err_message? }`; success
+                            when `err_code === 0` (treat
+                            "already opted in" as idempotent
+                            success).
+
+#### Remarks
+
+**Preconditions**
+Read the candidate draw from [getRaffles](#getraffles)'s embedded
+`draws[]` and gate the call on
+`requires_optin === true && !user_opted_in && is_active &&
+current_state !== Executed`. Calling without these guards may
+return a non-zero `err_code`.
+
+**Argument mapping** — the three IDs come from different fields:
+- `raffle_id` — the parent raffle's `TRaffle.id`
+- `draw_id` — `TRaffleDraw.id` (schedule_id, stable across runs)
+- `raffle_run_id` — `TRaffleDraw.run_id` (instance ID for this
+  specific run)
+
+**Error codes** (in `err_code`)
+- `0` — success; the user is opted into this run. Tickets
+  collected after the run's `ticket_start_ts` will participate.
+- `1` — generic opt-in failure. The `err_message` distinguishes
+  the specific cause: the draw doesn't require opt-in
+  (`requires_optin === false`), `raffle_id` doesn't match the
+  `draw_id`, the user is already opted in (or the draw has
+  completed), or the user is in a control group for this raffle.
+- other non-zero — generic server error. Surface `err_message`.
+
+**Idempotency**: NOT idempotent. A second call on the same
+`raffle_run_id` returns `err_code === 1` with `err_message`
+indicating the user is already opted in. Treat as success in
+the UI — the underlying state is what the consumer wants.
+Guard the call site against double-clicks.
+
+**Refresh after success (and after failure)**
+The SDK automatically refreshes the raffles cache on every
+response and fires the `onUpdate` callback registered via
+[getRaffles](#getraffles). After `err_code === 0`, the affected draw's
+`user_opted_in` flips to `true` on the refreshed list.
+
+**Side effects** (on `err_code === 0`)
+- The user is registered for this run. Tickets earned within
+  the run's eligibility window will participate in the draw.
+- No balance change. No CRM-side rewards. Opt-in is a metadata
+  operation only.
+
+**Throws**
+`raffle_id`, `draw_id`, and `raffle_run_id` are all required —
+the SDK throws synchronously when any is missing or falsy.
+
+**UI guidance**: see [UI Guide — `requestRaffleOptin`](../_media/UIGuide_requestRaffleOptin.md).
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+const raffles = await window._smartico.api.getRaffles({
+  onUpdate: (refreshed) => console.log('[smartico] raffles refreshed — re-render', refreshed),
+});
+const raffle = raffles[0];
+const draw = raffle.draws.find(d =>
+  d.requires_optin && !d.user_opted_in && d.is_active && d.current_state !== 3
+);
+
+if (!draw) {
+  console.log('[smartico] no opt-in-required draw available — keep CTA hidden');
+  return;
+}
+
+console.log('[smartico] opt-in starting — set in-flight flag, show loading dots on the Opt-in button');
+const r = await window._smartico.api.requestRaffleOptin({
+  raffle_id: raffle.id,
+  draw_id: draw.id,        // schedule_id, NOT run_id
+  raffle_run_id: draw.run_id,
+});
+console.log('[smartico] opt-in response received — clear in-flight flag');
+
+if (r.err_code === 0) {
+  console.log('[smartico] opted in successfully — show "Fully opted in" state on the draw card; onUpdate above will fire with user_opted_in: true');
+} else if (r.err_code === 1 && r.err_message?.toLowerCase().includes('already opted in')) {
+  console.log('[smartico] already opted in (perhaps from another tab) — treat as success, show "Fully opted in"');
+} else {
+  console.error('[smartico] opt-in failed — surface this error to the user:', r.err_message);
+}
+```
+
+***
+
+### getRaffleWonPrizes()
+
+> **getRaffleWonPrizes**(`props`): `Promise`\<[`GetRaffleWonPrizesResponse`](../interfaces/GetRaffleWonPrizesResponse.md)\>
+
+Returns every prize the current user has won within a single raffle —
+across ALL of that raffle's draws, newest-won first — in one paginated
+call. Use this to power a "my prizes" screen for a raffle (prize name,
+prize image, the user's name/avatar) without walking
+[getRaffleDrawRunsHistory](#getraffledrawrunshistory) and then paging
+[getRaffleDrawRun](#getraffledrawrun)'s per-draw winner lists.
+
+Each row carries its own `raf_won_id`, which IS the `won_id` to pass to
+[claimRafflePrize](#claimraffleprize): a row with `requires_claim === true` and no
+`claimed_date` is directly claimable.
+
+#### Parameters
+
+##### props
+
+###### raffle_id
+
+`number`
+
+The parent raffle's `id` (from `TRaffle.id`). Required.
+
+###### offset?
+
+`number`
+
+Zero-based index of the first row to return. Defaults to `0`.
+
+###### limit?
+
+`number`
+
+Page size. Defaults to `20`.
+
+#### Returns
+
+`Promise`\<[`GetRaffleWonPrizesResponse`](../interfaces/GetRaffleWonPrizesResponse.md)\>
+
+Promise resolving to [GetRaffleWonPrizesResponse](../interfaces/GetRaffleWonPrizesResponse.md)
+                        (`user`, this page of `won_prizes`, and `total`;
+                        `errCode 0` on success).
+
+#### Remarks
+
+**Authentication required**
+Works only for an identified (logged-in) user. Visitor / anonymous
+sessions are rejected — call this only after identify.
+
+**Preconditions**
+`raffle_id` is required — the SDK throws synchronously when it is
+missing or falsy.
+
+**Coverage & sort order**
+Includes the user's wins from every draw of the raffle — recurring,
+one-shot, and grand draws, across all historical runs. Rows are ordered
+newest-win first; there is no "unclaimed first" ordering, so sort
+client-side if you want claimable prizes at the top.
+
+**Pagination**
+`offset` / `limit` page the `won_prizes[]` rows (the SDK defaults to
+`0` / `20`). `total` is the authoritative full count of the user's wins
+for this raffle across all draws — drive "load more" from it
+(`offset + won_prizes.length < total`). An `offset` past the end returns
+an empty `won_prizes[]` with the real `total` and `errCode 0` — not an
+error. The server does NOT clamp `limit`, so always pass an explicit,
+sane page size.
+
+**Rate limit**
+The server caps this at roughly 30 calls per minute with a ~5-second
+minimum gap between calls. Fetch on screen open and on explicit "load
+more" — don't poll it on a timer.
+
+**Error codes** (in `errCode`)
+- `0` — success. Also returned with an empty `won_prizes[]` and
+  `total 0` when the user has no wins, or is not eligible to see this
+  raffle.
+- `1` — generic server error; surface `errMsg` if present.
+
+There are no granular codes — an unknown raffle, an ineligible user,
+and "no wins" all surface as `errCode 0` with an empty list.
+
+**Reading the result**
+- Null-check `user` before reading it — it is `null` whenever
+  `won_prizes` is empty.
+- For the avatar, use `user.avatar_id` (already a full URL for a system
+  avatar, otherwise an avatar token to resolve against the widget's
+  avatar domain); `user.avatar_url` is always `null`.
+- Render `public_username` as-is (it is server-masked for privacy, e.g.
+  `"32:r*****"`) and substitute a "You" label for the current user.
+- Treat `claimed_date` as the claim flag: `null` until claimed, then
+  epoch ms.
+
+**Idempotency / Side effects**: safe and read-only — one-shot promise,
+no client cache, no subscription. The server caches the response
+briefly; a successful [claimRafflePrize](#claimraffleprize) invalidates that cache,
+so a follow-up call reflects the new `claimed_date`. This method does
+NOT refresh the [getRaffles](#getraffles) list or fire its `onUpdate` — re-call
+manually to pick up newly-won prizes or a `claimed_date` flip.
+
+**UI guidance**: see [UI Guide — `getRaffleWonPrizes`](../_media/UIGuide_getRaffleWonPrizes.md).
+
+**Visitor mode**: not supported (see "Authentication required").
+
+#### Example
+
+```ts
+const raffles = await window._smartico.api.getRaffles();
+const raffle = raffles[0];
+
+// First page of the user's won prizes for this raffle.
+const page = await window._smartico.api.getRaffleWonPrizes({
+  raffle_id: raffle.id,
+  offset: 0,
+  limit: 20,
+});
+
+if (page.errCode !== 0) {
+  console.error('[smartico] could not load won prizes — show a retry state:', page.errMsg);
+  return;
+}
+if (page.won_prizes.length === 0) {
+  console.log('[smartico] no wins in this raffle (or not eligible) — render the empty state');
+  return;
+}
+
+console.log('[smartico]', page.user?.public_username, 'won', page.total, 'prizes total');
+for (const prize of page.won_prizes) {
+  console.log('[smartico] render prize card —', prize.public_meta.name, prize.public_meta.image_url);
+  if (prize.requires_claim && !prize.claimed_date) {
+    console.log('[smartico] show a Claim CTA — on click call claimRafflePrize({ won_id:', prize.raf_won_id, '})');
+  }
+}
+
+// Load more.
+if (page.offset + page.won_prizes.length < page.total) {
+  const next = await window._smartico.api.getRaffleWonPrizes({
+    raffle_id: raffle.id,
+    offset: page.offset + page.limit,
+    limit: 20,
+  });
+  console.log('[smartico] appended', next.won_prizes.length, 'more prizes');
+}
+```
+
 ***