@smartico/public-api 0.0.380 → 0.0.381

package/docs/api/classes/WSAPIInbox.md

@@ -3,174 +3,402 @@
 
 ### reportImpressionEvent()
 
-> **reportImpressionEvent**(`params`): `void`
+> **reportImpressionEvent**(`__namedParameters`): `void`
 
-Reports an impression event for an engagement (when engagement content is displayed to the user).
-Use this method to track when users view engagement content such as inbox messages, popups.
-When using for Inbox cases, you need to use message guid as engagement_uid, and pass 31 as activityType.
+Records that an engagement (inbox message, popup) was displayed to
+the user. Use this to drive engagement analytics — every visible
+inbox message should fire one impression event per render
+occurrence, and every popup display should fire one.
 
-**Example**:
-```
-_smartico.api.reportImpressionEvent({
-     engagement_uid: 'abc123-def456',
-     activityType: 31 // Inbox
-});
-```
-
-**Visitor mode: not supported**
+**Fire-and-forget**: the call is asynchronous and one-way — there
+is no response promise to await and no error reporting. The SDK
+swallows transport failures silently. Returns `void`.
 
 #### Parameters
 
-##### params
-
-Event parameters
+##### \_\_namedParameters
 
 ###### engagement_uid
 
 `string`
 
-Unique identifier for the engagement
+For inbox: the message's `message_guid` from `getInboxMessages`. For popups: the popup's GUID from the popup display callback.
 
 ###### activityType
 
 `number`
 
-Type of engagement activity (Popup=30, Inbox=31)
+`ActivityTypeLimited.Inbox` (`31`) for inbox; `Popup` (`30`) for popups.
 
 #### Returns
 
 `void`
 
-***
+#### Remarks
 
