agent-messenger 2.32.3 → 2.34.0

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

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, spyOn } from 'bun:test'
 
 import { DiscordClient, DiscordError } from './client'
-import type { DiscordReadState } from './types'
+import type { DiscordDMChannel, DiscordReadState } from './types'
 
 describe('DiscordClient', () => {
   const originalFetch = globalThis.fetch
@@ -362,6 +362,59 @@ describe('DiscordClient', () => {
     })
   })
 
+  describe('getMyGuildMember', () => {
+    const member = {
+      user: { id: 'user-1', username: 'alice' },
+      roles: ['role-1'],
+      joined_at: '2024-01-15T10:00:00Z',
+      deaf: false,
+      mute: false,
+      flags: 0,
+    }
+
+    it('gets the current user guild member', async () => {
+      mockResponse(member)
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      const result = await client.getMyGuildMember('guild-1')
+
+      expect(result).toEqual(member)
+      expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/users/@me/guilds/guild-1/member')
+    })
+
+    it('surfaces the error when the user is not in the guild', async () => {
+      mockResponse({ message: 'Unknown Guild', code: 10004 }, 404)
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+
+      await expect(client.getMyGuildMember('guild-1')).rejects.toEqual(new DiscordError('Unknown Guild', '10004'))
+      expect(fetchCalls).toHaveLength(1)
+    })
+  })
+
+  describe('listRoles', () => {
+    it('lists guild role definitions', async () => {
+      mockResponse([
+        {
+          id: 'role-1',
+          name: 'Member',
+          color: 0,
+          hoist: false,
+          position: 1,
+          permissions: '1024',
+          managed: false,
+          mentionable: false,
+        },
+      ])
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      const roles = await client.listRoles('guild-1')
+
+      expect(roles).toHaveLength(1)
+      expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/guilds/guild-1/roles')
+    })
+  })
+
   describe('uploadFile', () => {
     it('uploads file to channel', async () => {
       const tempFile = '/tmp/test-upload.txt'
@@ -896,4 +949,154 @@ describe('DiscordClient', () => {
       expect(result.count).toBe(100)
     })
   })
+
+  describe('getUnreadDMs', () => {
+    const dmChannel = (id: string, lastMessageId?: string, type = 1): DiscordDMChannel => ({
+      id,
+      type,
+      recipients: [{ id: `u${id}`, username: `user${id}` }],
+      ...(lastMessageId ? { last_message_id: lastMessageId } : {}),
+    })
+
+    const stub = (client: DiscordClient, channels: DiscordDMChannel[], states: DiscordReadState[], partial = false) => {
+      spyOn(client, 'listDMChannels').mockResolvedValue(channels)
+      spyOn(client, 'fetchReadStateSnapshot').mockResolvedValue({ states, partial })
+    }
+
+    it('keeps channels whose newest message is past the read marker', async () => {
+      // given: c1 has a message newer than its marker, c2 is fully read
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(
+        client,
+        [dmChannel('c1', '200'), dmChannel('c2', '50')],
+        [
+          { channelId: 'c1', lastMessageId: '100', mentionCount: 2 },
+          { channelId: 'c2', lastMessageId: '100', mentionCount: 0 },
+        ],
+      )
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.count).toBe(1)
+      expect(result.channels[0].id).toBe('c1')
+      expect(result.channels[0].unreadCount).toBe(2)
+      expect(result.totalUnread).toBe(2)
+    })
+
+    it('treats an equal snowflake as read', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(client, [dmChannel('c1', '100')], [{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.count).toBe(0)
+    })
+
+    it('compares snowflakes beyond the safe integer range', async () => {
+      // given: two 19-digit snowflakes that collapse to the same value as Numbers
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(
+        client,
+        [dmChannel('c1', '1234567890123456789')],
+        [{ channelId: 'c1', lastMessageId: '1234567890123456788', mentionCount: 1 }],
+      )
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.count).toBe(1)
+    })
+
+    it('surfaces a channel with no read-state entry as an unknown count', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(client, [dmChannel('c1', '200')], [])
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.count).toBe(1)
+      expect(result.channels[0].unreadCount).toBeNull()
+      // then: an unknown count must not be summed as zero-or-anything-else
+      expect(result.totalUnread).toBe(0)
+      expect(result.complete).toBe(true)
+    })
+
+    it('omits absent entries when the read state is partial', async () => {
+      // given: an incomplete collection, where absence means "not delivered", not "never read"
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(client, [dmChannel('c1', '200')], [], true)
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.count).toBe(0)
+      expect(result.complete).toBe(false)
+    })
+
+    it('still reports channels past their marker when the read state is partial', async () => {
+      // given: a delivered entry is authoritative even inside a partial collection
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(client, [dmChannel('c1', '200')], [{ channelId: 'c1', lastMessageId: '100', mentionCount: 2 }], true)
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.count).toBe(1)
+      expect(result.channels[0].unreadCount).toBe(2)
+      expect(result.complete).toBe(false)
+    })
+
+    it('skips channels that never had a message', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(client, [dmChannel('c1')], [])
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.count).toBe(0)
+    })
+
+    it('keeps a muted but unread channel with a zero count', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(client, [dmChannel('c1', '200')], [{ channelId: 'c1', lastMessageId: '100', mentionCount: 0 }])
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.count).toBe(1)
+      expect(result.channels[0].unreadCount).toBe(0)
+    })
+
+    it('treats a null read marker as never acknowledged', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(client, [dmChannel('c1', '200')], [{ channelId: 'c1', lastMessageId: null, mentionCount: 4 }])
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.count).toBe(1)
+      expect(result.channels[0].unreadCount).toBe(4)
+    })
+
+    it('includes group DMs and orders channels newest first', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(client, [dmChannel('c1', '200'), dmChannel('c2', '900', 3)], [])
+
+      const result = await client.getUnreadDMs()
+
+      expect(result.channels.map((channel) => channel.id)).toEqual(['c2', 'c1'])
+      expect(result.channels[0].type).toBe(3)
+    })
+
+    it('caps returned channels by limit while keeping totals unfiltered', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stub(
+        client,
+        [dmChannel('c1', '200'), dmChannel('c2', '900')],
+        [
+          { channelId: 'c1', lastMessageId: '100', mentionCount: 2 },
+          { channelId: 'c2', lastMessageId: '100', mentionCount: 5 },
+        ],
+      )
+
+      const result = await client.getUnreadDMs({ limit: 1 })
+
+      expect(result.channels).toHaveLength(1)
+      expect(result.count).toBe(2)
+      expect(result.totalUnread).toBe(7)
+    })
+  })
 })

