agent-messenger 2.30.0 → 2.32.0

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

@@ -1,6 +1,7 @@
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, it, spyOn } from 'bun:test'
 
 import { DiscordClient, DiscordError } from './client'
+import type { DiscordReadState } from './types'
 
 describe('DiscordClient', () => {
   const originalFetch = globalThis.fetch
@@ -226,23 +227,50 @@ describe('DiscordClient', () => {
 
       expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/channels/ch1/messages?limit=50')
     })
+
+    it('gets messages around a specific message', async () => {
+      mockResponse([])
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      await client.getMessages('ch1', 1, { around: 'msg/1' })
+
+      expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/channels/ch1/messages?around=msg%2F1&limit=1')
+    })
   })
 
   describe('getMessage', () => {
     it('returns single message', async () => {
-      mockResponse({
-        id: 'msg1',
-        channel_id: 'ch1',
-        author: { id: '123', username: 'user1' },
-        content: 'Message 1',
-        timestamp: '2024-01-01T00:00:00.000Z',
-      })
+      mockResponse([
+        {
+          id: 'msg1',
+          channel_id: 'ch1',
+          author: { id: '123', username: 'user1' },
+          content: 'Message 1',
+          timestamp: '2024-01-01T00:00:00.000Z',
+        },
+      ])
 
       const client = await new DiscordClient().login({ token: 'test-token' })
       const message = await client.getMessage('ch1', 'msg1')
 
       expect(message.id).toBe('msg1')
-      expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/channels/ch1/messages/msg1')
+      expect(fetchCalls[0].url).toBe('https://discord.com/api/v10/channels/ch1/messages?around=msg1&limit=1')
+    })
+
+    it('throws when the requested message is not returned', async () => {
+      mockResponse([
+        {
+          id: 'neighbor',
+          channel_id: 'ch1',
+          author: { id: '123', username: 'user1' },
+          content: 'Nearby message',
+          timestamp: '2024-01-01T00:00:00.000Z',
+        },
+      ])
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+
+      await expect(client.getMessage('ch1', 'missing')).rejects.toEqual(new DiscordError('Message not found', '10008'))
     })
   })
 
@@ -447,6 +475,127 @@ describe('DiscordClient', () => {
     })
   })
 
