feat(plugins)!: rename the command handler to message

Author: zeative

docs/content/plugins.mdx

@@ -32,7 +32,7 @@ import { definePlugin } from 'zaileys'
 export default definePlugin({
   name: 'greet',
   description: 'Say hello',
-  command: async (ctx) => {
+  message: async (ctx) => {
     await ctx.reply('hi there 👋')
   },
 })
@@ -90,12 +90,12 @@ export default definePlugin({
   description: 'Say hello',
   cooldown: 3,
 
-  command: async (ctx) => {
+  message: async (ctx) => {
     await ctx.reply('hi there 👋')
   },
 
-  message: (m) => {
-    console.log('saw a message:', m.text)
+  image: (ctx) => {
+    console.log('someone sent a picture:', ctx.senderId)
   },
 })
 ```
@@ -142,23 +142,23 @@ import { definePlugin } from 'zaileys'
 export default definePlugin({
   name: 'my-plugin',
   description: 'What it does',
-  command: async (ctx) => { /* handles !my-plugin */ },
-  message: (m) => { /* every inbound message */ },
+  message: async (ctx) => { /* handles !my-plugin */ },
+  image: (ctx) => { /* every inbound image */ },
 })
 ```
 
 ### The `Plugin` shape
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `name` | `string` | Required. Identifies the plugin **and** names the command `command` handles. |
-| `command` | `(ctx, plugin) => void \| Promise<void>` | Handles the command named after this plugin. Omit if the plugin only listens to events. |
+| `name` | `string` | Required. Identifies the plugin **and** names the command it handles. `name: 'sticker'` answers `!sticker`. |
+| `message` | `(ctx, plugin) => void \| Promise<void>` | Handles that command. 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. |
 
 Beside those, a plugin carries **every field a command spec carries** — `aliases`, `description`,
 `usage`, `category`, `hidden`, `metadata`, and the guards `group`, `private`, `admin`, `cooldown`.
-They describe the command that `command` handles. See
+They describe the command that `message` handles. See
 [Commands](/commands#describing-a-command) for the full table.
 
 ```typescript
@@ -170,7 +170,7 @@ export default definePlugin({
   group: true,
   admin: true,
   cooldown: 3,
-  command: async (ctx) => { /* ... */ },
+  message: async (ctx) => { /* ... */ },
 })
 ```
 
@@ -180,32 +180,37 @@ without saying so.
 </Callout>
 
 <Callout type="warning">
-Guards apply to **`command` only**. An event method like `message` receives the raw stream — check
-`m.isGroup` yourself if you need to narrow it. This keeps `admin` from triggering a group-metadata
+Guards apply to **`message` only**. An event method like `image` receives the raw stream — check
+`ctx.isGroup` yourself if you need to narrow it. This keeps `admin` from triggering a group-metadata
 lookup on every message that passes through your bot.
 </Callout>
 
 ## Event methods
 
-Every inbound event has a matching optional method. Hyphenated event names become camelCase, so
-`poll-vote` is `pollVote`.
+Beside `message`, every inbound event has a matching optional method. Hyphenated event names become
+camelCase, so `poll-vote` is `pollVote`.
 
 ```typescript
 export default definePlugin({
   name: 'watcher',
-  message: (m) => console.log(m.senderId, m.text),
-  image: async (m) => { await m.reply('nice picture') },
-  pollVote: async (v) => console.log(await v.options()),
-  groupJoin: (e) => console.log('joined:', e.participants.length),
-  callIncoming: (c) => console.log('call from', c.from),
+  text: (ctx) => console.log(ctx.senderId, ctx.text),
+  image: async (ctx) => { await ctx.reply('nice picture') },
+  pollVote: async (vote) => console.log(await vote.options()),
+  groupJoin: (event) => console.log('joined:', event.participants.length),
+  callIncoming: (call) => console.log('call from', call.from),
 })
 ```
 
-Available: `message` · `text` · `image` · `video` · `audio` · `document` · `sticker` · `reaction` ·
+Available: `text` · `image` · `video` · `audio` · `document` · `sticker` · `reaction` ·
 `edit` · `delete` · `pollVote` · `buttonClick` · `listSelect` · `mention` · `mentionAll` ·
 `groupUpdate` · `groupJoin` · `groupLeave` · `memberTag` · `callIncoming` · `callEnded` ·
 `historySync` · `limited` · `presence` · `newsletter`.
 
+<Callout type="info">
+There is no `message` event method — on a plugin that name is the **command handler**. To watch every
+inbound message regardless of type, use `setup(ctx)` and `ctx.on('message', …)`.
+</Callout>
+
 Each is typed from [the event map](/events), so the payload needs no annotation. Listeners are
 removed automatically when the plugin unloads.
 
@@ -214,7 +219,7 @@ removed automatically when the plugin unloads.
 A command handler gets the client straight off its context:
 
 ```typescript
-command: async (ctx) => {
+message: async (ctx) => {
   await ctx.client.group.removeMember(ctx.roomId!, ctx.mentions)
 },
 ```
@@ -223,8 +228,8 @@ Event payloads are plain message contexts and carry no client, so every handler
 **plugin context** as a second argument:
 
 ```typescript
-message: async (msg, plugin) => {
-  if (msg.text === 'ping') await plugin.client.send(msg.roomId!).text('pong')
+image: async (ctx, plugin) => {
+  await plugin.client.send(ctx.roomId!).text('gambar diterima')
 },
 ```
 

src/plugin/registry.ts

@@ -53,9 +53,9 @@ const specOf = (plugin: Plugin): CommandSpec => {
   return spec
 }
 
-/** Turns the plugin's `command()` and per-event methods into real registrations. */
+/** Turns the plugin's `message` handler and per-event methods into real registrations. */
 const wireHandlers = (plugin: Plugin, ctx: PluginContext): void => {
-  const run = plugin.command
+  const run = plugin.message
   if (typeof run === 'function') {
     ctx.command(specOf(plugin), (commandCtx) => run(commandCtx, ctx))
   }

src/plugin/types.ts

@@ -32,17 +32,19 @@ type Camel<S extends string> = S extends `${infer Head}-${infer Tail}`
   ? `${Head}${Capitalize<Camel<Tail>>}`
   : S
 
-/** One optional method per inbound event, derived so a new event is available here automatically. */
+/**
+ * One optional method per inbound event, derived so a new event is available here automatically.
+ * `message` is excluded — on a plugin that name belongs to the command handler.
+ */
 export type PluginEventHandlers = {
-  [E in keyof InboundEventMap as Camel<E>]?: (
+  [E in Exclude<keyof InboundEventMap, 'message'> as Camel<E>]?: (
     payload: InboundEventMap[E],
     ctx: PluginContext,
   ) => void | Promise<void>
 }
 
 /** Every inbound event name, in the order their methods are wired up. */
 export const INBOUND_EVENTS = [
-  'message',
   'text',
   'image',
   'video',
@@ -67,7 +69,7 @@ export const INBOUND_EVENTS = [
   'limited',
   'presence',
   'newsletter',
-] as const satisfies ReadonlyArray<keyof InboundEventMap>
+] as const satisfies ReadonlyArray<Exclude<keyof InboundEventMap, 'message'>>
 
 export type Plugin = CommandMeta &
   CommandGuards &
@@ -76,7 +78,7 @@ export type Plugin = CommandMeta &
     name: string
     aliases?: string[]
     /** Handles the command named after this plugin. The metadata above describes it. */
-    command?: (ctx: Parameters<CommandHandler>[0], plugin: PluginContext) => void | Promise<void>
+    message?: (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/plugin/end-to-end.test.ts

@@ -53,7 +53,7 @@ describe('plugin file to dispatched command', () => {
       `export default {
          name: 'ping',
          description: 'Cek bot',
-         command: async (ctx) => { globalThis.__hit = ctx.command },
+         message: async (ctx) => { globalThis.__hit = ctx.command },
        }`,
     )
     await boot()
@@ -70,11 +70,11 @@ describe('plugin file to dispatched command', () => {
   it('wires a declarative event method', async () => {
     await fs.writeFile(
       path.join(dir, 'info', 'watch.js'),
-      `export default { name: 'watch', message: (m) => { globalThis.__seen = m.text } }`,
+      `export default { name: 'watch', text: (ctx) => { globalThis.__seen = ctx.text } }`,
     )
     await boot()
 
-    client.emit('message', msg('halo'))
+    client.emit('text', msg('halo'))
     expect((globalThis as Record<string, unknown>)['__seen']).toBe('halo')
   })
 

tests/plugin/handlers.test.ts

@@ -28,8 +28,8 @@ const load = async (plugin: ReturnType<typeof definePlugin>, file = '/bot/plugin
   return { host: h, reg }
 }
 
-describe('plugin metadata becomes the command spec', () => {
-  it('registers command() using the plugin name and metadata, with no repetition', async () => {
+describe('the plugin is the command', () => {
+  it('registers the command from the plugin name and metadata, with no repetition', async () => {
     const run = vi.fn()
     const { host: h } = await load(
       definePlugin({
@@ -40,7 +40,7 @@ describe('plugin metadata becomes the command spec', () => {
         group: true,
         admin: true,
         cooldown: 3,
-        command: run,
+        message: run,
       }),
       '/bot/plugins/group/kick.ts',
     )
@@ -57,18 +57,18 @@ describe('plugin metadata becomes the command spec', () => {
     })
   })
 
-  it('hands the plugin context to command() as a second argument', async () => {
+  it('hands the plugin context to the handler as a second argument', async () => {
     const run = vi.fn()
-    const { host: h } = await load(definePlugin({ name: 'x', command: run }))
+    const { host: h } = await load(definePlugin({ name: 'x', message: 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 () => {
-    const { host: h } = await load(definePlugin({ name: 'quiet', description: 'no command' }))
+  it('registers no command when the plugin has no message handler', async () => {
+    const { host: h } = await load(definePlugin({ name: 'quiet', description: 'listener only' }))
     expect(h.commands).toHaveLength(0)
   })
 })
@@ -78,7 +78,7 @@ describe('event methods', () => {
     const { host: h } = await load(
       definePlugin({
         name: 'watcher',
-        message: vi.fn(),
+        text: vi.fn(),
         image: vi.fn(),
         pollVote: vi.fn(),
         callIncoming: vi.fn(),
@@ -87,23 +87,24 @@ describe('event methods', () => {
     expect(h.listeners.map((l) => l.event).sort()).toEqual([
       'call-incoming',
       'image',
-      'message',
       'poll-vote',
+      'text',
     ])
   })
 
   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 }))
+    const text = vi.fn()
+    const { host: h } = await load(definePlugin({ name: 'watcher', text }))
     h.listeners[0]!.handler({ text: 'halo' })
-    const [payload, pluginCtx] = message.mock.calls[0] as [unknown, { category?: string }]
+    const [payload, pluginCtx] = text.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 () => {
-    const { host: h } = await load(definePlugin({ name: 'bare', command: vi.fn() }))
+  it('never wires `message` as an event — that name is the command handler', async () => {
+    const { host: h } = await load(definePlugin({ name: 'bare', message: vi.fn() }))
     expect(h.listeners).toHaveLength(0)
+    expect(h.commands).toHaveLength(1)
   })
 
   it('does not mistake plain metadata for a handler', async () => {
@@ -114,23 +115,21 @@ describe('event methods', () => {
   })
 
   it('combines a command with event methods in one plugin', async () => {
-    const { host: h } = await load(
-      definePlugin({ name: 'both', command: vi.fn(), message: vi.fn() }),
-    )
+    const { host: h } = await load(definePlugin({ name: 'both', message: vi.fn(), image: vi.fn() }))
     expect(h.commands).toHaveLength(1)
     expect(h.listeners).toHaveLength(1)
   })
 })
 
 describe('setup stays available', () => {
   it('is optional now', async () => {
-    const { reg } = await load(definePlugin({ name: 'nosetup', command: vi.fn() }))
+    const { reg } = await load(definePlugin({ name: 'nosetup', message: vi.fn() }))
     expect(reg.list()).toEqual(['nosetup'])
   })
 
   it('still runs, alongside the declarative handlers', async () => {
     const setup = vi.fn()
-    const { host: h } = await load(definePlugin({ name: 'mixed', command: vi.fn(), setup }))
+    const { host: h } = await load(definePlugin({ name: 'mixed', message: vi.fn(), setup }))
     expect(setup).toHaveBeenCalledTimes(1)
     expect(h.commands).toHaveLength(1)
   })