@solarpunkltd/swarm-chat-js 4.2.2 → 5.0.0

package/README.md

@@ -43,7 +43,7 @@ npm/pnpm install @solarpunkltd/swarm-chat-js
 ### Imports
 
 ```typescript
-import { EVENTS, MessageData, SwarmChat, ChatSettings } from '@solarpunkltd/swarm-chat-js';
+import { EVENTS, MessageData, MessageType, SwarmChat, ChatSettings } from '@solarpunkltd/swarm-chat-js';
 ```
 
 ### `ChatSettings` Interface
@@ -106,118 +106,69 @@ The `SwarmChat` class instance provides the following core methods:
 - `start()`: Initializes and starts the chat service, including setting up listeners and beginning to poll for messages.
 - `stop()`: Stops the chat service, clears intervals, and cleans up resources.
 - `getEmitter()`: Returns an event emitter instance, allowing your application to subscribe to the `EVENTS` listed above.
-- `sendMessage(message: string)`: Initiates the process of sending a new chat message from the current user.
+- `sendMessage(message: string, type: MessageType, targetMessageId?: string, id?: string)`: Initiates the process of sending a new chat message from the current user. Supports different message types including text, threads, and reactions.
 - `fetchPreviousMessages()`: Manually triggers the fetching of older messages from the aggregated chat feed.
