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

package/dist/index.d.mts

@@ -664,18 +664,30 @@ type ChannelReadStatus<ErmisChatGenerics extends ExtendableGenerics = DefaultGen
 }>;
 /**
  * ChannelState - A container class for the channel state.
+ * This class synchronously binds to a `Channel` and holds the single source of truth for
+ * messages, read status, watchers, and typing indicators locally on the client.
  */
 declare class ChannelState<ErmisChatGenerics extends ExtendableGenerics = DefaultGenerics> {
     _channel: Channel<ErmisChatGenerics>;
+    /** The current count of users actively watching (having an open WebSocket) this channel. */
     watcher_count: number;
+    /** A dictionary of active typing events gracefully keyed by the user's ID. */
     typing: Record<string, Event$1<ErmisChatGenerics>>;
+    /** A dictionary of read states mapped per user's ID detailing the last viewed message. */
     read: ChannelReadStatus<ErmisChatGenerics>;
+    /** The locally cached array of pinned messages across the channel. */
     pinnedMessages: Array<ReturnType<ChannelState<ErmisChatGenerics>['formatMessage']>>;
+    /** A directory of users actively watching the channel, keyed by User ID. */
     watchers: Record<string, UserResponse<ErmisChatGenerics>>;
+    /** A comprehensive directory mapping user IDs to their member status in the channel. */
     members: Record<string, ChannelMemberResponse<ErmisChatGenerics>>;
+    /** The count of messages not yet read by the currently authenticated user. */
     unreadCount: number;
+    /** Information detailing the authenticated user's own membership relation to this channel. */
     membership: ChannelMembership<ErmisChatGenerics>;
+    /** Timestamp indicating when the very last message was created in this chat. */
     last_message_at: Date | null;
+    /** Designates if the local channel state is entirely synchronized with the backend history. */
     isUpToDate: boolean;
     messageSets: {
         isCurrent: boolean;
@@ -688,6 +700,15 @@ declare class ChannelState<ErmisChatGenerics extends ExtendableGenerics = Defaul
     set messages(messages: Array<ReturnType<ChannelState<ErmisChatGenerics>['formatMessage']>>);
     get latestMessages(): Array<ReturnType<ChannelState<ErmisChatGenerics>["formatMessage"]>>;
     set latestMessages(messages: Array<ReturnType<ChannelState<ErmisChatGenerics>['formatMessage']>>);
+    /**
+     * 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: MessageResponse<ErmisChatGenerics>, timestampChanged?: boolean, addIfDoesNotExist?: boolean, messageSetToAddToIfDoesNotExist?: MessageSetType): {
         messageSet: {
             isCurrent: boolean;
@@ -734,6 +755,12 @@ declare class ChannelState<ErmisChatGenerics extends ExtendableGenerics = Defaul
         removed: boolean;
         result: FormatMessageResponse<ErmisChatGenerics>[];
     };
+    /**
+     * 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: UserResponse<ErmisChatGenerics>) => void;
     deleteUserMessages: (user: UserResponse<ErmisChatGenerics>, hardDelete?: boolean) => void;
     filterErrorMessages(): void;
@@ -786,6 +813,11 @@ type VoiceRecordingMeta = {
  */
 declare function buildAttachmentPayload(file: File, uploadedUrl: string, thumbUrl?: string, voiceMeta?: VoiceRecordingMeta): Attachment;
 
+/**
+ * Represents a Channel in the Ermis Network.
+ * Channels handle chat sessions, livestream messages, teams, or video calls.
+ * This class abstracts and exposes all API operations you can perform on a specific channel instance.
+ */
 declare class Channel<ErmisChatGenerics extends ExtendableGenerics = DefaultGenerics> {
     _client: ErmisChat<ErmisChatGenerics>;
     type: string;
@@ -803,8 +835,24 @@ declare class Channel<ErmisChatGenerics extends ExtendableGenerics = DefaultGene
     lastTypingEvent: Date | null;
     isTyping: boolean;
     disconnected: boolean;
+    /**
+     * 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: ErmisChat<ErmisChatGenerics>, type: string, id: string | undefined, data: ChannelData<ErmisChatGenerics>);
     getClient(): ErmisChat<ErmisChatGenerics>;
+    /**
+     * 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.
+     */
     sendMessage(message: Message<ErmisChatGenerics>): Promise<SendMessageAPIResponse<ErmisChatGenerics>>;
     retryMessage(messageId: string): Promise<SendMessageAPIResponse<ErmisChatGenerics>>;
     createPoll(pollMessage: PollMessage): Promise<SendMessageAPIResponse<ErmisChatGenerics>>;
@@ -846,6 +894,11 @@ declare class Channel<ErmisChatGenerics extends ExtendableGenerics = DefaultGene
     acceptInvite(action: string): Promise<APIResponse>;
     rejectInvite(): Promise<APIResponse>;
     skipInvite(): Promise<APIResponse>;
+    /**
+     * Directly invites or adds registered users into this channel.
+     *
+     * @param members - Array of user IDs explicitly selected to be added.
+     */
     addMembers(members: string[]): Promise<UpdateChannelAPIResponse<ErmisChatGenerics>>;
     addModerators(members: string[]): Promise<UpdateChannelAPIResponse<ErmisChatGenerics>>;
     banMembers(members: string[]): Promise<UpdateChannelAPIResponse<ErmisChatGenerics>>;
@@ -863,6 +916,11 @@ declare class Channel<ErmisChatGenerics extends ExtendableGenerics = DefaultGene
     setSlowMode(cooldown: 0 | 10000 | 30000 | 60000 | 300000 | 900000 | 3600000): Promise<UpdateChannelAPIResponse<ErmisChatGenerics>>;
     queryAttachmentMessages(): Promise<AttachmentResponse<ErmisChatGenerics>>;
     searchMessage(search_term: string, offset: number): Promise<any>;
+    /**
+     * Expels specified currently participating users out of the channel.
+     *
+     * @param members - Array of user IDs to strictly remove from this chat.
+     */
     removeMembers(members: string[]): Promise<UpdateChannelAPIResponse<ErmisChatGenerics>>;
     demoteModerators(members: string[]): Promise<UpdateChannelAPIResponse<ErmisChatGenerics>>;
     _update(payload: Object): Promise<UpdateChannelAPIResponse<ErmisChatGenerics>>;
@@ -877,8 +935,19 @@ declare class Channel<ErmisChatGenerics extends ExtendableGenerics = DefaultGene
     }): Promise<void>;
     _isTypingIndicatorsEnabled(): boolean;
     lastMessage(): FormatMessageResponse<ErmisChatGenerics>;
+    /**
+     * 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.
+     */
     markRead(): Promise<unknown>;
     clean(): void;
+    /**
+     * 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.
+     */
     watch(options?: ChannelQueryOptions): Promise<QueryChannelAPIResponse<ErmisChatGenerics>>;
     lastRead(): Date | null | undefined;
     _countMessageAsUnread(message: FormatMessageResponse<ErmisChatGenerics> | MessageResponse<ErmisChatGenerics>): boolean;
@@ -978,42 +1047,91 @@ declare class TokenManager<ErmisChatGenerics extends ExtendableGenerics = Defaul
     getToken: () => string | undefined;
 }
 
