feat(chat): add sendWhisper (direct messages) and fix DirectChat decoder labels

Add sendWhisper(targetId, message) mirroring sendChat across SOOPChatClient, SOOPConnection and WebSocketManager, plus a createWhisperPacket builder (service code 0009 / CMD_DIRECT_CHAT). The public method guards on blank targetId, authentication and connection state.

Fix DirectChatDecoder: senderId/receiverId were swapped relative to the sender/receiver nicknames. Map senderId=parts[2], receiverId=parts[1] so the id and nickname pairs refer to the same user. Correct the type-field Javadoc (it is a sender flag, not a direction indicator).

Add unit tests (whisper packet, DirectChat decoder, client guards) and a README example. Verified end-to-end against the live SOOP server: outgoing send echo and incoming receive both confirmed.

Author: getCurrentThread

README.md

@@ -14,7 +14,7 @@
 - **Virtual Threads**: JDK 21+ Virtual Thread 기반 비동기 메시지 처리
 - **통합 API 클라이언트**: `SOOPClient` 파사드로 인증, 방송 정보, 채널 정보, 채팅을 통합 관리
 - **다중 채팅 연결**: bid 기준 dedup된 `add`/`remove`/`get` API와 `(streamerId, event)`를 함께 받는 글로벌 이벤트 리스너 지원
-- **채팅 전송 지원**: `sendChat()` 메서드로 채팅 메시지 전송
+- **채팅 전송 지원**: `sendChat()` / `sendWhisper()` 메서드로 채팅·귓말 전송
 - **익명(읽기 전용) 연결**: 인증 없이 채팅 수신 가능
 - WebSocket 기반 자동 재연결 및 핑 메커니즘
 - 이벤트 리스너 에러 핸들링
@@ -216,6 +216,9 @@ chat.connectToChat();
 
 // 4. 연결 완료 후 채팅 전송
 chat.sendChat("Hello!").join();
