@smartico/public-api 0.0.408 → 0.0.410

package/src/WSAPI/WSAPIMiniGames.ts

@@ -64,6 +64,27 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *   games server (not this SDK); the SAW spin is fired
 	 *   server-internally to deduct the buy-in.
 	 *
+	 * **Per-prize statistics (`expose_game_stat_on_api`)**
+	 * Each template's `prizes` array always carries the definition
+	 * fields — name, icon, `prize_type`, `prize_value`, acknowledge
+	 * configuration. The stock-statistics fields are gated by an
+	 * operator template setting, surfaced as
+	 * `expose_game_stat_on_api`:
+	 * - Populated when enabled: `pool` (remaining stock),
+	 *   `wins_count` (total wins across all players), `weekdays`
+	 *   (ISO 1–7 days the prize can be won), `active_from_ts` /
+	 *   `active_till_ts` (prize availability window).
+	 * - Omitted when disabled (the default) — this keeps the live
+	 *   prize economy (stock levels, win rates, schedules) hidden
+	 *   from players.
+	 * - Exception: `pool` is always populated for `MatchX` / `Quiz`
+	 *   templates, whose game flow needs the remaining stock.
+	 * - `pool_initial` is populated regardless of the setting.
+	 * When enabled, the values are also kept current — the server
+	 * refreshes the prize rows on each fetch and drops its template
+	 * caches after every play, so `pool` / `wins_count` are safe to
+	 * drive an "X prizes left" scarcity UI.
+	 *
 	 * **Cache TTL**: the SDK caches the response for 30 seconds. Cache
 	 * is fully cleared on login / logout.
 	 *
@@ -290,14 +311,19 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * it later by calling {@link miniGameWinAcknowledgeRequest} with the
 	 * `request_id` returned on this result.
 	 *
-	 * What `acknowledge: false` does and does NOT defer:
-	 * - For STANDARD prizes the value is credited at spin time
-	 *   regardless, so opting out does NOT delay the balance change —
-	 *   it only defers the "delivered" bookkeeping and the `is_claimed`
-	 *   flag flipping in {@link getMiniGamesHistory}.
-	 * - For operator-configured "explicit claim" prizes the credit IS
-	 *   deferred until the spin is acknowledged, so those require an
-	 *   explicit acknowledge to finalise.
+	 * What `acknowledge: false` defers:
+	 * - For STANDARD prizes the value is credited when the spin is
+	 *   finalised — by your later acknowledge or, failing that, by the
+	 *   server-side fallback below — so opting out delays the balance
+	 *   change by at most that fallback window. The `is_claimed` flag in
+	 *   {@link getMiniGamesHistory} flips on the same finalisation.
+	 * - For operator-configured "explicit claim" prizes the credit is
+	 *   deferred until your explicit acknowledge — the fallback does not
+	 *   cover them.
+	 *
+	 * While the spin is un-finalised it can also be finalised as LOST —
+	 * prize discarded back to the pool — via
+	 * {@link miniGameWinAcknowledgeRequest} with `{ lose: true }`.
 	 *
 	 * A server-side fallback auto-acknowledges ordinary un-acknowledged
 	 * spins after a short delay (about 1–3 minutes), so an ordinary
@@ -328,8 +354,10 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *   time the call resolves. Balance updates flow via the
 	 *   user-properties channel (observe via {@link getUserProfile}).
 	 * - Prize value credited per the prize's type (see "Prize handling"
-	 *   above). Standard prizes are credited at spin time; "explicit
-	 *   claim" prizes are credited when the spin is acknowledged.
+	 *   above) when the spin is finalised — with the default
+	 *   auto-acknowledge that happens before the call resolves;
+	 *   "explicit claim" prizes are credited only by an explicit
+	 *   acknowledge.
 	 * - The play is recorded server-side for analytics / reporting.
 	 *
 	 * **UI guidance**: see [UI Guide — `playMiniGame`](../../docs/ui/minigames/UIGuide_playMiniGame.md).
