@smartico/public-api 0.0.400 → 0.0.402

package/docs/api/interfaces/QuizEventMeta.md

@@ -0,0 +1,61 @@
+# Interface: QuizEventMeta
+
+QuizEventMeta describes metadata for a quiz-type event (custom question with answer options)
+
+## Extended by
+
+- [`GamePickEventMeta`](GamePickEventMeta.md)
+
+## Properties
+
+### answers?
+
+> `optional` **answers?**: `object`[]
+
+List of possible answer options for the quiz question
+
+#### value
+
+> **value**: `string`
+
+Answer identifier value sent on submission
+
+#### text
+
+> **text**: `string`
+
+Localized display text of the answer
+
+#### \_translations
+
+> **\_translations**: `object`
+
+Per-language overrides for the answer text
+
+##### Index Signature
+
+\[`key`: `string`\]: `object`
+
+***
+
+### question\_image?
+
+> `optional` **question\_image?**: `string`
+
+URL of an image associated with the question
+
+***
+
+### result?
+
+> `optional` **result?**: [`QuizAnswersValueType`](../enumerations/QuizAnswersValueType.md)
+
+Correct answer value after resolution
+
+***
+
+### custom\_question
+
+> **custom\_question**: `string`
+
+Custom question text displayed to the user

package/docs/api/interfaces/RafflePrizePublicMeta.md

@@ -31,3 +31,12 @@ URL of the image that represents the prize
 > **hide\_chance\_to\_win**: `boolean`
 
 Indicates whether the chance to win should be hidden in the UI.
+
+***
+
+### custom\_data?
+
+> `optional` **custom\_data?**: `string`
+
+Custom data field set in the backoffice prize setup.
+Can be used to build custom UI for gamification.

package/docs/api/interfaces/TAvatarCustomized.md

