@antzsoft/chat-core 1.4.3 → 1.4.5

package/dist/index.js

@@ -5,14 +5,17 @@ import {
   AntzChatPermissionError,
   AntzChatServerError,
   AntzChatValidationError,
+  awaitTransitReadyOr,
   clearTransitSession,
-  configureTransit,
+  configureTransitIfUnset,
   createRestTransitSession,
   decryptPayload,
   detectTransitAlgo,
   encryptPayload,
+  ensureRestTransitHandshake,
   fetchServerKeys,
   generateEphemeralKey,
+  generateUUID,
   getApiClient,
   getCompressionStrategy,
   getSessionId,
@@ -20,16 +23,20 @@ import {
   getTransitHandshakePromise,
   getTransitSession,
   initApiClient,
+  isApiClientConfigured,
   isTransitEnabled,
   isTransitEnvelope,
+  isTransitRequired,
   normalizeAxiosError,
+  onTransitReady,
   performHandshake,
   resetAlgoCache,
   setApiClientInstance,
+  setAuthReadyPromise,
   setTransitSession,
   storageApi,
   uploadBatch
-} from "./chunk-XTQYF5HU.js";
+} from "./chunk-WUNH3UTE.js";
 import {
   useChatStore
 } from "./chunk-UIYJAOGL.js";
@@ -88,6 +95,7 @@ function resolveConfig(config) {
       compressDocuments: config.compression?.compressDocuments ?? true
     },
     persistStorage: config.persistStorage,
+    onSendError: config.onSendError,
     messagePageSize: config.messagePageSize ?? 40,
     starredMessagePageSize: config.starredMessagePageSize ?? 30,
     searchPageSize: config.searchPageSize ?? 50
@@ -299,363 +307,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;
@@ -667,7 +318,6 @@ var _getToken = null;
 var _userId;
 var _tenantId;
 var _config = null;
