agent-messenger 2.29.1 → 2.31.0

package/src/platforms/kakaotalk/client.test.ts

@@ -15,6 +15,8 @@ const mockSyncMessages = mock(() => Promise.resolve({}))
 const mockSendMessage = mock(() => Promise.resolve({}))
 const mockSendReply = mock(() => Promise.resolve({}))
 const mockMarkRead = mock(() => Promise.resolve({}))
+const mockLeaveChat = mock(() => Promise.resolve({}))
+const mockSendTyping = mock(() => Promise.resolve({}))
 const mockClose = mock(() => {})
 const mockOnClose = mock((_handler: () => void) => {})
 const mockOnPush = mock((_handler: (packet: unknown) => void) => {})
@@ -33,6 +35,8 @@ mock.module('./protocol/session', () => ({
     sendMessage = mockSendMessage
     sendReply = mockSendReply
     markRead = mockMarkRead
+    leaveChat = mockLeaveChat
+    sendTyping = mockSendTyping
     close = mockClose
     onClose = mockOnClose
     onPush = mockOnPush
@@ -56,6 +60,8 @@ function resetAllMocks() {
   mockSendMessage.mockReset()
   mockSendReply.mockReset()
   mockMarkRead.mockReset()
+  mockLeaveChat.mockReset()
+  mockSendTyping.mockReset()
   mockClose.mockReset()
   mockOnClose.mockReset()
   mockOnPush.mockReset()
@@ -96,7 +102,9 @@ const DEFAULT_LOGIN_RESULT = {
 describe('KakaoTalkClient', () => {
   beforeEach(() => {
     resetAllMocks()
-    mockLogin.mockResolvedValue(DEFAULT_LOGIN_RESULT)
+    // Deep-clone so tests that mutate loginResult.chatDatas (e.g. leaveChat)
+    // don't leak into subsequent tests.
+    mockLogin.mockResolvedValue(structuredClone(DEFAULT_LOGIN_RESULT))
     mockGetChatLogs.mockResolvedValue({ body: { status: 0, chatLogs: [], eof: true } })
     mockGetChatInfo.mockResolvedValue({ body: { l: makeLong(99999) } })
   })
@@ -1239,6 +1247,191 @@ describe('KakaoTalkClient', () => {
     })
   })
 
+  describe('leaveChat', () => {
+    it('calls session.leaveChat with parsed chatId and returns success', async () => {
+      mockLeaveChat.mockResolvedValueOnce({ statusCode: 0, body: {} })
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      const result = await client.leaveChat('100')
+
+      expect(result).toEqual({ success: true, status_code: 0, chat_id: '100' })
+      expect(mockLeaveChat).toHaveBeenCalledWith(expect.objectContaining({ low: 100, high: 0 }))
+
+      client.close()
+    })
+
+    it('treats synthetic disconnect packet (statusCode: -1) as transport failure (throws)', async () => {
+      mockLeaveChat.mockResolvedValueOnce({ statusCode: -1, body: { error: 'connection closed' } })
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      try {
+        await client.leaveChat('100')
+        throw new Error('expected to throw')
+      } catch (e) {
+        expect(e).toBeInstanceOf(KakaoTalkError)
+        expect((e as KakaoTalkError).code).toBe('leave_chat_failed')
+      }
+
+      client.close()
+    })
+
+    it('evicts the departed chat from getChats cache', async () => {
+      mockLeaveChat.mockResolvedValueOnce({ statusCode: 0, body: {} })
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      const before = await client.getChats()
+      expect(before).toHaveLength(2)
+
+      await client.leaveChat('100')
+
+      const after = await client.getChats()
+      expect(after).toHaveLength(1)
+      expect(after[0].chat_id).toBe('200')
+
+      client.close()
+    })
+
+    it('reconnects and retries leaveChat after silent disconnect (full executeWithReconnect path)', async () => {
+      const closeHandlers: Array<() => void> = []
+      mockOnClose.mockImplementation((handler: () => void) => {
+        closeHandlers.push(handler)
+      })
+
+      mockLeaveChat.mockImplementationOnce(() => {
+        const handler = closeHandlers[0]
+        if (handler) handler()
+        return Promise.resolve({ statusCode: -1, body: { error: 'connection closed' } })
+      })
+      mockLeaveChat.mockResolvedValueOnce({ statusCode: 0, body: {} })
+
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+      const result = await client.leaveChat('100')
+
+      expect(result.success).toBe(true)
+      expect(mockLeaveChat).toHaveBeenCalledTimes(2)
+      expect(mockLogin).toHaveBeenCalledTimes(2)
+
+      client.close()
+    })
+
+    it('throws KakaoTalkError(invalid_chat_id) for non-numeric chatId', async () => {
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      try {
+        await client.leaveChat('not-a-number')
+        throw new Error('expected to throw')
+      } catch (e) {
+        expect(e).toBeInstanceOf(KakaoTalkError)
+        expect((e as KakaoTalkError).code).toBe('invalid_chat_id')
+      }
+
+      client.close()
+    })
+
+    it('wraps transport errors as KakaoTalkError(leave_chat_failed)', async () => {
+      mockLeaveChat.mockRejectedValue(new Error('Socket closed'))
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      try {
+        await client.leaveChat('100')
+        throw new Error('expected to throw')
+      } catch (e) {
+        expect(e).toBeInstanceOf(KakaoTalkError)
+        expect((e as KakaoTalkError).code).toBe('leave_chat_failed')
+      }
+
+      client.close()
+    })
+  })
+
+  describe('sendTyping', () => {
+    it('forwards parsed chatId to session.sendTyping and reports success on statusCode 0', async () => {
+      mockSendTyping.mockResolvedValueOnce({ statusCode: 0, body: {} })
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      const result = await client.sendTyping('12345')
+
+      expect(mockSendTyping).toHaveBeenCalledTimes(1)
+      const [chatIdArg, linkIdArg] = mockSendTyping.mock.calls[0] as [{ toString(): string }, unknown]
+      expect(chatIdArg.toString()).toBe('12345')
+      expect(linkIdArg).toBeUndefined()
+      expect(result).toEqual({ success: true, status_code: 0, chat_id: '12345' })
+
+      client.close()
+    })
+
+    it('passes linkId through when provided (open-chat typing)', async () => {
+      mockSendTyping.mockResolvedValueOnce({ statusCode: 0, body: {} })
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      await client.sendTyping('12345', { linkId: '77777' })
+
+      const [, linkIdArg] = mockSendTyping.mock.calls[0] as [unknown, { toString(): string }]
+      expect(linkIdArg).toBeDefined()
+      expect(linkIdArg.toString()).toBe('77777')
+
+      client.close()
+    })
+
+    it('throws KakaoTalkError(send_typing_failed) on transport-level failure (non-zero statusCode)', async () => {
+      mockSendTyping.mockResolvedValueOnce({ statusCode: -100, body: {} })
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      try {
+        await client.sendTyping('12345')
+        throw new Error('expected to throw')
+      } catch (e) {
+        expect(e).toBeInstanceOf(KakaoTalkError)
+        expect((e as KakaoTalkError).code).toBe('send_typing_failed')
+      }
+
+      client.close()
+    })
+
+    it('throws KakaoTalkError(send_typing_failed) when the session throws (transport error)', async () => {
+      mockSendTyping.mockRejectedValue(new Error('ACTION failed: statusCode=-1'))
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      try {
+        await client.sendTyping('12345')
+        throw new Error('expected to throw')
+      } catch (e) {
+        expect(e).toBeInstanceOf(KakaoTalkError)
+        expect((e as KakaoTalkError).code).toBe('send_typing_failed')
+      }
+
+      client.close()
+    })
+
+    it('throws KakaoTalkError(invalid_chat_id) for non-numeric chatId', async () => {
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      try {
+        await client.sendTyping('not-a-number')
+        throw new Error('expected to throw')
+      } catch (e) {
+        expect(e).toBeInstanceOf(KakaoTalkError)
+        expect((e as KakaoTalkError).code).toBe('invalid_chat_id')
+      }
+
+      client.close()
+    })
+
+    it('throws KakaoTalkError(invalid_link_id) for non-numeric linkId', async () => {
+      const client = await new KakaoTalkClient().login({ oauthToken: 'token', userId: 'user1', deviceUuid: 'device1' })
+
+      try {
+        await client.sendTyping('12345', { linkId: 'not-a-number' })
+        throw new Error('expected to throw')
+      } catch (e) {
+        expect(e).toBeInstanceOf(KakaoTalkError)
+        expect((e as KakaoTalkError).code).toBe('invalid_link_id')
+      }
+
+      client.close()
+    })
+  })
+
   describe('getMembers / getMembersByIds', () => {
     it('returns formatted members from GETMEM with normalized fields', async () => {
       mockGetAllMembers.mockResolvedValueOnce({

package/src/platforms/kakaotalk/client.ts

@@ -18,6 +18,7 @@ import {
   KAKAO_MESSAGE_TYPE,
   type KakaoChat,
   type KakaoDeviceType,
+  type KakaoLeaveChatResult,
   type KakaoMarkReadResult,
   type KakaoMember,
   type KakaoMessage,
@@ -26,6 +27,7 @@ import {
   type KakaoReplyExtra,
   type KakaoReplyTarget,
   type KakaoSendResult,
+  type KakaoTypingResult,
 } from './types'
 
 export type KakaoSessionEvent =
@@ -982,6 +984,30 @@ export class KakaoTalkClient {
     })
   }
 
+  async sendTyping(chatId: string, opts?: { linkId?: string }): Promise<KakaoTypingResult> {
+    const parsedChatId = parseChatId(chatId)
+    const parsedLinkId = opts?.linkId !== undefined ? parseLinkId(opts.linkId) : undefined
+
+    return this.executeWithReconnect(async ({ session }) => {
+      try {
+        const response = await session.sendTyping(parsedChatId, parsedLinkId)
+        // Throw on transport-level failure (incl. synthetic { statusCode: -1 }
+        // from LocoConnection.handleClose) so executeWithReconnect retries on
+        // a fresh session — matches the markRead pattern.
+        if (response.statusCode !== 0) {
+          throw new Error(`ACTION failed: statusCode=${response.statusCode}`)
+        }
+        return {
+          success: true,
+          status_code: response.statusCode,
+          chat_id: chatId,
+        }
+      } catch (error) {
+        throw wrapError(error, 'send_typing_failed')
+      }
+    })
+  }
+
   async sendAttachment(
     chatId: string,
     data: Uint8Array | Buffer,
@@ -1317,6 +1343,38 @@ export class KakaoTalkClient {
     })
   }
 
+  async leaveChat(chatId: string): Promise<KakaoLeaveChatResult> {
+    const parsedChatId = parseChatId(chatId)
+
+    return this.executeWithReconnect(async ({ session, loginResult }) => {
+      try {
+        const response = await session.leaveChat(parsedChatId)
+        // Throw on transport-level failure (incl. synthetic { statusCode: -1 }
+        // from LocoConnection.handleClose) so executeWithReconnect retries on
+        // a fresh session. The LEAVE command result lives in statusCode.
+        if (response.statusCode !== 0) {
+          throw new Error(`LEAVE failed: statusCode=${response.statusCode}`)
+        }
+        // Evict the departed chat from in-memory caches so subsequent getChats()
+        // calls do not return stale entries for this room.  Normalize via
+        // longToString(parsedChatId) so the cache key matches the canonical
+        // format used by the server (e.g. "0100" → "100").
+        const normalizedChatId = longToString(parsedChatId)
+        const raw = (loginResult.chatDatas ?? []) as ChatData[]
+        const idx = raw.findIndex((c) => longToString(c.c) === normalizedChatId)
+        if (idx !== -1) raw.splice(idx, 1)
+        this.nameCache.forget(normalizedChatId)
+        return {
+          success: true,
+          status_code: 0,
+          chat_id: chatId,
+        }
+      } catch (error) {
+        throw wrapError(error, 'leave_chat_failed')
+      }
+    })
+  }
+
   async getProfile(): Promise<KakaoProfile> {
     this.ensureAuth()
     try {

package/src/platforms/kakaotalk/commands/chat.test.ts

@@ -13,8 +13,11 @@ const mockGetChats = mock(() =>
   ]),
 )
 
+const mockLeaveChat = mock(() => Promise.resolve({ success: true, status_code: 0, chat_id: 'chat-1' }))
+
 const mockClient = {
   getChats: mockGetChats,
+  leaveChat: mockLeaveChat,
 }
 
 mock.module('./shared', () => ({
@@ -29,6 +32,7 @@ describe('chat commands', () => {
   beforeEach(() => {
     mockWithKakaoClient.mockReset()
     mockGetChats.mockReset()
+    mockLeaveChat.mockReset()
 
     mockWithKakaoClient.mockImplementation(async (_options: unknown, fn: (client: unknown) => Promise<unknown>) => {
       return fn(mockClient)
@@ -39,6 +43,7 @@ describe('chat commands', () => {
         { chat_id: 'chat-2', name: 'Direct', type: 'direct', member_count: 2 },
       ]),
     )
+    mockLeaveChat.mockImplementation(() => Promise.resolve({ success: true, status_code: 0, chat_id: 'chat-1' }))
 
     consoleLogSpy = mock((..._args: unknown[]) => {})
     console.log = consoleLogSpy
@@ -91,4 +96,23 @@ describe('chat commands', () => {
       expect(output).toEqual([])
     })
   })
+
+  describe('leave', () => {
+    it('leaves a chat room', async () => {
+      await chatCommand.parseAsync(['leave', 'chat-1'], { from: 'user' })
+
+      expect(mockLeaveChat).toHaveBeenCalledWith('chat-1')
+      const output = JSON.parse(consoleLogSpy.mock.calls[0][0])
+      expect(output).toEqual({ success: true, status_code: 0, chat_id: 'chat-1' })
+    })
+
+    it('passes account option to withKakaoClient', async () => {
+      await chatCommand.parseAsync(['leave', 'chat-1', '--account', 'my-account'], { from: 'user' })
+
+      expect(mockWithKakaoClient).toHaveBeenCalledWith(
+        expect.objectContaining({ account: 'my-account' }),
+        expect.any(Function),
+      )
+    })
+  })
 })

package/src/platforms/kakaotalk/commands/chat.ts

@@ -22,6 +22,21 @@ async function listAction(options: {
   }
 }
 
+async function leaveAction(
+  chatId: string,
+  options: {
+    account?: string
+    pretty?: boolean
+  },
+): Promise<void> {
+  try {
+    const result = await withKakaoClient(options, (client) => client.leaveChat(chatId))
+    console.log(formatOutput(result, options.pretty))
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
 export const chatCommand = new Command('chat')
   .description('KakaoTalk chat commands')
   .addCommand(
@@ -34,3 +49,11 @@ export const chatCommand = new Command('chat')
       .option('--pretty', 'Pretty print JSON output')
       .action(listAction),
   )
+  .addCommand(
+    new Command('leave')
+      .description('Leave a chat room')
+      .argument('<chat-id>', 'Chat room ID')
+      .option('--account <id>', 'Use a specific KakaoTalk account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(leaveAction),
+  )

package/src/platforms/kakaotalk/index.test.ts

@@ -7,6 +7,7 @@ import {
   KakaoCredentialManager,
   KakaoChatSchema,
   KakaoConfigSchema,
+  KakaoLeaveChatResultSchema,
   KakaoMessageSchema,
   KakaoSendResultSchema,
   KakaoTalkClient,
@@ -16,6 +17,7 @@ import {
   KakaoTalkPushMessageEventSchema,
   KakaoProfileSchema,
   KakaoTalkPushReadEventSchema,
+  KakaoTypingResultSchema,
 } from '@/platforms/kakaotalk/index'
 
 it('KakaoTalkClient is exported from barrel', () => {
@@ -77,3 +79,11 @@ it('KakaoProfileSchema is exported from barrel', () => {
 it('classifyKakaoChat is exported from barrel', () => {
   expect(typeof classifyKakaoChat).toBe('function')
 })
+
+it('KakaoLeaveChatResultSchema is exported from barrel', () => {
+  expect(typeof KakaoLeaveChatResultSchema.parse).toBe('function')
+})
+
+it('KakaoTypingResultSchema is exported from barrel', () => {
+  expect(typeof KakaoTypingResultSchema.parse).toBe('function')
+})

package/src/platforms/kakaotalk/index.ts

@@ -13,6 +13,7 @@ export type {
   KakaoEmoticonKind,
   KakaoEmoticonMessageType,
   KakaoFileExtra,
+  KakaoLeaveChatResult,
   KakaoLoginResult,
   KakaoMarkReadResult,
   KakaoMember,
@@ -30,6 +31,7 @@ export type {
   KakaoTalkPushMemberEvent,
   KakaoTalkPushMessageEvent,
   KakaoTalkPushReadEvent,
+  KakaoTypingResult,
 } from './types'
 export {
   KAKAO_EMOTICON_KIND_BY_TYPE,
@@ -38,6 +40,7 @@ export {
   KakaoAccountCredentialsSchema,
   KakaoChatSchema,
   KakaoConfigSchema,
+  KakaoLeaveChatResultSchema,
   KakaoMarkReadResultSchema,
   KakaoMemberSchema,
   KakaoMessageSchema,
@@ -47,6 +50,7 @@ export {
   KakaoTalkPushMemberEventSchema,
   KakaoTalkPushMessageEventSchema,
   KakaoTalkPushReadEventSchema,
+  KakaoTypingResultSchema,
 } from './types'
 export { attemptLogin, generateDeviceUuid, loginFlow, registerDevice, requestPasscode } from './auth/kakao-login'
 export type { LoginCredentials } from './auth/kakao-login'

package/src/platforms/kakaotalk/protocol/session.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it, mock } from 'bun:test'
+
+import { Long } from 'bson'
+
+import { buildTypingActionBody, sendTypingPacket, TYPING_ACTION_METHOD } from './session'
+import type { LocoPacket } from './types'
+
+type SentPacket = { method: string; body: Record<string, unknown> }
+
+// Fake connection object that captures every sendPacket call. We test
+// sendTypingPacket (the extracted wire-boundary function) directly rather than
+// the LocoSession class method — LocoSession.sendTyping is a two-line delegation
+// to this helper, and testing the class would require mock.module('./session',
+// …) which collides with client.test.ts's LocoSession mock.
+function fakeConnection(returnPacket: LocoPacket = { statusCode: 0, body: {} }): {
+  connection: { sendPacket: (method: string, body: Record<string, unknown>) => Promise<LocoPacket> }
+  sent: SentPacket[]
+  sendPacketMock: ReturnType<typeof mock>
+} {
+  const sent: SentPacket[] = []
+  const sendPacketMock = mock(async (method: string, body: Record<string, unknown>) => {
+    sent.push({ method, body })
+    return returnPacket
+  })
+  return { connection: { sendPacket: sendPacketMock }, sent, sendPacketMock }
+}
+
+describe('typing indicator wire contract', () => {
+  it('TYPING_ACTION_METHOD is the exact string "ACTION" that KakaoTalk expects on the wire', () => {
+    expect(TYPING_ACTION_METHOD).toBe('ACTION')
+  })
+
+  it('emits type=1 and omits linkId entirely for normal chats', () => {
+    const body = buildTypingActionBody(Long.fromString('459750513901477'))
+
+    expect((body.chatId as { toString(): string }).toString()).toBe('459750513901477')
+    expect(body.type).toBe(1)
+    expect('linkId' in body).toBe(false)
+  })
+
+  it('includes linkId when provided (open-chat pulse)', () => {
+    const body = buildTypingActionBody(Long.fromString('123'), Long.fromString('77777'))
+
+    expect(body.type).toBe(1)
+    expect((body.linkId as { toString(): string }).toString()).toBe('77777')
+  })
+
+  it('never sets linkId=null when caller passes undefined (would change server routing)', () => {
+    const body = buildTypingActionBody(Long.fromString('123'), undefined)
+
+    expect(body.linkId).toBeUndefined()
+    expect('linkId' in body).toBe(false)
+  })
+
+  it('body only carries chatId + type for normal chats (no stray fields)', () => {
+    const body = buildTypingActionBody(Long.fromString('123'))
+
+    expect(Object.keys(body).sort()).toEqual(['chatId', 'type'])
+  })
+
+  it('body only carries chatId + type + linkId for open chats (no stray fields)', () => {
+    const body = buildTypingActionBody(Long.fromString('123'), Long.fromString('77777'))
+
+    expect(Object.keys(body).sort()).toEqual(['chatId', 'linkId', 'type'])
+  })
+})
+
+describe('sendTypingPacket → sendPacket wire boundary', () => {
+  it('calls connection.sendPacket("ACTION", body) exactly once for a normal chat, with full-width Long chatId preserved', async () => {
+    const { connection, sent, sendPacketMock } = fakeConnection()
+
+    await sendTypingPacket(connection, Long.fromString('459750513901477'))
+
+    expect(sendPacketMock).toHaveBeenCalledTimes(1)
+    expect(sent).toHaveLength(1)
+    const packet = sent[0]!
+    expect(packet.method).toBe('ACTION')
+    expect((packet.body.chatId as Long).toString()).toBe('459750513901477')
+    expect(packet.body.type).toBe(1)
+    expect('linkId' in packet.body).toBe(false)
+  })
+
+  it('calls sendPacket with full-width Long linkId preserved for an open-chat pulse', async () => {
+    const { connection, sent } = fakeConnection()
+
+    await sendTypingPacket(connection, Long.fromString('459750513901477'), Long.fromString('280368495100000'))
+
+    const packet = sent[0]!
+    expect(packet.method).toBe('ACTION')
+    expect((packet.body.chatId as Long).toString()).toBe('459750513901477')
+    expect((packet.body.linkId as Long).toString()).toBe('280368495100000')
+    expect(packet.body.type).toBe(1)
+  })
+
+  it('propagates the LocoPacket returned by sendPacket verbatim', async () => {
+    const expected = { statusCode: 0, body: { hello: 'world' } }
+    const { connection } = fakeConnection(expected)
+
+    const result = await sendTypingPacket(connection, Long.fromString('123'))
+
+    expect(result).toBe(expected)
+  })
+
+  it('emits the same wire packet the reverse-engineered client builds (spec-lock)', async () => {
+    const { connection, sent } = fakeConnection()
+
+    await sendTypingPacket(connection, Long.fromString('123'), Long.fromString('456'))
+
+    const packet = sent[0]!
+    expect(packet.method).toBe(TYPING_ACTION_METHOD)
+    expect(packet.body).toEqual(buildTypingActionBody(Long.fromString('123'), Long.fromString('456')))
+  })
+})

package/src/platforms/kakaotalk/protocol/session.ts

@@ -17,6 +17,36 @@ import {
 import { LocoConnection } from './connection'
 import type { BookingResponse, CheckinResponse, LoginListResponse, LocoPacket, SyncState } from './types'
 
+// LOCO opcode string emitted on the wire for typing indicator pulses.
+// Reverse-engineered from KakaoTalk 25.x — see `LocoSession.sendTyping` docs.
+export const TYPING_ACTION_METHOD = 'ACTION'
+
+// Builds the BSON body the official KakaoTalk client emits for the typing
+// indicator subtype of the `ACTION` opcode. Exported so protocol tests can lock
+// the exact field shape.
+export function buildTypingActionBody(chatId: Long, linkId?: Long): Record<string, unknown> {
+  const body: Record<string, unknown> = { chatId, type: 1 }
+  // Must omit the field entirely (not `null`) for normal chats — the official
+  // client only populates linkId for OpenChat rooms, and sending null here
+  // would change server routing.
+  if (linkId !== undefined) body.linkId = linkId
+  return body
+}
+
+// The one-and-only delegation from `LocoSession.sendTyping` to a `sendPacket`
+// implementation. Extracting this makes the wire boundary directly testable
+// with a fake connection object — no `LocoSession` instantiation required,
+// which side-steps the `mock.module('./session', …)` set up by `client.test.ts`.
+// `LocoSession.sendTyping` is a 2-line delegation to this helper, so any test
+// that pins this function's behaviour also pins the class method's contract.
+export async function sendTypingPacket(
+  connection: { sendPacket: (method: string, body: Record<string, unknown>) => Promise<LocoPacket> },
+  chatId: Long,
+  linkId?: Long,
+): Promise<LocoPacket> {
+  return connection.sendPacket(TYPING_ACTION_METHOD, buildTypingActionBody(chatId, linkId))
+}
+
 export class LocoSession {
   private connection: LocoConnection | null = null
   private pingTimer: ReturnType<typeof setInterval> | null = null
@@ -289,6 +319,11 @@ export class LocoSession {
    * supply `linkId`; normal chats must omit it (the wire `li` key must be
    * absent, not null/0).
    */
+  async leaveChat(chatId: Long): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    return this.connection.sendPacket('LEAVE', { chatId })
+  }
+
   async markRead(chatId: Long, watermark: Long, linkId?: Long): Promise<LocoPacket> {
     if (!this.connection) throw new Error('Not connected')
     const body: Record<string, unknown> = { chatId, watermark }
@@ -298,6 +333,27 @@ export class LocoSession {
     return this.connection.sendPacket('NOTIREAD', body)
   }
 
+  /**
+   * Fire a single typing pulse to peers of a chat — this is what triggers the
+   * animated "…" dots the recipient sees while somebody is composing.
+   *
+   * Under the hood this sends the LOCO `ACTION` opcode with `type=1`. The
+   * KakaoTalk client-side lifetime is ~5s per pulse, so callers wanting a
+   * sustained indicator must re-fire faster than that.
+   *
+   * Reverse-engineered from KakaoTalk 25.x: the app's LOCO layer emits an
+   * `ACTION` packet with a BSON body of `{chatId, type, linkId?}` when the
+   * user types in a chat. `type=1` is the value the app uses for the typing
+   * indicator; other `type` values may exist for other in-composition states
+   * (recording audio, attaching media, etc.) but haven't been verified. The
+   * `linkId` field is omitted entirely (not sent as null) for normal chats;
+   * it is only populated for OpenChat rooms.
+   */
+  async sendTyping(chatId: Long, linkId?: Long): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    return sendTypingPacket(this.connection, chatId, linkId)
+  }
+
   onPush(handler: (packet: LocoPacket) => void): void {
     this.pushHandler = handler
     if (this.connection) {

package/src/platforms/kakaotalk/types.ts

@@ -207,6 +207,18 @@ export interface KakaoMarkReadResult {
   watermark: string
 }
 
+export interface KakaoLeaveChatResult {
+  success: boolean
+  status_code: number
+  chat_id: string
+}
+
+export interface KakaoTypingResult {
+  success: boolean
+  status_code: number
+  chat_id: string
+}
+
 export const KakaoChatSchema = z.object({
   chat_id: z.string(),
   type: z.number(),
@@ -263,6 +275,18 @@ export const KakaoMarkReadResultSchema = z.object({
   watermark: z.string(),
 })
 
+export const KakaoLeaveChatResultSchema = z.object({
+  success: z.boolean(),
+  status_code: z.number(),
+  chat_id: z.string(),
+})
+
+export const KakaoTypingResultSchema = z.object({
+  success: z.boolean(),
+  status_code: z.number(),
+  chat_id: z.string(),
+})
+
 export interface KakaoProfile {
   user_id: string
   nickname: string