@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/_responses/getUserProfile.json

@@ -0,0 +1,34 @@
+{
+  "core_public_tags": [
+    "SMARTICO.DEV"
+  ],
+  "ach_points_ever": 690,
+  "core_clan_is_kicked": null,
+  "user_last_session_push_state": "BLOCKED",
+  "aff_referred_by_friend_ext_user_id": null,
+  "core_inbox_unread_count": 0,
+  "core_user_language": "EN",
+  "ach_level_current": "Silver",
+  "ach_gems_balance": 10,
+  "ach_level_current_id": 698,
+  "user_country": "BG",
+  "ach_points_balance": 326,
+  "core_registration_date": 0,
+  "core_recommended_deposit_amount": 0,
+  "core_recommended_casino_bet_amount": 0,
+  "ach_gamification_in_control_group": false,
+  "core_avatar_real_id": null,
+  "core_wallet_currency": "UNKNOWN",
+  "ach_diamonds_balance": 1,
+  "aff_refer_friend_url": null,
+  "acc_bonus_abuser": false,
+  "aff_refered_friends_count": 0,
+  "core_clan_kicked_out_id": null,
+  "core_clan_id": "",
+  "core_is_test_account": false,
+  "user_id": 361368543,
+  "avatar_id": "https://cdn.example/avatars/12/00000000-0000-0000-0000-000000000000.png",
+  "avatar_real_id": 12,
+  "public_username": "Antonio",
+  "avatar_url": "https://cdn.example/avatars/12/00000000-0000-0000-0000-000000000000.png"
+}

package/docs/capabilities/_responses/jackpotGet.json

@@ -0,0 +1,113 @@
+[
+  {
+    "jp_template_id": 6,
+    "jp_type_id": 1,
+    "jp_public_meta": {
+      "image_url": "https://cdn.example/f8b68a18473c437e32a860-Jackpot1.jpg",
+      "placeholder1": null,
+      "placeholder2": null,
+      "name": "Minor",
+      "description": "1% on top of your bet amount will be contributed to the Jackpot",
+      "not_winner_template": {
+        "id": "0",
+        "content": ""
+      },
+      "priority": "1",
+      "winner_template": {
+        "id": "0",
+        "content": ""
+      },
+      "custom_data": {}
+    },
+    "jp_currency": "EUR",
+    "user_currency": "EUR",
+    "related_games": [],
+    "contribution_type": 2,
+    "contribution_value": 0.2,
+    "pot": {
+      "jp_template_id": 6,
+      "jp_pot_id": 306140,
+      "user_id": null,
+      "current_pot_amount": 12.28367028,
+      "current_pot_amount_user_currency": 12.28367028,
+      "explode_date_ts": null,
+      "current_pot_temperature": 2
+    },
+    "is_opted_in": false,
+    "is_auto_opt_in": true,
+    "ach_related_game_allow_all": true,
+    "registration_count": 17262,
+    "contribution_rules": [
+      {
+        "ruleId": 1,
+        "jpTemplateId": 6,
+        "type": 2,
+        "extEntityIds": [
+          "1111"
+        ],
+        "contributionValue": 4
+      },
+      {
+        "ruleId": 2,
+        "jpTemplateId": 6,
+        "type": 1,
+        "extEntityIds": [
+          "666666"
+        ],
+        "contributionValue": 3
+      }
+    ],
+    "expose_winners_over_api": false
+  },
+  {
+    "jp_template_id": 4,
+    "jp_type_id": 1,
+    "jp_public_meta": {
+      "image_url": "https://cdn.example/f8b68a18473c437e32a860-Jackpot1.jpg",
+      "placeholder1": null,
+      "placeholder2": null,
+      "name": "Major",
+      "description": "1% on top of your bet amount will be contributed to the Jackpot",
+      "not_winner_template": {
+        "id": "0",
+        "content": ""
+      },
+      "priority": "2",
+      "winner_template": {
+        "id": "0",
+        "content": ""
+      },
+      "custom_data": {}
+    },
+    "jp_currency": "EUR",
+    "user_currency": "EUR",
+    "related_games": [],
+    "contribution_type": 2,
+    "contribution_value": 6.7,
+    "pot": {
+      "jp_template_id": 4,
+      "jp_pot_id": 306164,
+      "user_id": null,
+      "current_pot_amount": 780.319207992,
+      "current_pot_amount_user_currency": 780.319207992,
+      "explode_date_ts": null,
+      "current_pot_temperature": 2
+    },
+    "is_opted_in": true,
+    "is_auto_opt_in": true,
+    "ach_related_game_allow_all": true,
+    "registration_count": 32971,
+    "contribution_rules": [
+      {
+        "ruleId": 3,
+        "jpTemplateId": 4,
+        "type": 2,
+        "extEntityIds": [
+          "999"
+        ],
+        "contributionValue": 8
+      }
+    ],
+    "expose_winners_over_api": false
+  }
+]