-var _preservingSession = false;
 function setStatus(s) {
   _status = s;
   _statusListeners.forEach((l) => l(s));
@@ -686,29 +336,48 @@ function onSocketStatus(listener) {
   _statusListeners.add(listener);
   return () => _statusListeners.delete(listener);
 }
-async function secureEmit(socket, event, payload, ack) {
-  if (isTransitEnabled()) {
-    const key = getSessionKey();
-    if (key) {
-      const envelope = await encryptPayload(payload, key);
-      if (ack) {
-        socket.emit(event, envelope, async (encryptedResponse) => {
-          if (isTransitEnvelope(encryptedResponse)) {
-            try {
-              const decrypted = await decryptPayload(encryptedResponse, key);
-              ack(decrypted);
-            } catch {
-              ack(encryptedResponse);
-            }
-          } else {
-            ack(encryptedResponse);
-          }
-        });
+var SECURE_EMIT_WAIT_MS = 4e3;
+function emitEncrypted(socket, event, envelope, key, ack) {
+  if (ack) {
+    socket.emit(event, envelope, async (encryptedResponse) => {
+      if (isTransitEnvelope(encryptedResponse)) {
+        try {
+          ack(await decryptPayload(encryptedResponse, key));
+        } catch {
+          ack(encryptedResponse);
+        }
       } else {
-        socket.emit(event, envelope);
+        ack(encryptedResponse);
       }
+    });
+  } else {
+    socket.emit(event, envelope);
+  }
+}
+async function secureEmit(socket, event, payload, ack) {
+  let key = getSessionKey();
+  if (key && isTransitEnabled()) {
+    emitEncrypted(socket, event, await encryptPayload(payload, key), key, ack);
+    return;
+  }
+  if (isTransitRequired()) {
+    try {
+      ensureRestTransitHandshake();
+    } catch {
+    }
+    const ok = await awaitTransitReadyOr(SECURE_EMIT_WAIT_MS);
+    key = getSessionKey();
+    if (ok && key && isTransitEnabled()) {
+      emitEncrypted(socket, event, await encryptPayload(payload, key), key, ack);
       return;
     }
+    if (isTransitRequired()) {
+      throw new AntzChatNetworkError(
+        `Transit encryption required but no session established \u2014 "${event}" not sent`,
+        "TRANSIT_NOT_READY",
+        { event }
+      );
+    }
   }
   if (ack) {
     socket.emit(event, payload, ack);
@@ -734,6 +403,28 @@ function secureOn(socket, event, handler) {
     handler(raw);
   });
 }
+var _joinedRooms = /* @__PURE__ */ new Set();
+function trackRoomJoin(conversationId) {
+  _joinedRooms.add(conversationId);
+}
+function trackRoomLeave(conversationId) {
+  _joinedRooms.delete(conversationId);
+}
+function resetTrackedRooms() {
+  _joinedRooms.clear();
+}
+function flushJoinedRooms() {
+  const socket = tryGetSocket();
+  if (!socket || _joinedRooms.size === 0) return;
+  for (const conversationId of _joinedRooms) {
+    void secureEmit(socket, "join_room", { conversationId }).catch(() => {
+    });
+  }
+}
+onTransitReady(flushJoinedRooms);
+onSocketStatus((status) => {
+  if (status === "connected") flushJoinedRooms();
+});
 async function connectSocket(config, getToken) {
   if (_socket && !_socket.disconnected) return _socket;
   if (_connectingPromise) return _connectingPromise;
@@ -755,6 +446,7 @@ async function _doConnect(config, getToken) {
     ...config.avatar?.url && { avatarUrl: config.avatar.url },
     ...config.avatar?.base64 && { avatarBase64: config.avatar.base64 }
   };
+  configureTransitIfUnset(config.transitEncryption);
   let boundDeriveSessionKey = null;
   if (config.transitEncryption) {
     const inFlight = getTransitHandshakePromise();
@@ -819,7 +511,6 @@ async function _doConnect(config, getToken) {
   _socket.on("connect", () => setStatus("connected"));
   _socket.on("disconnect", () => {
     setStatus("disconnected");
-    if (!_preservingSession) clearTransitSession();
   });
   _socket.on("connect_error", (err) => {
     console.error("[AntzChat] Socket connect_error:", err?.message, err?.data);
@@ -834,8 +525,9 @@ async function _doConnect(config, getToken) {
         resolve();
       };
       const timeout = setTimeout(() => {
-        console.warn("[AntzChat] transit_session timeout \u2014 unblocking HTTP without transit encryption");
-        configureTransit(false);
+        console.error(
+          "[AntzChat] transit_session did not arrive within 5s. Transit stays REQUIRED \u2014 chat requests are gated (not downgraded to plaintext) until the handshake succeeds via REST retry or socket reconnect. Persistent failure = check POST /crypto/session (rate limit / 5xx) and the socket transit middleware."
+        );
         done();
       }, 5e3);
       _socket.on("transit_session", async ({ sessionId }) => {
@@ -922,13 +614,8 @@ function reconnectSocket(token, userId, tenantId) {
         ...tenantId && { tenantId },
         transitSessionId: existing.sessionId
       };
-      _preservingSession = true;
-      try {
-        if (_socket.connected) _socket.disconnect();
-        _socket.connect();
-      } finally {
-        _preservingSession = false;
-      }
+      if (_socket.connected) _socket.disconnect();
+      _socket.connect();
       return;
     }
     if (_getToken) {
@@ -973,7 +660,15 @@ async function drainSendQueue(conversationId) {
       entry.reject(new AntzChatNetworkError("Message dropped: queued too long", "MESSAGE_DROPPED"));
       continue;
     }
-    entry.run().then(entry.resolve).catch(entry.reject);
+    let acked;
+    try {
+      ({ acked } = await emitWithAck("send_message", entry.payload));
+    } catch (err) {
+      entry.reject(err);
+      while (queue.length > 0) queue.shift().reject(err);
+      break;
+    }
+    acked.then(entry.resolve).catch(entry.reject);
   }
   sendQueues.delete(conversationId);
   sendQueueRunning.delete(conversationId);
@@ -986,7 +681,7 @@ function queueSendMessage(payload) {
     return Promise.reject(new AntzChatNetworkError("Send queue full: too many messages in flight", "SEND_QUEUE_FULL", { conversationId }));
   }
   return new Promise((resolve, reject) => {
-    queue.push({ run: () => withAck("send_message", payload), resolve, reject, enqueuedAt: Date.now() });
+    queue.push({ payload, resolve, reject, enqueuedAt: Date.now() });
     drainSendQueue(conversationId);
   });
 }
@@ -1009,91 +704,496 @@ function waitForReconnect() {
     });
   });
 }
-async function withAck(event, payload) {
+async function emitWithAck(event, payload) {
   let socket = tryGetSocket();
   if (!socket) {
     await waitForReconnect();
     socket = tryGetSocket();
   }
-  if (!socket) return Promise.reject(new AntzChatNetworkError(`Socket not connected (event: ${event})`, "SOCKET_NOT_CONNECTED", { event }));
-  return new Promise((resolve, reject) => {
-    let timer;
-    secureEmit(socket, event, payload, (response) => {
-      clearTimeout(timer);
-      resolve(response);
-    }).then(() => {
-      timer = setTimeout(() => reject(new AntzChatNetworkError(`Socket ack timeout: ${event}`, "SOCKET_TIMEOUT", { event })), ACK_TIMEOUT);
-    }).catch(reject);
+  if (!socket) throw new AntzChatNetworkError(`Socket not connected (event: ${event})`, "SOCKET_NOT_CONNECTED", { event });
+  let resolveAck;
+  let rejectAck;
+  const acked = new Promise((res, rej) => {
+    resolveAck = res;
+    rejectAck = rej;
+  });
+  await secureEmit(socket, event, payload, (response) => resolveAck(response));
+  const timer = setTimeout(
+    () => rejectAck(new AntzChatNetworkError(`Socket ack timeout: ${event}`, "SOCKET_TIMEOUT", { event })),
+    ACK_TIMEOUT
+  );
+  void acked.then(() => clearTimeout(timer), () => clearTimeout(timer));
+  return { acked };
+}
+async function withAck(event, payload) {
+  const { acked } = await emitWithAck(event, payload);
+  return acked;
+}
+function fireAndForget(event, payload) {
+  const socket = tryGetSocket();
+  if (!socket) return;
+  secureEmit(socket, event, payload).catch(() => {
   });
 }
-function fireAndForget(event, payload) {
-  const socket = tryGetSocket();
-  if (!socket) return;
-  secureEmit(socket, event, payload);
+var socketEmit = {
+  joinRoom(conversationId) {
+    trackRoomJoin(conversationId);
+    fireAndForget("join_room", { conversationId });
+  },
+  leaveRoom(conversationId) {
+    trackRoomLeave(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;
+    }
   }
 };
 
@@ -1254,6 +1354,7 @@ export {
   getSocketStatus,
   initApiClient,
   initAuthStore,
+  isApiClientConfigured,
   isMentionAll,
   isTransitEnvelope,
   messagesApi,
@@ -1266,9 +1367,11 @@ export {
   refreshSocketAuth,
   renderMentionParts,
   resetAuthStore,
+  resetTrackedRooms,
   resolveConfig,
   resolveSystemMessageText,
   setApiClientInstance,
+  setAuthReadyPromise,
   setTransitSession,
   socketEmit,
   storageApi,