@smartico/public-api 0.0.399 → 0.0.401

package/dist/Core/index.d.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/dist/GamePick/GamePickTypes.d.ts

@@ -432,9 +432,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;
@@ -443,13 +443,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/dist/Level/Level.d.ts

@@ -9,5 +9,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/dist/SmarticoGlobal.d.ts

@@ -0,0 +1,190 @@
+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/dist/WSAPI/WSAPIGamePick.d.ts

@@ -276,9 +276,9 @@ export declare 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`).
      *
@@ -370,9 +370,9 @@ export declare 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.
      *

package/dist/WSAPI/WSAPIMiniGames.d.ts

@@ -256,10 +256,8 @@ export declare class WSAPIMiniGames extends WSAPIRaffles {
      * Pass `acknowledge: false` to skip that automatic step.
      * `playMiniGame` then resolves as soon as the spin result is known,
      * without waiting for the win to be marked delivered. You finalise
-     * it later by calling {@link miniGameWinAcknowledgeRequest}. The
-     * result does NOT carry the spin's request id — obtain it as the
-     * `client_request_id` of the matching {@link getMiniGamesHistory}
-     * row (the spin appears there with `is_claimed: false`).
+     * it later by calling {@link miniGameWinAcknowledgeRequest} with the
+     * `request_id` returned on this result.
      *
      * What `acknowledge: false` does and does NOT defer:
      * - For STANDARD prizes the value is credited at spin time
@@ -374,12 +372,9 @@ export declare class WSAPIMiniGames extends WSAPIRaffles {
      *   // are credited only by the acknowledge below.
      *   console.log('[smartico] prize won — show the result / Claim CTA, then finalise');
      *
-     *   // The result has no request id — read it from history as client_request_id.
-     *   const [row] = await window._smartico.api.getMiniGamesHistory({ saw_template_id: game.id, limit: 1 });
-     *   if (row && !row.is_claimed) {
-     *     await window._smartico.api.miniGameWinAcknowledgeRequest(row.client_request_id);
-     *     console.log('[smartico] win finalised — refresh getUserProfile / getMiniGames to reflect it');
-     *   }
+     *   // On the user's Claim click, finalise with the request_id from the result.
+     *   await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
+     *   console.log('[smartico] win finalised — refresh getUserProfile / getMiniGames to reflect it');
      * }
      * ```
      */
