zaileys 4.8.9 → 4.9.0

package/dist/client/client.d.ts

@@ -1,7 +1,7 @@
 import { type WAMessageKey } from 'baileys';
 import { EditBuilder, MessageBuilder, type DeleteOptions, type PinOptions } from '../builder/index.js';
 import { CommunityModule, GroupModule, BusinessModule, ChatModule, ContactModule, NewsletterModule, PrivacyModule, ProfileModule } from '../domain/index.js';
-import { type CommandHandler, type Middleware } from '../command/index.js';
+import { type CommandHandler, type CommandSpec, type Middleware, type RegisteredCommand } from '../command/index.js';
 import { PresenceModule, type BroadcastOptions, type BroadcastResult, type ScheduleHandle } from '../automation/index.js';
 import type { CallPayload, MediaDownloadResult } from '../events/types.js';
 import type { AuthStoreBundle } from '../auth/types.js';
@@ -119,11 +119,15 @@ export declare class Client extends TypedEventEmitter<ClientEventMap> {
     private disconnectCloud;
     disconnect(): Promise<void>;
     logout(): Promise<void>;
-    command(spec: string, handler: CommandHandler): this;
-    unregisterCommand(spec: string): this;
+    command(spec: string | CommandSpec, handler: CommandHandler): this;
+    unregisterCommand(spec: string | CommandSpec): this;
+    /** Every registered command with its description and guards — build a help menu from this. */
+    commands(): RegisteredCommand[];
     use(middleware: Middleware): this;
     unuse(middleware: Middleware): this;
     private attachCommandsIfReady;
+    /** Admin lookup for the `admin` guard. Never throws — an unreachable group means "not an admin". */
+    private isGroupAdmin;
     private buildCommandContext;
     private detachCommands;
     send(to: string): MessageBuilder<'init'>;

package/dist/client/types.d.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';
@@ -109,6 +110,25 @@ export type ConnectionEventMap = {
         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...). */

package/dist/command/dispatcher.d.ts

@@ -1,5 +1,6 @@
 import type { Logger } from '../client/types.js';
 import type { MessageContext } from '../events/context.js';
+import { type GuardBlock } from './guards.js';
 import type { CommandRegistry } from './registry.js';
 import type { CommandContext, Middleware } from './types.js';
 export interface ResolvedCommand {
@@ -16,6 +17,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 {
     detach(): void;

package/dist/command/guards.d.ts

@@ -0,0 +1,17 @@
+import type { CommandBlockedReason, CommandContext, CommandGuards } from './types.js';
+export interface GuardBlock {
+    reason: CommandBlockedReason;
+    /** Seconds left before the sender may retry. Only set for `cooldown`. */
+    retryIn?: number;
+}
+export interface GuardDeps {
+    /** Resolves whether the sender is an admin of the group the command ran in. */
+    isAdmin: (groupJid: string, senderJid: string) => Promise<boolean>;
+    now: () => number;
+}
+export declare const resetCooldowns: () => void;
+/**
+ * Checks a command's guards. Returns the block, or `null` when the handler may run. Nothing is sent
+ * to the chat here — the caller emits `command-blocked` so the wording stays the bot author's.
+ */
+export declare const checkGuards: (guards: CommandGuards, ctx: CommandContext, deps: GuardDeps) => Promise<GuardBlock | null>;

package/dist/command/index.d.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';

package/dist/command/registry.d.ts

@@ -1,13 +1,15 @@
-import type { CommandDefinition, CommandHandler, ParsedArgs } from './types.js';
+import type { CommandDefinition, CommandHandler, CommandSpec, ParsedArgs, RegisteredCommand } from './types.js';
 export declare class CommandRegistry {
     private readonly paths;
     private readonly defs;
     private maxDepth;
-    register(spec: string, handler: CommandHandler): void;
+    register(spec: string | CommandSpec, handler: CommandHandler): void;
     resolve(parsed: ParsedArgs): {
         def: CommandDefinition;
         args: string[];
     } | undefined;
-    unregister(spec: string): void;
+    unregister(spec: string | CommandSpec): void;
     list(): CommandDefinition[];
+    /** The registered commands without their handlers — what a help menu is built from. */
+    describe(): RegisteredCommand[];
 }

package/dist/command/types.d.ts

@@ -22,9 +22,43 @@ export interface CommandContext extends MessageContext {
 }
 export type CommandHandler = (ctx: CommandContext) => Promise<void> | void;
 export type Middleware = (ctx: CommandContext, next: () => Promise<void>) => Promise<void> | void;
+/** Descriptive fields a command carries so a help menu can be generated instead of hand-written. */
+export interface CommandMeta {
+    description?: string;
+    /** Argument hint shown next to the name, e.g. `<@user>`. */
+    usage?: string;
+    /** Menu grouping. Plugins default it to the folder the file sits in. */
+    category?: string;
+    /** Keeps the command callable but leaves it out of listings. */
+    hidden?: boolean;
+    /** Anything else you want to hang off the command; zaileys never reads it. */
+    metadata?: Record<string, unknown>;
+}
+/** Conditions checked before a handler runs. A blocked command emits `command-blocked` instead. */
+export interface CommandGuards {
+    /** Only runs inside a group. */
+    group?: boolean;
+    /** Only runs in a one-to-one chat. */
+    private?: boolean;
+    /** Only runs for a group admin. Implies `group`. */
+    admin?: boolean;
+    /** Seconds the same sender must wait before reusing this command. */
+    cooldown?: number;
+}
+export interface CommandSpec extends CommandMeta, CommandGuards {
+    name: string;
+    aliases?: string[];
+}
+/** A command as registered, with its guards and metadata resolved. */
+export interface RegisteredCommand extends CommandMeta, CommandGuards {
+    name: string;
+    aliases: string[];
+}
+export type CommandBlockedReason = 'group-only' | 'private-only' | 'admin-only' | 'cooldown';
 export interface CommandDefinition {
     name: string;
     aliases: string[];
     parts: string[];
     handler: CommandHandler;
+    meta: CommandMeta & CommandGuards;
 }