@smartico/public-api 0.0.402 → 0.0.404

package/docs/capabilities/joinClan.md

@@ -0,0 +1,169 @@
+# joinClan — API (TClanJoinResult)
+
+> Joins (or switches into) a clan on behalf of the current user.
+> Import: `import { TClanJoinResult } from '@smartico/public-api'`
+> Search terms: joinClan, clans, TClanJoinResult
+
+## Signature
+```ts
+_smartico.api.joinClan(clanId: number): Promise<TClanJoinResult>
+```
+
+## Parameters
+- `clanId` — The clan ID from `TClans.clans[i].clan_id` (or `TClanInfo.clan_id`).
+
+## Returns — `Promise<TClanJoinResult>`
+`TClanJoinResult`:
+- `errCode` (number) — Error code. `0` = success. Typed values are members of `JoinClanErrorCode`. See `joinClan` TSDoc for the full table and per-code UI guidance.
+- `errMsg` (string) — Optional server-side error message. Present only on non-zero `errCode`; may be empty even then.
+
+## Behavioral contract
+**Result shape note**: `TClanJoinResult` uses `errCode` / `errMsg`
+(camelCase) — different from most other SDK result types in this
+library which use `err_code` / `err_message` (snake_case). Branch
+on the camelCase keys when reading this method's result.
+
+**Preconditions**
+Read the candidate from `getClans` and gate the call on
+`clan.member_count < clan.capacity_limit`, `cooldown_until == null`
+(on the `TClans` payload — the cooldown is user-level, not
+per-clan), and the user's balance for `entry_fee_currency_type_id`
+being at least `entry_fee_amount` (free clans bypass this check).
+The SDK forwards the call unconditionally — calling without
+satisfying these will most likely return one of the error codes
+below.
+
+
+
+**Idempotency**: NOT safe — and notably dangerous. Calling
+`joinClan` with the user's CURRENT `clanId` does NOT short-circuit
+server-side; the call is treated as a clan-switch to the same
+clan. If the label's cooldown is non-zero (the default), the
+second call returns `1006`. If the cooldown is configured to
+zero, the second call will deduct the entry fee AGAIN, deactivate
+the membership, and re-insert it. The SDK does NOT enforce an
+in-flight lock. Consumers MUST guard the call site against
+double-clicks (set a local "joining" flag on click, clear it on
+response) AND short-circuit when the user is already in the
+target clan.
+
+**Refresh after success (and after failure)**
+The SDK does NOT automatically refresh the `getClans` cache
+after a join. Manually re-call `getClans()` on success to pick up
+the new `user_clan_id`, refreshed `member_count`, and the new
+`cooldown_until` value. Until you do, the cached `TClans` payload
+is stale.
+
+**Side effects** (consumer-observable on success)
+- Entry-fee currency balance decreases by `entry_fee_amount`
+ (visible on the next `getUserProfile` refresh / via the
+ user-properties update channel).
+- The user's clan membership row is created (or replaced, on a
+ switch). `member_count` on the new clan increments by 1; on a
+ switch, the old clan's `member_count` decrements by 1 in the
+ same transaction.
+- The user's switch-cooldown restarts at the join time (the
+ `TClans.cooldown_until` field on the next list fetch reflects
+ the new expiry).
+- Server-side CRM analytics fire (clan-joined event, currency-
+ deducted event for paid clans). These surface only as
+ server-side traces; the SDK consumer observes them indirectly
+ via balance / membership refresh.
+
+**UI guidance**: see [UI Guide — `joinClan`](../../docs/ui/clans/UIGuide_joinClan.md).
+
+**Visitor mode**: not supported. The server rejects the request
+for unauthenticated sessions.
+
+## Example
+```ts
+const result = await window._smartico.api.getClans();
+const target = result.clans.find(c => c.clan_id === clanId);
+
+if (!target) {
+  console.log('[smartico] clan not in current list — refresh getClans and retry');
+  return;
+}
+if (target.clan_id === result.user_clan_id) {
+  console.log('[smartico] user is already in this clan — short-circuit; do NOT call joinClan again, the server will treat it as a switch and may re-deduct the fee');
+  return;
+}
+if (result.cooldown_until) {
+  console.log('[smartico] user is in cooldown — disable Join until', new Date(result.cooldown_until + 'Z').toLocaleString());
+  return;
+}
+if (target.member_count >= target.capacity_limit) {
+  console.log('[smartico] clan is full — disable Join');
+  return;
+}
+
+console.log('[smartico] join starting — set in-flight flag, show loading dots on Join button, keep modal open');
+const r = await window._smartico.api.joinClan(target.clan_id);
+console.log('[smartico] join response received — clear in-flight flag');
+
+if (r.errCode === 0) {
+  console.log('[smartico] joined successfully — refresh getClans to pick up the new user_clan_id, member_count, and cooldown_until');
+  await window._smartico.api.getClans();
+} else if (r.errCode === 1002) {
+  console.error('[smartico] clan is full — refresh list, hide the Join CTA on the now-full clan');
+} else if (r.errCode === 1003) {
+  const currencyLabel = ['points', 'gems', 'diamonds'][target.entry_fee_currency_type_id] ?? 'currency';
+  console.error('[smartico] insufficient', currencyLabel, '— need', target.entry_fee_amount);
+} else if (r.errCode === 1004) {
+  console.error('[smartico] user does not meet segment / entry conditions — show a gating message');
+} else if (r.errCode === 1006) {
+  console.error('[smartico] cooldown active — surface the cooldown_until from getClans:', result.cooldown_until);
+} else if (r.errCode === 1001) {
+  console.error('[smartico] clan not found or archived — refresh list and remove from UI');
+} else {
+  console.error('[smartico] join failed — show a generic error toast with this message:', r.errMsg);
+}
+```
+
+## Errors
+**Error codes** (in `errCode`, typed as `JoinClanErrorCode`)
+- `0` (`JOIN_CLAN_OK`) — success; membership persisted, fee
+ debited, cooldown restarted.
+- `1000` (`JOIN_CLAN_INVALID_PARAMETERS`) — request body missing
+ `clan_id`. Should not occur via the SDK; treat as a programming
+ error.
+- `1001` (`JOIN_CLAN_NOT_FOUND`) — clan doesn't exist for this
+ label, OR the clan is archived / in draft state. The server
+ merges "missing" and "archived" into this single code. Refresh
+ `getClans()` and remove the entry from the UI.
+- `1002` (`JOIN_CLAN_FULL`) — capacity reached between the list
+ fetch and the join click (`member_count >= capacity_limit` at
+ the server's atomic check). Refresh the list — the button will
+ become "Clan is full".
+- `1003` (`JOIN_CLAN_INSUFFICIENT_FUNDS`) — insufficient balance
+ for the clan's entry fee. A single code covers all three
+ currencies (points / gems / diamonds); read
+ `clan.entry_fee_currency_type_id` to identify which currency
+ the user is short on. Show an insufficient-balance UI naming
+ the deficit.
+- `1004` (`JOIN_CLAN_SEGMENT_MISMATCH`) — user does not meet the
+ clan's entry segment or numeric conditions. There is no
+ client-side pre-guard for this — surface a gating message.
+- `1005` (`JOIN_CLAN_USER_IS_NOT_IN_CLAN`) — this method NEVER
+ returns `1005`. The code is shared with the tournament
+ registration error space and fires only on
+ `registerInTournament` responses when a clan-based
+ tournament requires the user to be in a clan first.
+- `1006` (`JOIN_CLAN_COOLDOWN_ACTIVE`) — user is inside the
+ switch-cooldown window from a previous clan join (default
+ 7 days, configurable per label). Only reachable when the user is
+ already in a *different* clan (this call is then a clan switch);
+ a first-time join never returns `1006`. Surface the
+ `TClans.cooldown_until` expiry in the disabled CTA.
+- `1011` (`JOIN_CLAN_JOINED_AFTER_TOURNAMENT_START`) — this
+ method does NOT return `1011` directly. The code fires on
+ `registerInTournament` responses when the user joined
+ their current clan after the tournament started AND already
+ has tournament scores.
+- other non-zero — generic server error. Surface `errMsg` if any.
+
+## Related
+- `getClans`
+- `JoinClanErrorCode`
+- `registerInTournament`
+- `getUserProfile`

package/docs/capabilities/markAllInboxMessagesAsRead.md

@@ -0,0 +1,72 @@
+# markAllInboxMessagesAsRead — API (InboxMarkMessageAction)
+
+> Marks ALL of the user's inbox messages as read in one server round-trip — typically wired to a "Mark all as read" CTA in the inbox header.
+> Import: `import { InboxMarkMessageAction } from '@smartico/public-api'`
+> Search terms: markAllInboxMessagesAsRead, inbox, InboxMarkMessageAction, err_code, err_message
+
+## Signature
+```ts
+_smartico.api.markAllInboxMessagesAsRead(): Promise<InboxMarkMessageAction>
+```
+
+## Parameters
+_None._
+
+## Returns — `Promise<InboxMarkMessageAction>`
+`InboxMarkMessageAction`:
+- `err_code` (number) — Error code. `0` = success. See the calling method's TSDoc for the full error semantics (server returns generic codes; the five inbox mutations share the same shape).
+- `err_message` (string) — Optional server-side error message. Present only on non-zero `err_code`; may be empty even then.
+
+## Behavioral contract
+**Race condition note**: a new message arriving server-side
+between the call and its processing remains unread (the
+server's mark-all operation is a snapshot in time). Subsequent
+`getInboxMessages` calls show the new message as unread.
+
+**Refresh after success**
+Same as `markInboxMessageAsRead` — `getInboxMessages`
+`onUpdate` does NOT fire automatically, but the unread-count
+channel does (the badge will drop to 0, or to the count of any
+new messages that arrived during processing).
+
+**Idempotency**: safe. A second call on an already-all-read
+inbox returns `err_code === 0` with no-op effect.
+
+**Side effects** (on success)
+- Every unread message flipped to read.
+- `core_inbox_unread_count` drops to 0 (or near 0 if races).
+
+**UI guidance**: included in the
+[UI Guide — `markInboxMessageAsRead`](../../docs/ui/inbox/UIGuide_markInboxMessageAsRead.md)
+(Bulk variant section).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+console.log('[smartico] mark-all-read starting — set in-flight flag on the "Mark all read" button, show loading dots');
+const r = await window._smartico.api.markAllInboxMessagesAsRead();
+console.log('[smartico] mark-all-read response — clear in-flight flag');
+if (r.err_code === 0) {
+  console.log('[smartico] all messages marked read — optimistically flip every local read indicator; badge auto-drops via user-properties channel');
+} else {
+  console.error('[smartico] mark-all failed — surface a non-blocking error:', 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": 0,
+  "err_message": ""
+}
+```
+
+## Errors
+**Error codes** (in `err_code`)
+- `0` — success; all currently-unread messages flipped to read.
+- other non-zero — server error. Surface `err_message` if any.
+
+## Related
+- `markInboxMessageAsRead`

package/docs/capabilities/markInboxMessageAsRead.md

@@ -0,0 +1,69 @@
+# markInboxMessageAsRead — API (InboxMarkMessageAction)
+
+> Marks a single inbox message as read.
+> Import: `import { InboxMarkMessageAction } from '@smartico/public-api'`
+> Search terms: markInboxMessageAsRead, inbox, InboxMarkMessageAction, err_code, err_message
+
+## Signature
+```ts
+_smartico.api.markInboxMessageAsRead(messageGuid: string): Promise<InboxMarkMessageAction>
+```
+
+## Parameters
+- `messageGuid` — The `message_guid` from a `TInboxMessage`.
+
+## Returns — `Promise<InboxMarkMessageAction>`
+`InboxMarkMessageAction`:
+- `err_code` (number) — Error code. `0` = success. See the calling method's TSDoc for the full error semantics (server returns generic codes; the five inbox mutations share the same shape).
+- `err_message` (string) — Optional server-side error message. Present only on non-zero `err_code`; may be empty even then.
+
+## Behavioral contract
+**Refresh after success**
+The SDK does NOT auto-refresh `getInboxMessages` (no
+`onUpdate` callback fires after this mutation). The unread-count
+channel (`getInboxUnreadCount`, `core_inbox_unread_count`)
+DOES auto-update — subscribers to it see the new count
+automatically. If your inbox list UI shows the `read` field, you
+have two options: re-call `getInboxMessages` after the mutation,
+or update the local copy optimistically.
+
+**Idempotency**: safe. Repeated calls return `err_code === 0`.
+
+**Side effects** (on success)
+- Server-side `is_read` flag set to true.
+- Server-side `core_inbox_unread_count` decremented (if the
+ message was previously unread).
+
+**UI guidance**: see [UI Guide — `markInboxMessageAsRead`](../../docs/ui/inbox/UIGuide_markInboxMessageAsRead.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+const r = await window._smartico.api.markInboxMessageAsRead(message.message_guid);
+if (r.err_code === 0) {
+  console.log('[smartico] marked as read — optimistically flip the local read indicator; the inbox badge auto-decrements via the user-properties channel');
+} else {
+  console.error('[smartico] mark-as-read failed — keep the local state as-is and show a non-blocking error if appropriate:', 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": 0,
+  "err_message": ""
+}
+```
+
+## Errors
+**Error codes** (in `err_code`)
+- `0` — success; the message is now marked read. Idempotent — a
+ second call on the same `messageGuid` also returns `0`.
+- other non-zero — server error. Surface `err_message` if any.
+
+## Related
+- `getInboxUnreadCount`
+- `getUserProfile`
+- `getInboxMessages`

package/docs/capabilities/markUnmarkInboxMessageAsFavorite.md

@@ -0,0 +1,75 @@
+# markUnmarkInboxMessageAsFavorite — API (InboxMarkMessageAction)
+
+> Toggles a message's favorite (starred) state — pass `mark: true` to favorite, `mark: false` to unfavorite.
+> Import: `import { InboxMarkMessageAction } from '@smartico/public-api'`
+> Search terms: markUnmarkInboxMessageAsFavorite, inbox, InboxMarkMessageAction, err_code, err_message
+
+## Signature
+```ts
+_smartico.api.markUnmarkInboxMessageAsFavorite(messageGuid: string, mark: boolean): Promise<InboxMarkMessageAction>
+```
+
+## Parameters
+- `messageGuid` — The `message_guid` from a `TInboxMessage`.
+- `mark` — `true` to favorite, `false` to unfavorite.
+
+## Returns — `Promise<InboxMarkMessageAction>`
+`InboxMarkMessageAction`:
+- `err_code` (number) — Error code. `0` = success. See the calling method's TSDoc for the full error semantics (server returns generic codes; the five inbox mutations share the same shape).
+- `err_message` (string) — Optional server-side error message. Present only on non-zero `err_code`; may be empty even then.
+
+## Behavioral contract
+**Refresh after success**
+The SDK does NOT auto-refresh `getInboxMessages`. To
+reflect the new state in the UI, update the local copy of the
+affected `TInboxMessage` (set `favorite` to the new value) or
+re-call `getInboxMessages`.
+
+**Idempotency**: safe. `mark: true` on an already-favorite
+message returns `err_code === 0` (no-op). Same for `mark: false`
+on a non-favorite.
+
+**Side effects** (on success)
+- Server-side `is_starred` flag set to the requested value.
+- No effect on read state, unread count, or other fields.
+
+**UI guidance**: see [UI Guide — `markUnmarkInboxMessageAsFavorite`](../../docs/ui/inbox/UIGuide_markUnmarkInboxMessageAsFavorite.md).
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+// Toggle handler — flip the local state optimistically, then
+// call the server, and revert if the call fails.
+const target = !message.favorite;
+console.log('[smartico] optimistically flip the star to', target, '— it will revert if the server rejects');
+
+const r = await window._smartico.api.markUnmarkInboxMessageAsFavorite(
+  message.message_guid,
+  target,
+);
+
+if (r.err_code === 0) {
+  console.log('[smartico] favorite toggled — keep the local state and show a brief "Added to favorites" / "Removed from favorites" toast');
+} else {
+  console.error('[smartico] favorite toggle failed — revert the local state and show an error toast:', 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": 0,
+  "err_message": ""
+}
+```
+
+## Errors
+**Error codes** (in `err_code`)
+- `0` — success; the message's favorite state flipped to the
+ requested value.
+- other non-zero — server error. Surface `err_message` if any.
+
+## Related
+- `getInboxMessages`

package/docs/capabilities/miniGameWinAcknowledgeRequest.md

@@ -0,0 +1,98 @@
+# miniGameWinAcknowledgeRequest — API
+
+> Manually acknowledges a mini-game spin — marks the win delivered server-side.
+> Import: `import { /* types */ } from '@smartico/public-api'`
+> Search terms: miniGameWinAcknowledgeRequest, minigames, doSAWAcknowledge, SAWAcknowledge, acknowledge, SAWAcknowledgeType, request_id, errCode, errMsg, cid, ts, uuid, payload, duration
+
+## Signature
+```ts
+_smartico.api.miniGameWinAcknowledgeRequest(request_id: string): void
+```
+
+## Parameters
+- `request_id` — Correlation id of the spin to finalise: the `request_id` from a `playMiniGame` result (played with `acknowledge: false`), or the `client_request_id` of a `getMiniGamesHistory` row.
+
+## Returns
+_No return value._
+
+## Behavioral contract
+**When to call**
+- **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.** `playMiniGameBatch`
+ acknowledges on a fire-and-forget basis; if one is lost (network
+ drop) the spin shows `is_claimed: false` in
+ `getMiniGamesHistory`. Pass that row's `client_request_id`
+ to deliver it.
+
+The `request_id` on a `playMiniGame` result and the
+`client_request_id` on a `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 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
+`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 `playMiniGame` "Prize handling"); this call only
+ marks the win delivered.
+- The spin's `is_claimed` flips to `true` on the next
+ `getMiniGamesHistory` fetch.
+
+**Visitor mode**: not supported.
+
+## Example
+```ts
+// 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);
+}
+
+// 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);
+}
+```
+
+### 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
+{
+  "request_id": "00000000-0000-0000-0000-000000000000",
+  "errCode": 0,
+  "errMsg": "",
+  "cid": 705,
+  "ts": 1782287011139,
+  "uuid": "00000000-0000-0000-0000-000000000000",
+  "payload": null,
+  "duration": null
+}
+```
+
+## Errors
+See this method's TSDoc / the mutation pages for `err_code` handling.
+
+## Related
+- `playMiniGame`
+- `playMiniGameBatch`
+- `getMiniGamesHistory`