agent-messenger 2.30.0 → 2.32.0

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

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, expect, spyOn, it } from 'bun:test'
 
 import { DiscordClient } from '../client'
 import { DiscordCredentialManager } from '../credential-manager'
+import { unreadAction } from './mention'
 
 let clientGetMentionsSpy: ReturnType<typeof spyOn>
 let credManagerLoadSpy: ReturnType<typeof spyOn>
@@ -128,3 +129,86 @@ it('getMentions: includes mention metadata', async () => {
   expect(mention.mention_everyone).toBeDefined()
   expect(mention.mentions).toBeDefined()
 })
+
+it('unread command: emits snake_case JSON and forwards guild/limit options', async () => {
+  // given: an authenticated client whose getUnreadMentions returns one unread mention
+  credManagerLoadSpy.mockResolvedValue({
+    token: 'test-token',
+    current_server: null,
+    servers: {},
+  })
+  const loginSpy = spyOn(DiscordClient.prototype, 'login').mockImplementation(async function (this: DiscordClient) {
+    return this
+  })
+  const getUnreadSpy = spyOn(DiscordClient.prototype, 'getUnreadMentions').mockResolvedValue({
+    mentions: [
+      {
+        id: 'msg-1',
+        channel_id: 'ch-1',
+        author: { id: 'user-1', username: 'alice' },
+        content: 'Hey @testuser',
+        timestamp: '2024-01-29T10:00:00Z',
+        mention_everyone: false,
+        mentions: [{ id: 'user-me', username: 'testuser' }],
+        guild_id: 'guild-1',
+        mention_count: 2,
+      },
+    ],
+    count: 1,
+    badgeCount: 2,
+    complete: true,
+    windowDays: 7,
+  })
+  const consoleLogSpy = spyOn(console, 'log').mockImplementation(() => {})
+
+  // when: running the unread action with guild and limit
+  await unreadAction({ guild: 'guild-1', limit: 200 })
+
+  // then: options are forwarded and the emitted JSON uses documented snake_case keys
+  expect(getUnreadSpy).toHaveBeenCalledWith({ guildId: 'guild-1', limit: 200 })
+  const lastCall = consoleLogSpy.mock.calls.at(-1) as [string]
+  const emitted = JSON.parse(lastCall[0])
+  expect(emitted).toEqual({
+    mentions: [
+      {
+        id: 'msg-1',
+        channel_id: 'ch-1',
+        author: 'alice',
+        content: 'Hey @testuser',
+        timestamp: '2024-01-29T10:00:00Z',
+        mention_everyone: false,
+        mentioned_users: ['testuser'],
+        guild_id: 'guild-1',
+      },
+    ],
+    count: 1,
+    badge_count: 2,
+    complete: true,
+    window_days: 7,
+  })
+
+  loginSpy.mockRestore()
+  getUnreadSpy.mockRestore()
+  consoleLogSpy.mockRestore()
+})
+
+it('unread command: exits with error when not authenticated', async () => {
+  // given: no token in credentials
+  credManagerLoadSpy.mockResolvedValue({
+    token: undefined,
+    current_server: null,
+    servers: {},
+  })
+  const consoleLogSpy = spyOn(console, 'log').mockImplementation(() => {})
+  const processExitSpy = spyOn(process, 'exit').mockImplementation((_code?: number) => undefined as never)
+
+  // when: running the unread action
+  await unreadAction({})
+
+  // then: it reports the auth error and exits
+  expect(consoleLogSpy).toHaveBeenCalledWith(JSON.stringify({ error: 'Not authenticated. Run "auth extract" first.' }))
+  expect(processExitSpy).toHaveBeenCalledWith(1)
+
+  consoleLogSpy.mockRestore()
+  processExitSpy.mockRestore()
+})

