@antzsoft/chat-core 1.0.0 → 1.0.3

package/dist/index.d.ts

@@ -25,9 +25,12 @@ interface UploadableFile {
 }
 interface User {
     id: string;
+    externalId?: string;
     tenantId: string;
     email: string;
     username: string;
+    firstName?: string;
+    lastName?: string;
     displayName: string;
     avatarUrl?: string;
     phone?: string;
@@ -54,7 +57,9 @@ interface RegisterData {
     email: string;
     password: string;
     username: string;
-    displayName: string;
+    firstName: string;
+    lastName: string;
+    displayName?: string;
     phone?: string;
     tenantId?: string;
 }
@@ -135,9 +140,14 @@ interface Participant {
     isActive?: boolean;
     user?: User;
 }
+interface MessageConfig {
+    editWindowSeconds?: number;
+    deleteWindowSeconds?: number;
+}
 interface ConversationSettings {
     onlyAdminsCanMessage?: boolean;
     onlyAdminsCanAddMembers?: boolean;
+    messageConfig?: MessageConfig;
 }
 interface Conversation {
     id: string;
@@ -163,6 +173,38 @@ interface Conversation {
     isEncryptionEnabled?: boolean;
     encryptionKey?: string;
 }
+interface ConversationUnreadCount {
+    conversationId: string;
+    unreadCount: number;
+}
+interface UnreadSummary {
+    /** Total unread messages across all conversations */
+    totalUnread: number;
+    /** Per-conversation breakdown — only includes conversations with unread > 0 */
+    byConversation: ConversationUnreadCount[];
+}
+interface ConversationListParams {
+    page?: number;
+    limit?: number;
+    /** Filter by conversation type */
+    type?: ConversationType;
+    /** Only pinned (true) or unpinned (false) conversations */
+    isPinned?: boolean;
+    /** Only muted (true) or unmuted (false) conversations */
+    isMuted?: boolean;
+    /** Only conversations with unread messages */
+    hasUnread?: boolean;
+    /** Search by group name / description (text index) */
+    search?: string;
+    /** Filter by current user's role in the conversation */
+    role?: ParticipantRole;
+    /** Filter by whether the last message has attachments */
+    hasAttachments?: boolean;
+    /** Filter by last message attachment type */
+    attachmentType?: FileType;
+    /** Filter by notification setting */
+    notificationsEnabled?: boolean;
+}
 interface PaginationMeta {
     total: number;
     page: number;
@@ -243,6 +285,10 @@ interface MessageDeletedEvent {
     messageId: string;
     conversationId: string;
 }
+interface MessageDeletedForMeEvent {
+    messageId: string;
+    conversationId: string;
+}
 interface ReactionUpdatedEvent {
     messageId: string;
     conversationId: string;
@@ -313,6 +359,37 @@ interface SendMessagePayload {
     encryptedContent?: EncryptedContent;
     isEncrypted?: boolean;
 }
+interface QuietHours {
+    enabled: boolean;
+    /** HH:MM — e.g. "22:00" */
+    start: string;
+    /** HH:MM — e.g. "08:00" */
+    end: string;
+    /** IANA timezone — e.g. "Asia/Kolkata" */
+    timezone: string;
+}
+/**
+ * User notification preferences stored in chat_user_prefs.
+ * All fields are optional on update — only send what changed.
+ * Any future preference field is added here and to the server schema;
+ * no new collections or API endpoints needed.
+ */
+interface UserPreferences {
+    /** Master switch — false disables all push notifications */
+    notificationsEnabled?: boolean;
+    /** Play sound with notifications */
+    soundEnabled?: boolean;
+    /** Show message text in notification body (false = show "New message" only) */
+    messagePreview?: boolean;
+    /** Notify when @mentioned in a group */
+    notifyOnMention?: boolean;
+    /** Notify when someone reacts to your message */
+    notifyOnReaction?: boolean;
+    /** Notify when added to a group */
+    notifyOnGroupInvite?: boolean;
+    /** Quiet hours window — no push delivered during this period */
+    quietHours?: QuietHours;
+}
 
 interface FileSizeLimits {
     image?: number;
@@ -376,11 +453,38 @@ interface AntzChatConfig {
      * Not needed for builtin mode (chat server issues its own JWTs).
      */
     userId?: string;
+    /**
+     * Profile picture for non-builtin modes.
+     * Server fetches/decodes, hashes for dedup, uploads to chat storage on first use.
+     * Only sent once at init — not re-sent on every request.
+     * Client never needs to compute hashes; the server owns all dedup logic.
+     */
+    avatar?: {
+        /** Full URL the server can fetch (preferred — Antz/external/wso2 clients know their own file URLs) */
+        url?: string;
+        /** Raw base64 string (with or without data:... prefix) as fallback */
+        base64?: string;
+    };
     /** Required for multi-tenant backends. Sent as X-Tenant-ID header. */
     tenantId?: string;
     /** Must match server ENCRYPTION_MODE env var. Default: 'none' */
     encryptionMode?: 'none' | 'server';
     upload?: UploadConfig;
+    /**
+     * Number of messages fetched per page when loading chat history.
+     * Default: 40
+     */
+    messagePageSize?: number;
+    /**
+     * Number of starred messages fetched per page.
+     * Default: 30
+     */
+    starredMessagePageSize?: number;
+    /**
+     * Number of search results fetched per request.
+     * Default: 50
+     */
+    searchPageSize?: number;
     /**
      * Platform-specific binary upload implementation.
      * Required — each SDK (web, RN) provides its own.
@@ -402,10 +506,16 @@ interface ResolvedFileSizeLimits {
 interface ResolvedConfig {
     apiUrl: string;
     socketUrl: string;
+    socketOrigin: string;
+    socketPath: string;
     authToken?: string;
     authProvider?: () => Promise<string>;
     userId?: string;
     tenantId?: string;
+    avatar?: {
+        url?: string;
+        base64?: string;
+    };
     encryptionMode: 'none' | 'server';
     upload: {
         maxFileSizeMB: ResolvedFileSizeLimits;
@@ -416,6 +526,9 @@ interface ResolvedConfig {
     };
     platformUploadFn: PlatformUploadFn;
     persistStorage: PersistStorage;
+    messagePageSize: number;
+    starredMessagePageSize: number;
+    searchPageSize: number;
 }
 declare function resolveConfig(config: AntzChatConfig): ResolvedConfig;
 
@@ -426,6 +539,15 @@ declare const authApi: {
     logout(refreshToken?: string): Promise<void>;
     logoutAll(): Promise<void>;
     getMe(): Promise<User>;
+    uploadAvatar(file: File | Blob, mimeType?: string): Promise<{
+        avatarUrl: string;
+    }>;
+    syncAvatar(source: {
+        url?: string;
+        base64?: string;
+    }): Promise<{
+        avatarUrl: string;
+    }>;
 };
 
 interface ListMessagesParams {
@@ -452,6 +574,7 @@ declare const messagesApi: {
     send(conversationId: string, payload: SendData): Promise<Message>;
     update(messageId: string, text: string): Promise<Message>;
     delete(messageId: string): Promise<void>;
+    deleteForMe(messageId: string): Promise<void>;
     addReaction(messageId: string, emoji: string): Promise<Message>;
     removeReaction(messageId: string, emoji: string): Promise<Message>;
     star(messageId: string): Promise<void>;
@@ -462,6 +585,10 @@ declare const messagesApi: {
         conversationId?: string;
     }): Promise<PaginatedResponse<Message>>;
     search(params: SearchParams): Promise<PaginatedResponse<Message>>;
+    getLastRead(conversationId: string): Promise<{
+        lastReadMessageId: string | null;
+        lastReadAt: string | null;
+    }>;
     markAsRead(conversationId: string, messageId?: string): Promise<void>;
     pin(messageId: string): Promise<Message>;
     unpin(messageId: string): Promise<Message>;
@@ -484,10 +611,7 @@ interface UpdateConversationData {
     icon?: string;
 }
 declare const conversationsApi: {
-    list(params?: {
-        page?: number;
-        limit?: number;
-    }): Promise<PaginatedResponse<Conversation>>;
+    list(params?: ConversationListParams): Promise<PaginatedResponse<Conversation>>;
     get(conversationId: string): Promise<Conversation>;
     createGroup(payload: CreateGroupData): Promise<Conversation>;
     createDirect(payload: CreateDirectData): Promise<Conversation>;
@@ -502,7 +626,18 @@ declare const conversationsApi: {
     unpin(conversationId: string): Promise<void>;
     leave(conversationId: string): Promise<void>;
     getMembers(conversationId: string): Promise<User[]>;
-    searchUsers(query: string): Promise<User[]>;
+    /**
+     * Get unread message count for a single conversation.
+     * Use this after app foreground or socket reconnect to refresh a specific count.
+     */
+    getUnreadCount(conversationId: string): Promise<ConversationUnreadCount>;
+    /**
+     * 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.
+     */
+    getUnreadSummary(): Promise<UnreadSummary>;
 };
 
 declare const storageApi: {
@@ -590,6 +725,30 @@ declare const devicesApi: {
     remove(deviceId: string): Promise<void>;
 };
 
+declare const usersApi: {
+    list(params?: {
+        query?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<User>>;
+    getById(userId: string): Promise<User>;
+    getLastSeen(userId: string): Promise<{
+        lastSeenAt: string | null;
+    }>;
+    /**
+     * 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".
+     */
+    updatePreferences(prefs: UserPreferences): Promise<User>;
+    /**
+     * Fetch current notification preferences for the current user.
+     * Returns null if no prefs record exists yet (all defaults apply).
+     */
+    getPreferences(): Promise<UserPreferences | null>;
+};
+
 type TokenStore = {
     getAccessToken: () => string | null | undefined;
     getRefreshToken: () => string | null | undefined;
@@ -610,7 +769,16 @@ declare function getSocketStatus(): SocketStatus;
 declare function onSocketStatus(listener: StatusListener): () => void;
 declare function connectSocket(config: ResolvedConfig, getToken: () => string | null | undefined): Promise<Socket>;
 declare function disconnectSocket(): void;
-declare function reconnectSocket(token: string): void;
+declare function reconnectSocket(token: string, userId?: string, tenantId?: string): void;
+/**
+ * Updates the socket auth token from the stored getToken function and reconnects.
+ * Called by SocketProvider on connect_error to handle expired-token scenarios:
+ *   1. Token expired while disconnected → server rejects the reconnect handshake
+ *   2. authProvider returns a fresh token → we update socket auth and retry
+ *
+ * Returns true if the token was updated, false if no token source is available.
+ */
+declare function refreshSocketAuth(): boolean;
 
 declare const socketEmit: {
     joinRoom(conversationId: string): void;
@@ -618,6 +786,7 @@ declare const socketEmit: {
     sendMessage(payload: SendMessagePayload): Promise<unknown>;
     updateMessage(messageId: string, text: string): Promise<unknown>;
     deleteMessage(messageId: string): Promise<unknown>;
+    deleteMessageForMe(messageId: string): Promise<unknown>;
     addReaction(messageId: string, emoji: string): Promise<unknown>;
     removeReaction(messageId: string, emoji: string): Promise<unknown>;
     pinMessage(messageId: string): Promise<unknown>;
@@ -718,6 +887,10 @@ interface TypingUser {
     displayName: string;
     avatarUrl?: string;
 }
+interface LastReadEntry {
+    messageId: string;
+    readAt: string;
+}
 interface ChatState {
     activeConversationId: string | null;
     pendingTarget: {
@@ -726,6 +899,10 @@ interface ChatState {
     } | null;
     typingUsers: Record<string, TypingUser[]>;
     onlineUsers: string[];
+    /** keyed by conversationId — current user's last read pointer per conversation */
+    lastRead: Record<string, LastReadEntry>;
+    /** keyed by userId — last seen timestamp for each user */
+    lastSeen: Record<string, string>;
     replyingTo: Message | null;
     editingMessage: Message | null;
     isSidebarOpen: boolean;
@@ -741,6 +918,8 @@ interface ChatState {
     setUserOnline: (userId: string) => void;
     setUserOffline: (userId: string) => void;
     setOnlineUsers: (userIds: string[]) => void;
+    setLastRead: (conversationId: string, messageId: string, readAt: string) => void;
+    setLastSeen: (userId: string, lastSeenAt: string) => void;
     setReplyingTo: (message: Message | null) => void;
     setEditingMessage: (message: Message | null) => void;
     toggleSidebar: () => void;
@@ -773,6 +952,15 @@ declare class AntzChatClient {
         logout(refreshToken?: string): Promise<void>;
         logoutAll(): Promise<void>;
         getMe(): Promise<User>;
+        uploadAvatar(file: File | Blob, mimeType?: string): Promise<{
+            avatarUrl: string;
+        }>;
+        syncAvatar(source: {
+            url?: string;
+            base64?: string;
+        }): Promise<{
+            avatarUrl: string;
+        }>;
     };
     readonly messages: {
         list(conversationId: string, params?: ListMessagesParams): Promise<CursorPaginatedResponse<Message>>;
@@ -780,6 +968,7 @@ declare class AntzChatClient {
         send(conversationId: string, payload: SendData): Promise<Message>;
         update(messageId: string, text: string): Promise<Message>;
         delete(messageId: string): Promise<void>;
+        deleteForMe(messageId: string): Promise<void>;
         addReaction(messageId: string, emoji: string): Promise<Message>;
         removeReaction(messageId: string, emoji: string): Promise<Message>;
         star(messageId: string): Promise<void>;
@@ -790,16 +979,17 @@ declare class AntzChatClient {
             conversationId?: string;
         }): Promise<PaginatedResponse<Message>>;
         search(params: SearchParams): Promise<PaginatedResponse<Message>>;
+        getLastRead(conversationId: string): Promise<{
+            lastReadMessageId: string | null;
+            lastReadAt: string | null;
+        }>;
         markAsRead(conversationId: string, messageId?: string): Promise<void>;
         pin(messageId: string): Promise<Message>;
         unpin(messageId: string): Promise<Message>;
         getPinned(conversationId: string): Promise<Message[]>;
     };
     readonly conversations: {
-        list(params?: {
-            page?: number;
-            limit?: number;
-        }): Promise<PaginatedResponse<Conversation>>;
+        list(params?: ConversationListParams): Promise<PaginatedResponse<Conversation>>;
         get(conversationId: string): Promise<Conversation>;
         createGroup(payload: CreateGroupData): Promise<Conversation>;
         createDirect(payload: CreateDirectData): Promise<Conversation>;
@@ -814,7 +1004,8 @@ declare class AntzChatClient {
         unpin(conversationId: string): Promise<void>;
         leave(conversationId: string): Promise<void>;
         getMembers(conversationId: string): Promise<User[]>;
-        searchUsers(query: string): Promise<User[]>;
+        getUnreadCount(conversationId: string): Promise<ConversationUnreadCount>;
+        getUnreadSummary(): Promise<UnreadSummary>;
     };
     readonly storage: {
         requestPresignedUrl(payload: PresignedUrlRequest): Promise<PresignedUrlResponse>;
@@ -842,6 +1033,19 @@ declare class AntzChatClient {
             limit?: number;
         }): Promise<PaginatedResponse<FileResponse>>;
     };
+    readonly users: {
+        list(params?: {
+            query?: string;
+            page?: number;
+            limit?: number;
+        }): Promise<PaginatedResponse<User>>;
+        getById(userId: string): Promise<User>;
+        getLastSeen(userId: string): Promise<{
+            lastSeenAt: string | null;
+        }>;
+        updatePreferences(prefs: UserPreferences): Promise<User>;
+        getPreferences(): Promise<UserPreferences | null>;
+    };
     readonly socket: ClientSocketHandle;
     constructor(rawConfig: AntzChatConfig);
     connect(): Promise<void>;
@@ -849,4 +1053,4 @@ declare class AntzChatClient {
     uploadFiles(files: UploadableFile[], conversationId?: string): Promise<BatchUploadResult>;
 }
 
-export { AntzChatClient, type AntzChatConfig, type Attachment, type AuthResponse, type AuthTokens, type BatchUploadResult, type Conversation, type CreateDirectData, type CreateGroupData, type CursorPaginatedResponse, type EncryptedContent, type EncryptionKeyInfo, type EncryptionMode, type FileResponse, type FileSizeLimits, type FileType, type ListMessagesParams, type LoginCredentials, type Message, type MessageAckEvent, type MessageContent, type MessageDeletedEvent, type MessageDeliveredEvent, type MessageReaction, type MessageReplyReference, type MessageUpdatedEvent, type MessagesDeliveredEvent, type MobileDeviceToken, type NewMessageEvent, type OptimisticAttachment, type PaginatedResponse, type Participant, type PersistStorage, type PlatformUploadFn, type PresignedUrlRequest, type PresignedUrlResponse, type ReactionUpdatedEvent, type ReadReceiptEvent, type RegisterData, type RegisterDeviceTokenPayload, type ResolvedConfig, type ResolvedFileSizeLimits, type SearchParams, type SendData, type SendMessageAttachment, type SendMessagePayload, type SocketStatus, type StatusListener, type TokenStore, type TypingIndicatorEvent, type UpdateConversationData, type UploadConfig, type UploadProgress, type UploadableFile, type User, type UserStatusEvent, type WebPushDeviceToken, authApi, connectSocket, conversationsApi, createAuthStore, devicesApi, disconnectSocket, getApiClient, getAuthStore, getSocket, getSocketStatus, initApiClient, initAuthStore, messagesApi, normalizeConversation, onSocketStatus, reconnectSocket, resetAuthStore, resolveConfig, setApiClientInstance, socketEmit, storageApi, tryGetSocket, uploadBatch, useChatStore };
+export { AntzChatClient, type AntzChatConfig, type Attachment, type AuthResponse, type AuthTokens, type BatchUploadResult, type Conversation, type ConversationListParams, type ConversationUnreadCount, type CreateDirectData, type CreateGroupData, type CursorPaginatedResponse, type EncryptedContent, type EncryptionKeyInfo, type EncryptionMode, type FileResponse, type FileSizeLimits, type FileType, type LastReadEntry, type ListMessagesParams, type LoginCredentials, type Message, type MessageAckEvent, type MessageContent, type MessageDeletedEvent, type MessageDeletedForMeEvent, type MessageDeliveredEvent, type MessageReaction, type MessageReplyReference, type MessageUpdatedEvent, type MessagesDeliveredEvent, type MobileDeviceToken, type NewMessageEvent, type OptimisticAttachment, type PaginatedResponse, type Participant, type PersistStorage, type PlatformUploadFn, type PresignedUrlRequest, type PresignedUrlResponse, type QuietHours, type ReactionUpdatedEvent, type ReadReceiptEvent, type RegisterData, type RegisterDeviceTokenPayload, type ResolvedConfig, type ResolvedFileSizeLimits, type SearchParams, type SendData, type SendMessageAttachment, type SendMessagePayload, type SocketStatus, type StatusListener, type TokenStore, type TypingIndicatorEvent, type UnreadSummary, type UpdateConversationData, type UploadConfig, type UploadProgress, type UploadableFile, type User, type UserPreferences, type UserStatusEvent, type WebPushDeviceToken, authApi, connectSocket, conversationsApi, createAuthStore, devicesApi, disconnectSocket, getApiClient, getAuthStore, getSocket, getSocketStatus, initApiClient, initAuthStore, messagesApi, normalizeConversation, onSocketStatus, reconnectSocket, refreshSocketAuth, resetAuthStore, resolveConfig, setApiClientInstance, socketEmit, storageApi, tryGetSocket, uploadBatch, useChatStore, usersApi };