+/**
+ * The ErmisChat Client represents the connection securely established between your application
+ * and the Ermis core servers. It acts as the primary access point for real-time messaging,
+ * presence updates, call management, and channel querying.
+ *
+ * It is highly recommended to instantiate this class as a Singleton via `ErmisChat.getInstance()`.
+ */
 declare class ErmisChat<ErmisChatGenerics extends ExtendableGenerics = DefaultGenerics> {
     private static _instance?;
+    /** A map of active channels currently tracked by the client, keyed by Channel ID. */
     activeChannels: {
         [key: string]: Channel<ErmisChatGenerics>;
     };
+    /** The internal configured Axios instance used for REST API requests. */
     axiosInstance: AxiosInstance;
+    /** The primary base URL for REST API communication. */
     baseURL?: string;
+    /** The specific base URL for standard user-focused REST calls. */
     userBaseURL?: string;
+    /** True when the SDK is executed inside a browser environment. */
     browser: boolean;
     cleaningIntervalRef?: NodeJS.Timeout;
     clientID?: string;
     apiKey: string;
     projectId: string;
+    /** Internal mapped registry of event listeners. */
     listeners: Record<string, Array<(event: Event$1<ErmisChatGenerics>) => void>>;
     logger: Logger;
+    /** Whether the client should automatically fetch missing messages upon unexpected disconnects. */
     recoverStateOnReconnect?: boolean;
+    /** True when the SDK is executed in a NodeJS environment constraint. */
     node: boolean;
+    /** Custom options passed during client initialization. */
     options: ErmisChatOptions;
     setUserPromise: ConnectAPIResponse<ErmisChatGenerics> | null;
+    /** Centralized global state orchestrating user and client metadata. */
     state: ClientState<ErmisChatGenerics>;
     tokenManager: TokenManager<ErmisChatGenerics>;
+    /** The globally authenticated current user object. */
     user?: UserResponse<ErmisChatGenerics>;
     userAgent?: string;
+    /** The unique ID of the current authenticated user. */
     userID?: string;
+    /** The configured WebSocket endpoint base URL for realtime subscriptions. */
     wsBaseURL?: string;
+    /** The active WebSocket connection controller. */
     wsConnection: StableWSConnection<ErmisChatGenerics> | null;
     wsPromise: ConnectAPIResponse<ErmisChatGenerics> | null;
+    /** Tracks consecutive REST API failures for exponential backoff purposes. */
     consecutiveFailures: number;
     defaultWSTimeout: number;
     private eventSource;
+    /**
+     * 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: string, projectId: string, baseURL: string, options?: ErmisChatOptions);
+    /**
+     * 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<ErmisChatGenerics extends ExtendableGenerics = DefaultGenerics>(key: string, projectId: string, baseURL: string, options?: ErmisChatOptions): ErmisChat<ErmisChatGenerics>;
     refreshNewToken(refresh_token: string): Promise<APIResponse>;
     getAuthType(): string;
     setBaseURL(baseURL: string): void;
     getExternalAuthToken(user: UserResponse<ErmisChatGenerics>, token: string | null): Promise<any>;
+    /**
+     * 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: (user: UserResponse<ErmisChatGenerics>, userTokenOrProvider: string | null, extenal_auth?: boolean) => Promise<void | ConnectionOpen<ErmisChatGenerics>>;
     setUser: (user: UserResponse<ErmisChatGenerics>, userTokenOrProvider: string | null, extenal_auth?: boolean) => Promise<void | ConnectionOpen<ErmisChatGenerics>>;
     _setToken: (user: UserResponse<ErmisChatGenerics>, userTokenOrProvider: string | null) => Promise<void>;
@@ -1021,15 +1139,44 @@ declare class ErmisChat<ErmisChatGenerics extends ExtendableGenerics = DefaultGe
     closeConnection: (timeout?: number) => Promise<void>;
     openConnection: () => Promise<void | ConnectionOpen<ErmisChatGenerics>>;
     _setupConnection: () => Promise<void | ConnectionOpen<ErmisChatGenerics>>;
+    /**
+     * 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: (timeout?: number) => Promise<void>;
     disconnect: (timeout?: number) => Promise<void>;
+    /**
+     * Attaches an event listener to the client connection.
+     * Listeners can be scoped to specific event types (e.g. `message.new`) or listen to `all` events.
+     *
+     * @param callback - The handler invoked when the event is emitted.
+     * @returns An object containing an `unsubscribe` method to detach the listener.
+     */
     on(callback: EventHandler<ErmisChatGenerics>): {
         unsubscribe: () => void;
     };
+    /**
+     * Attaches an event listener filtered by a specific event type.
+     *
+     * @param eventType - The specific event name to listen for (e.g., `'notification.message_new'`).
+     * @param callback  - The handler invoked when the event is emitted.
+     * @returns An object containing an `unsubscribe` method to detach the listener.
+     */
     on(eventType: string, callback: EventHandler<ErmisChatGenerics>): {
         unsubscribe: () => void;
     };
+    /**
+     * Detaches a previously registered general event listener.
+     * @param callback - The original handler reference to remove.
+     */
     off(callback: EventHandler<ErmisChatGenerics>): void;
+    /**
+     * Detaches a previously registered event listener scoped to a specific event type.
+     * @param eventType - The specific event name.
+     * @param callback  - The original handler reference to remove.
+     */
     off(eventType: string, callback: EventHandler<ErmisChatGenerics>): void;
     _logApiRequest(type: string, url: string, data: unknown, config: AxiosRequestConfig & {
         config?: AxiosRequestConfig & {
@@ -1075,6 +1222,16 @@ declare class ErmisChat<ErmisChatGenerics extends ExtendableGenerics = DefaultGe
         avatar: string;
     }>;
     updateProfile(name: string, about_me: string): Promise<UserResponse<ErmisChatGenerics>>;
+    /**
+     * 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.
+     */
     queryChannels(filterConditions: ChannelFilters, sort?: ChannelSort, options?: {
         message_limit?: number;
     }, stateOptions?: ChannelStateOptions): Promise<Channel<ErmisChatGenerics>[]>;
@@ -1085,7 +1242,23 @@ declare class ErmisChat<ErmisChatGenerics extends ExtendableGenerics = DefaultGe
     searchPublicChannel(search_term: string, offset?: number, limit?: number): Promise<APIResponse>;
     pinChannel(channelType: string, channelId: string): Promise<APIResponse>;
     unpinChannel(channelType: string, channelId: string): Promise<APIResponse>;
+    /**
+     * Creates or instantiates an interactive `Channel` object locally based on type and custom data.
+     * This does NOT immediately ping the API unless `channel.watch()` or `channel.create()` is subsequently called.
+     *
+     * @param type   - The strict channel type descriptor (e.g., `'messaging'`, `'team'`, `'livestream'`).
+     * @param custom - Initial metadata or specific members to include in the channel.
+     * @returns        A newly instantiated `Channel` object.
+     */
     channel(type: string, custom?: ChannelData<ErmisChatGenerics>): Channel<ErmisChatGenerics>;
+    /**
+     * Creates or instantiates an interactive `Channel` object locally using a specific ID.
+     *
+     * @param type   - The strict channel type descriptor.
+     * @param id     - The unique identifer (UUID / slug) for the channel.
+     * @param custom - Initial metadata or specific members to include in the channel.
+     * @returns        A newly instantiated `Channel` object.
+     */
     channel(type: string, id: string, custom?: ChannelData<ErmisChatGenerics>): Channel<ErmisChatGenerics>;
     getChannelById: (channelType: string, channelID: string | undefined, custom: ChannelData<ErmisChatGenerics>) => Channel<ErmisChatGenerics>;
     getChannel: (channelType: string, custom: ChannelData<ErmisChatGenerics>) => Channel<ErmisChatGenerics>;
@@ -1281,6 +1454,7 @@ declare class ErmisCallNode<ErmisChatGenerics extends ExtendableGenerics = Defau
     private getAvailableDevices;
     private getMediaConstraints;
     startLocalStream(): Promise<MediaStream | null | undefined>;
+    private applyLocalStream;
     private setConnectionMessage;
     private setCallStatus;
     private setUserInfo;
@@ -1456,15 +1630,33 @@ declare const createForwardMessagePayload: <ErmisChatGenerics extends Extendable
 declare function parseSystemMessage(value: string, userMap: Record<string, string>): string;
 
 /**
- * Parse a raw signal message string into a human-readable English sentence.
+ * Call type constants for signal messages.
+ */
+declare const CallType: {
+    readonly AUDIO: "audio";
+    readonly VIDEO: "video";
+};
+type CallTypeValue = (typeof CallType)[keyof typeof CallType];
+/**
+ * Result of parsing a signal message.
+ */
+interface SignalMessageResult {
+    text: string;
+    duration: string;
+    callType: CallTypeValue | '';
+    color: string;
+}
+/**
+ * Parse a raw signal message string into a structured object
+ * containing text, duration, call type, and color.
  *
  * Signal messages represent call events. The raw format is:
- * `"<formatId> <userID> [<param1> <param2> ...]"`
+ * `"<formatId> <callerId> [<enderId> <duration>]"`
  *
- * @param value   - Raw signal message string from the server
- * @param userMap - Mapping of user IDs → display names
- * @returns         Parsed English text, or the original string if unknown
+ * @param value    - Raw signal message string from the server
+ * @param myUserId - The current user's ID (from client.userID)
+ * @returns          Parsed signal message object, or null if input is empty
  */
-declare function parseSignalMessage(value: string, userMap: Record<string, string>): string;
+declare function parseSignalMessage(value: string, myUserId: string): SignalMessageResult | null;
 
-export { type APIErrorResponse, type APIResponse, type AscDesc, type Attachment, type AttachmentResponse, type AudioConfig, CallAction, type CallEventData, type CallEventType, CallStatus, Channel, type ChannelAPIResponse, type ChannelData, type ChannelFilters, type ChannelMemberResponse, type ChannelMembership, type ChannelQueryOptions, type ChannelResponse, type ChannelSort, ChannelState, type ChannelStateOptions, ClientState, type ConnectAPIResponse, type ConnectionOpen, type Contact, type ContactResponse, type ContactResult, type DefaultGenerics, EVENT_MAP, type EditMessage, ErmisAuthProvider, ErmisCallNode, ErmisChat, type ErmisChatOptions, ErrorFromResponse, type Event$1 as Event, type EventHandler, type EventTypes, type ExtendableGenerics, FRAME_TYPE, type FormatMessageResponse, type ForwardMessage, type IMediaReceiverEvents, type INodeCall, type LiteralStringForUnion, type LogLevel, type Logger, type Message, type MessageBase, type MessageLabel, type MessageResponse, type MessageResponseBase, type MessageSetType, type Metadata, type PollMessage, type QueryChannelAPIResponse, type QueryChannelsAPIResponse, type Reaction, type ReactionAPIResponse, type ReactionResponse, type ReadResponse, type Role, type SendFileAPIResponse, type SendMessageAPIResponse, type SignalData, StableWSConnection, TokenManager, type TransceiverState, type UR, type UpdateChannelAPIResponse, type UserCallInfo, type UserResponse, type UsersResponse, type VideoConfig, type VoiceRecordingMeta, buildAttachmentPayload, chatCodes, createForwardMessagePayload, formatMessage, getAttachmentCategory, isHeicFile, isVideoFile, logChatPromiseExecution, normalizeFileName, parseSignalMessage, parseSystemMessage };
+export { type APIErrorResponse, type APIResponse, type AscDesc, type Attachment, type AttachmentResponse, type AudioConfig, CallAction, type CallEventData, type CallEventType, CallStatus, CallType, type CallTypeValue, Channel, type ChannelAPIResponse, type ChannelData, type ChannelFilters, type ChannelMemberResponse, type ChannelMembership, type ChannelQueryOptions, type ChannelResponse, type ChannelSort, ChannelState, type ChannelStateOptions, ClientState, type ConnectAPIResponse, type ConnectionOpen, type Contact, type ContactResponse, type ContactResult, type DefaultGenerics, EVENT_MAP, type EditMessage, ErmisAuthProvider, ErmisCallNode, ErmisChat, type ErmisChatOptions, ErrorFromResponse, type Event$1 as Event, type EventHandler, type EventTypes, type ExtendableGenerics, FRAME_TYPE, type FormatMessageResponse, type ForwardMessage, type IMediaReceiverEvents, type INodeCall, type LiteralStringForUnion, type LogLevel, type Logger, type Message, type MessageBase, type MessageLabel, type MessageResponse, type MessageResponseBase, type MessageSetType, type Metadata, type PollMessage, type QueryChannelAPIResponse, type QueryChannelsAPIResponse, type Reaction, type ReactionAPIResponse, type ReactionResponse, type ReadResponse, type Role, type SendFileAPIResponse, type SendMessageAPIResponse, type SignalData, type SignalMessageResult, StableWSConnection, TokenManager, type TransceiverState, type UR, type UpdateChannelAPIResponse, type UserCallInfo, type UserResponse, type UsersResponse, type VideoConfig, type VoiceRecordingMeta, buildAttachmentPayload, chatCodes, createForwardMessagePayload, formatMessage, getAttachmentCategory, isHeicFile, isVideoFile, logChatPromiseExecution, normalizeFileName, parseSignalMessage, parseSystemMessage };