@smartico/public-api 0.0.420 → 0.0.421

package/docs/Callbacks.md

@@ -88,7 +88,7 @@ strings below.
 | Event key | Fires when | Handler arguments |
 |---|---|---|
 | `mini_game_win` | A mini-game spin finishes and a prize is determined. Fires for both real and visitor-mode plays. | `({ prize_id, name, visitor_win_uuid })` — `name` is the prize display name. In visitor mode, `visitor_win_uuid` can be passed to `_smartico.convertVisitorGame(uuid)` to attach the win to a real account on registration. |
-| `jackpot_win` | A jackpot the user participates in is hit (the pot explodes and the user is among the recipients). | `(message)` — the win payload (winner details + jackpot info). See the Jackpots UI guide (`docs/ui/jackpots/`) for how the default Smartico UI surfaces wins. |
+| `jackpot_win` | A jackpot the user participates in is hit (the pot explodes). Fires both for the winner and for other players taking part in the same jackpot. | `(message)` — the win payload: `jackpot` (template + live `pot`, where `pot.explode_date_ts` is the explosion time) and `winners` (currently a single entry). `winners[0].is_me` tells you whether the recipient is the winner; `winning_game_id` / `winning_provider_id` / `bet_original_date` describe the bet that triggered the win and are `null` when unavailable. See the Jackpots UI guide (`docs/ui/jackpots/`) for how the default Smartico UI surfaces wins. |
 | `ach_game_opening` | The user taps a related / eligible casino game tile from inside the gamification widget (mission, tournament, jackpot, or store context). Use this to launch the game in your own casino lobby. | `(game)` — the game object (catalog id, name, launch links, plus a `context` field naming where it was opened from). If you do not handle this event, the default Smartico UI opens the game's configured link itself. |
 
 ### Errors

package/docs/api/README.md

@@ -84,8 +84,7 @@
 
 ## Interfaces
 
-- [PointsLog](interfaces/PointsLog.md)
-- [GemsDiamondsLog](interfaces/GemsDiamondsLog.md)
+- [ActivityLogEntry](interfaces/ActivityLogEntry.md)
 - [ActivityLogMeta](interfaces/ActivityLogMeta.md)
 - [AvatarCustomizeResponse](interfaces/AvatarCustomizeResponse.md)
 - [AvatarCustomized](interfaces/AvatarCustomized.md)
@@ -128,7 +127,9 @@
 - [GetJackpotsPotsResponse](interfaces/GetJackpotsPotsResponse.md)
 - [GetJackpotsRequest](interfaces/GetJackpotsRequest.md)
 - [GetJackpotsResponse](interfaces/GetJackpotsResponse.md)
+- [JackPotWinPushWinner](interfaces/JackPotWinPushWinner.md)
 - [JackPotWinner](interfaces/JackPotWinner.md)
+- [JackpotContributionRule](interfaces/JackpotContributionRule.md)
 - [JackpotDetails](interfaces/JackpotDetails.md)
 - [JackpotHtmlTemplate](interfaces/JackpotHtmlTemplate.md)
 - [JackpotPot](interfaces/JackpotPot.md)
@@ -255,7 +256,6 @@
 - [TRaffleDrawRun](interfaces/TRaffleDrawRun.md)
 - [TransformedRaffleClaimPrizeResponse](interfaces/TransformedRaffleClaimPrizeResponse.md)
 - [TActivityLog](interfaces/TActivityLog.md)
-- [TActivityLogEntry](interfaces/TActivityLogEntry.md)
 - [TRaffleOptinResponse](interfaces/TRaffleOptinResponse.md)
 - [TAvatarDefinition](interfaces/TAvatarDefinition.md)
 - [TAvatarCustomized](interfaces/TAvatarCustomized.md)
@@ -264,8 +264,8 @@
 
 ## Type Aliases
 
-- [ActivityLogEntry](type-aliases/ActivityLogEntry.md)
 - [TournamentRegistrationTypeName](type-aliases/TournamentRegistrationTypeName.md)
