@ermis-network/ermis-chat-react 1.0.8 → 2.0.0

package/src/context/ChatComponentsContext.tsx

@@ -0,0 +1,14 @@
+import React, { createContext, useContext } from 'react';
+import type { ModalProps, DropdownProps, PanelProps, ForwardMessageModalProps } from '../types';
+
+export type ChatComponentsContextValue = {
+  ModalComponent?: React.ComponentType<ModalProps>;
+  DropdownComponent?: React.ComponentType<DropdownProps>;
+  PanelComponent?: React.ComponentType<PanelProps>;
+  ForwardMessageModalComponent?: React.ComponentType<ForwardMessageModalProps>;
+  ChannelListErrorIndicator?: React.ComponentType<{ text?: string; onRetry?: () => void }>;
+};
+
+export const ChatComponentsContext = createContext<ChatComponentsContextValue>({});
+
+export const useChatComponents = () => useContext(ChatComponentsContext);

package/src/context/ChatProvider.tsx

@@ -1,8 +1,9 @@
-import React, { createContext, useState, useCallback } from 'react';
+import React, { createContext, useState, useCallback, useRef } from 'react';
 import type { Channel, FormatMessageResponse } from '@ermis-network/ermis-chat-sdk';
 import type { Theme, ChatContextValue, ChatProviderProps, ReadStateEntry } from '../types';
 import { ErmisCallProvider } from '../components/ErmisCallProvider';
 import { ErmisCallUI } from '../components/ErmisCallUI';
+import { ChatComponentsContext } from './ChatComponentsContext';
 
 export type { Theme, ChatContextValue, ChatProviderProps } from '../types';
 