package/docs/capabilities/_responses/jackpotOptIn.json

@@ -0,0 +1,9 @@
+{
+  "errCode": 1,
+  "errMsg": "JP User already opted in to Jackpot",
+  "cid": 805,
+  "ts": 1782287009179,
+  "uuid": "00000000-0000-0000-0000-000000000000",
+  "payload": null,
+  "duration": null
+}

package/docs/capabilities/_responses/jackpotOptOut.json

@@ -0,0 +1,9 @@
+{
+  "errCode": 0,
+  "errMsg": "",
+  "cid": 807,
+  "ts": 1782229816688,
+  "uuid": "00000000-0000-0000-0000-000000000000",
+  "payload": null,
+  "duration": null
+}

package/docs/capabilities/_responses/markAllInboxMessagesAsRead.json

@@ -0,0 +1,4 @@
+{
+  "err_code": 0,
+  "err_message": ""
+}

package/docs/capabilities/_responses/markInboxMessageAsRead.json

@@ -0,0 +1,4 @@
+{
+  "err_code": 0,
+  "err_message": ""
+}

package/docs/capabilities/_responses/markUnmarkInboxMessageAsFavorite.json

@@ -0,0 +1,4 @@
+{
+  "err_code": 0,
+  "err_message": ""
+}

package/docs/capabilities/_responses/miniGameWinAcknowledgeRequest.json

@@ -0,0 +1,10 @@
+{
+  "request_id": "00000000-0000-0000-0000-000000000000",
+  "errCode": 0,
+  "errMsg": "",
+  "cid": 705,
+  "ts": 1782287011139,
+  "uuid": "00000000-0000-0000-0000-000000000000",
+  "payload": null,
+  "duration": null
+}

package/docs/capabilities/_responses/playMiniGame.json

@@ -0,0 +1,6 @@
+{
+  "err_code": 0,
+  "err_message": "",
+  "prize_id": 37373,
+  "request_id": "00000000-0000-0000-0000-000000000000"
+}

package/docs/capabilities/_responses/playMiniGameBatch.json

@@ -0,0 +1,9 @@
+[
+  {
+    "errCode": 40004,
+    "errMessage": "Failed to spin. Max spins reached",
+    "saw_prize_id": null,
+    "jackpot_amount": null,
+    "first_spin_in_period": 1782287011000
+  }
+]

package/docs/capabilities/_responses/registerInTournament.json

@@ -0,0 +1,4 @@
+{
+  "err_code": 0,
+  "err_message": ""
+}

package/docs/capabilities/_responses/requestMissionOptIn.json

@@ -0,0 +1,4 @@
+{
+  "err_code": 0,
+  "err_message": ""
+}

package/docs/capabilities/_responses/setAvatar.json

@@ -0,0 +1,4 @@
+{
+  "err_code": 4,
+  "err_message": "Avatar is not available"
+}

package/docs/capabilities/avatarsCustomize.md