@@ -394,18 +422,24 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *
 	 * @example
 	 * Manual finalisation (`acknowledge: false`) — e.g. an explicit
-	 * "Claim" CTA, or finalising on your own schedule:
+	 * "Claim" CTA, a decline/forfeit flow, or finalising on your own
+	 * schedule:
 	 * ```ts
 	 * const r = await window._smartico.api.playMiniGame(game.id, { acknowledge: false });
 	 * if (r.err_code === 0) {
-	 *   // Spin resolved but not yet acknowledged. For standard prizes the
-	 *   // balance already changed server-side; "explicit claim" prizes
-	 *   // are credited only by the acknowledge below.
+	 *   // Spin resolved but not yet finalised — the prize is not credited
+	 *   // yet. Your acknowledge below credits it (for standard prizes the
+	 *   // server-side fallback would eventually do the same).
 	 *   console.log('[smartico] prize won — show the result / Claim CTA, then finalise');
 	 *
 	 *   // On the user's Claim click, finalise with the request_id from the result.
 	 *   await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
 	 *   console.log('[smartico] win finalised — refresh getUserProfile / getMiniGames to reflect it');
+	 *
+	 *   // Or, if the game flow ends in the player declining / losing the
+	 *   // drawn prize, finalise the spin as lost instead — the prize is
+	 *   // not credited and returns to the prize pool:
+	 *   // await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id, { lose: true });
 	 * }
 	 * ```
 	 */
@@ -433,9 +467,10 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 
 	/**
 	 * Manually acknowledges a mini-game spin — marks the win delivered
-	 * server-side. Most consumers do NOT need this: {@link playMiniGame}
-	 * acknowledges by default (`acknowledge: true`) and
-	 * {@link playMiniGameBatch} acknowledges automatically. Call this
+	 * server-side, or (with `lose: true`) finalises it as lost and
+	 * returns the prize to the pool. Most consumers do NOT need this:
+	 * {@link playMiniGame} acknowledges by default (`acknowledge: true`)
+	 * and {@link playMiniGameBatch} acknowledges automatically. Call this
 	 * directly only when you took ownership of the acknowledge step or
 	 * need to recover a lost one.
 	 *
@@ -458,6 +493,23 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * `client_request_id` on a {@link getMiniGamesHistory} row are the
 	 * same correlation id — this method accepts either.
 	 *
+	 * **Finalising as lost (`lose: true`)**
+	 * Pass `{ lose: true }` to finalise the spin as LOST instead of won:
+	 * the prize is NOT credited and is returned to the game's prize pool
+	 * (available again for other players), and the spin fires the
+	 * mini-game "lose" engagement event instead of the win one. On the
+	 * next {@link getMiniGamesHistory} fetch the row shows `is_claimed:
+	 * true` with no prize attached. Use this for game mechanics where the
+	 * player can decline or forfeit the drawn prize — e.g. a
+	 * gamble/discard step, or a client-driven game where the user's final
+	 * action decides whether the pre-drawn prize is actually won. It only
+	 * works on a spin that is not yet finalised, so it requires playing
+	 * with `acknowledge: false` and calling promptly — once the automatic
+	 * acknowledge or the server-side fallback (below) has finalised the
+	 * spin, `lose: true` is a no-op and the prize stays credited.
+	 * ("Explicit claim" prizes are exempt from the fallback, so for them
+	 * there is no time pressure.)
+	 *
 	 * **Idempotency**: safe. Acknowledging a spin that is already
 	 * finalised — by you, by the automatic acknowledge, or by the
 	 * fallback — is a no-op with no double credit. Acknowledging a
@@ -472,11 +524,12 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * call here.
 	 *
 	 * **Side effects** (first successful call for an un-acknowledged spin)
-	 * - For "explicit claim" prizes, the prize value is credited on this
-	 *   call. For standard prizes the value was already credited at spin
-	 *   time (see {@link playMiniGame} "Prize handling"); this call only
-	 *   marks the win delivered.
-	 * - The spin's `is_claimed` flips to `true` on the next
+	 * - Default (win): the prize value is credited on this call — this is
+	 *   the finalisation step that credits standard and "explicit claim"
+	 *   prizes alike (see {@link playMiniGame} "Prize handling").
+	 * - With `lose: true`: no credit; the prize returns to the prize pool
+	 *   and the "lose" engagement event fires.
+	 * - Either way the spin's `is_claimed` flips to `true` on the next
 	 *   {@link getMiniGamesHistory} fetch.
 	 *
 	 * **Visitor mode**: not supported.
@@ -486,6 +539,10 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *                    (played with `acknowledge: false`), or the
 	 *                    `client_request_id` of a
 	 *                    {@link getMiniGamesHistory} row.
+	 * @param options.lose  Optional. When `true`, finalises the spin as
+	 *                      lost — the prize is not credited and returns
+	 *                      to the prize pool (see "Finalising as lost").
+	 *                      Omit (or pass `false`) to deliver the win.
 	 *
 	 * @example
 	 * ```ts
@@ -496,6 +553,10 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 *   await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
 	 * }
 	 *
+	 * // Decline / forfeit — finalise the same spin as lost instead:
+	 * // the prize is not credited and goes back to the prize pool.
+	 * await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id, { lose: true });
+	 *
 	 * // Recovery — re-acknowledge any spins a batch acknowledge missed.
 	 * const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
 	 * for (const row of history.filter(h => !h.is_claimed)) {
@@ -504,8 +565,8 @@ export class WSAPIMiniGames extends WSAPIRaffles {
 	 * }
 	 * ```
 	 */