@@ -11,6 +12,7 @@ export const ChatContext = createContext<ChatContextValue | null>(null);
 export const ChatProvider: React.FC<ChatProviderProps> = ({
   client,
   children,
+  components = {},
   initialTheme = 'light',
   enableCall = false,
   callSessionId,
@@ -36,18 +38,18 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
   const [jumpToMessageId, setJumpToMessageId] = useState<string | null>(null);
 
   const activeChannel = activeChannelRaw;
+  const activeChannelCidRef = useRef<string | null>(null);
 
   const setActiveChannel = useCallback((channel: Channel | null) => {
+    const newCid = channel?.cid || null;
+    if (activeChannelCidRef.current === newCid) return;
+    
+    activeChannelCidRef.current = newCid;
     setActiveChannelRaw(channel);
     setQuotedMessage(null);
     setEditingMessage(null);
-    if (channel) {
-      setMessages([...channel.state.latestMessages]);
-      setReadState({ ...channel.state.read });
-    } else {
-      setMessages([]);
-      setReadState({});
-    }
+    setMessages([]);
+    setReadState({});
   }, []);
 
   /** Re-read messages from SDK state into React state */
@@ -87,12 +89,14 @@ export const ChatProvider: React.FC<ChatProviderProps> = ({
   );
 
   const content = (
-    <ChatContext.Provider value={value}>
-      <div className={`ermis-chat ermis-chat--${theme}`}>
-        {children}
-        {enableCall && CallUIView}
-      </div>
-    </ChatContext.Provider>
+    <ChatComponentsContext.Provider value={components}>
+      <ChatContext.Provider value={value}>
+        <div className={`ermis-chat ermis-chat--${theme}`}>
+          {children}
+          {enableCall && CallUIView}
+        </div>
+      </ChatContext.Provider>
+    </ChatComponentsContext.Provider>
   );
 
   if (enableCall) {

package/src/context/ErmisCallContext.tsx

@@ -32,6 +32,10 @@ export type CallContextValue = {
   isRemoteVideoMuted: boolean;
   upgradeCall: () => Promise<void>;
   callDuration: number;
+  isAccepting: boolean;
+  isRejecting: boolean;
+  isEnding: boolean;
+  resetCall: () => void;
 };
 
 export const ErmisCallContext = React.createContext<CallContextValue | undefined>(undefined);

package/src/hooks/useChannelCapabilities.ts

@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback } from 'react';
 import { useChatClient } from './useChatClient';
+import { usePreviewState } from './usePreviewState';
 import { isGroupChannel } from '../channelTypeUtils';
 import { canManageChannel, CHANNEL_ROLES } from '../channelRoleUtils';
 
@@ -19,18 +20,20 @@ export const useChannelCapabilities = () => {
   }, [activeChannel]);
 
   const currentUserId = client?.userID || '';
+  const { isPreviewMode } = usePreviewState(activeChannel, currentUserId);
   const isGroupCh = isGroupChannel(activeChannel);
   const role = (activeChannel?.state as any)?.members?.[currentUserId]?.channel_role;
   
-  const isOwner = role === CHANNEL_ROLES.OWNER || activeChannel?.data?.created_by_id === currentUserId;
-  const isModerator = role === CHANNEL_ROLES.MODERATOR;
-  const isOwnerOrModerator = isOwner || isModerator || canManageChannel(role);
+  const isOwner = isPreviewMode ? false : (role === CHANNEL_ROLES.OWNER || activeChannel?.data?.created_by_id === currentUserId);
+  const isModerator = isPreviewMode ? false : (role === CHANNEL_ROLES.MODERATOR);
+  const isOwnerOrModerator = isOwner || isModerator || (!isPreviewMode && canManageChannel(role));
 
   const capabilities: string[] = isGroupCh ? (activeChannel?.data as any)?.member_capabilities || [] : [];
 
   const hasCapability = useCallback((cap: string) => {
+    if (isPreviewMode) return false;
     return !isGroupCh || isOwnerOrModerator || capabilities.includes(cap);
-  }, [isGroupCh, isOwnerOrModerator, capabilities, updateTick]); // React to updateTick correctly
+  }, [isGroupCh, isOwnerOrModerator, capabilities, updateTick, isPreviewMode]);
 
   return {
     isGroupChannel: isGroupCh,

package/src/hooks/useChannelData.ts

@@ -43,13 +43,20 @@ export const useChannelProfile = (channel: Channel | null | undefined) => {
   useEffect(() => {
     if (!channel) return;
     const updateChannel = () => setChannelUpdateCount(c => c + 1);
-    const sub = channel.on('channel.updated', updateChannel);
-    return () => sub.unsubscribe();
+    const sub1 = channel.on('channel.updated', updateChannel);
+    const sub2 = channel.on('channel.pinned', updateChannel);
+    const sub3 = channel.on('channel.unpinned', updateChannel);
+    return () => {
+      sub1.unsubscribe();
+      sub2.unsubscribe();
+      sub3.unsubscribe();
+    };
   }, [channel]);
 
   const channelName = useMemo(() => channel?.data?.name || channel?.cid || 'Unknown Channel', [channel?.data?.name, channel?.cid, channel?.type, channelUpdateCount]);
   const channelImage = useMemo(() => channel?.data?.image as string | undefined, [channel?.data?.image, channelUpdateCount]);
   const channelDescription = useMemo(() => channel?.data?.description as string | undefined, [channel?.data?.description, channelUpdateCount]);
+  const isPinned = useMemo(() => channel?.data?.is_pinned === true, [channel?.data?.is_pinned, channelUpdateCount]);
 
-  return { channelName, channelImage, channelDescription };
+  return { channelName, channelImage, channelDescription, isPinned };
 };

package/src/hooks/useChannelListUpdates.ts

@@ -18,6 +18,7 @@ import { isPendingMember } from '../channelRoleUtils';
 export function useChannelListUpdates(
   channels: Channel[],
   setChannels: React.Dispatch<React.SetStateAction<Channel[]>>,
+  onOwnMessageNew?: () => void,
 ): void {
   const { client, activeChannel, setActiveChannel } = useChatClient();
 
@@ -25,17 +26,23 @@ export function useChannelListUpdates(
   const activeChannelRef = useRef(activeChannel);
   activeChannelRef.current = activeChannel;
 
+  // Ref to always have the latest callback without re-subscribing
+  const onOwnMessageNewRef = useRef(onOwnMessageNew);
+  onOwnMessageNewRef.current = onOwnMessageNew;
+
   useEffect(() => {
     // --- message.new: re-sort + auto mark-read ---
     const handleNewMessage = (event: Event) => {
       const eventCid = event.cid;
       if (!eventCid) return;
 
+      const isOwnMessage = event.user?.id === client.userID;
+
       // If the new message is on the active channel and from someone else,
       // mark it as read immediately so unreadCount resets to 0.
       // Skip markRead if the current user is banned, blocked, or pending in that channel.
       const active = activeChannelRef.current;
-      if (active?.cid === eventCid && event.user?.id !== client.userID) {
+      if (active?.cid === eventCid && !isOwnMessage) {
         const isBannedInActive = Boolean(active.state?.membership?.banned);
         const isBlockedInActive = isDirectChannel(active) && Boolean(active.state?.membership?.blocked);
         const isPendingActive = isPendingMember(active.state?.membership?.channel_role as string);
@@ -48,13 +55,23 @@ export function useChannelListUpdates(
       }
 
       setChannels((prev) => {
-        const idx = prev.findIndex((ch) => ch.cid === eventCid);
-        if (idx <= 0) {
+        let targetIdx = prev.findIndex((ch) => ch.cid === eventCid);
+
+        // If not found directly, check if this is a topic message — move the parent channel to top
+        if (targetIdx < 0) {
+          const topicChannel = client.activeChannels[eventCid];
+          const parentCid = topicChannel?.data?.parent_cid as string | undefined;
+          if (parentCid) {
+            targetIdx = prev.findIndex((ch) => ch.cid === parentCid);
+          }
+        }
+
+        if (targetIdx <= 0) {
           // Already at top or not found — just create a new reference
-          return idx === 0 ? [...prev] : prev;
+          return targetIdx === 0 ? [...prev] : prev;
         }
 
-        const channel = prev[idx];
+        const channel = prev[targetIdx];
 
         // Don't move banned channels to the top
         if (channel.state?.membership?.banned) {
@@ -63,10 +80,17 @@ export function useChannelListUpdates(
 
         // Move channel to the top
         const updated = [...prev];
-        const [ch] = updated.splice(idx, 1);
+        const [ch] = updated.splice(targetIdx, 1);
         updated.unshift(ch);
         return updated;
       });
+
+      // Notify the component layer that the current user sent a message
+      // so it can scroll to top. Use setTimeout(0) to ensure React has
+      // flushed the setChannels state update before the scroll fires.
+      if (isOwnMessage && onOwnMessageNewRef.current) {
+        setTimeout(() => onOwnMessageNewRef.current?.(), 0);
+      }
     };
 
     // --- channel.deleted: remove from list and reset active ---
@@ -178,32 +202,53 @@ export function useChannelListUpdates(
       }
     };
 
-    // --- notification.invite_accepted: force re-grouping ---
-    const handleMemberUpdated = (event: Event) => {
+    // --- notification.invite_accepted / member.joined: force re-grouping or add to list ---
+    const handleMemberUpdated = async (event: Event) => {
       const updatedUserId = event.member?.user_id || event.member?.user?.id || event.user?.id;
       if (updatedUserId === client.userID) {
-        setChannels((prev) => {
-          // Defensively mutate the channel's membership before grouping logic runs
-          const eventCid =
-            event.cid ||
-            event.channel?.cid ||
-            ((event as Record<string, unknown>).channel_id
-              ? `${(event as Record<string, unknown>).channel_type}:${(event as Record<string, unknown>).channel_id}`
-              : undefined);
+        const eventCid =
+          event.cid ||
+          event.channel?.cid ||
+          ((event as Record<string, unknown>).channel_id
+            ? `${(event as Record<string, unknown>).channel_type}:${(event as Record<string, unknown>).channel_id}`
+            : undefined);
 
+        setChannels((prev) => {
           if (eventCid && event.member) {
             const targetChannel = prev.find((c) => c.cid === eventCid);
-            // We forcefully map the updated incoming member data into the static channel representation
             if (targetChannel && targetChannel.state) {
+              // Channel already in list — just update membership for re-grouping
               targetChannel.state.membership = {
                 ...targetChannel.state.membership,
                 ...event.member,
               } as unknown as Record<string, unknown>;
             }
           }
-
-          return [...prev]; // Force react map to regenerate
+          return [...prev];
         });
+
+        // If the channel is NOT in the list yet (e.g. user just joined a public channel
+        // from search), add it — same logic as handleChannelCreated
+        if (eventCid) {
+          setChannels((prev) => {
+            if (prev.some((c) => c.cid === eventCid)) return prev; // already in list
+            const type = event.channel?.type || (event as Record<string, unknown>).channel_type;
+            const id = event.channel?.id || (event as Record<string, unknown>).channel_id;
+            if (!type || !id) return prev;
+            const channelInstance = client.channel(type as string, id as string);
+            if (channelInstance.state) {
+              channelInstance.state.membership = {
+                ...channelInstance.state.membership,
+                ...event.member,
+              } as unknown as Record<string, unknown>;
+            }
+            // Watch if not initialized so we get full state
+            if (!channelInstance.initialized) {
+              channelInstance.watch().catch(() => {});
+            }
+            return [channelInstance, ...prev];
+          });
+        }
       }
     };
 
@@ -215,7 +260,10 @@ export function useChannelListUpdates(
     const sub1 = client.on('message.new', handleNewMessage);
     const sub2 = client.on('channel.deleted', handleChannelDeleted);
     const sub3 = client.on('member.removed', handleMemberRemoved);
-    const sub4 = client.on('channel.created', (event) => handleChannelCreated(event, true));
+    const sub4 = client.on('channel.created', (event) => {
+      const isCreator = event.user?.id === client.userID || event.user_id === client.userID;
+      handleChannelCreated(event, !isCreator);
+    });
     const sub5 = client.on('member.added', handleMemberAdded);
     const sub6 = client.on('notification.added_to_channel', handleMemberAdded);
     const sub7 = client.on('notification.invite_rejected', handleMemberRemoved);
@@ -226,6 +274,9 @@ export function useChannelListUpdates(
     const sub12 = client.on('channel.pinned', handleGenericUpdate);
     const sub13 = client.on('channel.unpinned', handleGenericUpdate);
     const sub14 = client.on('notification.invite_messaging_skipped', handleMemberUpdated);
+    // When a user joins a public channel (action='join'), the server sends member.joined
+    // instead of notification.invite_accepted — handle it to re-group the channel list
+    const sub15 = client.on('member.joined', handleMemberUpdated);
 
     return () => {
       sub1.unsubscribe();
@@ -242,6 +293,7 @@ export function useChannelListUpdates(
       sub12.unsubscribe();
       sub13.unsubscribe();
       sub14.unsubscribe();
+      sub15.unsubscribe();
     };
   }, [client, setChannels, setActiveChannel]);
 }

package/src/hooks/useChannelMessages.ts

@@ -10,8 +10,16 @@ export type UseChannelMessagesOptions = {
   isAtBottomRef: React.MutableRefObject<boolean>;
   /** Called to reset load-more state when channel switches */
   onChannelSwitch?: () => void;
+  /** Whether to include hidden (deleted) messages in the initial channel query */
+  includeHiddenMessages?: boolean;
+  /** Ref to the message list container for smooth opacity transitions */
+  containerRef?: React.RefObject<HTMLDivElement>;
 };
 
+// Track channels that have already been queried with include_hidden_messages globally for the session
+const fullyQueriedChannels = new Set<string>();
+export const markChannelAsFullyQueried = (cid: string) => fullyQueriedChannels.add(cid);
+
 /**
  * Schedule multiple scroll-to-bottom attempts with increasing delays.
  * Handles content that changes height after initial render (images, embeds).
@@ -29,6 +37,8 @@ export function useChannelMessages({
   jumpingRef,
   isAtBottomRef,
   onChannelSwitch,
+  includeHiddenMessages = true,
+  containerRef,
 }: UseChannelMessagesOptions): void {
   const { client, activeChannel, syncMessages, setReadState } = useChatClient();
 
@@ -60,15 +70,58 @@ export function useChannelMessages({
 
     // Block scroll triggers during channel-switch scroll
     jumpingRef.current = true;
-    // Defer scroll outside React lifecycle to avoid virtua flushSync warning
-    setTimeout(() => {
-      scrollToBottom(false);
-      // Wait long enough for scrollToBottom's internal retries and the browser
-      // to execute the scroll event
+
+    // Instantly hide the list when channel changes
+    const el = containerRef?.current;
+    if (el) {
+      el.style.opacity = '0';
+      el.style.transition = 'none';
+    }
+
+    const fadeListIn = () => {
+      if (!el) return;
+      // Allow virtua a brief moment to measure items after scroll before showing
       setTimeout(() => {
-        jumpingRef.current = false;
-      }, 100);
-    }, 0);
+        el.style.transition = 'opacity 0.1s ease-out';
+        el.style.opacity = '1';
+      }, 50);
+    };
+
+    // Fetch hidden messages if not already done for this channel
+    const cid = activeChannel.cid;
+    if (includeHiddenMessages && cid && !fullyQueriedChannels.has(cid)) {
+      activeChannel
+        .query({
+          messages: { limit: 25, include_hidden_messages: true },
+        })
+        .then(() => {
+          fullyQueriedChannels.add(cid);
+          syncMessages();
+          // Sync initial read state from SDK so read receipts show immediately
+          setReadState({ ...activeChannel.state.read });
+          scheduleScrollToBottom(false);
+          fadeListIn(); // Fade in AFTER query finishes and sync is called
+        })
+        .catch((err: any) => {
+          console.error('Failed to query channel on select', err);
+          fadeListIn(); // Fade in anyway on error
+        });
+    } else {
+      // Already queried or disabled: sync cache, scroll and fade in quickly
+      syncMessages();
+      // Sync initial read state from SDK so read receipts show immediately
+      setReadState({ ...activeChannel.state.read });
+      setTimeout(() => {
+        scheduleScrollToBottom(false);
+        fadeListIn();
+      }, 0);
+    }
+
+    // Wait long enough for scrollToBottom's internal retries and the browser
+    // to execute the scroll event
+    setTimeout(() => {
+      jumpingRef.current = false;
+    }, 100);
 
     const handleNewMessage = (event: Event) => {
       // Capture scroll state BEFORE sync causes re-render
@@ -106,7 +159,7 @@ export function useChannelMessages({
               activeChannel.markRead().catch(() => {});
             }
           })
-          .catch((e) => console.error('Failed to sync messages after unblock', e));
+          .catch((e: any) => console.error('Failed to sync messages after unblock', e));
       }
     };
 
@@ -124,10 +177,15 @@ export function useChannelMessages({
             scheduleScrollToBottom(false);
             activeChannel.markRead().catch(() => {});
           })
-          .catch((e) => console.error('Failed to sync messages after accepting invite', e));
+          .catch((e: any) => console.error('Failed to sync messages after accepting invite', e));
       }
     };
 
+    const handleRecovery = () => {
+      syncMessages();
+      scheduleScrollToBottom(false);
+    };
+
     const client = activeChannel.getClient();
     const sub1 = activeChannel.on('message.new', handleNewMessage);
     const sub2 = activeChannel.on('message.updated', handleMessageChange);
@@ -140,6 +198,8 @@ export function useChannelMessages({
     const sub9 = activeChannel.on('reaction.deleted', handleMessageChange);
     const sub10 = activeChannel.on('member.unblocked', handleUnblocked);
     const sub11 = client.on('notification.invite_accepted', handleInviteAccepted);
+    const sub12 = client.on('connection.recovered', handleRecovery);
+    const sub13 = client.on('channels.queried', handleRecovery);
 
     return () => {
       sub1.unsubscribe();
@@ -153,6 +213,8 @@ export function useChannelMessages({
       sub9.unsubscribe();
       sub10.unsubscribe();
       sub11.unsubscribe();
+      sub12.unsubscribe();
+      sub13.unsubscribe();
     };
   }, [activeChannel, scrollToBottom, scheduleScrollToBottom, syncMessages, onChannelSwitch, setReadState]);
 }

package/src/hooks/useChannelRowUpdates.ts

@@ -18,10 +18,17 @@ export function useChannelRowUpdates(channel: Channel, currentUserId?: string) {
   const [updateCount, setUpdateCount] = useState(0);
 
   useEffect(() => {
-    setIsBannedInChannel(Boolean(channel.state?.membership?.banned));
-    setIsBlockedInChannel(
-      isDirectChannel(channel) ? Boolean(channel.state?.membership?.blocked) : false
-    );
+    const parentCid = channel.data?.parent_cid as string | undefined;
+    const parentChannel = parentCid ? channel.getClient().activeChannels[parentCid] : undefined;
+
+    const computeIsBanned = () => {
+      const selfBanned = Boolean(channel.state?.membership?.banned);
+      const parentBanned = Boolean(parentChannel?.state?.membership?.banned);
+      return selfBanned || parentBanned;
+    };
+
+    setIsBannedInChannel(computeIsBanned());
+    setIsBlockedInChannel(isDirectChannel(channel) ? Boolean(channel.state?.membership?.blocked) : false);
 
     const handleBanned = (event: any) => {
       if (event.member?.user_id === currentUserId) {
@@ -30,7 +37,7 @@ export function useChannelRowUpdates(channel: Channel, currentUserId?: string) {
     };
     const handleUnbanned = (event: any) => {
       if (event.member?.user_id === currentUserId) {
-        setIsBannedInChannel(false);
+        setIsBannedInChannel(computeIsBanned());
       }
     };
 
@@ -42,6 +49,7 @@ export function useChannelRowUpdates(channel: Channel, currentUserId?: string) {
     const sub4 = channel.on('message.read', handleUpdate);
     const sub5 = channel.on('message.updated', handleUpdate);
     const sub6 = channel.on('message.deleted', handleUpdate);
+    const sub6_me = channel.on('message.deleted_for_me', handleUpdate);
     const sub7 = channel.on('channel.updated', handleUpdate);
     const sub8 = channel.on('member.added', handleUpdate);
     const sub9 = channel.on('member.removed', handleUpdate);
@@ -63,6 +71,14 @@ export function useChannelRowUpdates(channel: Channel, currentUserId?: string) {
     const sub13 = channel.on('channel.pinned', handleUpdate);
     const sub14 = channel.on('channel.unpinned', handleUpdate);
 
+    // Topic support: listen for ban events on parent channel too
+    let sub15: { unsubscribe: () => void } | undefined;
+    let sub16: { unsubscribe: () => void } | undefined;
+    if (parentChannel) {
+      sub15 = parentChannel.on('member.banned', handleBanned);
+      sub16 = parentChannel.on('member.unbanned', handleUnbanned);
+    }
+
     return () => {
       sub1.unsubscribe();
       sub2.unsubscribe();
@@ -70,6 +86,7 @@ export function useChannelRowUpdates(channel: Channel, currentUserId?: string) {
       sub4.unsubscribe();
       sub5.unsubscribe();
       sub6.unsubscribe();
+      sub6_me.unsubscribe();
       sub7.unsubscribe();
       sub8.unsubscribe();
       sub9.unsubscribe();
@@ -78,6 +95,8 @@ export function useChannelRowUpdates(channel: Channel, currentUserId?: string) {
       sub12.unsubscribe();
       sub13.unsubscribe();
       sub14.unsubscribe();
+      if (sub15) sub15.unsubscribe();
+      if (sub16) sub16.unsubscribe();
     };
   }, [channel, currentUserId]);
 

package/src/hooks/useChatUser.ts

@@ -0,0 +1,31 @@
+import { useState, useEffect } from 'react';
+import { useChatClient } from './useChatClient';
+import type { UserResponse, ExtendableGenerics, DefaultGenerics } from '@ermis-network/ermis-chat-sdk';
+
+export const useChatUser = <ErmisChatGenerics extends ExtendableGenerics = DefaultGenerics>() => {
+  const { client } = useChatClient();
+  const [user, setUser] = useState<UserResponse<ErmisChatGenerics> | undefined>(client?.user);
+
+  useEffect(() => {
+    if (!client) return;
+
+    // Set initial user in case it changed before the effect runs
+    setUser(client.user);
+
+    const handleUserUpdated = (event: any) => {
+      if (event.me) {
+        setUser((prev) => ({ ...prev, ...event.me }));
+      }
+    };
+
+    const listener = client.on('user.updated', handleUserUpdated);
+    const healthListener = client.on('health.check', handleUserUpdated);
+
+    return () => {
+      listener.unsubscribe();
+      healthListener.unsubscribe();
+    };
+  }, [client]);
+
+  return { user };
+};

package/src/hooks/useContactChannels.ts

@@ -0,0 +1,45 @@
+import { useEffect, useState, useMemo, useCallback } from 'react';
+import type { Channel } from '@ermis-network/ermis-chat-sdk';
+import { useChatClient } from './useChatClient';
+import { isDirectChannel } from '../channelTypeUtils';
+import { isOwnerMember } from '../channelRoleUtils';
+
+/**
+ * A hook that retrieves all friend (contact) channels from the SDK's local cache
+ * without triggering an extra API network query.
+ *
+ * A contact is defined as a direct (1-1) channel where both members
+ * hold the 'owner' channel_role.
+ *
+ * Re-renders automatically when related events arrive.
+ */
+export function useContactChannels(): Channel[] {
+  const { client } = useChatClient();
+  const [updateCount, setUpdateCount] = useState(0);
+
+  const forceUpdate = useCallback(() => setUpdateCount((c) => c + 1), []);
+
+  useEffect(() => {
+    if (!client) return;
+
+    const listeners = [
+      client.on('channels.queried', forceUpdate),
+      client.on('notification.invite_accepted', forceUpdate),
+    ];
+
+    return () => listeners.forEach((l) => l.unsubscribe());
+  }, [client, forceUpdate]);
+
+  return useMemo(() => {
+    if (!client) return [];
+
+    return Object.values(client.activeChannels).filter((channel) => {
+      if (!isDirectChannel(channel)) return false;
+
+      const members = Object.values(channel.state?.members || {});
+      if (members.length !== 2) return false;
+
+      return members.every((m) => isOwnerMember(m.channel_role as string));
+    });
+  }, [client, updateCount]);
+}

package/src/hooks/useContactCount.ts

@@ -0,0 +1,50 @@
+import { useState, useEffect } from 'react';
+import { useChatClient } from './useChatClient';
+import { isDirectChannel } from '../channelTypeUtils';
+import { isOwnerMember } from '../channelRoleUtils';
+
+export const useContactCount = () => {
+  const { client } = useChatClient();
+  const [contactCount, setContactCount] = useState(0);
+
+  useEffect(() => {
+    if (!client || !client.user) return;
+
+    const countContacts = () => {
+      let count = 0;
+      const channels = Object.values(client.activeChannels);
+      for (const channel of channels) {
+        if (!isDirectChannel(channel)) continue;
+
+        const members = Object.values(channel.state?.members || {});
+        // Contacts are direct channels where both members are owners
+        if (members.length === 2) {
+          const isAllOwners = members.every((m) => isOwnerMember(m.channel_role as string));
+          if (isAllOwners) count++;
+        }
+      }
+      return count;
+    };
+
+    // Calculate initial count
+    setContactCount(countContacts());
+
+    const handleEvent = () => {
+      // Delay slightly to ensure client.activeChannels is updated by SDK internal handlers first
+      setTimeout(() => {
+        setContactCount(countContacts());
+      }, 0);
+    };
+
+    const listeners = [
+      client.on('channels.queried', handleEvent),
+      client.on('notification.invite_accepted', handleEvent),
+    ];
+
+    return () => {
+      listeners.forEach((l) => l.unsubscribe());
+    };
+  }, [client]);
+
+  return { contactCount };
+};