package/src/platforms/discord/client.ts

@@ -11,9 +11,13 @@ import type {
   DiscordMention,
   DiscordMessage,
   DiscordReadState,
+  DiscordReadStateSnapshot,
   DiscordRelationship,
+  DiscordRole,
   DiscordSearchOptions,
   DiscordSearchResult,
+  DiscordUnreadDM,
+  DiscordUnreadDMsResult,
   DiscordUnreadMention,
   DiscordUnreadMentionsResult,
   DiscordUser,
@@ -33,6 +37,47 @@ function isSnowflakeNewer(candidate: string, marker: string): boolean {
   }
 }
 
+interface ReadStateCandidateChannel {
+  id: string
+  last_message_id?: string | null
+}
+
+export interface UnreadChannel<T> {
+  channel: T
+  lastMessageId: string
+  unreadCount: number | null
+}
+
+export function selectUnreadChannels<T extends ReadStateCandidateChannel>(
+  channels: T[],
+  readState: DiscordReadStateSnapshot,
+): UnreadChannel<T>[] {
+  const readStateByChannel = new Map(readState.states.map((state) => [state.channelId, state]))
+
+  const unread: UnreadChannel<T>[] = []
+  for (const channel of channels) {
+    const lastMessageId = channel.last_message_id
+    if (!lastMessageId) continue
+
+    const state = readStateByChannel.get(channel.id)
+    // An absent entry only carries meaning when the collection is complete. In a
+    // complete payload Discord omits read states for channels it never tracked, so a
+    // channel holding messages with no marker is far more likely never-opened than
+    // read: surface it with an unknown count rather than silently hiding it. In a
+    // partial payload the entry may simply have been left out, so reporting it would
+    // be a false positive on an already-read channel.
+    if (!state) {
+      if (!readState.partial) unread.push({ channel, lastMessageId, unreadCount: null })
+      continue
+    }
+
+    if (state.lastMessageId !== null && !isSnowflakeNewer(lastMessageId, state.lastMessageId)) continue
+    unread.push({ channel, lastMessageId, unreadCount: state.mentionCount })
+  }
+
+  return unread.sort((a, b) => (isSnowflakeNewer(a.lastMessageId, b.lastMessageId) ? -1 : 1))
+}
+
 export class DiscordError extends Error {
   code: string
 
@@ -349,6 +394,31 @@ export class DiscordClient {
     })
   }
 
