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

package/dist/index.mjs

@@ -354,15 +354,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 = [];
@@ -394,6 +404,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],
@@ -581,6 +600,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++) {
@@ -852,6 +877,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!:_-]+$/;
@@ -878,6 +912,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() };
@@ -1107,6 +1148,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 });
   }
@@ -1172,6 +1218,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 });
   }
@@ -1251,6 +1302,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");
   }
@@ -1264,6 +1319,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 };
@@ -2701,32 +2763,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;
@@ -2760,6 +2845,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);
@@ -2807,6 +2902,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"]
@@ -2889,6 +2993,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"]
@@ -3454,6 +3564,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;
@@ -3605,7 +3725,7 @@ var ErmisChat = class _ErmisChat {
     return pinExpires;
   }
   getUserAgent() {
-    return this.userAgent || `ermis-chat-sdk-javascript-client-${this.node ? "node" : "browser"}-${"1.0.3"}`;
+    return this.userAgent || `ermis-chat-sdk-javascript-client-${this.node ? "node" : "browser"}-${"1.0.4"}`;
   }
   setUserAgent(userAgent) {
     this.userAgent = userAgent;
@@ -6964,7 +7084,7 @@ var ErmisAuthProvider = class {
     return data;
   }
   getUserAgent() {
-    return this.userAgent || `ermis-chat-sdk-javascript-client-${this.node ? "node" : "browser"}-${"1.0.3"}`;
+    return this.userAgent || `ermis-chat-sdk-javascript-client-${this.node ? "node" : "browser"}-${"1.0.4"}`;
   }
   setUserAgent(userAgent) {
     this.userAgent = userAgent;