-	public async miniGameWinAcknowledgeRequest(request_id: string) {
-		return this.api.doAcknowledgeRequest(this.userExtId, request_id);
+	public async miniGameWinAcknowledgeRequest(request_id: string, { lose }: { lose?: boolean } = {}) {
+		return this.api.doAcknowledgeRequest(this.userExtId, request_id, lose);
 	}
 
 	/**

package/src/WSAPI/WSAPITypes.ts

@@ -53,25 +53,29 @@ export interface TMiniGamePrize {
 	acknowledge_dp_additional?: string;
 	/** The name of the action button in modal pop-up (additional) */
 	acknowledge_action_title_additional?: string;
+	/** Deep link that will trigger some action in modal pop-up (second button) */
+	second_btn?: string,
+	/** The name of the action button in modal pop-up (second button) */
+	second_btn_action_title?: string;
 	/** Message when the prize pool is empty for that specific prize */
 	out_of_stock_message?: string;
-	/** Number of items in stock */
+	/** Remaining stock of the prize — decrements on each win, refunded if the spin is finalised as lost. Populated only when the template's `expose_game_stat_on_api` is enabled; always populated for MatchX / Quiz games */
 	pool?: number;
-	/** Initial number of items in stock */
+	/** Initial (configured) stock of the prize. Populated regardless of `expose_game_stat_on_api` */
 	pool_initial?: number;
-	/** Number of wins in game */
+	/** Number of times the prize has been won, across all players. Populated only when the template's `expose_game_stat_on_api` is enabled */
 	wins_count?: number;
-	/** Number of days of week, when the prize can be available */
+	/** ISO weekday numbers (1 = Monday … 7 = Sunday) on which the prize can be won; absent = any day. Populated only when the template's `expose_game_stat_on_api` is enabled */
 	weekdays?: number[];
-	/** Holds time from which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp) */
+	/** Time from which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled */
 	active_from_ts?: number;
-	/** Holds time till which prize will become available, for the prizes that are targeted to be available from specific time (UNIX timestamp) */
+	/** Time until which the prize can be won (epoch ms), evaluated against `relative_period_timezone`. Populated only when the template's `expose_game_stat_on_api` is enabled */
 	active_till_ts?: number;
-	/** Time zone to ensure each day aligns with your local midnight. */
+	/** Timezone offset in minutes used to evaluate `weekdays` and the active window (UTC minus local, as in JS `Date.getTimezoneOffset()` — e.g. `-180` for UTC+3) */
 	relative_period_timezone?: number;
-	/** Flag indicating that the prize is surcharged (available all the time, despite pool numbers) */
+	/** When true, the prize stays winnable even when its `pool` reaches 0 (effectively unlimited stock) */
 	is_surcharge?: boolean;
-	/** Flag indicating the state of the prize */
+	/** Always `false` in API responses — deleted prizes are excluded server-side */
 	is_deleted?: boolean;
 	/** The custom data of the mini-game defined by operator in the BackOffice. Can be a JSON object, string or number */
 	custom_data?: any;
@@ -204,7 +208,7 @@ export interface TMiniGameTemplate {
 	/** List of prizes for mini-games */
 	prizes: TMiniGamePrize[];
 
-	/** When enabled, the number of items in the pool and number of won items will be exposed in the Retention API and in the UI Widgets */
+	/** Operator template setting. When enabled, the per-prize stock statistics (`pool`, `wins_count`, `weekdays`, `active_from_ts` / `active_till_ts`) are populated on `prizes` and kept current after every play; when disabled (default) those fields are omitted. See `getMiniGames` "Per-prize statistics" */
 	expose_game_stat_on_api?: boolean;
 
 	/** Time zone to ensure each day aligns with your local midnight. */
@@ -215,7 +219,7 @@ export interface TMiniGameTemplate {
 	activeTillDate?: number;
 	/** The amount of steps to complete the game and gather the prize */
 	steps_to_finish_game?: number;
-	/** Hold the id of the custom section */
+	/** ID of the operator-defined custom section (widget menu grouping) the mini-game is assigned to */
 	custom_section_id?: number;
 
 	/** The UI definition of the mini-game */
@@ -228,7 +232,7 @@ export interface TMiniGameTemplate {
 	max_number_of_attempts?: number;
 	/** The period of time in milliseconds during which the user can do the maximum number of attempts */
 	max_spins_period_ms?: number;
-	/** The ID of the user spin id to expose on the game */
+	/** Which identifier to show next to a win result for transparency/audit — 'userId' (the player's external user id) or 'spinId' (the spin's transaction id). Absent when the operator disabled it */
 	expose_user_spin_id?: SAWExposeUserSpinIdName;
 }
 

package/docs/api/interfaces/TClanTournamentPlayer.md

@@ -1,55 +0,0 @@
-# Interface: TClanTournamentPlayer
-
-## Properties
-
-### user\_id
-
-> **user\_id**: `number`
-
-***
-
-### clean\_ext\_user\_id
-
-> **clean\_ext\_user\_id**: `string`
-
-***
-
-### public\_username
-
-> **public\_username**: `string`
-
-***
-
-### avatar\_id
-
-> **avatar\_id**: `string`
-
-***
-
-### avatar\_real\_id
-
-> **avatar\_real\_id**: `number`
-
-***
-
-### avatar\_url?
-
-> `optional` **avatar\_url?**: `string`
-
-***
-
-### position
-
-> **position**: `number`
-
-***
-
-### scores
-
-> **scores**: `number`
-
-***
-
-### is\_me
-
-> **is\_me**: `boolean`

package/docs/api/interfaces/TClanTournamentPlayersResult.md

@@ -1,13 +0,0 @@
-# Interface: TClanTournamentPlayersResult
-
-## Properties
-
-### tournament\_instance\_id
-
-> **tournament\_instance\_id**: `number`
-
-***
-
-### players
-
-> **players**: [`TClanTournamentPlayer`](TClanTournamentPlayer.md)[]