@smartico/public-api 0.0.399 → 0.0.401

package/docs/api/interfaces/GamePickRoundRequestParams.md

@@ -0,0 +1,63 @@
+# Interface: GamePickRoundRequestParams
+
+GamePickRoundRequestParams extends base params with a specific round ID
+
+## Extends
+
+- [`GamePickRequestParams`](GamePickRequestParams.md)
+
+## Properties
+
+### saw\_template\_id
+
+> **saw\_template\_id**: `number`
+
+ID of the MatchX or Quiz game template. The only field the consumer supplies.
+
+#### Inherited from
+
+[`GamePickRequestParams`](GamePickRequestParams.md).[`saw_template_id`](GamePickRequestParams.md#saw_template_id)
+
+***
+
+### ext\_user\_id?
+
+> `optional` **ext\_user\_id?**: `string`
+
+External user ID. Injected by the SDK from the active session; consumers omit it.
+
+#### Inherited from
+
+[`GamePickRequestParams`](GamePickRequestParams.md).[`ext_user_id`](GamePickRequestParams.md#ext_user_id)
+
+***
+
+### smartico\_ext\_user\_id?
+
+> `optional` **smartico\_ext\_user\_id?**: `string`
+
+Platform external user ID. Injected by the SDK from the active session; consumers omit it.
+
+#### Inherited from
+
+[`GamePickRequestParams`](GamePickRequestParams.md).[`smartico_ext_user_id`](GamePickRequestParams.md#smartico_ext_user_id)
+
+***
+
+### lang?
+
+> `optional` **lang?**: `string`
+
+Language code for translations (e.g. 'EN', 'DE'). Defaults to the session language.
+
+#### Inherited from
+
+[`GamePickRequestParams`](GamePickRequestParams.md).[`lang`](GamePickRequestParams.md#lang)
+
+***
+
+### round\_id
+
+> **round\_id**: `number`
+
+ID of the specific round

package/docs/api/interfaces/GamePickUserInfo.md

@@ -0,0 +1,107 @@
+# Interface: GamePickUserInfo
+
+GamePickUserInfo describes the current user's profile in the games system
+
+## Properties
+
+### ext\_user\_id
+
+> **ext\_user\_id**: `string`
+
+External user ID (Smartico numeric user ID)
+
+***
+
+### int\_user\_id
+
+> **int\_user\_id**: `number`
+
+Internal user ID within the games system
+
+***
+
+### public\_username
+
+> **public\_username**: `string`
+
+Display name
+
+***
+
+### avatar\_url
+
+> **avatar\_url**: `string`
+
+URL of the user's avatar image
+
+***
+
+### gp\_position?
+
+> `optional` **gp\_position?**: `number`
+
+User's leaderboard rank position
+
+***
+
+### full\_wins\_count?
+
+> `optional` **full\_wins\_count?**: `number`
+
+Number of fully correct predictions
+
+***
+
+### part\_wins\_count?
+
+> `optional` **part\_wins\_count?**: `number`
+
+Number of partially correct predictions
+
+***
+
+### resolution\_score?
+
+> `optional` **resolution\_score?**: `number`
+
+User's total score
+
+***
+
+### last\_wallet\_sync\_time?
+
+> `optional` **last\_wallet\_sync\_time?**: `Date`
+
+Last time the user's balance was synced from the Smartico platform
+
+***
+
+### ach\_points\_balance?
+
+> `optional` **ach\_points\_balance?**: `number`
+
+User's current points balance
+
+***
+
+### ach\_gems\_balance?
+
+> `optional` **ach\_gems\_balance?**: `number`
+
+User's current gems balance
+
+***
+
+### ach\_diamonds\_balance?
+
+> `optional` **ach\_diamonds\_balance?**: `number`
+
+User's current diamonds balance
+
+***
+
+### pubic\_username\_set?
+
+> `optional` **pubic\_username\_set?**: `boolean`
+
+Whether the user has set a custom public username

package/docs/api/interfaces/GamesApiResponse.md

@@ -0,0 +1,33 @@
+# Interface: GamesApiResponse\<T\>
+
+GamesApiResponse is the standard response wrapper for all GamePick/Quiz API calls
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Properties
+
+### errCode
+
+> **errCode**: `number`
+
+Error code; `0` = success. Per-method code tables live in each `gamePick*` method's TSDoc.
+
+***
+
+### errMessage?
+
+> `optional` **errMessage?**: `string`
+
+Human-readable error message; populated when `errCode` is non-zero.
+
+***
+
+### data?
+
+> `optional` **data?**: `T`
+
+Response payload, present on success

package/docs/api/interfaces/Level.md

@@ -49,3 +49,11 @@ Internal status of level. Not in use right now on the front-end
 ### general\_level\_progress
 
 > **general\_level\_progress**: `number`
+
+***
+
+### ordinal\_position?
+
+> `optional` **ordinal\_position?**: `number`
+
+1-based position of this level within the level ladder.

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/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/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.399",
+	"version": "0.0.401",
 	"description": "Smartico public API",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

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

@@ -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/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/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.
 	 *