fix: speed up group participant sync

Author: Rodrigo

__tests__/routes/groups.ts

@@ -10,6 +10,8 @@ import { addToBlacklist } from '../../src/services/blacklist'
 import { Reload } from '../../src/services/reload'
 import { Logout } from '../../src/services/logout'
 
+jest.setTimeout(30000)
+
 type LoadedApp = {
   app: any
   incoming: any
@@ -23,6 +25,9 @@ type LoadedApp = {
     getPnForLid: jest.Mock
     getProfilePicture: jest.Mock
     setGroup: jest.Mock
+    redisSetIfNotExists: jest.Mock
+    redisDelKey: jest.Mock
+    groupKey: jest.Mock
   }
 }
 
@@ -57,6 +62,9 @@ const loadApp = async (metaGroupsEnabled: boolean): Promise<LoadedApp> => {
     getPnForLid: jest.fn(),
     getProfilePicture: jest.fn(),
     setGroup: jest.fn(),
+    redisSetIfNotExists: jest.fn(),
+    redisDelKey: jest.fn(),
+    groupKey: jest.fn((phone: string, jid: string) => `unoapi-group:${phone}:${jid}`),
   }))
 
   // Require after doMock so defaults/redis are evaluated with this test's flag.
@@ -65,6 +73,7 @@ const loadApp = async (metaGroupsEnabled: boolean): Promise<LoadedApp> => {
   // eslint-disable-next-line @typescript-eslint/no-var-requires
   const redis = require('../../src/services/redis')
   const incoming = mock<Incoming>()
+  ;(incoming as any).groupMetadata = jest.fn()
   const outgoing = mock<Outgoing>()
   const onNewLogin = mock<OnNewLogin>()
   const reload = mock<Reload>()
@@ -105,6 +114,10 @@ describe('groups routes', () => {
     jest.dontMock('../../src/services/rate_limit')
   })
 
+  beforeEach(() => {
+    addToBlacklistMock.mockClear()
+  })
+
   test('list keeps legacy shape when meta group flag is disabled', async () => {
     const phone = '556600000000'
     const groupJid = '120363040468224422@g.us'
@@ -211,6 +224,7 @@ describe('groups routes', () => {
         {
           jid: '556688888888',
           wa_id: '556688888888',
+          user_id: '',
           name: 'Joao',
           is_admin: false,
           role: 'member',
@@ -252,6 +266,7 @@ describe('groups routes', () => {
         {
           jid: '556688888888',
           wa_id: '556688888888',
+          user_id: '',
           name: '556688888888',
           is_admin: false,
           role: 'member',
@@ -284,7 +299,7 @@ describe('groups routes', () => {
     expect(redis.getProfilePicture).toHaveBeenCalledWith(phone, '556699999999@s.whatsapp.net')
   })
 
-  test('participants route keeps wa_id blank for LID-only participants', async () => {
+  test('participants route resolves wa_id for LID-only participants from jid map', async () => {
     const phone = '556600000000'
     const groupJid = '120363040468224422@g.us'
     const { app, redis } = await loadApp(true)
@@ -297,22 +312,82 @@ describe('groups routes', () => {
         },
       ],
     })
+    redis.getPnForLid.mockResolvedValue('5566996222471@s.whatsapp.net')
 
     const res = await request(app.server).get(`/v15.0/${phone}/groups/${groupJid}/participants`)
 
     expect(res.status).toEqual(200)
     expect(res.body.participants).toEqual([
       expect.objectContaining({
-        jid: '777777777777777@lid',
-        wa_id: '',
+        jid: '5566996222471',
+        wa_id: '5566996222471',
         user_id: '777777777777777@lid',
         username: '@lid.only',
         name: '@lid.only',
       }),
     ])
+    expect(redis.getPnForLid).toHaveBeenCalledWith(phone, '777777777777777@lid')
     expect(res.body.total_participant_count).toEqual(1)
   })
 
+  test('participants route enriches legacy payload with wa_id and user_id', async () => {
+    const phone = '556600000000'
+    const groupJid = '120363040468224422@g.us'
+    const { app, redis } = await loadApp(false)
+    redis.getGroup.mockResolvedValue({
+      subject: cachedGroup.subject,
+      participants: [{ lid: '11343495192601@lid' }],
+    })
+    redis.getPnForLid.mockResolvedValue('5566996222471@s.whatsapp.net')
+    redis.getContactName.mockResolvedValue('ViperTec')
+
+    const res = await request(app.server).get(`/v15.0/${phone}/groups/${groupJid}/participants`)
+
+    expect(res.status).toEqual(200)
+    expect(res.body.participants).toEqual([
+      {
+        jid: '5566996222471',
+        wa_id: '5566996222471',
+        user_id: '11343495192601@lid',
+        name: 'ViperTec',
+      },
+    ])
+  })
+
+  test('participants route refreshes raw group metadata before responding when available', async () => {
+    const phone = '556600000000'
+    const groupJid = '120363040468224422@g.us'
+    const { app, incoming, redis } = await loadApp(true)
+    const staleGroup = {
+      subject: cachedGroup.subject,
+      participants: [{ id: '556600000001@s.whatsapp.net' }],
+    }
+    const freshGroup = {
+      subject: cachedGroup.subject,
+      participants: [
+        { id: '556600000001@s.whatsapp.net' },
+        { id: '5566996222471@s.whatsapp.net', lid: '11343495192601@lid', admin: 'admin' },
+      ],
+    }
+    redis.getGroup.mockResolvedValue(staleGroup)
+    redis.redisSetIfNotExists.mockResolvedValue(true)
+    incoming.groupMetadata.mockResolvedValue(freshGroup)
+
+    const res = await request(app.server).get(`/v15.0/${phone}/groups/${groupJid}/participants`)
+
+    expect(res.status).toEqual(200)
+    expect(incoming.groupMetadata).toHaveBeenCalledWith(phone, groupJid)
+    expect(redis.redisDelKey).toHaveBeenCalledWith(`unoapi-group:${phone}:${groupJid}`)
+    expect(redis.setGroup).toHaveBeenCalledWith(phone, groupJid, freshGroup)
+    expect(res.body.total_participant_count).toEqual(2)
+    expect(res.body.participants[1]).toEqual(expect.objectContaining({
+      wa_id: '5566996222471',
+      user_id: '11343495192601@lid',
+      role: 'admin',
+      is_admin: true,
+    }))
+  })
+
   test('participants route returns Meta-like 404 payload when group is not cached', async () => {
     const phone = '556600000000'
     const groupJid = '120363040468224422@g.us'

src/controllers/groups_controller.ts

@@ -1,6 +1,6 @@
 import { Request, Response } from 'express'
 import { UNOAPI_META_GROUPS_ENABLED } from '../defaults'
-import { getContactInfo, getContactName, getGroup, getLidForPn, getPnForLid, getProfilePicture, redisKeys, BASE_KEY, setGroup } from '../services/redis'
+import { getContactInfo, getContactName, getGroup, getLidForPn, getPnForLid, getProfilePicture, redisKeys, BASE_KEY, setGroup, redisSetIfNotExists, redisDelKey, groupKey } from '../services/redis'
 import { normalizeGroupId, normalizeParticipantId } from '../services/transformer'
 import { Incoming } from '../services/incoming'
 import { Outgoing } from '../services/outgoing'
@@ -88,6 +88,69 @@ const participantRole = (participant: any): string => {
   return 'member'
 }
 
+const resolveParticipantIdentity = async (phone: string, participant: any) => {
+  const rawId = `${participant?.id || participant?.jid || participant?.lid || ''}`.trim()
+  const rawPhoneNumber = `${participant?.phoneNumber || participant?.phone_number || participant?.pn || ''}`.trim()
+  const sourceJid = rawId || rawPhoneNumber
+  let pnJid = rawPhoneNumber.endsWith('@s.whatsapp.net') ? rawPhoneNumber : ''
+  if (!pnJid && rawPhoneNumber) {
+    const candidate = normalizeParticipantJidForBaileys(rawPhoneNumber)
+    if (candidate.endsWith('@s.whatsapp.net')) pnJid = candidate
+  }
+  if (!pnJid && sourceJid.endsWith('@s.whatsapp.net')) pnJid = sourceJid
+  let lid = participantLid(participant, rawId || sourceJid)
+
+  if (!pnJid && sourceJid && !sourceJid.endsWith('@lid')) {
+    const candidate = normalizeParticipantJidForBaileys(sourceJid)
+    if (candidate.endsWith('@s.whatsapp.net')) pnJid = candidate
+  }
+
+  if (!pnJid && lid) {
+    try { pnJid = `${await getPnForLid(phone, lid) || ''}`.trim() } catch {}
+  }
+
+  if (!lid && pnJid) {
+    try { lid = `${await getLidForPn(phone, pnJid) || ''}`.trim() } catch {}
+  }
+
+  const waId = normalizeParticipantPhoneForResponse(pnJid || sourceJid)
+  return {
+    sourceJid,
+    pnJid,
+    lid,
+    waId,
+    responseJid: normalizeParticipantJidForResponse(pnJid || sourceJid || lid),
+  }
+}
+
+const participantDisplayName = (participant: any): string => {
+  return firstNonEmptyString(
+    participant?.name,
+    participant?.notify,
+    participant?.verifiedName,
+    participant?.pushName,
+  ) || ''
+}
+
+const resolveParticipantName = async (phone: string, participant: any, pnJid: string, lid: string): Promise<string> => {
+  const directName = participantDisplayName(participant)
+  if (directName) return directName
+  for (const jid of [pnJid, lid]) {
+    const clean = `${jid || ''}`.trim()
+    if (!clean) continue
+    let name = ''
+    try { name = `${await getContactName(phone, clean) || ''}`.trim() } catch {}
+    if (!name) {
+      try {
+        const infoRaw = await getContactInfo(phone, clean)
+        name = `${parseContactInfoName(infoRaw) || ''}`.trim()
+      } catch {}
+    }
+    if (name) return name
+  }
+  return ''
+}
+
 const groupDescription = (group: any): string => {
   return `${group?.desc || group?.description || ''}`
 }
@@ -121,6 +184,9 @@ const inviteLinkFromCode = (code?: string): string => {
 }
 
 const nowTimestamp = () => `${Math.floor(Date.now() / 1000)}`
+const GROUP_METADATA_REFRESH_THROTTLE_SECONDS = 60
+const GROUP_METADATA_REFRESH_TIMEOUT_MS = 5000
+const GROUP_PARTICIPANTS_NAME_LOOKUP_LIMIT = 100
 
 const managementWebhook = (phone: string, field: string, value: any) => ({
   object: 'whatsapp_business_account',
@@ -196,23 +262,38 @@ export class GroupsController {
     return `${group?.profilePicture || group?.picture || cached || ''}`
   }
 
-  private async formatParticipant(phone: string, participant: any, options: { includePicture?: boolean } = {}) {
-    const sourceJid = `${participant?.id || participant?.jid || participant?.lid || ''}`.trim()
-    const jid = normalizeParticipantJidForResponse(sourceJid)
-    const pnJid = sourceJid.endsWith('@s.whatsapp.net') ? sourceJid : ''
-    const lid = participantLid(participant, sourceJid)
-    const waId = normalizeParticipantPhoneForResponse(pnJid || sourceJid)
+  private async refreshGroupMetadata(phone: string, groupJid: string): Promise<any | undefined> {
+    if (typeof this.incoming.groupMetadata !== 'function') return undefined
+    const refreshKey = `${BASE_KEY}group-refresh:${phone}:${groupJid}`
+    const acquired = await redisSetIfNotExists(refreshKey, `${Date.now()}`, GROUP_METADATA_REFRESH_THROTTLE_SECONDS)
+    if (!acquired) return undefined
+    const timeout = new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), GROUP_METADATA_REFRESH_TIMEOUT_MS))
+    const fetched = await Promise.race([
+      this.incoming.groupMetadata(phone, groupJid).catch(() => undefined),
+      timeout,
+    ])
+    if (!fetched) return undefined
+    try { await redisDelKey(groupKey(phone, groupJid)) } catch {}
+    await setGroup(phone, groupJid, fetched as any)
+    return fetched
+  }
+
+  private async formatParticipant(phone: string, participant: any, options: { includePicture?: boolean, resolveName?: boolean } = {}) {
+    const { sourceJid, pnJid, lid, waId, responseJid } = await resolveParticipantIdentity(phone, participant)
+    const shouldResolveName = options.resolveName !== false
     let contactInfo: any
-    try { contactInfo = parseContactInfo(await getContactInfo(phone, sourceJid)) } catch {}
+    if (shouldResolveName) {
+      try { contactInfo = parseContactInfo(await getContactInfo(phone, pnJid || sourceJid || lid)) } catch {}
+    }
     const username = participantUsername(participant, contactInfo)
-    const resolvedName = await resolveNameForJid(phone, sourceJid)
+    const resolvedName = shouldResolveName ? await resolveParticipantName(phone, participant, pnJid, lid) : participantDisplayName(participant)
     const name = firstNonEmptyString(resolvedName, username, waId, lid) || ''
-    const picture = options.includePicture ? await getProfilePicture(phone, sourceJid) : ''
+    const picture = options.includePicture ? await getProfilePicture(phone, pnJid || sourceJid || lid) : ''
     return {
-      jid,
+      jid: responseJid,
       wa_id: waId,
+      user_id: lid,
       name,
-      ...(lid ? { user_id: lid } : {}),
       ...(username ? { username } : {}),
       ...(picture ? { picture } : {}),
       ...(lid ? { lid } : {}),
@@ -222,14 +303,9 @@ export class GroupsController {
   }
 
   private async formatParticipantReference(phone: string, rawJid: string) {
-    const clean = `${rawJid || ''}`.trim()
-    const waId = normalizeParticipantPhoneForResponse(clean)
-    let userId = clean.endsWith('@lid') ? clean : ''
-    if (!userId && clean.endsWith('@s.whatsapp.net')) {
-      try { userId = `${await getLidForPn(phone, clean) || ''}`.trim() } catch {}
-    }
+    const { waId, lid } = await resolveParticipantIdentity(phone, { id: rawJid })
     const response: any = { wa_id: waId }
-    if (userId) response.user_id = userId
+    if (lid) response.user_id = lid
     return response
   }
 
@@ -427,18 +503,25 @@ export class GroupsController {
       if (!phone) return res.status(400).json({ error: 'missing phone param' })
       if (!groupId) return res.status(400).json({ error: 'missing groupId param' })
       const groupJid = normalizeGroupJid(groupId)
-      const group = await getGroup(phone, groupJid)
+      const cachedGroup = await getGroup(phone, groupJid)
+      const cachedParticipants = Array.isArray((cachedGroup as any)?.participants) ? (cachedGroup as any).participants : []
+      const shouldRefreshMetadata =
+        !cachedGroup ||
+        cachedParticipants.length <= GROUP_PARTICIPANTS_NAME_LOOKUP_LIMIT ||
+        queryBoolean(req.query.refresh_metadata || req.query.refreshMetadata)
+      const group = shouldRefreshMetadata ? await this.refreshGroupMetadata(phone, groupJid) || cachedGroup : cachedGroup
       if (!group) return res.status(404).json(
         UNOAPI_META_GROUPS_ENABLED
           ? { error: 'group not found in cache', group_id: groupJid }
           : { error: 'group not found in cache', groupJid }
       )
 
       const participantsRaw: any[] = Array.isArray((group as any)?.participants) ? (group as any).participants : []
+      const resolveParticipantNames = participantsRaw.length <= GROUP_PARTICIPANTS_NAME_LOOKUP_LIMIT || queryBoolean(req.query.resolve_names || req.query.resolveNames)
       if (UNOAPI_META_GROUPS_ENABLED) {
         const picture = await this.groupPicture(phone, groupJid, group)
         const includeParticipantPictures = queryBoolean(req.query.include_pictures)
-        const participants = await Promise.all(participantsRaw.map((participant: any) => this.formatParticipant(phone, participant, { includePicture: includeParticipantPictures })))
+        const participants = await Promise.all(participantsRaw.map((participant: any) => this.formatParticipant(phone, participant, { includePicture: includeParticipantPictures, resolveName: resolveParticipantNames })))
         return res.json({
           phone,
           group: {
@@ -452,10 +535,13 @@ export class GroupsController {
         })
       }
       const participants = await Promise.all(participantsRaw.map(async (participant: any) => {
-        const sourceJid = `${participant?.id || participant?.jid || participant?.lid || ''}`.trim()
-        const name = await resolveNameForJid(phone, sourceJid)
+        const { pnJid, waId, lid, responseJid } = await resolveParticipantIdentity(phone, participant)
+        const resolvedName = resolveParticipantNames ? await resolveParticipantName(phone, participant, pnJid, lid) : participantDisplayName(participant)
+        const name = firstNonEmptyString(resolvedName, waId, lid) || ''
         return {
-          jid: normalizeParticipantJidForResponse(sourceJid),
+          jid: responseJid,
+          wa_id: waId,
+          user_id: lid,
           name,
         }
       }))

src/jobs/incoming.ts

@@ -38,6 +38,7 @@ export class IncomingJob {
       'groupLeave',
       'groupSettingUpdate',
       'groupJoinApprovalMode',
+      'groupMetadata',
     ]
     if (!allowedActions.includes(action)) {
       throw new Error(`Unknown group management action ${action}`)

src/services/client.ts

@@ -70,4 +70,6 @@ export interface Client {
   groupSettingUpdate?(jid: string, setting: 'announcement' | 'not_announcement' | 'locked' | 'unlocked'): Promise<void>
 
   groupJoinApprovalMode?(jid: string, mode: 'on' | 'off'): Promise<void>
+
+  groupMetadata?(jid: string): Promise<any>
 }