feat(commands): add object command specs with metadata, guards, and lifecycle events

Author: zeative

docs/content/commands.mdx

@@ -98,6 +98,124 @@ client.command('group kick', async (ctx) => {
 `/group kick 628123` resolves to `group kick` with `ctx.args === ['628123']`. The leading words
 that form the command name are consumed and never appear in `ctx.args`.
 
+### Describing a command
+
+Pass an object instead of a string when a command should carry a description or restrict who may
+run it. Both forms register the same way — the string form is just the short one.
+
+```typescript
+client.command(
+  {
+    name: 'kick',
+    aliases: ['remove'],
+    description: 'Remove a member from the group',
+    usage: '<@user>',
+    category: 'group',
+    group: true,
+    admin: true,
+    cooldown: 5,
+  },
+  async (ctx) => {
+    await ctx.reply(`Kicking ${ctx.args[0]}`)
+  },
+)
+```
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `string` | The command name. Spaces make it a subcommand, exactly as in the string form. |
+| `aliases` | `string[]` | Extra names that resolve to the same handler. |
+| `description` | `string` | One line explaining the command. Used to build a menu. |
+| `usage` | `string` | Argument hint shown beside the name, e.g. `<@user>`. |
+| `category` | `string` | Menu grouping. Inside a plugin this defaults to the folder name. |
+| `hidden` | `boolean` | Keeps the command callable but leaves it out of `client.commands()` listings. |
+| `metadata` | `Record<string, unknown>` | Anything else you want to attach. zaileys never reads it. |
+| `group` | `boolean` | Only runs inside a group. |
+| `private` | `boolean` | Only runs in a one-to-one chat. |
+| `admin` | `boolean` | Only runs for a group admin. Implies `group`. |
+| `cooldown` | `number` | Seconds the same sender must wait before reusing this command. |
+
+### Guards and `command-blocked`
+
+When a guard stops a command, zaileys **sends nothing to the chat** — it emits `command-blocked` so
+the wording, and the language, stay yours.
+
+```typescript
+client.on('command-blocked', async ({ reason, retryIn, ctx }) => {
+  const message = {
+    'group-only': 'Perintah ini hanya untuk grup.',
+    'private-only': 'Perintah ini hanya lewat chat pribadi.',
+    'admin-only': 'Khusus admin grup.',
+    cooldown: `Tunggu ${retryIn} detik lagi.`,
+  }[reason]
+  await ctx.reply(message)
+})
+```
+
+| `reason` | Raised when |
+| -------- | ----------- |
+| `group-only` | The command needs a group (`group: true`, or `admin: true`) but ran in a DM. |
+| `private-only` | The command needs a DM but ran in a group. |
+| `admin-only` | The sender is not an admin of the group, or the group could not be read. |
+| `cooldown` | The same sender reran the command too soon. `retryIn` holds the seconds left. |
+
+<Callout type="info">
+A blocked call does **not** start a cooldown, so someone who is refused for being a non-admin is not
+also made to wait before their next attempt.
+</Callout>
+
+### Catching errors
+
+A handler that throws would otherwise disappear into the log. Listen for `command-error` to tell
+the user something went wrong — and to report it wherever you collect errors.
+
+```typescript
+client.on('command-error', async ({ command, error, ctx }) => {
+  console.error(`command ${command} failed`, error)
+  await ctx.reply('Maaf, terjadi kesalahan. Coba lagi nanti.')
+})
+```
+
+<Callout type="info">
+Listening **takes ownership** of the failure: zaileys stops logging it itself, so the same error is
+not reported twice. Without a listener the old behaviour is unchanged — the error is logged and the
+bot keeps running.
+</Callout>
+
+### Unknown commands
+
+`command-not-found` fires when a message carries a prefix but matches no command. Use it for a
+"did you mean" reply, or leave it alone to stay silent.
+
+```typescript
+client.on('command-not-found', async ({ command, message }) => {
+  await message.reply(`Perintah *${command}* tidak ada. Ketik .menu untuk daftar perintah.`)
+})
+```
+
+<Callout type="warning">
+Replying to every unknown command makes a bot noisy in busy groups — any stray `.` message gets an
+answer. Consider replying only in private chats, or not at all.
+</Callout>
+
+### Listing commands for a menu
+
+`client.commands()` returns every registered command with its metadata — enough to build a help
+menu without maintaining a second list by hand.
+
+```typescript
+client.command({ name: 'menu', description: 'Show all commands' }, async (ctx) => {
+  const groups = new Map<string, string[]>()
+  for (const c of client.commands()) {
+    if (c.hidden) continue
+    const line = `.${c.name}${c.usage ? ` ${c.usage}` : ''} — ${c.description ?? ''}`
+    groups.set(c.category ?? 'other', [...(groups.get(c.category ?? 'other') ?? []), line])
+  }
+  const text = [...groups].map(([cat, lines]) => `*${cat}*\n${lines.join('\n')}`).join('\n\n')
+  await ctx.reply(text)
+})
+```
+
 ## The command context
 
 A `CommandContext` extends the full [message context](/events) — every field and method from a

docs/content/events.mdx

@@ -63,6 +63,16 @@ These fire as your session connects, authenticates, and (occasionally) drops. Ev
 | `auth-exhausted` | `{ sessionId, kind, attempts, max }` | The [`authGuard`](/configuration#authguard) budget ran out — too many QR / pairing regenerations. `kind` is `'qr' \| 'pairing'`. The client stops and will not auto-retry until you call `connect()` again. |
 | `error` | `{ sessionId, error }` | An internal connection error surfaced as an `Error`. |
 
+### Commands
+
+Emitted by the [command framework](/commands). All three are silent no-ops unless you listen.
+
+| Event | Payload | Fires when |
+| ----- | ------- | ---------- |
+| `command-blocked` | `{ command, reason, retryIn?, ctx }` | A guard stopped a command. `reason` is `'group-only' \| 'private-only' \| 'admin-only' \| 'cooldown'`. zaileys replies nothing — see [Guards](/commands#guards-and-command-blocked). |
+| `command-error` | `{ command, error, ctx }` | A command handler threw. Listening takes ownership, so zaileys stops logging it itself. |
+| `command-not-found` | `{ command, message }` | A prefixed message matched no registered command. |
+
 ### Inbound messages
 
 These deliver a rich [message context](#the-message-context) object — the same shape across every message type. The `media` accessor is populated only for media kinds.

docs/content/plugins.mdx

@@ -185,6 +185,22 @@ ctx.command('help|h|?', async (c) => {
 })
 ```
 
+Pass an object instead to describe the command or guard it. Inside a plugin the **`category`
+defaults to the plugin's folder**, so `plugins/group/kick.ts` needs no `category` field:
+
+```typescript
+// plugins/group/kick.ts
+ctx.command(
+  { name: 'kick', description: 'Remove a member', group: true, admin: true },
+  async (c) => { /* ... */ },
+)
+// registered with category: 'group'
+```
+
+`ctx.category` holds that folder name, or `undefined` for a plugin sitting directly in the plugins
+root. Setting `category` yourself always wins. See [Commands](/commands#describing-a-command) for
+every field.
+
 See [Commands](/commands) for the full command spec syntax, argument parsing, and `CommandContext`.
 
 ### `ctx.use(middleware)`
@@ -237,7 +253,8 @@ leaked listeners, commands, or middleware.
 | `client` | `Client` | The full `Client` instance. Call any client method directly from here. |
 | `logger` | `Logger \| undefined` | The client's logger instance. May be `undefined` if logging is disabled. |
 | `pluginDir` | `string` | Absolute path to the directory containing this plugin file. Useful for loading sibling assets (e.g. JSON config, image files). |
-| `command(spec, handler)` | `void` | Register a command. Tracked — auto-removed on unload. |
+| `category` | `string \| undefined` | The subfolder this plugin lives in, e.g. `'group'` for `plugins/group/kick.ts`. `undefined` for a plugin in the plugins root. Commands default their `category` to it. |
+| `command(spec, handler)` | `void` | Register a command. `spec` is a pipe string or a [command object](/commands#describing-a-command). Tracked — auto-removed on unload. |
 | `use(middleware)` | `void` | Register command middleware. Tracked — auto-removed on unload. |
 | `on(event, handler)` | `() => void` | Subscribe to a client event. Returns an unsubscribe fn. Tracked — auto-removed on unload. |
 | `once(event, handler)` | `() => void` | Like `on` but fires once. Returns an unsubscribe fn. Tracked — auto-removed on unload. |
@@ -378,7 +395,7 @@ import type {
 | Type | Shape |
 | ---- | ----- |
 | `Plugin` | `{ name: string; setup(ctx: PluginContext): void \| (() => void) \| Promise<void \| (() => void)>; onUnload?(): void \| Promise<void> }` |
-| `PluginContext` | `{ client, logger, pluginDir, command, use, on, once }` — see table above |
+| `PluginContext` | `{ client, logger, pluginDir, category, command, use, on, once }` — see table above |
 | `PluginsOptions` | `{ dir?, watch?, pattern?, ignore?, onError? }` — see table above |
 
 `definePlugin` is also exported and is the recommended way to author plugins:

src/client/client.ts

@@ -40,8 +40,10 @@ import {
   ZaileysCommandError,
   type CommandContext,
   type CommandHandler,
+  type CommandSpec,
   type DispatcherHandle,
   type Middleware,
+  type RegisteredCommand,
   type ResolvedCommand,
 } from '../command/index.js'
 import { applyGroupStatusWrap } from '../builder/status-wrap.js'
@@ -738,17 +740,22 @@ export class Client extends TypedEventEmitter<ClientEventMap> {
     await this.disconnect()
   }
 
-  command(spec: string, handler: CommandHandler): this {
+  command(spec: string | CommandSpec, handler: CommandHandler): this {
     ;(this.commandRegistry ??= new CommandRegistry()).register(spec, handler)
     this.attachCommandsIfReady()
     return this
   }
 
-  unregisterCommand(spec: string): this {
+  unregisterCommand(spec: string | CommandSpec): this {
     this.commandRegistry?.unregister(spec)
     return this
   }
 
+  /** Every registered command with its description and guards — build a help menu from this. */
+  commands(): RegisteredCommand[] {
+    return this.commandRegistry?.describe() ?? []
+  }
+
   use(middleware: Middleware): this {
     this.commandMiddleware.push(middleware)
     return this
@@ -777,9 +784,45 @@ export class Client extends TypedEventEmitter<ClientEventMap> {
         return () => this.off('text', wrapped)
       },
       buildContext: (resolved, msg) => this.buildCommandContext(resolved, msg),
+      isAdmin: (groupJid, senderJid) => this.isGroupAdmin(groupJid, senderJid),
+      onError: (error, ctx) => {
+        if (this.listenerCount('command-error') === 0) return false
+        this.emit('command-error', { command: ctx.command, error, ctx })
+        return true
+      },
+      onNotFound: (name, msg) => {
+        if (this.listenerCount('command-not-found') === 0) return
+        this.emit('command-not-found', { command: name, message: msg })
+      },
+      onBlocked: (block, ctx) => {
+        this.emit('command-blocked', {
+          command: ctx.command,
+          reason: block.reason,
+          ...(block.retryIn !== undefined ? { retryIn: block.retryIn } : {}),
+          ctx,
+        })
+      },
     })
   }
 
+  /** Admin lookup for the `admin` guard. Never throws — an unreachable group means "not an admin". */
+  private async isGroupAdmin(groupJid: string, senderJid: string): Promise<boolean> {
+    try {
+      const meta = await this.group.metadata(groupJid)
+      const bare = (jid: string): string => jid.split('@')[0]?.split(':')[0] ?? jid
+      const target = bare(senderJid)
+      return (meta.participants ?? []).some((p) => {
+        const entry = p as unknown as Record<string, unknown>
+        const ids = [p.id, entry['phoneNumber'], entry['jid']].filter(
+          (v): v is string => typeof v === 'string',
+        )
+        return ids.some((id) => bare(id) === target) && p.admin != null
+      })
+    } catch {
+      return false
+    }
+  }
+
   private buildCommandContext(resolved: ResolvedCommand, msg: MessageContext): CommandContext {
     let lastSentKey: WAMessageKey | undefined
     return {

src/client/types.ts

@@ -6,7 +6,8 @@ import type { OperationGuardOptions } from '../automation/operation-guard.js'
 import type { PresenceThrottleOptions } from '../automation/presence.js'
 import type { AuthGuardOptions } from '../connection/auth-guard.js'
 import type { DisconnectReasonDomain } from '../connection/disconnect-reason.js'
-import type { CitationConfig } from '../events/context.js'
+import type { CommandBlockedReason, CommandContext } from '../command/types.js'
+import type { CitationConfig, MessageContext } from '../events/context.js'
 import type { InboundEventMap } from '../events/types.js'
 import type { MessageStore } from '../store/types.js'
 import type { PluginsOptions } from '../plugin/types.js'
@@ -97,6 +98,18 @@ export type ConnectionEventMap = {
   reconnecting: { sessionId: string; attempt: number; delayMs: number; reason: DisconnectReasonDomain }
   'auth-exhausted': { sessionId: string; kind: ConnectionAuthType; attempts: number; max: number }
   error: { sessionId: string; error: Error }
+  /** A command matched but a guard stopped it. zaileys sends nothing — reply here if you want to. */
+  'command-blocked': {
+    command: string
+    reason: CommandBlockedReason
+    /** Seconds until the sender may retry. Only present when `reason` is `cooldown`. */
+    retryIn?: number
+    ctx: CommandContext
+  }
+  /** A command handler threw. Listening takes ownership: zaileys stops logging it as an error. */
+  'command-error': { command: string; error: unknown; ctx: CommandContext }
+  /** A prefixed message matched no command. Only emitted when something is listening. */
+  'command-not-found': { command: string; message: MessageContext }
   /** Cloud provider: delivery lifecycle of outbound messages (sent/delivered/read/failed). */
   'message-status': CloudStatusEvent
   /** Cloud provider: template review lifecycle (APPROVED/REJECTED/PAUSED...). */

src/command/dispatcher.ts

@@ -1,6 +1,7 @@
 import type { Logger } from '../client/types.js'
 import type { MessageContext } from '../events/context.js'
 import { ZaileysCommandError } from './errors.js'
+import { checkGuards, type GuardBlock } from './guards.js'
 import { runMiddleware } from './middleware.js'
 import { parseCommand } from './parser.js'
 import type { CommandRegistry } from './registry.js'
@@ -21,6 +22,11 @@ export interface DispatcherDeps {
   onText: (handler: (msg: MessageContext) => void) => () => void
   buildContext: (resolved: ResolvedCommand, msg: MessageContext) => CommandContext
   logger: Logger
+  isAdmin?: (groupJid: string, senderJid: string) => Promise<boolean>
+  onBlocked?: (block: GuardBlock, ctx: CommandContext) => void
+  /** Return `true` to claim the failure; otherwise the dispatcher logs it. */
+  onError?: (error: unknown, ctx: CommandContext) => boolean
+  onNotFound?: (name: string, msg: MessageContext) => void
 }
 
 export interface DispatcherHandle {
@@ -36,7 +42,10 @@ export function attachCommandDispatcher(deps: DispatcherDeps): DispatcherHandle
     const parsed = parseCommand(msg.text, deps.prefixes)
     if (!parsed.matched) return
     const resolution = deps.registry.resolve(parsed)
-    if (resolution === undefined) return
+    if (resolution === undefined) {
+      if (parsed.name !== undefined && parsed.name.length > 0) deps.onNotFound?.(parsed.name, msg)
+      return
+    }
 
     const resolved: ResolvedCommand = {
       command: resolution.def.name,
@@ -47,13 +56,25 @@ export function attachCommandDispatcher(deps: DispatcherDeps): DispatcherHandle
     }
     const ctx = deps.buildContext(resolved, msg)
 
-    void Promise.resolve(
-      runMiddleware(deps.middleware, ctx, () => resolution.def.handler(ctx)),
-    ).catch((err) => {
+    const run = async (): Promise<void> => {
+      const block = await checkGuards(resolution.def.meta, ctx, {
+        isAdmin: deps.isAdmin ?? (async () => false),
+        now: () => Date.now(),
+      })
+      if (block !== null) {
+        deps.onBlocked?.(block, ctx)
+        return
+      }
+      await runMiddleware(deps.middleware, ctx, () => resolution.def.handler(ctx))
+    }
+
+    void run().catch((err) => {
       const wrapped =
         err instanceof ZaileysCommandError
           ? err
           : new ZaileysCommandError('HANDLER_ERROR', 'command handler failed', { cause: err })
+      /** A listener takes ownership of the failure; without one it would vanish into the log. */
+      if (deps.onError?.(wrapped, ctx) === true) return
       deps.logger.error(wrapped, 'command dispatch failed')
     })
   }

src/command/guards.ts

@@ -3,5 +3,6 @@ export * from './errors.js'
 export { parseCommand } from './parser.js'
 export { CommandRegistry } from './registry.js'
 export { runMiddleware } from './middleware.js'
+export { checkGuards, resetCooldowns, type GuardBlock } from './guards.js'
 export { attachCommandDispatcher } from './dispatcher.js'
 export type { DispatcherDeps, DispatcherHandle, ResolvedCommand } from './dispatcher.js'