+- [~~TActivityLogEntry~~](type-aliases/TActivityLogEntry.md)
 
 ## Variables
 

package/docs/api/classes/WSAPIJackpots.md

@@ -140,6 +140,8 @@ ID of the jackpot template to join.
 - The jackpot must currently be active and the user must be in its
   eligibility segment. Ineligible jackpots are filtered out of
   [jackpotGet](#jackpotget) entirely, so a card the user sees is opt-in-able.
+- Skip the opt-in CTA when the template reports `is_auto_opt_in: true` —
+  eligible users are enrolled automatically and there is nothing to join.
 
 **Error handling**
 The server returns a non-zero `errCode` with a human-readable `errMsg`

package/docs/api/classes/WSAPIUser.md

@@ -544,15 +544,16 @@ if (next) {
 
 > **getActivityLog**(`__namedParameters`): `Promise`\<[`TActivityLog`](../interfaces/TActivityLog.md)[]\>
 
-Returns the user's unified balance-change history — every points, gems, and
-diamonds transaction within the requested time window, ordered newest-first.
-Use to power an "Activity" / "History" tab showing wins, claims, purchases,
-level-up rewards, and operator adjustments.
+Returns the user's activity history within the requested time window,
+ordered newest-first. Today that is primarily wallet changes (points /
+gems / diamonds); when the server starts returning richer activity rows
+(missions, badges, levels, …), the same method surfaces them via optional
+fields on [TActivityLog](../interfaces/TActivityLog.md) — no separate call, same wire CID.
 
-The returned shape is the same regardless of currency type — `type` (see
-[UserBalanceType](../enumerations/UserBalanceType.md)) distinguishes points / gems / diamonds and
-`source_type_id` (see [PointChangeSourceType](../enumerations/PointChangeSourceType.md)) names the originating
-event.
+Existing wallet fields (`type`, `amount`, `balance`, `source_type_id`, …)
+stay stable. Clients that only read those keep working; clients that want
+the fuller feed can also read `activity_type_id`, `meta`,
+`source_entity_*`, and `is_wallet_entry` when present.
 
 #### Parameters
 
@@ -582,6 +583,18 @@ Pagination offset (0-based).
 
 Pagination ceiling (exclusive); server caps `to - from` at 50.
 
+###### types?
+
+`number`[]
+
+Optional — filter by [ActivityLogActivities](../enumerations/ActivityLogActivities.md) / `type_id`.
+
+###### src_types?
+
+`number`[]
+
+Optional — filter by [PointChangeSourceType](../enumerations/PointChangeSourceType.md) / `source_type_id`.
+
 ###### onUpdate?
 
 (`data`) => `void`
@@ -606,13 +619,18 @@ hard-caps a single response at 50 entries. For infinite scroll, advance
 `from` by 50 between calls. Both `startTimeSeconds` and `endTimeSeconds`
 are epoch seconds bounding the window the server scans.
 
+**Filtering** — optional server-side filters:
+- `types` — [ActivityLogActivities](../enumerations/ActivityLogActivities.md) / `type_id` values (e.g. Points=3, Gems=1)
+- `src_types` — [PointChangeSourceType](../enumerations/PointChangeSourceType.md) / `source_type_id` values
+Omit both for an unfiltered window.
+
 **Subscription model (`onUpdate`)**
 The callback fires when the user's `ach_points_balance`,
 `ach_gems_balance`, or `ach_diamonds_balance` changes (i.e. whenever a
 wallet event lands). The pushed payload is a FIXED re-fetch of the
 **last 10 minutes / first 50 entries** — it does NOT honor the original
-call's `startTimeSeconds` / `endTimeSeconds` / `from` / `to`. Consumers
-maintaining a long historical view must re-call `getActivityLog` with
+call's `startTimeSeconds` / `endTimeSeconds` / `from` / `to` / filters.
+Consumers maintaining a long historical view must re-call `getActivityLog` with
 their own params after receiving an `onUpdate` notification.
 
 **Refresh**
@@ -635,6 +653,8 @@ const log = await window._smartico.api.getActivityLog({
     endTimeSeconds:   now,
     from: 0,
     to:   50,
+    types: [1], // Gems only (ActivityLogActivities.Gems)
+    src_types: [11], // Tournament wins only (PointChangeSourceType.Tournament)
     onUpdate: (refreshed) => {
         console.log('[smartico] wallet changed — refreshed payload is last 10 min / 50 entries:', refreshed.length, 'rows');
         // If the consumer is showing a full 30-day view, re-call getActivityLog with the original params here.
@@ -646,52 +666,3 @@ for (const row of log) {
     console.log('[smartico] activity row — render with', row.type === 0 ? 'points' : row.type === 1 ? 'gems' : 'diamonds', 'icon, color by sign:', sign + row.amount, 'balance after:', row.balance, 'source:', row.source_type_id);
 }
 ```
-
-***
-
-### getActivityLogV2()
-
-> **getActivityLogV2**(`__namedParameters`): `Promise`\<[`TActivityLogEntry`](../interfaces/TActivityLogEntry.md)[]\>
-
-Returns the full activity log (v2) — wallet changes **and** non-wallet
-activities (missions, badges, levels, tournaments, avatars, …).
-
-**Backwards compatibility**: existing integrations should keep using
-[getActivityLog](#getactivitylog), which returns wallet-only [TActivityLog](../interfaces/TActivityLog.md)
-rows with the original field contract unchanged.
-
-**Pagination** — same `from` / `to` offset model as [getActivityLog](#getactivitylog)
-(server caps a single response at 50 entries).
-
-**Filtering** — pass `types` with [ActivityLogActivities](../enumerations/ActivityLogActivities.md) values to
-request a server-side subset (e.g. missions only). Omit for all activity types.
-
-#### Parameters
-
-##### \_\_namedParameters
-
-###### startTimeSeconds
-
-`number`
-
-###### endTimeSeconds
-
-`number`
-
-###### from
-
-`number`
-
-###### to
-
-`number`
-
-###### types?
-
-`number`[]
-
-#### Returns
-
-`Promise`\<[`TActivityLogEntry`](../interfaces/TActivityLogEntry.md)[]\>
-
-Array of [TActivityLogEntry](../interfaces/TActivityLogEntry.md) ordered newest-first.

package/docs/api/documents/Callbacks.md

@@ -88,7 +88,7 @@ strings below.
 | Event key | Fires when | Handler arguments |
 |---|---|---|
 | `mini_game_win` | A mini-game spin finishes and a prize is determined. Fires for both real and visitor-mode plays. | `({ prize_id, name, visitor_win_uuid })` — `name` is the prize display name. In visitor mode, `visitor_win_uuid` can be passed to `_smartico.convertVisitorGame(uuid)` to attach the win to a real account on registration. |
-| `jackpot_win` | A jackpot the user participates in is hit (the pot explodes and the user is among the recipients). | `(message)` — the win payload (winner details + jackpot info). See the Jackpots UI guide (`docs/ui/jackpots/`) for how the default Smartico UI surfaces wins. |
+| `jackpot_win` | A jackpot the user participates in is hit (the pot explodes). Fires both for the winner and for other players taking part in the same jackpot. | `(message)` — the win payload: `jackpot` (template + live `pot`, where `pot.explode_date_ts` is the explosion time) and `winners` (currently a single entry). `winners[0].is_me` tells you whether the recipient is the winner; `winning_game_id` / `winning_provider_id` / `bet_original_date` describe the bet that triggered the win and are `null` when unavailable. See the Jackpots UI guide (`docs/ui/jackpots/`) for how the default Smartico UI surfaces wins. |
 | `ach_game_opening` | The user taps a related / eligible casino game tile from inside the gamification widget (mission, tournament, jackpot, or store context). Use this to launch the game in your own casino lobby. | `(game)` — the game object (catalog id, name, launch links, plus a `context` field naming where it was opened from). If you do not handle this event, the default Smartico UI opens the game's configured link itself. |
 
 ### Errors

package/docs/api/enumerations/ActivityLogActivities.md

@@ -1,6 +1,6 @@
 # Enumeration: ActivityLogActivities
 
-Activity-log entry type as returned on the v2 wire (`type_id`).
+Activity-log entry type as returned on the wire (`type_id`).
 
 ## Enumeration Members
 

package/docs/api/enumerations/PointChangeSourceType.md

@@ -98,6 +98,12 @@
 
 ***
 
+### Jackpot
+
+> **Jackpot**: `20`
+
+***
+
 ### Raffle
 
 > **Raffle**: `21`

package/docs/api/interfaces/ActivityLogEntry.md

@@ -0,0 +1,124 @@
+# Interface: ActivityLogEntry
+
+One raw activity-log row as it arrives on the wire.
+
+JS consumers receive the friendlier [TActivityLog](TActivityLog.md) instead — this is the
+pre-transform shape, documented for native clients that read the protocol directly.
+
+## Properties
+
+### create\_date
+
+> **create\_date**: `object`
+
+Creation time; `seconds` is the epoch value in SECONDS (not ms).
+
+#### seconds
+
+> **seconds**: `number`
+
+#### nanos?
+
+> `optional` **nanos?**: `number`
+
+***
+
+### user\_ext\_id
+
+> **user\_ext\_id**: `string`
+
+***
+
+### crm\_brand\_id
+
+> **crm\_brand\_id**: `string`
+
+Sent as a string on the wire.
+
+***
+
+### type
+
+> **type**: [`ActivityLogActivities`](../enumerations/ActivityLogActivities.md)
+
+Kind of activity this row records.
+
+***
+
+### ctx\_1
+
+> **ctx\_1**: `number`
+
+Sub-action within `type` (e.g. unlock vs complete, add vs deduct).
+
+***
+
+### ctx\_meta?
+
+> `optional` **ctx\_meta?**: [`ActivityLogMeta`](ActivityLogMeta.md)
+
+Extra display payload for the row; contents vary by `type`.
+
+***
+
+### source\_type\_id
+
+> **source\_type\_id**: [`PointChangeSourceType`](../enumerations/PointChangeSourceType.md)
+
+What triggered the change.
+
+***
+
+### source\_ref\_id
+
+> **source\_ref\_id**: `number`
+
+More specific id within the source (e.g. level id, draw id, win id).
+
+***
+
+### source\_root\_id
+
+> **source\_root\_id**: `number`
+
+Root / parent entity id when the source is nested.
+
+***
+
+### amount
+
+> **amount**: `number`
+
+Delta applied by this row, in the balance named by `type`.
+
+***
+
+### balance
+
+> **balance**: `number`
+
+Balance after this row, in the balance named by `type`.
+
+***
+
+### user\_points\_balance?
+
+> `optional` **user\_points\_balance?**: `number`
+
+Points balance after this row; points rows only.
+
+***
+
+### user\_points\_ever?
+
+> `optional` **user\_points\_ever?**: `number`
+
+Total points ever collected after this row; points rows only.
+
+***
+
+### points\_collected?
+
+> `optional` **points\_collected?**: `number`
+
+Placeholder on points rows (`-1`) — read `amount` for the real delta.

package/docs/api/interfaces/ActivityLogMeta.md

@@ -1,11 +1,17 @@
 # Interface: ActivityLogMeta
 
+Extra display payload attached to an activity-log row (`ctx_meta` on the wire).
+Which keys are present depends on the row's activity type — treat every field
+as optional and render only what is there.
+
 ## Properties
 
 ### name?
 
 > `optional` **name?**: `string`
 
+Display name of the source entity (mission, tournament, raffle, …).
+
 ***
 
 ### image\_url?
@@ -24,14 +30,108 @@
 
 > `optional` **user\_points\_balance\_before?**: `number`
 
+Points balance before this row; points rows.
+
 ***
 
 ### points\_requested?
 
 > `optional` **points\_requested?**: `number`
 
+Points the awarding rule asked for; points rows.
+
 ***
 
 ### user\_points\_ever?
 
 > `optional` **user\_points\_ever?**: `number`
+
+Total points ever collected after this row; points rows.
+
+***
+
+### amount\_requested?
+
+> `optional` **amount\_requested?**: `number`
+
+Gems / diamonds the awarding rule asked for; gems / diamonds rows.
+
+***
+
+### balance\_before?
+
+> `optional` **balance\_before?**: `number`
+
+Gems / diamonds balance before this row.
+
+***
+
+### affects\_level?
+
+> `optional` **affects\_level?**: `boolean`
+
+Whether this row counts toward level progress.
+
+***
+
+### affects\_leaderboard?
+
+> `optional` **affects\_leaderboard?**: `boolean`
+
+Whether this row counts toward leaderboards.
+
+***
+
+### affects\_current\_balance?
+
+> `optional` **affects\_current\_balance?**: `boolean`
+
+Whether this row moved the spendable balance.
+
+***
+
+### user\_initialization?
+
+> `optional` **user\_initialization?**: `boolean`
+
+Set on the row that seeds a brand-new user's wallet.
+
+***
+
+### is\_recurring?
+
+> `optional` **is\_recurring?**: `boolean`
+
+Set on mission rows for repeatable missions.
+
+***
+
+### from\_level\_id?
+
+> `optional` **from\_level\_id?**: `number`
+
+Level moved from; level-change rows.
+
+***
+
+### to\_level\_id?
+
+> `optional` **to\_level\_id?**: `number`
+
+Level moved to; level-change rows.
+
+***
+
+### from\_level\_public\_meta?
+
+> `optional` **from\_level\_public\_meta?**: `any`
+
+Public meta of the level moved from; level-change rows.
+
+***
+
+### to\_level\_public\_meta?
+
+> `optional` **to\_level\_public\_meta?**: `any`
+
+Public meta of the level moved to; level-change rows.

package/docs/api/interfaces/JackPotWinPushWinner.md

@@ -0,0 +1,103 @@
+# Interface: JackPotWinPushWinner
+
+One winner entry inside a [JackpotWinPush](JackpotWinPush.md).
+
+Distinct from [JackPotWinner](JackPotWinner.md), which is the winner shape returned by the
+`getJackpotWinners()` history — the live win push carries bet / trigger context
+and no avatar.
+
+## Properties
+
+### user\_id
+
+> **user\_id**: `number`
+
+Smartico user ID of the winner
+
+***
+
+### ext\_user\_id
+
+> **ext\_user\_id**: `string`
+
+Operator's external user ID of the winner
+
+***
+
+### is\_me
+
+> **is\_me**: `boolean`
+
+Flag indicating that this copy of the push was delivered to the winner themselves
+
+***
+
+### public\_username
+
+> **public\_username**: `string`
+
+Name of the winner, masked for everyone except `is_me` unless masking is disabled by request to Smartico AM team
+
+***
+
+### public\_username\_custom
+
+> **public\_username\_custom**: `string`
+
+Custom display name; falls back to `public_username` when not set
+
+***
+
+### winning\_amount\_jp\_currency
+
+> **winning\_amount\_jp\_currency**: `number`
+
+Won amount in the Jackpot currency; real and bonus parts are combined
+
+***
+
+### winning\_amount\_wallet\_currency
+
+> **winning\_amount\_wallet\_currency**: `number`
+
+Won amount in the user Wallet currency; real and bonus parts are combined
+
+***
+
+### winning\_position
+
+> **winning\_position**: `number`
+
+Position of the winner. Relevant for jackpots where there could be multiple winners
+
+***
+
+### winning\_game\_id
+
+> **winning\_game\_id**: `string`
+
+External game ID of the game whose bet triggered the win; `null` when the triggering bet context is unavailable
+
+***
+
+### winning\_provider\_id
+
+> **winning\_provider\_id**: `string`
+
+External provider ID of the triggering game's provider; `null` when the triggering bet context is unavailable
+
+***
+
+### bet\_original\_date
+
+> **bet\_original\_date**: `number`
+
+Placement time of the triggering bet as reported by the operator (epoch milliseconds) — not the time Smartico processed it; `null` when unavailable
+
+***
+
+### pending\_approve?
+
+> `optional` **pending\_approve?**: `boolean`
+
+Present only on the `is_me` copy; `true` while the win awaits manual approval before payout

package/docs/api/interfaces/JackPotWinner.md

@@ -46,4 +46,12 @@ Position of the winner. Relevant for jackpots where there could be multiple winn
 
 > **avatar\_id**: `string`
 
-Avatar of the winner
+Avatar image URL of the winner
+
+***
+
+### avatar\_real\_id
+
+> **avatar\_real\_id**: `number`
+
+Numeric ID of the winner's avatar; `null` when the winner has not picked one

package/docs/api/interfaces/JackpotContributionRule.md

@@ -0,0 +1,49 @@
+# Interface: JackpotContributionRule
+
+One per-game / per-provider override of a jackpot's default contribution.
+
+When a qualifying bet matches a rule's `extEntityIds`, that rule's
+`contributionValue` and `type` are used instead of the template-level
+`contribution_value` / `contribution_type`. Rules are informational for
+consumers — the server applies them. Note the camelCase field names; the rest
+of the jackpot payload is snake_case.
+
+## Properties
+
+### ruleId
+
+> **ruleId**: `number`
+
+Stable ID of the rule within its template
+
+***
+
+### jpTemplateId
+
+> **jpTemplateId**: `number`
+
+Template this rule belongs to
+
+***
+
+### type
+
+> **type**: [`JackpotContributionType`](../enumerations/JackpotContributionType.md)
+
+Whether `contributionValue` is a fixed amount or a percentage; see [JackpotContributionType](../enumerations/JackpotContributionType.md)
+
+***
+
+### extEntityIds
+
+> **extEntityIds**: `string`[]
+
+Operator-side game or provider IDs this rule applies to
+
+***
+
+### contributionValue
+
+> **contributionValue**: `number`
+
+Contribution to apply for matching bets — fixed amount or percentage depending on `type`

package/docs/api/interfaces/JackpotDetails.md

@@ -61,6 +61,22 @@ Amount of contribution per qualifying bet — fixed value or percentage dependin
 
 ***
 
+### contribution\_rules
+
+> **contribution\_rules**: [`JackpotContributionRule`](JackpotContributionRule.md)[]
+
+Per-game / per-provider overrides of `contribution_type` + `contribution_value`; see [JackpotContributionRule](JackpotContributionRule.md). Empty when the template contributes at a flat rate.
+
+***
+
+### related\_games
+
+> **related\_games**: [`AchRelatedGame`](AchRelatedGame.md)[]
+
+Reserved — the server currently always sends an empty array. Use `getJackpotEligibleGames()` for the eligible-games list.
+
+***
+
 ### pot
 
 > **pot**: [`JackpotPot`](JackpotPot.md)
@@ -77,6 +93,14 @@ Live pot snapshot (amount, temperature, last explosion timestamp).
 
 ***
 
+### is\_auto\_opt\_in
+
+> **is\_auto\_opt\_in**: `boolean`
+
+`true` when eligible users are opted in automatically, so no opt-in CTA is needed; `false` means `jackpotOptIn()` must be called explicitly.
+
+***
+
 ### ach\_related\_game\_allow\_all
 
 > **ach\_related\_game\_allow\_all**: `boolean`

package/docs/api/interfaces/JackpotPot.md

@@ -41,7 +41,15 @@ Current pot amount converted to the user's wallet currency (`user_currency`).
 
 > **explode\_date\_ts**: `number`
 
-Unix ms timestamp of when this pot last exploded; `0` if it has never exploded.
+Unix ms timestamp of when this pot last exploded; `null` while the pot is still running.
+
+***
+
+### user\_id
+
+> **user\_id**: `number`
+
+Owning user for `JackpotType.Personal` pots; `null` for shared `MultiUser` pots.
 
 ***