feat(commands): expose the client on the command context and pass plugin context to handlers

Author: zeative

docs/content/commands.mdx

@@ -224,6 +224,7 @@ normal text message is available (`ctx.senderId`, `ctx.roomId`, `ctx.isGroup`, `
 
 | Field / Method | Type | Description |
 | -------------- | ---- | ----------- |
+| `client` | `Client` | The client that received the command. Lets a handler call any client method without importing anything. |
 | `command` | `string` | The canonical command name that matched (e.g. `'help'`, `'group kick'`). |
 | `args` | `string[]` | Positional arguments after the command name. Flags and the leading command words are removed. |
 | `flags` | `Record<string, string \| boolean>` | Parsed `--flag` options. `true` for boolean flags, the string value otherwise. |

docs/content/plugins.mdx

@@ -32,8 +32,8 @@ import { definePlugin } from 'zaileys'
 export default definePlugin({
   name: 'greet',
   description: 'Say hello',
-  command: async (c) => {
-    await c.reply('hi there 👋')
+  command: async (ctx) => {
+    await ctx.reply('hi there 👋')
   },
 })
 ```
@@ -90,8 +90,8 @@ export default definePlugin({
   description: 'Say hello',
   cooldown: 3,
 
-  command: async (c) => {
-    await c.reply('hi there 👋')
+  command: async (ctx) => {
+    await ctx.reply('hi there 👋')
   },
 
   message: (m) => {
@@ -142,7 +142,7 @@ import { definePlugin } from 'zaileys'
 export default definePlugin({
   name: 'my-plugin',
   description: 'What it does',
-  command: async (c) => { /* handles !my-plugin */ },
+  command: async (ctx) => { /* handles !my-plugin */ },
   message: (m) => { /* every inbound message */ },
 })
 ```
@@ -152,7 +152,7 @@ export default definePlugin({
 | Field | Type | Description |
 | ----- | ---- | ----------- |
 | `name` | `string` | Required. Identifies the plugin **and** names the command `command` handles. |
-| `command` | `CommandHandler` | Handles the command named after this plugin. Omit if the plugin only listens to events. |
+| `command` | `(ctx, plugin) => void \| Promise<void>` | Handles the command named after this plugin. Omit if the plugin only listens to events. |
 | `setup` | `(ctx) => void \| (() => void) \| Promise<…>` | Optional escape hatch — see [below](#going-beyond-the-shorthands). |
 | `onUnload` | `() => void \| Promise<void>` | Optional cleanup, called on unload. |
 
@@ -170,7 +170,7 @@ export default definePlugin({
   group: true,
   admin: true,
   cooldown: 3,
-  command: async (c) => { /* ... */ },
+  command: async (ctx) => { /* ... */ },
 })
 ```
 
@@ -209,6 +209,25 @@ Available: `message` · `text` · `image` · `video` · `audio` · `document` ·
 Each is typed from [the event map](/events), so the payload needs no annotation. Listeners are
 removed automatically when the plugin unloads.
 
+### Reaching the client
+
+A command handler gets the client straight off its context:
+
+```typescript
+command: async (ctx) => {
+  await ctx.client.group.removeMember(ctx.roomId!, ctx.mentions)
+},
+```
+
+Event payloads are plain message contexts and carry no client, so every handler also receives the
+**plugin context** as a second argument:
+
+```typescript
+message: async (msg, plugin) => {
+  if (msg.text === 'ping') await plugin.client.send(msg.roomId!).text('pong')
+},
+```
+
 ## Going beyond the shorthands
 
 `setup(ctx)` is still there for what the fields cannot express: registering **several** commands
@@ -238,12 +257,12 @@ Supports aliases (pipe-separated) and multi-word commands. The command is automa
 de-registered when the plugin unloads.
 
 ```typescript
-ctx.command('ping', async (c) => {
-  await c.reply('pong')
+ctx.command('ping', async (ctx) => {
+  await ctx.reply('pong')
 })
 
-ctx.command('help|h|?', async (c) => {
-  await c.reply('Available: !ping, !help')
+ctx.command('help|h|?', async (ctx) => {
+  await ctx.reply('Available: !ping, !help')
 })
 ```
 
@@ -254,7 +273,7 @@ defaults to the plugin's folder**, so `plugins/group/kick.ts` needs no `category
 // plugins/group/kick.ts
 ctx.command(
   { name: 'kick', description: 'Remove a member', group: true, admin: true },
-  async (c) => { /* ... */ },
+  async (ctx) => { /* ... */ },
 )
 // registered with category: 'group'
 ```
@@ -335,8 +354,8 @@ export default definePlugin({
     const path = require('node:path')
     const config = require(path.join(ctx.pluginDir, 'config.json'))
 
-    ctx.command('status', async (c) => {
-      await c.reply(`Mode: ${config.mode}`)
+    ctx.command('status', async (ctx) => {
+      await ctx.reply(`Mode: ${config.mode}`)
     })
   },
 })

src/client/client.ts

@@ -827,6 +827,7 @@ export class Client extends TypedEventEmitter<ClientEventMap> {
     let lastSentKey: WAMessageKey | undefined
     return {
       ...msg,
+      client: this,
       raw: resolved.raw,
       command: resolved.command,
       args: resolved.args,

src/command/types.ts

@@ -1,6 +1,7 @@
 import type { WAMessageKey } from 'baileys'
 import type { MessageContext } from '../events/context.js'
 import type { TextOptions } from '../builder/builder.js'
+import type { Client as ZaileysClient } from '../client/client.js'
 
 export type CommandPrefix = string | string[]
 
@@ -14,6 +15,8 @@ export interface ParsedArgs {
 }
 
 export interface CommandContext extends MessageContext {
+  /** The client that received this command, so a handler needs nothing else in scope. */
+  client: ZaileysClient
   raw: string
   command: string
   args: string[]

src/plugin/registry.ts

@@ -55,13 +55,16 @@ const specOf = (plugin: Plugin): CommandSpec => {
 
 /** Turns the plugin's `command()` and per-event methods into real registrations. */
 const wireHandlers = (plugin: Plugin, ctx: PluginContext): void => {
-  if (typeof plugin.command === 'function') ctx.command(specOf(plugin), plugin.command)
+  const run = plugin.command
+  if (typeof run === 'function') {
+    ctx.command(specOf(plugin), (commandCtx) => run(commandCtx, ctx))
+  }
   const methods = plugin as unknown as Record<string, unknown>
   for (const event of INBOUND_EVENTS) {
     const handler = methods[camel(event)]
     if (typeof handler !== 'function') continue
     ctx.on(event, (payload) => {
-      void (handler as (p: unknown) => unknown)(payload)
+      void (handler as (p: unknown, c: PluginContext) => unknown)(payload, ctx)
     })
   }
 }

src/plugin/types.ts

@@ -36,6 +36,7 @@ type Camel<S extends string> = S extends `${infer Head}-${infer Tail}`
 export type PluginEventHandlers = {
   [E in keyof InboundEventMap as Camel<E>]?: (
     payload: InboundEventMap[E],
+    ctx: PluginContext,
   ) => void | Promise<void>
 }
 
@@ -75,7 +76,7 @@ export type Plugin = CommandMeta &
     name: string
     aliases?: string[]
     /** Handles the command named after this plugin. The metadata above describes it. */
-    command?: CommandHandler
+    command?: (ctx: Parameters<CommandHandler>[0], plugin: PluginContext) => void | Promise<void>
     /** Escape hatch for what the methods above cannot express: extra commands, middleware, cleanup. */
     setup?(ctx: PluginContext): void | (() => void) | Promise<void | (() => void)>
     onUnload?(): void | Promise<void>

tests/client/command-guards.test.ts

@@ -171,3 +171,15 @@ describe('command-not-found', () => {
     expect(seen).not.toHaveBeenCalled()
   })
 })
+
+describe('ctx.client', () => {
+  it('hands the client to every command handler', async () => {
+    const client = connected()
+    let seen: unknown
+    client.command('who', (ctx) => {
+      seen = ctx.client
+    })
+    await send(client, '!who', false)
+    expect(seen).toBe(client)
+  })
+})

tests/plugin/handlers.test.ts

@@ -55,7 +55,16 @@ describe('plugin metadata becomes the command spec', () => {
       cooldown: 3,
       category: 'group',
     })
-    expect(h.commands[0]!.handler).toBe(run)
+  })
+
+  it('hands the plugin context to command() as a second argument', async () => {
+    const run = vi.fn()
+    const { host: h } = await load(definePlugin({ name: 'x', command: run }))
+    ;(h.commands[0]!.handler as (c: unknown) => void)({ command: 'x' })
+    expect(run).toHaveBeenCalledTimes(1)
+    const [commandCtx, pluginCtx] = run.mock.calls[0] as [unknown, { category?: string }]
+    expect(commandCtx).toEqual({ command: 'x' })
+    expect(pluginCtx.category).toBe('tool')
   })
 
   it('registers nothing when the plugin has no command handler', async () => {
@@ -83,11 +92,13 @@ describe('event methods', () => {
     ])
   })
 
-  it('passes the payload straight to the method', async () => {
+  it('passes the payload and the plugin context to the method', async () => {
     const message = vi.fn()
     const { host: h } = await load(definePlugin({ name: 'watcher', message }))
     h.listeners[0]!.handler({ text: 'halo' })
-    expect(message).toHaveBeenCalledWith({ text: 'halo' })
+    const [payload, pluginCtx] = message.mock.calls[0] as [unknown, { category?: string }]
+    expect(payload).toEqual({ text: 'halo' })
+    expect(pluginCtx.category).toBe('tool')
   })
 
   it('subscribes to nothing when no event method is present', async () => {