+
+// 5. 특정 사용자에게 귓말 전송 ("targetUser" = 받는 사람 로그인 ID, 닉네임/(n) 형태 아님)
+chat.sendWhisper("targetUser", "안녕하세요").join();
 ```
 
 ### 연결 상태 이벤트

lib/src/main/java/com/github/getcurrentthread/soopapi/client/SOOPChatClient.java

@@ -25,7 +25,8 @@
  * SOOP 채팅 클라이언트.
  *
  * <p>{@link SOOPChatConfig}에 {@code authCookie}가 설정되지 않은 경우, 클라이언트는 익명(읽기 전용) 모드로 연결됩니다. 익명 모드에서는
- * 채팅 메시지를 수신할 수 있지만, {@link #sendChat(String)}을 호출하면 {@link AuthenticationException}이 발생합니다.
+ * 채팅 메시지를 수신할 수 있지만, {@link #sendChat(String)}이나 {@link #sendWhisper(String, String)}을 호출하면 {@link
+ * AuthenticationException}이 발생합니다.
  */
 public class SOOPChatClient implements AutoCloseable {
     private static final Logger LOGGER = Logger.getLogger(SOOPChatClient.class.getName());
@@ -160,6 +161,33 @@ public CompletableFuture<Void> sendChat(String message) {
         return conn.sendChat(message);
     }
 
+    /**
+     * 특정 사용자에게 귓말(다이렉트 채팅)을 전송합니다.
+     *
+     * @param targetId 받는 사람의 SOOP 로그인 ID (예: {@code "targetUser"}). 닉네임이나 런타임 {@code (n)} 접미사 형태가
+     *     아닙니다.
+     * @param message 전송할 메시지
+     * @return 전송이 완료되면 완료되는 CompletableFuture. 인증되지 않았거나 연결되지 않은 경우, 또는 {@code targetId}가 비어 있는 경우
+     *     예외로 완료됩니다.
+     */
+    public CompletableFuture<Void> sendWhisper(String targetId, String message) {
+        if (targetId == null || targetId.isBlank()) {
+            return CompletableFuture.failedFuture(
+                    new IllegalArgumentException("targetId must not be null or blank"));
+        }
+        if (!config.isAuthenticated()) {
+            return CompletableFuture.failedFuture(
+                    new AuthenticationException(
+                            "Authentication required. Set AuthCookie to send whisper messages."));
+        }
+        SOOPConnection conn = this.connection;
+        if (conn == null || !isConnected) {
+            return CompletableFuture.failedFuture(
+                    new IllegalStateException("Not connected. Call connectToChat() first."));
+        }
+        return conn.sendWhisper(targetId, message);
+    }
+
     /**
      * 현재 연결 위에서 가벼운 재연결을 수행합니다.
      *

lib/src/main/java/com/github/getcurrentthread/soopapi/connection/SOOPConnection.java

@@ -210,6 +210,10 @@ public CompletableFuture<Void> sendChat(String message) {
         return webSocketManager.sendChat(message);
     }
 
+    public CompletableFuture<Void> sendWhisper(String targetId, String message) {
+        return webSocketManager.sendWhisper(targetId, message);
+    }
+
     public void disconnect() {
         connectionLock.lock();
         try {

lib/src/main/java/com/github/getcurrentthread/soopapi/decoder/message/DirectChatDecoder.java

@@ -5,6 +5,18 @@
 import com.github.getcurrentthread.soopapi.event.model.DirectChatEvent;
 import com.github.getcurrentthread.soopapi.util.SOOPChatUtils;
 
+/**
+ * 귓말(다이렉트 채팅) 메시지를 디코딩합니다.
+ *
+ * <p>프로토콜은 발신/수신 방향과 무관하게 동일한 필드 순서로 보냅니다: {@code message, receiverId, senderId, type, grade,
+ * senderNickname, receiverNickname, flag, ...}. 즉 {@code parts[2]}(senderId)가 {@code
+ * parts[5]}(senderNickname)와, {@code parts[1]}(receiverId)가 {@code parts[6]}(receiverNickname)와 짝을
+ * 이룹니다.
+ *
+ * <p>{@code type}은 방향 지시자가 <b>아니다</b>. 실측상 발신자가 일반 사용자면 {@code 0}, 방송인(BJ)이면 {@code 1}로 관찰되었다(내가 보낸
+ * echo·내가 받은 귓말 모두 포함). 방향은 {@code senderId}/{@code receiverId}를 내 로그인 ID와 비교해 판단하라. id 값에는 런타임
+ * {@code (n)} 접미사(예: {@code "myUser(2)"})가 그대로 포함될 수 있다.
+ */
 public class DirectChatDecoder implements IMessageDecoder {
     private static final int MIN_PARTS = 8;
 
@@ -15,8 +27,8 @@ public BaseEvent decode(String[] parts, String raw) {
         }
         return new DirectChatEvent(
                 parts[0],
-                parts[1],
                 parts[2],
+                parts[1],
                 SOOPChatUtils.safeParseInt(parts[3], 0),
                 parts[5],
                 parts[6],

lib/src/main/java/com/github/getcurrentthread/soopapi/websocket/WebSocketManager.java

@@ -417,6 +417,18 @@ public CompletableFuture<Void> sendChat(String message) {
                 .thenRun(() -> {});
     }
 
+    public CompletableFuture<Void> sendWhisper(String targetId, String message) {
+        String packet = WebSocketPacketBuilder.createWhisperPacket(targetId, message);
+        return requireActiveSocket()
+                .thenCompose(
+                        ws ->
+                                ws.sendText(packet, true)
+                                        .orTimeout(
+                                                config.getConnectionTimeout().toMillis(),
+                                                TimeUnit.MILLISECONDS))
+                .thenRun(() -> {});
+    }
+
     public CompletableFuture<Void> sendEnterInfo(String synAck) {
         LOGGER.fine("Sending ENTER_INFO packet...");
         String packet = WebSocketPacketBuilder.createEnterInfoPacket(synAck);

lib/src/main/java/com/github/getcurrentthread/soopapi/websocket/WebSocketPacketBuilder.java

@@ -17,6 +17,9 @@ public class WebSocketPacketBuilder {
     /** 채팅 메시지 전송의 명령 코드. */
     static final String CMD_CHAT = "0005";
 
+    /** 귓말(다이렉트 채팅) 전송의 명령 코드. */
+    static final String CMD_DIRECT_CHAT = "0009";
+
     /** 인증된 사용자 입장 정보의 명령 코드. */
     static final String CMD_ENTER_INFO = "0012";
 
@@ -109,6 +112,22 @@ public static String createChatPacket(String message) {
         return buildPacket(CMD_CHAT, SOOPConstants.F + message + SOOPConstants.F.repeat(6));
     }
 
+    /**
+     * 귓말(다이렉트 채팅) 전송 패킷을 생성합니다.
+     *
+     * <p>페이로드는 {@code F + message + F + targetId + F} 형태이며, {@code targetId}는 받는 사람의 SOOP 로그인 ID(예:
+     * {@code "targetUser"})입니다. 닉네임이나 런타임 {@code (n)} 접미사 형태가 아닙니다.
+     *
+     * @param targetId 받는 사람의 로그인 ID
+     * @param message 전송할 메시지
+     * @return 송신 가능한 귓말 패킷 문자열
+     */
+    public static String createWhisperPacket(String targetId, String message) {
+        return buildPacket(
+                CMD_DIRECT_CHAT,
+                SOOPConstants.F + message + SOOPConstants.F + targetId + SOOPConstants.F);
+    }
+
     private static String buildPacket(String command, String data) {
         int byteLength = SOOPChatUtils.utf8ByteLength(data);
         String lengthStr = String.valueOf(byteLength);

lib/src/test/java/com/github/getcurrentthread/soopapi/client/SOOPChatClientTest.java

@@ -191,6 +191,36 @@ void sendChat_withoutAuth_prioritizesAuthOverConnection() {
                 "Authentication error should occur before connection error");
     }
 
+    @Test
+    void sendWhisper_withoutAuth_throwsAuthenticationException() {
+        SOOPChatConfig config =
+                new SOOPChatConfig.Builder().bid("testStreamer").bno("12345").build();
+
+        SOOPChatClient client = new SOOPChatClient(config);
+
+        ExecutionException ex =
+                assertThrows(
+                        ExecutionException.class,
+                        () -> client.sendWhisper("targetUser", "Hello!").get());
+
+        assertInstanceOf(AuthenticationException.class, ex.getCause());
+    }
+
+    @Test
+    void sendWhisper_withBlankTargetId_throwsIllegalArgument() {
+        SOOPChatConfig config =
+                new SOOPChatConfig.Builder().bid("testStreamer").bno("12345").build();
+
+        SOOPChatClient client = new SOOPChatClient(config);
+
+        // targetId 검증은 인증/연결 검사보다 먼저 수행되므로 미인증 상태에서도 IllegalArgumentException이 발생해야 함
+        ExecutionException ex =
+                assertThrows(
+                        ExecutionException.class, () -> client.sendWhisper("  ", "Hello!").get());
+
+        assertInstanceOf(IllegalArgumentException.class, ex.getCause());
+    }
+
     @Test
     void constructor_withoutBno_doesNotThrow() {
         SOOPChatConfig config = new SOOPChatConfig.Builder().bid("testStreamer").build();

lib/src/test/java/com/github/getcurrentthread/soopapi/decoder/message/DirectChatDecoderTest.java

@@ -0,0 +1,83 @@
+package com.github.getcurrentthread.soopapi.decoder.message;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import com.github.getcurrentthread.soopapi.event.ChatEvent;
+import com.github.getcurrentthread.soopapi.event.model.BaseEvent;
+import com.github.getcurrentthread.soopapi.event.model.DirectChatEvent;
+
+class DirectChatDecoderTest {
+
+    private DirectChatDecoder decoder;
+
+    @BeforeEach
+    void setup() {
+        decoder = new DirectChatDecoder();
+    }
+
+    @Test
+    void decode_incomingWhisper_mapsSenderAndReceiverConsistently() {
+        // 방송인(BJ, peerUser)이 나(myUser)에게 보낸 귓말 — 발신자가 BJ라 type=1 (type은 방향이 아니라 발신자 구분 플래그)
+        // 원본 필드 순서: message | receiverId | senderId | type | grade | senderNick | receiverNick |
+        // flag | ...
+        String[] parts = {
+            "받은 귓말", "myUser(2)", "peerUser", "1", "3", "PeerNick", "MyNick", "100", "200", ""
+        };
+
+        BaseEvent result = decoder.decode(parts, "raw");
+
+        assertNotNull(result);
+        assertInstanceOf(DirectChatEvent.class, result);
+        DirectChatEvent event = (DirectChatEvent) result;
+
+        assertEquals("받은 귓말", event.message());
+        // 발신자 id와 닉네임이 같은 사람(상대)을 가리켜야 함
+        assertEquals("peerUser", event.senderId());
+        assertEquals("PeerNick", event.senderNickname());
+        // 수신자 id와 닉네임이 같은 사람(나)을 가리켜야 함
+        assertEquals("myUser(2)", event.receiverId());
+        assertEquals("MyNick", event.receiverNickname());
+        assertEquals(1, event.type());
+        assertEquals("100", event.flag());
+        assertEquals(ChatEvent.DIRECT_CHAT, event.eventType());
+    }
+
+    @Test
+    void decode_outgoingEcho_mapsSenderAndReceiverConsistently() {
+        // 내가(myUser, 일반 사용자) peerUser에게 보낸 귓말의 echo — 발신자가 BJ가 아니라 type=0
+        String[] parts = {
+            "보낸 귓말", "peerUser", "myUser(2)", "0", "3", "MyNick", "PeerNick", "300", "400", ""
+        };
+
+        BaseEvent result = decoder.decode(parts, "raw");
+
+        assertNotNull(result);
+        DirectChatEvent event = (DirectChatEvent) result;
+
+        assertEquals("보낸 귓말", event.message());
+        // echo에서 발신자는 나
+        assertEquals("myUser(2)", event.senderId());
+        assertEquals("MyNick", event.senderNickname());
+        // 수신자는 상대
+        assertEquals("peerUser", event.receiverId());
+        assertEquals("PeerNick", event.receiverNickname());
+        assertEquals(0, event.type());
+    }
+
+    @Test
+    void decode_tooFewParts_returnsNull() {
+        String[] parts = {"msg", "a", "b", "1", "2", "nick", "0"}; // 7개 (< 8)
+
+        BaseEvent result = decoder.decode(parts, "raw");
+
+        assertNull(result, "Should return null for fewer than 8 parts");
+    }
+
+    @Test
+    void decode_emptyParts_returnsNull() {
+        assertNull(decoder.decode(new String[0], "raw"));
+    }
+}

lib/src/test/java/com/github/getcurrentthread/soopapi/websocket/WebSocketPacketBuilderTest.java

@@ -129,6 +129,55 @@ void chatPacket_containsMessage() {
         assertTrue(packet.contains(message), "Chat packet should contain the message");
     }
 
+    @Test
+    void whisperPacket_hasCorrectCommand() {
+        String packet = WebSocketPacketBuilder.createWhisperPacket("targetUser", "hi");
+
+        assertTrue(packet.startsWith(SOOPConstants.ESC));
+        String command =
+                packet.substring(SOOPConstants.ESC.length(), SOOPConstants.ESC.length() + 4);
+        assertEquals(WebSocketPacketBuilder.CMD_DIRECT_CHAT, command);
+    }
+
+    @Test
+    void whisperPacket_containsMessageAndTargetId() {
+        String packet = WebSocketPacketBuilder.createWhisperPacket("targetUser", "Hello");
+
+        assertTrue(packet.contains("Hello"), "Whisper packet should contain the message");
+        assertTrue(packet.contains("targetUser"), "Whisper packet should contain the targetId");
+    }
+
+    @Test
+    void whisperPacket_lengthField_matchesUtf8ByteLength() {
+        // F + "안녕" + F + "targetUser" + F = 1 + 6 + 1 + 10 + 1 = 19 (한글은 UTF-8에서 글자당 3바이트)
+        String packet = WebSocketPacketBuilder.createWhisperPacket("targetUser", "안녕");
+        int lengthStart = SOOPConstants.ESC.length() + 4;
+        String lengthField = packet.substring(lengthStart, lengthStart + 6);
+
+        assertEquals("000019", lengthField);
+    }
+
+    @Test
+    void whisperPacket_lengthField_isSixZeroPaddedDigits() {
+        String packet = WebSocketPacketBuilder.createWhisperPacket("user", "hi");
+        int lengthStart = SOOPConstants.ESC.length() + 4;
+        String lengthField = packet.substring(lengthStart, lengthStart + 6);
+
+        assertTrue(lengthField.matches("\\d{6}"), "Length field should be 6 zero-padded digits");
+    }
+
+    @Test
+    void whisperPacket_fieldOrder_isMessageThenTarget() {
+        // 페이로드 레이아웃 검증: F + message + F + targetId + F (메시지가 targetId보다 앞, 끝에 단일 F)
+        String packet = WebSocketPacketBuilder.createWhisperPacket("targetUser", "msg");
+        String expectedData =
+                SOOPConstants.F + "msg" + SOOPConstants.F + "targetUser" + SOOPConstants.F;
+
+        assertTrue(
+                packet.endsWith(expectedData),
+                "message must precede targetId, with a single trailing F");
+    }
+
     @Test
     void enterInfoPacket_hasCorrectCommand() {
         String packet = WebSocketPacketBuilder.createEnterInfoPacket("syn_ack_value");