+  describe('searchMessages', () => {
+    const searchResult = {
+      id: 'msg1',
+      channel_id: 'ch1',
+      guild_id: 'guild1',
+      author: { id: 'user1', username: 'user1' },
+      content: 'matching message',
+      timestamp: '2026-01-01T00:00:00.000Z',
+      hit: true,
+    }
+
+    it('flattens grouped search results and keeps hits', async () => {
+      mockResponse({
+        doing_deep_historical_index: false,
+        total_results: 1,
+        messages: [[searchResult, { ...searchResult, id: 'context', hit: false }]],
+      })
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      const result = await client.searchMessages('guild1', 'matching', { limit: 25 })
+
+      expect(result).toEqual({ results: [searchResult], total: 1 })
+      expect(fetchCalls[0].url).toBe(
+        'https://discord.com/api/v10/guilds/guild1/messages/search?content=matching&limit=25',
+      )
+    })
+
+    it('retries when the search index is not ready', async () => {
+      mockResponse(
+        {
+          message: 'Index not yet available. Try again later',
+          code: 110000,
+          documents_indexed: 0,
+          retry_after: 0,
+        },
+        202,
+      )
+      mockResponse({
+        doing_deep_historical_index: false,
+        total_results: 1,
+        messages: [[searchResult]],
+      })
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      const startTime = Date.now()
+      const result = await client.searchMessages('guild1', 'matching')
+      const elapsed = Date.now() - startTime
+
+      expect(result).toEqual({ results: [searchResult], total: 1 })
+      expect(elapsed).toBeGreaterThanOrEqual(50)
+      expect(fetchCalls).toHaveLength(2)
+    })
+
+    it('throws a clear error when the search index remains unavailable', async () => {
+      for (let attempt = 0; attempt < 4; attempt++) {
+        mockResponse(
+          {
+            message: 'Index not yet available. Try again later',
+            code: 110000,
+            documents_indexed: 0,
+            retry_after: 0.001,
+          },
+          202,
+        )
+      }
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+
+      await expect(client.searchMessages('guild1', 'matching')).rejects.toThrow(
+        'Search index is not ready after retries',
+      )
+      expect(fetchCalls).toHaveLength(4)
+    })
+
+    it('rejects unexpected successful response payloads', async () => {
+      mockResponse(
+        {
+          message: 'Unexpected response',
+          code: 999999,
+          retry_after: 0,
+        },
+        202,
+      )
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+
+      try {
+        await client.searchMessages('guild1', 'matching')
+        throw new Error('Expected searchMessages to throw')
+      } catch (error) {
+        expect(error).toBeInstanceOf(DiscordError)
+        if (!(error instanceof DiscordError)) throw error
+        expect(error.code).toBe('invalid_search_response')
+      }
+      expect(fetchCalls).toHaveLength(1)
+    })
+
+    it('rejects malformed message and retry payloads', async () => {
+      mockResponse({ total_results: 1, messages: null })
+      mockResponse(
+        {
+          message: 'Index not yet available. Try again later',
+          code: 110000,
+          documents_indexed: 0,
+          retry_after: -1,
+        },
+        202,
+      )
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+
+      await expect(client.searchMessages('guild1', 'matching')).rejects.toThrow(
+        'Discord returned an invalid search response',
+      )
+      await expect(client.searchMessages('guild1', 'matching')).rejects.toThrow(
+        'Discord returned an invalid search response',
+      )
+      expect(fetchCalls).toHaveLength(2)
+    })
+  })
+
   describe('rate limiting', () => {
     it('waits when bucket is exhausted before making request', async () => {
       mockResponse({ id: '1', username: 'user1' }, 200, {
@@ -553,5 +702,198 @@ describe('DiscordClient', () => {
 
       expect(fetchCalls.length).toBe(2)
     })
+
+    it('normalizes query strings for the same channel route', async () => {
+      mockResponse([], 200, {
+        'X-RateLimit-Remaining': '0',
+        'X-RateLimit-Reset': String(Date.now() / 1000 + 0.1),
+        'X-RateLimit-Bucket': 'messages-bucket',
+      })
+      mockResponse([])
+
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      await client.getMessages('123456789', 1, { around: 'message-1' })
+
+      const startTime = Date.now()
+      await client.getMessages('123456789', 1, { around: 'message-2' })
+      const elapsed = Date.now() - startTime
+
+      expect(elapsed).toBeGreaterThanOrEqual(50)
+      expect(fetchCalls.length).toBe(2)
+    })
+  })
+
+  describe('getUnreadMentions', () => {
+    const mention = (id: string, channelId: string, guildId?: string) => ({
+      id,
+      channel_id: channelId,
+      author: { id: 'a1', username: 'alice' },
+      content: `mention ${id}`,
+      timestamp: '2024-01-29T10:00:00Z',
+      mention_everyone: false,
+      mentions: [{ id: 'me', username: 'me' }],
+      ...(guildId ? { guild_id: guildId } : {}),
+    })
+
+    const stubReadState = (client: DiscordClient, readState: DiscordReadState[]) =>
+      spyOn(client, 'fetchReadState').mockResolvedValue(readState)
+
+    it('keeps mentions newer than the channel read marker', async () => {
+      // given: one channel with an unread mention (200 > marker 100) and one already read (50 < 100)
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
+      mockResponse([mention('200', 'c1'), mention('50', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      // then: only the newer message is unread
+      expect(result.count).toBe(1)
+      expect(result.mentions[0].id).toBe('200')
+      expect(result.mentions[0].mention_count).toBe(1)
+    })
+
+    it('treats an equal snowflake as read', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
+      mockResponse([mention('100', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.count).toBe(0)
+    })
+
+    it('omits mentions for channels with no read-state entry', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [])
+      mockResponse([mention('200', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.count).toBe(0)
+    })
+
+    it('omits channels whose mention_count is zero', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '100', mentionCount: 0 }])
+      mockResponse([mention('200', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.count).toBe(0)
+    })
+
+    it('includes all mentions when the read marker is null', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: null, mentionCount: 2 }])
+      mockResponse([mention('200', 'c1'), mention('50', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.count).toBe(2)
+    })
+
+    it('reports badgeCount from summed read-state mention counts', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [
+        { channelId: 'c1', lastMessageId: '100', mentionCount: 2 },
+        { channelId: 'c2', lastMessageId: '100', mentionCount: 3 },
+      ])
+      mockResponse([mention('200', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.badgeCount).toBe(5)
+      expect(result.count).toBe(1)
+    })
+
+    it('paginates mention history with a before cursor', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 200 }])
+
+      const firstPage = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      const secondPage = [mention('900', 'c1')]
+      mockResponse(firstPage)
+      mockResponse(secondPage)
+
+      const result = await client.getUnreadMentions()
+
+      expect(fetchCalls.length).toBe(2)
+      expect(fetchCalls[1].url).toContain('before=901')
+      expect(result.count).toBe(101)
+    })
+
+    it('deduplicates mentions repeated across pages', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 100 }])
+
+      const page = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      const overlap = [mention('901', 'c1'), mention('800', 'c1')]
+      mockResponse(page)
+      mockResponse(overlap)
+
+      const result = await client.getUnreadMentions()
+
+      const ids = result.mentions.map((m) => m.id)
+      expect(new Set(ids).size).toBe(ids.length)
+    })
+
+    it('caps the scan at limit 1 with a single bounded request', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 5 }])
+      mockResponse([mention('1000', 'c1')])
+
+      const result = await client.getUnreadMentions({ limit: 1 })
+
+      // then: exactly one page requested, capped to the limit, incomplete scan
+      expect(fetchCalls.length).toBe(1)
+      expect(fetchCalls[0].url).toContain('limit=1')
+      expect(result.count).toBe(1)
+      expect(result.complete).toBe(false)
+    })
+
+    it('caps the scan at a custom limit that spans multiple pages', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 200 }])
+
+      const firstPage = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      const secondPage = Array.from({ length: 50 }, (_, i) => mention(String(900 - i), 'c1'))
+      mockResponse(firstPage)
+      mockResponse(secondPage)
+
+      const result = await client.getUnreadMentions({ limit: 150 })
+
+      // then: second page bounded to remaining 50, scan stops at the cap and is incomplete
+      expect(fetchCalls.length).toBe(2)
+      expect(fetchCalls[1].url).toContain('limit=50')
+      expect(result.count).toBe(150)
+      expect(result.complete).toBe(false)
+    })
+
+    it('marks the scan complete when a short page ends history', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 3 }])
+      mockResponse([mention('1000', 'c1'), mention('999', 'c1')])
+
+      const result = await client.getUnreadMentions()
+
+      expect(result.complete).toBe(true)
+      expect(result.count).toBe(2)
+    })
+
+    it('stops and reports incomplete when the cursor fails to advance', async () => {
+      const client = await new DiscordClient().login({ token: 'test-token' })
+      stubReadState(client, [{ channelId: 'c1', lastMessageId: '0', mentionCount: 200 }])
+
+      const fullPage = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      const repeatedPage = Array.from({ length: 100 }, (_, i) => mention(String(1000 - i), 'c1'))
+      mockResponse(fullPage)
+      mockResponse(repeatedPage)
+
+      const result = await client.getUnreadMentions()
+
+      // then: the repeated page adds nothing new, so the guard stops the scan as incomplete
+      expect(result.complete).toBe(false)
+      expect(result.count).toBe(100)
+    })
   })
 })