+  async getUnreadDMs(options?: { limit?: number }): Promise<DiscordUnreadDMsResult> {
+    const [readState, channels] = await Promise.all([this.fetchReadStateSnapshot(), this.listDMChannels()])
+
+    const unread = selectUnreadChannels(channels, readState).map(
+      ({ channel, lastMessageId, unreadCount }): DiscordUnreadDM => ({
+        id: channel.id,
+        type: channel.type,
+        name: channel.name ?? null,
+        recipients: channel.recipients,
+        lastMessageId,
+        unreadCount,
+      }),
+    )
+
+    const totalUnread = unread.reduce((sum, channel) => sum + (channel.unreadCount ?? 0), 0)
+    const limited = options?.limit === undefined ? unread : unread.slice(0, options.limit)
+
+    return {
+      channels: limited,
+      count: unread.length,
+      totalUnread,
+      complete: !readState.partial,
+    }
+  }
+
   async getMentions(options?: { limit?: number; guildId?: string; before?: string }): Promise<DiscordMention[]> {
     const params = new URLSearchParams()
     params.set('limit', (options?.limit ?? 25).toString())
@@ -366,15 +436,19 @@ export class DiscordClient {
   }
 
   async fetchReadState(): Promise<DiscordReadState[]> {
+    return (await this.fetchReadStateSnapshot()).states
+  }
+
+  async fetchReadStateSnapshot(): Promise<DiscordReadStateSnapshot> {
     const { DiscordListener } = await import('./listener')
     const listener = new DiscordListener(this)
     try {
       await listener.start()
-      const readState = listener.getReadState()
-      if (readState === null) {
+      const snapshot = listener.getReadStateSnapshot()
+      if (snapshot === null) {
         throw new DiscordError('Discord gateway did not deliver read state', 'no_read_state')
       }
-      return readState
+      return snapshot
     } finally {
       listener.stop()
     }
@@ -481,6 +555,14 @@ export class DiscordClient {
     return this.request<DiscordGuildMember[]>('GET', `/guilds/${guildId}/members/search?${params.toString()}`)
   }
 
+  async getMyGuildMember(guildId: string): Promise<DiscordGuildMember> {
+    return this.request<DiscordGuildMember>('GET', `/users/@me/guilds/${guildId}/member`)
+  }
+
+  async listRoles(guildId: string): Promise<DiscordRole[]> {
+    return this.request<DiscordRole[]>('GET', `/guilds/${guildId}/roles`)
+  }
+
   async searchMessages(
     guildId: string,
     query: string,

package/src/platforms/discord/commands/dm.test.ts

@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from 'bun:te
 import { DiscordClient } from '../client'
 import { DiscordCredentialManager } from '../credential-manager'
 import type { DiscordDMChannel } from '../types'
-import { createAction, listAction } from './dm'
+import { createAction, listAction, unreadAction } from './dm'
 
 class ProcessExit extends Error {
   constructor(readonly code?: string | number | null) {
@@ -13,6 +13,7 @@ class ProcessExit extends Error {
 
 let clientListDMChannelsSpy: ReturnType<typeof spyOn>
 let clientCreateDMSpy: ReturnType<typeof spyOn>
+let clientGetUnreadDMsSpy: ReturnType<typeof spyOn>
 let credManagerLoadSpy: ReturnType<typeof spyOn>
 
 const mockChannels: DiscordDMChannel[] = [
@@ -57,6 +58,30 @@ beforeEach(() => {
     ],
   })
 
+  clientGetUnreadDMsSpy = spyOn(DiscordClient.prototype, 'getUnreadDMs').mockResolvedValue({
+    channels: [
+      {
+        id: '123',
+        type: 1,
+        name: null,
+        recipients: [{ id: '456', username: 'testuser' }],
+        lastMessageId: '900',
+        unreadCount: 3,
+      },
+      {
+        id: '789',
+        type: 3,
+        name: 'Group Chat',
+        recipients: [{ id: '111', username: 'user1' }],
+        lastMessageId: '800',
+        unreadCount: null,
+      },
+    ],
+    count: 2,
+    totalUnread: 3,
+    complete: true,
+  })
+
   credManagerLoadSpy = spyOn(DiscordCredentialManager.prototype, 'load').mockResolvedValue({
     token: 'test-token',
     current_server: null,
@@ -67,6 +92,7 @@ beforeEach(() => {
 afterEach(() => {
   clientListDMChannelsSpy?.mockRestore()
   clientCreateDMSpy?.mockRestore()
+  clientGetUnreadDMsSpy?.mockRestore()
   credManagerLoadSpy?.mockRestore()
 })
 
@@ -150,4 +176,103 @@ describe('dm commands', () => {
       }
     })
   })
+
+  describe('unreadAction', () => {
+    it('reports unread channels with labelled types and totals', async () => {
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await unreadAction({ pretty: false })
+      } finally {
+        console.log = originalLog
+      }
+
+      const payload = JSON.parse(consoleSpy.mock.calls[0][0] as unknown as string)
+      expect(payload.count).toBe(2)
+      expect(payload.total_unread).toBe(3)
+      expect(payload.complete).toBe(true)
+      expect(payload.channels[0]).toEqual({
+        id: '123',
+        type: 'DM',
+        name: null,
+        recipients: [{ id: '456', username: 'testuser' }],
+        last_message_id: '900',
+        unread_count: 3,
+      })
+      expect(payload.channels[1].type).toBe('Group DM')
+    })
+
+    it('preserves an unknown unread count as null', async () => {
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await unreadAction({ pretty: false })
+      } finally {
+        console.log = originalLog
+      }
+
+      const payload = JSON.parse(consoleSpy.mock.calls[0][0] as unknown as string)
+      expect(payload.channels[1].unread_count).toBeNull()
+    })
+
+    it('surfaces an incomplete read state as complete false', async () => {
+      clientGetUnreadDMsSpy.mockResolvedValue({ channels: [], count: 0, totalUnread: 0, complete: false })
+
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await unreadAction({ pretty: false })
+      } finally {
+        console.log = originalLog
+      }
+
+      const payload = JSON.parse(consoleSpy.mock.calls[0][0] as unknown as string)
+      expect(payload.complete).toBe(false)
+    })
+
+    it('forwards the limit to the client', async () => {
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await unreadAction({ limit: 5, pretty: false })
+      } finally {
+        console.log = originalLog
+      }
+
+      expect(clientGetUnreadDMsSpy).toHaveBeenCalledWith({ limit: 5 })
+    })
+
+    it('handles authentication error', async () => {
+      credManagerLoadSpy.mockResolvedValue({
+        token: '',
+        current_server: null,
+        servers: {},
+      })
+
+      const exitSpy = spyOn(process, 'exit').mockImplementation((code?: string | number | null) => {
+        throw new ProcessExit(code)
+      })
+
+      const consoleSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = consoleSpy
+
+      try {
+        await expect(unreadAction({ pretty: false })).rejects.toThrow(ProcessExit)
+        expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Not authenticated'))
+        expect(exitSpy).toHaveBeenCalledWith(1)
+      } finally {
+        console.log = originalLog
+        exitSpy.mockRestore()
+      }
+    })
+  })
 })

package/src/platforms/discord/commands/dm.ts

@@ -1,4 +1,4 @@
-import { Command } from 'commander'
+import { Command, InvalidArgumentError } from 'commander'
 
 import { handleError } from '@/shared/utils/error-handler'
 import { formatOutput } from '@/shared/utils/output'
@@ -7,6 +7,18 @@ import { DiscordClient } from '../client'
 import { DiscordCredentialManager } from '../credential-manager'
 import type { DiscordDMChannel } from '../types'
 
+function parseLimit(value: string): number {
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new InvalidArgumentError('Must be a positive integer.')
+  }
+  return parsed
+}
+
+function channelTypeLabel(type: number): string {
+  return type === 1 ? 'DM' : 'Group DM'
+}
+
 export async function listAction(options: { pretty?: boolean }): Promise<void> {
   try {
     const credManager = new DiscordCredentialManager()
@@ -22,7 +34,7 @@ export async function listAction(options: { pretty?: boolean }): Promise<void> {
 
     const output = channels.map((channel: DiscordDMChannel) => ({
       id: channel.id,
-      type: channel.type === 1 ? 'DM' : 'Group DM',
+      type: channelTypeLabel(channel.type),
       name: channel.name || null,
       recipients: channel.recipients.map((user) => ({
         id: user.id,
@@ -52,7 +64,7 @@ export async function createAction(userId: string, options: { pretty?: boolean }
 
     const output = {
       id: channel.id,
-      type: channel.type === 1 ? 'DM' : 'Group DM',
+      type: channelTypeLabel(channel.type),
       name: channel.name || null,
       recipients: channel.recipients.map((user) => ({
         id: user.id,
@@ -66,6 +78,42 @@ export async function createAction(userId: string, options: { pretty?: boolean }
   }
 }
 
+export async function unreadAction(options: { limit?: number; pretty?: boolean }): Promise<void> {
+  try {
+    const credManager = new DiscordCredentialManager()
+    const config = await credManager.load()
+
+    if (!config.token) {
+      console.log(formatOutput({ error: 'Not authenticated. Run "auth extract" first.' }, options.pretty))
+      process.exit(1)
+    }
+
+    const client = await new DiscordClient().login({ token: config.token })
+    const result = await client.getUnreadDMs({ limit: options.limit })
+
+    const output = {
+      channels: result.channels.map((channel) => ({
+        id: channel.id,
+        type: channelTypeLabel(channel.type),
+        name: channel.name,
+        recipients: channel.recipients.map((user) => ({
+          id: user.id,
+          username: user.username,
+        })),
+        last_message_id: channel.lastMessageId,
+        unread_count: channel.unreadCount,
+      })),
+      count: result.count,
+      total_unread: result.totalUnread,
+      complete: result.complete,
+    }
+
+    console.log(formatOutput(output, options.pretty))
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
 export const dmCommand = new Command('dm')
   .description('DM channel commands')
   .addCommand(
@@ -81,3 +129,15 @@ export const dmCommand = new Command('dm')
       .option('--pretty', 'Pretty print JSON output')
       .action(createAction),
   )
+  .addCommand(
+    new Command('unread')
+      .description('List unread DM and group-DM channels, newest first')
+      .option('--limit <n>', 'Max number of channels to return', parseLimit)
+      .option('--pretty', 'Pretty print JSON output')
+      .action((options) => {
+        unreadAction({
+          limit: options.limit,
+          pretty: options.pretty,
+        })
+      }),
+  )