@antzsoft/chat-core 1.4.3 → 1.4.4

package/dist/index.js

@@ -13,6 +13,7 @@ import {
   encryptPayload,
   fetchServerKeys,
   generateEphemeralKey,
+  generateUUID,
   getApiClient,
   getCompressionStrategy,
   getSessionId,
@@ -299,363 +300,6 @@ function resolveSystemMessageText(message, currentUserId) {
   }
 }
 
-// src/api/messages.ts
-var MAX_FORWARD_TARGETS = 5;
-var HIGHLY_FORWARDED_DEPTH_THRESHOLD = 5;
-var messagesApi = {
-  async list(conversationId, params = {}) {
-    const { cursor, direction, ...rest } = params;
-    const serverParams = { ...rest };
-    if (cursor) {
-      serverParams[direction === "after" ? "after" : "before"] = cursor;
-    }
-    const { data } = await getApiClient().get(
-      `/conversations/${conversationId}/messages`,
-      { params: serverParams }
-    );
-    const currentUserId = getAuthStore().useAuthStore.getState().user?.id;
-    if (!currentUserId) return data;
-    return {
-      ...data,
-      data: data.data.map(
-        (m) => m.content.type === "system" ? { ...m, content: { ...m.content, text: resolveSystemMessageText(m, currentUserId) } } : m
-      )
-    };
-  },
-  async get(messageId) {
-    const { data } = await getApiClient().get(`/messages/${messageId}`);
-    return data;
-  },
-  async send(conversationId, payload) {
-    const { data } = await getApiClient().post(
-      `/conversations/${conversationId}/messages`,
-      payload
-    );
-    return data;
-  },
-  async update(messageId, text) {
-    const { data } = await getApiClient().post(`/messages/${messageId}/update`, { text });
-    return data;
-  },
-  async delete(messageId) {
-    await getApiClient().post(`/messages/${messageId}/delete`);
-  },
-  async deleteForMe(messageId) {
-    await getApiClient().post(`/messages/${messageId}/delete-for-me`);
-  },
-  async addReaction(messageId, emoji) {
-    const { data } = await getApiClient().post(`/messages/${messageId}/reactions`, { emoji });
-    return data;
-  },
-  async removeReaction(messageId, emoji) {
-    const { data } = await getApiClient().post(
-      `/messages/${messageId}/reactions/${encodeURIComponent(emoji)}/remove`
-    );
-    return data;
-  },
-  async getReactions(messageId) {
-    const { data } = await getApiClient().post(`/messages/${messageId}/reactions/list`);
-    return data;
-  },
-  async star(messageId) {
-    await getApiClient().post(`/messages/${messageId}/star`);
-  },
-  async unstar(messageId) {
-    await getApiClient().post(`/messages/${messageId}/unstar`);
-  },
-  async getStarred(params = {}) {
-    const { data } = await getApiClient().get("/messages/starred", { params });
-    return data;
-  },
-  async search(params) {
-    const { data } = await getApiClient().get("/messages/search", { params });
-    return data;
-  },
-  async getLastRead(conversationId) {
-    const { data } = await getApiClient().get(
-      `/conversations/${conversationId}/read-receipt`
-    );
-    return data;
-  },
-  async markAsRead(conversationId, messageId) {
-    await getApiClient().post(`/conversations/${conversationId}/read`, messageId ? { messageId } : {});
-  },
-  async pin(messageId) {
-    const { data } = await getApiClient().post(`/messages/${messageId}/pin`);
-    return data;
-  },
-  async unpin(messageId) {
-    const { data } = await getApiClient().post(`/messages/${messageId}/unpin`);
-    return data;
-  },
-  async getPinned(conversationId) {
-    const { data } = await getApiClient().get(`/conversations/${conversationId}/pinned-messages`);
-    return data;
-  },
-  async getReceipts(messageId) {
-    const { data } = await getApiClient().get(`/messages/${messageId}/receipts`);
-    return data;
-  },
-  /**
-   * Forwards a message into one or more target conversations (max MAX_FORWARD_TARGETS
-   * per call, also enforced server-side). Each target is independent — one failing
-   * (e.g. no longer a participant) does not block the others; check `success`/`error`
-   * per entry in the returned array.
-   *
-   * Pass `attachmentIds` to forward only a subset of the source message's attachments
-   * (e.g. one image out of a multi-image message) — omit it to forward the whole
-   * message, including all its attachments, unchanged. An ID not present on the
-   * source message is ignored server-side.
-   */
-  async forward(messageId, targetConversationIds, attachmentIds) {
-    const { data } = await getApiClient().post(
-      `/messages/${messageId}/forward`,
-      { targetConversationIds, ...attachmentIds ? { attachmentIds } : {} }
-    );
-    return data;
-  }
-};
-
-// src/api/conversations.ts
-function normalizeParticipant(p) {
-  const hasUserDetails = p.displayName || p.username || p.avatarUrl;
-  return {
-    userId: p.userId,
-    externalId: p.externalId ?? p.user?.externalId,
-    role: p.role,
-    joinedAt: p.joinedAt,
-    isActive: p.isActive,
-    user: hasUserDetails ? {
-      id: p.userId,
-      externalId: p.externalId,
-      tenantId: "",
-      email: "",
-      username: p.username ?? "",
-      displayName: p.displayName ?? p.username ?? "",
-      avatarUrl: p.avatarUrl,
-      status: "offline",
-      createdAt: p.joinedAt ?? "",
-      updatedAt: p.joinedAt ?? ""
-    } : p.user
-  };
-}
-function normalizeLastMessage(lastMsg) {
-  if (!lastMsg) return void 0;
-  if (lastMsg.content !== void 0) return lastMsg;
-  return {
-    id: lastMsg.messageId ?? "",
-    tenantId: "",
-    conversationId: "",
-    senderId: lastMsg.senderId ?? "",
-    content: {
-      type: lastMsg.hasAttachments ? "attachment" : "text",
-      text: lastMsg.contentPreview
-    },
-    reactions: [],
-    lastReaction: lastMsg.lastReaction ?? null,
-    status: lastMsg.status ?? "active",
-    deliveryStatus: lastMsg.deliveryStatus ?? "sent",
-    isEdited: false,
-    sentAt: lastMsg.sentAt ?? "",
-    createdAt: lastMsg.sentAt ?? "",
-    ...lastMsg.senderName && { senderName: lastMsg.senderName },
-    ...lastMsg.attachmentType && { attachmentType: lastMsg.attachmentType }
-  };
-}
-function normalizeConversation(conv) {
-  return {
-    ...conv,
-    id: conv.id ?? conv.conversationId,
-    participants: (conv.participants ?? []).map(normalizeParticipant),
-    lastMessage: normalizeLastMessage(conv.lastMessage)
-  };
-}
-var conversationsApi = {
-  async list(params = {}) {
-    const { data } = await getApiClient().get("/conversations", { params });
-    return { ...data, data: data.data.map(normalizeConversation) };
-  },
-  async get(conversationId) {
-    const { data } = await getApiClient().get(`/conversations/${conversationId}`);
-    return normalizeConversation(data);
-  },
-  async createGroup(payload) {
-    const { data } = await getApiClient().post("/conversations", payload);
-    return normalizeConversation(data);
-  },
-  async createDirect(payload) {
-    const { data } = await getApiClient().post("/conversations/direct", payload);
-    return normalizeConversation(data);
-  },
-  async update(conversationId, payload) {
-    const { data } = await getApiClient().post(`/conversations/${conversationId}/update`, payload);
-    return normalizeConversation(data);
-  },
-  async delete(conversationId) {
-    await getApiClient().post(`/conversations/${conversationId}/delete`);
-  },
-  async addParticipants(conversationId, userIds, role) {
-    const { data } = await getApiClient().post(
-      `/conversations/${conversationId}/participants`,
-      { userIds, ...role && { role } }
-    );
-    return normalizeConversation(data);
-  },
-  async removeParticipant(conversationId, userId) {
-    const { data } = await getApiClient().post(
-      `/conversations/${conversationId}/participants/${userId}/remove`
-    );
-    return normalizeConversation(data);
-  },
-  async updateParticipantRole(conversationId, userId, role) {
-    const { data } = await getApiClient().post(
-      `/conversations/${conversationId}/participants/${userId}/role`,
-      { role }
-    );
-    return normalizeConversation(data);
-  },
-  async mute(conversationId, mutedUntil) {
-    await getApiClient().post(`/conversations/${conversationId}/mute`, mutedUntil ? { mutedUntil } : {});
-  },
-  async unmute(conversationId) {
-    await getApiClient().post(`/conversations/${conversationId}/unmute`);
-  },
-  async pin(conversationId) {
-    await getApiClient().post(`/conversations/${conversationId}/pin`);
-  },
-  async unpin(conversationId) {
-    await getApiClient().post(`/conversations/${conversationId}/unpin`);
-  },
-  async markUnread(conversationId) {
-    await getApiClient().post(`/conversations/${conversationId}/unread`);
-  },
-  async markRead(conversationId) {
-    await getApiClient().post(`/conversations/${conversationId}/unread/clear`);
-  },
-  async leave(conversationId, andDelete) {
-    const url = andDelete ? `/conversations/${conversationId}/leave?delete=true` : `/conversations/${conversationId}/leave`;
-    await getApiClient().post(url);
-  },
-  async getMembers(conversationId, filter) {
-    const { data } = await getApiClient().get(
-      `/conversations/${conversationId}/participants`,
-      filter ? { params: { filter } } : void 0
-    );
-    return (data ?? []).map(normalizeParticipant);
-  },
-  /**
-   * Get unread message count for a single conversation.
-   * Use this after app foreground or socket reconnect to refresh a specific count.
-   */
-  async getUnreadCount(conversationId) {
-    const { data } = await getApiClient().get(
-      `/conversations/${conversationId}/unread`
-    );
-    return data;
-  },
-  /**
-   * Get total unread count across all conversations + per-conversation breakdown.
-   * Use on app cold start, foreground resume, or after socket reconnect.
-   * The socket keeps counts live while connected — this is the source of truth
-   * when the socket was down.
-   */
-  async getUnreadSummary() {
-    const { data } = await getApiClient().get("/conversations/unread");
-    return data;
-  },
-  /**
-   * Set the group icon from an already-uploaded file (admin only).
-   * The fileId comes from uploadBatch() / client.uploadFiles() — same as attachments.
-   * Server copies storageKey into conversation.iconMeta and deletes the chat_files record.
-   */
-  async uploadIcon(conversationId, fileId) {
-    const { data } = await getApiClient().post(
-      `/conversations/${conversationId}/icon`,
-      { fileId }
-    );
-    return normalizeConversation(data);
-  },
-  async removeIcon(conversationId) {
-    const { data } = await getApiClient().post(`/conversations/${conversationId}/icon/remove`);
-    return normalizeConversation(data);
-  },
-  async clearChat(conversationId) {
-    await getApiClient().post(`/conversations/${conversationId}/clear-for-me`);
-  }
-};
-
-// src/api/devices.ts
-var devicesApi = {
-  /**
-   * Register or update a device push token with the chat server.
-   *
-   * Upserts by `deviceId` — calling this multiple times with the same deviceId
-   * simply refreshes the token value (tokens can rotate silently on some platforms).
-   *
-   * The SDK never calls this automatically. The parent app or the `tokenProvider`
-   * option in `pushNotifications` config is responsible for calling it after
-   * obtaining the token from the OS / browser.
-   */
-  async register(payload) {
-    await getApiClient().post("/users/me/devices", payload);
-  },
-  /**
-   * Remove a device token from the chat server.
-   * Call this on logout so the user stops receiving push notifications on this device.
-   */
-  async remove(deviceId) {
-    await getApiClient().post(`/users/me/devices/${deviceId}/remove`);
-  }
-};
-
-// src/api/users.ts
-var usersApi = {
-  async list(params = {}) {
-    const { data } = await getApiClient().get("/users", { params });
-    return data;
-  },
-  async getById(userId) {
-    const { data } = await getApiClient().get(`/users/${userId}`);
-    return data;
-  },
-  async getLastSeen(userId) {
-    const { data } = await getApiClient().get(`/users/${userId}`);
-    return { lastSeenAt: data.lastSeenAt ?? null };
-  },
-  /**
-   * Update basic profile fields for the current user.
-   * Works in both builtin and non-builtin modes. Use this to push an immediate
-   * profile update to the chat server when the host app knows a change just
-   * happened — without waiting for the next 2-hour sync cycle.
-   */
-  async updateProfile(payload) {
-    const { data } = await getApiClient().post("/users/me/update", payload);
-    return data;
-  },
-  /**
-   * Update notification preferences for the current user.
-   * Partial update — only send fields you want to change.
-   * A prefs record is automatically created with defaults when a device
-   * token is first registered, so this never fails with "not found".
-   */
-  async updatePreferences(prefs) {
-    const { data } = await getApiClient().post("/users/me/preferences", prefs);
-    return data;
-  },
-  /**
-   * Fetch current notification preferences for the current user.
-   * Returns null if no prefs record exists yet (all defaults apply).
-   */
-  async getPreferences() {
-    try {
-      const { data } = await getApiClient().get("/users/me/preferences");
-      return data;
-    } catch {
-      return null;
-    }
-  }
-};
-
 // src/socket/socket.ts
 import { io } from "socket.io-client";
 var _socket = null;
