@smartico/public-api 0.0.420 → 0.0.422

package/src/ActivityLog/ActivityLogEntry.ts

@@ -1,27 +1,39 @@
+import { ActivityLogActivities } from './ActivityLogActivities';
+import { ActivityLogMeta } from './ActivityLogMeta';
 import { PointChangeSourceType } from './PointChangeSourceType';
-import { UserBalanceType } from './UserBalanceType';
-	
-export interface PointsLog {
-	/** Epoch timestamp in SECONDS (not ms — unlike most SDK timestamps). */
-	create_date: number;
-	user_ext_id: string;
-	crm_brand_id: number;
-	points_collected: number;
-	user_points_ever: number;
-	user_points_balance: number;
-	source_type_id: PointChangeSourceType;
-}
 
-export interface GemsDiamondsLog {
-	/** Epoch timestamp in SECONDS (not ms — unlike most SDK timestamps). */
-	create_date: number;
+/**
+ * One raw activity-log row as it arrives on the wire.
+ *
+ * JS consumers receive the friendlier {@link TActivityLog} instead — this is the
+ * pre-transform shape, documented for native clients that read the protocol directly.
+ */
+export interface ActivityLogEntry {
+	/** Creation time; `seconds` is the epoch value in SECONDS (not ms). */
+	create_date: { seconds: number; nanos?: number };
 	user_ext_id: string;
-	crm_brand_id: number;
-	type: UserBalanceType;
+	/** Sent as a string on the wire. */
+	crm_brand_id: string;
+	/** Kind of activity this row records. */
+	type: ActivityLogActivities;
+	/** Sub-action within `type` (e.g. unlock vs complete, add vs deduct). */
+	ctx_1: number;
+	/** Extra display payload for the row; contents vary by `type`. */
+	ctx_meta?: ActivityLogMeta;
+	/** What triggered the change. */
+	source_type_id: PointChangeSourceType;
+	/** More specific id within the source (e.g. level id, draw id, win id). */
+	source_ref_id: number;
+	/** Root / parent entity id when the source is nested. */
+	source_root_id: number;
+	/** Delta applied by this row, in the balance named by `type`. */
 	amount: number;
+	/** Balance after this row, in the balance named by `type`. */
 	balance: number;
-	source_type_id: PointChangeSourceType;
+	/** Points balance after this row; points rows only. */
+	user_points_balance?: number;
+	/** Total points ever collected after this row; points rows only. */
+	user_points_ever?: number;
+	/** Placeholder on points rows (`-1`) — read `amount` for the real delta. */
+	points_collected?: number;
 }
-
-export type ActivityLogEntry = PointsLog | GemsDiamondsLog;
-

package/src/ActivityLog/ActivityLogMeta.ts

@@ -1,8 +1,39 @@
+/**
+ * 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.
+ */
 export interface ActivityLogMeta {
+	/** Display name of the source entity (mission, tournament, raffle, …). */
 	name?: string;
 	image_url?: string;
 	position?: number;
+	/** Points balance before this row; points rows. */
 	user_points_balance_before?: number;
+	/** Points the awarding rule asked for; points rows. */
 	points_requested?: number;
+	/** Total points ever collected after this row; points rows. */
 	user_points_ever?: number;
+	/** Gems / diamonds the awarding rule asked for; gems / diamonds rows. */
+	amount_requested?: number;
+	/** Gems / diamonds balance before this row. */
+	balance_before?: number;
+	/** Whether this row counts toward level progress. */
+	affects_level?: boolean;
+	/** Whether this row counts toward leaderboards. */
+	affects_leaderboard?: boolean;
+	/** Whether this row moved the spendable balance. */
+	affects_current_balance?: boolean;
+	/** Set on the row that seeds a brand-new user's wallet. */
+	user_initialization?: boolean;
+	/** Set on mission rows for repeatable missions. */
+	is_recurring?: boolean;
+	/** Level moved from; level-change rows. */
+	from_level_id?: number;
+	/** Level moved to; level-change rows. */
+	to_level_id?: number;
+	/** Public meta of the level moved from; level-change rows. */
+	from_level_public_meta?: any;
+	/** Public meta of the level moved to; level-change rows. */
+	to_level_public_meta?: any;
 }

package/src/ActivityLog/GetActivityLogRequest.ts

@@ -6,6 +6,8 @@ export interface GetActivityLogRequest extends ProtocolMessage {
 	endTimeSeconds: number;
 	limit: number;
 	offset: number;
+	/** Optional filter — {@link ActivityLogActivities} values to include. */
 	types?: number[];
+	/** Optional filter — {@link PointChangeSourceType} values to include. */
 	src_types?: number[];
 }

package/src/ActivityLog/GetActivityLogResponse.ts

@@ -1,7 +1,7 @@
 import { ProtocolResponse } from '../Base/ProtocolResponse';
 import { ActivityLogEntry } from './ActivityLogEntry';
 import { ActivityLogActivities } from './ActivityLogActivities';
-import { TActivityLog, TActivityLogEntry } from '../WSAPI/WSAPITypes';
+import { TActivityLog } from '../WSAPI/WSAPITypes';
 import { UserBalanceType } from './UserBalanceType';
 
 export interface GetActivityLogResponse extends ProtocolResponse {
@@ -13,64 +13,38 @@ export const ActivityLogTransform = (items: ActivityLogEntry[]): TActivityLog[]
 		return [];
 	}
 
-	return items.map((item: any): TActivityLog => {
-		const itemTransformed: Partial<TActivityLog> = {
-			create_date: item.create_date?.seconds ?? item.create_date,
-			user_ext_id: item.user_ext_id,
-			crm_brand_id: item.crm_brand_id,
-			source_type_id: item.source_type_id,
-		};
-
-		item.type = item.type ?? UserBalanceType.Points;
-
-		if (item.type === UserBalanceType.Diamonds || item.type === UserBalanceType.Gems) {
-			itemTransformed.type = item.type;
-			itemTransformed.amount = item.amount;
-			itemTransformed.balance = item.balance;
-		}
-
-		if (item.type === UserBalanceType.Points) {
-			itemTransformed.type = UserBalanceType.Points;
-			itemTransformed.amount = item.points_collected;
-			itemTransformed.balance = item.user_points_balance;
-			itemTransformed.total_ever = item.user_points_ever;
-		}
-
-		return itemTransformed as TActivityLog;
-	});
-};
-
-export const ActivityLogV2Transform = (items: any[]): TActivityLogEntry[] => {
-	if (!items) {
-		return [];
-	}
-
-	return items.map((r) => {
-		const isGems = r.type_id === ActivityLogActivities.Gems || r.type === UserBalanceType.Gems;
-		const isDiamonds = r.type_id === ActivityLogActivities.Diamonds || r.type === UserBalanceType.Diamonds;
+	return items.map((r: any): TActivityLog => {
+		// The wire sends the activity kind as `type` (an ActivityLogActivities value).
+		// `type_id` is accepted as an alias so an older/newer server spelling still maps.
+		const activityTypeId: ActivityLogActivities = r.type_id ?? r.type;
+		const isGems = activityTypeId === ActivityLogActivities.Gems;
+		const isDiamonds = activityTypeId === ActivityLogActivities.Diamonds;
+		const meta = r.ctx_meta ?? r.context_value_meta;
 
-		const x: TActivityLogEntry = {
+		return {
 			create_date: r.create_date?.seconds ?? r.create_date,
 			user_ext_id: r.user_ext_id,
-			crm_brand_id: r.crm_brand_id,
+			// Sent as a string on the wire.
+			crm_brand_id: Number(r.crm_brand_id),
 			type: isGems ? UserBalanceType.Gems : isDiamonds ? UserBalanceType.Diamonds : UserBalanceType.Points,
-			amount: r.points_collected ?? r.amount,
+			// `amount` carries the real delta; `points_collected` is a `-1` placeholder on points rows.
+			amount: r.amount ?? r.points_collected,
 			balance: r.user_points_balance ?? r.balance,
 			total_ever: r.user_points_ever,
 			source_type_id: r.source_type_id,
-			activity_type_id: r.type_id,
-			context_value_1: r.context_value_1,
-			meta: r.context_value_meta,
-			source_entity_name: r.source_entity_name,
+			activity_type_id: activityTypeId,
+			context_value_1: r.ctx_1 ?? r.context_value_1,
+			meta,
+			// Entity name travels inside the context meta, not as a top-level field.
+			source_entity_name: r.source_entity_name ?? meta?.name,
 			source_entity_id: r.source_entity_id,
-			source_reference_id: r.source_reference_id,
+			source_reference_id: r.source_ref_id ?? r.source_reference_id,
 			source_root_id: r.source_root_id,
 			is_wallet_entry:
-				r.type_id == null
-				|| r.type_id === ActivityLogActivities.Gems
-				|| r.type_id === ActivityLogActivities.Diamonds
-				|| r.type_id === ActivityLogActivities.Points,
+				activityTypeId == null
+				|| activityTypeId === ActivityLogActivities.Gems
+				|| activityTypeId === ActivityLogActivities.Diamonds
+				|| activityTypeId === ActivityLogActivities.Points,
 		};
-		return x;
 	});
 };

package/src/Jackpots/JackPotWinPushWinner.ts

@@ -0,0 +1,35 @@
+/**
+ * One winner entry inside a {@link JackpotWinPush}.
+ *
+ * Distinct from {@link JackPotWinner}, which is the winner shape returned by the
+ * `getJackpotWinners()` history — the live win push carries bet / trigger context
+ * and no avatar.
+ */
+interface JackPotWinPushWinner {
+	/** Smartico user ID of the winner */
+	user_id: number;
+	/** Operator's external user ID of the winner */
+	ext_user_id: string;
+	/** Flag indicating that this copy of the push was delivered to the winner themselves */
+	is_me: boolean;
+	/** Name of the winner, masked for everyone except `is_me` unless masking is disabled by request to Smartico AM team */
+	public_username: string;
+	/** Custom display name; falls back to `public_username` when not set */
+	public_username_custom: string;
+	/** Won amount in the Jackpot currency; real and bonus parts are combined */
+	winning_amount_jp_currency: number;
+	/** Won amount in the user Wallet currency; real and bonus parts are combined */
+	winning_amount_wallet_currency: number;
+	/** Position of the winner. Relevant for jackpots where there could be multiple winners */
+	winning_position: number;
+	/** External game ID of the game whose bet triggered the win; `null` when the triggering bet context is unavailable */
+	winning_game_id: string | null;
+	/** External provider ID of the triggering game's provider; `null` when the triggering bet context is unavailable */
+	winning_provider_id: string | null;
+	/** Placement time of the triggering bet as reported by the operator (epoch milliseconds) — not the time Smartico processed it; `null` when unavailable */
+	bet_original_date: number | null;
+	/** Present only on the `is_me` copy; `true` while the win awaits manual approval before payout */
+	pending_approve?: boolean;
+}
+
+export { JackPotWinPushWinner };

package/src/Jackpots/JackPotWinner.ts

@@ -9,8 +9,10 @@ interface JackPotWinner {
 	winning_amount_wallet_currency: number;
 	/** Position of the winner. Relevant for jackpots where there could be multiple winners */
 	winning_position: number;
-	/** Avatar of the winner */
+	/** Avatar image URL of the winner */
 	avatar_id: string;
+	/** Numeric ID of the winner's avatar; `null` when the winner has not picked one */
+	avatar_real_id: number | null;
 }
 
 export { JackPotWinner };

package/src/Jackpots/JackpotContributionRule.ts

@@ -0,0 +1,25 @@
+import { JackpotContributionType } from './JackpotContributionType';
+
+/**
+ * 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.
+ */
+interface JackpotContributionRule {
+	/** Stable ID of the rule within its template */
+	ruleId: number;
+	/** Template this rule belongs to */
+	jpTemplateId: number;
+	/** Whether `contributionValue` is a fixed amount or a percentage; see {@link JackpotContributionType} */
+	type: JackpotContributionType;
+	/** Operator-side game or provider IDs this rule applies to */
+	extEntityIds: string[];
+	/** Contribution to apply for matching bets — fixed amount or percentage depending on `type` */
+	contributionValue: number;
+}
+
+export { JackpotContributionRule };

package/src/Jackpots/JackpotDetails.ts

@@ -1,3 +1,5 @@
+import { AchRelatedGame } from '../Base/AchRelatedGame';
+import { JackpotContributionRule } from './JackpotContributionRule';
 import { JackpotContributionType } from './JackpotContributionType';
 import { JackpotPot } from './JackpotPot';
 import { JackpotPublicMeta } from './JackpotPublicMeta';
@@ -22,10 +24,16 @@ interface JackpotDetails {
 	contribution_type: JackpotContributionType;
 	/** Amount of contribution per qualifying bet — fixed value or percentage depending on `contribution_type`. */
 	contribution_value: number;
+	/** Per-game / per-provider overrides of `contribution_type` + `contribution_value`; see {@link JackpotContributionRule}. Empty when the template contributes at a flat rate. */
+	contribution_rules: JackpotContributionRule[];
+	/** Reserved — the server currently always sends an empty array. Use `getJackpotEligibleGames()` for the eligible-games list. */
+	related_games: AchRelatedGame[];
 	/** Live pot snapshot (amount, temperature, last explosion timestamp). */
 	pot: JackpotPot;
 	/** `true` when the current user is currently opted in. */
 	is_opted_in: boolean;
+	/** `true` when eligible users are opted in automatically, so no opt-in CTA is needed; `false` means `jackpotOptIn()` must be called explicitly. */
+	is_auto_opt_in: boolean;
 	/** `true` when every game in the operator catalog contributes; if `true`, skip `getJackpotEligibleGames`. */
 	ach_related_game_allow_all: boolean;
 	/** Number of users currently opted in; always `1` for `JackpotType.Personal`. */

package/src/Jackpots/JackpotPot.ts

@@ -22,8 +22,10 @@ interface JackpotPot {
 	current_pot_amount: number;
 	/** Current pot amount converted to the user's wallet currency (`user_currency`). */
 	current_pot_amount_user_currency: number;
-	/** Unix ms timestamp of when this pot last exploded; `0` if it has never exploded. */
-	explode_date_ts: number;
+	/** Unix ms timestamp of when this pot last exploded; `null` while the pot is still running. */
+	explode_date_ts: number | null;
+	/** Owning user for `JackpotType.Personal` pots; `null` for shared `MultiUser` pots. */
+	user_id: number | null;
 	/** Heat band of the pot relative to its explosion range; see {@link JackPotTemparature}. */
 	current_pot_temperature: JackPotTemparature;
 }

package/src/Jackpots/JackpotPublicMeta.ts

@@ -14,12 +14,16 @@ interface JackpotPublicMeta {
 	placeholder1: string;
 	/** custom value of placeholder2 defined by operator and can be used in the HTML templates */
 	placeholder2: string;
+	/** operator-defined display order, ascending; sent as a string */
+	priority: string;
 	/**
-	 * Custom data as string or JSON string that can be used in API to build custom UI
+	 * Custom data that can be used in API to build custom UI.
+	 * `jackpotGet()` returns this already parsed — an object when the operator stored JSON,
+	 * otherwise the raw string. Elsewhere (e.g. the jackpot-win push) it arrives unparsed.
 	 * You can request from Smartico to define fields for your specific case that will be managed from Smartico BackOffice
 	 * Read more here - <https://help.smartico.ai/welcome/products/tools-and-guides/custom-fields-attributes>
 	*/
-	custom_data: string;
+	custom_data: any;
 }
 
 export { JackpotPublicMeta };

package/src/Jackpots/JackpotWinPush.ts

@@ -1,8 +1,20 @@
 import { ProtocolMessage } from '../Base/ProtocolMessage';
-import { JackPotWinner } from './JackPotWinner';
+import { JackPotWinPushWinner } from './JackPotWinPushWinner';
 import { JackpotDetails } from './JackpotDetails';
 
+/**
+ * Live jackpot-win notification. Delivered both to the winner and to other players
+ * taking part in the same jackpot — use `winners[].is_me` to tell the two apart;
+ * the copy sent to other players has its `public_username` masked.
+ *
+ * Surfaced to consumers through the `jackpot_win` callback
+ * (`_smartico.on('jackpot_win', …)`).
+ *
+ * The explosion time is `jackpot.pot.explode_date_ts` (epoch milliseconds).
+ */
 export interface JackpotWinPush extends ProtocolMessage {
+	/** The jackpot that exploded, including its live `pot` snapshot */
 	jackpot: JackpotDetails;
-	winners: JackPotWinner[];
+	/** Winner entries; currently always a single entry */
+	winners: JackPotWinPushWinner[];
 }

package/src/Jackpots/index.ts

@@ -3,6 +3,8 @@ export * from './GetJackpotsPotsResponse';
 export * from './GetJackpotsRequest';
 export * from './GetJackpotsResponse';
 export * from './JackPotWinner';
+export * from './JackPotWinPushWinner';
+export * from './JackpotContributionRule';
 export * from './JackpotContributionType';
 export * from './JackpotDetails';
 export * from './JackpotPot';

package/src/MiniGames/SAWGetTemplatesResponse.ts

@@ -47,6 +47,7 @@ export const SAWTemplatesTransform = (items: SAWTemplate[]): TMiniGameTemplate[]
 			earliest_expiration_dt: r.earliest_expiration_dt,
 			latest_expiration_dt: r.latest_expiration_dt,
 			steps_to_finish_game: r.saw_template_ui_definition.steps_to_finish_game,
+			min_steps_to_finish_game: r.saw_template_ui_definition.min_steps_to_finish_game,
 			custom_section_id: r.saw_template_ui_definition.custom_section_id,
 			saw_template_ui_definition: r.saw_template_ui_definition,
 			...(r.saw_game_type_id === SAWGameType.LootboxCalendarDays || r.saw_game_type_id === SAWGameType.LootboxWeekdays

package/src/SmarticoAPI.ts

@@ -102,7 +102,6 @@ import {
 	TRaffle,
 	TLevelCurrent,
 	TActivityLog,
-	TActivityLogEntry,
 	TRaffleDraw,
 	TAvatarDefinition,
 	TAvatarCustomized,
@@ -137,7 +136,7 @@ import { GetRelatedAchTourRequest } from './Missions/GetRelatedAchTourRequest';
 import { GetRelatedAchTourResponse } from './Missions/GetRelatedAchTourResponse';
 import { GetRafflesResponse, raffleTransform } from './Raffle/GetRafflesResponse';
 import { GetRafflesRequest } from './Raffle/GetRafflesRequest';
-import { GetActivityLogRequest, GetActivityLogResponse, ActivityLogTransform, ActivityLogV2Transform } from './ActivityLog';
+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, GetRaffleWonPrizesRequest, GetRaffleWonPrizesResponse } from './Raffle';
@@ -1783,31 +1782,6 @@ class SmarticoAPI {
 		return await this.send<GetActivityLogResponse>(message, ClassId.GET_POINT_HISTORY_RESPONSE);
 	}
 
-	public async getActivityLogV2(
-		user_ext_id: string,
-		startTimeSeconds: number,
-		endTimeSeconds: number,
-		limit: number,
-		offset: number,
-		types?: number[],
-		src_types?: number[],
-	): Promise<GetActivityLogResponse> {
-		const message = this.buildMessage<GetActivityLogRequest, GetActivityLogResponse>(
-			user_ext_id,
-			ClassId.GET_POINT_HISTORY_REQUEST,
-			{
-				startTimeSeconds: Math.floor(startTimeSeconds),
-				endTimeSeconds: Math.floor(endTimeSeconds),
-				limit,
-				offset,
-				...(types ? { types } : {}),
-				...(src_types ? { src_types } : {}),
-			},
-		);
-
-		return await this.send<GetActivityLogResponse>(message, ClassId.GET_POINT_HISTORY_RESPONSE);
-	}
-
 	public async getActivityLogT(
 		user_ext_id: string,
 		startTimeSeconds: number,
@@ -1824,23 +1798,6 @@ class SmarticoAPI {
 			(await this.getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset, types, src_types)).logHistory,
 		);
 	}
-
-	public async getActivityLogV2T(
-		user_ext_id: string,
-		startTimeSeconds: number,
-		endTimeSeconds: number,
-		from: number = 0,
-		to: number = 50,
-		types?: number[],
-		src_types?: number[],
-	): Promise<TActivityLogEntry[]> {
-		const limit = to - from > 50 ? 50 : to - from;
-		const offset = from;
-
-		return ActivityLogV2Transform(
-			(await this.getActivityLogV2(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset, types, src_types)).logHistory,
-		);
-	}
 }
 
 export { SmarticoAPI, MessageSender };

package/src/WSAPI/WSAPIBase.ts

@@ -40,7 +40,6 @@ export enum onUpdateContextKey {
 	CurrentLevel = 'currentLevel',
 	InboxUnreadCount = 'inboxUnreadCount',
 	ActivityLog = 'activityLog',
-	ActivityLogV2 = 'activityLogV2',
 	AvatarsList = 'avatarsList',
 	AvatarsCustomized = 'avatarsCustomized',
 	AvatarPrompts = 'avatarPrompts',

package/src/WSAPI/WSAPIJackpots.ts

@@ -176,6 +176,8 @@ export class WSAPIJackpots extends WSAPIClans {
 	 * - The jackpot must currently be active and the user must be in its
 	 *   eligibility segment. Ineligible jackpots are filtered out of
 	 *   {@link 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/src/WSAPI/WSAPITypes.ts

@@ -222,6 +222,8 @@ export interface TMiniGameTemplate {
 	activeTillDate?: number;
 	/** Number of steps to complete the game and collect the prize (step games — Voyager / Treasure Hunt) */
 	steps_to_finish_game?: number;
+	/** Minimum number of path steps / collectible prizes a session must include before the game can finish (step games — Voyager / Treasure Hunt). `>= 1` and `<= steps_to_finish_game`; when omitted, no minimum is enforced */
+	min_steps_to_finish_game?: number;
 	/** ID of the operator-defined custom section (widget menu grouping) the mini-game is assigned to */
 	custom_section_id?: number;
 
@@ -1784,8 +1786,12 @@ export interface TransformedRaffleClaimPrizeResponse {
 	errorMessage?: string
 }
 /**
- * TActivityLog describes a unified history log entry for points, gems, or diamonds changes.
- * The structure is the same regardless of balance type, making it easy to iterate and display.
+ * One activity-log row from {@link WSAPIUser.getActivityLog}.
+ *
+ * Always includes the wallet fields (`type` / `amount` / `balance` / …). When the
+ * server returns richer activity rows (missions, badges, levels, …), the optional
+ * fields below are populated — same method, same CID; clients that ignore unknown
+ * fields keep working.
  */
 export interface TActivityLog {
 	/** Date when the change was created (epoch timestamp in seconds) */
@@ -1804,31 +1810,27 @@ export interface TActivityLog {
 	total_ever?: number;
 	/** Source type ID indicating what triggered this change */
 	source_type_id: PointChangeSourceType;
-}
-
-/**
- * Full activity-log row returned by {@link WSAPIUser.getActivityLogV2}.
- * Includes wallet changes and non-wallet activities (missions, badges, levels, …).
- */
-export interface TActivityLogEntry {
-	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 kind — see {@link ActivityLogActivities} (`type` on the wire). */
 	activity_type_id?: ActivityLogActivities;
+	/** Sub-action for `activity_type_id` (e.g. unlock vs complete, add vs deduct, raffle win vs register). */
 	context_value_1?: number;
+	/** Extra display payload for the row (name, image, position, …) — see {@link ActivityLogMeta}. */
 	meta?: ActivityLogMeta;
+	/** Human-readable name of the source entity (mission, tournament, raffle, …). */
 	source_entity_name?: string;
+	/** Primary id of the source entity (mission / badge / tournament / …). */
 	source_entity_id?: number;
+	/** More specific id within the source (e.g. level id, draw id, win id). */
 	source_reference_id?: number;
+	/** Root / parent entity id when the source is nested (e.g. raffle id owning a draw). */
 	source_root_id?: number;
-	is_wallet_entry: boolean;
+	/** True when the row is a points/gems/diamonds wallet change. */
+	is_wallet_entry?: boolean;
 }
 
+/** @deprecated Use {@link TActivityLog} — same shape; kept as an alias for early adopters. */
+export type TActivityLogEntry = TActivityLog;
+
 
 /**
  * Result of `_smartico.api.requestRaffleOptin({raffle_id, draw_id, raffle_run_id})`.

package/src/WSAPI/WSAPIUser.ts

@@ -2,7 +2,6 @@ import { CoreUtils } from '../Core';
 import { ECacheContext, OCache } from '../OCache';
 import {
 	TActivityLog,
-	TActivityLogEntry,
 	TLevel,
 	TLevelCurrent,
 	TSegmentCheckResult,
@@ -514,15 +513,16 @@ export class WSAPIUser extends WSAPIBase {
 	}
 
 	/**
-	 * 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 {@link TActivityLog} — no separate call, same wire CID.
 	 *
-	 * The returned shape is the same regardless of currency type — `type` (see
-	 * {@link UserBalanceType}) distinguishes points / gems / diamonds and
-	 * `source_type_id` (see {@link PointChangeSourceType}) 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.
 	 *
 	 * @remarks
 	 * **Preconditions**
@@ -535,7 +535,7 @@ export class WSAPIUser extends WSAPIBase {
 	 * `from` by 50 between calls. Both `startTimeSeconds` and `endTimeSeconds`
 	 * are epoch seconds bounding the window the server scans.
 	 *
-	 * **Filtering** — optional server-side filters (SMR-52608):
+	 * **Filtering** — optional server-side filters:
 	 * - `types` — {@link ActivityLogActivities} / `type_id` values (e.g. Points=3, Gems=1)
 	 * - `src_types` — {@link PointChangeSourceType} / `source_type_id` values
 	 * Omit both for an unfiltered window.
@@ -662,47 +662,4 @@ export class WSAPIUser extends WSAPIBase {
 			onUpdate(payload);
 		}
 	}
-
-	/**
-	 * Returns the full activity log (v2) — wallet changes **and** non-wallet
-	 * activities (missions, badges, levels, tournaments, avatars, …).
-	 *
-	 * **Backwards compatibility**: existing integrations should keep using
-	 * {@link getActivityLog}, which returns wallet-only {@link TActivityLog}
-	 * rows with the original field contract unchanged.
-	 *
-	 * **Pagination** — same `from` / `to` offset model as {@link getActivityLog}
-	 * (server caps a single response at 50 entries).
-	 *
-	 * **Filtering** — optional server-side filters:
-	 * - `types` — {@link ActivityLogActivities} values (`type_id`)
-	 * - `src_types` — {@link PointChangeSourceType} values (`source_type_id`)
-	 * Omit both for all activity types / sources.
-	 *
-	 * @returns Array of {@link TActivityLogEntry} ordered newest-first.
-	 */
-	public async getActivityLogV2({
-		startTimeSeconds,
-		endTimeSeconds,
-		from,
-		to,
-		types,
-		src_types,
-	}: {
-		startTimeSeconds: number;
-		endTimeSeconds: number;
-		from: number;
-		to: number;
-		types?: number[];
-		src_types?: number[];
-	}): Promise<TActivityLogEntry[]> {
-		const cacheKey = `${onUpdateContextKey.ActivityLogV2}:${startTimeSeconds}:${endTimeSeconds}:${from}:${to}:${types?.join(',') ?? ''}:${src_types?.join(',') ?? ''}`;
-
-		return await OCache.use(
-			cacheKey,
-			ECacheContext.WSAPI,
-			() => this.api.getActivityLogV2T(this.userExtId, startTimeSeconds, endTimeSeconds, from, to, types, src_types),
-			CACHE_DATA_SEC,
-		);
-	}
 }