@@ -22,6 +22,6 @@ Absolute CDN URL of the AI-generated image. Can be passed as `avatar_url` to `se
 
 ### dt\_created
 
-> **dt\_created**: `string`
+> **dt\_created**: `number`
 
-ISO date string of when the variant was generated.
+Unix-ms timestamp of when the variant was generated.

package/docs/api/interfaces/TInboxMessage.md

@@ -20,7 +20,8 @@ and the mark / favorite / delete mutations.
 
 > **sent\_date**: `string`
 
-Date when the message was sent (server timestamp).
+Date-time the message was sent, as a `"dd/MM/yyyy HH:mm:ss"` string
+(server local — NOT ISO-8601, so `new Date(sent_date)` will not parse it).
 
 ***
 

package/docs/api/interfaces/TMiniGamePlayResult.md

@@ -30,3 +30,14 @@ Optional server-side error message. Present only on non-zero
 ID of the won prize. Look up in `template.prizes` to interpret
 (including `prize_type === 'no-prize'` for a configured loss
 slot). Always populated, even when `err_code !== 0`.
+
+***
+
+### request\_id
+
+> **request\_id**: `string`
+
+Correlation id of this spin. Pass it to
+`miniGameWinAcknowledgeRequest` to finalise the win when
+playing with `acknowledge: false` — no need to look it up via
+`getMiniGamesHistory`.

package/docs/api/interfaces/TMissionOrBadge.md

@@ -261,7 +261,9 @@ The date/timestamp indicating when the prize was claimed by the user
 
 > `optional` **complete\_date?**: `string`
 
-Time in hours that took this player to complete mission
+Date-time the mission/badge was completed, as a `"dd/MM/yyyy HH:mm:ss"` string
+(server local — NOT ISO-8601, so `new Date(complete_date)` will not parse it).
+Prefer the epoch-ms `complete_date_ts` for date math.
 
 ***
 

package/docs/api/interfaces/TRafflePrize.md

@@ -34,6 +34,15 @@ URL of the image that represents the prize, 256x256px
 
 ***
 
+### custom\_data?
+
+> `optional` **custom\_data?**: `string`
+
+Custom data field set in the backoffice prize setup.
+Can be used to build custom UI for gamification.
+
+***
+
 ### prizes\_per\_run
 
 > **prizes\_per\_run**: `number`

package/docs/api/variables/AllRoundsGameBoardID.md

@@ -0,0 +1,5 @@
+# Variable: AllRoundsGameBoardID
+
+> `const` **AllRoundsGameBoardID**: `-1` = `-1`
+
+Round ID constant used to request the overall/seasonal leaderboard across all rounds

package/docs/ui/minigames/UIGuide_playMiniGame.md

@@ -86,11 +86,12 @@ For `ExplicitAcknowledge`, gate the acknowledge on the user's Claim
 tap: call `playMiniGame(template_id, { acknowledge: false })` so the
 SDK does NOT auto-finalise, then call
 [`miniGameWinAcknowledgeRequest`](../../api/classes/WSAPIMiniGames.md#minigamewinacknowledgerequest)
-when the user taps Claim. Pass the spin's `client_request_id`, read
-from the matching [`getMiniGamesHistory`](../../api/classes/WSAPIMiniGames.md#getminigameshistory)
-row (it appears with `is_claimed: false`). Note: "explicit claim"
-prizes are NOT covered by the server-side auto-acknowledge fallback,
-so for these you MUST acknowledge or the prize is never credited.
+with the `request_id` from that play result when the user taps Claim.
+(The same id also surfaces as `client_request_id` on a
+[`getMiniGamesHistory`](../../api/classes/WSAPIMiniGames.md#getminigameshistory)
+row if you need to recover it later.) Note: "explicit claim" prizes
+are NOT covered by the server-side auto-acknowledge fallback, so for
+these you MUST acknowledge or the prize is never credited.
 
 Modal contents per prize:
 

package/package.json

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

package/src/ActivityLog/ActivityLogEntry.ts

@@ -2,6 +2,7 @@ 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;
@@ -12,6 +13,7 @@ export interface PointsLog {
 }
 
 export interface GemsDiamondsLog {
+	/** Epoch timestamp in SECONDS (not ms — unlike most SDK timestamps). */
 	create_date: number;
 	user_ext_id: string;
 	crm_brand_id: number;

package/src/Avatars/AvatarCustomized.ts

@@ -3,6 +3,6 @@ export interface AvatarCustomized {
 	avatar_real_id: number;
 	/** CDN URL of the AI-customized avatar image */
 	url: string;
-	/** ISO date string when the customization was created */
-	dt_created: string;
+	/** Unix-ms timestamp when the customization was created. */
+	dt_created: number;
 }

package/src/Core/index.ts

@@ -5,5 +5,6 @@ export * from './GetLabelInfoResponse';
 export * from './GetTranslationsRequest';
 export * from './GetTranslationsResponse';
 export * from './PublicLabelSettings';
+export * from './PublicProperties';
 export * from './ResponseIdentify';
 export * from './TranslationArea';

package/src/GamePick/GamePickTypes.ts

@@ -211,10 +211,10 @@ export interface GamePickEventMeta extends QuizEventMeta {
 export interface GamePickEvent {
 	/** Unique identifier of the event */
 	gp_event_id: number;
-	/** Timestamp (ms) when the event was resolved, null if not yet resolved */
-	event_resolution_date: number;
-	/** Timestamp (ms) of the match/event start time */
-	match_date: number;
+	/** ISO 8601 date-time string when the event was resolved; null until resolved. */
+	event_resolution_date: string;
+	/** ISO 8601 date-time string of the match/event start time. */
+	match_date: string;
 	/** Market type defining the prediction format (e.g. two-team score, quiz question, custom) */
 	market_type_id: SAWGPMarketType;
 	/** Event metadata containing team names, images, sport type, and question details */
@@ -412,8 +412,8 @@ export interface GamePickUserInfo {
 	part_wins_count?: number;
 	/** User's total score */
 	resolution_score?: number;
-	/** Last time the user's balance was synced from the Smartico platform */
-	last_wallet_sync_time?: Date;
+	/** ISO 8601 date-time string of the last time the user's balance was synced from the Smartico platform. */
+	last_wallet_sync_time?: string;
 	/** User's current points balance */
 	ach_points_balance?: number;
 	/** User's current gems balance */
@@ -440,9 +440,9 @@ export interface GamePickGameInfo {
  * GamesApiResponse is the standard response wrapper for all GamePick/Quiz API calls
  */
 export interface GamesApiResponse<T> {
-	/** Error code: 0 on success, non-zero on failure */
+	/** Error code; `0` = success. Per-method code tables live in each `gamePick*` method's TSDoc. */
 	errCode: number;
-	/** Human-readable error message when errCode is non-zero */
+	/** Human-readable error message; populated when `errCode` is non-zero. */
 	errMessage?: string;
 	/** Response payload, present on success */
 	data?: T;
@@ -452,13 +452,13 @@ export interface GamesApiResponse<T> {
  * GamePickRequestParams describes the base parameters required for GamePick API calls
  */
 export interface GamePickRequestParams {
-	/** ID of the MatchX or Quiz game template */
+	/** ID of the MatchX or Quiz game template. The only field the consumer supplies. */
 	saw_template_id: number;
-	/** External user ID */
-	ext_user_id: string;
-	/** Smartico external user ID used for platform API calls */
-	smartico_ext_user_id: string;
-	/** Language code for translations (e.g. 'EN', 'DE') */
+	/** External user ID. Injected by the SDK from the active session; consumers omit it. */
+	ext_user_id?: string;
+	/** Platform external user ID. Injected by the SDK from the active session; consumers omit it. */
+	smartico_ext_user_id?: string;
+	/** Language code for translations (e.g. 'EN', 'DE'). Defaults to the session language. */
 	lang?: string;
 }
 

package/src/Level/Level.ts

@@ -10,5 +10,6 @@ export interface Level {
 	required_level_counter_1: number;
 	required_level_counter_2: number;
 	general_level_progress: number;
+	/** 1-based position of this level within the level ladder. */
 	ordinal_position?: number;
 }

package/src/Missions/UserAchievement.ts

@@ -23,9 +23,9 @@ export interface UserAchievement {
 	start_date_ts?: number;
 	time_limit_ms?: number;
 	progress?: number;
-	complete_date?: string;
+	complete_date?: string; // "dd/MM/yyyy HH:mm:ss" string (not ISO-8601); use complete_date_ts for epoch-ms
 	complete_date_ts?: number;
-	unlock_date?: string;
+	unlock_date?: string; // "dd/MM/yyyy HH:mm:ss" string (not ISO-8601)
 	milliseconds_till_available?: number;
 	completed_tasks?: number;
 	achievementTasks?: UserAchievementTask[];

package/src/SmarticoAPI.ts

@@ -1478,7 +1478,8 @@ class SmarticoAPI {
 			};
 		} else if (params) {
 			const extraQuery = Object.entries(params)
-				.map(([k, v]) => `${k}=${encodeURIComponent(JSON.stringify(v))}`)
+				.filter(([, v]) => v !== null && v !== undefined)
+				.map(([k, v]) => `${k}=${encodeURIComponent(typeof v === 'object' ? JSON.stringify(v) : v)}`)
 				.join('&');
 			url += `&${extraQuery}`;
 		}

package/src/SmarticoGlobal.ts

@@ -0,0 +1,209 @@
+import type { WSAPI } from './WSAPI/WSAPI';
+import type { PublicProperties } from './Core/PublicProperties';
+
+/**
+ * Type-only module. Contains no runtime code — interfaces, type aliases and the
+ * `declare global` augmentation below all compile to **nothing**, so importing
+ * `@smartico/public-api` for these types adds zero bytes to a consumer bundle.
+ *
+ * It exists so that any TypeScript app embedding the Smartico SDK gets the global
+ * `window._smartico` object fully typed *without hand-redeclaring it*. The two
+ * heaviest members — `api` and `vapi` — resolve to the real {@link WSAPI} class
+ * exported by this same package, so they can never drift out of sync with the SDK
+ * the way a hand-copied subset does.
+ *
+ * The `_smartico` object itself is implemented in the tracker bundle
+ * (`window._smartico`) and is loaded on the page by the Smartico embed snippet.
+ * This file only describes its *shape*; it does not provide an implementation.
+ *
+ * @document docs/SmarticoObject.md
+ */
+
+/**
+ * Widget kinds accepted by {@link SmarticoGlobal.showWidget}. Mirrors the widget
+ * set the SDK supports; values are stable string identifiers.
+ */
+export type SmarticoWidgetType =
+	| 'achievements'
+	| 'short_info'
+	| 'tournaments'
+	| 'store'
+	| 'inbox'
+	| 'missions'
+	| 'mini-game'
+	| 'match-x-2'
+	| 'quiz'
+	| 'custom-section'
+	| 'inbox-widget'
+	| 'ui-widget'
+	| 'liquid';
+
+/** Presentation options for {@link SmarticoGlobal.showWidget} / {@link SmarticoGlobal.miniGame}. */
+export interface SmarticoWidgetParams {
+	/** Theme name to render the widget with. */
+	theme?: string;
+	/** `'auto'` to size to content, or an explicit CSS height. */
+	height?: 'auto' | string;
+	/** Render inline instead of as an overlay. */
+	inline?: boolean;
+	/** Zoom factor applied to the widget iframe. */
+	zoom?: number;
+	/** Force the mobile layout regardless of viewport. */
+	force_mobile?: boolean;
+}
+
+/**
+ * Options passed to {@link SmarticoGlobal.init} / {@link SmarticoGlobal.initVisitorMode}.
+ * All fields are optional; only `brand_key` is commonly set.
+ */
+export interface SmarticoInitParams {
+	/** Brand key for multi-brand labels. */
+	brand_key?: string | null;
+	/** Enable verbose SDK logging. */
+	debug?: boolean;
+	/** Initial UI language (e.g. `'EN'`). */
+	lang?: string;
+	/** Override the SDK WebSocket endpoint. */
+	ws_url?: string | null;
+	/** Allow additional forward-compatible init options. */
+	[key: string]: unknown;
+}
+
+/**
+ * The global `_smartico` object exposed by the Smartico embed on `window`.
+ *
+ * `api` and `vapi` are the {@link WSAPI} surface documented across this package's
+ * API reference; every other member is a core SDK control method implemented in
+ * the tracker bundle (see the `_smartico` object reference doc).
+ *
+ * @document docs/SmarticoObject.md
+ */
+export interface SmarticoGlobal {
+	/**
+	 * The authenticated WebSocket API surface (`_smartico.api.*`). Available once
+	 * the SDK has initialized and identified the user — gate calls on
+	 * {@link SmarticoGlobal.checkSuccessfullyIdentify}.
+	 */
+	api: WSAPI;
+
+	/**
+	 * Visitor-mode (unauthenticated) API surface for the given language. Returns a
+	 * {@link WSAPI} scoped to anonymous visitors.
+	 */
+	vapi(language: string): WSAPI;
+
+	/**
+	 * `true` once the SDK is initialized **and** the user has been successfully
+	 * identified. Use as a synchronous gate before calling any `api.*` method.
+	 */
+	checkSuccessfullyIdentify(): boolean;
+
+	/** Initialize the SDK for an identified integration. */
+	init(labelApiKey: string, params?: SmarticoInitParams): void;
+	/** Initialize the SDK in visitor (anonymous) mode. */
+	initVisitorMode(labelApiKey: string, params?: SmarticoInitParams): void;
+	/** Identify the current user against the label. */
+	identify(extUserId: string, hash: string, payload?: Record<string, unknown>): Promise<void>;
+	/** Mark an identified user as online for the given language. */
+	online(extUserId: string, language: string, userHash: string, payload?: Record<string, unknown>): Promise<void>;
+	/** Re-run the login flow for the current session. */
+	login(language?: string, payload?: Record<string, unknown>): void;
+	/** Log the current user out of the SDK session. */
+	logout(payload?: Record<string, unknown>): void;
+	/** Clear SDK state/cookies. */
+	clear(params?: Record<string, unknown>): void;
+	/** Switch the active UI language. */
+	changeLanguage(language: string): void;
+
+	/**
+	 * Subscribe to a lifecycle/engagement callback. Pass `null` as the handler to
+	 * unsubscribe. See the callbacks reference for available keys.
+	 */
+	on(event: string, cb: null | ((...args: any[]) => void), params?: Record<string, unknown>): void;
+	/** Remove a previously registered callback. */
+	off(event: string, cb: null | ((...args: any[]) => void)): void;
+
+	/** Trigger a Smartico deep link. */
+	dp(deepLink: string): void;
+	/** Open a Smartico widget overlay/inline. */
+	showWidget(widgetType: SmarticoWidgetType, params?: SmarticoWidgetParams): void;
+	/** Open a mini-game widget for the given template. */
+	miniGame(sawTemplateId: string, params: SmarticoWidgetParams, pendingMessageId?: string | number): void;
+	/** Render a banner into a host element. */
+	showBanner(params: { dom_id: string; placement_key: string }): void;
+	/** Push data into an already-rendered banner. */
+	sendDataToBanner(params: { placement_key: string; data: Record<string, unknown> }): void;
+	/** Embed the gamification block into a host element. */
+	gamificationBlock(params: { dom_id: string; url: string; fit?: 'content' | 'fill' }): void;
+
+	/** Snapshot of the user's public gamification properties. */
+	getPublicProps(): PublicProperties;
+	/** Add/remove/replace/clear the user's public tags. */
+	updatePublicTags(operation: 'add' | 'remove' | 'replace' | 'clear', tags?: string[]): void;
+	/** Set UTM attribution for the session. */
+	setUTMs(source: string, campaign: string): void;
+	/** Record the last login entry point. */
+	setLoginEntry(entry: string): void;
+	/** Set the user's avatar. */
+	setAvatar(avatarId: string): void;
+	/** Set the user's nickname. */
+	setNickname(nickname: string): void;
+	/** Set the active UI skin. */
+	setSkin(skinName: string): void;
+
+	/** Prompt the browser for web-push permission. */
+	requestPushPermissions(): void;
+	/** Register a native push token (mobile webviews). */
+	registerNativePushToken(token: string, platform?: number, appPackageId?: string): void;
+
+	/** Send a client event. */
+	event(eventType: string, payload?: Record<string, unknown>): void;
+	/** Send a client action. */
+	action(actionValue: unknown, extraPayload?: Record<string, unknown>): void;
+	/** Report a client-side error to the server. */
+	sendServerError(message: string): void;
+	/** Send a client-side debug message to the server. */
+	sendServerDebug(message: string): void;
+
+	/** Temporarily suspend/resume automatic popups. */
+	suspendPopups(flag: boolean): void;
+	/** Temporarily suspend/resume the inbox. */
+	suspendInbox(flag: boolean): void;
+	/** Temporarily suspend/resume mini-games. */
+	suspendMiniGames(flag: boolean): void;
+
+	/** Show a visitor-mode game. */
+	showVisitorGame(params: Record<string, unknown>): void;
+	/** Convert a visitor-mode win into an identified reward. */
+	convertVisitorGame(visitorWinUuid: string): void;
+
+	/** Start landing-page analytics for a template. */
+	startLpAnalytics(params: { lp_template_uuid: string; shadow_root?: ShadowRoot | null }): void;
+	/** Send a landing-page analytics activity. */
+	sendAnalytics(activityId: number, viewTimeSec?: number): void;
+
+	/** `true` on mobile viewports. */
+	isMobile(): boolean;
+	/** Parse the current URL query into a map. */
+	parseUrl(): Record<string, string>;
+	/** Parse the current URL hash into a map. */
+	parseUrlHash(): Record<string, string>;
+}
+
+declare global {
+	interface Window {
+		/**
+		 * Params injected by the Smartico widget runtime (`widget.js`) when a widget
+		 * is embedded via `_smartico.showWidget` / a widget script tag. Keys mirror
+		 * the params passed in the embedding snippet (e.g. `id`).
+		 */
+		__SMARTICO_LP_PARAMS__?: Record<string, string | number>;
+
+		/**
+		 * The global Smartico SDK object, present once the embed snippet has loaded.
+		 * Optional because it is `undefined` until the script initializes — guard
+		 * access (`window._smartico?.…`) or gate on `checkSuccessfullyIdentify()`.
+		 */
+		_smartico?: SmarticoGlobal;
+	}
+}

package/src/Store/StoreItem.ts

@@ -37,7 +37,7 @@ export const StoreItemTransform = (items: StoreItem[]): TStoreItem[] => {
 				id: r.id,
 				name: r.itemPublicMeta.name,
 				purchase_type: mapPurchaseType(r.itemPublicMeta.purchase_type),
-				price: r.itemPublicMeta.price as any as number, // AA: strange why it's string
+				price: Number(r.itemPublicMeta.price), // wire delivers price as a string; coerce to the number the type promises
 				image: r.itemPublicMeta.image_url,
 				description: r.itemPublicMeta.description,
 				ribbon: r.itemPublicMeta.label_tag === 'custom' ? r.itemPublicMeta.custom_label_tag : r.itemPublicMeta.label_tag,

package/src/WSAPI/WSAPIAvatars.ts

@@ -142,7 +142,7 @@ export class WSAPIAvatars extends WSAPIMiniGames {
 	 *
 	 * // Newest-first within each base.
 	 * for (const list of byBase.values()) {
-	 *     list.sort((a, b) => b.dt_created.localeCompare(a.dt_created));
+	 *     list.sort((a, b) => b.dt_created - a.dt_created);
 	 * }
 	 *
 	 * console.log('[smartico] AI variants by base avatar — render as a carousel under each base');

package/src/WSAPI/WSAPIGamePick.ts

@@ -307,9 +307,9 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 * **Side effects**
 	 * - First successful submit deducts the buy-in (Points / Gems / Diamonds /
 	 *   one Spin) per `saw_buyin_type_id`.
-	 * - Reports a `minigame_matchx_prediction` event to the operator's event log.
-	 * - Updates the round's participant counter (`users_cnt`) and per-event
-	 *   counters (`num_users`).
+	 * - Records the user's participation against the round and its events
+	 *   server-side and reports a prediction event to the operator's activity
+	 *   stream.
 	 * - Score is awarded after the operator resolves the round
 	 *   ({@link GPRoundStatus} = `RoundResolved`).
 	 *
@@ -408,9 +408,9 @@ export class WSAPIGamePick extends WSAPIAvatars {
 	 * **Idempotency**: identical to {@link gamePickSubmitSelection} — re-submit
 	 * returns `errCode: 3` and never double-charges the buy-in.
 	 *
-	 * **Side effects**: identical to {@link gamePickSubmitSelection}, with the
-	 * reported event being `minigame_quiz_prediction` instead of
-	 * `minigame_matchx_prediction`.
+	 * **Side effects**: identical to {@link gamePickSubmitSelection} — buy-in
+	 * deduction on first submit, participation recorded, score awarded on round
+	 * resolution.
 	 *
 	 * **Visitor mode**: not supported.
 	 *