@@ -1026,74 +670,468 @@ async function withAck(event, payload) {
     }).catch(reject);
   });
 }
-function fireAndForget(event, payload) {
-  const socket = tryGetSocket();
-  if (!socket) return;
-  secureEmit(socket, event, payload);
+function fireAndForget(event, payload) {
+  const socket = tryGetSocket();
+  if (!socket) return;
+  secureEmit(socket, event, payload);
+}
+var socketEmit = {
+  joinRoom(conversationId) {
+    fireAndForget("join_room", { conversationId });
+  },
+  leaveRoom(conversationId) {
+    fireAndForget("leave_room", { conversationId });
+  },
+  sendMessage(payload) {
+    return queueSendMessage({ ...payload, sentAt: Date.now() });
+  },
+  // Not queued like sendMessage — forward targets are independent conversations,
+  // not the single conversation ordering that queueSendMessage protects, and each
+  // target's own new_message/push already fires server-side via MessagesService.forward()'s
+  // internal create() calls, so there's nothing here that needs in-order draining.
+  forwardMessage(payload) {
+    return withAck("forward_message", payload);
+  },
+  updateMessage(messageId, text) {
+    return withAck("update_message", { messageId, text });
+  },
+  deleteMessage(messageId) {
+    return withAck("delete_message", { messageId });
+  },
+  deleteMessageForMe(messageId) {
+    return withAck("delete_message_for_me", { messageId });
+  },
+  clearChat(conversationId) {
+    return withAck("clear_chat_for_me", { conversationId });
+  },
+  addReaction(messageId, emoji) {
+    return withAck("add_reaction", { messageId, emoji });
+  },
+  removeReaction(messageId, emoji) {
+    return withAck("remove_reaction", { messageId, emoji });
+  },
+  pinMessage(messageId) {
+    return withAck("pin_message", { messageId });
+  },
+  unpinMessage(messageId) {
+    return withAck("unpin_message", { messageId });
+  },
+  // markRead and typing are best-effort — silently dropped if socket not ready
+  typing(conversationId, isTyping) {
+    fireAndForget("typing", { conversationId, isTyping });
+  },
+  markRead(conversationId, messageId) {
+    fireAndForget("mark_read", { conversationId, ...messageId ? { messageId } : {} });
+  },
+  getOnlineUsers(userIds) {
+    const socket = tryGetSocket();
+    if (!socket) return Promise.resolve([]);
+    return new Promise((resolve, reject) => {
+      let timer;
+      secureEmit(socket, "get_online_users", { userIds }, (response) => {
+        clearTimeout(timer);
+        if (response && typeof response === "object" && "onlineStatus" in response) {
+          const status = response.onlineStatus;
+          resolve(Object.entries(status).filter(([, v]) => v).map(([k]) => k));
+        } else if (Array.isArray(response)) {
+          resolve(response);
+        } else {
+          resolve([]);
+        }
+      }).then(() => {
+        timer = setTimeout(() => reject(new AntzChatNetworkError("Socket ack timeout: get_online_users", "SOCKET_TIMEOUT", { event: "get_online_users" })), ACK_TIMEOUT);
+      }).catch(reject);
+    });
+  },
+  getTypingUsers(conversationId) {
+    return withAck("get_typing_users", { conversationId });
+  }
+};
+
+// src/api/messages.ts
+var MAX_FORWARD_TARGETS = 5;
+var HIGHLY_FORWARDED_DEPTH_THRESHOLD = 5;
+var messagesApi = {
+  async list(conversationId, params = {}) {
+    const { cursor, direction, ...rest } = params;
+    const serverParams = { ...rest };
+    if (cursor) {
+      serverParams[direction === "after" ? "after" : "before"] = cursor;
+    }
+    const { data } = await getApiClient().get(
+      `/conversations/${conversationId}/messages`,
+      { params: serverParams }
+    );
+    const currentUserId = getAuthStore().useAuthStore.getState().user?.id;
+    if (!currentUserId) return data;
+    return {
+      ...data,
+      data: data.data.map(
+        (m) => m.content.type === "system" ? { ...m, content: { ...m.content, text: resolveSystemMessageText(m, currentUserId) } } : m
+      )
+    };
+  },
+  async get(messageId) {
+    const { data } = await getApiClient().get(`/messages/${messageId}`);
+    return data;
+  },
+  /**
+   * Sends a message via REST. For real-time delivery use `socketEmit.sendMessage`
+   * instead — this is a lower-level entry point (used e.g. by the socket path's
+   * REST-mirror flows). Pass `payload.tempId` and reuse the SAME value on retry to
+   * make a retry-after-timeout safe — see `SendData.tempId`.
+   */
+  async send(conversationId, payload) {
+    const { data } = await getApiClient().post(
+      `/conversations/${conversationId}/messages`,
+      payload
+    );
+    return data;
+  },
+  async update(messageId, text) {
+    const { data } = await getApiClient().post(`/messages/${messageId}/update`, { text });
+    return data;
+  },
+  async delete(messageId) {
+    await getApiClient().post(`/messages/${messageId}/delete`);
+  },
+  async deleteForMe(messageId) {
+    await getApiClient().post(`/messages/${messageId}/delete-for-me`);
+  },
+  async addReaction(messageId, emoji) {
+    const { data } = await getApiClient().post(`/messages/${messageId}/reactions`, { emoji });
+    return data;
+  },
+  async removeReaction(messageId, emoji) {
+    const { data } = await getApiClient().post(
+      `/messages/${messageId}/reactions/${encodeURIComponent(emoji)}/remove`
+    );
+    return data;
+  },
+  async getReactions(messageId) {
+    const { data } = await getApiClient().post(`/messages/${messageId}/reactions/list`);
+    return data;
+  },
+  async star(messageId) {
+    await getApiClient().post(`/messages/${messageId}/star`);
+  },
+  async unstar(messageId) {
+    await getApiClient().post(`/messages/${messageId}/unstar`);
+  },
+  async getStarred(params = {}) {
+    const { data } = await getApiClient().get("/messages/starred", { params });
+    return data;
+  },
+  async search(params) {
+    const { data } = await getApiClient().get("/messages/search", { params });
+    return data;
+  },
+  async getLastRead(conversationId) {
+    const { data } = await getApiClient().get(
+      `/conversations/${conversationId}/read-receipt`
+    );
+    return data;
+  },
+  async markAsRead(conversationId, messageId) {
+    await getApiClient().post(`/conversations/${conversationId}/read`, messageId ? { messageId } : {});
+  },
+  async pin(messageId) {
+    const { data } = await getApiClient().post(`/messages/${messageId}/pin`);
+    return data;
+  },
+  async unpin(messageId) {
+    const { data } = await getApiClient().post(`/messages/${messageId}/unpin`);
+    return data;
+  },
+  async getPinned(conversationId) {
+    const { data } = await getApiClient().get(`/conversations/${conversationId}/pinned-messages`);
+    return data;
+  },
+  async getReceipts(messageId) {
+    const { data } = await getApiClient().get(`/messages/${messageId}/receipts`);
+    return data;
+  },
+  /**
+   * Forwards a message into one or more target conversations (max MAX_FORWARD_TARGETS
+   * per call, also enforced server-side). Each target is independent — one failing
+   * (e.g. no longer a participant) does not block the others; check `success`/`error`
+   * per entry in the returned array.
+   *
+   * Pass `attachmentIds` to forward only a subset of the source message's attachments
+   * (e.g. one image out of a multi-image message) — omit it to forward the whole
+   * message, including all its attachments, unchanged. An ID not present on the
+   * source message is ignored server-side.
+   *
+   * Idempotency: pass `tempId` — generate ONE value per forward action (e.g. via
+   * `generateUUID` from '@antzsoft/chat-core/internal') and reuse that SAME value if
+   * you retry this exact forward (e.g. after a client-side timeout). The server then
+   * recognizes the retry per target and returns the already-created message instead
+   * of creating a duplicate. Never mint a new tempId for a retry — only when the user
+   * initiates a genuinely new forward action. If omitted, a fresh one is generated
+   * per call, which means a retry without an explicit tempId gets NO dedup protection.
+   *
+   * Transport: uses the 'forward_message' socket event when a socket is connected
+   * (lower latency, same server-side MessagesService.forward() path, so broadcast/
+   * push notification behavior is identical either way) and transparently falls back
+   * to the REST endpoint when no socket is available.
+   */
+  async forward(messageId, targetConversationIds, attachmentIds, tempId) {
+    const resolvedTempId = tempId ?? generateUUID();
+    if (tryGetSocket()) {
+      const ack = await socketEmit.forwardMessage({
+        messageId,
+        targetConversationIds,
+        ...attachmentIds ? { attachmentIds } : {},
+        tempId: resolvedTempId
+      });
+      if (ack.error) throw new Error(ack.error);
+      return ack.results;
+    }
+    const { data } = await getApiClient().post(
+      `/messages/${messageId}/forward`,
+      { targetConversationIds, ...attachmentIds ? { attachmentIds } : {}, tempId: resolvedTempId }
+    );
+    return data;
+  }
+};
+
+// src/api/conversations.ts
+function normalizeParticipant(p) {
+  const hasUserDetails = p.displayName || p.username || p.avatarUrl;
+  return {
+    userId: p.userId,
+    externalId: p.externalId ?? p.user?.externalId,
+    role: p.role,
+    joinedAt: p.joinedAt,
+    isActive: p.isActive,
+    user: hasUserDetails ? {
+      id: p.userId,
+      externalId: p.externalId,
+      tenantId: "",
+      email: "",
+      username: p.username ?? "",
+      displayName: p.displayName ?? p.username ?? "",
+      avatarUrl: p.avatarUrl,
+      status: "offline",
+      createdAt: p.joinedAt ?? "",
+      updatedAt: p.joinedAt ?? ""
+    } : p.user
+  };
+}
+function normalizeLastMessage(lastMsg) {
+  if (!lastMsg) return void 0;
+  if (lastMsg.content !== void 0) return lastMsg;
+  return {
+    id: lastMsg.messageId ?? "",
+    tenantId: "",
+    conversationId: "",
+    senderId: lastMsg.senderId ?? "",
+    content: {
+      type: lastMsg.hasAttachments ? "attachment" : "text",
+      text: lastMsg.contentPreview
+    },
+    reactions: [],
+    lastReaction: lastMsg.lastReaction ?? null,
+    status: lastMsg.status ?? "active",
+    deliveryStatus: lastMsg.deliveryStatus ?? "sent",
+    isEdited: false,
+    sentAt: lastMsg.sentAt ?? "",
+    createdAt: lastMsg.sentAt ?? "",
+    ...lastMsg.senderName && { senderName: lastMsg.senderName },
+    ...lastMsg.attachmentType && { attachmentType: lastMsg.attachmentType }
+  };
 }
-var socketEmit = {
-  joinRoom(conversationId) {
-    fireAndForget("join_room", { conversationId });
+function normalizeConversation(conv) {
+  return {
+    ...conv,
+    id: conv.id ?? conv.conversationId,
+    participants: (conv.participants ?? []).map(normalizeParticipant),
+    lastMessage: normalizeLastMessage(conv.lastMessage)
+  };
+}
+var conversationsApi = {
+  async list(params = {}) {
+    const { data } = await getApiClient().get("/conversations", { params });
+    return { ...data, data: data.data.map(normalizeConversation) };
   },
-  leaveRoom(conversationId) {
-    fireAndForget("leave_room", { conversationId });
+  async get(conversationId) {
+    const { data } = await getApiClient().get(`/conversations/${conversationId}`);
+    return normalizeConversation(data);
   },
-  sendMessage(payload) {
-    return queueSendMessage({ ...payload, sentAt: Date.now() });
+  async createGroup(payload) {
+    const { data } = await getApiClient().post("/conversations", payload);
+    return normalizeConversation(data);
   },
-  updateMessage(messageId, text) {
-    return withAck("update_message", { messageId, text });
+  async createDirect(payload) {
+    const { data } = await getApiClient().post("/conversations/direct", payload);
+    return normalizeConversation(data);
   },
-  deleteMessage(messageId) {
-    return withAck("delete_message", { messageId });
+  async update(conversationId, payload) {
+    const { data } = await getApiClient().post(`/conversations/${conversationId}/update`, payload);
+    return normalizeConversation(data);
   },
-  deleteMessageForMe(messageId) {
-    return withAck("delete_message_for_me", { messageId });
+  async delete(conversationId) {
+    await getApiClient().post(`/conversations/${conversationId}/delete`);
   },
-  clearChat(conversationId) {
-    return withAck("clear_chat_for_me", { conversationId });
+  async addParticipants(conversationId, userIds, role) {
+    const { data } = await getApiClient().post(
+      `/conversations/${conversationId}/participants`,
+      { userIds, ...role && { role } }
+    );
+    return normalizeConversation(data);
   },
-  addReaction(messageId, emoji) {
-    return withAck("add_reaction", { messageId, emoji });
+  async removeParticipant(conversationId, userId) {
+    const { data } = await getApiClient().post(
+      `/conversations/${conversationId}/participants/${userId}/remove`
+    );
+    return normalizeConversation(data);
   },
-  removeReaction(messageId, emoji) {
-    return withAck("remove_reaction", { messageId, emoji });
+  async updateParticipantRole(conversationId, userId, role) {
+    const { data } = await getApiClient().post(
+      `/conversations/${conversationId}/participants/${userId}/role`,
+      { role }
+    );
+    return normalizeConversation(data);
   },
-  pinMessage(messageId) {
-    return withAck("pin_message", { messageId });
+  async mute(conversationId, mutedUntil) {
+    await getApiClient().post(`/conversations/${conversationId}/mute`, mutedUntil ? { mutedUntil } : {});
   },
-  unpinMessage(messageId) {
-    return withAck("unpin_message", { messageId });
+  async unmute(conversationId) {
+    await getApiClient().post(`/conversations/${conversationId}/unmute`);
   },
-  // markRead and typing are best-effort — silently dropped if socket not ready
-  typing(conversationId, isTyping) {
-    fireAndForget("typing", { conversationId, isTyping });
+  async pin(conversationId) {
+    await getApiClient().post(`/conversations/${conversationId}/pin`);
   },
-  markRead(conversationId, messageId) {
-    fireAndForget("mark_read", { conversationId, ...messageId ? { messageId } : {} });
+  async unpin(conversationId) {
+    await getApiClient().post(`/conversations/${conversationId}/unpin`);
   },
-  getOnlineUsers(userIds) {
-    const socket = tryGetSocket();
-    if (!socket) return Promise.resolve([]);
-    return new Promise((resolve, reject) => {
-      let timer;
-      secureEmit(socket, "get_online_users", { userIds }, (response) => {
-        clearTimeout(timer);
-        if (response && typeof response === "object" && "onlineStatus" in response) {
-          const status = response.onlineStatus;
-          resolve(Object.entries(status).filter(([, v]) => v).map(([k]) => k));
-        } else if (Array.isArray(response)) {
-          resolve(response);
-        } else {
-          resolve([]);
-        }
-      }).then(() => {
-        timer = setTimeout(() => reject(new AntzChatNetworkError("Socket ack timeout: get_online_users", "SOCKET_TIMEOUT", { event: "get_online_users" })), ACK_TIMEOUT);
-      }).catch(reject);
-    });
+  async markUnread(conversationId) {
+    await getApiClient().post(`/conversations/${conversationId}/unread`);
   },
-  getTypingUsers(conversationId) {
-    return withAck("get_typing_users", { conversationId });
+  async markRead(conversationId) {
+    await getApiClient().post(`/conversations/${conversationId}/unread/clear`);
+  },
+  async leave(conversationId, andDelete) {
+    const url = andDelete ? `/conversations/${conversationId}/leave?delete=true` : `/conversations/${conversationId}/leave`;
+    await getApiClient().post(url);
+  },
+  async getMembers(conversationId, filter) {
+    const { data } = await getApiClient().get(
+      `/conversations/${conversationId}/participants`,
+      filter ? { params: { filter } } : void 0
+    );
+    return (data ?? []).map(normalizeParticipant);
+  },
+  /**
+   * Get unread message count for a single conversation.
+   * Use this after app foreground or socket reconnect to refresh a specific count.
+   */
+  async getUnreadCount(conversationId) {
+    const { data } = await getApiClient().get(
+      `/conversations/${conversationId}/unread`
+    );
+    return data;
+  },
+  /**
+   * Get total unread count across all conversations + per-conversation breakdown.
+   * Use on app cold start, foreground resume, or after socket reconnect.
+   * The socket keeps counts live while connected — this is the source of truth
+   * when the socket was down.
+   */
+  async getUnreadSummary() {
+    const { data } = await getApiClient().get("/conversations/unread");
+    return data;
+  },
+  /**
+   * Set the group icon from an already-uploaded file (admin only).
+   * The fileId comes from uploadBatch() / client.uploadFiles() — same as attachments.
+   * Server copies storageKey into conversation.iconMeta and deletes the chat_files record.
+   */
+  async uploadIcon(conversationId, fileId) {
+    const { data } = await getApiClient().post(
+      `/conversations/${conversationId}/icon`,
+      { fileId }
+    );
+    return normalizeConversation(data);
+  },
+  async removeIcon(conversationId) {
+    const { data } = await getApiClient().post(`/conversations/${conversationId}/icon/remove`);
+    return normalizeConversation(data);
+  },
+  async clearChat(conversationId) {
+    await getApiClient().post(`/conversations/${conversationId}/clear-for-me`);
+  }
+};
+
+// src/api/devices.ts
+var devicesApi = {
+  /**
+   * Register or update a device push token with the chat server.
+   *
+   * Upserts by `deviceId` — calling this multiple times with the same deviceId
+   * simply refreshes the token value (tokens can rotate silently on some platforms).
+   *
+   * The SDK never calls this automatically. The parent app or the `tokenProvider`
+   * option in `pushNotifications` config is responsible for calling it after
+   * obtaining the token from the OS / browser.
+   */
+  async register(payload) {
+    await getApiClient().post("/users/me/devices", payload);
+  },
+  /**
+   * Remove a device token from the chat server.
+   * Call this on logout so the user stops receiving push notifications on this device.
+   */
+  async remove(deviceId) {
+    await getApiClient().post(`/users/me/devices/${deviceId}/remove`);
+  }
+};
+
+// src/api/users.ts
+var usersApi = {
+  async list(params = {}) {
+    const { data } = await getApiClient().get("/users", { params });
+    return data;
+  },
+  async getById(userId) {
+    const { data } = await getApiClient().get(`/users/${userId}`);
+    return data;
+  },
+  async getLastSeen(userId) {
+    const { data } = await getApiClient().get(`/users/${userId}`);
+    return { lastSeenAt: data.lastSeenAt ?? null };
+  },
+  /**
+   * Update basic profile fields for the current user.
+   * Works in both builtin and non-builtin modes. Use this to push an immediate
+   * profile update to the chat server when the host app knows a change just
+   * happened — without waiting for the next 2-hour sync cycle.
+   */
+  async updateProfile(payload) {
+    const { data } = await getApiClient().post("/users/me/update", payload);
+    return data;
+  },
+  /**
+   * Update notification preferences for the current user.
+   * Partial update — only send fields you want to change.
+   * A prefs record is automatically created with defaults when a device
+   * token is first registered, so this never fails with "not found".
+   */
+  async updatePreferences(prefs) {
+    const { data } = await getApiClient().post("/users/me/preferences", prefs);
+    return data;
+  },
+  /**
+   * Fetch current notification preferences for the current user.
+   * Returns null if no prefs record exists yet (all defaults apply).
+   */
+  async getPreferences() {
+    try {
+      const { data } = await getApiClient().get("/users/me/preferences");
+      return data;
+    } catch {
+      return null;
+    }
   }
 };