@smartico/public-api 0.0.417 → 0.0.419

package/docs/api/README.md

@@ -8,6 +8,7 @@
 
 ## Enumerations
 
+- [ActivityLogActivities](enumerations/ActivityLogActivities.md)
 - [PointChangeSourceType](enumerations/PointChangeSourceType.md)
 - [UserBalanceType](enumerations/UserBalanceType.md)
 - [AvatarCustomizeErrorCode](enumerations/AvatarCustomizeErrorCode.md)
@@ -85,6 +86,7 @@
 
 - [PointsLog](interfaces/PointsLog.md)
 - [GemsDiamondsLog](interfaces/GemsDiamondsLog.md)
+- [ActivityLogMeta](interfaces/ActivityLogMeta.md)
 - [AvatarCustomizeResponse](interfaces/AvatarCustomizeResponse.md)
 - [AvatarCustomized](interfaces/AvatarCustomized.md)
 - [AvatarDefinition](interfaces/AvatarDefinition.md)
@@ -147,6 +149,8 @@
 - [SAWGetTemplatesRequest](interfaces/SAWGetTemplatesRequest.md)
 - [SAWGetTemplatesResponse](interfaces/SAWGetTemplatesResponse.md)
 - [SAWPrize](interfaces/SAWPrize.md)
+- [SAWPrizeDropAknowledgeCancelRequest](interfaces/SAWPrizeDropAknowledgeCancelRequest.md)
+- [SAWPrizeDropAknowledgeCancelResponse](interfaces/SAWPrizeDropAknowledgeCancelResponse.md)
 - [SAWPrizeDropAknowledgeRequest](interfaces/SAWPrizeDropAknowledgeRequest.md)
 - [SAWPrizeDropAknowledgeResponse](interfaces/SAWPrizeDropAknowledgeResponse.md)
 - [SAWPrizeDropWinPush](interfaces/SAWPrizeDropWinPush.md)
@@ -251,6 +255,7 @@
 - [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)

package/docs/api/classes/WSAPIJackpots.md

@@ -328,7 +328,9 @@ in the jackpot's NATIVE currency, NOT the user's wallet currency. If a
 user-currency display is needed, the consumer must convert client-side.
 
 **Refresh**
-- The SDK caches per `jp_template_id` for 30 seconds.
+- The SDK caches each page separately (per `jp_template_id` +
+  `limit` + `offset`) for 30 seconds, so paging back and forth is
+  served from cache and each page keeps its own fresh copy.
 - Caches clear on jackpot-win push events and on opt-in / opt-out.
 
 **Error handling**

package/docs/api/classes/WSAPIMiniGames.md

