fix(commands): dispatch commands sent as a media caption

Author: zeative

.changeset/command-on-caption.md

@@ -0,0 +1,10 @@
+---
+"zaileys": patch
+---
+
+Commands now fire when they arrive as a media caption.
+
+The dispatcher listened to the `text` event, which deliberately excludes captions — so a photo
+captioned `!sticker` never reached the handler, even though `ctx.text` would have carried it. It now
+listens to `message`, which is the same stream with captions included. Plain text commands are
+unaffected, and a command still runs exactly once.

docs/content/commands.mdx

@@ -36,8 +36,18 @@ omitting the option all leave the command framework disabled — your `command()
 never fire.
 </Callout>
 
-Commands are matched on the `text` event stream, so they work in DMs, groups, and any chat that
-produces a text message. See [Events](/events) for the full event surface.
+Commands are matched on every inbound message, in DMs and groups alike — **including media
+captions**. Sending a photo captioned `!sticker` runs the `sticker` command with the photo attached
+as `ctx.media`, which is how most WhatsApp bots are actually used.
+
+```typescript
+client.command('sticker', async (ctx) => {
+  if (ctx.media?.type !== 'image') return ctx.reply('Send a photo captioned !sticker')
+  await ctx.send().sticker(await ctx.media.buffer())
+})
+```
+
+See [Events](/events) for the full event surface.
 
 ## Registering a command
 

src/client/client.ts

@@ -782,10 +782,14 @@ export class Client extends TypedEventEmitter<ClientEventMap> {
       middleware: this.commandMiddleware,
       prefixes: this.commandPrefixes,
       logger: this.logger,
+      /**
+       * `message` rather than `text`: a command is just as often a media caption (`.sticker` on a
+       * photo), and the `text` event deliberately excludes captions.
+       */
       onText: (handler) => {
         const wrapped = (msg: MessageContext): void => handler(msg)
-        this.on('text', wrapped)
-        return () => this.off('text', wrapped)
+        this.on('message', wrapped)
+        return () => this.off('message', wrapped)
       },
       buildContext: (resolved, msg) => this.buildCommandContext(resolved, msg),
       isAdmin: (groupJid, senderJid) => this.isGroupAdmin(groupJid, senderJid),

tests/client/command-guards.test.ts

@@ -30,7 +30,7 @@ const connected = () => {
 
 /** Fires a text message through the real dispatcher and waits for the async guard chain. */
 const send = async (client: Client, text: string, isGroup = true): Promise<void> => {
-  client.emit('text', msg(text, isGroup))
+  client.emit('message', msg(text, isGroup))
   await new Promise((r) => setTimeout(r, 10))
 }
 

tests/client/command-on-caption.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Client } from '../../src/client/client.js'
+import { MemoryAuthStore } from '../../src/auth/adapters/memory.js'
+import { attachInboundPipeline } from '../../src/events/pipeline.js'
+import { makeInboundSocket } from '../_helpers/mock-socket-events.js'
+
+const SELF = '628SELF@s.whatsapp.net'
+const SENDER = '628111@s.whatsapp.net'
+
+/** Drives the real decode pipeline so the command sees exactly what a live message produces. */
+const bot = () => {
+  const client = new Client({
+    auth: new MemoryAuthStore(),
+    qrTerminal: false,
+    autoConnect: false,
+    commandPrefix: '!',
+  })
+  const socket = makeInboundSocket({ user: { id: SELF } })
+  ;(client as unknown as { _socket: unknown })._socket = socket
+  attachInboundPipeline(client, socket as unknown as Parameters<typeof attachInboundPipeline>[1], {
+    selfJid: SELF,
+  })
+  return { client, socket }
+}
+
+const deliver = async (socket: ReturnType<typeof bot>['socket'], message: unknown) => {
+  socket.triggerMessagesUpsert({
+    messages: [{ key: { remoteJid: SENDER, id: 'M1', fromMe: false }, message, messageTimestamp: 1700 }],
+    type: 'notify',
+  })
+  await new Promise((r) => setTimeout(r, 20))
+}
+
+describe('a command may arrive as a media caption', () => {
+  it('runs when the prefix is the caption of an image', async () => {
+    const { client, socket } = bot()
+    const run = vi.fn()
+    client.command('sticker', run)
+    await deliver(socket, { imageMessage: { mimetype: 'image/jpeg', caption: '!sticker' } })
+    expect(run).toHaveBeenCalledTimes(1)
+  })
+
+  it('runs for a video caption too, and passes its arguments', async () => {
+    const { client, socket } = bot()
+    const run = vi.fn()
+    client.command('swgc', run)
+    await deliver(socket, { videoMessage: { mimetype: 'video/mp4', caption: '!swgc promo hari ini' } })
+    expect(run).toHaveBeenCalledTimes(1)
+    expect((run.mock.calls[0]![0] as { args: string[] }).args).toEqual(['promo', 'hari', 'ini'])
+  })
+
+  it('still runs for a plain text message', async () => {
+    const { client, socket } = bot()
+    const run = vi.fn()
+    client.command('ping', run)
+    await deliver(socket, { conversation: '!ping' })
+    expect(run).toHaveBeenCalledTimes(1)
+  })
+
+  it('runs a command exactly once, not once per event it appears on', async () => {
+    const { client, socket } = bot()
+    const run = vi.fn()
+    client.command('ping', run)
+    await deliver(socket, { conversation: '!ping' })
+    expect(run).toHaveBeenCalledTimes(1)
+  })
+
+  it('leaves a captioned image alone when the caption is not a command', async () => {
+    const { client, socket } = bot()
+    const run = vi.fn()
+    client.command('sticker', run)
+    await deliver(socket, { imageMessage: { mimetype: 'image/jpeg', caption: 'foto liburan' } })
+    expect(run).not.toHaveBeenCalled()
+  })
+})

tests/client/reply-lifetime.test.ts

@@ -54,7 +54,7 @@ describe('replies inherit the disappearing timer', () => {
     client.command('ping', async (ctx) => {
       await ctx.reply('pong')
     })
-    client.emit('text', msg(604800))
+    client.emit('message', msg(604800))
     await new Promise((r) => setTimeout(r, 20))
     expect(optionsOf(sendMessage).ephemeralExpiration).toBe(604800)
   })
@@ -64,7 +64,7 @@ describe('replies inherit the disappearing timer', () => {
     client.command('ping', async (ctx) => {
       await ctx.reply('pong')
     })
-    client.emit('text', msg())
+    client.emit('message', msg())
     await new Promise((r) => setTimeout(r, 20))
     expect(optionsOf(sendMessage).ephemeralExpiration).toBeUndefined()
   })

tests/plugin/end-to-end.test.ts

@@ -62,7 +62,7 @@ describe('plugin file to dispatched command', () => {
       { name: 'ping', aliases: [], description: 'Cek bot', category: 'info' },
     ])
 
-    client.emit('text', msg('!ping'))
+    client.emit('message', msg('!ping'))
     await new Promise((r) => setTimeout(r, 20))
     expect((globalThis as Record<string, unknown>)['__hit']).toBe('ping')
   })
@@ -88,7 +88,7 @@ describe('plugin file to dispatched command', () => {
     )
     await boot()
 
-    client.emit('text', msg('!legacy'))
+    client.emit('message', msg('!legacy'))
     await new Promise((r) => setTimeout(r, 20))
     expect((globalThis as Record<string, unknown>)['__legacy']).toBe(true)
   })