@smartico/public-api 0.0.345 → 0.0.347

package/README.md

@@ -40,6 +40,22 @@ _smartico.api.getMiniGames( { onUpdate: miniGamesUpdates} ).then( games => {
 
 See the [API documentation](docs/api/classes/WSAPI.md) for all available methods and returning data.
 
+See [expo.smartico.ai](https://expo.smartico.ai/widgets/intro) for the open-source examples of using the API as React-based components. Available examples:
+
+* [User profile](https://expo.smartico.ai/widgets/user) — display user gamification info (points, level, badges)
+* [Mini-games](https://expo.smartico.ai/widgets/mini_games) — show list of mini-games and trigger a mini-game with a deep link
+* [Prize history](https://expo.smartico.ai/widgets/prize_history) — show user's mini-game prize history
+* [Missions](https://expo.smartico.ai/widgets/missions) — list missions, opt-in, and claim rewards
+* [Store](https://expo.smartico.ai/widgets/store) — display store items and categories, handle purchases
+* [Tournaments](https://expo.smartico.ai/widgets/tournaments) — show tournament lobby and registration
+* [Inbox](https://expo.smartico.ai/widgets/inbox) — inbox messages with read/delete/favorite actions
+* [Custom Level Map](https://expo.smartico.ai/widgets/api_custom_lvl_map) — build a custom level progression map
+* [Custom mini-game via API](https://expo.smartico.ai/widgets/dp_custom_mini_game) — implement a fully custom mini-game using the API
+* [Custom mini-game example](https://expo.smartico.ai/widgets/dp_custom_mini_game_example) — working example of a custom mini-game
+* [Jackpots](https://expo.smartico.ai/jackpots/jp_intro) — jackpot opt-in, custom win animation, multi-jackpot
+* [Raffles](https://expo.smartico.ai/raffles/raffle_intro) — raffle draws, prizes, and draw history
+* [UI Widgets](https://expo.smartico.ai/ui_widgets/dp_ui_widgets) — pre-built UI widgets for mini-games, leaderboard, store, missions, badges, tournaments, levels, and jackpots
+
 ## Visitor mode
 
 You can also get gamification data for the visitors (not authorized users). 
@@ -56,6 +72,43 @@ _smartico.vapi('EN').getLevels().then( levels => {
 
 ```
 
+See [expo.smartico.ai/visitor_api](https://expo.smartico.ai/visitor_api/visitor_api_intro) for open-source examples of the Visitor API:
+
+* [Missions](https://expo.smartico.ai/visitor_api/visitor_api_missions) — display missions available for visitors
+* [Tournaments](https://expo.smartico.ai/visitor_api/visitor_api_tournaments) — show tournament lobby for non-authenticated users
+* [Store](https://expo.smartico.ai/visitor_api/visitor_api_store) — display store items before user login
+* [Custom levels map](https://expo.smartico.ai/visitor_api/visitor_api_custom_lvl_map) — build a custom level map for visitors
+
+## Using in Native apps (iOS/Android)
+
+Smartico supports integration with native iOS and Android applications via a WebSocket-based protocol and a Native Bridge for WebView communication.
+
+### General integration guide
+
+See the full integration guide: [iOS/Android clients integration guide](https://help.smartico.ai/welcome/technical-guides/front-end-integration/ios-android-clients-integration-guide)
+
+### Connection flow
+
+1. Establish a WebSocket connection to the Smartico API endpoint
+2. Send `INIT` (cid: 3) → receive `INIT_RESPONSE` (cid: 4)
+3. Send `IDENTIFY` (cid: 5) → receive `IDENTIFY_RESPONSE` (cid: 6)
+4. Send `LOGIN` (cid: 7) → receive `LOGIN_RESPONSE` (cid: 11)
+5. Session is active — call any API methods (missions, store, mini-games, tournaments, etc.)
+6. Maintain connection with PING/PONG keepalive
+7. Listen for server-initiated events (popups, mini-game triggers, deep links, property changes)
+
+### Gamification widget & popups
+
+The `IDENTIFY_RESPONSE` returns `native_app_gf_url` and `native_app_popup_url` — use these to load gamification and engagement content in a WebView. The native app communicates with loaded web pages through the Native Bridge interface (`SmarticoBridge`).
+
+### Push notifications
+
+Register push tokens via WebSocket (cid: 1003) or via HTTP POST/GET to the Smartico public endpoint. See the [integration guide](https://help.smartico.ai/welcome/technical-guides/front-end-integration/ios-android-clients-integration-guide) for details on reporting delivery, impression, and click events.
+
+### Protocol reference
+
+For the full low-level protocol specification including all API methods (levels, missions, store, mini-games, tournaments, leaderboard, inbox, jackpots, raffles, etc.) and server-initiated events, see [Native Protocol](docs/native/PROTOCOL.md).
+
 ## Backend usage (NodeJS context)
 
 Note: access to the server-to-server API is not provided by default and is a topic for a separate agreement with Smartico.
@@ -84,7 +137,67 @@ response.templates.forEach( t => {
 
 ```
 
-## Development and publishing process
+## Backend usage (http-protocol)
+
+You can make HTTP calls to the Smartico public endpoint to interact with user data server-to-server — for example, to check if a specific user belongs to segment(s).
+
+> **Note:** Usage of backend-based integration is subject to rate limits and additional charges. High/intensive usage may degrade performance of your client setup. Please contact your Smartico account manager for pricing details based on your expected request volume.
+
+### What you will need
+
+- **Endpoint** — has the form `https://imgX.smr.vc/s2s-api`, where `X` corresponds to your environment ID (ask your account manager)
+- **Label public API key**
+- **Brand public API key**
+
+### Example: check segment membership
+
+This example checks whether a user belongs to specific segments. It corresponds to `checkSegmentListMatch` (cid: 161 / response cid: 162) described in [Native Protocol](docs/native/PROTOCOL.md).
+
+**Request:**
+
+```bash
+curl --location 'https://imgX.smr.vc/s2s-api' \
+--header 'Content-Type: application/json' \
+--data '{
+  "api_key": "your-label-public-api-key",
+  "brand_key": "your-brand-public-api-key",
+  "ext_user_id": "your-user-ext-id",
+  "cid": 161,
+  "uuid": "f07f0730-4886-4135-81b7-62c94659d3cf",
+  "ts": 1770278728317,
+  "segment_id": [
+    6493, 1234
+  ]
+}'
+```
+
+**Response:**
+
+```json
+{
+    "segments": [
+        {
+            "segment_id": 6493,
+            "is_matching": true
+        },
+        {
+            "segment_id": 1234,
+            "is_matching": false
+        }
+    ],
+    "errCode": 0,
+    "errMsg": "",
+    "cid": 162,
+    "ts": 1770303940950,
+    "uuid": "f07f0730-4886-4135-81b7-62c94659d3cf"
+}
+```
+
+### Using other API methods
+
+You can call any API method described in [Native Protocol](docs/native/PROTOCOL.md) using the same HTTP approach. Build the request body with the appropriate `cid` and method-specific fields, along with `api_key`, `brand_key`, `ext_user_id`, `uuid`, and `ts`. The response will follow the same structure documented for each method.
+
+## For Smartico developers
 
 ### Publishing process
 

package/dist/SmarticoAPI.d.ts

@@ -11,7 +11,7 @@ import { GetTournamentInfoResponse, GetTournamentsResponse, TournamentRegisterRe
 import { LeaderBoardDetails, LeaderBoardPeriodType } from './Leaderboard';
 import { GetLevelMapResponse } from './Level';
 import { WSAPI } from './WSAPI/WSAPI';
-import { TInboxMessage, TInboxMessageBody, TLevel, TMiniGameTemplate, TMissionOrBadge, TStoreCategory, TAchCategory, TStoreItem, TTournament, TTournamentDetailed, LeaderBoardDetailsT, UserLevelExtraCountersT, TSegmentCheckResult, TUICustomSection, TBonus, TRaffle, TLevelCurrent, TActivityLog } from './WSAPI/WSAPITypes';
+import { TInboxMessage, TInboxMessageBody, TLevel, TMiniGameTemplate, TMissionOrBadge, TStoreCategory, TAchCategory, TStoreItem, TTournament, TTournamentDetailed, LeaderBoardDetailsT, UserLevelExtraCountersT, TSegmentCheckResult, TUICustomSection, TBonus, TRaffle, TLevelCurrent, TActivityLog, TRaffleDraw } from './WSAPI/WSAPITypes';
 import { GetAchievementsUserInfoResponse } from './Core/GetAchievementsUserInfoResponse';
 import { GetJackpotsPotsResponse, GetJackpotsResponse, JackpotsOptinResponse, JackpotsOptoutResponse } from './Jackpots';
 import { GetCustomSectionsResponse } from './CustomSections';
@@ -160,7 +160,10 @@ declare class SmarticoAPI {
     getRaffleDrawRun(user_ext_id: string, payload: {
         raffle_id: number;
         run_id: number;
+        winners_limit?: number;
+        winners_offset?: number;
     }): Promise<GetDrawRunResponse>;
+    getRaffleDrawRunT(user_ext_id: string, raffle_id: number, run_id: number, winners_from?: number, winners_to?: number): Promise<TRaffleDraw>;
     getRaffleDrawRunsHistory(user_ext_id: string, props: {
         raffle_id: number;
         draw_id?: number;

package/dist/WSAPI/WSAPI.d.ts

@@ -735,7 +735,8 @@ export declare class WSAPI {
         onUpdate?: (data: TRaffle[]) => void;
     }): Promise<TRaffle[]>;
     /**
-     * Returns draw run for provided raffle_id and run_id
+     * Returns draw run for provided raffle_id and run_id.
+     * You can pass winners_from and winners_to parameters to get a specific range of winners. Default is 0-20.
      *
      *
      * **Example**:
@@ -759,6 +760,8 @@ export declare class WSAPI {
     getRaffleDrawRun(props: {
         raffle_id: number;
         run_id: number;
+        winners_from?: number;
+        winners_to?: number;
     }): Promise<TRaffleDraw>;
     /**
      * Returns history of draw runs for the provided raffle_id and draw_id, if the draw_id is not provided will return history of all the draws for the provided raffle_id

package/dist/WSAPI/WSAPITypes.d.ts

@@ -521,6 +521,8 @@ export interface TStoreItem {
     only_in_custom_section?: boolean;
     /** ID of specific Custom Section type */
     custom_section_type_id?: number;
+    /** The message that should be shown to the user if they are not eligible to buy it. This message can be used to explain the reason why user cannot buy the item, e.g. 'You should be VIP to buy this item'. */
+    cant_buy_message?: string;
 }
 /**
  * TAchCategory describes the badge category item. Each badge item can be assigned to 1 or more categories

package/dist/index.js

@@ -1026,7 +1026,7 @@ var StoreItemTransform = function StoreItemTransform(items) {
     return r.id >= 1;
   }).map(function (r) {
     var _r$itemPublicMeta$pri, _r$categoryIds;
-    var x = {
+    var x = _extends({
       id: r.id,
       name: r.itemPublicMeta.name,
       purchase_type: mapPurchaseType$1(r.itemPublicMeta.purchase_type),
@@ -1051,7 +1051,9 @@ var StoreItemTransform = function StoreItemTransform(items) {
       custom_section_id: r.itemPublicMeta.custom_section_id,
       only_in_custom_section: r.itemPublicMeta.only_in_custom_section,
       custom_section_type_id: r.itemPublicMeta.custom_section_type_id
-    };
+    }, r.itemPublicMeta.cant_buy_message ? {
+      cant_buy_message: r.itemPublicMeta.cant_buy_message
+    } : {});
     return x;
   });
 };
@@ -3675,7 +3677,8 @@ var WSAPI = /*#__PURE__*/function () {
     }
   }
   /**
-   * Returns draw run for provided raffle_id and run_id
+   * Returns draw run for provided raffle_id and run_id.
+   * You can pass winners_from and winners_to parameters to get a specific range of winners. Default is 0-20.
    *
    *
    * **Example**:
@@ -3700,12 +3703,10 @@ var WSAPI = /*#__PURE__*/function () {
   _proto.getRaffleDrawRun = function getRaffleDrawRun(props) {
     try {
       var _this57 = this;
-      return Promise.resolve(_this57.api.getRaffleDrawRun(null, props)).then(function (res) {
-        if (!props.raffle_id || !props.run_id) {
-          throw new Error('both raffle_id and run_id are required');
-        }
-        return drawRunTransform(res);
-      });
+      if (!props.raffle_id || !props.run_id) {
+        throw new Error('both raffle_id and run_id are required');
+      }
+      return Promise.resolve(_this57.api.getRaffleDrawRunT(null, props.raffle_id, props.run_id, props.winners_from, props.winners_to));
     } catch (e) {
       return Promise.reject(e);
     }
@@ -5259,43 +5260,64 @@ var SmarticoAPI = /*#__PURE__*/function () {
       return Promise.reject(e);
     }
   };
-  _proto.getRaffleDrawRunsHistory = function getRaffleDrawRunsHistory(user_ext_id, props) {
+  _proto.getRaffleDrawRunT = function getRaffleDrawRunT(user_ext_id, raffle_id, run_id, winners_from, winners_to) {
+    if (winners_from === void 0) {
+      winners_from = 0;
+    }
+    if (winners_to === void 0) {
+      winners_to = 20;
+    }
     try {
       var _this72 = this;
-      var message = _this72.buildMessage(user_ext_id, exports.ClassId.RAF_GET_DRAW_HISTORY_REQUEST, props);
-      return Promise.resolve(_this72.send(message, exports.ClassId.RAF_GET_DRAW_HISTORY_RESPONSE));
+      var winners_limit = winners_to - winners_from > 50 ? 50 : winners_to - winners_from;
+      var winners_offset = winners_from;
+      return Promise.resolve(_this72.getRaffleDrawRun(user_ext_id, {
+        raffle_id: raffle_id,
+        run_id: run_id,
+        winners_limit: winners_limit,
+        winners_offset: winners_offset
+      })).then(drawRunTransform);
     } catch (e) {
       return Promise.reject(e);
     }
   };
-  _proto.claimRafflePrize = function claimRafflePrize(user_ext_id, props) {
+  _proto.getRaffleDrawRunsHistory = function getRaffleDrawRunsHistory(user_ext_id, props) {
     try {
       var _this73 = this;
-      var message = _this73.buildMessage(user_ext_id, exports.ClassId.RAF_CLAIM_PRIZE_REQUEST, props);
-      return Promise.resolve(_this73.send(message, exports.ClassId.RAF_CLAIM_PRIZE_RESPONSE));
+      var message = _this73.buildMessage(user_ext_id, exports.ClassId.RAF_GET_DRAW_HISTORY_REQUEST, props);
+      return Promise.resolve(_this73.send(message, exports.ClassId.RAF_GET_DRAW_HISTORY_RESPONSE));
     } catch (e) {
       return Promise.reject(e);
     }
   };
-  _proto.raffleOptin = function raffleOptin(user_ext_id, props) {
+  _proto.claimRafflePrize = function claimRafflePrize(user_ext_id, props) {
     try {
       var _this74 = this;
-      var message = _this74.buildMessage(user_ext_id, exports.ClassId.RAF_OPTIN_REQUEST, props);
-      return Promise.resolve(_this74.send(message, exports.ClassId.RAF_OPTIN_RESPONSE));
+      var message = _this74.buildMessage(user_ext_id, exports.ClassId.RAF_CLAIM_PRIZE_REQUEST, props);
+      return Promise.resolve(_this74.send(message, exports.ClassId.RAF_CLAIM_PRIZE_RESPONSE));
     } catch (e) {
       return Promise.reject(e);
     }
   };
-  _proto.getActivityLog = function getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset) {
+  _proto.raffleOptin = function raffleOptin(user_ext_id, props) {
     try {
       var _this75 = this;
-      var message = _this75.buildMessage(user_ext_id, exports.ClassId.GET_POINT_HISTORY_REQUEST, {
+      var message = _this75.buildMessage(user_ext_id, exports.ClassId.RAF_OPTIN_REQUEST, props);
+      return Promise.resolve(_this75.send(message, exports.ClassId.RAF_OPTIN_RESPONSE));
+    } catch (e) {
+      return Promise.reject(e);
+    }
+  };
+  _proto.getActivityLog = function getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset) {
+    try {
+      var _this76 = this;
+      var message = _this76.buildMessage(user_ext_id, exports.ClassId.GET_POINT_HISTORY_REQUEST, {
         startTimeSeconds: Math.floor(startTimeSeconds),
         endTimeSeconds: Math.floor(endTimeSeconds),
         limit: limit,
         offset: offset
       });
-      return Promise.resolve(_this75.send(message, exports.ClassId.GET_POINT_HISTORY_RESPONSE));
+      return Promise.resolve(_this76.send(message, exports.ClassId.GET_POINT_HISTORY_RESPONSE));
     } catch (e) {
       return Promise.reject(e);
     }
@@ -5308,11 +5330,11 @@ var SmarticoAPI = /*#__PURE__*/function () {
       to = 50;
     }
     try {
-      var _this76 = this;
+      var _this77 = this;
       var limit = to - from > 50 ? 50 : to - from;
       var offset = from;
-      return Promise.resolve(_this76.getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset)).then(function (_this76$getActivityLo) {
-        return ActivityLogTransform(_this76$getActivityLo.logHistory);
+      return Promise.resolve(_this77.getActivityLog(user_ext_id, startTimeSeconds, endTimeSeconds, limit, offset)).then(function (_this77$getActivityLo) {
+        return ActivityLogTransform(_this77$getActivityLo.logHistory);
       });
     } catch (e) {
       return Promise.reject(e);