@smartico/public-api 0.0.380 → 0.0.382

package/docs/api/classes/WSAPIBonuses.md

@@ -3,39 +3,160 @@
 
 ### getBonuses()
 
-> **getBonuses**(`__namedParameters?`): `Promise`\<[`TBonus`](../interfaces/TBonus.md)[]\>
+> **getBonuses**(`params?`): `Promise`\<[`TBonus`](../interfaces/TBonus.md)[]\>
 
-Returns all the bonuses for the current user
-The returned bonuses are cached for 30 seconds. But you can pass the onUpdate callback as a parameter.
-Note that each time you call getBonuses with a new onUpdate callback, the old one will be overwritten by the new one.
-The onUpdate callback will be called on bonus claimed and the updated bonuses will be passed to it.
+Returns the bonuses awarded to the current user — both pending
+(player-claim required) and already-redeemed. Each bonus carries
+a `bonus_status_id` ([BonusStatus](../enumerations/BonusStatus.md)) describing its lifecycle
+stage and an `is_redeemable` flag that signals whether the
+consumer must trigger a manual [claimBonus](#claimbonus) call.
 
-**Visitor mode: not supported**
+Bonuses originate from many sources (CRM rules, mission/tournament
+rewards, store redemptions, mini-game prizes, manual operator
+awards) and all surface through this single list. The consumer
+cannot distinguish the source server-side without operator
+coordination.
 
 #### Parameters
 
-##### \_\_namedParameters?
+##### params?
+
+Optional. Omit to fetch without subscribing.
 
 ###### onUpdate?
 
 (`data`) => `void`
 
+Callback invoked with the full refreshed
+                           bonuses list after every
+                           [claimBonus](#claimbonus) resolves. Each call
+                           to `getBonuses` overwrites the prior
+                           callback.
+
 #### Returns
 
 `Promise`\<[`TBonus`](../interfaces/TBonus.md)[]\>
 
+Promise resolving to the bonuses list.
+                           Empty array if no bonuses are visible.
+
+#### Remarks
+
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed bonuses list (never a
+diff/patch). Each subsequent call to `getBonuses({ onUpdate })`
+REPLACES the prior callback. Pass `onUpdate: undefined` (or omit
+it) to keep the prior callback in place; the callback is never
+auto-cleared.
+
+**Update triggers** — the callback fires after every
+[claimBonus](#claimbonus) call resolves on this connection (success OR
+failure). This is the ONLY trigger.
+
+Does NOT fire when: a new bonus is awarded server-side
+(CRM rule, mission completion, store purchase, etc.), a bonus
+expires, or an operator manually issues / cancels a bonus. Those
+changes surface only on the next cache miss (after the 30 s TTL).
+Re-call `getBonuses()` manually if your UI needs near-live state
+for server-driven awards.
+
+**Reading state from the returned bonus**
+Drive UI bucketing from `bonus_status_id` (enum [BonusStatus](../enumerations/BonusStatus.md)):
+
+- `COUPON_ISSUED` (2) — actionable; player must claim. Pair with
+  `is_redeemable === true` to gate the Claim button.
+- `REDEEM_FAILED` (4) — also actionable; the previous claim
+  attempt failed but the bonus is still valid. Surface a retry CTA
+  — the default Smartico UI treats this identically to
+  `COUPON_ISSUED` from the player's perspective.
+- `REDEEMED` (3) — historical; show in a "claimed" tab.
+- `New` (1), `COUPON_ISSUE_FAILED` (5), `EXPIRED` (6) — these
+  should not normally reach the client and are typically filtered
+  out by operator-side widget configuration; if they do appear,
+  they have no player-actionable state.
+
+`is_redeemable` is the authoritative gate for showing the Claim
+button — it's `true` only when the bonus is in a claimable status
+AND the operator's integration uses a coupon model (where the
+player must explicitly trigger delivery). Auto-redeemed bonuses
+arrive already in `REDEEMED` state with `is_redeemable: false`.
+
+**Field hierarchy — display amount**
+Bonuses carry both template-level (`label_bonus_template_meta_map.description`)
+and instance-level (`bonus_meta_map.uiAmount`) display strings.
+Prefer `bonus_meta_map.uiAmount` when present — it's the dynamic
+amount computed at issuance time (e.g. from a dynamic-bonus
+formula). Fall back to `label_bonus_template_meta_map.description`
+(which can include HTML; sanitize before injecting).
+
+**Date format**
+`create_date` and `redeem_date` are ISO 8601 UTC strings WITHOUT
+a timezone suffix (`"YYYY-MM-DDTHH:MM:SS"`). Parse as UTC and
+display in the user's local timezone. `redeem_date` is absent
+until the bonus reaches `REDEEMED` status.
+
+**Cache TTL**: the SDK caches the response for 30 seconds. Cache
+is fully cleared on login / logout.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getBonuses`](../_media/UIGuide_getBonuses.md).
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+const bonuses = await window._smartico.api.getBonuses({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] bonuses refreshed (after claimBonus) — re-render the bonuses UI from this array:', refreshed);
+  },
+});
+
+// Bucket into pending vs redeemed tabs. The default Smartico UI groups
+// COUPON_ISSUED + REDEEM_FAILED into the same "Pending" tab.
+const pending = bonuses.filter(b =>
+  b.bonus_status_id === 2 || b.bonus_status_id === 4  // COUPON_ISSUED or REDEEM_FAILED
+);
+const redeemed = bonuses.filter(b => b.bonus_status_id === 3);  // REDEEMED
+
+console.log('[smartico] render bonus tabs: pending=', pending.length, 'redeemed=', redeemed.length);
+
+// Render each pending bonus card; show Claim button only when redeemable.
+for (const b of pending) {
+  const amount = b.bonus_meta_map?.uiAmount || b.label_bonus_template_meta_map?.description;
+  if (b.is_redeemable) {
+    console.log('[smartico] render Claim button for bonus', b.bonus_id, '— amount:', amount);
+  } else {
+    console.log('[smartico] render bonus as informational (no Claim button) — amount:', amount);
+  }
+}
+
+// Server-awarded bonuses (e.g. from a CRM campaign) do NOT push;
+// poll if you need near-live awareness.
+setInterval(async () => {
+  const fresh = await window._smartico.api.getBonuses();
+  const newCount = fresh.filter(b => b.bonus_status_id === 2 || b.bonus_status_id === 4).length;
+  console.log('[smartico] poll tick — pending bonuses now:', newCount);
+}, 30_000);
+```
+
 ***
 
 ### claimBonus()
 
 > **claimBonus**(`bonus_id`): `Promise`\<[`TClaimBonusResult`](../interfaces/TClaimBonusResult.md)\>
 
-Claim the bonus by bonus_id. Returns the err_code in case of success or error.
-Note that this method can be used only on integrations where originally failed bonus can be claimed again.
-For example, user won a bonus in the mini-game, but Operator rejected this bonus.
-This bonus will be available for the user to claim again.
+Triggers manual redemption of a coupon-model bonus the user has
+been awarded. For bonuses with `is_redeemable === true` returned
+by [getBonuses](#getbonuses), this is the call that asks the operator's
+integration to actually credit the bonus to the player's account.
+Bonuses on integrations that auto-redeem arrive already in
+`REDEEMED` state and do not require this call.
 
-**Visitor mode: not supported**
+Use this for `bonus_status_id` of `COUPON_ISSUED` (2) as the
+first-time claim, and for `REDEEM_FAILED` (4) as a retry after a
+prior unsuccessful attempt.
 
 #### Parameters
 
@@ -43,8 +164,108 @@ This bonus will be available for the user to claim again.
 
 `number`
 
+The `bonus_id` from a `TBonus` returned by
+                 [getBonuses](#getbonuses).
+
 #### Returns
 
 `Promise`\<[`TClaimBonusResult`](../interfaces/TClaimBonusResult.md)\>
 
+`{ err_code, err_message, success? }`; success when
+         `err_code === 0` (or `err_code === -1` when treated as
+         idempotent no-op). The `success` field is unreliable —
+         ignore it.
+
+#### Remarks
+
+**Preconditions**
+Read the candidate bonus from [getBonuses](#getbonuses) and gate the
+call on `is_redeemable === true`. The SDK forwards the request
+unconditionally — calling on a non-claimable bonus returns
+`err_code = -1`.
+
+**Error codes** (in `err_code`)
+
+The SDK currently types `err_code` as [SAWSpinErrorCode](../enumerations/SAWSpinErrorCode.md) for
+historical reasons, but the values returned by this method come
+from the server's general error space and are NOT mini-game codes.
+Branch on the numeric values:
+
+- `0` — success; the bonus has been redeemed and the operator's
+  integration has credited the player's account.
+- `-1` — bonus not claimable: not found, already claimed by
+  another session, or its status is no longer `COUPON_ISSUED` /
+  `REDEEM_FAILED`. Treat as idempotent — refresh
+  [getBonuses](#getbonuses) and reconcile.
+- `1` — generic server error. Transient; allow retry after a brief
+  delay.
+- `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.
+
+**`success` field is unreliable**: the wire response does not
+carry a `success` boolean — the field on `TClaimBonusResult` will
+be `undefined` in practice. Always branch on `err_code === 0`
+for the success check.
+
+**Refresh after success (and after failure)**
+The SDK automatically refreshes the bonuses cache on every
+response (success OR failure) and fires any `onUpdate` callback
+registered via [getBonuses](#getbonuses)'s `onUpdate`. After
+`err_code === 0`, the redeemed bonus shifts from
+`COUPON_ISSUED` / `REDEEM_FAILED` to `REDEEMED` on the refreshed
+array, with `redeem_date` populated. After a failure, the bonus
+typically lands in `REDEEM_FAILED` and remains claimable for a
+retry.
+
+**Idempotency**: NOT idempotent at the SDK level. A second call
+returns `err_code = -1` once the first has succeeded — treat that
+as success in the UI rather than as a real error. Guard the call
+site against double-clicks (set a local "claiming" flag on click,
+clear it on response).
+
+**Side effects** (on `err_code === 0`)
+- Bonus status transitions to `REDEEMED`; `redeem_date` is set.
+- The operator's integration credits the player's account
+  externally. The SDK does not observe that credit directly —
+  balance updates flow over the user-properties channel from the
+  operator's side, not from this response.
+- Server-side analytics events fire downstream (not directly
+  observable from the SDK).
+
+**UI guidance**: see [UI Guide — `claimBonus`](../_media/UIGuide_claimBonus.md).
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+const bonuses = await window._smartico.api.getBonuses({
+  onUpdate: (refreshed) => console.log('[smartico] bonuses refreshed — re-render from this array', refreshed),
+});
+const bonus = bonuses.find(b => b.bonus_id === bonusId);
+
+if (!bonus) {
+  console.log('[smartico] bonus no longer visible — refresh list and hide CTA');
+  return;
+}
+if (!bonus.is_redeemable) {
+  console.log('[smartico] bonus is not claimable (auto-redeemed or already finalised) — keep CTA hidden');
+  return;
+}
+
+console.log('[smartico] claim starting — set in-flight flag, show loading dots on the Claim button, keep the modal open');
+const r = await window._smartico.api.claimBonus(bonus.bonus_id);
+console.log('[smartico] claim response received — clear in-flight flag');
+
+if (r.err_code === 0 || r.err_code === -1) {
+  console.log('[smartico] claim succeeded (or was already done) — show a success toast; the getBonuses onUpdate above will fire with the refreshed list');
+} else if (r.err_code === 9999) {
+  console.error('[smartico] uncaught server exception — show a generic error toast and allow retry');
+} else {
+  console.error('[smartico] claim failed — surface this error message to the user; the bonus will move to REDEEM_FAILED state and remain claimable for a retry:', r.err_message);
+}
+```
+
 ***