@ermis-network/ermis-chat-sdk 1.0.2 → 1.0.4

package/dist/index.browser.mjs

@@ -356,15 +356,25 @@ var createForwardMessagePayload = (message, targetCid, activeCid) => {
 // src/channel_state.ts
 var ChannelState = class {
   _channel;
+  /** The current count of users actively watching (having an open WebSocket) this channel. */
   watcher_count;
+  /** A dictionary of active typing events gracefully keyed by the user's ID. */
   typing;
+  /** A dictionary of read states mapped per user's ID detailing the last viewed message. */
   read;
+  /** The locally cached array of pinned messages across the channel. */
   pinnedMessages;
+  /** A directory of users actively watching the channel, keyed by User ID. */
   watchers;
+  /** A comprehensive directory mapping user IDs to their member status in the channel. */
   members;
+  /** The count of messages not yet read by the currently authenticated user. */
   unreadCount;
+  /** Information detailing the authenticated user's own membership relation to this channel. */
   membership;
+  /** Timestamp indicating when the very last message was created in this chat. */
   last_message_at;
+  /** Designates if the local channel state is entirely synchronized with the backend history. */
   isUpToDate;
   messageSets = [];
   topics = [];
@@ -396,6 +406,15 @@ var ChannelState = class {
     const index = this.messageSets.findIndex((s) => s.isLatest);
     this.messageSets[index].messages = messages;
   }
+  /**
+   * Pushes a new message directly into the sorted array of the local tracking state.
+   * Useful to achieve optimistic UI updates locally.
+   *
+   * @param newMessage                      - The message context payload to insert.
+   * @param timestampChanged                - Specifies if the underlying `created_at` timestamp mutated.
+   * @param addIfDoesNotExist               - Append it strictly if its ID doesn't already exist.
+   * @param messageSetToAddToIfDoesNotExist - Specifies which message set scope to manipulate.
+   */
   addMessageSorted(newMessage, timestampChanged = false, addIfDoesNotExist = true, messageSetToAddToIfDoesNotExist = "latest") {
     return this.addMessagesSorted(
       [newMessage],
@@ -583,6 +602,12 @@ var ChannelState = class {
     const result = msgArray.filter((message) => !(!!message.id && !!msg.id && message.id === msg.id));
     return { removed: result.length < msgArray.length, result };
   };
+  /**
+   * Refreshes internal user references cascading across all presently active messages.
+   * Invoked instantly whenever an underlying user's profile metadata updates (e.g. name or avatar changes).
+   *
+   * @param user - The newly formatted and populated User details object.
+   */
   updateUserMessages = (user) => {
     const _updateUserMessages = (messages, user2) => {
       for (let i = 0; i < messages.length; i++) {
@@ -854,6 +879,15 @@ var Channel = class {
   lastTypingEvent;
   isTyping;
   disconnected;
+  /**
+   * Initializes a new Channel class instance.
+   * Normally you should not call this directly; use `client.channel(type, id)` instead.
+   *
+   * @param client - The shared ErmisChat client instance initializing this channel.
+   * @param type   - The type of channel (`messaging`, `team`, `livestream`, etc.).
+   * @param id     - The unique ID of the channel.
+   * @param data   - Initial arbitrary metadata stored within this channel.
+   */
   constructor(client, type, id, data) {
     const validTypeRe = /^[\w_-]+$/;
     const validIDRe = /^[\w!:_-]+$/;
@@ -880,6 +914,13 @@ var Channel = class {
   getClient() {
     return this._client;
   }
+  /**
+   * Sends a message to this channel.
+   * By default, it pushes the message eagerly (optimistically) to the local UI state before the server replies.
+   *
+   * @param message - The constructed text/attachment object payload representing the message.
+   * @returns       A Promise resolving to the exact API response encompassing message details.
+   */
   async sendMessage(message) {
     if (!message.id) {
       message = { ...message, id: randomId() };
@@ -1109,6 +1150,11 @@ var Channel = class {
     const url = this.getClient().baseURL + `/invites/${this.type}/${this.id}/skip`;
     return this.getClient().post(url);
   }
+  /**
+   * Directly invites or adds registered users into this channel.
+   *
+   * @param members - Array of user IDs explicitly selected to be added.
+   */
   async addMembers(members) {
     return await this._update({ add_members: members });
   }
@@ -1174,6 +1220,11 @@ var Channel = class {
       })
     };
   }
+  /**
+   * Expels specified currently participating users out of the channel.
+   *
+   * @param members - Array of user IDs to strictly remove from this chat.
+   */
   async removeMembers(members) {
     return await this._update({ remove_members: members });
   }
@@ -1253,6 +1304,10 @@ var Channel = class {
     messageSlice.sort((a, b) => b.created_at.getTime() - a.created_at.getTime());
     return messageSlice[0];
   }
+  /**
+   * Emits a mark-read event, updating the backend that the authenticated user has viewed up to the latest known message.
+   * @returns Successful acknowledgement from the server.
+   */
   async markRead() {
     return await this.getClient().post(this._channelURL() + "/read");
   }
@@ -1266,6 +1321,13 @@ var Channel = class {
     }
     this.state.clean();
   }
+  /**
+   * Subscribes to realtime events (WebSocket) for this channel, grabs the latest available metadata,
+   * loads the most recent messages, and initializes the local state.
+   *
+   * @param options - Pagination limits like `{ watch: true, presence: true, state: true }`.
+   * @returns         The synchronized comprehensive channel state.
+   */
   async watch(options) {
     await this.getClient().wsPromise;
     const combined = { ...options };
@@ -2703,32 +2765,55 @@ function isString(x) {
 var ErmisChat = class _ErmisChat {
   static _instance;
   // type is undefined|ErmisChat, unknown is due to TS limitations with statics
+  /** A map of active channels currently tracked by the client, keyed by Channel ID. */
   activeChannels;
+  /** The internal configured Axios instance used for REST API requests. */
   axiosInstance;
+  /** The primary base URL for REST API communication. */
   baseURL;
+  /** The specific base URL for standard user-focused REST calls. */
   userBaseURL;
+  /** True when the SDK is executed inside a browser environment. */
   browser;
   cleaningIntervalRef;
   clientID;
   apiKey;
   projectId;
+  /** Internal mapped registry of event listeners. */
   listeners;
   logger;
+  /** Whether the client should automatically fetch missing messages upon unexpected disconnects. */
   recoverStateOnReconnect;
+  /** True when the SDK is executed in a NodeJS environment constraint. */
   node;
+  /** Custom options passed during client initialization. */
   options;
   setUserPromise;
+  /** Centralized global state orchestrating user and client metadata. */
   state;
   tokenManager;
+  /** The globally authenticated current user object. */
   user;
   userAgent;
+  /** The unique ID of the current authenticated user. */
   userID;
+  /** The configured WebSocket endpoint base URL for realtime subscriptions. */
   wsBaseURL;
+  /** The active WebSocket connection controller. */
   wsConnection;
   wsPromise;
+  /** Tracks consecutive REST API failures for exponential backoff purposes. */
   consecutiveFailures;
   defaultWSTimeout;
   eventSource = null;
+  /**
+   * Initializes a new Ermis Chat Client instance.
+   *
+   * @param apiKey    - Your public Ermis Network API Key.
+   * @param projectId - Your specific Project UUID pointing to the app config.
+   * @param baseURL   - The API base endpoint assigned to your project.
+   * @param options   - Additional connection rules and configuration options.
+   */
   constructor(apiKey, projectId, baseURL, options) {
     this.apiKey = apiKey;
     this.projectId = projectId;
@@ -2762,6 +2847,16 @@ var ErmisChat = class _ErmisChat {
     this.logger = isFunction(inputOptions.logger) ? inputOptions.logger : () => null;
     this.recoverStateOnReconnect = this.options.recoverStateOnReconnect;
   }
+  /**
+   * Retrieves the globally registered Singleton instance of the ErmisChat client.
+   * If the instance lacks existence, it initializes a new one.
+   *
+   * @param key       - Your public Ermis Network API Key.
+   * @param projectId - Your specific Project UUID.
+   * @param baseURL   - The API base endpoint.
+   * @param options   - Connection options.
+   * @returns           The shared ErmisChat client instance.
+   */
   static getInstance(key, projectId, baseURL, options) {
     if (!_ErmisChat._instance) {
       _ErmisChat._instance = new _ErmisChat(key, projectId, baseURL, options);
@@ -2809,6 +2904,15 @@ var ErmisChat = class _ErmisChat {
     }
     return await response.json();
   }
+  /**
+   * Connects a user to the Ermis network and establishes the WebSocket connection.
+   * This is the primary method to authenticate your client application.
+   *
+   * @param user                - The User object containing `id`, `name`, and optional `avatar`.
+   * @param userTokenOrProvider - The JWT token or an async token provider function.
+   * @param extenal_auth        - Set to `true` to use your custom backend external authentication flow.
+   * @returns                     A promise resolving to the API connection response once authenticated.
+   */
   connectUser = async (user, userTokenOrProvider, extenal_auth) => {
     this.logger("info", "client:connectUser() - started", {
       tags: ["connection", "client"]
@@ -2891,6 +2995,12 @@ var ErmisChat = class _ErmisChat {
     return this.wsPromise;
   };
   _setupConnection = this.openConnection;
+  /**
+   * Gracefully disconnects the current user, terminates the WebSocket connection,
+   * cleans up listeners, and resets the client's internal references.
+   *
+   * @param timeout - Optional timeout in milliseconds before forcing the disconnect.
+   */
   disconnectUser = async (timeout) => {
     this.logger("info", "client:disconnect() - Disconnecting the client", {
       tags: ["connection", "client"]
@@ -3456,6 +3566,16 @@ var ErmisChat = class _ErmisChat {
     this.state.updateUser(response);
     return response;
   }
+  /**
+   * Queries the API for a list of channels based on provided search filters and sort conditions.
+   * Also hydrates these channels into the local SDK state memory.
+   *
+   * @param filterConditions - Specific criteria to filter channels (e.g. `{ type: 'messaging', members: { $in: ['user1'] } }`).
+   * @param sort             - The sorting hierarchy applied to the channel results.
+   * @param options          - Pagination and message limit parameters.
+   * @param stateOptions     - Defines whether to skip state initialization or offline usage.
+   * @returns                  An array of hydrated and locally manageable `Channel` objects.
+   */
   async queryChannels(filterConditions, sort = [], options = {}, stateOptions = {}) {
     await this.wsPromise;
     let project_id = this.projectId;
@@ -3607,7 +3727,7 @@ var ErmisChat = class _ErmisChat {
     return pinExpires;
   }
   getUserAgent() {
-    return this.userAgent || `ermis-chat-sdk-javascript-client-${this.node ? "node" : "browser"}-${"1.0.2"}`;
+    return this.userAgent || `ermis-chat-sdk-javascript-client-${this.node ? "node" : "browser"}-${"1.0.4"}`;
   }
   setUserAgent(userAgent) {
     this.userAgent = userAgent;
@@ -6316,21 +6436,38 @@ var ErmisCallNode = class {
     const mediaConstraints = await this.getMediaConstraints();
     try {
       const stream = await navigator.mediaDevices.getUserMedia(mediaConstraints);
-      if (this.callStatus === "ended" /* ENDED */) {
-        stream.getTracks().forEach((track) => track.stop());
-        this.destroy();
-        return;
+      return this.applyLocalStream(stream);
+    } catch (error) {
+      console.warn("Error getting user media:", error?.message);
+      if (this.callType === "video" && mediaConstraints.video) {
+        try {
+          const audioOnlyStream = await navigator.mediaDevices.getUserMedia({
+            audio: mediaConstraints.audio,
+            video: false
+          });
+          this.setConnectionMessage("Camera not available, using audio only");
+          return this.applyLocalStream(audioOnlyStream);
+        } catch {
+        }
       }
-      if (this.onLocalStream) {
-        this.onLocalStream(stream);
+      if (typeof this.onError === "function") {
+        this.onError("No microphone or camera found. Please check your device.");
       }
-      this.localStream = stream;
-      return stream;
-    } catch (error) {
-      console.error("Error getting user media:", error);
       return null;
     }
   }
+  applyLocalStream(stream) {
+    if (this.callStatus === "ended" /* ENDED */) {
+      stream.getTracks().forEach((track) => track.stop());
+      this.destroy();
+      return;
+    }
+    if (this.onLocalStream) {
+      this.onLocalStream(stream);
+    }
+    this.localStream = stream;
+    return stream;
+  }
   setConnectionMessage(message) {
     if (typeof this.onConnectionMessageChange === "function") {
       this.onConnectionMessageChange(message);
@@ -6375,20 +6512,10 @@ var ErmisCallNode = class {
           this.isDestroyed = false;
           this.callStatus = "";
           this.callType = is_video ? "video" : "audio";
-          await this.startLocalStream();
-          if (this.callStatus === "ended" /* ENDED */) return;
           this.setUserInfo(cid, eventUserId);
           this.setCallStatus("ringing" /* RINGING */);
           this.cid = cid || "";
           this.metadata = metadata || {};
-          console.log("----metadata---", metadata);
-          if (eventUserId !== this.userID) {
-            await this.initialize();
-          }
-          if (this.localStream && this.mediaSender && this.mediaReceiver) {
-            this.mediaSender?.initEncoders(this.localStream);
-            this.mediaReceiver?.initDecoders(this.callType);
-          }
           if (typeof this.onCallEvent === "function") {
             this.onCallEvent({
               type: eventUserId !== this.userID ? "incoming" : "outgoing",
@@ -6399,6 +6526,15 @@ var ErmisCallNode = class {
               metadata: this.metadata
             });
           }
+          await this.startLocalStream();
+          if (this.callStatus === "ended" /* ENDED */) return;
+          if (eventUserId !== this.userID) {
+            await this.initialize();
+          }
+          if (this.localStream && this.mediaSender && this.mediaReceiver) {
+            this.mediaSender?.initEncoders(this.localStream);
+            this.mediaReceiver?.initDecoders(this.callType);
+          }
           if (eventUserId === this.userID) {
             if (this.missCallTimeout) clearTimeout(this.missCallTimeout);
             this.missCallTimeout = setTimeout(async () => {
@@ -6659,21 +6795,30 @@ var ErmisCallNode = class {
   }
   async stopScreenShare() {
     const mediaConstraints = await this.getMediaConstraints();
-    const cameraStream = await navigator.mediaDevices.getUserMedia(mediaConstraints);
-    const cameraTrack = cameraStream.getVideoTracks()[0];
-    if (this.localStream) {
-      this.localStream.getVideoTracks().forEach((track) => track.stop());
-      this.localStream.removeTrack(this.localStream.getVideoTracks()[0]);
-      this.localStream.addTrack(cameraTrack);
-    } else {
-      this.localStream = cameraStream;
-    }
-    if (this.onLocalStream) {
-      this.onLocalStream(this.localStream);
-      this.mediaSender?.replaceVideoTrack(this.localStream.getVideoTracks()[0]);
-    }
-    if (typeof this.onScreenShareChange === "function") {
-      this.onScreenShareChange(false);
+    try {
+      const cameraStream = await navigator.mediaDevices.getUserMedia({
+        video: mediaConstraints.video,
+        audio: false
+      });
+      const cameraTrack = cameraStream.getVideoTracks()[0];
+      if (this.localStream) {
+        this.localStream.getVideoTracks().forEach((track) => {
+          track.stop();
+          this.localStream?.removeTrack(track);
+        });
+        this.localStream.addTrack(cameraTrack);
+      } else {
+        this.localStream = cameraStream;
+      }
+      if (this.onLocalStream) {
+        this.onLocalStream(this.localStream);
+        this.mediaSender?.replaceVideoTrack(this.localStream.getVideoTracks()[0]);
+      }
+      if (typeof this.onScreenShareChange === "function") {
+        this.onScreenShareChange(false);
+      }
+    } catch (error) {
+      console.error("Error stopping screen share and reverting to camera:", error);
     }
   }
   async toggleMic(enabled) {
@@ -6940,7 +7085,7 @@ var ErmisAuthProvider = class {
     return data;
   }
   getUserAgent() {
-    return this.userAgent || `ermis-chat-sdk-javascript-client-${this.node ? "node" : "browser"}-${"1.0.2"}`;
+    return this.userAgent || `ermis-chat-sdk-javascript-client-${this.node ? "node" : "browser"}-${"1.0.4"}`;
   }
   setUserAgent(userAgent) {
     this.userAgent = userAgent;
@@ -7173,70 +7318,116 @@ function parseSystemMessage(value, userMap) {
 }
 
 // src/signal_message.ts
-function formatDuration(durationSec) {
-  const sec = parseInt(durationSec, 10);
-  if (isNaN(sec) || sec < 0) return durationSec;
-  const minutes = Math.floor(sec / 60);
-  const seconds = sec % 60;
-  return `${minutes}:${seconds.toString().padStart(2, "0")}`;
-}
-function resolveUser2(userId, userMap) {
-  return userMap[userId] ?? userId;
+var CallType = {
+  AUDIO: "audio",
+  VIDEO: "video"
+};
+function formatDuration(durationMs) {
+  if (!durationMs) return "";
+  const ms = parseInt(durationMs, 10);
+  if (isNaN(ms) || ms <= 0) return "";
+  const totalSeconds = Math.floor(ms / 1e3);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes} min, ${seconds} sec`;
 }
-function parseSignalMessage(value, userMap) {
-  if (!value || typeof value !== "string") return value ?? "";
+function parseSignalMessage(value, myUserId) {
+  if (!value || typeof value !== "string") return null;
   const trimmed = value.trim();
-  if (!trimmed) return "";
+  if (!trimmed) return null;
   const parts = trimmed.split(" ");
-  const formatId = parts[0];
-  const userId = parts[1] ?? "";
-  const userName = userId ? resolveUser2(userId, userMap) : "User";
-  switch (formatId) {
-    // 1: Audio call started
-    case "1":
-      return `\u{1F4DE} ${userName} started an audio call.`;
-    // 2: Audio call missed
-    case "2":
-      return `\u{1F4DE} Missed audio call from ${userName}.`;
-    // 3: Audio call ended (caller_id ender_id duration)
-    case "3": {
-      const enderId = parts[2] ?? "";
-      const duration = parts[3] ?? "0";
-      const enderName = enderId ? resolveUser2(enderId, userMap) : "User";
-      return `\u{1F4DE} Audio call by ${userName}, ended by ${enderName}. Duration: ${formatDuration(duration)}.`;
-    }
-    // 4: Video call started
-    case "4":
-      return `\u{1F4F9} ${userName} started a video call.`;
-    // 5: Video call missed
-    case "5":
-      return `\u{1F4F9} Missed video call from ${userName}.`;
-    // 6: Video call ended (caller_id ender_id duration)
-    case "6": {
-      const enderId = parts[2] ?? "";
-      const duration = parts[3] ?? "0";
-      const enderName = enderId ? resolveUser2(enderId, userMap) : "User";
-      return `\u{1F4F9} Video call by ${userName}, ended by ${enderName}. Duration: ${formatDuration(duration)}.`;
-    }
-    // 7: Audio call rejected
-    case "7":
-      return `\u{1F4DE} Audio call from ${userName} was rejected.`;
-    // 8: Video call rejected
-    case "8":
-      return `\u{1F4F9} Video call from ${userName} was rejected.`;
-    // 9: Audio call busy
-    case "9":
-      return `\u{1F4DE} Audio call from ${userName} \u2014 recipient was busy.`;
-    // 10: Video call busy
-    case "10":
-      return `\u{1F4F9} Video call from ${userName} \u2014 recipient was busy.`;
+  const number = parseInt(parts[0], 10);
+  const callerId = parts[1] ?? "";
+  const isMe = myUserId === callerId;
+  let enderId = "";
+  let duration = "";
+  let callType = "";
+  let color = "";
+  if (number === 3 || number === 6) {
+    enderId = parts[2] ?? "";
+    duration = parts[3] === "0" ? "" : parts[3] ?? "";
+  }
+  let text;
+  switch (number) {
+    case 1:
+      text = isMe ? "Calling..." : "Incoming audio call...";
+      callType = CallType.AUDIO;
+      color = "#54D62C";
+      break;
+    case 2:
+      text = isMe ? "Outgoing audio call" : "You missed audio call";
+      callType = CallType.AUDIO;
+      color = "#FF4842";
+      break;
+    case 3:
+      if (duration) {
+        text = isMe ? "Outgoing audio call" : "Incoming audio call";
+        color = "#54D62C";
+      } else {
+        if (enderId === myUserId) {
+          text = "You cancel audio call";
+        } else {
+          text = "You missed audio call";
+        }
+        color = "#FF4842";
+      }
+      callType = CallType.AUDIO;
+      break;
+    case 4:
+      text = isMe ? "Calling..." : "Incoming video call...";
+      callType = CallType.VIDEO;
+      color = "#54D62C";
+      break;
+    case 5:
+      text = isMe ? "Outgoing video call" : "You missed video call";
+      callType = CallType.VIDEO;
+      color = "#FF4842";
+      break;
+    case 6:
+      if (duration) {
+        text = isMe ? "Outgoing video call" : "Incoming video call";
+        color = "#54D62C";
+      } else {
+        if (enderId === myUserId) {
+          text = "You cancel video call";
+        } else {
+          text = "You missed video call";
+        }
+        color = "#FF4842";
+      }
+      callType = CallType.VIDEO;
+      break;
+    case 7:
+      text = isMe ? "Recipient rejected audio call" : "You rejected audio call";
+      callType = CallType.AUDIO;
+      color = "#FF4842";
+      break;
+    case 8:
+      text = isMe ? "Recipient rejected video call" : "You rejected video call";
+      callType = CallType.VIDEO;
+      color = "#FF4842";
+      break;
+    case 9:
+      text = isMe ? "Recipient was busy" : "You missed audio call";
+      callType = CallType.AUDIO;
+      color = "#FF4842";
+      break;
+    case 10:
+      text = isMe ? "Recipient was busy" : "You missed video call";
+      callType = CallType.VIDEO;
+      color = "#FF4842";
+      break;
     default:
-      return trimmed;
+      text = trimmed;
+      callType = "";
+      color = "";
   }
+  return { text, duration: formatDuration(duration), callType, color };
 }
 export {
   CallAction,
   CallStatus,
+  CallType,
   Channel,
   ChannelState,
   ClientState,