@@ -388,63 +383,76 @@ export declare class WSAPIMiniGames extends WSAPIRaffles {
         acknowledge?: boolean;
     }): Promise<TMiniGamePlayResult>;
     /**
-     * Manually acknowledges a mini-game spin — marks the spin as
-     * "delivered" so the prize takes effect server-side. Most consumers
-     * do NOT need to call this method directly; {@link playMiniGame}
-     * and {@link playMiniGameBatch} auto-acknowledge on success. Use
-     * this only for recovery scenarios.
+     * Manually acknowledges a mini-game spin — marks the win delivered
+     * server-side. Most consumers do NOT need this: {@link playMiniGame}
+     * acknowledges by default (`acknowledge: true`) and
+     * {@link playMiniGameBatch} acknowledges automatically. Call this
+     * directly only when you took ownership of the acknowledge step or
+     * need to recover a lost one.
      *
      * @remarks
      * **When to call**
-     * - **Lost auto-acknowledge** — when the WebSocket dropped between
-     *   the spin response and the auto-acknowledge fire-and-forget,
-     *   the spin shows `is_claimed: false` in
-     *   {@link getMiniGamesHistory}. Pass that row's
-     *   `client_request_id` here to deliver the prize.
-     * - **Explicit-acknowledge UI** — for templates configured with
-     *   the `ExplicitAcknowledge` acknowledge type (operator
-     *   decision), the consumer's UI shows a "Claim" CTA after the
-     *   prize animation. Click handler calls this method with the
-     *   spin's `client_request_id` rather than auto-acknowledging.
-     *
-     * **No-op on already-acknowledged spins**
-     * The server's acknowledge SQL matches on `acknowledge_date IS
-     * NULL` — a duplicate call returns successfully with no effect.
+     * - **Primary — after `playMiniGame(..., { acknowledge: false })`.**
+     *   You opted out of the automatic acknowledge to finalise the win
+     *   on your own schedule (e.g. on a user "Claim" tap). Pass the
+     *   `request_id` from that call's result here when ready. This is
+     *   REQUIRED for operator-configured "explicit claim" prizes — they
+     *   are not covered by the server-side fallback, so without this
+     *   call their prize is never credited.
+     * - **Recovery — a lost acknowledge.** {@link playMiniGameBatch}
+     *   acknowledges on a fire-and-forget basis; if one is lost (network
+     *   drop) the spin shows `is_claimed: false` in
+     *   {@link getMiniGamesHistory}. Pass that row's `client_request_id`
+     *   to deliver it.
+     *
+     * The `request_id` on a {@link playMiniGame} result and the
+     * `client_request_id` on a {@link getMiniGamesHistory} row are the
+     * same correlation id — this method accepts either.
+     *
+     * **Idempotency**: safe. Acknowledging a spin that is already
+     * finalised — by you, by the automatic acknowledge, or by the
+     * fallback — is a no-op with no double credit. Acknowledging a
+     * failed spin's id is likewise a no-op.
      *
      * **Server-side fallback**
-     * Even without ever calling this method, a server-side job
-     * auto-acknowledges stale spins every ~60 seconds — so prizes are
-     * eventually delivered. The `is_claimed` flag flips on the next
-     * `getMiniGamesHistory` call after the job runs.
-     *
-     * **Idempotency**: safe. Repeated calls have no effect after the
-     * first.
-     *
-     * **Side effects** (on first successful call for an unacknowledged
-     * spin)
-     * - Prize value credited per the prize's type (see
-     *   {@link playMiniGame} "Prize handling").
-     * - The spin's `is_claimed` flag flips to `true` on the next
-     *   {@link getMiniGamesHistory} call.
+     * Even if you never call this, a server-side job finalises ordinary
+     * un-acknowledged spins automatically after a short delay (about 1–3
+     * minutes), flipping `is_claimed` to `true` on the next
+     * {@link getMiniGamesHistory} fetch. "Explicit claim" prizes are the
+     * exception — excluded from the fallback, they require an explicit
+     * call here.
+     *
+     * **Side effects** (first successful call for an un-acknowledged spin)
+     * - For "explicit claim" prizes, the prize value is credited on this
+     *   call. For standard prizes the value was already credited at spin
+     *   time (see {@link playMiniGame} "Prize handling"); this call only
+     *   marks the win delivered.
+     * - The spin's `is_claimed` flips to `true` on the next
+     *   {@link getMiniGamesHistory} fetch.
      *
      * **Visitor mode**: not supported.
      *
-     * @param request_id  The `client_request_id` from a `TSawHistory`
-     *                    row returned by {@link getMiniGamesHistory}.
+     * @param request_id  Correlation id of the spin to finalise: the
+     *                    `request_id` from a {@link playMiniGame} result
+     *                    (played with `acknowledge: false`), or the
+     *                    `client_request_id` of a
+     *                    {@link getMiniGamesHistory} row.
      *
      * @example
      * ```ts
-     * const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
-     * const unacknowledged = history.filter(h => !h.is_claimed);
+     * // Primary — finalise a win you played with acknowledge: false.
+     * const r = await window._smartico.api.playMiniGame(templateId, { acknowledge: false });
+     * if (r.err_code === 0) {
+     *   console.log('[smartico] show the prize / Claim CTA; on Claim, finalise the win');
+     *   await window._smartico.api.miniGameWinAcknowledgeRequest(r.request_id);
+     * }
      *
-     * for (const row of unacknowledged) {
+     * // Recovery — re-acknowledge any spins a batch acknowledge missed.
+     * const history = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
+     * for (const row of history.filter(h => !h.is_claimed)) {
      *   console.log('[smartico] re-acknowledging stale spin', row.client_request_id);
      *   await window._smartico.api.miniGameWinAcknowledgeRequest(row.client_request_id);
      * }
-     *
-     * // Re-fetch history to see the updated is_claimed flags.
-     * const fresh = await window._smartico.api.getMiniGamesHistory({ limit: 20 });
-     * console.log('[smartico] history after recovery —', fresh.filter(h => !h.is_claimed).length, 'still unacknowledged');
      * ```
      */
     miniGameWinAcknowledgeRequest(request_id: string): Promise<import("../MiniGames").SAWDoAknowledgeResponse>;

package/dist/WSAPI/WSAPITypes.d.ts

@@ -98,6 +98,11 @@ export interface TMiniGamePlayResult {
      * (including `prize_type === 'no-prize'` for a configured loss
      * slot). Always populated, even when `err_code !== 0`. */
     prize_id: number;
+    /** 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`. */
+    request_id: string;
 }
 /**
  * TMiniGamePlayBatchResult describes one entry in the array returned

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './Base/ClassId';
 export * from './ILogger';
 export * from './SmarticoAPI';
 export * from './WSAPI/WSAPI';
+export * from './SmarticoGlobal';
 export * from './CookieStore';
 export * from './Analytics';
 export * from './Core';