package/src/platforms/discord/client.ts

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises'
 
 import { getDiscordHeaders } from './super-properties'
+import { DiscordSearchIndexNotReadyResponseSchema, DiscordSearchResponseSchema } from './types'
 import type {
   DiscordChannel,
   DiscordDMChannel,
@@ -9,15 +10,29 @@ import type {
   DiscordGuildMember,
   DiscordMention,
   DiscordMessage,
+  DiscordReadState,
   DiscordRelationship,
   DiscordSearchOptions,
-  DiscordSearchResponse,
   DiscordSearchResult,
+  DiscordUnreadMention,
+  DiscordUnreadMentionsResult,
   DiscordUser,
   DiscordUserNote,
   DiscordUserProfile,
 } from './types'
 
+const MENTIONS_WINDOW_DAYS = 7
+const MENTIONS_PAGE_SIZE = 100
+const UNREAD_MENTIONS_MAX = 500
+
+function isSnowflakeNewer(candidate: string, marker: string): boolean {
+  try {
+    return BigInt(candidate) > BigInt(marker)
+  } catch {
+    return false
+  }
+}
+
 export class DiscordError extends Error {
   code: string
 
@@ -37,6 +52,7 @@ interface RateLimitBucket {
 const BASE_URL = 'https://discord.com/api/v10'
 const MAX_RETRIES = 3
 const BASE_BACKOFF_MS = 100
+const MAX_SEARCH_INDEX_RETRY_MS = 30_000
 
 export class DiscordClient {
   private token: string | null = null
@@ -74,7 +90,9 @@ export class DiscordClient {
   }
 
   private getBucketKey(method: string, path: string): string {
-    const normalized = path
+    const queryIndex = path.indexOf('?')
+    const route = queryIndex === -1 ? path : path.slice(0, queryIndex)
+    const normalized = route
       .replace(/\/channels\/\d+/, '/channels/{channel_id}')
       .replace(/\/guilds\/\d+/, '/guilds/{guild_id}')
       .replace(/\/users\/\d+/, '/users/{user_id}')
@@ -234,12 +252,22 @@ export class DiscordClient {
     return this.request<DiscordMessage>('POST', `/channels/${channelId}/messages`, body)
   }
 
-  async getMessages(channelId: string, limit: number = 50): Promise<DiscordMessage[]> {
-    return this.request<DiscordMessage[]>('GET', `/channels/${channelId}/messages?limit=${limit}`)
+  async getMessages(channelId: string, limit: number = 50, options?: { around?: string }): Promise<DiscordMessage[]> {
+    const params = new URLSearchParams()
+    if (options?.around) {
+      params.set('around', options.around)
+    }
+    params.set('limit', limit.toString())
+    return this.request<DiscordMessage[]>('GET', `/channels/${channelId}/messages?${params}`)
   }
 
   async getMessage(channelId: string, messageId: string): Promise<DiscordMessage> {
-    return this.request<DiscordMessage>('GET', `/channels/${channelId}/messages/${messageId}`)
+    const messages = await this.getMessages(channelId, 1, { around: messageId })
+    const message = messages[0]
+    if (!message || message.id !== messageId) {
+      throw new DiscordError('Message not found', '10008')
+    }
+    return message
   }
 
   async editMessage(channelId: string, messageId: string, content: string): Promise<DiscordMessage> {
@@ -321,7 +349,7 @@ export class DiscordClient {
     })
   }
 
-  async getMentions(options?: { limit?: number; guildId?: string }): Promise<DiscordMention[]> {
+  async getMentions(options?: { limit?: number; guildId?: string; before?: string }): Promise<DiscordMention[]> {
     const params = new URLSearchParams()
     params.set('limit', (options?.limit ?? 25).toString())
     params.set('roles', 'true')
@@ -330,10 +358,100 @@ export class DiscordClient {
     if (options?.guildId) {
       params.set('guild_id', options.guildId)
     }
+    if (options?.before) {
+      params.set('before', options.before)
+    }
 
     return this.request<DiscordMention[]>('GET', `/users/@me/mentions?${params.toString()}`)
   }
 
+  async fetchReadState(): Promise<DiscordReadState[]> {
+    const { DiscordListener } = await import('./listener')
+    const listener = new DiscordListener(this)
+    try {
+      await listener.start()
+      const readState = listener.getReadState()
+      if (readState === null) {
+        throw new DiscordError('Discord gateway did not deliver read state', 'no_read_state')
+      }
+      return readState
+    } finally {
+      listener.stop()
+    }
+  }
+
+  async getUnreadMentions(options?: { guildId?: string; limit?: number }): Promise<DiscordUnreadMentionsResult> {
+    const limit = options?.limit ?? UNREAD_MENTIONS_MAX
+    const [readState, scan] = await Promise.all([
+      this.fetchReadState(),
+      this.collectMentions({ guildId: options?.guildId, limit }),
+    ])
+
+    const readStateByChannel = new Map(readState.map((state) => [state.channelId, state]))
+
+    const unread: DiscordUnreadMention[] = []
+    for (const mention of scan.mentions) {
+      const state = readStateByChannel.get(mention.channel_id)
+      // A channel with no read-state entry is unknown, not unread: omit rather than assume unread.
+      if (!state || state.mentionCount === 0) continue
+      if (state.lastMessageId !== null && !isSnowflakeNewer(mention.id, state.lastMessageId)) continue
+      unread.push({ ...mention, mention_count: state.mentionCount })
+    }
+
+    // READY read states carry no guild association, so badgeCount is always the
+    // account-wide unread-mention total even when mentions are guild-filtered.
+    const badgeCount = readState.reduce((sum, state) => sum + state.mentionCount, 0)
+
+    return {
+      mentions: unread,
+      count: unread.length,
+      badgeCount,
+      complete: scan.complete,
+      windowDays: MENTIONS_WINDOW_DAYS,
+    }
+  }
+
+  private async collectMentions(options: {
+    guildId?: string
+    limit: number
+  }): Promise<{ mentions: DiscordMention[]; complete: boolean }> {
+    const collected: DiscordMention[] = []
+    const seen = new Set<string>()
+    let before: string | undefined
+
+    while (collected.length < options.limit) {
+      const pageSize = Math.min(MENTIONS_PAGE_SIZE, options.limit - collected.length)
+      const page = await this.getMentions({ limit: pageSize, guildId: options.guildId, before })
+
+      // An empty or short page is the natural end of history: the scan is exhaustive.
+      if (page.length < pageSize) {
+        for (const mention of page) {
+          if (seen.has(mention.id)) continue
+          seen.add(mention.id)
+          collected.push(mention)
+        }
+        return { mentions: collected, complete: true }
+      }
+
+      let added = 0
+      for (const mention of page) {
+        if (collected.length >= options.limit) break
+        if (seen.has(mention.id)) continue
+        seen.add(mention.id)
+        collected.push(mention)
+        added++
+      }
+
+      // Discord returns pages newest-first; a non-advancing cursor means a repeated
+      // page, so stop to avoid looping. Either way the scan did not reach history's end.
+      const oldest = page[page.length - 1].id
+      if (added === 0 || oldest === before) return { mentions: collected, complete: false }
+      before = oldest
+    }
+
+    return { mentions: collected, complete: false }
+  }
+
   async getUserNote(userId: string): Promise<DiscordUserNote | null> {
     try {
       return await this.request<DiscordUserNote>('GET', `/users/@me/notes/${userId}`)
@@ -393,28 +511,50 @@ export class DiscordClient {
       params.set('offset', options.offset.toString())
     }
 
-    const response = await this.request<DiscordSearchResponse>(
-      'GET',
-      `/guilds/${guildId}/messages/search?${params.toString()}`,
-    )
-
-    const results = response.messages
-      .flat()
-      .filter((msg) => msg.hit)
-      .map((msg) => ({
-        id: msg.id,
-        channel_id: msg.channel_id,
-        guild_id: msg.guild_id,
-        content: msg.content,
-        author: msg.author,
-        timestamp: msg.timestamp,
-        hit: msg.hit,
-      }))
+    const path = `/guilds/${guildId}/messages/search?${params.toString()}`
 
-    return {
-      results,
-      total: response.total_results,
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      const response: unknown = await this.request('GET', path)
+      const searchResponse = DiscordSearchResponseSchema.safeParse(response)
+
+      if (searchResponse.success) {
+        const results = searchResponse.data.messages
+          .flat()
+          .filter((msg) => msg.hit)
+          .map((msg) => ({
+            id: msg.id,
+            channel_id: msg.channel_id,
+            guild_id: msg.guild_id,
+            content: msg.content,
+            author: msg.author,
+            timestamp: msg.timestamp,
+            hit: msg.hit,
+          }))
+
+        return {
+          results,
+          total: searchResponse.data.total_results,
+        }
+      }
+
+      const indexNotReadyResponse = DiscordSearchIndexNotReadyResponseSchema.safeParse(response)
+      if (!indexNotReadyResponse.success) {
+        throw new DiscordError('Discord returned an invalid search response', 'invalid_search_response')
+      }
+
+      if (attempt === MAX_RETRIES) {
+        throw new DiscordError('Search index is not ready after retries', 'search_index_not_ready')
+      }
+
+      const requestedDelayMs = indexNotReadyResponse.data.retry_after * 1000
+      const retryDelayMs = Math.min(
+        requestedDelayMs === 0 ? BASE_BACKOFF_MS : requestedDelayMs,
+        MAX_SEARCH_INDEX_RETRY_MS,
+      )
+      await this.sleep(retryDelayMs)
     }
+
+    throw new DiscordError('Search failed after retries', 'max_retries')
   }
 
   async getUserProfile(userId: string): Promise<DiscordUserProfile> {