@smartico/public-api 0.0.385 → 0.0.387

package/src/WSAPI/WSAPIMissions.ts

@@ -198,8 +198,14 @@ export class WSAPIMissions extends WSAPIGeneral {
 	 * **Idempotency / Side effects**: fetch-only; safe to call repeatedly.
 	 * The cache layer deduplicates concurrent calls within the TTL window.
 	 *
+	 * **Visitor mode**: not supported. Badges are an authenticated-only
+	 * feature; calling this on the visitor-mode handle (`_smartico.vapi`)
+	 * throws synchronously rather than silently returning an empty list.
+	 *
 	 * **UI guidance**: see [UI Guide — `getBadges`](../../docs/ui/missions/UIGuide_getBadges.md).
 	 *
+	 * @throws `Error("getBadges is not available in visitor mode")` when
+	 *         called from a visitor-mode session.
 	 * @returns Promise resolving to `TMissionOrBadge[]`. Every item has
 	 *          `type === 'badge'`. Cached for 30 s under the `Badges` key.
 	 *
@@ -241,6 +247,12 @@ export class WSAPIMissions extends WSAPIGeneral {
 	 * ```
 	 */
 	public async getBadges(): Promise<TMissionOrBadge[]> {
+		// Badges are an authenticated-only feature. The visitor-mode WSAPI
+		// instance (`_smartico.vapi`) is constructed without a tracker, so the
+		// server would silently return nothing; throw a clear error instead.
+		if (!this.api.tracker) {
+			throw new Error('getBadges is not available in visitor mode');
+		}
 		return OCache.use(onUpdateContextKey.Badges, ECacheContext.WSAPI, () => this.api.badgetsGetItemsT(this.userExtId), CACHE_DATA_SEC);
 	}
 

package/src/WSAPI/WSAPITypes.ts

@@ -953,6 +953,10 @@ export interface TMissionOrBadgeTask {
 	progress: number;
 	/** Reward for completing the task in points */
 	points_reward: number;
+	/** Reward for completing the task in gems */
+	gems_reward?: number;
+	/** Reward for completing the task in diamonds */
+	diamonds_reward?: number;
 	/** This is the total number of times the user needs to execute to complete task. e.g. he needs to bet 100 times. Here will be 100 */
 	execution_count_expected?: number;
 	/** This is the number of times the user has executed 'activity' of the task. e.g. he bet 5 times out of 100. Here will be 5 */
@@ -1780,9 +1784,9 @@ export interface TAvatarPrompt {
 	name: string;
 	/** Absolute CDN URL of the prompt's preview icon. */
 	icon_url: string;
-	/** Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diamonds. */
+	/** Currency used to pay for the customization. `0` = points, `1` = gems, `2` = diamonds, `3` = free. A `cost_value` of `0` is also free. */
 	cost_currency_type_id: number;
-	/** Cost amount in the currency named by `cost_currency_type_id`. */
+	/** Cost amount in the currency named by `cost_currency_type_id`. `0` = free. */
 	cost_value: number;
 }
 

package/src/WSAPI/WSAPIUser.ts

@@ -371,12 +371,25 @@ export class WSAPIUser extends WSAPIBase {
 	 * `ach_points_ever` and {@link getLevels} would also work, but
 	 * `progress` saves the math.
 	 *
-	 * **Cache TTL**: the SDK caches the response for 30 seconds. There is
-	 * no push event that refreshes this cache; a server-side level change
-	 * (visible immediately on {@link getUserProfile}'s `ach_level_current_id`
-	 * via the user-properties update channel) becomes visible on this
-	 * method only after the cache TTL expires, or after
-	 * `_smartico.api.clearCaches()` is called.
+	 * **Cache TTL & freshness**
+	 * The response is cached for 30 seconds, but the SDK automatically
+	 * drops that cache whenever a user-properties update arrives — the
+	 * same live channel that backs {@link getUserProfile}. The practical
+	 * effect depends on the label's leveling logic:
+	 * - **Points-based or operator-manual leveling**: a points or level
+	 *   change flows through the user-properties channel, so the cache is
+	 *   busted at that moment and the next `getCurrentLevel()` call
+	 *   returns up-to-date data without waiting out the TTL.
+	 * - **Counter-based leveling** (level driven by sliding-window
+	 *   counters such as deposit or wagering totals over a recent window —
+	 *   see {@link getUserLevelExtraCounters}): ordinary progress changes
+	 *   are recomputed by a periodic server job and do NOT emit a
+	 *   user-properties update, so they become visible on this method only
+	 *   after the 30 s TTL expires (or after `_smartico.api.clearCaches()`).
+	 *
+	 * Avoid calling `clearCaches()` on the points/manual path — it's
+	 * unnecessary there (the cache is already refreshed on the property
+	 * update) and forces a slower extra round-trip.
 	 *
 	 * **Leveling logic**
 	 * The semantics of how a user advances depends on the label's
@@ -404,10 +417,10 @@ export class WSAPIUser extends WSAPIBase {
 	 * console.log('[smartico] render level badge — name:', level.name,
 	 *   'progress:', Math.round(level.progress), '%');
 	 *
-	 * // Detect level-up via getUserProfile's push channel.
+	 * // Detect level-up via getUserProfile's push channel. No clearCaches()
+	 * // needed — the SDK already drops the level cache on this update.
 	 * window._smartico.on('props_change', async (changed) => {
 	 *   if ('ach_level_current_id' in changed) {
-	 *     await window._smartico.api.clearCaches();   // bust the 30 s cache
 	 *     const fresh = await window._smartico.api.getCurrentLevel();
 	 *     console.log('[smartico] user levelled up — animate badge to new level:', fresh.name);
 	 *   }
@@ -443,14 +456,12 @@ export class WSAPIUser extends WSAPIBase {
 	 * `levelsCounter2Name`.
 	 *
 	 * **Refresh cadence**
-	 * Sliding-window counters are recomputed by a server-side job that
-	 * runs roughly every 60 seconds against the operator's BigQuery
-	 * dataset; level transitions driven by counter changes have a
-	 * latency of up to several minutes after the underlying activity
-	 * (e.g. a deposit). The SDK caches the response for 30 seconds; no
-	 * push event refreshes this cache. After a level change visible on
-	 * {@link getUserProfile}'s `ach_level_current_id`, call
-	 * `_smartico.api.clearCaches()` to force a fresh fetch.
+	 * Sliding-window counters are recomputed by a periodic server-side
+	 * job. Its rebuild cadence is operator-configured per brand —
+	 * commonly daily, though it can be set more frequent — so level
+	 * transitions driven by counter changes surface with a latency tied
+	 * to that rebuild schedule after the underlying activity (e.g. a
+	 * deposit), not in real time.
 	 *
 	 * **Idempotency**: safe. Read-only. Repeated calls within the cache
 	 * window return a deep-cloned cached value without a network

package/tsconfig.json

@@ -90,7 +90,9 @@
 			"src/Tournaments/GetClanTournamentPlayersResponse.ts",
 			"src/Avatars/AvatarDefinition.ts",
 			"src/Avatars/AvatarCustomized.ts",
-			"src/Avatars/AvatarPrompt.ts"
+			"src/Avatars/AvatarPrompt.ts",
+			"src/Avatars/AvatarCustomizeResponse.ts",
+			"src/Avatars/AvatarCustomizeErrorCode.ts"
 		],
 		"out": "docs/api",
 		"projectDocuments": ["docs/SmarticoObject.md", "docs/Callbacks.md", "docs/Transforms.md"],