+- `hasPreviousMessages()`: Returns a boolean indicating whether there are previous messages available to fetch (determined by checking if more than one message state reference exists).
 - `retrySendMessage(message: MessageData)`: Attempts to resend a message that previously encountered an error during the initial request phase (e.g., failed to write to the user's own feed).
 - `retryBroadcastUserMessage(message: MessageData)`: Attempts to re-broadcast a message update via GSOC if the message was successfully uploaded to the user's feed but the GSOC broadcast might have failed or needs retrying.
 
+### Message Types
+
+The library supports three types of messages through the `MessageType` enum:
+
+- `MessageType.TEXT`: Regular chat messages
+- `MessageType.THREAD`: Reply messages that reference a parent message via `targetMessageId`
+- `MessageType.REACTION`: Emoji reactions to existing messages, also using `targetMessageId` to reference the target message
+
+### Message State Management
+
+The library includes robust message state handling with:
+
+- **Automatic retry logic**: Failed message state references are automatically retried with exponential backoff
+- **Ref banning**: Persistently failing references are banned after maximum retry attempts to prevent infinite loops
+- **Efficient caching**: Message state data is cached to avoid redundant network requests
+
 ---
 
 ## 🚀 Usage Example (React)
 
 Here's an example of how `swarm-chat-js` can be integrated into a React application using a custom hook (`useSwarmChat`). This hook encapsulates chat logic, state management, and event handling.
 
+### Complete Implementation
+
+For a full working example, check out our React integration:
+
+**📖 [View Complete useSwarmChat Hook Implementation](https://github.com/Solar-Punk-Ltd/swarm-chat-react-example/blob/master/src/hooks/useSwarmChat.tsx)**
+
+### Basic Usage
+
 ```typescript
-import { useEffect, useRef, useState } from 'react';
-import { EVENTS, MessageData, SwarmChat, ChatSettings } from '@solarpunkltd/swarm-chat-js';
-
-export interface VisibleMessage extends MessageData {
-  requested?: boolean;
-  uploaded?: boolean;
-  received?: boolean;
-  error?: boolean;
-}
+import { useSwarmChat } from './hooks/useSwarmChat';
+import { MessageType } from '@solarpunkltd/swarm-chat-js';
+
+function ChatComponent() {
+  const { messages, isLoading, sendMessage, hasPreviousMessages, loadPreviousMessages } = useSwarmChat(chatSettings);
 
-export const useSwarmChat = ({ user, infra }: ChatSettings) => {
-  const chat = useRef<SwarmChat | null>(null);
-  const messageCache = useRef<VisibleMessage[]>([]);
-  const [allMessages, setAllMessages] = useState<VisibleMessage[]>([]);
-  const [chatLoading, setChatLoading] = useState<boolean>(true);
-  const [messagesLoading, setMessagesLoading] = useState<boolean>(false);
-  const [error, setError] = useState<any | null>(null);
-
-  useEffect(() => {
-    if (!chat.current) {
-      const newChat = new SwarmChat({
-        user,
-        infra,
-      });
-
-      chat.current = newChat;
-
-      const { on } = newChat.getEmitter();
-
-      const updateMessage = (id: string, updates: Partial<VisibleMessage>) => {
-        messageCache.current = messageCache.current.map((msg) => (msg.id === id ? { ...msg, ...updates } : msg));
-        setAllMessages(chat.current?.orderMessages([...messageCache.current]) || []);
-      };
-
-      const handleMessageEvent = (event: string, updates: Partial<VisibleMessage>) => {
-        on(event, (d: MessageData | string) => {
-          const data = typeof d === 'string' ? JSON.parse(d) : d;
-
-          const existingMessage = messageCache.current.find((msg) => msg.id === data.id);
-          if (existingMessage) {
-            updateMessage(data.id, updates);
-          } else {
-            messageCache.current.push({ ...data, ...updates });
-            setAllMessages(chat.current?.orderMessages([...messageCache.current]) || []);
-          }
-        });
-      };
-
-      handleMessageEvent(EVENTS.MESSAGE_REQUEST_INITIATED, {
-        error: false,
-        requested: true,
-      });
-      handleMessageEvent(EVENTS.MESSAGE_REQUEST_UPLOADED, {
-        error: false,
-        uploaded: true,
-      });
-      handleMessageEvent(EVENTS.MESSAGE_RECEIVED, {
-        error: false,
-        received: true,
-      });
-      handleMessageEvent(EVENTS.MESSAGE_REQUEST_ERROR, { error: true });
-
-      on(EVENTS.LOADING_INIT, setChatLoading);
-      on(EVENTS.LOADING_PREVIOUS_MESSAGES, setMessagesLoading);
-      on(EVENTS.CRITICAL_ERROR, setError);
-
-      newChat.start();
-    }
-
-    return () => {
-      if (chat.current) {
-        chat.current.stop();
-        chat.current = null;
-      }
-    };
-  }, [user.privateKey]);
-
-  const sendMessage = (message: string) => chat.current?.sendMessage(message);
-
-  const fetchPreviousMessages = () => chat.current?.fetchPreviousMessages();
-
-  const retrySendMessage = (message: VisibleMessage) => {
-    if (message.requested && message.error) {
-      chat.current?.retrySendMessage(message);
-    }
-    if (message.uploaded && message.error) {
-      chat.current?.retryBroadcastUserMessage(message);
-    }
+  const handleSendMessage = (text: string) => {
+    sendMessage(text, MessageType.TEXT);
   };
 
-  return {
-    chatLoading,
-    messagesLoading,
-    allMessages,
-    sendMessage,
-    fetchPreviousMessages,
-    retrySendMessage,
-    error,
+  const handleReaction = (targetMessageId: string, emoji: string) => {
+    sendMessage(emoji, MessageType.REACTION, targetMessageId);
   };
-};
+
+  const handleReply = (targetMessageId: string, replyText: string) => {
+    sendMessage(replyText, MessageType.THREAD, targetMessageId);
+  };
+
+  return (
+    <div className="chat-container">
+      {/* Your chat UI implementation */}
+      {hasPreviousMessages() && <button onClick={loadPreviousMessages}>Load Previous Messages</button>}
+      {/* Message list, input field, etc. */}
+    </div>
+  );
+}
 ```
 
 ---
@@ -244,7 +195,8 @@ npm run mine -- <bee-address> <topic-name>
 
 ## 💡 Future Development
 
-- **Push-Based Event System:** We are actively designing a new architecture to transition from the polling mechanism to a more efficient, push-based event system for message delivery. This will significantly reduce node load and improve real-time message propagation. Stay tuned! ☀️
+- **Push-Based Event System:** We are actively designing a new architecture to transition from the polling mechanism to a more efficient, push-based event system for message delivery. This will significantly reduce node load and improve real-time message propagation.
+- **Performance Optimizations:** Further improvements to message state handling and caching mechanisms.
 
 ---
 
@@ -253,5 +205,6 @@ npm run mine -- <bee-address> <topic-name>
 - [What are Feeds? (Official Swarm Documentation)](https://docs.ethswarm.org/docs/develop/tools-and-features/feeds#what-are-feeds)
 - [GSOC Introduction (Official Swarm Documentation)](https://docs.ethswarm.org/docs/develop/tools-and-features/gsoc/#introduction)
 - [Example Aggregator: Solar-Punk-Ltd/swarm-chat-aggregator-js](https://github.com/Solar-Punk-Ltd/swarm-chat-aggregator-js)
+- [Example React client](https://github.com/Solar-Punk-Ltd/swarm-chat-react-example)
 
 ---

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { SwarmChat } from './lib/core';
 export { EVENTS } from './lib/constants';
-export type { MessageData, ChatSettings } from './interfaces';
+export type { MessageData, ChatSettings, StatefulMessage, MessageStateRef } from './interfaces';
+export { MessageType } from './interfaces';
 export type { EthAddress } from '../node_modules/@ethersphere/bee-js/dist/types/index.d.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE9D,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEhG,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}