agent-messenger 2.32.3 → 2.34.0

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

@@ -2,11 +2,52 @@ import { afterEach, beforeEach, expect, spyOn, it } from 'bun:test'
 
 import { DiscordClient } from '../client'
 import { DiscordCredentialManager } from '../credential-manager'
+import { meAction } from './member'
 
+let clientGetMyGuildMemberSpy: ReturnType<typeof spyOn>
+let clientListRolesSpy: ReturnType<typeof spyOn>
 let clientSearchMembersSpy: ReturnType<typeof spyOn>
+let consoleLogSpy: ReturnType<typeof spyOn>
 let credManagerLoadSpy: ReturnType<typeof spyOn>
 
 beforeEach(() => {
+  clientGetMyGuildMemberSpy = spyOn(DiscordClient.prototype, 'getMyGuildMember').mockResolvedValue({
+    user: {
+      id: 'user-1',
+      username: 'alice',
+      global_name: 'Alice Smith',
+      avatar: 'avatar-hash-1',
+      bot: false,
+    },
+    nick: 'AliceNick',
+    roles: ['role-low', 'role-missing', 'role-high'],
+    joined_at: '2024-01-15T10:00:00Z',
+    deaf: false,
+    mute: false,
+    flags: 0,
+  })
+  clientListRolesSpy = spyOn(DiscordClient.prototype, 'listRoles').mockResolvedValue([
+    {
+      id: 'role-low',
+      name: 'Member',
+      color: 0,
+      hoist: false,
+      position: 1,
+      permissions: '1024',
+      managed: false,
+      mentionable: false,
+    },
+    {
+      id: 'role-high',
+      name: 'Admin',
+      color: 16711680,
+      hoist: true,
+      position: 10,
+      permissions: '8',
+      managed: false,
+      mentionable: true,
+    },
+  ])
   clientSearchMembersSpy = spyOn(DiscordClient.prototype, 'searchMembers').mockResolvedValue([
     {
       user: {
@@ -47,10 +88,14 @@ beforeEach(() => {
       'guild-1': { server_id: 'guild-1', server_name: 'Test Guild' },
     },
   })
+  consoleLogSpy = spyOn(console, 'log').mockImplementation(() => {})
 })
 
 afterEach(() => {
+  clientGetMyGuildMemberSpy?.mockRestore()
+  clientListRolesSpy?.mockRestore()
   clientSearchMembersSpy?.mockRestore()
+  consoleLogSpy?.mockRestore()
   credManagerLoadSpy?.mockRestore()
 })
 
@@ -97,3 +142,135 @@ it('search: uses default limit of 10', async () => {
 
   expect(members).toHaveLength(2)
 })
+
+it("me: returns the current user's member object", async () => {
+  await meAction(undefined, {})
+
+  const output = JSON.parse(consoleLogSpy.mock.calls.at(-1)?.[0] as string)
+  expect(output).toMatchObject({
+    user: {
+      id: 'user-1',
+      username: 'alice',
+      global_name: 'Alice Smith',
+      avatar: 'avatar-hash-1',
+      bot: false,
+    },
+    nick: 'AliceNick',
+    joined_at: '2024-01-15T10:00:00Z',
+    deaf: false,
+    mute: false,
+    flags: 0,
+  })
+  expect(clientGetMyGuildMemberSpy).toHaveBeenCalledWith('guild-1')
+  expect(clientListRolesSpy).toHaveBeenCalledWith('guild-1')
+})
+
+it('me: returns roles resolved to names (not raw IDs)', async () => {
+  await meAction('guild-2', {})
+
+  const output = JSON.parse(consoleLogSpy.mock.calls.at(-1)?.[0] as string)
+  expect(output.roles.map((role: { name: string }) => role.name)).toEqual(['Admin', 'Member'])
+  expect(output.roles).not.toContain('role-high')
+  expect(clientGetMyGuildMemberSpy).toHaveBeenCalledWith('guild-2')
+})
+
+it('me: roles are sorted by position descending', async () => {
+  await meAction(undefined, {})
+
+  const output = JSON.parse(consoleLogSpy.mock.calls.at(-1)?.[0] as string)
+  expect(output.roles.map((role: { position: number }) => role.position)).toEqual([10, 1])
+})
+
+it('me: role IDs with no matching role definition are dropped', async () => {
+  await meAction(undefined, {})
+
+  const output = JSON.parse(consoleLogSpy.mock.calls.at(-1)?.[0] as string)
+  expect(output.roles).toHaveLength(2)
+  expect(output.roles.map((role: { id: string }) => role.id)).not.toContain('role-missing')
+})
+
+it('me: breaks equal-position ties by snowflake, ranking the smaller ID higher', async () => {
+  // given two roles sharing a position whose IDs collide once coerced to Number
+  clientGetMyGuildMemberSpy.mockResolvedValue({
+    user: { id: 'user-1', username: 'alice', global_name: 'Alice Smith', avatar: 'avatar-hash-1', bot: false },
+    nick: null,
+    roles: ['1234567890123456789', '1234567890123456788'],
+    joined_at: '2024-01-15T10:00:00Z',
+    deaf: false,
+    mute: false,
+    flags: 0,
+  })
+  clientListRolesSpy.mockResolvedValue([
+    {
+      id: '1234567890123456789',
+      name: 'Newer',
+      color: 0,
+      position: 5,
+      hoist: false,
+      managed: false,
+      mentionable: false,
+      permissions: '0',
+    },
+    {
+      id: '1234567890123456788',
+      name: 'Older',
+      color: 0,
+      position: 5,
+      hoist: false,
+      managed: false,
+      mentionable: false,
+      permissions: '0',
+    },
+  ])
+
+  await meAction(undefined, {})
+
+  const output = JSON.parse(consoleLogSpy.mock.calls.at(-1)?.[0] as string)
+  expect(output.roles.map((role: { name: string }) => role.name)).toEqual(['Older', 'Newer'])
+})
+
+it('me: ranks by position before falling back to the snowflake', async () => {
+  clientGetMyGuildMemberSpy.mockResolvedValue({
+    user: { id: 'user-1', username: 'alice', global_name: 'Alice Smith', avatar: 'avatar-hash-1', bot: false },
+    nick: null,
+    roles: ['100', '200'],
+    joined_at: '2024-01-15T10:00:00Z',
+    deaf: false,
+    mute: false,
+    flags: 0,
+  })
+  clientListRolesSpy.mockResolvedValue([
+    {
+      id: '100',
+      name: 'Low',
+      color: 0,
+      position: 1,
+      hoist: false,
+      managed: false,
+      mentionable: false,
+      permissions: '0',
+    },
+    {
+      id: '200',
+      name: 'High',
+      color: 0,
+      position: 9,
+      hoist: false,
+      managed: false,
+      mentionable: false,
+      permissions: '0',
+    },
+  ])
+
+  await meAction(undefined, {})
+
+  const output = JSON.parse(consoleLogSpy.mock.calls.at(-1)?.[0] as string)
+  expect(output.roles.map((role: { name: string }) => role.name)).toEqual(['High', 'Low'])
+})
+
+it('me: preserves the raw role IDs even when a definition is unresolvable', async () => {
+  await meAction(undefined, {})
+
+  const output = JSON.parse(consoleLogSpy.mock.calls.at(-1)?.[0] as string)
+  expect(output.role_ids).toEqual(['role-low', 'role-missing', 'role-high'])
+})

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

@@ -5,6 +5,7 @@ import { formatOutput } from '@/shared/utils/output'
 
 import { DiscordClient } from '../client'
 import { DiscordCredentialManager } from '../credential-manager'
+import type { DiscordRole } from '../types'
 
 async function searchAction(
   guildId: string,
@@ -46,6 +47,80 @@ async function searchAction(
   }
 }
 
+export async function meAction(guildId: string | undefined, options: { 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 targetGuildId = guildId ?? config.current_server
+    if (!targetGuildId) {
+      console.log(formatOutput({ error: 'No current server set. Run "server switch <id>" first.' }, options.pretty))
+      process.exit(1)
+    }
+
+    const client = await new DiscordClient().login({ token: config.token })
+    const [member, roles] = await Promise.all([client.getMyGuildMember(targetGuildId), client.listRoles(targetGuildId)])
+    const rolesById = new Map<string, DiscordRole>(roles.map((role) => [role.id, role]))
+    const resolvedRoles = member.roles
+      .map((roleId) => rolesById.get(roleId))
+      .filter((role): role is DiscordRole => role !== undefined)
+      .sort(compareRolesByHierarchy)
+      .map((role) => ({
+        id: role.id,
+        name: role.name,
+        color: role.color,
+        position: role.position,
+        hoist: role.hoist,
+        managed: role.managed,
+        mentionable: role.mentionable,
+        permissions: role.permissions,
+      }))
+
+    const output = {
+      user: {
+        id: member.user.id,
+        username: member.user.username,
+        global_name: member.user.global_name,
+        avatar: member.user.avatar,
+        bot: member.user.bot,
+      },
+      nick: member.nick,
+      role_ids: member.roles,
+      roles: resolvedRoles,
+      joined_at: member.joined_at,
+      deaf: member.deaf,
+      mute: member.mute,
+      flags: member.flags,
+    }
+
+    console.log(formatOutput(output, options.pretty))
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+// Discord ranks roles by descending position and breaks ties on the snowflake,
+// where the smaller ID is the higher role. Snowflakes exceed Number.MAX_SAFE_INTEGER,
+// so they are compared as BigInt rather than subtracted.
+function compareRolesByHierarchy(left: DiscordRole, right: DiscordRole): number {
+  if (left.position !== right.position) {
+    return right.position - left.position
+  }
+
+  const leftId = BigInt(left.id)
+  const rightId = BigInt(right.id)
+  if (leftId === rightId) {
+    return 0
+  }
+
+  return leftId < rightId ? -1 : 1
+}
+
 export const memberCommand = new Command('member')
   .description('Member commands')
   .addCommand(
@@ -57,3 +132,10 @@ export const memberCommand = new Command('member')
       .option('--pretty', 'Pretty print JSON output')
       .action(searchAction),
   )
+  .addCommand(
+    new Command('me')
+      .description('Get your own membership and roles in a guild')
+      .argument('[guild-id]', 'Guild ID (defaults to current server)')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(meAction),
+  )

package/src/platforms/discord/index.ts

@@ -26,10 +26,16 @@ export type {
   DiscordMessage,
   DiscordReaction,
   DiscordReadState,
+  DiscordReadStateSnapshot,
   DiscordRelationship,
+  DiscordRole,
+  DiscordRoleColors,
+  DiscordRoleTags,
   DiscordSearchOptions,
   DiscordSearchResponse,
   DiscordSearchResult,
+  DiscordUnreadDM,
+  DiscordUnreadDMsResult,
   DiscordUnreadMention,
   DiscordUnreadMentionsResult,
   DiscordUser,

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

@@ -143,19 +143,28 @@ describe('parseReadStates', () => {
       { id: 'c2', read_state_type: 2, mention_count: 5 },
     ])
 
-    expect(result).toEqual([{ channelId: 'c1', lastMessageId: '100', mentionCount: 1 }])
+    expect(result.states).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 }])
+    expect(result.states).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 }])
+    expect(result.states).toEqual([{ channelId: 'c1', lastMessageId: null, mentionCount: 1 }])
+  })
+
+  it('treats a bare array payload as complete', () => {
+    expect(parseReadStates([{ id: 'c1' }]).partial).toBe(false)
+  })
+
+  it('reads the partial flag from a versioned payload', () => {
+    expect(parseReadStates({ entries: [{ id: 'c1' }], version: 7, partial: true }).partial).toBe(true)
+    expect(parseReadStates({ entries: [{ id: 'c1' }], version: 7 }).partial).toBe(false)
   })
 
   it('throws on a non-array, non-versioned payload', () => {

package/src/platforms/discord/listener.ts

@@ -3,16 +3,22 @@ import { EventEmitter } from 'events'
 import WebSocket from 'ws'
 
 import type { DiscordClient } from './client'
-import type { DiscordListenerEventMap, DiscordGatewayGenericEvent, DiscordReadState } from './types'
+import type {
+  DiscordListenerEventMap,
+  DiscordGatewayGenericEvent,
+  DiscordReadState,
+  DiscordReadStateSnapshot,
+} from './types'
 import { DiscordGatewayOpcode, DiscordRawReadStateSchema, DiscordReadyReadStateSchema } from './types'
 
-export function parseReadStates(value: unknown): DiscordReadState[] {
+export function parseReadStates(value: unknown): DiscordReadStateSnapshot {
   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 partial = Array.isArray(parsed.data) ? false : (parsed.data.partial ?? false)
 
   const readStates: DiscordReadState[] = []
   for (const entry of entries) {
@@ -25,7 +31,7 @@ export function parseReadStates(value: unknown): DiscordReadState[] {
       mentionCount: state.data.mention_count ?? 0,
     })
   }
-  return readStates
+  return { states: readStates, partial }
 }
 
 const GATEWAY_URL = 'wss://gateway.discord.gg/?v=10&encoding=json'
@@ -80,6 +86,7 @@ export class DiscordListener {
   private token: string | null = null
   private cachedUser: { id: string; username: string } | null = null
   private readState: DiscordReadState[] | null = null
+  private readStatePartial = false
   private generation = 0
   private startPromise: Promise<void> | null = null
   private pendingStartReject: ((error: Error) => void) | null = null
@@ -202,6 +209,10 @@ export class DiscordListener {
     return this.readState
   }
 
+  getReadStateSnapshot(): DiscordReadStateSnapshot | null {
+    return this.readState === null ? null : { states: this.readState, partial: this.readStatePartial }
+  }
+
   private isCurrent(generation: number, ws?: WebSocket): boolean {
     if (generation !== this.generation || !this.running) return false
     if (ws !== undefined && this.ws !== ws) return false
@@ -326,7 +337,9 @@ 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)
+      const snapshot = d.read_state === undefined ? null : parseReadStates(d.read_state)
+      this.readState = snapshot === null ? [] : snapshot.states
+      this.readStatePartial = snapshot?.partial ?? false
       this.reconnectAttempts = 0
       this.emitter.emit('connected', { user: d.user, sessionId: d.session_id })
       return

package/src/platforms/discord/types.ts

@@ -139,6 +139,13 @@ export interface DiscordReadState {
   mentionCount: number
 }
 
+// When partial is true the entries are an incomplete slice, so an absent channel
+// carries no information: it may simply have been left out of this payload.
+export interface DiscordReadStateSnapshot {
+  states: DiscordReadState[]
+  partial: boolean
+}
+
 export interface DiscordUnreadMention extends DiscordMention {
   mention_count: number
 }
@@ -153,6 +160,31 @@ export interface DiscordUnreadMentionsResult {
   windowDays: number
 }
 
+export interface DiscordUnreadDM {
+  id: string
+  type: number
+  name: string | null
+  recipients: DiscordUser[]
+  lastMessageId: string
+  // Discord's own badge counter, which counts every message in a DM rather than
+  // only mentions. null when the channel has no READY read-state entry (count
+  // unknown); 0 when the DM is muted, since muting stops the counter but still
+  // leaves the channel unread.
+  unreadCount: number | null
+}
+
+// count and totalUnread describe every unread DM found, so they stay truthful when
+// `channels` is capped by a limit. totalUnread sums known counts only, meaning
+// channels with an unknown count contribute nothing to it. complete is false when
+// Discord delivered a partial read state, in which case never-opened DMs may be
+// missing from the result.
+export interface DiscordUnreadDMsResult {
+  channels: DiscordUnreadDM[]
+  count: number
+  totalUnread: number
+  complete: boolean
+}
+
 export interface DiscordSearchResult {
   id: string
   channel_id: string
@@ -207,6 +239,38 @@ export interface DiscordGuildMember {
   flags: number
 }
 
+export interface DiscordRoleColors {
+  primary_color: number
+  secondary_color: number | null
+  tertiary_color: number | null
+}
+
+export interface DiscordRoleTags {
+  bot_id?: string
+  integration_id?: string
+  premium_subscriber?: null
+  subscription_listing_id?: string
+  available_for_purchase?: null
+  guild_connections?: null
+}
+
+export interface DiscordRole {
+  id: string
+  name: string
+  /** @deprecated Discord still returns this; prefer {@link DiscordRoleColors.primary_color}. */
+  color: number
+  colors: DiscordRoleColors
+  hoist: boolean
+  position: number
+  permissions: string
+  managed: boolean
+  mentionable: boolean
+  flags: number
+  icon?: string | null
+  unicode_emoji?: string | null
+  tags?: DiscordRoleTags
+}
+
 export interface DiscordUserProfile {
   user: DiscordUser & { bio?: string }
   connected_accounts: Array<{
@@ -480,7 +544,11 @@ export type DiscordRawReadState = z.infer<typeof DiscordRawReadStateSchema>
 // 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() }),
+  z.object({
+    entries: z.array(z.unknown()),
+    version: z.number().optional(),
+    partial: z.boolean().optional(),
+  }),
 ])
 
 export type DiscordGatewayEvent =