@@ -485,7 +485,7 @@ if (r.err_code === 0) {
 
 ### miniGameWinAcknowledgeRequest()
 
-> **miniGameWinAcknowledgeRequest**(`request_id`, `__namedParameters?`): `Promise`\<[`SAWDoAknowledgeResponse`](../interfaces/SAWDoAknowledgeResponse.md)\>
+> **miniGameWinAcknowledgeRequest**(`request_id`, `lose?`): `Promise`\<[`SAWDoAknowledgeResponse`](../interfaces/SAWDoAknowledgeResponse.md)\>
 
 Manually acknowledges a mini-game spin — marks the win delivered
 server-side, or (with `lose: true`) finalises it as lost and
@@ -507,7 +507,12 @@ Correlation id of the spin to finalise: the
                    `client_request_id` of a
                    [getMiniGamesHistory](#getminigameshistory) row.
 
-##### \_\_namedParameters?
+##### 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.
 
 ###### lose?
 

package/docs/api/classes/WSAPIUser.md

@@ -646,3 +646,52 @@ 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/enumerations/ActivityLogActivities.md

@@ -0,0 +1,123 @@
+# Enumeration: ActivityLogActivities
+
+Activity-log entry type as returned on the v2 wire (`type_id`).
+
+## Enumeration Members
+
+### Gems
+
+> **Gems**: `1`
+
+***
+
+### Diamonds
+
+> **Diamonds**: `2`
+
+***
+
+### Points
+
+> **Points**: `3`
+
+***
+
+### LevelChanged
+
+> **LevelChanged**: `4`
+
+***
+
+### Bonus
+
+> **Bonus**: `5`
+
+***
+
+### PrizeDrop
+
+> **PrizeDrop**: `6`
+
+***
+
+### Minigame
+
+> **Minigame**: `7`
+
+***
+
+### RaffleTicket
+
+> **RaffleTicket**: `8`
+
+***
+
+### Avatar
+
+> **Avatar**: `9`
+
+***
+
+### Task
+
+> **Task**: `10`
+
+***
+
+### Mission
+
+> **Mission**: `11`
+
+***
+
+### Badge
+
+> **Badge**: `12`
+
+***
+
+### TangiblePrize
+
+> **TangiblePrize**: `13`
+
+***
+
+### Jackpot
+
+> **Jackpot**: `14`
+
+***
+
+### Spin
+
+> **Spin**: `15`
+
+***
+
+### NoPrize
+
+> **NoPrize**: `16`
+
+***
+
+### Leaderboard
+
+> **Leaderboard**: `17`
+
+***
+
+### Tournament
+
+> **Tournament**: `18`
+
+***
+
+### ClanTournament
+
+> **ClanTournament**: `19`
+
+***
+
+### Clan
+
+> **Clan**: `20`

package/docs/api/enumerations/PointChangeSourceType.md

@@ -107,3 +107,9 @@
 ### Avatars
 
 > **Avatars**: `22`
+
+***
+
+### Clan
+
+> **Clan**: `23`

package/docs/api/interfaces/ActivityLogMeta.md

@@ -0,0 +1,37 @@
+# Interface: ActivityLogMeta
+
+## Properties
+
+### name?
+
+> `optional` **name?**: `string`
+
+***
+
+### image\_url?
+
+> `optional` **image\_url?**: `string`
+
+***
+
+### position?
+
+> `optional` **position?**: `number`
+
+***
+
+### user\_points\_balance\_before?
+
+> `optional` **user\_points\_balance\_before?**: `number`
+
+***
+
+### points\_requested?
+
+> `optional` **points\_requested?**: `number`
+
+***
+
+### user\_points\_ever?
+
+> `optional` **user\_points\_ever?**: `number`

package/docs/api/interfaces/SAWPrizeDropAknowledgeCancelRequest.md

@@ -0,0 +1,47 @@
+# Interface: SAWPrizeDropAknowledgeCancelRequest
+
+## Extends
+
+- `ProtocolMessage`
+
+## Properties
+
+### cid
+
+> **cid**: `number`
+
+#### Inherited from
+
+`ProtocolMessage.cid`
+
+***
+
+### ts?
+
+> `optional` **ts?**: `number`
+
+#### Inherited from
+
+`ProtocolMessage.ts`
+
+***
+
+### uuid?
+
+> `optional` **uuid?**: `string`
+
+#### Inherited from
+
+`ProtocolMessage.uuid`
+
+***
+
+### request\_id
+
+> **request\_id**: `string`
+
+***
+
+### pending\_message\_id
+
+> **pending\_message\_id**: `number`

package/docs/api/interfaces/SAWPrizeDropAknowledgeCancelResponse.md

@@ -0,0 +1,41 @@
+# Interface: SAWPrizeDropAknowledgeCancelResponse
+
+## Extends
+
+- `ProtocolMessage`
+
+## Properties
+
+### cid
+
+> **cid**: `number`
+
+#### Inherited from
+
+`ProtocolMessage.cid`
+
+***
+
+### ts?
+
+> `optional` **ts?**: `number`
+
+#### Inherited from
+
+`ProtocolMessage.ts`
+
+***
+
+### uuid?
+
+> `optional` **uuid?**: `string`
+
+#### Inherited from
+
+`ProtocolMessage.uuid`
+
+***
+
+### request\_id
+
+> **request\_id**: `string`

package/docs/api/interfaces/SAWTemplateUI.md

@@ -572,7 +572,7 @@ controlling obstacle frequency and game speed.
 
 URL of the operator-hosted custom mini-game, loaded inside an iframe by
 the widget for `SAWGameType.CustomMinigame`.  The operator is trusted
-(the URL resolves to the operator's own published Web Studio game), but
+(the URL resolves to the operator's own published Vibe Studio game), but
 the iframe is still rendered with a restrictive sandbox as defence in
 depth: `sandbox="allow-scripts allow-forms allow-same-origin allow-popups
 allow-pointer-lock"`. Top-level navigation is intentionally not allowed,

package/docs/api/interfaces/TActivityLogEntry.md

@@ -0,0 +1,100 @@
+# Interface: TActivityLogEntry
+
+Full activity-log row returned by [WSAPIUser.getActivityLogV2](../classes/WSAPIUser.md#getactivitylogv2).
+Includes wallet changes and non-wallet activities (missions, badges, levels, …).
+
+## Properties
+
+### create\_date
+
+> **create\_date**: `number`
+
+***
+
+### user\_ext\_id
+
+> **user\_ext\_id**: `string`
+
+***
+
+### crm\_brand\_id
+
+> **crm\_brand\_id**: `number`
+
+***
+
+### type
+
+> **type**: [`UserBalanceType`](../enumerations/UserBalanceType.md)
+
+***
+
+### amount
+
+> **amount**: `number`
+
+***
+
+### balance
+
+> **balance**: `number`
+
+***
+
+### total\_ever?
+
+> `optional` **total\_ever?**: `number`
+
+***
+
+### source\_type\_id
+
+> **source\_type\_id**: [`PointChangeSourceType`](../enumerations/PointChangeSourceType.md)
+
+***
+
+### activity\_type\_id?
+
+> `optional` **activity\_type\_id?**: [`ActivityLogActivities`](../enumerations/ActivityLogActivities.md)
+
+***
+
+### context\_value\_1?
+
+> `optional` **context\_value\_1?**: `number`
+
+***
+
+### meta?
+
+> `optional` **meta?**: [`ActivityLogMeta`](ActivityLogMeta.md)
+
+***
+
+### source\_entity\_name?
+
+> `optional` **source\_entity\_name?**: `string`
+
+***
+
+### source\_entity\_id?
+
+> `optional` **source\_entity\_id?**: `number`
+
+***
+
+### source\_reference\_id?
+
+> `optional` **source\_reference\_id?**: `number`
+
+***
+
+### source\_root\_id?
+
+> `optional` **source\_root\_id?**: `number`
+
+***
+
+### is\_wallet\_entry
+
+> **is\_wallet\_entry**: `boolean`

package/docs/capabilities/getActivityLogV2.md

@@ -0,0 +1,62 @@
+# getActivityLogV2 — API (TActivityLogEntry)
+
+> Returns the full activity log (v2) — wallet changes **and** non-wallet activities (missions, badges, levels, tournaments, avatars, …).
+> Import: `import { TActivityLogEntry } from '@smartico/public-api'`
+> Search terms: getActivityLogV2, user, TActivityLogEntry, UserBalanceType, PointChangeSourceType, ActivityLogActivities, ActivityLogMeta
+
+## Signature
+```ts
+_smartico.api.getActivityLogV2({
+		startTimeSeconds,
+		endTimeSeconds,
+		from,
+		to,
+		types,
+	}: {
+		startTimeSeconds: number;
+		endTimeSeconds: number;
+		from: number;
+		to: number;
+		types?: number[];
+	}): Promise<TActivityLogEntry[]>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<TActivityLogEntry[]>`
+Array of `TActivityLogEntry`. Each item:
+- `create_date` (number)
+- `user_ext_id` (string)
+- `crm_brand_id` (number)
+- `type` (UserBalanceType)
+- `amount` (number)
+- `balance` (number)
+- `total_ever` (number)
+- `source_type_id` (PointChangeSourceType)
+- `activity_type_id` (ActivityLogActivities)
+- `context_value_1` (number)
+- `meta` (ActivityLogMeta)
+  - `name` (string)
+  - `image_url` (string)
+  - `position` (number)
+  - `user_points_balance_before` (number)
+  - `points_requested` (number)
+  - `user_points_ever` (number)
+- `source_entity_name` (string)
+- `source_entity_id` (number)
+- `source_reference_id` (number)
+- `source_root_id` (number)
+- `is_wallet_entry` (boolean)
+
+## Behavioral contract
+See the [UI guide](../ui/user/UIGuide_getActivityLogV2.md) if present.
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `getActivityLog`
+- `TActivityLog`
+- `ActivityLogActivities`
+- `TActivityLogEntry`

package/docs/capabilities/getJackpotWinners.md

@@ -55,7 +55,9 @@ in the jackpot's NATIVE currency, NOT the user's wallet currency. If a
 user-currency display is needed, the consumer must convert client-side.
 
 **Refresh**
-- The SDK caches per `jp_template_id` for 30 seconds.
+- The SDK caches each page separately (per `jp_template_id` +
+ `limit` + `offset`) for 30 seconds, so paging back and forth is
+ served from cache and each page keeps its own fresh copy.
 - Caches clear on jackpot-win push events and on opt-in / opt-out.
 
 **Error handling**

package/docs/capabilities/miniGameWinAcknowledgeRequest.md

@@ -11,7 +11,7 @@ _smartico.api.miniGameWinAcknowledgeRequest(request_id: string, { lose }: { lose
 
 ## Parameters
 - `request_id` — Correlation id of the spin to finalise: the `request_id` from a `playMiniGame` result (played with `acknowledge: false`), or the `client_request_id` of a `getMiniGamesHistory` row.
-- `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.
+- `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.
 
 ## Returns
 _No return value._

package/docs/native/PROTOCOL.md

@@ -25,6 +25,7 @@ This document describes the low-level protocol for communicating with Smartico b
 - [SAW_SHOW_SPIN_PUSH](#saw_show_spin_push)
 - [JP_WIN_PUSH](#jp_win_push)
 - [SAW_PRIZE_DROP_WIN_PUSH](#saw_prize_drop_win_push)
+- [FORM_SHOW_PUSH](#form_show_push)
 - [CLIENT_EXECUTE_DEEPLINK_EVENT](#client_execute_deeplink_event)
 - [CLIENT_EXECUTE_JS_EVENT](#client_execute_js_event)
 
@@ -409,6 +410,7 @@ Unlike request/response methods, server initiated messages can arrive at any tim
 | `707` | SAW_SHOW_SPIN_PUSH | Trigger to show mini-game |
 | `808` | JP_WIN_PUSH | Jackpot win notification |
 | `708` | SAW_PRIZE_DROP_WIN_PUSH | Prize drop win notification |
+| `1050` | FORM_SHOW_PUSH | Trigger to show a data-collection form |
 | `105` | CLIENT_EXECUTE_DEEPLINK_EVENT | Execute deep link on client |
 | `107` | CLIENT_EXECUTE_JS_EVENT | Execute JavaScript on client |
 
@@ -626,6 +628,36 @@ Sent when a prize drop is won by the user.
 
 ---
 
+## FORM_SHOW_PUSH
+
+Sent as a trigger to display a data-collection form to the user, fired by a campaign's "Show Form" activity. Fire-and-forget — there is no response ClassId; the client reports the funnel back through the regular EVENT channel (`form_viewed` / `form_submitted`).
+
+**ClassId:** `1050`
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cid` | `number` | Message type identifier |
+| `form_id` | `number` | ID of the form to display |
+| `engagement_uid` | `string` | Engagement instance uid — pass it back on the form content request and submit so the server ties the display to the campaign engagement |
+| `uuid` | `string` | Message correlation id (not the engagement uid) |
+
+**Example:**
+
+```json
+{
+  "cid": 1050,
+  "form_id": 11,
+  "engagement_uid": "1322b558-9bd8-4514-9adb-e6c9f8210c1f",
+  "uuid": "c6ed2c18-0e76-4863-a090-c17ac5959785"
+}
+```
+
+**Recommended action:** Fetch and render the form for `form_id`, forwarding `engagement_uid` on the content fetch and on submit.
+
+---
+
 ## CLIENT_EXECUTE_DEEPLINK_EVENT
 
 Server-initiated event to execute a deep link on the client.
@@ -2956,7 +2988,7 @@ Register a push notifications token for the current user. Required for receiving
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `token` | `string` | Push notification token (FCM token for Android, APNs token for iOS). Set to `null` to unregister. |
+| `token` | `string` | Push notification token (FCM token for Android, APNs token for iOS). |
 | `platform` | `number` | Platform: `6`=NATIVE_IOS, `7`=NATIVE_ANDROID |
 | `pushNotificationUserStatus` | `number` | Status: `0`=ALLOWED, `1`=ASK, `2`=BLOCKED, `3`=SUSPENDED |
 | `app_package_id` | `string` | Application package ID (e.g. "com.example.app") |

package/package.json

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

package/src/ActivityLog/ActivityLogActivities.ts

@@ -1,5 +1,3 @@
-import { UserBalanceType } from './UserBalanceType';
-
 /** Activity-log entry type as returned on the v2 wire (`type_id`). */
 export enum ActivityLogActivities {
 	Gems = 1,
@@ -21,46 +19,5 @@ export enum ActivityLogActivities {
 	Leaderboard = 17,
 	Tournament = 18,
 	ClanTournament = 19,
+	Clan = 20,
 }
-
-export enum WalletChangeType {
-	Add = 1,
-	Deduct = 2,
-	Set = 3,
-}
-
-export enum LevelChangeType {
-	Increase = 1,
-	Decrease = 2,
-}
-
-/** Wire ctx_1 for Mission / Badge / Task — see SMR-44986. */
-export enum AchievementChangeType {
-	Complete = 1,
-	Unlock = 2,
-}
-
-/** Wire ctx_1 for Jackpot rows — SMR-44986. */
-export enum JackpotContextValue {
-	Registration = 1,
-	Win = 3,
-}
-
-const WALLET_TYPE_IDS = new Set<number>([
-	ActivityLogActivities.Gems,
-	ActivityLogActivities.Diamonds,
-	ActivityLogActivities.Points,
-]);
-
-export const isWalletActivityTypeId = (typeId: number): boolean => WALLET_TYPE_IDS.has(typeId);
-
-export const activityTypeIdToBalanceType = (typeId: ActivityLogActivities): UserBalanceType => {
-	switch (typeId) {
-		case ActivityLogActivities.Gems:
-			return UserBalanceType.Gems;
-		case ActivityLogActivities.Diamonds:
-			return UserBalanceType.Diamonds;
-		default:
-			return UserBalanceType.Points;
-	}
-};