-### reportClickEvent()
+**When to call**
+- Inbox: when a message becomes visible (the user opens / scrolls
+  it into view). The default Smartico UI fires this when the
+  message detail expands, alongside
+  [markInboxMessageAsRead](#markinboxmessageasread).
+- Popup: when the popup content is shown to the user.
 
-> **reportClickEvent**(`params`): `void`
+**Activity types**
+Pass [ActivityTypeLimited.Inbox](../enumerations/ActivityTypeLimited.md#inbox) (`31`) for inbox messages,
+[ActivityTypeLimited.Popup](../enumerations/ActivityTypeLimited.md#popup) (`30`) for popups. Other values
+are not used by the engagement-impression channel.
 
-Reports a click/action event for an engagement (when user interacts with engagement content).
-Use this method to track when users click on or interact with engagement content such as inbox messages, popups.
-When using for Inbox cases, you need to use message guid as engagement_uid, and pass 31 as activityType, and pass the action/deeplink that was triggered by the user interaction as action.
+**Idempotency**: the server records every impression event —
+repeated calls add to the impression count. Don't fire it on
+every re-render; fire it once per logical "display" event
+(modal open, list-row scroll-into-view, popup show).
 
-**Example**:
-```
-_smartico.api.reportClickEvent({
-     engagement_uid: 'abc123-def456',
-     activityType: 31 // Inbox
-     action: 'dp:gf_missions'
+**Side effects**: server-side increments the engagement's
+`impression_count` and updates `last_impression_date`. The
+counter is observable via operator analytics; the SDK consumer
+receives no signal back.
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+// When the user opens an inbox message in the detail view.
+window._smartico.api.reportImpressionEvent({
+  engagement_uid: message.message_guid,
+  activityType: 31,  // ActivityTypeLimited.Inbox
 });
+console.log('[smartico] inbox impression reported for', message.message_guid, '— no response to await, fire-and-forget');
 ```
 
-**Visitor mode: not supported**
+***
+
+### reportClickEvent()
 
-#### Parameters
+> **reportClickEvent**(`__namedParameters`): `void`
 
-##### params
+Records that the user interacted with an engagement — typically
+tapping a CTA button, following a deep-link, or clicking a popup
+action. Use this to drive engagement analytics on what users
+actually act on (vs what they merely see —
+[reportImpressionEvent](#reportimpressionevent)).
 
-Event parameters
+**Fire-and-forget**: the call is asynchronous and one-way — there
+is no response promise to await and no error reporting. The SDK
+swallows transport failures silently. Returns `void`.
+
+#### Parameters
+
+##### \_\_namedParameters
 
 ###### engagement_uid
 
 `string`
 
-Unique identifier for the engagement
+For inbox: the message's `message_guid` from `getInboxMessages`.
 
 ###### activityType
 
 `number`
 
-Type of engagement activity (Popup=30, Inbox=31)
+`ActivityTypeLimited.Inbox` (`31`) for inbox; `Popup` (`30`) for popups.
 
 ###### action?
 
 `string`
 
-Optional action/deeplink that was triggered by the user interaction
+The deep-link / URL the user triggered (optional but recommended for analytics fidelity).
 
 #### Returns
 
 `void`
 
+#### Remarks
+
+**When to call**
+- Inbox: when the user taps a CTA button on a message or follows
+  a deep-link inside the message body. Pass the deep-link or URL
+  as `action`.
+- Popup: when the user clicks a popup action button.
+
+**Activity types**
+Pass [ActivityTypeLimited.Inbox](../enumerations/ActivityTypeLimited.md#inbox) (`31`) for inbox,
+[ActivityTypeLimited.Popup](../enumerations/ActivityTypeLimited.md#popup) (`30`) for popups.
+
+**`action` payload**
+Pass the deep-link or URL that the user triggered (e.g.
+`'dp:gf_missions'`, `'https://example.com/promo'`). The SDK
+forwards the string to the server for analytics — it does not
+execute the deep-link. To execute deep-links safely, call
+`_smartico.dp(action)` separately.
+
+**Idempotency**: the server records every click event —
+repeated calls add to the count. Fire once per logical user
+action.
+
+**Side effects**: server-side updates the engagement's
+`last_action` field; observable via operator analytics. The SDK
+consumer receives no signal back.
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+// When the user taps a CTA button in an inbox message.
+window._smartico.api.reportClickEvent({
+  engagement_uid: message.message_guid,
+  activityType: 31,  // ActivityTypeLimited.Inbox
+  action: 'dp:gf_missions',
+});
+window._smartico.dp('dp:gf_missions');   // separately execute the deep-link
+```
+
 ***
 
 ### getInboxMessages()
 
 > **getInboxMessages**(`params?`): `Promise`\<[`TInboxMessage`](../interfaces/TInboxMessage.md)[]\>
 
-Returns inbox messages based on the provided parameters. "From" and "to" indicate the range of messages to be fetched.
-The maximum number of messages per request is limited to 20. 
-An indicator "onlyFavorite" can be passed to get only messages marked as favorites.
-An indicator "read_status" can be passed to get only messages marked as read or unread.
-You can leave this params empty and by default it will return list of messages ranging from 0 to 20.
-This function returns a list of messages without the body of each message.
-To get the body of the message you need to call getInboxMessageBody function and pass the message guid contained in each message of this request.
-All other action like mark as read, favorite, delete, etc. can be done using this message GUID.
-The "onUpdate" callback will be triggered when the user receives a new message. It will provide an updated list of messages, ranging from 0 to 20, to the onUpdate callback function.
+Returns the user's inbox messages — newest first — with optional
+filtering by category, favorite status, and read state. Each
+`TInboxMessage` is a lightweight envelope (`message_guid`,
+`sent_date`, `read`, `favorite`, `category_id`, `expire_on_dt`);
+fetch the rich body (title, preview, icon, html_body, buttons)
+separately via [getInboxMessageBody](#getinboxmessagebody).
 
-**Visitor mode: not supported**
+Use this to power an inbox list screen. Subscribe via `onUpdate`
+to react to newly-arrived messages pushed by the server (from
+campaigns, automation rules, manual operator sends).
 
 #### Parameters
 
 ##### params?
 
+Optional filters + subscription.
+
 ###### from?
 
 `number`
 
+First message index (0-based). Defaults
+                           to `0`.
+
 ###### to?
 
 `number`
 
+Last message index (exclusive).
+                           Defaults to `20`. Server caps the page
+                           at 20.
+
 ###### onlyFavorite?
 
 `boolean`
 
+When `true`, returns only favorite
+                           (starred) messages.
+
 ###### categoryId?
 
 [`InboxCategories`](../enumerations/InboxCategories.md)
 
+When set, returns only messages in this
+                           category ([InboxCategories](../enumerations/InboxCategories.md)).
+
 ###### read_status?
 
 [`InboxReadStatus`](../enumerations/InboxReadStatus.md)
 
+When set, scopes to read or unread
+                           only ([InboxReadStatus](../enumerations/InboxReadStatus.md)).
+
 ###### onUpdate?
 
 (`data`) => `void`
 
+Callback invoked with the full
+                           refreshed list when a new message
+                           arrives.
+
 #### Returns
 
 `Promise`\<[`TInboxMessage`](../interfaces/TInboxMessage.md)[]\>
 
+Promise resolving to up to 20 `TInboxMessage` envelopes.
+         Empty array when the user has no messages matching the
+         filter.
+
+#### Remarks
+
+**Subscription model (`onUpdate`)**
+The callback receives the FULL refreshed message list (never a
+diff/patch). Each subsequent call to `getInboxMessages({ 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 ONLY when:
+
+1. A new message is pushed by the server (campaign / automation /
+   operator send). The refreshed list includes the new message
+   at the top.
+
+Does NOT fire for: `markInboxMessageAsRead`,
+`markAllInboxMessagesAsRead`,
+`markUnmarkInboxMessageAsFavorite`, `deleteInboxMessage`,
+`deleteAllInboxMessages`. After a mutation, re-call
+`getInboxMessages` manually if your UI needs the refreshed list
+— or maintain optimistic state locally.
+
+**Pagination**
+`from` (defaults to `0`) and `to` (defaults to `20`) define a
+half-open range of message indices. The server caps the page at
+**20 messages per request** — passing `to - from > 20` silently
+truncates to 20. For "load more" pagination, advance `from` by
+the prior page size on each subsequent call.
+
+**Filters**
+All filters are ANDed server-side. Omitting a filter means "no
+constraint" on that dimension:
+- `categoryId` ([InboxCategories](../enumerations/InboxCategories.md)): `General` (0),
+  `Platform` (1), `Personal` (2). Omit to get all categories.
+- `onlyFavorite: true` returns only starred messages.
+  Omit / `false` returns all (starred and not).
+- `read_status` ([InboxReadStatus](../enumerations/InboxReadStatus.md)): `UnreadOnly` (1) or
+  `ReadOnly` (2). Omit to get both.
+
+**Server-side filtering** (always applied)
+Expired messages (`expire_on_dt` in the past) and
+soft-deleted messages are excluded server-side. Consumers do not
+need to filter for these.
+
+**No client cache**: every call sends a fresh server round-trip.
+To avoid redundant fetches in your UI, hold the result in
+application state and re-fetch on `onUpdate` fires or explicit
+user-driven refresh.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**UI guidance**: see [UI Guide — `getInboxMessages`](../_media/UIGuide_getInboxMessages.md).
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+const messages = await window._smartico.api.getInboxMessages({
+  onUpdate: (refreshed) => {
+    console.log('[smartico] new inbox message arrived — re-render the list from this array, new message is at index 0:', refreshed);
+  },
+});
+
+// For each message, fetch its body for the list view (title, preview, icon).
+for (const msg of messages) {
+  const body = await window._smartico.api.getInboxMessageBody(msg.message_guid);
+  console.log('[smartico] render message', msg.message_guid,
+    '— title:', body.title,
+    '— preview:', body.preview_body,
+    '— read:', msg.read,
+    '— favorite:', msg.favorite);
+}
+
+// "Load more" pagination — advance from by the prior page size.
+const page2 = await window._smartico.api.getInboxMessages({ from: 20, to: 40 });
+console.log('[smartico] page 2:', page2.length, 'messages');
+
+// Filter examples.
+const onlyStarred = await window._smartico.api.getInboxMessages({ onlyFavorite: true });
+const onlyUnread = await window._smartico.api.getInboxMessages({ read_status: 1 });  // InboxReadStatus.UnreadOnly
+```
+
 ***
 
 ### getInboxUnreadCount()
 
 > **getInboxUnreadCount**(`params?`): `Promise`\<`number`\>
 
-Returns inbox unread count.
+Returns the user's current unread inbox message count — a single
+integer suitable for driving a header badge. Optionally subscribe
+to live updates via `onUpdate`.
 
-**Visitor mode: not supported**
+For most UIs, prefer `core_inbox_unread_count` from
+[getUserProfile](WSAPIUser.md#getuserprofile) instead: it carries the same value, is
+push-updated in real time via the user-properties channel, and
+doesn't require a separate cache. This method is useful when you
+want a dedicated subscription tied to the inbox surface rather
+than the broader user-properties channel.
 
 #### Parameters
 
 ##### params?
 
+Optional subscription bag.
+
 ###### onUpdate?
 
 (`unread_count`) => `void`
 
+Callback invoked with the new unread
+                        count whenever it changes (push-driven).
+
 #### Returns
 
 `Promise`\<`number`\>
 
+Promise resolving to the current unread
+                        count (integer, includes `0`).
+
+#### Remarks
+
+**Subscription model**
+`onUpdate` fires whenever the cached value changes — either on a
+push from the user-properties channel (new message arrival,
+mark-as-read, delete) or after an inbox-list fetch that returns
+a fresh count.
+
+**Cache TTL**: 30 seconds. The cached value is patched in place
+by push events (no full re-fetch on every push), so the
+`onUpdate` callback reflects server state with sub-second latency
+regardless of the TTL.
+
+**Idempotency / Side effects**: safe. Read-only.
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+// Static read for an initial badge render.
+const count = await window._smartico.api.getInboxUnreadCount();
+console.log('[smartico] inbox badge initial count:', count);
+
+// Live subscription for badge updates.
+await window._smartico.api.getInboxUnreadCount({
+  onUpdate: (newCount) => {
+    console.log('[smartico] inbox count changed — update the badge to:', newCount,
+      '— hide badge entirely when 0, show raw integer otherwise (no "99+" cap in the default UI)');
+  },
+});
+```
+
 ***
 
 ### getInboxMessageBody()
 
 > **getInboxMessageBody**(`messageGuid`): `Promise`\<[`TInboxMessageBody`](../interfaces/TInboxMessageBody.md)\>
 
-Returns the message body of the specified message guid.
+Returns the rich body of a single inbox message — title, preview
+text, icon, click action, optional rich HTML body, and optional
+buttons. Call this after fetching the envelope list via
+[getInboxMessages](#getinboxmessages) to render either a list-item preview or
+a full detail view.
 
-**Visitor mode: not supported**
+The message body is served from a CDN — not over the WebSocket —
+so latency depends on CDN proximity rather than WS round-trip
+time. There is NO client-side cache; every call is a fresh
+HTTP fetch. Browser HTTP caching applies (Cache-Control headers
+from the CDN), but the SDK does not memoize the result.
 
 #### Parameters
 
@@ -178,19 +406,70 @@ Returns the message body of the specified message guid.
 
 `string`
 
+The `message_guid` from a `TInboxMessage`
+                    returned by [getInboxMessages](#getinboxmessages).
+
 #### Returns
 
 `Promise`\<[`TInboxMessageBody`](../interfaces/TInboxMessageBody.md)\>
 
+Promise resolving to `TInboxMessageBody`.
+
+#### Remarks
+
+**Rich vs simple messages**
+The shape of the returned body branches on the `action` field:
+- When `action === 'dp:inbox'`, the message has a rich HTML body
+  (`html_body`) and may have up to 2 action `buttons`. Use these
+  for a full-detail rendering.
+- For any other `action` (deep-link like `'dp:deposit'` or a URL),
+  the message is a simple notification — `html_body` and
+  `buttons` will be `undefined` regardless of what's in the
+  underlying CDN payload. Render `title` + `preview_body` + a
+  single CTA driving the `action`.
+
+**The `action` field**
+For both shapes, `action` carries either a deep-link
+(`'dp:gf_missions'`) or a plain URL. Pass it to `_smartico.dp()`
+for safe execution — that helper handles URL vs deep-link
+routing.
+
+**Idempotency / Side effects**: safe. Read-only HTTP fetch.
+
+**UI guidance**: see [UI Guide — `getInboxMessageBody`](../_media/UIGuide_getInboxMessageBody.md).
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+const body = await window._smartico.api.getInboxMessageBody(messageGuid);
+
+console.log('[smartico] render message — title:', body.title,
+  '— preview:', body.preview_body,
+  '— icon:', body.icon);
+
+if (body.action === 'dp:inbox' && body.html_body) {
+  console.log('[smartico] rich message — render the html_body in a sandboxed iframe; render up to 2 action buttons:',
+    body.buttons?.length ?? 0);
+} else {
+  console.log('[smartico] simple message — show preview_body + single CTA wired to:', body.action,
+    '— execute via _smartico.dp(body.action)');
+}
+```
+
 ***
 
 ### markInboxMessageAsRead()
 
 > **markInboxMessageAsRead**(`messageGuid`): `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
-Requests to mark inbox message with specified guid as read
-
-**Visitor mode: not supported**
+Marks a single inbox message as read. Server-side this flips the
+message's `is_read` flag and decrements the user's unread count
+(the change propagates back via the user-properties channel —
+subscribers to [getInboxUnreadCount](#getinboxunreadcount)'s `onUpdate` and
+[getUserProfile](WSAPIUser.md#getuserprofile)'s `core_inbox_unread_count` see it within
+~1 second).
 
 #### Parameters
 
@@ -198,33 +477,126 @@ Requests to mark inbox message with specified guid as read
 
 `string`
 
+The `message_guid` from a `TInboxMessage`.
+
 #### Returns
 
 `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
+`{ err_code, err_message }`; success when
+         `err_code === 0`.
+
+#### Remarks
+
+**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.
+
+**Refresh after success**
+The SDK does NOT auto-refresh [getInboxMessages](#getinboxmessages) (no
+`onUpdate` callback fires after this mutation). The unread-count
+channel ([getInboxUnreadCount](#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`](../_media/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);
+}
+```
+
 ***
 
 ### markAllInboxMessagesAsRead()
 
 > **markAllInboxMessagesAsRead**(): `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
-Requests to mark all inbox messages as read
+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.
 
-**Visitor mode: not supported**
+The operation is global to the user — NOT filtered by the
+current view (active category tab, favorite filter, etc.). Every
+unread message in the user's inbox flips to read.
 
 #### Returns
 
 `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
+`{ err_code, err_message }`; success when
+         `err_code === 0`.
+
+#### Remarks
+
+**Error codes** (in `err_code`)
+- `0` — success; all currently-unread messages flipped to read.
+- other non-zero — server error. Surface `err_message` if any.
+
+**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](#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`](../_media/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);
+}
+```
+
 ***
 
 ### markUnmarkInboxMessageAsFavorite()
 
 > **markUnmarkInboxMessageAsFavorite**(`messageGuid`, `mark`): `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
-Requests to mark inbox message with specified guid as favorite. Pass mark true to add message to favorite and false to remove.
-
-**Visitor mode: not supported**
+Toggles a message's favorite (starred) state — pass `mark: true`
+to favorite, `mark: false` to unfavorite. Use to power a star
+icon click handler on the inbox list.
 
 #### Parameters
 
@@ -232,23 +604,76 @@ Requests to mark inbox message with specified guid as favorite. Pass mark true t
 
 `string`
 
+The `message_guid` from a `TInboxMessage`.
+
 ##### mark
 
 `boolean`
 
+`true` to favorite, `false` to unfavorite.
+
 #### Returns
 
 `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
+`{ err_code, err_message }`; success when
+                    `err_code === 0`.
+
+#### Remarks
+
+**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.
+
+**Refresh after success**
+The SDK does NOT auto-refresh [getInboxMessages](#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`](../_media/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);
+}
+```
+
 ***
 
 ### deleteInboxMessage()
 
 > **deleteInboxMessage**(`messageGuid`): `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
-Requests to delete inbox message
-
-**Visitor mode: not supported**
+Soft-deletes a single inbox message. After deletion, the message
+is excluded from future [getInboxMessages](#getinboxmessages) responses
+server-side, but its row is retained for analytics — there is no
+"undelete" path via the SDK.
 
 #### Parameters
 
@@ -256,22 +681,121 @@ Requests to delete inbox message
 
 `string`
 
+The `message_guid` from a `TInboxMessage`.
+
 #### Returns
 
 `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
+`{ err_code, err_message }`; success when
+         `err_code === 0`.
+
+#### Remarks
+
+**Error codes** (in `err_code`)
+- `0` — success; the message is now deleted from the user's
+  view.
+- other non-zero — server error. Surface `err_message` if any.
+
+**Refresh after success**
+The SDK does NOT auto-refresh [getInboxMessages](#getinboxmessages). Drop the
+deleted message from your local list, or re-call
+`getInboxMessages` to reload. If the deleted message was unread,
+the unread count drops automatically via the user-properties
+channel.
+
+**Idempotency**: safe. A second call on an already-deleted
+`messageGuid` returns `err_code === 0` (server treats it as a
+no-op — already-deleted messages are filtered out).
+
+**Side effects** (on success)
+- Server-side `is_deleted` flag set to true.
+- If the message was unread, `core_inbox_unread_count`
+  decrements via the user-properties channel.
+
+**UI guidance**: see [UI Guide — `deleteInboxMessage`](../_media/UIGuide_deleteInboxMessage.md).
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+// Swipe-to-delete on mobile; trash-icon click on desktop.
+console.log('[smartico] delete starting — animate the row out of the list (slide left/right by 100%)');
+const r = await window._smartico.api.deleteInboxMessage(message.message_guid);
+if (r.err_code === 0) {
+  console.log('[smartico] deleted — drop the message from the local list, fire a brief "Message deleted" toast (no undo affordance — there is no undelete via the SDK)');
+} else {
+  console.error('[smartico] delete failed — animate the row back into place and show a non-blocking error:', r.err_message);
+}
+```
+
 ***
 
 ### deleteAllInboxMessages()
 
 > **deleteAllInboxMessages**(): `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
-Requests to delete all inbox messages
+Soft-deletes ALL of the user's inbox messages in one server
+round-trip — typically wired to a "Delete all" CTA in the inbox
+header (usually behind a confirm dialog given the destructive
+nature).
 
-**Visitor mode: not supported**
+The operation is global to the user — NOT filtered by the
+current view (active category tab, favorite filter, etc.). Every
+non-deleted message in the user's inbox flips to deleted.
 
 #### Returns
 
 `Promise`\<[`InboxMarkMessageAction`](../interfaces/InboxMarkMessageAction.md)\>
 
+`{ err_code, err_message }`; success when
+         `err_code === 0`.
+
+#### Remarks
+
+**Error codes** (in `err_code`)
+- `0` — success; the entire inbox is now empty from the user's
+  view.
+- other non-zero — server error. Surface `err_message` if any.
+
+**Race condition note**: a new message arriving server-side
+between the call and its processing is NOT deleted (the
+server's delete-all operation is a snapshot in time). Subsequent
+`getInboxMessages` calls show the new message.
+
+**Refresh after success**
+Same as [deleteInboxMessage](#deleteinboxmessage) — `getInboxMessages` `onUpdate`
+does not fire automatically. Replace the local list with `[]`
+(or re-call `getInboxMessages`). The unread count drops to 0
+(or near-0 if races) via the user-properties channel.
+
+**Idempotency**: safe. A second call on an already-empty inbox
+returns `err_code === 0` with no-op effect.
+
+**Side effects** (on success)
+- Every message flipped to deleted server-side.
+- `core_inbox_unread_count` drops to 0.
+- There is no SDK undelete path — recovery requires operator
+  intervention.
+
+**UI guidance**: included in the
+[UI Guide — `deleteInboxMessage`](../_media/UIGuide_deleteInboxMessage.md)
+(Bulk variant section).
+
+**Visitor mode**: not supported.
+
+#### Example
+
+```ts
+// After a confirm dialog "Are you sure you want to delete all messages?"
+console.log('[smartico] delete-all confirmed — show loading state on the "Delete all" button');
+const r = await window._smartico.api.deleteAllInboxMessages();
+if (r.err_code === 0) {
+  console.log('[smartico] inbox cleared — replace the local list with [], fire a "All messages deleted" toast, badge auto-drops to 0');
+} else {
+  console.error('[smartico] delete-all failed — show a non-blocking error toast:', r.err_message);
+}
+```
+
 ***