@@ -0,0 +1,115 @@
+# avatarsCustomize — API (AvatarCustomizeResponse)
+
+> Generates an AI-customized variant of a base avatar by applying an operator-defined style prompt, returning the CDN URL of the result.
+> Import: `import { AvatarCustomizeResponse } from '@smartico/public-api'`
+> Search terms: avatarsCustomize, avatars, AvatarCustomizeResponse, AvatarCustomizeErrorCode
+
+## Signature
+```ts
+_smartico.api.avatarsCustomize(props: {
+		user_id: number;
+		prompt_id: number;
+		avatar_url: string;
+		avatar_real_id: number;
+	}): Promise<AvatarCustomizeResponse>
+```
+
+## Parameters
+- `props.user_id` — Numeric Smartico user ID.
+- `props.prompt_id` — Style-prompt ID (`prompt_id`) from `getAvatarPrompts`.
+- `props.avatar_url` — CDN URL of the base avatar to customize.
+- `props.avatar_real_id` — `avatar_real_id` of the base avatar.
+
+## Returns — `Promise<AvatarCustomizeResponse>`
+`AvatarCustomizeResponse`:
+- `cdn_url` (string) — CDN URL of the generated avatar variant. Present on success.
+- `errCode` (AvatarCustomizeErrorCode | number) — Error code. Present on failure. Typed values are members of `AvatarCustomizeErrorCode`; `-1` is a generic failure. See the `avatarsCustomize` TSDoc for the full table.
+- `errMessage` (string) — Optional error message. Present on failure; the generic (`-1`) message is fixed text, so branch on `errCode`, not this string.
+
+## Behavioral contract
+**Preconditions**
+- Authenticated session required; not available in visitor mode (throws).
+- All five fields are mandatory — the SDK throws synchronously
+ (`Error("<field> is required")`) if any is missing or zero.
+- `prompt_id` must be one of the prompts from `getAvatarPrompts`;
+ `avatar_url` / `avatar_real_id` identify the base avatar to style.
+
+**Cost**
+Each generation costs the currency the operator configured on the
+chosen prompt (points, gems, or diamonds — some prompts are free; read
+`cost_currency_type_id` / `cost_value` from the `getAvatarPrompts`
+entry to gate the UI before calling). The cost is charged only on
+success; if the user can't afford it the call fails with `errCode -1`
+and nothing is generated or charged.
+
+**Latency**
+Generation runs server-side AI image synthesis and is synchronous from
+the caller's side — expect several seconds (roughly 5–20 s) before the
+promise resolves. There is no SDK cache and no push/subscription; show
+a loading state for the full duration and disable the trigger to
+prevent duplicate submissions.
+
+**Result & error codes**
+On success the result has `cdn_url` set; on failure it has `errCode` /
+`errMessage` set and no `cdn_url`. Branch on `errCode` — the generic
+message is fixed text, not cause-specific:
+- `12001` (`AvatarCustomizeErrorCode.AVATAR_USER_LIMIT`) — the user hit
+ their monthly per-user generation cap. Nothing is generated or charged.
+- `12002` (`AvatarCustomizeErrorCode.AVATAR_LABEL_LIMIT`) — the brand's
+ shared monthly pool is exhausted. Nothing is generated or charged;
+ surface a "try again later" message.
+- `-1` — generic failure: insufficient balance, an unavailable prompt,
+ or a generation error. Nothing is charged. Allow the user to retry.
+
+Both monthly caps are operator-configured and reset at the start of
+each calendar month.
+
+**Side effects (on success)**
+The generated variant is persisted to the user's customization history
+and counts toward the monthly caps **whether or not** it is later
+activated — generation is not reversible. The SDK clears the
+`getAvatarsCustomized` cache so the next call surfaces the new
+variant. The user's active avatar is unchanged until you call
+`setAvatar` with the returned `cdn_url`.
+
+**Idempotency**: not idempotent — each successful call generates (and
+charges for) a new variant. Guard the call site against double-clicks.
+
+**UI guidance**: see [UI Guide — `avatarsCustomize`](../../docs/ui/avatars/UIGuide_avatarsCustomize.md).
+
+**Visitor mode**: not supported (throws).
+
+## Example
+```ts
+// user_id identifies the Smartico user being customized.
+const prompts = await window._smartico.api.getAvatarPrompts();
+const prompt = prompts[0];
+
+console.log('[smartico] generating avatar — show a spinner for ~5-20s and disable the Generate button');
+const result = await window._smartico.api.avatarsCustomize({
+  user_id,
+  prompt_id: prompt.prompt_id,
+  avatar_url: baseAvatar.avatar_url,
+  avatar_real_id: baseAvatar.avatar_real_id,
+});
+
+if (result.cdn_url) {
+  console.log('[smartico] generation succeeded — preview this URL, then call setAvatar to apply it:', result.cdn_url);
+  // await window._smartico.api.setAvatar({ avatar_url: result.cdn_url, avatar_real_id: baseAvatar.avatar_real_id });
+} else if (result.errCode === 12001) {
+  console.error('[smartico] user monthly limit reached — show "you have used all your custom avatars this month"');
+} else if (result.errCode === 12002) {
+  console.error('[smartico] brand monthly pool exhausted — show "custom avatars are unavailable right now, try later"');
+} else {
+  console.error('[smartico] generation failed (e.g. not enough balance) — let the user retry:', result.errMessage);
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `setAvatar`
+- `getAvatarPrompts`
+- `getAvatarsCustomized`
+- `AvatarCustomizeResponse`

package/docs/capabilities/buyStoreItem.md

@@ -0,0 +1,179 @@
+# buyStoreItem — API (TBuyStoreItemResult)
+
+> Purchase a specific store item on behalf of the current user.
+> Import: `import { TBuyStoreItemResult } from '@smartico/public-api'`
+> Search terms: buyStoreItem, store, TBuyStoreItemResult, BuyStoreItemErrorCode, err_code, err_message
+
+## Signature
+```ts
+_smartico.api.buyStoreItem(item_id: number): Promise<TBuyStoreItemResult>
+```
+
+## Parameters
+- `item_id` — The store item `id` (from `getStoreItems()`).
+
+## Returns — `Promise<TBuyStoreItemResult>`
+`TBuyStoreItemResult`:
+- `err_code` (BuyStoreItemErrorCode) — Error code. `0` = success. See `buyStoreItem` TSDoc for the full table.
+- `err_message` (string) — Optional error message; populated on non-zero `err_code`.
+
+## Behavioral contract
+**Preconditions**
+Read the candidate item from `getStoreItems()` first and gate the call
+on these fields:
+- `can_buy === true` — server-derived; combines segment / visibility
+  conditions and any operator-set restrictions.
+- `pool == null || pool > 0` — `null` means unlimited stock; a positive
+  number means N units remain.
+- User's balance for the item's `purchase_type`
+  (`'points'` / `'gems'` / `'diamonds'`) is `>= price` (or
+  `>= discounted_price` if set). Balances are not on `TStoreItem` —
+  read them from the user properties returned by `getUserState()`.
+- If `active_till_date` is set, it is in the future.
+
+Calling without satisfying these will most likely return a non-zero
+`err_code` (one of the codes below). The SDK does not pre-validate
+— it forwards the request to the server unconditionally.
+
+
+
+**Idempotency**: NOT idempotent. The server performs no de-duplication —
+a second successful call deducts funds again and grants the reward
+again (subject to per-user purchase caps). The SDK itself does **not**
+enforce a single in-flight call. The consumer MUST guard the call site
+against double-clicks (set a local "buying" flag on click, clear it on
+response).
+
+**Refresh after success (and after failure)**
+The SDK automatically re-fetches the store item list and the
+purchased-items history on every response (success or error). Any
+`onUpdate` callback registered via `getStoreItems({ onUpdate })` (or
+the purchased-items equivalent) fires shortly after with the updated
+arrays — reflecting the new `pool`, `can_buy`, and any `purchased_*`
+flags. The user's balance (points / gems / diamonds) is exposed on the
+user-properties channel and updates independently; if the UI displays
+the balance, subscribe to user-property updates separately (it does
+NOT flow through `getStoreItems`).
+
+**Side effects** (consumer-observable on success)
+- User's points / gems / diamonds balance decreases by `price`
+  (or `discounted_price` if set).
+- Item's `pool` decrements by 1 (when `pool != null`).
+- Per-user purchase counters update — `purchased_today`,
+  `purchased_this_week`, `purchased_this_month` on the next
+  `getStoreItems()` refresh.
+- The reward is delivered: bonus issuance, mini-game spin grant,
+  level change, prize drop, raffle ticket, or tangible-item record.
+  Each reward type pushes its own follow-up update (e.g. a new
+  bonus appears in `getBonuses()`, the spin shows up in
+  `getMiniGames()`). Subscribe to each relevant channel separately.
+- A purchase row is appended to the user's purchase history,
+  surfaced via the purchased-items list.
+
+**UI guidance**: see [UI Guide — `buyStoreItem`](../../docs/ui/store/UIGuide_buyStoreItem.md).
+
+## Example
+```ts
+const items = await window._smartico.api.getStoreItems({
+  onUpdate: (next) => console.log('[smartico] store items updated — re-render store grid with this fresh array', next),
+});
+const item = items.find(i => i.id === itemId);
+
+if (!item) {
+  console.log('[smartico] item not in current store list — keep UI as-is, possibly refresh getStoreItems');
+  return;
+}
+
+// Local pre-checks: keep these aligned with the Buy-button decision matrix above.
+const effectivePrice = item.discounted_price ?? item.price;
+const inStock = item.pool == null || item.pool > 0;
+const inWindow = !item.active_till_date || Date.now() < item.active_till_date;
+if (!item.can_buy || !inStock || !inWindow) {
+  console.log('[smartico] buy not applicable — show disabled state with operator copy if any:', item.cant_buy_message);
+  return;
+}
+
+console.log('[smartico] buy starting — set in-flight flag, show loading dots on Buy button, keep detail modal open');
+const r = await window._smartico.api.buyStoreItem(item.id);
+console.log('[smartico] buy response received — clear in-flight flag');
+
+if (r.err_code === 0) {
+  console.log('[smartico] purchase successful — close the detail modal, show a success toast; getStoreItems onUpdate above will fire with the refreshed list (do NOT manually re-fetch)');
+} else if (r.err_code === 11000 || r.err_code === 11011 || r.err_code === 11012) {
+  console.error('[smartico] insufficient balance for this purchase_type — show insufficient-balance UI and how many units are missing:', item.purchase_type, effectivePrice);
+} else if (r.err_code === 11009) {
+  console.error('[smartico] item sold out — show a dedicated "Sold out" message; the auto-refresh will mark the card as such shortly');
+} else if (r.err_code === 11006) {
+  console.error('[smartico] per-user purchase cap reached — surface the operator-defined limit message:', item.limit_message || r.err_message);
+} else if (r.err_code === 11014) {
+  console.error('[smartico] outside purchase window — surface the operator-defined purchase-limit message:', item.purchase_limit_message || r.err_message);
+} else if (r.err_code === 11004 || r.err_code === 11003) {
+  console.error('[smartico] user not eligible / stale visibility — show a localized "try again later" message and let auto-refresh reconcile');
+} else {
+  console.error('[smartico] buy failed — show a generic error toast/modal with this message:', r.err_message);
+}
+```
+
+### Example response (REAL shape)
+> Where this real payload differs from the typed Returns above (TS interface vs raw wire), the REAL shape is the runtime truth.
+```json
+{
+  "err_code": 11002,
+  "err_message": "This bonus cannot be redeemed.You must make at least one real money deposit between redemption of consecutive free bonuses.Please contact support for more in…"
+}
+```
+
+## Errors
+**Error codes** (in `err_code`)
+- `0` — success; funds debited and reward delivered.
+- `1` — generic server error / control-group rejection. Treat as a
+  transient failure; show a "try again later" message.
+- `106` — label mismatch detected before the purchase transaction
+  (e.g. cross-label item id). From a consumer perspective: the item is
+  not purchasable by this user.
+- `11000` (`SHOP_NO_BALANCE`) — insufficient **points** balance.
+  Show an insufficient-balance message that names how many points are
+  missing (`price - current_points_balance`). The Buy button on the
+  item should already be disabled when this is the case; this code
+  normally fires only on a stale local balance.
+- `11001` (`SHOP_WRONG_LABEL`) — user-vs-item label mismatch detected
+  inside the purchase transaction. Distinct from `106`; both mean
+  "not purchasable by this user" from the consumer's perspective.
+  Surface as a generic "item not available" message.
+- `11002` (`SHOP_FAILED_TO_BUY_BONUS`) — the bonus configured on the
+  store item couldn't be issued (bad / disabled bonus config on the
+  operator side). Funds are NOT debited. Surface a generic error and
+  advise the user to contact support if it persists.
+- `11003` (`SHOP_FAILED_TO_BUY_SHOP_ITEM_CONDITION`) — the item's
+  **visibility** segment condition is not satisfied. Shouldn't be
+  reachable through a correctly-rendered UI (the item shouldn't be
+  shown in the first place); usually indicates a stale local store
+  list. Re-fetch via `getStoreItems()`.
+- `11004` (`SHOP_FAILED_TO_BUY_SHOP_ITEM_CONDITION_PURSHASE`) — the
+  item's **purchase** segment condition is not satisfied (the item is
+  visible but the user is not in the buyable segment). Surface a
+  localized "try again later" / "you're not eligible" message; do not
+  retry automatically.
+- `11005` (`SHOP_FAILED_TO_BUY_MATCHING_BONUS`) — matching-bonus
+  coupon issuance failed (variant of `11002` for matching-deposit
+  bonuses). Funds are NOT debited. Surface a generic error.
+- `11006` (`SHOP_FAILED_MAX_BOUGHT_ITEMS_REACHED`) — per-user purchase
+  cap reached (e.g. "max 1 per day"). Surface the item's
+  `limit_message` if set, otherwise `err_message`. Do not retry.
+- `11007` — bonus was issued but a follow-up redemption step failed
+  server-side. Funds **are** debited and the purchase event is recorded;
+  the consumer's UI should refresh the store list (auto-refresh will
+  fire) and surface a soft warning rather than a hard error.
+- `11009` (`SHOP_FAILED_POOL_EMPTY`) — stock pool is empty / sold out.
+  Show a "sold out" message; auto-refresh will mark the item as such
+  in subsequent `getStoreItems()` updates.
+- `11011` (`SHOP_NO_BALANCE_GEMS`) — insufficient **gems** balance.
+  Same handling as `11000` but for the gems currency.
+- `11012` (`SHOP_NO_BALANCE_DIAMONDS`) — insufficient **diamonds**
+  balance. Same handling as `11000` but for the diamonds currency.
+- `11014` (`SHOP_FAILED_PURCHASE_LIMITATION`) — outside the configured
+  purchase window (purchase weekday / time-of-day / window). Surface
+  the item's `purchase_limit_message` if set, otherwise `err_message`.
+- `9999` — uncaught server exception. Treat as a transient failure;
+  surface a generic error and allow retry.
+- other non-zero — generic server error. Surface `err_message` if any.

package/docs/capabilities/checkSegmentListMatch.md

@@ -0,0 +1,69 @@
+# checkSegmentListMatch — API (TSegmentCheckResult)
+
+> Checks the current user's membership in multiple segments in a single server round-trip — returns a `TSegmentCheckResult[]` with one entry per *unique* segment ID.
+> Import: `import { TSegmentCheckResult } from '@smartico/public-api'`
+> Search terms: checkSegmentListMatch, user, TSegmentCheckResult
+
+## Signature
+```ts
+_smartico.api.checkSegmentListMatch(segment_ids: number[]): Promise<TSegmentCheckResult[]>
+```
+
+## Parameters
+- `segment_ids` — Array of segment IDs to check. Duplicates are silently de-duplicated server-side. Segment IDs are label-scoped — use the IDs configured for your label.
+
+## Returns — `Promise<TSegmentCheckResult[]>`
+Array of `TSegmentCheckResult`. Each item:
+- `segment_id` (number) — The segment ID this result refers to (label-scoped).
+- `is_matching` (boolean) — `true` if the user currently matches this segment. `false` also covers the case where the segment doesn't exist for the label — the two are not distinguishable.
+
+## Behavioral contract
+**Response order is NOT guaranteed**
+The server returns results in an unspecified order — different
+from the input array. Always correlate by the `segment_id` field on
+each `TSegmentCheckResult` rather than by array position. The
+returned array length may also be smaller than the input array
+(duplicate IDs are silently de-duplicated server-side).
+
+**Single round-trip**
+The entire `segment_ids` array is sent in one request. Two segments
+cost the same as one in terms of network latency and rate-limit
+consumption (one call = one rate-limit slot, regardless of how many
+segments).
+
+**Shared semantics with `checkSegmentMatch`**
+Both methods wrap the same underlying server endpoint and share
+the same caching, refresh, rate-limit, and ambiguity behavior. See
+`checkSegmentMatch` for: no client cache · no push event for
+membership changes · behavioral segments have batch lag · rate
+limit (10 requests / 60 s, ~5 s minimum gap between calls) ·
+`is_matching: false` doesn't distinguish "not in segment" from
+"segment doesn't exist for this label".
+
+**Idempotency**: safe. Read-only. No side effects.
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const segmentIds = [vipSegmentId, newPlayerSegmentId, freeRollSegmentId];
+const results = await window._smartico.api.checkSegmentListMatch(segmentIds);
+
+// Always correlate by segment_id — the response order is unspecified.
+const byId = new Map(results.map(r => [r.segment_id, r.is_matching]));
+
+if (byId.get(vipSegmentId)) {
+  console.log('[smartico] user is in VIP segment — render VIP surface');
+}
+if (byId.get(newPlayerSegmentId) && byId.get(freeRollSegmentId)) {
+  console.log('[smartico] new player AND eligible for free roll — show the welcome promo');
+}
+
+// Cache the result map for the session; refresh on material state changes.
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `checkSegmentMatch`

package/docs/capabilities/checkSegmentMatch.md

@@ -0,0 +1,74 @@
+# checkSegmentMatch — API
+
+> Checks whether the current user matches a single segment, returning `true` / `false` directly.
+> Import: `import { /* types */ } from '@smartico/public-api'`
+> Search terms: checkSegmentMatch, user
+
+## Signature
+```ts
+_smartico.api.checkSegmentMatch(segment_id: number): Promise<boolean>
+```
+
+## Parameters
+- `segment_id` — The segment ID. Segment IDs are label-scoped; the same numeric ID can refer to different segments under different labels. Use the IDs configured for your label.
+
+## Returns
+Resolves to `boolean`.
+
+## Behavioral contract
+**Refresh model**
+- **No client cache.** Every call sends a request; the SDK does not
+ memoize results.
+- **No push event** notifies the consumer when segment membership
+ flips (the user crosses a qualification threshold, or the
+ operator changes the segment definition). Membership changes
+ become visible only on the next `checkSegmentMatch` call.
+- **Behavioral segments (configured against BigQuery) have batch
+ lag** — even if the user's activity has changed (deposit, wager,
+ etc.), the segment-membership result may not reflect that change
+ until the next batch evaluation run (typically up to several
+ hours).
+
+**Rate limit** (important)
+The server caps `checkSegment*` calls at **10 requests per
+60-second window**, with a minimum gap of **~5 seconds between
+consecutive calls**. Avoid calling on every render — cache the
+result client-side for the session, or until you have a reason to
+believe the user's state changed (e.g. after a deposit completes,
+a level changes via `getUserProfile`'s `props_change`, or a
+specific custom event fires).
+
+**`is_matching: false` is ambiguous on the server** — both "the
+segment doesn't exist for this label" and "the user doesn't
+qualify" return `false` with no distinguishing signal. Pass IDs
+you've verified are valid for your label.
+
+**Idempotency**: safe. Read-only. No side effects (no analytics
+events, no DB writes).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const isVip = await window._smartico.api.checkSegmentMatch(vipSegmentId);
+if (isVip) {
+  console.log('[smartico] user is in VIP segment — render the VIP-only widget surface');
+} else {
+  console.log('[smartico] user not in VIP segment (or segment id misconfigured) — hide the VIP surface');
+}
+
+// Cache the result for the session; re-check after material user-state changes.
+window._smartico.on('props_change', async (changed) => {
+  if ('ach_points_ever' in changed || 'ach_level_current_id' in changed) {
+    const fresh = await window._smartico.api.checkSegmentMatch(vipSegmentId);
+    console.log('[smartico] user state changed — VIP membership now:', fresh);
+  }
+});
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `checkSegmentListMatch`
+- `getUserProfile`