package/src/platforms/discord/commands/mention.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'
@@ -6,6 +6,14 @@ import { formatOutput } from '@/shared/utils/output'
 import { DiscordClient } from '../client'
 import { DiscordCredentialManager } from '../credential-manager'
 
+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
+}
+
 export async function listAction(options: { limit?: number; guild?: string; pretty?: boolean }): Promise<void> {
   try {
     const credManager = new DiscordCredentialManager()
@@ -39,17 +47,72 @@ export async function listAction(options: { limit?: number; guild?: string; pret
   }
 }
 
-export const mentionCommand = new Command('mention').description('Mention commands').addCommand(
-  new Command('list')
-    .description('List mentions')
-    .option('--limit <n>', 'Number of mentions to fetch', '25')
-    .option('--guild <guild-id>', 'Filter by guild ID')
-    .option('--pretty', 'Pretty print JSON output')
-    .action((options) => {
-      listAction({
-        limit: options.limit ? parseInt(options.limit, 10) : undefined,
-        guild: options.guild,
-        pretty: options.pretty,
-      })
-    }),
-)
+export async function unreadAction(options: { guild?: string; 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.getUnreadMentions({
+      guildId: options.guild,
+      limit: options.limit,
+    })
+
+    const output = {
+      mentions: result.mentions.map((mention) => ({
+        id: mention.id,
+        channel_id: mention.channel_id,
+        author: mention.author.username,
+        content: mention.content,
+        timestamp: mention.timestamp,
+        mention_everyone: mention.mention_everyone,
+        mentioned_users: mention.mentions.map((u) => u.username),
+        guild_id: mention.guild_id || null,
+      })),
+      count: result.count,
+      badge_count: result.badgeCount,
+      complete: result.complete,
+      window_days: result.windowDays,
+    }
+
+    console.log(formatOutput(output, options.pretty))
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+export const mentionCommand = new Command('mention')
+  .description('Mention commands')
+  .addCommand(
+    new Command('list')
+      .description('List mentions')
+      .option('--limit <n>', 'Number of mentions to fetch', parseLimit, 25)
+      .option('--guild <guild-id>', 'Filter by guild ID')
+      .option('--pretty', 'Pretty print JSON output')
+      .action((options) => {
+        listAction({
+          limit: options.limit,
+          guild: options.guild,
+          pretty: options.pretty,
+        })
+      }),
+  )
+  .addCommand(
+    new Command('unread')
+      .description('List unread mentions (correlates mention history with per-channel read state)')
+      .option('--limit <n>', 'Max number of mentions to scan', parseLimit)
+      .option('--guild <guild-id>', 'Filter by guild ID')
+      .option('--pretty', 'Pretty print JSON output')
+      .action((options) => {
+        unreadAction({
+          limit: options.limit,
+          guild: options.guild,
+          pretty: options.pretty,
+        })
+      }),
+  )

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

@@ -37,7 +37,7 @@ beforeEach(() => {
         count: 1,
       },
     ],
-  } as any)
+  })
 
   // Spy on DiscordCredentialManager.prototype methods
   credManagerLoadSpy = spyOn(DiscordCredentialManager.prototype, 'load').mockResolvedValue({

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

@@ -101,7 +101,7 @@ export async function listAction(channelId: string, messageId: string, options:
       process.exit(1)
     }
 
-    const reactions = (message as any).reactions || []
+    const reactions = message.reactions ?? []
 
     console.log(
       formatOutput(

package/src/platforms/discord/index.ts

@@ -25,10 +25,13 @@ export type {
   DiscordMention,
   DiscordMessage,
   DiscordReaction,
+  DiscordReadState,
   DiscordRelationship,
   DiscordSearchOptions,
   DiscordSearchResponse,
   DiscordSearchResult,
+  DiscordUnreadMention,
+  DiscordUnreadMentionsResult,
   DiscordUser,
   DiscordUserNote,
   DiscordUserProfile,

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

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, mock, it } from 'bun:test'
 
-import { DiscordListener } from '@/platforms/discord/listener'
+import { DiscordListener, parseReadStates } from '@/platforms/discord/listener'
 import type {
   DiscordGatewayGenericEvent,
   DiscordGatewayMessageCreateEvent,
@@ -68,7 +68,7 @@ class MockWs {
     this.simulateMessage({ op: 10, d: { heartbeat_interval: interval } })
   }
 
-  simulateReady(sessionId = 'session_123') {
+  simulateReady(sessionId = 'session_123', readState?: unknown) {
     this.simulateMessage({
       op: 0,
       t: 'READY',
@@ -77,6 +77,7 @@ class MockWs {
         session_id: sessionId,
         resume_gateway_url: 'wss://resume.discord.gg',
         user: { id: 'U_SELF', username: 'testbot' },
+        ...(readState === undefined ? {} : { read_state: readState }),
       },
     })
   }
@@ -135,6 +136,33 @@ async function startConnecting(listener: DiscordListener): Promise<MockWs> {
   return ws
 }
 
+describe('parseReadStates', () => {
+  it('filters out non-channel read state types', () => {
+    const result = parseReadStates([
+      { id: 'c1', last_message_id: '100', mention_count: 1 },
+      { id: 'c2', read_state_type: 2, mention_count: 5 },
+    ])
+
+    expect(result).toEqual([{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
+  })
+
+  it('normalizes missing last_message_id and mention_count', () => {
+    const result = parseReadStates([{ id: 'c1' }])
+
+    expect(result).toEqual([{ channelId: 'c1', lastMessageId: null, mentionCount: 0 }])
+  })
+
+  it('skips malformed entries but keeps valid ones', () => {
+    const result = parseReadStates([{ id: 'c1', mention_count: 1 }, { mention_count: 3 }])
+
+    expect(result).toEqual([{ channelId: 'c1', lastMessageId: null, mentionCount: 1 }])
+  })
+
+  it('throws on a non-array, non-versioned payload', () => {
+    expect(() => parseReadStates({ foo: 'bar' })).toThrow(/invalid read_state/)
+  })
+})
+
 describe('DiscordListener', () => {
   let listener: DiscordListener
 
@@ -235,6 +263,45 @@ describe('DiscordListener', () => {
     })
   })
 
+  describe('read state', () => {
+    it('captures raw-array read_state from READY', async () => {
+      const client = createMockClient()
+      listener = new DiscordListener(client)
+
+      const started = listener.start()
+      const ws = await waitForSocket()
+      ws.simulateOpen()
+      ws.simulateHello()
+      ws.simulateReady('session_123', [{ id: 'c1', last_message_id: '100', mention_count: 2 }])
+      await started
+
+      expect(listener.getReadState()).toEqual([{ channelId: 'c1', lastMessageId: '100', mentionCount: 2 }])
+    })
+
+    it('captures versioned { entries } read_state from READY', async () => {
+      const client = createMockClient()
+      listener = new DiscordListener(client)
+
+      const started = listener.start()
+      const ws = await waitForSocket()
+      ws.simulateOpen()
+      ws.simulateHello()
+      ws.simulateReady('session_123', { version: 7, entries: [{ id: 'c1', last_message_id: '100', mention_count: 1 }] })
+      await started
+
+      expect(listener.getReadState()).toEqual([{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
+    })
+
+    it('defaults to an empty read state when READY omits read_state', async () => {
+      const client = createMockClient()
+      listener = new DiscordListener(client)
+
+      await startAndReady(listener)
+
+      expect(listener.getReadState()).toEqual([])
+    })
+  })
+
   describe('identify', () => {
     it('sends Identify after Hello', async () => {
       const client = createMockClient()

package/src/platforms/discord/listener.ts

@@ -3,8 +3,30 @@ import { EventEmitter } from 'events'
 import WebSocket from 'ws'
 
 import type { DiscordClient } from './client'
-import type { DiscordListenerEventMap, DiscordGatewayGenericEvent } from './types'
-import { DiscordGatewayOpcode } from './types'
+import type { DiscordListenerEventMap, DiscordGatewayGenericEvent, DiscordReadState } from './types'
+import { DiscordGatewayOpcode, DiscordRawReadStateSchema, DiscordReadyReadStateSchema } from './types'
+
+export function parseReadStates(value: unknown): DiscordReadState[] {
+  const parsed = DiscordReadyReadStateSchema.safeParse(value)
+  if (!parsed.success) {
+    throw new Error('Discord READY contained an invalid read_state payload')
+  }
+
+  const entries = Array.isArray(parsed.data) ? parsed.data : parsed.data.entries
+
+  const readStates: DiscordReadState[] = []
+  for (const entry of entries) {
+    const state = DiscordRawReadStateSchema.safeParse(entry)
+    if (!state.success) continue
+    if ((state.data.read_state_type ?? 0) !== 0) continue
+    readStates.push({
+      channelId: state.data.id,
+      lastMessageId: state.data.last_message_id ?? null,
+      mentionCount: state.data.mention_count ?? 0,
+    })
+  }
+  return readStates
+}
 
 const GATEWAY_URL = 'wss://gateway.discord.gg/?v=10&encoding=json'
 const GATEWAY_QUERY = '?v=10&encoding=json'
@@ -57,6 +79,7 @@ export class DiscordListener {
   private resumeGatewayUrl: string | null = null
   private token: string | null = null
   private cachedUser: { id: string; username: string } | null = null
+  private readState: DiscordReadState[] | null = null
   private generation = 0
   private startPromise: Promise<void> | null = null
   private pendingStartReject: ((error: Error) => void) | null = null
@@ -151,6 +174,7 @@ export class DiscordListener {
     this.resumeGatewayUrl = null
     this.token = null
     this.cachedUser = null
+    this.readState = null
     rejectStart?.(new Error('Discord gateway start was stopped before becoming ready'))
   }
 
@@ -174,6 +198,10 @@ export class DiscordListener {
     return this
   }
 
+  getReadState(): DiscordReadState[] | null {
+    return this.readState
+  }
+
   private isCurrent(generation: number, ws?: WebSocket): boolean {
     if (generation !== this.generation || !this.running) return false
     if (ws !== undefined && this.ws !== ws) return false
@@ -298,6 +326,7 @@ export class DiscordListener {
       this.sessionId = d.session_id
       this.resumeGatewayUrl = d.resume_gateway_url
       this.cachedUser = d.user
+      this.readState = d.read_state === undefined ? [] : parseReadStates(d.read_state)
       this.reconnectAttempts = 0
       this.emitter.emit('connected', { user: d.user, sessionId: d.session_id })
       return

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

@@ -150,6 +150,17 @@ it('DiscordReactionSchema validates reaction with custom emoji', () => {
   expect(result.success).toBe(true)
 })
 
+it('DiscordReactionSchema validates nullable emoji fields', () => {
+  const result = DiscordReactionSchema.safeParse({
+    emoji: {
+      id: null,
+      name: null,
+    },
+    count: 1,
+  })
+  expect(result.success).toBe(true)
+})
+
 it('DiscordReactionSchema rejects missing required fields', () => {
   const result = DiscordReactionSchema.safeParse({
     emoji: {

package/src/platforms/discord/types.ts

@@ -38,6 +38,7 @@ export interface DiscordMessage {
   timestamp: string
   edited_timestamp?: string
   thread_id?: string
+  reactions?: DiscordReaction[]
 }
 
 export interface DiscordUser {
@@ -58,8 +59,8 @@ export interface DiscordDMChannel {
 
 export interface DiscordReaction {
   emoji: {
-    id?: string
-    name: string
+    id?: string | null
+    name: string | null
   }
   count: number
 }
@@ -91,6 +92,26 @@ export interface DiscordUserNote {
   note: string
 }
 
+export interface DiscordReadState {
+  channelId: string
+  lastMessageId: string | null
+  mentionCount: number
+}
+
+export interface DiscordUnreadMention extends DiscordMention {
+  mention_count: number
+}
+
+export interface DiscordUnreadMentionsResult {
+  mentions: DiscordUnreadMention[]
+  count: number
+  // Account-wide unread-mention badge total; not narrowed by guildId because
+  // READY read states carry no guild association.
+  badgeCount: number
+  complete: boolean
+  windowDays: number
+}
+
 export interface DiscordSearchResult {
   id: string
   channel_id: string
@@ -109,6 +130,15 @@ export interface DiscordSearchResponse {
   messages: DiscordSearchResult[][]
 }
 
+export interface DiscordSearchIndexNotReadyResponse {
+  message: string
+  code: 110000
+  documents_indexed: number
+  retry_after: number
+}
+
+export type DiscordSearchApiResponse = DiscordSearchResponse | DiscordSearchIndexNotReadyResponse
+
 export interface DiscordSearchOptions {
   channelId?: string
   authorId?: string
@@ -181,6 +211,14 @@ export const DiscordChannelSchema = z.object({
   position: z.number().optional(),
 })
 
+export const DiscordReactionSchema = z.object({
+  emoji: z.object({
+    id: z.string().nullish(),
+    name: z.string().nullable(),
+  }),
+  count: z.number(),
+})
+
 export const DiscordMessageSchema = z.object({
   id: z.string(),
   channel_id: z.string(),
@@ -192,6 +230,7 @@ export const DiscordMessageSchema = z.object({
   timestamp: z.string(),
   edited_timestamp: z.string().optional(),
   thread_id: z.string().optional(),
+  reactions: z.array(DiscordReactionSchema).optional(),
 })
 
 export const DiscordUserSchema = z.object({
@@ -210,14 +249,6 @@ export const DiscordDMChannelSchema = z.object({
   name: z.string().optional(),
 })
 
-export const DiscordReactionSchema = z.object({
-  emoji: z.object({
-    id: z.string().optional(),
-    name: z.string(),
-  }),
-  count: z.number(),
-})
-
 export const DiscordFileSchema = z.object({
   id: z.string(),
   filename: z.string(),
@@ -267,6 +298,13 @@ export const DiscordSearchResponseSchema = z.object({
   messages: z.array(z.array(DiscordSearchResultSchema)),
 })
 
+export const DiscordSearchIndexNotReadyResponseSchema = z.object({
+  message: z.string(),
+  code: z.literal(110000),
+  documents_indexed: z.number(),
+  retry_after: z.number().nonnegative(),
+})
+
 export const DiscordCredentialsSchema = z.object({
   token: z.string(),
 })
@@ -386,6 +424,24 @@ export interface DiscordGatewayGenericEvent {
   [key: string]: unknown
 }
 
+// read_state_type 0 = channel read state (carries last_message_id); non-zero types
+// carry last_acked_id instead and must be filtered out for mention correlation.
+export const DiscordRawReadStateSchema = z.object({
+  id: z.string(),
+  read_state_type: z.number().optional(),
+  last_message_id: z.string().nullish(),
+  mention_count: z.number().optional(),
+})
+
+export type DiscordRawReadState = z.infer<typeof DiscordRawReadStateSchema>
+
+// READY sends read_state as a raw array, or as { entries, version } when the
+// VERSIONED_READ_STATES gateway capability is negotiated.
+export const DiscordReadyReadStateSchema = z.union([
+  z.array(z.unknown()),
+  z.object({ entries: z.array(z.unknown()), version: z.number().optional() }),
+])
+
 export type DiscordGatewayEvent =
   | DiscordGatewayMessageCreateEvent
   | DiscordGatewayMessageUpdateEvent